Writing Plans

---
name: writing-plans
description: >
  MUST USE after design approval to decompose requirements into executable
  task plans with verification commands and TDD ordering. Triggers on:
  "write a plan", "break this down", "plan the implementation", after
  brainstorming approval. Routed by brainstorming as the next step.
---

# Writing Plans

Create an implementation plan another agent can execute with minimal ambiguity.

## Output Path

Derive the **topic folder** from the spec path (the derivation rule and the
folder shape are defined in the "Artifact Layout" section of
`skills/brainstorming/SKILL.md`): the spec must be
`<D>/specs/<file>` where `<D>` is a direct child of
`docs/superpowers-orchestrator/` at the repository root and `<D>`'s basename
matches `^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(-[a-z0-9]+)*$`. Then `<D>` is
the topic folder, its basename is `<date>-<slug>`, and `<slug>` is that
basename minus the date prefix.

Save to `docs/superpowers-orchestrator/<date>-<slug>/plans/<slug>.md`,
creating `plans/` if it does not exist.

- User preferences for plan location override this default.
- A spec that is **outside the layout** is handled by "Spec Outside the
  Layout" below — do not write a plan next to it.

## Spec Outside the Layout

A spec whose path is not `<D>/specs/<file>` — where `<D>` is a direct child
of `docs/superpowers-orchestrator/` at the repository root whose basename
matches the topic-folder shape defined in the "Artifact Layout" section of
`skills/brainstorming/SKILL.md` — gets **no plan written beside it**. The
`specs/` segment is required: the general derivation rule in that section
also accepts `<D>/plans/<file>`, but a *spec* sitting in a `plans/` folder is
outside the layout and gets the offer below, exactly as this task's "Does NOT
cover" note states. The invariant this protects: every plan lives in a topic folder
together with its spec.

1. Compute `<slug>` = the spec basename with `YYYY-MM-DD-`, `-design` and
   `.md` stripped, each only if present, then normalized by the "Slug" rule
   in the "Artifact Layout" section of `skills/brainstorming/SKILL.md` (the
   same normalization brainstorming applies to a topic name). Without it, a
   basename such as `MyFeature-design.md` yields a folder name that fails
   the layout check, and the offer below repeats on every run.
2. Name the expected location:
   `docs/superpowers-orchestrator/<today>-<slug>/specs/<slug>-design.md`. If a
   folder matching `docs/superpowers-orchestrator/????-??-??-<slug>/` already
   exists, reuse that folder instead of `<today>` (slug uniqueness). More than
   one match → stop and report the ambiguity; write nothing. If the reused
   folder already holds `specs/<slug>-design.md` or its
   `specs/<slug>-design-review-log.md` sidecar, stop and report the
   collision — a different spec already owns that slug — and move and write
   nothing.
3. State the reason the spec is outside the layout — wrong parent directory,
   or a folder name that does not match
   `^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(-[a-z0-9]+)*$` — next to the
   expected location, so a spec already in the right place but wrongly named
   is never described as a move onto itself.
4. Ask the user **once** whether to move the spec there.
   - **Yes:** `mkdir -p` the destination `specs/` folder first (`git mv` fails
     when the destination directory does not exist), then `git mv` the spec to
     `specs/<slug>-design.md` and — when it exists — its `-review-log.md`
     sidecar to `specs/<slug>-design-review-log.md`. A file git does not track
     yet (`git ls-files --error-unmatch <path>` fails — the normal state of a
     spec that was written and never committed) cannot be moved with `git mv`:
     move it with plain `mv` and `git add` the destination path instead. Use
     plain `mv` when the project is not a git repository. The sidecar is
     renamed together with the spec because the sidecar rule derives the log
     name from the document name: a sidecar that kept its old basename would be
     orphaned and a later spec review would start a new log. Then continue with
     the moved spec.
   - **No:** stop. No plan is written.

## Plan Header

