Skip to content

leek/agent-skills / skills/implement-spec

implement-spec

Verified

Build a whole spec fast: parallel implementer subagents work the ticket frontier, each in its own worktree, merging onto one integration branch; then one review, one verification pass, and one PR or a stack of PRs.

Implement Spec

Build every ticket of one spec in this session by orchestrating, not building: implementer subagents do the code, each in its own worktree; you own the tracker, the integration branch, the merges, and the final gates. The goal is the whole spec on one integration branch, every ticket closed, delivered as the user chose: one PR, a stack of PRs (one per ticket), or a pushed branch.

The tickets are not a list of steps. They are a task graph: blocked-by edges mean there is always a frontier of tickets ready to grab, and every ticket on it can be built at once.

Reach for the neighbours instead when they fit better: /implement <spec> all builds the same tickets one after another in this session, with no subagents (and is the fallback when the harness has none: say so and stop); autopilot builds the same frontier the same way, on the same kind of integration branch, but with a script as the orchestrator and fresh top-level sessions as the implementers, so the run goes on while you are away.

Talk to subagents in context pointers: paths to the spec, the ticket, blocker resolutions, notes, commits. Never paste what a pointer already reaches. Ask them for sparse reports. To follow up with a subagent (an implementer or fixer), use SendMessage to the agentId you kept against its label in Claude Code, or the follow-up move in harness-tools elsewhere; where neither exists, brief a fresh one with its worktree path, its ticket or findings, and the new input.

Guardrails

  • Never reset, roll back, drop, or truncate a database this run did not create, or run another destructive data operation on one, without explicit approval. Schema changes go in new migrations.
  • Verify identifiers before using them: route names, config keys, enum values, package APIs.

Stack references. Identify the stack from its manifests. If a matching file exists below, read it before step 1 and pass its pointer into every implementer brief: it names that stack's destructive commands, worktree setup, test-config files, and formatter.

Ticket board. Report each ticket's status per ticket-board.md, with kind: "spec": ready and blocked (note: the blockers) from step 1, not-built (note: why) or skipped for tickets left out, as that file tells them apart, running at dispatch, fixing when a failure goes back to its implementer, merged (note: the merge SHA), released (note: why), and closed in step 7, or awaiting-deploy (note: the after-deploy steps, in a few words) for a delivery ticket left at ready-for-human. From step 5 on, also send the stage at each change (review and verify round 1, fix pass 1, review and verify round 2, fix pass 2, fix pass 3 when step 5's extra round runs, final checks, deliver) and each finding's status, so the pane never goes quiet after the last merge. Step 7 sends the open list.

Process

1. Load the task graph

