Spec Lifecycle Rules
Section schema lives in .forge/specs/_TEMPLATE-spec.md. These are the rules for working with specs.
Required Sections
Every spec must have all the following sections populated:
- Context — why this feature exists, what problem it solves
- Requirements — what the system must do (functional + non-functional)
- Acceptance Criteria — how to verify each requirement. For user-facing features with a design reference, include observable visual ACs: name the token / layout / state — e.g. “Type badge uses the semantic tone in the design-system spec”, not “looks good”. A spec classified as a redesign (or otherwise carrying a prototype/mockup) references that artifact in
## Input Sources. Projects with no design reference state functional ACs only. - Scope Boundaries — what is explicitly out of scope (both In Scope and Out of Scope listed)
- Constraints and Dependencies — technical/business constraints, upstream dependencies
- Open Questions — unresolved questions that must be answered before/during implementation
- Input Sources — screenshots, flows, reference-system behaviors this spec is based on
- Revisions — appended after approval when requirements change
Status Transitions
- New spec →
Status: draftin both file and tracker - Never assume approval. Only mark
approvedwhen the developer explicitly confirms - “Looks good” or “that’s fine” → confirm before marking approved: “Should I mark this as approved in the tracker?”
- Approval requires a
Reviewed-via: /forge-spec-reviewannotation in the header (feature specs only; foundation specs exempt) — theguard-spec-approvalhook enforces this at write time - At close, tick the acceptance criteria. When the item reaches
done(the Reflect walk is the natural moment), every- [ ]under## Acceptance Criteriabecomes- [x], with one dated line at the head of the section pointing at the evidence — the code PRs and the plan’s## Progressreceipts — rather than a pointer per box. An unticked box on a done item reads as an unmet criterion, and nothing else in the file says otherwise. Ticking is an annotation, not a rewrite; a criterion that turned out unmet or retired keeps its[ ]and gains a one-line note in the form— *Not met: <why>; <where that is recorded>.*.python3 .claude/lib/check-done-acs.pyfails on a done feature with an unticked criterion that has no*Not metnote, or with a criterion joined onto the line before it (a removed note once took the next criterion’s line break with it, hiding that criterion from the check);Repo hygieneruns it on every harness PR and/forge-reflectruns it before the flip todone, because nine features once closed with none ticked. Tick in the delivering PR, not a post-merge follow-up — the ACs reach[x]in the same PR that carries the work that meets them (.claude/rules/tracker.md§ Update Rules, “Mark completion in the delivering PR” — which also states the one exception, for ACs owned by a manual wave)
Revision Convention
Approved specs are contracts. When a spec changes after approval:
- Add a revision entry at the bottom under
## Revisions - Update the affected requirements and acceptance criteria in the spec body
- Note the impact on the plan if one exists
A revision that records the lead’s decision names the lead on its **Approved by:** line (the date is in the ### Rev heading) and asks no one to confirm it on the PR. Where the decision touches other specs still at draft or in-review, add a dated note to each of them in the same PR. A revision that rewords requirements gets the fresh-context comparison of .claude/CLAUDE.md § Compounding Engineering item 6. Why: a confirmation request left in a merged PR is never read, and the team already knows the lead’s decisions (the lead, 2026-10-26).
## Revisions
### Rev 1 — YYYY-MM-DD
- **Changed:** [what changed]
- **Why:** [reason discovered]
- **Impact on plan:** [subtask or approach affected]
- **Approved by:** [name]
Revision required: any change to requirements, acceptance criteria, or scope after approval. No revision needed: typos, clarifying detail that doesn’t change a requirement, open question updates.
Rework Triggers (spec is wrong mid-implementation)
- Do not silently adjust an approved spec — follow the Revision Convention above
- If the change invalidates the current plan, pause implementation and revise the plan first
- Reference-system behavior misunderstood → spec revision
- Entirely new feature discovered → add to project PRD for decomposition; do not fold into the current ticket
Pre-Spec Gap Check
Before fleshing out any feature spec body beyond ## Context, run the forge-gap-check skill against the spec. Resolve Blockers (B-N) before drafting requirements; Warnings (W-N) can be resolved during drafting or before the plan.
Findings Capture
Tactical findings discovered during/after feature work go in .forge/specs/<feature>-findings.md (use _TEMPLATE-findings.md). The change that creates the file also adds > Findings: [`<stem>-findings.md`](<stem>-findings.md) as the last line of the spec’s header — a link edit, so no revision entry, even on an approved spec; why: nothing else links a findings file, and Repo hygiene fails one that nothing links (“Unreferenced machinery” in python3 .claude/lib/harness-graph.py). One entry per coherent finding, ID format F-NNN, append-only. Promote generalizable findings to .forge/lessons.md during Reflect with a Promoted: L-NNN back-reference; scoped findings stay where they are with Promoted: scoped.