Plan Lifecycle Rules
Section schema lives in .forge/plans/_TEMPLATE-plan.md. These are the rules for working with plans.
Required Sections
Every plan must have all the following sections populated:
- Success Criteria — the verifiable definition of done, passed to the implementing agent as its halt condition and ticked at close (§ Progress Discipline). A timing or performance criterion names the data shape, not only the volume: most rows sit on the branch production rows take (for example, research
donewith findings), and the timed requests carry no filter users do not apply (for example, “20,000 leads, 90% with researchdoneand findings, no status filter”). Why: a fixture whose rows all took the cheap branch, timed through a filter that cut the rows to a quarter, passed a 300 ms target that the real data missed tenfold (.forge/lessons.mdL-258). - Approach — implementation strategy and key decisions
- UI / Design Adherence — REQUIRED for WIs shipping user-visible UI, only if the project has a design reference (
.forge/design/ui/<design-system>.md+ a prototype/mockup, both project-set). Cite the design-system spec + the prototype and declare the semantic tokens, custom components, and screen layouts the WI conforms to. Sub-views (detail /…/[id]/…/new/…/edit) must declare a back-navigation affordance; all UI text follows the design system’s capitalization rule. Declare thebp/tablet(768px) behaviour — the reflow the screen uses (design-system §9) or an explicit “no reflow needed, fits at 768”; tablet is the CRM floor (PRD § Accessibility), phones (<768px) are out of scope. The spec is authoritative over the prototype. Name, for each visible state the WI builds (selected, hover, a list row, a card, a badge, a dialog), the design-system pattern it uses and one instance of it already onmainto copy (file:selector). A plan never gives a screen its own variant of an existing pattern: a needed change is a design-system revision the lead decides, and the WI that makes it changes every instance in the same PR (design-system’s One look per pattern; L-254). The prototype cited is the current one —.forge/design/prototypes/crm-current/forforge-et-fe,pwa-current/forforge-et-pwa;crm/andpwa/are frozen originals. Forforge-et-pwa, also name the screenshots: besides citingpwa-current/, name for each screen and state the WI builds its picture in.forge/design/prototypes/pwa-current/screenshots/(by file, from that folder’sREADME.mdindex), so the implementer and the reviewer compare the built screen with the screenshot as well as with the prototype; the prototype stays the design, and a WI that changes it re-runsscreenshots/capture.mjsand commits the new pictures in the same delivery. The current prototype leads: a new screen, or a change to a screen’s layout or to a shared pattern, that the WI builds is drawn there before the plan is approved, committed to the ticket’s harness branch, and the section cites it; a small change inside an existing pattern (a label, a column, a state) may be drawn in the same delivery instead (.forge/design/prototypes/README.md § The current prototype leads; the lead, 2026-11-10). A WI that changes how a screen looks also updates that screen in the current prototype: the section names the screen,## Files to Modifylists the prototype file, and a subtask draws the change, committed to the ticket’s harness branch in the same delivery (frontend-implementer§ Design reference). A change that cannot be drawn there in that delivery — a plan-lessfix/BUG-*PR included — adds an.forge/owed.mdrow naming the screen and what differs, or links an open harness PR that draws it. Why: client demos show the built app and then the current prototype for what is not built, so the two must look like one product (the lead, 2026-11-05). Omit (delete the section) for backend-only WIs or projects with no design reference. - Decisions — specific technical choices (patterns, libraries, why)
- Subtasks — ordered, numbered list — small enough to be a session boundary
- Files to modify — specific paths with what changes in each
- Risks — what could go wrong and mitigation
- Test Approach — tier (T1/T2/T3/T-E2E — see
.forge/test-strategy.md; atype: manualrun sheet hastier: none— see “Run sheets” below), rationale, and test tables for the assigned tier; sub-WI plans must match the tier in the Decomposition Plan’s## Test Strategy Map. Runtime-verifiable: every row’s test file must exist on the worktree at PR-open time, every AC on hook (filtered by theOwnershipcolumn for verify-WIs) must be covered by at least one row, and the suite must be green. Execution decoupling (Dispatch Invariant): the test specialists (e2e-test-implementer,seam-test-implementer) author + static-check these tests but do NOT live-run them — a dispatched sub-agent is torn down on return and cannot keep dev servers booted or drive a live browser. The main orchestrator runs the live browser / API-seam tiers and drives a run → classify → dispatch-fix → re-run-until-green loop;/forge-test-verifythen acts as the green-status guard (files exist, ACs covered, the orchestrator’s run is green; for T1/T2 it runs the cheap command itself). Test files are durable, reusable artifacts — reuse existing tests for previously-built functions and author new rows only for new functionality. Plan-time/forge-plan-reviewTC-2 (tier-match) and TC-3 (AC-coverage) are the static counterparts; in wave mode plan-reviewer §11 (Wave Vertical-Shipping Audit) adds verify-WI-aware checks. A row that names a CI lane, a deployed environment or another repo’s tooling is a claim about an external artifact (.claude/rules/source-trust.md): it cites the workflow file and job that runs it, or is written as an intention with the wiring listed as owed work — a plan is read as intentions, so a factual claim inside one is not read as a claim at all (.forge/lessons.mdL-045). - Progress — updated as subtasks complete (with its
### Failed Approachessubsection) - Notes — review feedback, discoveries, anything that doesn’t fit above
Run sheets (type: manual WIs). A manual WI’s plan is a run sheet for a person, not an agent (the schema is in .claude/rules/tracker.md § Workitem decomposition; the section-by-section shape is forge-plan-author’s run-sheet case and _TEMPLATE-plan.md). For a run sheet:
## Approachholds one short paragraph: what the run proves and against which real system.## Decisions,## Risksand## Test Approachmay read “none — person-run”. A run sheet hastier: noneand no test tables.
Sub-WI plan header fields (decomposed specs only): fill > Key Workitem: and > WI ID: from the template — /forge-plan-review uses these to detect sub-WI plans and run tier-match (TC-2) and AC-coverage (TC-3) checks. > Key Workitem: points at the owning Decomposition Plan; > WI ID: is this plan’s work-item id. New or revised sub-WI plans must use > Key Workitem: + > WI ID:.
Status Transitions
- New plan →
Status: draftin both file and tracker - Never assume approval. Only mark
approvedwhen the developer explicitly confirms - Approval requires a
Reviewed-via: /forge-plan-reviewannotation in the header — theguard-plan-approvalhook enforces this at write time (foundation and feature plans both gated)
Progress Discipline
- Update the plan’s
## Progresssection before ending any implementation session - At close, tick
## Success Criteriathe same way.claude/rules/specs.md § Status Transitionsticks acceptance criteria: every box[x], one dated evidence line at the head of the section pointing at the## Progressreceipts. A done plan with unticked criteria reads as unfinished. Tick in the delivering PR, not a post-merge follow-up (.claude/rules/tracker.md§ Update Rules, “Mark completion in the delivering PR” — which also states the one exception, for a manual wave’s run sheets) - Record failed approaches in
## Progress→### Failed Approaches— what was tried and why it didn’t work. Prevents the next session from repeating dead ends - Follow patterns referenced in the plan — if the plan says “follow UserService”, follow it
Rework Triggers
- Check fails → fix in the same worktree and re-run. Record the fix in
## Progress. Normal development loop. - Review rejects implementation → record feedback in
## Notes(what was wrong, what needs to change). Fix and resubmit. If the fix needs a different approach, update the plan with the new approach and note what changed and why. - Spec changed mid-implementation → if the change invalidates the current plan, pause implementation and revise the plan first.
Deviation
Deviating from the approved plan’s approach is an ASK FIRST action — surface it before coding, not after.