implement-spec

If your agent can't run subagents in separate git worktrees, stop here: tell the user this skill needs both, and suggest running implement on one ticket at a time instead.

You have been provided a spec. This spec should have tickets associated with it, describing how to implement the spec.

The issue tracker should have been provided to you. If not, tell the user to run /setup-sdlc.

The goal is the entire spec implemented as a Stack: one pull request per ticket, chained first to last, each pushed and opened as soon as its own gate passes. The user merges them; you never do.

The tickets are not a list of steps. They are a task graph with blocking relationships between them, and the spec's Implementation flow orders them into Groups. Tickets in a Group are built in parallel from the same base, then chained in ticket order.

Communication to and from subagents should be sparse. Communicate primarily through context pointers: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers.

Implementer subagents should be run in the background where possible for maximum concurrency.

Steps

1. Load the worktrees skill and resolve the worktree for this work before writing anything. The Spec's Feature branch link leads to its Feature worktree, the root of the Stack. Hold its lock until the last step. The feature slug is the feature branch's Slug (worktree.sh slug <feature branch>); it prefixes every branch below, so two features' branches never share a Slug.
2. Read the spec, its Implementation flow and the tickets to understand the task graph. If commits have landed in their area since they were written, suggest running refresh-spec on the spec first. If the spec has no Implementation flow, tell the user to run to-tickets on it and stop. Each ticket's Stacks on: line names the branch its pull request targets. The first one targets the feature branch, or the default branch when the feature branch holds no grilling docs and so has no pull request of its own.
3. (optional) Use an exploration subagent to conduct any exploration required by the tickets - relevant codebase files or external documentation. Ensure the exploration subagent can save files - it should save its markdown notes in a directory outside the repo, accessible by all future subagents. This lets implementer subagents focus on implementation rather than exploration.

4. Once, before Group 1, push the feature branch, so implement finds it on origin, and open pull request 0 when it holds grilling docs, meaning commits beyond the default branch. Load the pr skill to open it against the default branch as its "Opening the PR" section says, as complete work, with the stack table and no closing line. With no such commits there is no pull request 0, and the first Ticket's pull request targets the default branch.

   Then work through the Groups in flow order. A Group's base is the feature branch for the first Group and the last ticket branch of the previous Group after that. Build the Group:

   • Use implementer subagents to implement each of its tickets in parallel, each in its own Implementer worktree on branch <feature-slug>-t<ticket>, based on the Group's base. Create it with the worktrees skill's Create rules (worktree.sh create <feature-slug>-t<ticket> <base>) and hand the subagent its path, or use your agent's own subagent worktree isolation when it places worktrees under the Main checkout's .claude/worktrees/.
   • Each implementer subagent takes its own lock on its worktree with its own description, as the worktrees skill's Resolve step 4 says; confirms its worktree is on <feature-slug>-t<ticket> and based on the Group's base before starting, and runs git checkout -B <feature-slug>-t<ticket> <base> if not (an isolation worktree starts on a branch named after its folder); loads the tdd skill to build the ticket, and the code-comments skill for every comment it writes, plus the ui-design skill when the ticket builds UI, following the spec's UI Design section; and commits and releases its lock before reporting done.
   • With a stack slot, after its full test suite passes, the implementer loads the dev-stack skill to verify the ticket at its worktree's Dev URL, then runs scripts/dev-stack destroy before reporting done, naming in its report the real-provider items the skill's Report step handed back; without one, it starts no stack, even where a loaded skill such as ui-design asks for one, verifies through its tests and names the missing slot in its report.

   When the repo has a Dev stack contract (an executable scripts/dev-stack), hand out stack slots with the subagents. The free slots are the cap in docs/agents/dev-stack.md (default 4) minus the stacks portless list shows running, counted the way the dev-stack skill's Cap step counts them, minus one held back for the stack at the tip. Give one slot to each implementer whose ticket is reachable over HTTP or UI, while free slots remain, and take it back when that implementer reports done. The rest get none. Without a contract, implementers get no slots and no stack instructions.

