Feature: Plan

graph LR
    A["Draft"]
    B["In Review"]
    C["Approved"]
    E["Executing"]
    K["Blocked"]
    I["Implemented"]
    F["Failed"]
    R["Rejected"]
    W["Withdrawn"]
    S["Superseded"]
    D["Deprecated"]
A -->|submit| B
A -->|approve| C
B -->|revisions| A
B -->|approve| C
B -->|reject| R
C -->|lint --fix rollup| E
E --> K
E --> I
E --> F
K --> E
C -->|abandon| W
C -->|replace| S
C --&gt;|retire| D</pre></div>

REQ: status-transitions

Plan status transitions MUST follow these rules. Prep (human-authored): Draft MAY transition to In Review, or directly to Approved (a fast-track that skips review); In Review MAY transition back to Draft (revisions requested), forward to Approved, or to Rejected (the approach is rejected outright, not sent back for revisions). Execution (derived by lint --fix, only from Approved onward): Approved MAY transition to an execution-band status; execution statuses transition among themselves per the task-status rollup. Disposition (human-authored): Approved (or a later state) MAY transition to Withdrawn, Superseded, or Deprecated (the approach is no longer recommended, with no named successor). There is no resurrection from a disposition status — re-pursuing the work means authoring a new plan. No other transitions are permitted.

Snapshots

A snapshot is an immutable reference point within a plan's history. Instead of freezing the entire plan on approval, snapshots record meaningful moments -- approval, checkpoints, completion -- as entries in a table with a corresponding git commit hash.

Snapshots remove the need to freeze a plan on approval. A plan can be edited freely at any time. When a reference point is needed, a snapshot captures the plan's state at that git hash. The snapshot table lives in the plan document:

## Snapshots

| Date | Git Hash | Action | Comment |
|---|---|---|---|
| 2026-03-15 | `a1b2c3d` | approved | Initial approval by @jordan |
| 2026-03-20 | `e4f5g6h` | checkpoint | Added streaming support task |
| 2026-04-01 | `i7j8k9l` | completed | All tasks verified |

REQ: snapshot-table-format

When a plan includes snapshots, they MUST be recorded in a ## Snapshots section containing a table with columns: Date, Git Hash, Action, and Comment.

REQ: snapshot-actions

Snapshot actions include approved, checkpoint, completed, and user-defined values. The approved action SHOULD correspond to setting the plan status to Approved.

REQ: snapshot-git-hash

Each snapshot MUST reference a valid git commit hash that represents the plan's state at the time the snapshot was taken.

Recursive task and plan model

Optional / reserved advanced form. The default and lint-enforced shape of a plan is a single flat file (spec/plans/{slug}.md, per plan-file) whose tasks are inline ### Task N: blocks. The recursive directory decomposition described below is an OPTIONAL advanced form for very large plans; it is not currently enforced or required by specscore spec lint (which enforces the single-file contract via P-003). It is documented here as the reserved model for future sub-plan support.

A plan is a composite task -- it contains other tasks. Some of those child tasks may themselves contain subtasks, making them sub-plans. This nesting is recursive with no artificial depth limit.

spec/plans/
  README.md                          <- index
  chat-feature/
    README.md                        <- plan (composite task)
    chat-infrastructure/
      README.md                      <- sub-plan (also a composite task)
      set-up-database/
        README.md                    <- task (leaf)
      configure-networking/
        README.md                    <- task (leaf)
    chat-workflow-engine/
      README.md                      <- sub-plan
    send-notifications/
      README.md                      <- task (leaf, sibling of sub-plans)
  e2e-testing-framework/
    README.md                        <- plan (standalone, no sub-plans)

Whether something is a "plan" or a "task" is determined by structure: if it has children, it is a plan. If it has no children, it is a task. The same document format applies at every level.

REQ: recursive-nesting

In the optional directory form, plans and tasks MAY nest to arbitrary depth. There is no maximum nesting level. Depth is a judgment call made by the plan author. The single-file form (the default and lint-enforced shape) carries its tasks as inline ### Task N: blocks rather than child directories.

REQ: child-plan-format

A sub-plan (child plan) MUST follow the same format as a top-level plan, including tasks and acceptance criteria.

Mixed children

Tasks and sub-plans can coexist at the same level within a plan. There is no requirement to separate them or force restructuring. In the example above, send-notifications (a leaf task) is a sibling of chat-infrastructure and chat-workflow-engine (sub-plans).

REQ: mixed-children

A plan MAY contain both leaf tasks and sub-plans as direct children at the same level. No restructuring is required to separate tasks from sub-plans.

