spec-phase-orchestration · diff
git:20260909.b95c02f to git:20260911.e4022a8
1 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: spec-phase-orchestration
- description: The pre-implementation document pipeline — 5 files + `meetings/` directory (README.md + docs/design.md + docs/foundations.md + docs/plan.md + docs/methodology.md + meetings/), section-by-section approval (§What before §How), prerequisite checklist with Unconfirmed / Resolved gates, "no implementation code before design.md and plan.md approved" rule. Invoke when deciding doc structure for a spec-first project, or when asked "which documents go in the spec phase".
+ description: Run the spec-first document phase of a project and gate implementation on it. Use when starting a project that needs a spec before code, deciding which documents the spec phase produces and in what order, choosing whether a section may advance while a prerequisite is unconfirmed, judging whether implementation code may start yet, or when asked "design or foundations first", "which documents go in the spec phase", "can we code before plan.md is approved". Does NOT own where stray ideas are parked (backlog-routing-by-topic) nor the per-section review rounds (subagent-review-cycles).
---
# 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:
```markdown
**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.