Slash command: Write Plan

---
description: Write a Superpowers plan from an existing spec, split into per-task files written by parallel subagents
argument-hint: [path to the spec/design doc, or the feature it describes]
allowed-tools: Read, Glob, Grep, Edit, Write, TodoWrite, Task, Bash(git status:*), Bash(git diff:*)
---

Use the Superpowers writing-plans skill to produce an implementation plan for: $ARGUMENTS

Brainstorming is already done. Do NOT invoke the brainstorming skill, do not re-open
requirements, and do not ask clarifying questions. Read the spec/design doc and plan
from it as written. If the spec is silent on something, make a reasonable choice and
record it under Global Constraints in 00-overview.md rather than stopping to ask.

Follow the Superpowers writing-plans workflow:

- Map which files get created/modified BEFORE defining tasks
- Structure every task for TDD (red -> green -> refactor)
- Each step must be a single concrete action, ~2-5 minutes

This command runs in three phases. YOU (the orchestrator) own phases 1 and 3 alone.
Only phase 2 is parallel. Never parallelize the index or the review.

## Plan location - let Superpowers decide, but write a DIRECTORY

Do NOT hardcode a plan path. Use whatever location and filename the Superpowers
writing-plans skill would use by default. Then apply one override:

Where the skill would write a single plan file:

    <its-plan-dir>/<its-plan-name>.md

instead create a directory of the SAME name and write the plan inside it:

    <its-plan-dir>/<its-plan-name>/
    ├── 00-overview.md
    ├── 01-<kebab-noun-phrase>.md
    ├── 02-<kebab-noun-phrase>.md
    └── 03-<kebab-noun-phrase>.md

The skill's own docs state that user preferences for plan location override its default.
This is that preference: same directory, same plan name, one file per task.

Before writing, state the resolved plan path you are using.

## Phase 1 - Index and contract (orchestrator only)

All sizing and interface decisions happen HERE, once. After 00-overview.md is
written, task boundaries and cross-task interfaces are final - subagents in phase 2
fill them in, they never redraw them.

A task is one test cycle (writing-plans "Task Right-Sizing"): a reviewer could
reject it while approving its neighbors. Draw task boundaries so that each task:

- creates or modifies at most 3 files (tests excluded)
- has at most 6 steps: the 4 TDD steps (failing test, run-fail, implement,
  run-pass) plus at most 2 more. There is no commit step - see "No commit steps".
- ends with an independently testable deliverable

If a candidate task needs more than that, it is two tasks. Give both their own
number in the index (03, 04). Never use sub-folders or 03a/03b suffixes -
renumbering before anything is written is free; splitting afterwards is not.

Naming: the plan directory name comes from the skill. INSIDE it, files are zero-padded
two digits. Numbers give ORDER, not scheduling - dependencies live inside the files.
Slug is a short noun phrase, no verbs. Filenames under ~40 chars.
Never encode dependencies or waves in filenames.

Write 00-overview.md (see its section below) in a single Write call. Because subagents
never see each other's work, the Interface Contract in it must be complete and exact:
every name, parameter, type and return value that crosses a task boundary.
If you cannot write a signature yet, the task boundary is wrong - fix it now.

## Phase 2 - Fan out task files (parallel subagents)

Small plans: if the index has 3 or fewer tasks, skip fan-out and write the task
files yourself, one Write call per file, in index order. Then go to phase 3.

Otherwise:

1. Group tasks into batches of 2-4 ADJACENT tasks. Prefer keeping a task in the same
   batch as the task it Consumes from. Cap at ~5 batches; make batches larger
   rather than exceeding the cap.
2. Dispatch ALL batches in ONE message as parallel Task calls - there is a single
   wave. Ordering between tasks is irrelevant here because the contract in
   00-overview.md already fixes every interface.
3. Each subagent prompt must be self-contained and include:
   - the absolute paths to the spec and to 00-overview.md (tell it to read both first)
   - its assigned task file names, with their index rows copied verbatim
   - the full "Each task file" and "No commit steps" sections of this command, verbatim
   - the subagent rules below, verbatim

Subagent rules (paste into every subagent prompt):

- Write ONLY your assigned files. Do not create, read back, edit, rename or delete
  any other file in the plan directory, including 00-overview.md.
- Write each assigned file exactly once, in its own Write call. Do not split,
  merge or renumber tasks.