Cross-repo plan composition

The directory form above nests sub-plans physically inside one repo. Cross-repo plan composition is a distinct, lint-enforced form that composes flat single-file plans — including plans in different repositories — by reference rather than by directory nesting. It is the mechanism behind a single Idea fanning out into coordinated work across repos.

A master plan is an ordinary single-file plan whose work is carried out by sub-plans. Each sub-plan is itself a flat single-file plan that names its master through the Parent header field (**Parent:** <plan-ref>). The reference is either a same-repo plan slug or a cross-repo <repo-slug>:<plan-slug> soft reference. On the master side, a task MAY delegate to a sub-plan via the Task entity's sub_plan property — the master-side expression of the same edge.

specscore/spec/plans/cross-repo-master.md        <- master plan (root: no Parent)
specscore-cli/spec/plans/sub-cli-bootstrap.md    <- **Parent:** specscore:cross-repo-master
specscore/spec/plans/sub-entity-model.md         <- **Parent:** cross-repo-master   (same-repo)
specstudio-skills/spec/plans/sub-skills.md       <- **Parent:** specscore:cross-repo-master

The canonical, navigable link is the child's Parent ref (child → master); composition is single-parent (a tree) in the MVP. Lint owns reference integrity per rule P-005: same-repo parents are resolved and checked for acyclicity; cross-repo <repo-slug>:<plan-slug> parents are validated syntactically only — the linter never scans sibling repositories, so a cross-repo parent is a best-effort, unresolved reference (like an external link). Cross-repo back-link maintenance and execution ordering across the tree are out of scope for this model and belong to the consuming skills.

REQ: cross-repo-parent-ref

A plan MAY declare a single **Parent:** <plan-ref> header field naming the master plan it is a sub-plan of. The value is a same-repo plan slug or a cross-repo <repo-slug>:<plan-slug> reference. A plan with no **Parent:** field is a root plan. Composition is single-parent in the MVP: a plan MUST NOT declare more than one parent. Reference validity (same-repo resolution and acyclicity; cross-repo syntactic-only checks) is enforced by specscore spec lint rule P-005, not by this document.

Coordination branch

