source: .claude/rules/plans.md · generated — edit the markdown, not this file

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 done with findings), and the timed requests carry no filter users do not apply (for example, “20,000 leads, 90% with research done and 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.md L-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 the bp/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 on main to 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/ for forge-et-fe, pwa-current/ for forge-et-pwa; crm/ and pwa/ are frozen originals. For forge-et-pwa, also name the screenshots: besides citing pwa-current/, name for each screen and state the WI builds its picture in .forge/design/prototypes/pwa-current/screenshots/ (by file, from that folder’s README.md index), 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-runs screenshots/capture.mjs and 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 Modify lists 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-less fix/BUG-* PR included — adds an .forge/owed.md row 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; a type: manual run sheet has tier: 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 the Ownership column 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-verify then 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-review TC-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.md L-045).
  • Progress — updated as subtasks complete (with its ### Failed Approaches subsection)
  • 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:

  • ## Approach holds one short paragraph: what the run proves and against which real system.
  • ## Decisions, ## Risks and ## Test Approach may read “none — person-run”. A run sheet has tier: none and 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: draft in both file and tracker
  • Never assume approval. Only mark approved when the developer explicitly confirms
  • Approval requires a Reviewed-via: /forge-plan-review annotation in the header — the guard-plan-approval hook enforces this at write time (foundation and feature plans both gated)

Progress Discipline

  • Update the plan’s ## Progress section before ending any implementation session
  • At close, tick ## Success Criteria the same way .claude/rules/specs.md § Status Transitions ticks acceptance criteria: every box [x], one dated evidence line at the head of the section pointing at the ## Progress receipts. 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.

Generated from .claude/rules/plans.md by .claude/lib/render-docs-html.js. Markdown is canonical.