5. Chain the Group once every implementer has reported done. In ticket order, a merger subagent merges each branch's predecessor into it: a Group's first ticket needs no merge, since its branch is built on the base, and every later ticket's predecessor is the ticket before it in the Group. The merger works in its own worktree on branch <feature-slug>-m<ticket>, created from the ticket branch and locked the same way. It merges the predecessor there, resolves any conflicts (shared files such as changelogs and lockfiles included), runs the full suite and typechecking again, then fast-forwards the ticket branch to it (git -C <ticket worktree> merge --ff-only <feature-slug>-m<ticket>) and releases its lock. When the ticket's branch is already pushed, push the forward-merged branch with an ordinary push after the suite passes. Run mergers one at a time, so each branch contains the one before it when its merger starts.
6. Gate each pull request of the Group on its own diff against its predecessor's branch:
   • Load the review-changes skill and run it with the ticket as the spec.
   • Fix blocking findings in that ticket's branch, in an implementer subagent on branch <feature-slug>-t<ticket>-fix<round> created from it, then fast-forward the ticket's own branch to the fix branch before merging forward through the later branches of the Group with the merger step, rerunning the suite and typechecking on each. Push with ordinary pushes only, never a force-push. Review again; repeat while the verdict is blocking and each round fixes something.
   • When the ticket's suite and typechecking are green, its last verdict is pass and no decision waits on the user, push its branch and load the pr skill to open the pull request as its "Opening the PR" section says: as complete work, against the predecessor's branch, with the stack table, closing only this ticket. Do this as soon as its own gate passes, without waiting for the rest of the Group, but never before its base branch is on origin: the pull requests of a Group open in ticket order, so a ticket whose gate passes early waits until its predecessor's pull request is open. When the predecessor fails its gate, the pull requests of the tickets after it do not open, and the stop rule below applies. Rerun CI when a forward merge changes a branch that is already pushed. After each pull request opens, run the pr skill again on the ones already open, so their pending cells hold real links, and once more when the Stack is complete, including after the top pull request of step 9 opens.
   • A Group is done only when every pull request in it is open, green and reviewed. Then start the next Group at the Group build in step 4 (pull request 0 happens once, before Group 1). A Group that cannot finish clean after the retry rounds stops the run: later Groups do not start, open pull requests stay, nothing further is pushed, and the Run report names the stopping point and the failing check.
7. Once all Groups are done, review the Stack as a whole. Load the review-changes skill and run it on the Stack's tip with the spec as the spec, one run for the whole Stack. Fix all issues it raises in a single implementer subagent on branch <feature-slug>-review, based on the tip, then review again; repeat while the verdict is blocking and each round fixes something. Earlier pull requests stay as reviewed: fixes never go back into them.
8. When the repo has a Dev stack contract, run e2e once, on the Stack's tip, never per pull request or per Group. Once the review fixes are merged, load the dev-stack skill in the worktree of the tip's branch (<feature-slug>-review when step 7 committed fixes, otherwise the last ticket's), bring up its stack, and run the doc's e2e command in full with E2E_BASE_URL=<Dev URL> (or the skill's next strongest check when the repo has no e2e suite). Fix failures the way step 7 fixes review findings, then run it again. Leave that stack running, and keep the real-provider items the skill's Report step hands back for the Run report.
9. When steps 7 and 8 changed the code, gate <feature-slug>-review like every other pull request: suite and typechecking green, review-changes verdict pass on its diff against the tip's branch with the spec as the spec. Then push it and open it through the pr skill as the extra top pull request, against the tip's branch, closing the spec as well as its own fixes. When <feature-slug>-review cannot pass its gate after the retry rounds, push nothing from it, stop, and report it in the Run report as the stopping point. When they changed nothing, there is no top pull request and the last ticket's pull request is the tip: run the pr skill on it again to add the spec to its closing lines, so the spec still closes when the Stack is merged. When the issue tracker doesn't live on the code host (a local tracker), or the pr skill's host check opened no PR, resolve each ticket and the spec the way the issue tracker closes work.
10. After a stop, as step 6 says, skip steps 7 to 9 and close the run at steps 11 and 12.
11. Finish every implementer and merger worktree through the worktrees skill's Finish rules: pushed branches finish with worktree.sh finish <path>, with --pr-open where the script cannot see the branch on origin. A merger branch <feature-slug>-m<ticket> is never pushed: once its work is merged into the ticket branch, finish it with --merged-into <ticket branch>. A fix branch <feature-slug>-t<ticket>-fix<round> was fast-forwarded into its ticket branch and never pushed: finish it with --merged-into <ticket branch>. A <feature-slug>-review worktree whose branch holds no commits beyond the last ticket's branch, and so is not the tip, finishes with --merged-into <tip branch>. A ticket branch that was never pushed after a stop is kept, and the Run report names its path and branch. Leave the worktree holding the Stack's tip alone: its Dev stack stays running and the Run report names the worktree. In a repo with a contract, the script destroys each one's Dev stack before it removes the worktree. Note any worktree it leaves, and why, for the Run report.
12. Release this session's worktree lock, as the worktrees skill's Release section says. Then load the run-report skill and end with the Run report in its Stack form: the pull requests in merge order (pull request 0 first when the Stack has one), or "Stack stopped at Group <n>" after a stop. Its worktree is the one holding the Stack's tip, and when step 8 ran, it carries that stack's dev-stack lines. Its "Before merging" section collects the real-provider items from every implementer and from step 8 once across Tickets, so a provider several Tickets touched gets one item.