Superpowers Writing Plans: Turning a Spec Into Bite-Sized Work

Most failed projects do not fail at the keyboard. They fail in the gap between “we know what we want” and “here is the next thing to do, with a test that proves it.” The superpowers writing-plans skill lives in exactly that gap. It takes an approved design and converts it into an implementation plan: a document precise enough that someone who has never seen the codebase could execute it task by task, and disciplined enough that it fits in a human afternoon instead of a quarter.

What the writing-plans skill actually does

Writing-plans is the middle skill in the Superpowers planning chain. superpowers-brainstorming explores intent and produces an approved spec; writing-plans turns that spec into a task list; and superpowers-executing-plans or subagent-driven execution carries the tasks to done. The skill saves every plan to docs/superpowers/plans/YYYY-MM-DD-<feature>.md, so the plan is a versioned artifact that travels with the code, not a Slack thread that evaporates.

The whole skill rests on one mental model, and it is worth quoting because everything else follows from it: assume the implementer writes idiomatic code once they know the exact interface and the exact test. What the implementer cannot know is what you decided — which files, which names and signatures, which values from the spec, which tests prove each task. The skill’s conclusion: “A plan is the set of decisions the implementer cannot make alone.” That single sentence sets the length of a good plan. A plan that re-derives things the implementer could decide itself is padding; a plan that leaves your decisions open is a bug report waiting to happen.

Before any of that, the skill runs a scope check: if the spec covers multiple independent subsystems, it should have been split during brainstorming, and if it wasn’t, writing-plans splits it now — one plan per subsystem, each producing working, testable software on its own.

The plan header is a contract

Every plan starts with a fixed header, and each field exists to answer a question a fresh implementer will otherwise ask halfway through Task 3:

# Article Series: The Skills We Use Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use
> superpowers:subagent-driven-development (recommended) or
> superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Write and deploy an article series about the 14 Superpowers
skills and 5 cross-skill themes for byteittech.com.

**Architecture:** Each article is a self-contained HTML file following the
existing byteittech.com article template. ...

**Tech Stack:** HTML, CSS (existing byteittech stylesheet), Python
`apply-patch.py` for deployment

**Spec:** docs/superpowers/specs/2026-11-05-article-series.md

## Global Constraints

- Newline style: LF (verified on live site)
- Each deep-dive article: 1,200-2,000 words
- Article slugs: `skills/deep-dive/<skill-name>`

## Review Focus

- Each article must have a clear "what this skill does,"
  "when to use it," and "real example" section
- All articles need SEO head enrichment (meta description, og:image)

Goal — one sentence. If you cannot write it, the scope check should have fired earlier.
Architecture — two or three sentences of approach, so every task inherits the same mental model.
Spec — the path to the design doc. The plan argues from the spec, so the spec ships with the plan; executors read both.
Global Constraints — the project-wide rules with exact values copied verbatim from the spec: version floors, naming rules, newline style. Every task’s requirements implicitly include this section, so it is written once and never repeated per task.
Review Focus — the subtlest field. A spec is a vision document: its silence on an input is not permission for that input to break the program. The header asks for the five input classes or failure modes the spec implies but no task’s tests exercise — then each line gets a test pinned to the task that owns the code. An empty section means “checked and found none,” not “skipped the check.”

Right-sizing tasks: one test cycle per task

The skill defines a task as the smallest unit that carries its own test cycle and is worth a fresh reviewer’s gate. Two practical corollaries follow. First, fold setup, configuration, scaffolding, and documentation into the task whose deliverable needs them — there is no “Task 0: make a directory.” Second, split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task therefore ends with an independently testable deliverable, which is what makes parallel and subagent execution possible at all.

Because a task’s implementer sees only their own task, every task carries a Interfaces block: Consumes lists what it uses from earlier tasks with exact signatures; Produces lists what later tasks rely on — exact function names, parameter and return types. That block is how two implementers who never talk agree on the name of the thing between them.

Inside a task, each step is one action with a checkable result. The canonical rhythm is five steps: write the failing test, run it to make sure it fails, implement the minimum to pass, run it to make sure it passes, commit. A step is done when the implementer can write exactly one reasonable thing from it — unambiguous, not complete. A test step carries its assertions as code with the spec’s exact values; a code step carries the exact signature, file, and pinned values, but no body unless the signature and tests don’t determine an algorithm; a verification step carries the command and the output that means “passed.”