```markdown
# <Feature Name> Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-orchestrator:subagent-driven-development (recommended) or superpowers-orchestrator:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
>
> **Body authority:** Exactly two things in this plan bind: the `**Global Constraints:**` block, and a block whose immediately preceding paragraph reads `**Exact content:** <reason>` where that reason names a pin this plan does not itself write or edit. Everything else is reference: fenced code blocks and block-quoted wording in task steps are reference implementations, and so is every other code block, every quoted wording, every header field, and this note itself — a finding against any of them is an ordinary fix, not a plan conflict, unless it contradicts a stated `**Contract:**` or a global constraint. A finding whose subject is this note's own wording is never a plan conflict: record it against the plan-writing skill at `skills/writing-plans/SKILL.md` and continue. That disposition covers the note's own text alone; a finding that this note contradicts something specific to this plan — one of its global constraints, say — is about that interaction and is triaged as an ordinary finding.

**Goal:** <single sentence>
**Spec:** `docs/superpowers-orchestrator/<YYYY-MM-DD>-<slug>/specs/<slug>-design.md` *(multi-doc-review reads this line to locate the spec on direct plan reviews; an old-layout path here would produce a plan whose spec is outside the layout)*
**Architecture:** <2-4 sentences>
**Tech Stack:** <languages/libraries/tools>
**Assumptions:** <list the key assumptions this plan rests on. For each, state what it excludes: "Assumes X — will NOT work if Y."> *(skip only if the plan contains zero conditional logic)*
**Global Constraints:** <rules that bind every task — version floors, dependency limits, naming and copy, exact values — copied verbatim from the spec. subagent-driven-development hands this block verbatim to every reviewer as its attention lens. Omit only if the spec truly has none; a missing block forces the SDD controller to re-derive constraints from the spec on every dispatch.>

---
```

## 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.

## 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 — you reason best about code you can hold in context at once, and your edits are more reliable when files are focused.
- 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.

## Task Rules

- Keep tasks independent when possible.
- Keep each step to one action (roughly 2-5 minutes).
- Use exact file paths.
- Include exact verification commands and expected outcomes.
- Use TDD ordering when code behavior changes.
- For ambiguous features, ask clarifying questions before finalizing the plan rather than guessing.

## Contracts and Literal Bodies

A **contract** is the set of properties an artifact must guarantee, stated
so that a check can falsify them. A **reference implementation** is a
concrete body (a code block or quoted text) that satisfies the contract:
it shows one way, it does not bind.

1. **State a contract for every governed artifact.** For every helper,
   function, command, or piece of wording a task introduces or modifies,
   state the contract in the task's `**Contract:**` field: the invariants
   that must hold and the verification (a runnable command or check) that
   would falsify them; for code artifacts also inputs and outputs. A task
   that creates or modifies several artifacts holds one entry per artifact
   in the same field (a list) — or is a candidate for splitting.
   Procedural step blocks that operate the pipeline rather than build
   the feature — the Step 5 commit command, `Run:` verification lines
   — need no contract entry; rule 3's default covers them. The test is
   intrinsic to the block: it asks what the block itself does to the
   working tree, never what any list elsewhere in the task records. A
   block is procedural when it creates, modifies, or deletes no file
   in the working tree, and runs at least one command, every command it
   runs being a pipeline command — the two canonical forms are the Step 5
   commit block and a verification `Run:` line, though a `Run:` line is a
   procedural form only when the command it runs writes no working-tree
   file; the Step 5 commit block qualifies because it writes the git index
   and git objects but no working-tree file. This is the one test for "procedural" used
   everywhere in the plan you are writing and in review. When it is
   unclear whether a block meets this test, treat the block as not procedural
   — ambiguity produces a contract entry, never a silent exemption. Two
   contract shapes exist — code artifact and wording artifact — shown in the
   examples below.

2. **Pin an interface only when something outside the plan depends on
   it.** An interface (signature, flag set, file format) is pinned in the
   contract only when something *outside the plan* already depends on it.
   Stating inputs and outputs in the `**Contract:**` field does not pin
   them: a concrete signature written there is descriptive — part of the
   reference implementation — unless the external-dependency condition
   holds, and a fix may amend the signature together with the contract's
   inputs/outputs wording as one ordinary fix.

