Writing Plans (obra/superpowers)

tl;dr: this is the bridge skill between spec and code in obra/superpowers. brainstorming writes the spec, writing-plans breaks it into tasks a junior engineer could follow cold, then subagent-driven-development or executing-plans walks the plan. The plan itself is the artifact — saved to docs/superpowers/plans/YYYY-MM-DD-<feature>.md, every step has actual code (no “TBD”, no “implement later”), every step is 2–5 minutes, every task is independently testable.

What it actually does

The SKILL.md (obra/superpowers, fetched 2026-09-10) tells the agent to announce itself at the start: “I’m using the writing-plans skill to create the implementation plan.” Then it walks four blocks:

1. Scope check. If the spec covers multiple independent subsystems, push back — split into sub-project specs during brainstorming, write one plan per subsystem. A plan that produces working, testable software on its own is the unit.
2. File structure. Map out which files get created or modified and what each is responsible for, before defining tasks. Split by responsibility, not by technical layer. Files that change together live together.
3. Task right-sizing. A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer’s gate. Fold setup, scaffolding, and docs into the task whose deliverable needs them; split only where a reviewer could reject one task and approve the next.
4. Bite-sized steps. Every step is one action, 2–5 minutes: write the failing test, run it to confirm it fails, implement minimal code, run the test to confirm it passes, commit. Plan failures look like “TBD”, “similar to Task N”, “add appropriate error handling” — the skill names all of them explicitly and tells you not to write them.

The description field is the trigger:

Use when you have a spec or requirements for a multi-step task, before touching code

So writing-plans is not the brainstorming skill, not the execution skill, not a research skill. It’s the one that takes an approved design and emits a plan file.

The plan contract

Every plan starts with this header — the skill quotes it verbatim, do not paraphrase:

# [Feature Name] 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.
> Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
**Spec:** [path to the spec/design doc this plan implements]

## Global Constraints

[Project-wide requirements — version floors, dependency limits, naming rules — verbatim from the spec]

Each task inside follows the same shape: Files (Create / Modify / Test), Interfaces (Consumes / Produces — exact signatures, because a fresh subagent reads only their own task), then five steps numbered 1–5, each with its own code block and the literal command to run.

Save location and self-review

The skill is opinionated about where plans go: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md. User preference overrides the directory but not the naming.

After writing the plan, the skill mandates a three-point self-review before handoff:

1. Spec coverage. Skim the spec, point to a task per requirement. List gaps.
2. Placeholder scan. Search for TBD, TODO, “implement later”, “similar to Task N”, “add appropriate error handling” — fix inline.
3. Type consistency. A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug; the interface blocks are how downstream tasks learn names, so they have to match.

Execution handoff

The plan ends with an explicit choice for the human partner:

Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:

1. Subagent-Driven (recommended) — I dispatch a fresh subagent per task, review between tasks, fast iteration 2. Inline Execution — Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?

If subagent-driven: load superpowers:subagent-driven-development. If inline: load superpowers:executing-plans. The plan file carries the spec with it; executors read both.

Install

The upstream README does not document npx skills add obra/superpowers. Install is per-harness and the README enumerates them. Common paths:

# Claude Code — official Anthropic marketplace
/plugin install superpowers@claude-plugins-official

# Claude Code — Superpowers marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Codex CLI — official Codex marketplace
/plugins
# search: superpowers → Install Plugin

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# OpenCode — host fetches install doc itself
# Say: "Fetch and follow instructions from
#       https://raw.githubusercontent.com/obra/superpowers/main/.opencode/INSTALL.md"

If your host only watches a local SKILL.md, clone the repo and drop this one file:

git clone https://github.com/obra/superpowers
# place at any path your host's skill loader watches:
#   ~/.claude/skills/writing-plans/SKILL.md
#   .claude/skills/writing-plans/SKILL.md

writing-plans chains to subagent-driven-development or executing-plans for execution. Install the whole skills/ tree, not just this file.

Gotchas

• Plans are not specs. This skill assumes an already-approved design (typically from brainstorming). If the request is still a vague idea, the upstream text routes you back to brainstorming, not forward into task lists.
• No placeholders. The skill explicitly forbids “TBD”, “similar to Task N”, “implement later”, and the other rationalizations that show up when a planner runs out of context. If you can’t write the actual code for a step, leave the whole task out.
• Task size is non-negotiable. 2–5 minute steps. Five steps per task. A task with twelve steps is a sign the right-sizing analysis was skipped.
• Interface blocks are the contract. A downstream task’s implementer reads only their own task. The Produces: block is how they learn the function names and signatures neighboring tasks use. Get them wrong and the plan won’t compose.
• Spec must travel with the plan. The header points to the spec file. Executors read both — without the spec, the plan is a list of steps with no rationale.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not write a plan and walk it through a subagent.

Related: Brainstorming (obra/superpowers) — produces the spec that writing-plans decomposes; Subagent-Driven Development — the recommended execution path after the plan is written; Executing Plans — the inline-execution alternative the skill offers at handoff.