/write-executable-plan

name: write-executable-plan
description: Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects "TBD", "TODO", "add error handling", "similar to Task N".
model: inherit
color: green
tools: Read, Grep, Glob, Bash, Write

Write Executable Plan

> Bite-sized plans for parallel agents. No placeholders. No vague steps.

When to use

• A PRD from `/plan feature` exists but you need a step-by-step implementation plan
• A `/brainstorm` design is approved and you want to skip the PRD layer
• Multiple agents will execute the plan in parallel and need conflict-free task boundaries
• The work is complex enough that describing it to an agent loses fidelity

When NOT to use

• Trivial 1-file changes (just do them; no plan needed)
• Pure exploration (use `/brainstorm` instead)
• Bug investigation (use `/debug` instead)
• The source PRD is vague or unapproved (get PRD approval before planning execution)

Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. </HARD-GATE>

Phase 1: Source Selection

Accept ONE of the following inputs (in order of preference):

1. **PRD path** — `docs/prd/YYYY-MM-DD-<feature>.md` produced by `/plan feature` 2. **Design spec path** — `docs/specs/YYYY-MM-DD-<slug>-design.md` produced by `/brainstorm` 3. **Inline description** — user provides a free-text description; prompt for elaboration via AUQ before proceeding

If no source is provided and `$ARGUMENTS` is empty, ask via AUQ:

AskUserQuestion({
  questions: [{
    question: "Which source should this plan be based on?",
    header: "Plan Source",
    options: [
      { label: "Existing PRD (Recommended)", description: "Point me to docs/prd/YYYY-MM-DD-<feature>.md — most precise decomposition." },
      { label: "Design spec from /brainstorm", description: "Point me to docs/specs/YYYY-MM-DD-<slug>-design.md — skips formal PRD." },
      { label: "Describe inline", description: "Paste or describe the feature — I will ask follow-up questions before planning." }
    ],
    multiSelect: false
  }]
})

Read the source file and extract:

• **Feature title** (for filename slug and plan header)
• **Acceptance criteria** or equivalent (drives Task decomposition)
• **Explicit out-of-scope items** (excludes from plan)
• **File inventory** if present (seeds the whole-plan Files block)

Phase 2: Decomposition

Break the source into Tasks. Each Task MUST satisfy all of these constraints:

• **Single owner** — one agent role (e.g., `code-implementer`, `test-writer`), not "the team"
• **Bounded file set** — lists every file it creates, modifies, or tests; no file appears in two Tasks
• **Independently testable** — after Step 4 the task stands on its own; no cross-task dependencies in the test command
• **2-5 minute wall-clock estimate** — if the estimate exceeds 5 minutes, split the Task; if two Tasks share a file, merge or re-scope

Before writing Tasks, output a brief decomposition plan in plain text:

## Decomposition (draft)
- Task 1: <title> — <owner> — ~<N> min — Files: <list>
- Task 2: <title> — <owner> — ~<N> min — Files: <list>
...

If any task's file set overlaps another, surface the conflict and resolve it before writing Steps.

Phase 3: Step Authoring (per Task)

Each Task gets exactly 5 steps in this order. All 5 steps are mandatory.

Step 1: Write the failing test

**EARS seam:** If the source PRD/spec carries an `## Acceptance Criteria (EARS)` (or `## 3.A`) section, apply the EARS→vitest 1:1 mapping below to emit per-clause test stubs. If no EARS section is present, fall back to manual derivation from prose.

EARS → vitest mapping (1:1)

| EARS pattern | vitest construct | example skeleton | |---|---|---| | **Ubiquitous** ("The S shall R.") | invariant `it()` — no setup branching | `it('S shall R', () => { /* assert invariant */ })` | | **State-driven** ("While P, the S shall R.") | `describe()` for state context, nested `it()` for assertion | `describe('while P', () => { it('S shall R', () => { /* enter P; expect R */ }) })` | | **Event-driven** ("When T, the S shall R.") | arrange/trigger/expect inside `it()` | `it('when T, S shall R', () => { /* arrange; trigger T; expect R */ })` | | **Optional feature** ("Where F, the S shall R.") | `it.skipIf(!F)` (vitest conditional) | `it.skipIf(!F)('where F, S shall R', () => { /* expect R */ })` | | **Unwanted behaviour** ("If C, then the S shall R.") | error-path `it()` with negative assertion or `toThrow()` | `it('if C, then S shall R', () => { /* induce C; expect R */ })` |

Reference test exemplifying this pattern: `tests/lib/wave-executor/persona-gate-hook.test.mjs` (shipped at #481).

Follow `.claude/rules/testing.md` § "Test Quality — False-Positive Prevention": one meaningful assertion per `it`, behaviour not implementation, no branching, hardcoded expected values.

Provide:

• Exact file path (absolute from project root)
• Complete, runnable test code — no `// ...`, no placeholders, no `// implement later`
• One sentence explaining why this test verifies the intended behavior

The test MUST fail before Step 3 is applied. If the behavior already exists and cannot fail, pick a harder assertion or a new edge case.

Step 2: Run the test to confirm it fails

Provide:

• Exact command (e.g., `npm test -- tests/unit/my-module.test.mjs`)
• Expected terminal output — the specific assertion failure line that proves the test exercises missing code (not