CrewRig

Plan format

This document defines the normative format for the PLAN artifact of the lifecycle introduced in ADR-0010 — specifically Stage definitions → PLAN. It is the contract that every plan SHALL satisfy and the schema that the plan reviewer (per AGENTS.md → Plan review protocol) and the retroactive routing engine (issue #172) will rely on. The format is mandated by specs/0004-plan-format-and-review.md (R1..R11) and, for the tier-conditioned mandatory set below, by specs/0138-tier-bounded-plan-artifacts-and-loops.md (R1); every section below traces back to one of these requirements.

Not a file — a comment

A plan is a GitHub comment posted on the logbook issue, not a file in the repository. Consequently a plan has no YAML frontmatter and no file path. Future readers SHOULD NOT graft a frontmatter schema by analogy with docs/spec-format.md: the spec format applies to artifacts that ship on main and need machine-readable metadata; the plan format applies to discussion-thread comments whose machine-read fields (id, status, related issue) are already carried by the GitHub issue itself.

Header conventions

The first line of every plan comment SHALL be a level-2 heading matching exactly one of the patterns below.

Comment kind Header Requirement
Initial plan ## PLAN — issue #<N> (spec <NNNN>) R1
Revision ## PLAN v<N+1> — issue #<N> (spec <NNNN>) — revision after <trigger> R9
Review (pass 1) ## PLAN review — issue #<N> (or ## PLAN review of v1 — issue #<N>) followed by ### Verdict: APPROVE or ### Verdict: REQUEST CHANGES on the next non-empty line R6
Review (pass M ≥ 2) ## PLAN review of v<M> — issue #<N> followed by ### Verdict: APPROVE or ### Verdict: REQUEST CHANGES on the next non-empty line R6

<N> is the logbook issue number, <NNNN> the zero-padded spec id, <M> the plan revision ordinal being judged (v1, v2, etc.), and <trigger> is a short noun phrase describing why the revision exists (DEV finding, user request, REQUEST CHANGES review, etc.). ## PLAN review — issue #<N> is accepted as a backward-compatible alias for ## PLAN review of v1 — issue #<N>.

Mandatory body sections

An initial or revised plan comment SHALL contain the level-3 headings below that are mandatory at its complexity tier (see Tier-conditioned mandatory set), in this order, with their text matching verbatim (case-sensitive, no trailing punctuation). A future plan linter will rely on header presence and ordering to validate conformance.

1. ### Approach — one paragraph, plain prose. Captures the semantics of the plan — what stance the implementation takes — in a single breath. No file-by-file enumeration here; that belongs in ### Steps.

2. ### Steps — ordered list. Each step SHALL name the concrete file path(s) it touches and a one-line description of the edit. A step MAY carry the [P] marker as its first token (after the list number) to indicate the step CAN run in parallel with the preceding step; absence of [P] means strictly sequential (R4).

1. Edit `path/to/a.md` — add the X section after Y.
2. [P] Edit `path/to/b.md` — refresh the Z table.
3. Run `scripts/build-components.sh` and stage the regenerated outputs.

3. ### Blast radius — bullet list. Each bullet names one of: an affected code path, a downstream ticket, a build output, a version-bump trigger (per AGENTS.md → Version Bump Convention), or a CLI-matrix trigger surface (per AGENTS.md → CLI Matrix Maintenance). When a category is genuinely empty for the ticket, state so explicitly (Build outputs: none.) rather than omitting the bullet — silence reads as oversight.

4. ### Alternatives considered and rejected — at least one alternative, each followed by a one-line rationale. The purpose is to surface the design space the author traversed; a plan with zero rejected alternatives is rarely a plan that explored options.

5. ### Rollback strategy — one paragraph. Names the concrete revert path (commit revert, configuration rollback, data migration reversal, etc.) and any coordination required with downstream tickets or deployed components.

Tier-conditioned mandatory set

The complexity tier declared in the ticket's spec frontmatter (per ADR-0010 → Complexity tiers and team sizing) determines which of the five sections above are mandatory:

  • At every tier — trivial, small, standard, and large — ### Approach and ### Steps are mandatory for a structured plan comment; the sole exception is the trivial-tier one-line plan confirmation admitted by spec 0138 R2 and by ADR-0010 → Stage definitions and transition rules rule 3, which is a sufficient PLAN artifact without either section. That confirmation still carries the Initial plan header ## PLAN — issue #<N> (spec <NNNN>) from Header conventions above, so it stays discoverable under the header patterns this document's preamble names and satisfies specs/0004-plan-format-and-review.md R1; it is exempt from the level-3 section set alone.
  • At trivial and small tiers, ### Blast radius, ### Alternatives considered and rejected, and ### Rollback strategy MAY be omitted; when present, they SHALL keep the format defined above.
  • At standard and large tiers, all five sections remain mandatory (R1 of spec 0138).

These clauses bound the plan's size and the loop's length; they remove no item from the reviewer's checklist at any tier.

Optional sections

### Risks — discrete risks with a one-line mitigation or acceptance note each. When present, the section SHALL appear after ### Rollback strategy (R3). Plans that surface non-trivial uncertainty SHOULD include it; plans whose blast radius is fully bounded MAY omit it.

### Finding traceability (or ### Revision rationale & traceability) — a Markdown table mapping every reviewer-minted ID (v<N>-F<M>) raised across prior review passes to its resolution or rationale in the revised plan comment. Mandatory when revising a plan in response to a REQUEST CHANGES verdict. The table SHALL carry the schema:

| Plan Ver | Finding ID | Resolution / Rationale | Step |
|---|---|---|---|
| v1 | v1-F1 | Added preconditions step | Step 1 |
| v1 | v1-F2 | Clarified scope boundary | Step 3 |

The row count of addressed reviewer-minted IDs SHALL equal the total number of findings raised across prior review passes (per docs/plan-review-protocol.md → Countable invariant).

Finding tag schema

Every plan-review finding SHALL carry a reviewer-minted identifier in its header (v<N>-F<M>) and exactly one class: field whose value is one of tech, arch, or spec (R7). The class drives the loop target of the retroactive review loop; the routing matrix is defined once, in docs/retroactive-loop.md → Routing matrix (restated in condensed form in ADR-0010 → Routing matrix), and SHALL NOT be duplicated here.

A reviewer comment that lists multiple findings SHALL tag each finding individually:

**Finding 1 (v1-F1)**

class: tech
<one-paragraph description and remediation pointer>

**Finding 2 (v1-F2)**

class: arch
<one-paragraph description and remediation pointer>

Findings without a class: tag are malformed and SHALL be returned to the reviewer for retagging before the routing engine consumes them.

Append-only revisions

Once a plan comment is validated (by the reviewer in autonomous modes or by the user in FULL / INTERMEDIATE mode), it SHALL NOT be edited or deleted (R9). Subsequent revisions are posted as new comments with the revision header above, citing the trigger. Silent edits of a validated plan break the audit trail the retroactive review loop relies on and are prohibited.

Worked example

The first live use of the PLAN stage was the validated plan for issue #170 (the spec-PR workflow ticket), authored by the architect role in INTERMEDIATE mode and validated by the user before the implementation branch was cut. It is the canonical worked example this document points to (R10):

Readers should treat the comment's structure — five mandatory sections, file-path-anchored steps, an explicit deferral recommendation, zero [P] markers because the steps were genuinely sequential — as the lived demonstration of the schema above.