A design describes the intended result but may leave the next developer guessing about files, interfaces, and verification. Writing-plans bridges that gap by turning an approved design into concrete implementation work.
Install and start
Run the following plugin command inside a Claude Code session to install Superpowers, including its cooperating skills. In Codex, find Superpowers in the plugin interface and install it there. Install separately for each client you use. Start a fresh session in the project and explicitly ask to use writing-plans with a bounded task.
/plugin install superpowers@claude-plugins-official
Begin with an approved specification
Adapt this first request to your project:
Use Superpowers writing-plans with docs/specs/order-export.md. Inspect the repository layout, test framework, and interfaces. For each task specify files, test inputs, expected failures, and passing outcomes. Preserve export permissions, row limits, and timestamp rules. Write the plan without executing it.
Provide the actual design and repository. Undecided permissions, output formats, or limits should remain questions until resolved; the planner should not silently invent product decisions. Use this skill when the destination is agreed and the remaining problem is how to reach it.
Make tasks independently understandable
The plan first identifies affected files and responsibilities, then divides the work into deliverables that can be reviewed and tested. An export feature might involve validation, data access, file generation, and download interaction. The boundaries should follow the existing architecture rather than split a coherent interface into arbitrary fragments.
Each task should name the files to create or change, relevant input and output types, test locations, and commands. Tests need concrete inputs and expected behavior, not a placeholder saying to add unit tests. Implementation guidance should explain important decisions instead of vague instructions to handle errors. The upstream workflow emphasizes observing a meaningful failing test before minimal implementation, then confirming it passes.
Preserve constraints across tasks
Some requirements affect several layers. Export row limits, timestamp formats, and authorization checks should remain visible in the plan, with consistent treatment wherever they matter. Put edge cases into the tests of the task that owns them; a reminder at the end of the document is easy to miss during execution.
The default destination is a dated document under docs/superpowers/plans. Review whether paths and commands match the repository, interfaces agree between tasks, and placeholders are gone. A later session should be able to find the specification and necessary context from the plan alone.
Review before execution
Producing a plan completes planning, not implementation. After reviewing it, choose whether to execute in the current context or use separate task agents with review. Worktree setup belongs to the start of implementation rather than being a prerequisite for writing the document. Keep the plan proportional to the change: the useful property is that a task can be followed and verified, not that the document contains many tiny steps.
Test a plan by handing it to someone new
Suppose the agreed design adds single sign-on to an existing app. A useful plan says more than “integrate OAuth, add tests, deploy.” It identifies the current login callback, session store, account linking, and error page files; states the new endpoint's input and output; and describes how old accounts map to new identities. Order dependencies: verify provider callback and state handling, then account linking, then UI and docs. Each task needs a runnable check and expected observation, not just “tests pass.”
Ask a developer who missed the discussion to read only the plan and name the first file to change, the test location, and the constraint that must not break. If they still need a verbal explanation, the plan lacks context. Correct a wrong package manager or nonexistent test command before execution. It is fine to flag an unresolved account-conflict decision, but downstream tasks are not executable until it is settled. Exact paths, boundaries, and acceptance criteria matter more than page count.
Try to break the plan before handoff
After writing the plan, rehearse its first step and riskiest step against the real project: verify commands, working directory, environment, file paths, and field names. Across many sessions, one user found apparently complete plans with missing virtualenv setup, wrong test commands, or field mappings that drifted between steps. Ask a second reader to try to break the plan: “Which step fails first in order? Which input silently changes name later?” Patch the plan before handing it to implementation rather than making the next session discover the gaps halfway through.