About sync-spec
sync-spec is a workflow skill for bringing one feature’s requirements, design, tasks, tests, and index back into agreement. It emphasizes preserving requirement history and making status changes only when evidence supports them.
Key features
- 01Compare requirements, design, and tasks
- 02Use trace checks before and after edits
- 03Preserve immutable requirement IDs
- 04Flag orphan references for decisions
- 05Update status only with evidence
- 06Keep the specs index synchronized
Use cases
- 01Reconcile a feature’s specification after code changes
- 02Find requirements missing tasks or design coverage
- 03Review whether completion status is supported by tests
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/sync-specin Claude Code to confirm it loaded.
Details
From the project READMESync a Spec
Realign one feature's spec triad (docs/specs/<date>-<feature>/{requirements,design,tasks}.md) with what is actually true — in the code, the tests, and the tasks. Specs that are not resynced after change become fiction, and fiction is worse than no spec.
Work one feature at a time. Identify the spec directory first (from the user, the current branch, or docs/specs/INDEX.md).
Iron rules
- Never renumber requirement IDs. IDs are immutable once approved; everything downstream cites them.
- Never delete a requirement. Retire it:
~~**CODE-N.M**~~ <reason>— struck-through IDs stop counting as defined, but the history stays legible. - New requirements get the next free number under their story; new tasks match the existing task format exactly.
Steps
a. Baseline. Run the trace check (REQUIRED SUB-SKILL: use trace) and capture the finding set — this is the "before" picture.
b. Requirements ↔ tasks. Compare requirements.md against tasks.md:
- A live requirement no task cites → append a covering task in the same format as the rest of the file, ending with its
_Requirements: CODE-N.M_footer. - Work that is verifiably complete (implemented and its verify evidence exists) but whose task box is unchecked → check the box.
c. Requirements ↔ design. Compare requirement IDs against the Satisfies: lines in design.md. Any live requirement appearing in no Satisfies: line gets flagged to the user — either the design needs a section (extend it) or the requirement is aspirational (consider retiring it). Do not invent design content silently.
d. Orphans. List every task footer and test annotation citing an ID that is struck through or does not exist. Present the list to the user with a suggested disposition per item (repoint to a live ID, retire the test, or resurrect the requirement) — orphans are decisions, not cleanup.
e. Status transitions — with evidence only.
| Transition | Required evidence |
|---|---|
| Draft → Approved | the user explicitly approved the spec — never inferred |
| Approved → Implemented | every task box checked AND the trace check shows every live requirement covered by a test |
| Implemented → Shipped | the feature went out in a release (this step is normally invoked by release) |
Apply any transition whose evidence exists: update the Status: line in requirements.md and the feature's row in docs/specs/INDEX.md. If evidence is partial, say exactly what is missing instead of transitioning.
f. After picture. Re-run the trace check and print both finding sets side by side — errors and warnings resolved, anything remaining, and what you changed to get there. Confirm docs/specs/INDEX.md reflects every spec's current Status: line, staged into this same commit.
Done when: the after-report is no worse than the before-report on errors, every flagged item has either an edit or an explicit user decision pending, and INDEX.md agrees with every spec's Status: line.