Read the spec: its Build Contract section first, then what the tickets name. Run bash <this-skill-dir>/../setup/scripts/ticket.sh frontier <spec slug> once (<this-skill-dir> is this skill's directory; written ticket.sh below): its tickets give each ticket's derived state, blocked_by, claimed_by, deploy_gate, and delivery, and its frontier the ready ones.

No tickets/ yet? Cut them yourself with to-tickets' rules: its step 3 for the slicing, its step 4 for the open decisions, its step 5 and Ticket template to publish and commit. Vertical slices with honest blocked-by edges are what make the frontier wide; a chain of tickets each blocked by the last builds no faster than /implement all.

Open the ticket board now, before anything else in this step: load mcp__leek-skills__ticket_board with ToolSearch if it is deferred, and send every in-scope ticket with its title as ready or blocked, and each left-out one as skipped (closed) or not-built (open; note: why).

Leave out closed tickets and tickets claimed by someone else (name them in the report). Never dispatch the delivery ticket (delivery: true) to an implementer: you work it in steps 6–7. A deploy-gate: true ticket bounds the run: build up to and including it, then stop at step 7 with a PR.

Run bash <this-skill-dir>/scripts/spec-run-state.sh <slug> once from the main checkout (read-only, JSON). Its branch is the name this run uses wherever this skill says <slug>: an earlier run's finished branch moves this one to the next free <slug>-<n>. That covers the branch, its worktree, and the notes directory only: the spec's own directory is always .scratch/<spec slug>/, never .scratch/<slug>-<n>/. When mode is resume, or a deploy gate has dependents in scope, read references/resume-and-gates.md now and follow it in steps 1–3.

Sweep for open decisions first. Run one read-only subagent over the spec, every in-scope ticket, and the spec's decisions/ and research/ (a domain-expert agent type when the harness offers one for the spec's domain). Its brief: list every choice the build will have to make that these documents do not settle, each with the tickets it touches, the line that leaves it open, and a recommended answer. Settled choices (including those to-tickets' sweep already wrote to decisions/) and pure implementation detail are not open decisions. Most questions a run would otherwise raise mid-build come from here, and asking them now keeps the frontier moving. Skip the sweep when the script's decision_sweep_done is true (a committed Build decisions ticket from to-tickets, and no later commit touched the spec or a ticket): that sweep already covered these documents.

Before the first dispatch, ask these in one structured-question call (harness-tools; a second call when they pass four; otherwise one message in chat), and nothing else:

  • Open decisions from the sweep, recommended answer first, in as many further structured-question calls as they need (at most 4 questions each). Step 2 commits the answers to the integration branch; pass that pointer in every implementer and review brief so a reviewer never reopens a settled choice.
  • Worktree: build the integration branch in a worktree at .claude/worktrees/<slug> (recommended: this checkout stays as it is), or switch this checkout to <slug>. Skip it when the tree is dirty (the worktree is the only option; say so) or the request already says. Each implementer gets its own worktree either way: that is what lets them build in parallel.
  • Delivery: implement's delivery question for a whole spec: one PR, stacked PRs, or the branch with no PR.
  • Deploy gate, when dependents wait behind one (per the reference).
  • Resume, on a resumed run with claims of its own (per the reference).
  • Cleanup: at the end, remove what step 8 would otherwise ask about (a refused or released ticket's worktree and database, and the verify setup) without asking (recommended), or list them for a choice then. A worktree holding uncommitted work beyond agent notes is always listed, and a branch with unmerged commits always stays.

Finish when every in-scope ticket and its edges are known, the ticket board lists them (where the tool exists), the open decisions are answered, the worktree, delivery and cleanup choices are made, and the first frontier is listed.

2. Create the integration branch

Make a notes directory outside every worktree: the script's notes (<git-common-dir>/implement-spec/<slug>). Its screenshots/ folder is the run's one screenshot folder: name it in every brief whose agent may open a browser (the verifier's, each implementer's), so no image sits in a temporary folder that a cleanup removes.

On a resume, set up the integration checkout and base_sha per the reference. Otherwise make implement's PR delivery: before step 1 call: bash <this-skill-dir>/../implement/scripts/start-branch.sh <spec slug> --branch <slug> --default <default>, with --worktree when step 1's worktree answer (or a dirty tree) says so, --reset-default always (it moves local <default> back only when that loses nothing), and --stack --title "<spec title>" for Stacked PRs. Write its base_sha to $notes/base_sha, keep integration_pr, and do its todo. Either way, this checkout is the integration checkout.

When step 1 answered open decisions, make that call without --stack, then write them in the integration checkout as one closed decision ticket in .scratch/<slug>/decisions/, in the format to-tickets' Publish step gives its Build decisions ticket, and commit it (docs(scratch): <slug> build decisions, unless the repo ignores .scratch). Only then take base_sha: git rev-parse HEAD, or for Stacked PRs the base_sha that start-branch.sh <spec slug> --branch <slug> --stack --title "<spec title>" --existing prints with integration_pr. So every ticket worktree carries the answers and no ticket's PR shows them.

When several tickets need the same exploration (an unfamiliar module, a package's docs), run one read-only exploration subagent first that writes its findings to $notes as Markdown, so implementers build instead of explore.

3. Dispatch the frontier

For each frontier ticket, up to the concurrency limit (default 5: each one runs a test suite). A ticket whose ## Files share a path with a running ticket's waits until that one merges, so the two never conflict; dispatch the next frontier ticket instead.

  1. Claim it in the integration checkout: ticket.sh claim <path> --as implement-spec-<slug>-<run id> --built <NN,NN> (the tracker's Claim operation), where --built lists the tickets this run has merged: they close only in step 7, and without it their dependents are refused as blocked. Only you write .scratch/; claims stay uncommitted until step 7.
  2. Worktree. git worktree add -b <slug>--<NN> <main checkout>/.claude/worktrees/<slug>--<NN> <integration tip> (the main checkout's .claude/worktrees/, never one inside the integration worktree), then make it runnable (install dependencies, copy local env config) the way the project's docs say, or as the stack reference says. When you write the setup into the implementer's brief, point at that recipe rather than restating a shorter one: a hand-written list that skips a step (for Laravel, the herd.yml workspaces.copy files) fails the implementer's first artisan call. When the tests need a real database, give it its own (<app db>_spec_<slug>_<NN>, never a name the main checkout's env or test config uses) and register it the moment you create it: bash <this-skill-dir>/../laravel-herd-worktrees/scripts/scratch-db.sh register <pgsql|mysql> <database> <worktree path> (Scratch database registry).
  3. Implementer subagent, in the background where the harness allows (Claude Code: subagents run in the background by default and wake you on completion; pass run_in_background: true where the Agent tool offers it; give it no name (a named subagent is never woken by its own background command) and start its description with <slug>--<NN>, so the ticket board finds it; write the returned agentId into $notes/<NN>.md at once, so a compacted context can still address it; other harnesses: dispatch in the background per harness-tools, keeping each returned id against <slug>--<NN>). Its brief gives pointers (worktree path, ticket path, the spec's Build Contract, the decisions answered in step 1, direct blockers' reports from step 4, the notes directory) and these rules:
    • Work only in that worktree (enter it with EnterWorktree({path}) where available, otherwise use absolute paths into it). Confirm git merge-base --is-ancestor <integration tip> HEAD before starting.
    • Choose seams with the tdd skill's Seams: where tests go rules and state them; then call the Skill tool with tdd and build the ticket test-first. Focused tests and configured static analysis end green.
    • Before writing each of these kinds of change, call the Skill tool with its skill (where the harness has no Skill tool, read that skill's SKILL.md: write each one's absolute path into the brief): what a user sees (views, templates, components, stylesheets, or UI-defining classes such as Filament resources, pages, and widgets, or Livewire components) → ui-design, meeting its Build section's done condition; user-facing strings (labels, messages, notifications, emails, lang/ files) → brand-guidelines, following its Write section; an ADR or a GLOSSARY.md entry → domain-modeling.
    • Run tests in the foreground and wait for the result. A run too long for the tool's timeout is too broad; run fewer files. Never end your turn while a command you started is still running. If the shell tool moves a command to the background (it does at its timeout), wait for it in the foreground: bash <this-skill-dir>/../harness-tools/scripts/wait-task-output.sh <the output file it named>, and run that again while it prints running. (Write the script's absolute path into the brief.)
    • Format touched paths with the repo's configured formatter, commit per the commit skill's Staging and Subject sections (write <this-skill-dir>/../commit/SKILL.md's absolute path into the brief), leaving .claude/agent-memory/ out: step 8 carries it. Never touch .scratch/, never push, never write another branch.
    • When you look at your work in a browser, save a screenshot as $notes/screenshots/<NN>-<what>.png and list its path in the report. Tests that cover the change need no browser.
    • Before reporting, merge the current integration tip into the branch and rerun the focused tests.
    • Report in at most ten lines: commit SHAs, touched paths, seams (name any public seam a dependent ticket should reuse), the focused test command and result, deviations from the ticket, any decision built on an assumed answer, and anything blocking.

Then end the turn and let completion notifications wake you; never poll. An idle notification or completion from an implementer that has not reported is a stall, not progress, even when it says it is waiting on a background run: follow up with it at once, per harness-tools' stall rule, to finish or say what blocks it. One that repeats a report you already acted on needs nothing: end the turn without a reply.

A hung tool call sends no notification at all. So give every running implementer an idle watch, started with its dispatch: bash <this skill's dir>/scripts/worktree-idle.sh <worktree> as a background shell command (Claude Code: Bash with run_in_background: true, never a Monitor, which expires after 30 minutes; elsewhere, per harness-tools, or check the worktree's last file change whenever anything wakes you). It exits once that worktree has gone 20 minutes with no file change, or prints gone when the worktree is removed. Never hand-write the time check, since stat and date flags differ between macOS and Linux. Stop an implementer's watch (TaskStop) when its report lands, and start a fresh one with each follow-up. Woken by a watch with no new commit, message that implementer to report what it is waiting on, and stop the hung call when it cannot.

4. Merge as each implementer lands

With Stacked PRs, review the ticket on its branch first, per implement's Stacked PRs step 1: its PR must hold every commit it will ever get. Then, in the integration checkout: git merge --no-ff --no-commit <slug>--<NN>. On a conflict, call the Skill tool with resolving-merge-conflicts. Rerun that ticket's focused tests on the merged tree, then commit the merge; on a failure, git merge --abort, so <slug> only ever holds green merges. With Stacked PRs, push and open the ticket's PR right after its merge commit, per implement's Stacked PRs. A failure goes back to the same implementer with the output (follow up with it), so it keeps its worktree and ticket context; a ticket that reports itself blocked is released (ticket.sh release <path> --note "<why>"), and its dependents stay out of this run.

Keep each implementer's report in $notes/<NN>.md: it feeds dependents' briefs and the ticket's Resolution. A merged ticket counts as done for its dependents, so recompute the frontier (ticket.sh frontier <spec slug> --built <NN,NN>, every merged ticket listed) and dispatch what it unblocked (step 3).

After each merge, update the ticket board, and post one progress line so the user never has to ask for status: <NN> merged (<k> of <M>); running: <NNs>; next: <NNs>, with · PR #<n> after merged in a stack. Skip the line when the board's pane shows the run.

A question never stops the run. A decision the sweep missed (one that only shows once code exists) is built on its recommended answer when that answer is reversible: the implementer or fixer records it as an assumption in its report, and you ask it at the next merge, so a different answer becomes a follow-up fix, not a wait. When the choice is not reversible (a schema shape a later ticket builds on, a data migration), release that ticket and its dependents, keep building the rest of the frontier, and ask the open questions together at the next merge, or in the final report when nothing else is running. Stop and wait only when every remaining ticket is blocked on an answer.

Record work outside the spec at once. When the user decides or asks for something during the run that this spec does not cover (a side grill, a new instrument, a new feature), write it to the tracker in the same turn: a decision record per grilling's Record the ledger, or a ticket. Then send it on the board's open list with that path as its where, and name it on the end block's Open line. Chat holds no copy that the next session can find.

Finish when every in-scope ticket but the delivery ticket is merged or released, and no implementer is running.

5. Review and verify once, over the whole branch

Start both at the integration tip, at once: call the Skill tool with code-review against base_sha on the integration branch, scoped to every path the run touched, and dispatch one verifier subagent (dispatch and wait per harness-tools) that calls the Skill tool with verify (otherwise follows the verify skill) and checks every ticket's acceptance criteria in one pass. Its brief: screenshot every surface it checks, pass or fail, as $notes/screenshots/<NN>-<what>.png (<NN> the ticket number), and report each failure and every screenshot's path. A harness with no sub-agents runs verify inline once the review returns. Verification needs no review fix to start, and its failures join the same fix batch instead of a second cycle. With Stacked PRs, every ticket's commits were already reviewed on every axis before their merge, so pass code-review only the Correctness and Spec axes (plus UI when a review-fix commit changes what a user sees, aimed at those commits), its Correctness brief aimed at what crosses tickets (shared seams, ordering, one ticket's change breaking another's path) and at each ticket's review-fix commits, which got no re-review of their own. Its fix batch also takes every ticket's BLOCKING and MAJOR Left open: findings.

Fix both sets of findings as one batch, grouped into fixers per Parallel fix batch steps 1–4 (its merged-tree test run included; the re-review below is its pre-push review, and nothing is pushed): each fixer in a detached worktree <main checkout>/.claude/worktrees/<slug>--fix-<k> off the integration tip, labelled <slug>--fix-<k> (its database, when it needs one, <app db>_spec_<slug>_fix<k>), merged back into the integration checkout. A batch below that file's threshold goes to a single fixer, <slug>--fix, working in the integration checkout. Later rounds follow up with each fixer, and a fixer merges the integration tip into its worktree before a later round, so it builds on every earlier fix. Fixers work through tdd and commit each finding on its own, with a subject that says what it fixed. Mark the findings fixing at the handoff, and fixed (note: the SHA) for each one whose commit git log shows whenever you wake. When you tell the user about findings, name each by what is wrong and where, never by a made-up code (C2, S1) the user has no key for; once the fixes are merged, re-run code-review as a re-review, passing the previous round's findings and head, and re-run verify only on the criteria that failed or whose code the fixes touched. A finding that needs the user's decision never holds the round: send every other finding now, ask that one in parallel, and pass the answer on as a follow-up. Two rounds is the budget. When the second still has BLOCKING or MAJOR findings, fix those in one more round without asking, its re-review covering only them; name whatever is left in the final report and the PR, with the commit each round reviewed (if the user asks to ship them in a follow-up PR, open one follow-up PR for all remaining findings, never one PR per finding, after step 7, based on the integration branch while that PR is open (in a stack, on the closing PR's <slug>-stack-fixes, since the remote <slug> holds no ticket until triage lands them); once it has merged, retarget per Follow-up on a delivered PR). Finish when review and verification report nothing actionable, or when the rounds are spent; a verification failure an external dependency blocks is named, and its tickets stay open.

6. Final checks

Run implement's step 6 once over the whole range. Skip the full-suite question when the repo's rules or the user's saved preferences already settle it (CI runs the suite, or "do not run the full suite unless asked"); otherwise ask once. A declined full suite is never replaced by a broad sweep of many test files: each ticket's focused tests stand as the evidence. A failure the run caused goes to step 5's fixers. Then, when the spec has a delivery ticket, run its pass 1 per DELIVERY-TICKET.md: the full suite and step 5's verify pass count toward its Before merge list, and a coverage gap goes to step 5's fixers like a product failure. Finish when the checks passed and pass 1 is done, or name the exact external blocker and leave those tickets open.

7. Close and deliver

For each verified ticket: write its Resolution (what was built, deviations, verification evidence, its implementation commits, seams for successors, from $notes/<NN>.md) to a file and run ticket.sh resolve <path> --body-file <file>, which appends it, sets status: closed, and clears the claim. The delivery ticket closes, or goes to ready-for-human with its after-deploy steps copied into the PR body, per its file. Commit the tracker separately (docs(scratch): <slug> resolutions), never folded into code. Then follow PR delivery: after step 8 for the chosen shape: push, open the PR (or, for a stack, whose ticket PRs opened as each ticket merged and whose integration PR opened in step 2, open the closing PR and fill in the integration PR's body per its Stacked PRs step 4), and read review threads once, except on a stack. A fix that is built but not committed or pushed follows that section's Not yet in this pull request rule: the delivery is not complete while one exists.

Screenshots reach the pull requests. Upload the images in $notes/screenshots per the pr skill's Screenshots section, which inspects each one first, and put them in the pull request's Evidence: in a stack, on each ticket's pull request (its <NN>- images) and on the closing one, per Stacked PRs step 4. After each successful upload, run bash <this-skill-dir>/scripts/screenshots-report.sh $notes --uploaded <image>...; an image that section leaves out goes to --left-out instead. Then run it with no flag. While its counts.not_uploaded is above 0 the delivery is not complete: each such image goes on the board's open list as not-shipped, with the folder's path as its where.

Last, send the board's full open list per ticket-board.md's Open after this run, and settle every entry and finding the pane still shows as unfinished per its Keep the open list true: entries sent earlier in the run stay on the pane until a call marks them. Work done later in this session (a follow-up fix, after-deploy checks, a triage) updates the board the same way.

8. Clean up

Run cleanup from the integration checkout, so git branch -d checks each ticket branch against <slug>. For each ticket merged into the integration branch, clean up only the environment this run created, in order: carry any change under its .claude/agent-memory/ into the main checkout's copy (reviewer notes are append-only: add the lines the main copy lacks), then restore the tracked notes (git checkout -- .claude/agent-memory, when any are tracked) and delete the untracked ones you carried (git status --porcelain --untracked-files=all -- .claude/agent-memory lists them); then run bash <this-skill-dir>/../laravel-herd-worktrees/scripts/remove-worktree.sh <worktree> --branch <slug>--<NN> (laravel-herd-worktrees' Remove a served worktree: clean check, no --force, git branch -d only). After it returns, run bash <this-skill-dir>/../laravel-herd-worktrees/scripts/scratch-db.sh drop <database> for each database its databases lists: it drops <app db>_spec_<slug>_<NN> and its _test_<N> copies, unregisters what it dropped, and names each one it kept, with the reason, in kept. A refused removal keeps that ticket's branch, databases, and registry lines together; a refused git branch -d keeps the branch (its -D hint is not a go-ahead). Name each refusal and each kept entry in the report. A fixer worktree <slug>--fix-<k> whose commits are merged goes the same way, with no --branch. List each successful removal. What is left that you created (a refused environment, the environment of an unmerged or released ticket, and the verify setup: the Herd workspace, database or worktree verify made for the run, when it made any) follows step 1's cleanup answer: when anything is left, read references/leftovers.md and do what it says. Keep $notes/screenshots while screenshots-report.sh counts an image as not_uploaded. Keep the integration worktree: it holds the PR branch (leave it with ExitWorktree({action: "keep"}) if you entered it). Anything kept is repository-cleanup's job later.

Stopping mid-run

When the user stops the run, follow Stopping mid-run.

When you're done

Print the end-of-session block using the frame in wayfinder/references/pipeline-end-block.md. Its Pipeline: and Done: lines here are Pipeline: decide → spec → tickets → **build** (4 of 4) and Done: <tickets closed of total, integration branch, PR, verification state>. Its Open line carries every entry of step 7's open list that is not done. Its Next conditions:

  • A PR is open and review bots are still running → /resolve-review-comments <PR> once they post
  • A stack of PRs is open → /triage-github-pr <every PR, bottom-up> to land it bottom-up with merge commits
  • Stopped at a deploy gate → deploy the PR, then /implement-spec <spec> for the dependents
  • The delivery ticket is at ready-for-human → merge and deploy, then /implement <delivery ticket> for its after-deploy steps; list them
  • Tickets released or left open → /implement <ticket> for each, or /implement-spec <spec> again (/autopilot <spec> to leave it running)
  • The build exposed a decision nobody made → /grill-me on it, then re-run /to-spec
  • The run went sideways → /retro this
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall