flow-spec

name	flow-spec
description	Create an approved spec and self-reviewed implementation plan. Invoke with /flow-spec before multi-step work.
disable-model-invocation	true
metadata	{"flow":{"command":"/flow-spec"}}

Flow Spec

Triggered by: /flow-spec

Create a clear spec (user-approved) and implementation plan (AI self-reviewed). The orchestrator does not implement plan tasks — no edits to src/, tests/, or app code for Task N. After branch confirm, auto-continue dispatches implementer subagents per plan-execution.md (same session; no /flow-execute handoff).

If a brainstorm brief exists at docs/flow/brainstorms/, read it first and carry forward agreed direction.

Situation	Action
Requirements still fuzzy	Tell the user to invoke /flow-brainstorm — do not write a spec yet
Brief scope small and bounded (≤3 files, one concern)	Read flow-patch/SKILL.md via path resolver and follow patch — do not write a spec or tell the user to invoke /flow-patch
Same-topic continuation after brainstorm handoff (user picked 1 or 2 for spec on §7 menu)	Continue Phase A here — session gate skipped per §4
User invoked /flow-spec cold with no brief	Normal Phase A flow

Phase A — Spec

1. Explore context

Read relevant files, docs, recent commits, and any brainstorm brief. Understand existing patterns.

2. Clarify (one question at a time)

Ask until there are zero open questions about:

• Purpose and success criteria
• Scope and explicit out-of-scope
• Constraints and non-goals

Prefer multiple-choice when possible. One question per message.

When offering A/B/C/D options, mark exactly one with (Recommended) and add one sentence why. See flow-brainstorm for format.

If requirements are still fuzzy after a few questions, redirect to /flow-brainstorm.

3. Propose design

When scope is clear:

• Present 2–3 approaches with trade-offs if genuinely ambiguous; otherwise present one recommended design
• Cover architecture, components, error handling, testing approach
• Present the design, then send the design gate below — do not write the spec in the same message

Design gate (required)

After presenting the design, send only this gate — do not combine with writing the spec, naming a spec path, session gate, STATE updates, or plan outline:

Does this design work for you?

1. Approve design — I'll write the spec
2. Request changes — tell me what to revise in the design
3. Stop — no spec or implementation

User-facing option 1 — only: next step is writing the spec file. Do not add (no code) or implementation-model parentheticals in the gate menu.

Orchestrator (not in the gate): no production code until branch/workspace after the spec path; spec and plan gates still apply.

Stop until the user picks 1, approves the design explicitly, or requests changes (2). Option 3 ends spec work. If they request changes, revise the design proposal and re-send the design gate.

"Yes" / "approve" / "proceed" after this gate counts as design approval only — not spec approval, plan writing, branch/workspace confirmation, or permission to run /flow-execute.

After design approval: proceed to §4 (session gate if needed), then §5 (write spec).

4. Session gate (required)

Read and follow flow-shared/references/session-gate.md (resolve via path resolver in flow/SKILL.md).

Before writing the spec file or updating STATE: if STATE shows active unrelated work, send the session gate message and stop. Do not save the spec or write STATE in the same turn as the gate.

Same-topic handoffs from an approved brainstorm brief on this initiative → proceed without gate.

5. Write spec

Save to:

docs/flow/specs/YYYY-MM-DD-<topic>.md

Required sections:

# [Topic]

## Goal
## Success Criteria
## Scope
## Out of Scope
## Design
## Testing Approach
## Open Questions

Open Questions must be empty or say "None" before proceeding.

Testing Approach: Distinguish automated vs manual verification. For behavior changes, name what gets RED-GREEN tests. For pure presentation or visual work, say no new unit tests and list manual/browser checks. Follow flow-shared/references/tdd-red-green.md — test behavior, not markup presence or CSS values.

6. Spec self-review (structural)

Orchestrator-only audit: success-criteria mapping and path/tree consistency. Do not proceed to §6.5 while any §6 blocking check fails.

Completeness, TBD/TODO in requirements, non-path contradictions, clarity, scope, and YAGNI → §6.5 document reviewer (not §6).

Record self-review output internally (review notes, not necessarily in the spec file):

Status: Ready | Blocked
Blocking: [list, or none]
Advisory: [list, or none]

Calibration: Unmapped success criteria and path mismatches are blocking. Wording polish and uneven section depth are advisory — note but do not block.

Success criteria audit

• List every bullet under ## Success Criteria as a numbered item
• For each item, cite the spec section (heading + path/tree/table/command/paragraph) that satisfies it
• If any success criterion has no supporting section, add one or remove the criterion

Structure & path consistency (required when spec mentions trees, paths, moves, mirroring, or file layout)

Render two columns using the spec's documented convention (colocated tests beside source, mirrored root such as tests/ ↔ src/, hybrid, or N/A for the paired column if the spec defines none):