A real example: the plan behind this article

This article is Task 2, Step 2 of a plan written with the writing-plans skill itself. The job: a 19-article series for this very site, built and deployed by agents. The header goal reads: “Write and deploy an article series about the 14 Superpowers skills and 5 cross-skill themes,” with architecture and tech stack beneath it. Watch how the skill’s rules show up in the finished plan:

Global Constraints carries verbatim values. The constraint list includes “Newline style: LF (verified on live site).” The live docroot is LF; an earlier release era was CRLF. Written into the plan once, that one line silently protects all 19 articles from the single most dangerous failure mode in this deployment.
Tasks are right-sized around reviewable deliverables. Task 1 produces the directory tree and master index. Task 2 delivers the 14 deep-dives. Task 4 adds SEO head enrichment only after every article exists, because a meta description written for an article that changes is a rewrite. Task 6 is the deploy with its manifest and verification. Each could be approved or rejected independently.
Review Focus names what tests can’t. Nothing in the build checks that an article “has a clear what/when/real example section” — so the plan says it once, up top, where every executor sees it.

### Task 5: Create pager links between articles

**Files:**
- Modify: every article's pager `<nav>` element

**Interfaces:**
- Consumes: the 19 article files produced by Tasks 2 and 3
- Produces: a fully linked series; each article has prev/next within
  its series plus a link to the master index

- [ ] **Step 1: Add pager links to each article**
  Deep-dive series pager order:
  1. brainstorming -> 2. writing-plans -> 3. executing-plans -> ...
  Expected after: every article renders prev/next that resolve.

Note what the plan does not do: it never drafts the 19 articles. The decisions locked in are the series structure, slug scheme, pager order, and deploy mechanics — the things 19 independent implementers could not agree on alone. Prose style? Left open. That is what “a reasonable choice wherever the plan leaves one open” means.

Sidebar: How a good plan saves hours of rework. Deploying this series means touching every live article to splice pager links, then hashing 20 files into a manifest the server verifies. If the newline constraint lived only in someone’s head, the likely outcome is a payload written in Windows text mode: LF becomes CRLF, every manifest hash mismatches, and the deploy either fails loudly or — worse — succeeds and renders wrong. That is a half-day of byte diffs to untangle. Because writing-plans forced the constraint into a verbatim Global Constraints line that every task inherits, the mistake has to survive 19 executors to happen at all. Plans are cheapest when they make the expensive mistakes structurally impossible.

Self-review: the checklist that saves the plan

After the last task, the skill makes the author re-read the plan with fresh eyes, against the spec — five checks, run inline, not by a subagent:

Spec coverage: for each spec requirement, can you point to a task that implements it? Gaps mean add the task.
Step scan: every step lets the implementer write exactly one reasonable thing — no more, no less.
Type consistency: a function called clearLayers() in Task 3 and clearFullLayers() in Task 7 is a bug the plan wrote itself.
Review Focus: each named failure mode has a test in the owning task.
Proportion: compare plan length to spec length. A plan several times longer than its spec is a transcript of the program, not a plan.

The two classic failures are mirror images. The transcript plan pastes function bodies the signature and tests already determine — it has written the code instead of the plan. The hand-waving plan carries lines that decide nothing: “TBD,” “handle edge cases,” “write tests for the above.” The self-review catches both, and the fix is always inline: no review loop, just fix and move on.

Handoff: plan, then choose the execution method

A finished plan ends with a question, not a command. The author presents two execution modes — subagent-driven (a fresh subagent implements each task, a fresh reviewer gates it, then a whole-branch review) or native (one agent implements every task in-session, with a single final review) — and recommends one with a sentence grounded in the plan itself: how much the tasks depend on each other’s interfaces, how many there are, what a shipped mistake would cost. For our article series the recommendation was native execution with one review at the end; prose tasks have weak interface coupling and a wrong article is cheap to rewrite.

Related Deep Dives in the Series

The skill you just read about doesn’t stand alone. superpowers-brainstorming is upstream — no approved spec, no plan. Downstream, superpowers-executing-plans is the native executor that walks the checkboxes, and superpowers-subagent-driven-development is the high-assurance executor with a fresh reviewer per task. When the last checkbox flips, superpowers-finishing-a-development-branch verifies the whole branch before anyone calls it done.