# IDEA.md – an issue tracker of your own for you and Claude This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on Relay, an issue tracker with a web interface and an MCP server that replaced Linear and was built with Claude Code. ## 1. What to build An issue tracker where a human and Claude share the same board: the human in the browser, Claude through an MCP server. The issues live on your own server. In Relay: - **issues** with identifiers that never change (`AND-55`), a status with a type, labels, priority, a Markdown description (with clickable checkboxes), relations (blocked by, related, duplicate) and status history - **board and list** per project, with filters - **comments** with threads, reactions, quotes from the description and screenshots - **whose turn**: worked out from the label's owner and "waiting for an answer" - **an MCP server** with the same tool names as the tool you're leaving, and `get_board` for the start of a session - **webhooks** that can wake a Claude session - people and agents with keys of their own, shared projects, invitations, forgotten password - a home page, calendar and timeline, Swedish and English, light and dark mode - **import** from the old tool, with the images ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **The web**: React 18, Vite and TypeScript. - **The server**: PHP 8.3 with no framework, mysqli and MariaDB. - **Important: a tool registry** where every capability is defined once with JSON Schema and a handler. Both the MCP server and the web interface's API go through the same registry, so a new capability reaches both. - **Important: all domain logic in one place** – lookups, response shapes, every change – and all access control in another: every read of issues, comments and attachments goes through the same check. - **Identifiers from one place**: the project's own counter if it has a prefix, the team's otherwise. Two counters must never share a prefix. - **Times in UTC** with milliseconds. - **Attachments outside the docroot**, the type read from the file's content, and a file written during a transaction removed if the transaction rolls back. ## 3. Decisions that turned out to matter **Measure what's actually used before building anything.** Go through the session logs' calls to the old tool's MCP server, and build that. The rest becomes issues in a backlog. **Keep the tool names.** With the same names, parameters and field names, the way of working and every instruction keep working unchanged. Wrong parameters are refused with the name of what's wrong, rather than ignored. **Whose turn is worked out, not set.** Every label has an owner (agent, human, nobody) and a description that is a working rule. "Waiting for an answer" clears when a human comments. **One call at the start of a session.** `get_board` gives the open issues by status, the labels' rules, changes and new comments since the agent last read. **One issue at a time per project for agents**, checked in the same transaction as the move, with an error that says which issue is in progress. **Write as the agent, on behalf of the human.** An agent has its own name and key, and everything it writes shows who it works for. **A way of working in one file**, `RELAY.md`, copied unchanged into every project and pointed to from the project's instructions. The tool leaves projects that haven't opted in alone. **`idempotency_key`** on anything that creates something, so a retry gives the same issue. **Calendar and timeline are counted from the history.** An activity is a change to an issue or a comment, by a person or an agent. No dates are filled in by hand, so the views show what was actually done. Count the days in the browser's time zone, group in quarter hours in UTC before moving them to the right day (so time zones with half hours and summer time come out right), and let the timeline use the same count as the calendar. ## 4. Pitfalls - **Two sessions take one issue each in the same project.** Lock in the database, not in the receiver. - **The agent wakes itself.** Let webhooks by default send only humans' changes. - **A slow webhook receiver holds up the page.** Send after the answer, and release the session first, or the page's next request waits. - **Retries pending when a webhook is switched off** should be dropped, so nothing old is sent when it's switched on again. - **A lost connection** must not replace the page with an error. Save drafts in the browser and show a line that the connection is gone. - **"Remember me" with a rotating secret**: a page load sends several requests at once with the same cookie. Give the previous secret a short grace period. - **Affected rows** must be read from the statement, not the connection, once the statement has been freed. - **Images held by the old tool** must be fetched over during the import, or the descriptions point at something that will disappear. - **A renamed project** must still be found by its old name and old address. ## 5. Requirements and measurements - Identifiers never change, not even when an issue moves project. - An agent can't have two issues in progress in the same project. - No read of issues, comments or attachments bypasses the access check. ## 6. How it's verified - Type checking and lint in the build. - An end-to-end test of the API and the MCP server against a throwaway database that a script starts and tears down, never against the real one. - Pure functions (such as whose turn) tested without a browser. - Webhooks in production: comment on an issue and see a session start. ## 7. Way of working - **Start with a specification** drawn from what you've actually used. - **Move over early**, and then run the tool from itself: every new feature is an issue. - **Verification as issues of their own** for what can only be tried in production. ## 8. The prompt > Build an issue tracker for me and Claude: issues with status, labels, relations and comments, a board in [React] and an MCP server with the same tool names as [Linear]. [PHP with no framework and MariaDB]. Labels have an owner so it shows whose turn it is, and a webhook can wake a Claude session. > > Read all of IDEA.md below first. > > Work like this: > 1. Go through my session logs and write a specification of what I actually use. > 2. Build it, with a tool registry that both MCP and the web go through. > 3. Test the API and the MCP server against a throwaway database. > > [paste IDEA.md here]