Source / runtime tree	Test / mirror tree (if applicable)
...	...

Then verify:

• Segment-for-segment alignment per the documented rule — file names may differ (Foo.tsx vs Foo.test.tsx; colocated tests share directory segments)
• If success criteria or scope use mirror, reflect, or match structure, paired paths must preserve intermediate folders (common/, feature namespaces, private child folders) — not flatten them unless documented
• Import conventions in Design must not contradict the tree when the spec mandates import style
• Allowed skips must be named in Success Criteria or Design (e.g. "index.ts has no test counterpart")

Contradiction stop rule

If Success Criteria, Design tree, and Testing Approach disagree on paths or layout, do not proceed to §6.5 or §7 until resolved. Resolve by picking one rule and updating all sections, or ask the user one multiple-choice question:

• A) Strict mirror (paired tree matches source tree segment-for-segment) (Recommended for move/refactor specs)
• B) Flattened paired tree (document explicit exceptions in Success Criteria)
• C) Other (user specifies)

Document the chosen rule in Design or Testing Approach so the plan cannot interpret it two ways.

6.5. Spec document review (subagent, required)

After §6 structural self-review is Ready, dispatch a spec document reviewer for planning-quality checks (TBD/TODO, completeness, clarity, scope, YAGNI, non-path contradictions) before the user spec gate.

1. Read flow-shared/prompts/spec-document-reviewer.md (resolve via path resolver in flow/SKILL.md)
2. Dispatch with the spec file path (docs/flow/specs/...)
3. If Issues Found: fix the spec inline → re-run §6 blocking checks affected by the edit → re-dispatch until Approved
4. If Approved: proceed to §7

Forbidden: Sending the §7 spec gate while document review is still Issues Found or not yet run.

Forbidden: Skipping this subagent because §6 structural audit passed — fresh context catches planning blockers the author rationalizes past.

Do not expose document reviewer output (Status, Issues, Recommendations) in the user-facing spec gate message.

7. Spec gate (required)

Run §6 structural self-review and §6.5 document review. Do not proceed to §7 while either is blocked or Issues Found. Then present the spec path and send only this gate — do not combine with plan writing, STATE updates, or execute/workspace setup:

Spec ready at docs/flow/specs/....

1. Approve spec — I'll write and self-review the plan, then pause for branch/workspace
2. Request changes — tell me what to revise
3. Stop — no plan or implementation

User-facing option 1 — only: plan next → branch/workspace pause. Do not add parentheticals about subagents, plan review, or /flow-execute in the gate menu.

After branch confirm (orchestrator, not in the gate): implement plan tasks via subagents in this session — no separate plan user gate, no /flow-execute handoff. Do not use internal labels (e.g. "Phase B") or bare "no code" in the gate — users otherwise think approval ends at documentation only.

Do not expose internal self-review checklist names (criteria mapping counts, structure trees, Status/Blocked) in the gate message — the user reviews the spec content, not the agent's audit worksheet. Do not ask the user to find contradictions you should have caught in self-review.

Stop until the user picks 1, approves the spec explicitly, or requests changes (2). Option 3 ends spec work. If they request changes, update spec and re-run §6 and §6.5 before re-sending the gate.

"Yes" / "approve" / "proceed" after this gate counts as spec approval only — not plan approval (plan has no user gate) or branch/workspace confirmation. If the user bundles workspace preferences (e.g. "yes, use a worktree when we implement"), note them for the branch gate after plan — do not create branches or worktrees during Phase B.

After spec approval: update docs/flow/STATE.md with spec path and phase: spec, then proceed to Phase B.

---

Phase B — Plan (no user approval)

Runs automatically after spec approval.

1. Scope check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

If splitting is needed, stop and get user agreement on which subsystem this plan covers before writing tasks.

2. Write plan

Write for an implementer with zero codebase context — exact paths, full code, exact commands, expected output. DRY. YAGNI. TDD. Frequent commits.

Save to:

docs/flow/plans/YYYY-MM-DD-<topic>.md

Header:

# [Topic] Implementation Plan

> **Execution:** Subagents per `flow-shared/references/plan-execution.md`. TDD required.

**Goal:** [one sentence]
**Spec:** docs/flow/specs/YYYY-MM-DD-<topic>.md
**Architecture:** [2-3 sentences]

---

3. File structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

• Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
• Prefer smaller, focused files over large ones that do too much.
• Files that change together should live together. Split by responsibility, not by technical layer.
• In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure — but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

4. Task structure

Each task: exact file paths, complete code in steps, exact commands with expected output, TDD steps (write failing test → verify fail → implement → verify pass → commit).

Bite-sized steps (2–5 minutes each). Checkbox syntax: - [ ]. Each TDD step is its own checkbox — do not combine RED/GREEN into one step.

