io.github.ivanlai/primer-mcp

Close a spike by recording its findings — the answer to the question it was investigating and any recommendations. Works from any status.

Mark a task as completed with notes on what was done. The notes parameter is a terse one-liner for the frontmatter field; write a fuller summary (approach, key changes, decisions) into the ## Completion Notes body section of the ticket separately. Ideally call start_task first, but this works from any status. After this, call verify_task with evidence to finalise.

Create a Spike under a story — a timeboxed investigation to answer a specific question before committing to an implementation approach. The parent story must already exist. When done, call complete_spike with your findings.

Create a Story under an epic — a deliverable with acceptance criteria. The epic must exist — if one hasn't been created yet, call plan_epic first. The user will have described their goals; use that to create the epic, asking for clarification if needed. If no ADR has been recorded, the response will suggest capturing decisions first, but the story is still created. Pass adr_ids to link the story to the architectural decisions that govern it. Each ADR must exist and belong to the same epic. After creating stories, present the plan to the user and wait for their agreement before creating tasks or starting work.

Create a Task under a story — a concrete unit of implementation work with a testable outcome. The parent story must already exist. After breaking a story into tasks, present the task list to the user before starting work — don't create tasks and immediately begin implementing. For small bug fixes (1-2 tasks), prefer adding a task under the standing bug-fix story rather than creating a new story. Suggest a dedicated story only when the fix spans 3+ tasks.

Delete a ticket. Non-todo tickets are deleted with a warning. Children are reported but not deleted — call delete_ticket on each to cascade. After all deletions, call sweep_blocked_by to clean up dangling references. Recoverable from git history.

Generate a self-contained HTML file visualising the project as an interactive graph. Opens in any browser with no external requests. Nodes are coloured by type and status; edges show both hierarchy (epic -> story -> task) and dependencies (blocked_by). Click a node to see its details. On-demand — call when you want a snapshot.

Read one ticket by ID, with its full body. Also reports which tickets it blocks — that direction is not stored on the ticket itself, so this is the only way to see it.

Initialise this project for primer-mcp: creates the primer/ ticket store and adds the workflow section to CLAUDE.md and AGENTS.md, creating them if needed. Non-destructive and idempotent. Call this once per project, before any other tool. Optionally pass jira_project_key if tickets may later be exported to Jira.

List what can be acted on right now, with epic context. Returns the epic's goals, story coverage, and a table of actionable items. Always show the full table to the user first, then add your recommendation below it. The table is the primary output — the user needs to see all options to make their own call. After showing the table, recommend what to do next: 1. Check whether the stories cover the epic's goals. If goals are uncovered, recommend more planning (create_story) before execution. 2. Urgent items (unverified or in-progress tasks) should usually be finished before starting new work. 3. For the remaining items, read the tickets that look relevant (get_ticket) and recommend based on impact — what unblocks the most work, what aligns with current momentum, why now. 4. If several items are genuinely equal, say so and explain why.

List tickets one per line, newest work last. Filter by type (epic, adr, story, task, spike), status, or parent_id (show only children of that ticket). Use this to find an ID before calling another tool.

Create an Epic — the top-level container for a body of work. Start here: state why the work matters, its goals, and how you'll know it's done. Consider recording decisions (record_adr) before creating stories — it captures reasoning that gets lost once implementation starts.

Record an Architecture Decision Record under an epic: the context forcing a choice, the decision, alternatives rejected (with reasons), and consequences accepted. Recording decisions before creating stories is recommended — it captures reasoning that gets lost once implementation starts.

Transition a task to in-progress — call this when you begin working on a task. Works from any status; you'll get a note if the transition is unusual. After finishing, call complete_task.

Remove blocked_by references that point to tickets that no longer exist. Call once after finishing a batch of delete_ticket calls.

Amend a ticket after creation; anything left out is left alone. status — which values each type accepts: - Epic, story, spike: todo, in-progress, blocked, done. - Task: todo, in-progress, blocked. Finish with complete_task then verify_task. - ADR: none — it records a decision and has no lifecycle. blocked_by replaces the dependency list. It is refused if a referenced ticket does not exist or the edge would create a cycle. To say "A blocks B", set blocked_by on B. body_sections replaces whole markdown sections by heading.

Verify a task with evidence that the work holds (e.g. "218 passed, mypy clean"). Pass the short commit hash in the commit parameter so it is labelled consistently. Ideally call complete_task first to capture notes, but this works from any status. Sets the task to verified.