3. **Bodies are reference implementations by default.** Code blocks and
   quoted wording in task steps are reference implementations. The
   implementer follows them as written; a later review finding against
   such a body is an **ordinary fix** so long as the stated contract still
   holds. Only a change that breaks or amends the contract itself is a
   plan conflict.

4. **Mark exact content explicitly.** A block is binding byte-for-byte
   only when the paragraph immediately preceding the fenced block or block
   quote it pins begins with `**Exact content:** <reason>`. The reason
   may wrap across more than one line; what matters is that the marker
   starts the paragraph, not that it sits on the single line right above
   the fence. The reason must name the
   *external* pin: a pre-existing test asserting the string, another file
   that must already match byte-for-byte, or user-approved copy — and a
   user-approval reason must cite where the approval is recorded (a spec
   section, a review-log disposition, or a plan amendment quote); an
   uncited approval claim is not a valid reason. A marker with no reason
   is a plan failure of the same class as the "No Placeholders" patterns.
   Never place the marker inline on the same line as the content it pins.

5. **A self-pin never justifies the marker.** A pin the plan itself
   introduces (the plan also writes the test that asserts the string, or
   also writes the matching file) does not justify `**Exact content:**`:
   body and pin are amendable **together as one ordinary fix** — the fix
   changes the text and its pinning test in the same commit. The same
   applies to a *pre-existing* pin whose assertion the same plan edits: a
   pin the plan controls is a self-pin, whatever its age. Only a pin the
   plan leaves untouched binds. Circular reasons — a reason citing an
   artifact the same plan creates or modifies — are a plan failure.

6. **Boundaries.**
   (a) This section defines the *authority* of bodies; it does not license
   vague steps — the "No Placeholders" rules still require actual code.
   (b) The default never applies to the plan header's
   `**Global Constraints:**` block, which binds as stated; a conflict with
   a global constraint is genuine and stops the run. One exception: a
   `**Global Constraints:**` entry that fails the two-part self-pin test
   from Self-Review check 5 — it does not trace to the spec named on the
   plan's `**Spec:**` line AND it restates the body of an artifact the
   plan itself creates or modifies — is amendable as an ordinary fix;
   every other Global Constraints entry keeps binding as stated. A finding
   whose subject is the `**Body authority:**` note's own wording is never a
   plan conflict: record it against this skill file,
   `skills/writing-plans/SKILL.md`, and let the run continue. That
   disposition covers the note's own text alone; a finding that the note
   contradicts something specific to the plan it appears in — one of that
   plan's global constraints, for example — is about that interaction and
   is triaged as an ordinary finding.
   (c) Other non-task plan content (header prose such as
   `**Architecture:**` and `**Assumptions:**`, the File Structure section)
   follows the same reference default: findings against it are ordinary
   fixes unless they contradict a stated contract or a global constraint.
   (d) A finding against a body in a task whose field reads
   `**Contract:** none — <reason>` is an ordinary fix under rule 3's
   default — there is no contract to break.
   (e) The implementer follows the reference body; the contract governs
   later findings.

**Example — code artifact contract:**

> **Contract:** `assert_round_reviewers <log> <round> <m> <required|optional>`
> - Inputs: review-log path, round number, expected reviewer count M, an
>   expectation mode supplied by the caller.
> - Output: exit 0 only when the round entry demonstrates M reviewers per
>   lens and every consolidated finding maps to reviewer sources.
> - Invariants: mode `required` makes a `Sources mapped: 0/0` entry fail;
>   mode `optional` keeps the documented skip; a missing or misspelled
>   mode fails.
> - Verification: synthetic-fixture checks covering both modes × both
>   outcomes, bad mode, missing round entry.
> - Interface not externally pinned — the signature above is descriptive
>   and may change in a fix (rule 2).

**Example — wording artifact contract:**

> **Contract:** model-probe example in `reviewer-prompt.md`
> - Must convey: a reviewer asserting a harness property runs a probe; the
>   probe prompt must not name the canary token.
> - Invariant: no example places the token inside the probe prompt text.
> - Verification: `bash tests/reviewer-templates/run-tests.sh` asserts the
>   section exists and the example probe omits the token.
> - Sentence wording is free; the properties above bind.

## Task Template

````markdown
### Task N: <Name>