Every task uses this shape:

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file`
- Modify: `exact/path/to/existing`
- Test: `exact/path/to/test`

- [ ] **Step 1: Write the failing test**

[complete test code]

- [ ] **Step 2: Run test to verify it fails**

Run: `[exact command]`
Expected: FAIL — [reason]

- [ ] **Step 3: Write minimal implementation**

[complete code or precise edit instructions with code]

- [ ] **Step 4: Run test to verify it passes**

Run: `[exact command]`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add ...
git commit -m "..."
```

Plan failures (never write these):

• TBD, TODO, "implement later", "fill in details"
• Final task named "Final verification", "Run full test suite", or verification-only — verify auto-runs after all implementation tasks via plan-execution.md §4; do not duplicate in the plan
• "Add tests", "add appropriate error handling", "add validation", "handle edge cases"
• "Write tests for the above" without actual test code
• "Similar to Task N" without repeating code
• Steps that describe what to do without showing how (code blocks required for code steps)
• Steps without actual code or commands
• References to types, functions, or methods not defined in any task

5. Plan self-review loop

Repeat until all pass. Record Status: Ready | Blocked with blocking vs advisory issues (same blocking/advisory calibration as spec §6 structural self-review).

Check	Question
Spec coverage	Every spec requirement maps to a task?
Success criteria coverage	Every Success Criteria bullet maps to a specific task step with an expected path or artifact (not just "update tests")?
Out-of-scope guard	Any task step touches files, systems, or behavior listed under Out of Scope (or beyond Scope)?
Tree parity	If spec defines source + paired trees, plan task paths (moves, creates, deletes) match the spec trees segment-for-segment; flag any flatten/skip?
Spec diagram authority	Plan paths match the spec's canonical tree. If the plan improves on the spec, update the spec first — plan must not silently diverge
Placeholders	Any vague steps?
Consistency	Names/signatures match across tasks?
Undefined references	Any type, function, or method used but not defined in an earlier task?
TDD	Behavior changes have RED-GREEN steps? Presentation-only tasks skip new tests per tdd-red-green.md — not placeholder existence tests?
Granularity	Steps are 2–5 minute actions?
Verify in plan	No task whose sole purpose is final/full verification — that is auto-run after tasks in execute (plan-execution.md §4)?

Structure refactor plans: Before handoff, produce a short mapping table in the plan or review notes:

Success criterion	Plan task	Expected path(s)
...	Task N	exact/path/

If any row is missing or paths disagree across spec/plan, loop plan self-review again.

Fix issues inline. Do not ask user to approve the plan.

If a plan gap requires a spec decision, stop and ask the user to update the spec.

6. Auto-continue

When plan self-review passes:

1. Update docs/flow/STATE.md: phase: planned, record spec: and plan: paths
2. Read and follow flow-shared/references/plan-execution.md (resolve via path resolver in flow/SKILL.md) from step 1 (branch gate)

You may note the plan path in one short line, then send only the branch/workspace gate — do not bundle Task 1, git mutations, or subagent dispatch with the gate question.

Hard gate — before branch confirm: no git checkout -b, worktrees, artifact commit, Task 1, TodoWrite, subagents, or production code.

Hard gate — after branch confirm: Follow plan-execution.md steps 2–5. Subagents only for every plan task — orchestrator must not create or edit production/test source files for Task N (no inline TDD "to save a turn", even when Task 1 is tests-only or the plan already contains the code). Dispatch implementer with full task text; then spec and correctness reviewers per plan-execution.md §4.

Hard gate — after plan: Forbidden: Run /flow-execute handoff or stopping for the user to invoke /flow-execute. After branch confirm, continue plan-execution steps 2–5 without pausing.

Red flags — never

• Use freeform "reply approve" at design time — send the numbered design gate (§3); spec gate (§7) is a separate step after the spec file exists
• Bundle spec writing, spec path preview, STATE update, or session gate with the design gate message — send design gate only; wait for approval before §4–§5
• Skip §6.5 spec document reviewer because §6 structural audit passed or the spec "looks ready"
• Send the §7 spec gate before document reviewer returns Approved
• Skip design gate because clarifying questions are done or the design looks solid
• Stop with Run /flow-execute after plan — auto-continue to plan-execution step 1; branch gate is the only post-approval pause
• Start Task 1, inline code, or subagents before branch confirm — see plan-execution.md
• Implement plan tasks inline after branch confirm — dispatch implementer subagent; reading implementer.md does not license orchestrator edits to src/ or tests/
• Use "no code", "production code only", or "domain/tests aren't production" to justify orchestrator TDD — task work is subagent-only per plan-execution.md
• Bundle plan outline, STATE update, worktree, or Task 1 with the spec gate message — send spec gate only; wait for approval before Phase B
• Skip spec gate because the user asked for implementation preferences in the same message
• Orchestrator implements plan tasks (inline code in src/, tests/, or app paths) — subagents only after branch confirm