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

Write for an engineer who has not seen this codebase or this spec. Assume they write idiomatic code in the project's language once they know the exact interface and the exact test, and that they make a reasonable choice wherever the plan leaves one open. What they cannot know is what you decided: which files, which names and signatures, which values from the spec, which tests prove each task. The plan records those decisions. It is not a transcript of the code.

Output Path

Save to `docs/plans/YYYY-MM-DD-<feature-name>.md`.

• User preferences for plan location override this default.

Plan Header

# <Feature Name> Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-optimized:subagent-driven-development (recommended) or superpowers-optimized:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** <single sentence>
**Architecture:** <2-4 sentences>
**Tech Stack:** <languages/libraries/tools>
**Spec:** <path to the design doc this plan implements, or `none` if there isn't one. The plan argues from the spec, so the spec travels with it — executors read both, and plan conflicts resolve against the spec.>
**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

<The project-wide requirements every task is bound by — version floors, dependency limits, naming and copy rules, platform requirements, exact values — one line each, copied verbatim from the spec. Every task's requirements implicitly include this section. Write `none` if there genuinely are none.>

## Review Focus

<Up to five input classes or failure modes the spec implies but no task's tests exercise — the ones most likely to bite a real user, most likely first. One line each: name the input or condition, and the behavior a reasonable person would expect.

A spec is a vision document. It says what the software must do; it does not enumerate every input the software will meet, and its silence about an input is not permission for that input to crash the program.

Write this list once, with the spec in front of you. Then, for each line, add the test that pins it to the task that owns that code, in that task's own step style. An empty section means you checked and found none — not that you skipped the check.>

---

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 with a checkable result.
• 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.

Task Template

### Task N: <Name>

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

**Interfaces:**
- Consumes: *(exact signatures this task uses from earlier tasks — function names, parameter and return types. Write `nothing` if it stands alone.)*
- Produces: *(exact signatures later tasks will rely on. Write `nothing` if no later task builds on this.)*

*This block is not optional bookkeeping. An implementer dispatched by `subagent-driven-development` sees only its own task text — never the plan, never its neighbours. This block is the only way it learns the names and types the tasks around it use. Omit it and the implementer invents a plausible name, which the next task then fails to import.*

**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.)*

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

```<lang>
<the test's name and its assertions, with the spec's exact values>

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

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

• [ ] **Step 3: Implement `<exact signature>` in `<path>`**

<One line on the approach when the signatur