**Files:**
- Create: `<path>`
- Modify: `<path>`
- Test: `<path>`

**Security flag:** `none` *(set to `security` if this task handles auth, credentials, input validation, permissions, crypto, or data access boundaries — triggers pre-implementation security review before the implementer is dispatched)*

**Does NOT cover:** *(required when this task adds a condition, gate, trigger, or any "when X do Y" logic — state the scenarios the condition excludes. If an excluded scenario should be covered, revise this task before implementing.)*

**Contract:** *(one entry per artifact this task creates or modifies: the invariants that must hold and the verification that would falsify them; inputs and outputs for code artifacts. See "Contracts and Literal Bodies" for the two shapes — code artifact and wording artifact. Write `none — <reason>` when the task creates or modifies nothing a later review finding could be judged against.)*

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

```<lang>
<actual test code>
```

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

Run: `<command>`
Expected: FAIL with "<expected failure reason>"

- [ ] **Step 3: Implement minimal change**

```<lang>
<actual implementation code>
```

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

Run: `<command>`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add <files>
git commit -m "<type>(<scope>): <what changed>" --trailer "Session: <slug>" --trailer "Stage: task <N>/<total>"
```
````

## Commit Messages

Every commit made while executing a plan must say which workstream and which stage it belongs to — without this, a branch full of task commits is unreadable later.

- **Slug** = the plan's file basename with the `YYYY-MM-DD-` date prefix and the `.md` extension stripped, each only if present. Every skill in the pipeline derives the slug with this same rule. Under the artifact layout the plan basename *is* the slug, so the rule yields it unchanged: `docs/superpowers-orchestrator/2026-08-17-auth-login/plans/auth-login.md` → `auth-login`.
- Step 5 of each task carries the full commit command: a conventional subject describing the change, plus two trailers (a trailer is a `Key: value` line at the end of the commit message, the same mechanism as `Co-Authored-By`):
  - `Session: <slug>` — the workstream.
  - `Stage: task <N>/<total>` — position in the pipeline.
- Fill in the real slug and task numbers when writing the plan — the No Placeholders rule applies to the commit command too. `git log --grep "^Session: <slug>"` then lists every commit of the workstream.

## No Placeholders

Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:

- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
- Steps that describe what to do without showing how (code blocks required for code steps)
- References to types, functions, or methods not defined in any task

These patterns are about *content completeness*; the "Contracts and
Literal Bodies" section defines the *authority* of that content. A body
must still be actual code or actual wording even when it binds only as a
reference implementation.

## Quality Bar

- No vague steps like "update logic".
- No hidden dependencies between distant tasks.
- Call out migrations, feature flags, and rollback checks when relevant.
- Prefer small vertical slices over large horizontal phases.

## Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.

**4. Scope-reduction scan:** Search the plan for: "v1", "basic", "simple", "for now", "placeholder", "initial version", "minimal". For each hit, verify it was explicitly sanctioned by the user — not a quiet scope downgrade from what was requested. Fix any that weren't.

**5. Contract audit:** Every fenced block, block quote, and `Run:` line in a task step is in one of three buckets: (a) it falls under its task's stated `**Contract:**`; (b) it carries an `**Exact content:**` marker; or (c) it is a procedural step block under rule 1's test — it creates, modifies, or deletes no file in the working tree, and runs at least one command, every command it runs being a pipeline command, such as the Step 5 commit block or a verification `Run:` line (a `Run:` line is a procedural form only when the command it runs writes no working-tree file), with an unclear case treated as not procedural — covered by the reference default of "Contracts and Literal Bodies" rule 3. This check's universe is task-step content only; plan-header content is out of scope — including the `**Body authority:**` block quote, which is template text every generated plan carries — with one exception: the `**Global Constraints:**` entries that the last sentence of this check inspects. Every marker's reason names a pin external to the plan and untouched by it — a reason citing an artifact this same plan creates or modifies is circular and invalid. Every `**Contract:**` field is falsifiable: a contract no check could fail ("must work correctly") is treated as missing, and so is a `none — <reason>` field on a task that does create or modify a governed artifact (a false `none`). Each `**Global Constraints:**` entry is checked too: an entry that (a) does not trace to the spec named on the plan's `**Spec:**` line and (b) restates the body of an artifact the plan itself creates or modifies is a self-pin in disguise and is flagged.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

## Multi-Round Plan Review

After self-review, invoke `superpowers-orchestrator:multi-doc-review` on the saved
plan (doc type `plan`; spec path from the plan header's `**Spec:**` line).
It asks for N if not already stated (default 3; 0 skips), runs at most once
per gate, and writes its audit log to `<plan-basename>-review-log.md`. If
the user requests plan changes afterward, re-run only Self-Review — another
loop pass only on explicit user request. Skip on platforms without the
Agent tool.

## Execution Handoff

After saving the plan, completing self-review, and completing the multi-round plan review, auto-select the execution approach using the logic below, seed `state.md`, then output the ready message and **stop**. Do not invoke any execution skill until the user replies.

### Selection Logic (evaluate in order)

1. Current context window ≥ 60% full → **Subagent-Driven** (offload context pressure)
2. Task count ≥ 5 → **Subagent-Driven** (fresh context per task)
3. Tasks have heavy inter-task state sharing (each task depends on runtime state from the previous) → **Inline**
4. Default → **Subagent-Driven**

### Seed `state.md`

Write the plan pointer into `state.md` at the project root — a full rewrite of
the plan-execution sections, in the same shape subagent-driven-development
writes at each batch end:

- `## Current Goal` — the plan's Goal line
- `## Plan` — path to the plan file + "Next task: 1 — <title>"
- `## Decisions & Deviations` — decisions made during planning that live only in
  this conversation. Usually empty: a decision that binds implementation belongs
  in the plan's Global Constraints, not here.