A plan document is a single file that many parallel actors -- human or AI agent, each often on their own feature branch or in their own git worktree -- read and want to move forward at the same time. Without an agreed rule for where the plan document itself is mutated, two actors editing the same plan on different branches (adding tasks, walking a status) collide when their branches merge, and the collision has to be untangled by hand (e.g. two independently numbered ### Task 16: blocks landing from two different feature branches).

The Coordination branch is that agreed rule, declared once in the plan's own header:

**Coordination:** specscore/specscore-cli@main

<owner>/<repo> is a GitHub owner/repository pair; <branch> is the branch name (which MAY itself contain /, e.g. feature/plan-coordination-branch). When present, every mutation to this plan document -- task status walks, new tasks, task renumbering, plan-status transitions, or any other edit to the file -- is authoritative only on that declared repo/branch. A plan with no **Coordination:** field carries no such restriction: it may be mutated from anywhere, exactly as before this field existed.

The field draws a line between two kinds of truth that otherwise get conflated on a feature branch:

• Feature branches carry implementation. Code changes, task completion evidence, everything a plan's tasks describe building.
• The coordination branch carries plan truth. The plan document's own structure and status.

An actor implementing a task on feature/some-task never needs to also own the authoritative copy of the plan file -- their task-completion report is applied on the coordination branch (directly, or via whatever routing the consuming tooling uses), rather than mutating a parallel copy of the plan that later has to be reconciled by hand.

A merge conflict in a plan file that declares **Coordination:** is therefore a signal, not a chore: it means the separation was violated -- some actor mutated the plan document on a branch other than the declared one. The fix is to redo the mutation on the coordination branch (or to fix the tooling that let it happen elsewhere), not to hand-merge the conflicting hunks as if this were an ordinary content collision.

Enforcement of the declared repo/branch -- checking the current invocation against it, refusing a mismatched mutation, and the override mechanism for exceptional cases -- is a CLI concern (specscore-cli), not this specification: this document defines only the field's syntax and intended meaning. See specscore-cli's plan change-status/reconcile and task change-status Features for the enforcement contract.

REQ: coordination-branch-format

A plan MAY declare a single **Coordination:** <owner>/<repo>@<branch> header field. <owner>/<repo> MUST be a GitHub owner/repository pair (no / within either component); <branch> MUST be a non-empty git ref name (which MAY contain /). A plan with no **Coordination:** field is unrestricted. The reference is validated syntactically only by specscore spec lint (lint rule P-010), mirroring the cross-repo precedent of cross-repo-parent-ref and the implementation-commit-provenance ref format: the linter never resolves or scans the named repository, and never checks whether the branch exists.

REQ: coordination-branch-semantics

When a plan declares **Coordination:**, all mutations to that plan document -- task status transitions, new tasks, task renumbering, plan-status transitions, and any other edit to the file -- are authoritative only on the declared <branch> of the declared <owner>/<repo>. Feature branches (and worktrees derived from them) carry implementation; the coordination branch carries plan truth. A merge conflict in a plan file that declares **Coordination:** indicates this separation was violated (a mutation landed on a branch other than the declared one), and MUST be treated as a process violation to fix at the source -- not as an ordinary merge chore to resolve hunk-by-hunk.

Status rollup

Once a plan is Approved, its execution-band status is derived from the rollup of its task statuses. This is what lint --fix maintains; it never runs while the plan is in a prep state (Draft/In Review/Approved are human-owned).

Precedence is top-to-bottom: Failed wins over Executing, which wins over Blocked, which wins over Implemented.

REQ: status-rollup

When a plan is Approved or in an execution-band status, specscore spec lint --fix MUST derive the plan's execution-band status from the rollup of its task statuses per the precedence above. The rollup reads task status only — it MUST NOT write task status, and MUST NOT overwrite a human-authored prep (Draft/In Review/Approved) or disposition (Withdrawn/Superseded) status.

Task count

A plan carries a derived count of its tasks, surfaced in frontmatter so external tools can size a plan without parsing its body.

REQ: tasks-count

A plan MUST carry a derived tasks_count recording the number of its direct child tasks. The value is maintained by specscore spec lint --fix and surfaced in the plan's frontmatter per the artifact-frontmatter-convention feature. Authors MUST NOT hand-maintain tasks_count; lint reconciles it from the actual task children.

Tasks and dependencies

Tasks whose Depends on is none may execute in parallel. The dependency graph determines the critical path.

For complex plans, an optional Dependency graph section visualizes the parallelism:

graph LR
    A["Task 1"]
    B["Task 2"]
    C["Task 3"]
    D["Task 4"]
    E["Task 5<br/>(independent)"]
A --&gt; B
B --&gt; C
B --&gt; D</pre></div>

**Status:** complete
**Implemented-by:** sneat-co/chess@cfabf5e
**Note:** shipped to production, verified live
**Evidence:** cfabf5e, https://chessraiders.com/board/

**Effort:** S | M | L | XL
**Impact:** low | medium | high | critical

## Plans

| Plan                                                                  | Status    | Author | Approved   |
|-----------------------------------------------------------------------|-----------|--------|------------|
| [chat-feature](../../plans/chat-feature.md)                           | Draft     | @alex  | -          |
| [user-auth](../../plans/user-auth.md)                                 | Approved  | @alex  | 2026-03-15 |
| [add-batch-mode](../../plans/add-batch-mode.md)                       | In Review | @alex  | -          |

graph LR
    A["Trigger<br/>(spec approved)"]
    B["Author<br/>plan"]
    C["Review &<br/>approve"]
A --&gt;|human or&lt;br/&gt;AI agent| B
B --&gt;|submit| C</pre></div>

graph LR
    A["Draft"]
    B["In Review"]
    C["Approved"]
A -->|submit| B
A -->|approve| C
B -->|revisions<br/>requested| A
B --&gt;|approve| C</pre></div>

spec/plans/{plan-slug}/
  README.md             <- the plan
  reports/
    README.md           <- deviation report

# What's Next

**Generated:** 2026-03-24
**Mode:** incremental | full

## Completed Since Last Update

- [chat-infrastructure](chat-feature/chat-infrastructure/) -- completed 2026-03-20

## In Progress

- [hero-scene](hero-scene/) -- 2/4 tasks done, no blockers

## Recommended Next

1. **[chat-workflow-engine](chat-feature/chat-workflow-engine/)** -- Impact: high,
   Effort: M. Unblocked by chat-infrastructure completion. Advances the
   highest-impact plan.
2. **[agent-skills-framework](agent-skills-framework/)** -- Impact: medium, Effort: L.
   No blockers, independent of current momentum.

### Reasoning

Brief AI explanation of prioritization -- dependency unlocks, ROI ratio,
momentum, competing priorities.

## Open Questions

(ambiguities the AI surfaced during analysis)