domains / software-engineering / implement-spec / implement-spec

implement-spec

Skill card

combined

The two copies describe different procedures for the same skill name. mattpocock/skills treats the spec as a ticket graph and orchestrates parallel implementer subagents in worktrees, merging to an integration branch and using a merger subagent. dzhng/skills treats the spec as a sequence of reviewable passes with maintenance checkpoints, visual verification, and a choices ledger, and does not use the ticket/worktree/merger model. Neither is a shortening or wrapper of the other; crowning one would hide a real alternative workflow.

Repositories

Other copies

Combined skill

---
name: implement-spec
description: Implement an existing spec to completion using either a ticket-graph subagent model or a reviewable-pass model, depending on the spec structure.
---

# Implement Spec

Build the active spec to completion. The spec is the implementation plan; user constraints and accepted evidence remain binding when the architecture changes.

## Choose the execution model

- If the spec is decomposed into tickets with blocking relationships, use the **ticket-graph model**.
- If the spec is decomposed into slices or passes, use the **reviewable-pass model**.

## Ticket-graph model

1. Read the spec and tickets to understand the task graph.
2. Optionally use an exploration subagent to gather codebase or external documentation notes, saved outside the repo for all subagents.
3. Create an integration branch. If the issue tracker closes work through PRs, open a draft PR after the first merge, marked as closing the spec and tickets.
4. For each ticket in the frontier, run an implementer subagent in its own worktree on its own branch. Each implementer:
   - confirms its worktree is based on the integration branch and resets if not;
   - uses the `tdd` skill to build the ticket;
   - merges the integration branch tip into its own branch before reporting done.
5. When an implementer completes, use a merger subagent to merge its work to the integration branch.
6. If the frontier changes, kick off more implementer subagents for the new tickets.
7. When all tickets are complete, run the `code-review` skill on the integration branch and fix all issues in a single implementer subagent.
8. If a draft PR exists, mark it ready for review. Otherwise, resolve each ticket the way the issue tracker closes work and report the integration branch.
9. Clean up all implementer worktrees.

## Reviewable-pass model

1. Read the repo README, the spec README, and the next slice before editing. Load any skills named by the spec. Identify the current pickup point, global TODOs, required gates, and what must stay green. If a multi-slice spec lacks a live handoff prompt, add one before the first pass ends.
2. Reconcile the plan with the current code. Replace development-only shims, duplicated types, weak wrappers, or obsolete paths with the simpler architecture and update the spec handoff.
3. Implement one coherent pass: usually one slice, one vertical checkpoint, or one architecture correction. Keep the review surface small enough to audit.
4. Verify the actual contract. For behavior changes, run focused unit tests first. For browser-visible work, use the real browser/harness and inspect screenshots. A visual change requires a byte/pixel diff against the pre-change baseline and an unprimed screenshot critique before declaring it fixed. Never weaken an existing default gate or repin a failing contract without proving the old contract is wrong.
5. Review the change list and clean up after every pass, before committing. Read `git status` and `git diff --stat` line by line and account for every path. One-off probes, shot scripts, scratch files, `nohup.out`, ad-hoc screenshot dirs, and disposable SPIKE/debug notes never enter a commit. Preserve frozen references, fixtures, and research evidence in the project's reference or spec assets area.
6. Run the `review` skill at the end of every pass, before committing. It sequences refactor-clean on the shape, code-review on the settled diff, and write-docs on what the change touched. Apply the fixes from all three. Run `audit-choices` on the cleaned pass to append every decision made where the spec was silent to the spec's choices ledger. Act on its findings: redo unsound choices from their corrected decisions, adopt the recorded provisional call on any user-only entry. Rerun the affected checks, then commit only the focused changes from this pass.
7. Update the spec README's "Next Agent Prompt": status, completed work, next pickup point, blockers, changed gates, and any architecture decision that changed the plan.
8. Run a maintenance checkpoint as part of the loop, not as endgame cleanup. Trigger it after a red pass, after every two or three slice commits, after a rebase/resume/compaction, before changing feature areas, when evidence invalidates the plan, when the handoff contradicts the TODO/graph, when the choices ledger's entries cluster around one slice, or when the active prompt grows hard to scan. A checkpoint cleans both plan and code before more feature work:
   - Shorten the README handoff to one current pickup, one priority order, and one compact evidence ledger; move play-by-play into slice files or assets.
   - Correct completed/rejected/next markers; delete stale TODOs, stale acceptance claims, duplicated status sections, and obsolete prompts.
   - Re-rank remaining work so the next red/high-risk contract is explicit.

## Conflicts

- mattpocock/skills prescribes a ticket-graph model with worktrees, implementer subagents, and a merger subagent; dzhng/skills prescribes a reviewable-pass model with maintenance checkpoints and a choices ledger. The two models are not interchangeable and should be selected based on the spec's structure.
- mattpocock/skills delegates implementation to subagents and communicates via context pointers; dzhng/skills requires the orchestrator to perform detailed per-pass cleanup, visual critique, and audit-choices in addition to delegating independent passes.