- `## Open Issues` — anything unresolved that execution must not run past

**Replace any earlier plan's sections — never append.** A `state.md` still
pointing at a previous plan makes the next session resume the wrong plan. This
seed is what makes it safe to start execution in a fresh session.

### Ready Message

```
Plan saved to `docs/superpowers-orchestrator/<date>-<slug>/plans/<slug>.md`. Ready to execute with **[Subagent-Driven / Inline Execution]** (<N> tasks[, <one-word reason>]).

Recommended: start execution in a fresh session (`/clear` in Claude Code) — this session's planning context is no longer needed for execution and only spends the first batch's context budget before Task 1 begins. The plan file and `state.md` carry everything execution needs. Then paste:

    <paste prompt from the table below>

Or reply here to execute in this session, or say "inline" / "subagent" to switch.
```

Fill the paste prompt from the selected approach. When Subagent-Driven is
selected, offer both variants (batched first) — the selection logic does not
distinguish them:

| Approach | Paste prompt | Behavior |
|---|---|---|
| Subagent-Driven, batched | `Use subagents in batched autonomous mode on docs/superpowers-orchestrator/<date>-<slug>/plans/<slug>.md` | Never asks mid-batch; hands off at the context boundary |
| Subagent-Driven, interactive | `Use subagents to implement docs/superpowers-orchestrator/<date>-<slug>/plans/<slug>.md` | Per-task subagents; stops to ask on ambiguity or blockers |
| Inline | `Execute the plan at docs/superpowers-orchestrator/<date>-<slug>/plans/<slug>.md` | Continuous in-session execution with checkpoints |

**Use these prompts verbatim — they are tuned to the skill-activator's
scoring, not just readable.** Two failure modes they avoid: a prompt matching
only one keyword scores 1 and is dropped below the confidence threshold, so the
fresh session routes to no skill at all; and a Subagent-Driven prompt that loses
its "subagents" or "in batches" wording falls through to executing-plans
(priority `high` against subagent-driven-development's `medium`) and silently
lands in inline execution.

**Stop here.** Do not invoke any execution skill until the user replies.

### On User Reply

**If Subagent-Driven:**
- **REQUIRED SUB-SKILL:** Use superpowers-orchestrator:subagent-driven-development
- Fresh subagent per task + two-stage review

**If Inline Execution:**
- **REQUIRED SUB-SKILL:** Use superpowers-orchestrator:executing-plans
- Continuous execution with checkpoints for review