- Copy every Consumes/Produces signature verbatim from the Interface Contract in
  00-overview.md. Never invent, rename or extend a cross-task interface.
- You may read project source files to get exact paths and line ranges.
- If the contract is missing something your task needs, or is wrong, still write the
  file using your best reading, and report it - do not fix it yourself.
- Do not commit, stage or run any git command that changes state.
- Final message, nothing else:
  FILES WRITTEN: <list>
  CONTRACT ISSUES: <task file - what is missing or wrong, or "none">
  ASSUMPTIONS: <one line each, or "none">

## Phase 3 - Integrate and self-review (orchestrator only, once)

1. Confirm every file in the index exists. If a subagent failed or skipped one,
   write that file yourself - do not re-dispatch.
2. Resolve every CONTRACT ISSUE: decide the correct interface, update the contract in
   00-overview.md, then make targeted Edits in each affected task file.
   Fold relevant ASSUMPTIONS into Global Constraints.
3. Run the writing-plans self-review ONCE against the spec: spec coverage, step scan,
   type consistency across tasks, review focus, proportion. Type consistency is the
   check most likely to fail after fan-out: for every Consumes in a task, confirm the
   matching Produces exists with an identical signature.
4. Grep every task file for `commit` and `git`; any hit is a bug - delete the step.

Fix problems with targeted Edits in the file where they live. Do not re-review,
do not rewrite files wholesale, do not revisit task boundaries.

Length is not a metric. If a task file feels long, it contains code bodies.
Keep signatures, test names and assertions; drop the bodies
(writing-plans "Proportion" rule). Do not split it.

## 00-overview.md

Carries the Superpowers plan header and project-wide context ONLY:

- The required Superpowers agentic-worker header block (REQUIRED SUB-SKILL:
  superpowers:subagent-driven-development or superpowers:executing-plans)
- Goal: one sentence
- Architecture: 2-3 sentences
- Tech Stack: key technologies/libraries
- Spec: path to the spec/design doc this plan implements
- Global Constraints: project-wide requirements, exact values copied verbatim from the spec.
  Every task's requirements implicitly include this section.
- Review Focus: the failure modes the spec implies but no task's tests exercise,
  one line each; each one gets a test added to the task that owns the code
- Task index: | file | one-line goal | depends-on | files touched |
- Interface Contract: one row per cross-task interface -
  | name | exact signature (params, types, return) | produced by | consumed by |
  Signatures only, no bodies. This is the single source of truth task files copy from.

Do NOT restate task contents here. Keep it short.

## Each task file

Standard Superpowers task structure, one task per file:

- Depends on: (task numbers, or "none")
- Files:
  - Create: exact/path/to/file.py
  - Modify: exact/path/to/existing.py:123-145
  - Test: tests/exact/path/to/test.py
- Interfaces (omit any line that would be empty):
  - Consumes: what this task uses from earlier tasks (exact signatures, from the contract)
  - Produces: what later tasks rely on (exact names, params, types, from the contract)
- Steps: checkbox `- [ ]` syntax, TDD order (write failing test -> run, expect fail ->
  implement -> run, expect pass), each step a single 2-5 minute action.
  The last step of every task is "run tests, expect PASS". Nothing comes after it.
  Test steps carry the test as code with the spec's exact values. Code steps carry
  the exact signature and file; a body only for an algorithm the tests do not determine.
- Review checkpoint: at most 3 bullets on what the code-reviewer should verify

Each task file must be independently followable by someone who has read 00-overview.md
and nothing else.

## No commit steps

This overrides the writing-plans skill. Its task template ends with
"Step 5: Commit" and its overview says "Frequent commits". Do NOT follow that here.

- No task may contain a commit step, a `git add`/`git commit` command, a commit
  message, or any mention of committing, staging, pushing or branches.
- Do not replace it with a substitute ("save your work", "checkpoint here").
  The task simply ends at "run tests, expect PASS".
- Committing happens after implementation, outside the plan, and is not a
  concern of any task. Do not mention this policy inside the plan files either.

## Constraints

- Lint and format after making any file changes
- Do NOT commit anything while planning - not the plan, not any other files
- No two subagents ever write the same file; only the orchestrator edits after phase 2

When done, print:

- the resolved plan path
- the task tree with one-line goals
- how tasks were batched across subagents (or "written directly" for small plans)
- any contract issues raised and how you resolved them