Spec Phase Orchestration

Spec Phase Orchestration

When to invoke

• Starting a new project and deciding which documents the spec phase produces.
• Multiple documents / sections are in flight and you need to decide the order of progress.
• User asks "design or foundations first", "can we proceed with prerequisites unresolved".

Default decisions

5 files + meetings/ directory

<repo>/
├── README.md                  # Project entry point
├── docs/
│   ├── foundations.md         # Engineering substrate (language version, modules, CI, L10n, secrets)
│   ├── design.md              # Product spec §What + technical design §How (unified)
│   ├── plan.md                # TDD-ordered checklist
│   └── methodology.md         # Claude agent application practices (living doc)
└── meetings/
    └── {YYYY-MM-DD}_{topic}.md

Default: these live in the same repo as the code. A separate <project>-spec repo is a deviation for teams that need spec review gated independently of the code repo — not the default.

Don't split further:

• No separate spec.md / rfc.md / tasks.md (folded into design.md / plan.md)
• No adr/ directory; major decisions land directly in design.md or foundations.md (open one only if real need arises)

Progression order

foundations.md §1..§N (one section at a time) →
design.md §What (product spec) →
design.md §How (technical design) →
plan.md (TDD-ordered) →
implementation phase begins

Rule: don't write §How before design.md §What passes; don't write implementation code before plan.md passes.

Section-by-section approval

• The Leader advances one section at a time, waiting for user / review approval before moving on.
• Multiple sub-agent rounds may happen within a single section (see subagent-review-cycles).
• Section order is non-skippable: §What before §How, §1 before §2.

Prerequisite checklist (Unconfirmed / Resolved gates)

Any proposal depending on external tools / APIs / third-party packages must include a prerequisite checklist:

**Prerequisites**:
- [ ] Behaviour of Apple `XYZAPI.foo()` is consistent across iOS 26 and 25 — **Unconfirmed** (verified in plan.md step N)
- [x] ~~Xcode Cloud hook naming~~ — **Resolved** (Code Review round N, date): adopt `ci_post_clone.sh`

• Unconfirmed items block Leader approval — the section stays DRAFT until each item is Resolved.
• Resolved items are checked off with their decision basis + date.

No implementation code before design + plan approved

• Before design.md §What + §How pass and plan.md is written and approved, no implementation Swift code is written.
• Exception: a pure exploratory spike — must be logged under meetings/ as a spike; its output doesn't land on main.

Backlog sections

Every living doc carries a §Backlog; route stray ideas there by topic — see backlog-routing-by-topic.

Rationale

• 5 docs + meetings dir is the "enough to record, not redundant" sweet spot for solo / small teams; 8 files is over-structured, 4 lacks room for foundations / methodology.
• Section-by-section avoids the high cost of "send the whole doc back".
• Prerequisite gates force "assumptions" to become "items to verify"; CLI trial-and-error is not the default answer.
• Spec-first: "no spec, no code" is a fundamental premise of AI agent collaboration (otherwise prompts are vague and output diverges).

Deviation considerations

• Tiny utility / 1-day project: keep only README.md + meeting log; inline the design in the README.
• Adding a feature to an existing codebase: skip foundations.md; lean on the existing conventions.
• Multi-person collaboration: plan.md may split into plan/<feature>.md, but keep a master plan listing the dependencies.
• Full outsourcing / contractor: use an RFC + tasks split instead; this skill is a solo / small-team default.

Verification checklist

• 5 docs + meetings dir structure in place (README + 4 docs + meetings dir).
• design.md contains §What and §How; §How is only filled after §What passes.
• foundations.md sections carry Status (DRAFT / FINAL / OBSOLETE) + Open items (if any).
• plan.md steps are TDD-ordered (test step precedes implementation step).
• Every prerequisite item is explicitly marked Unconfirmed / Resolved.

Related skills

• backlog-routing-by-topic: rules for placing stray ideas.
• subagent-review-cycles: round structure inside spec sections.
• leader-developer-handoff-contract: dispatch contract when handing sections to a sub-agent.
• session-to-meeting-log: persisting each spec session.