Overview
Write an implementation plan for an engineer who has never seen this codebase and has never seen this spec. Assume that once they know the exact interfaces and the exact tests, they can write idiomatic code in the language the project uses; also assume that where the plan leaves room for choice, they will make reasonable choices. What they have no way of knowing is what you have already decided: which files, which names and signatures, which values from the spec, which tests prove each task. Write these down. Break the entire plan into small step-by-step tasks. DRY. YAGNI. TDD. Commit frequently.
At the start, announce: "I am using the writing-plans skill to create an implementation plan."
Context: This skill should be run in a dedicated worktree (created by the brainstorming skill).
Where to save the plan: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
- (the user's preference for the plan location takes precedence over this default)
Scope Check
If the spec covers multiple independent subsystems, it should have been split into sub-project specs during the brainstorming phase. If it was not, suggest splitting it into independent plans—one per subsystem. Each plan should be able to independently produce working, testable software.
File Structure
Before defining tasks, first list the files that will be created or modified and the responsibility of each file. This is where decomposition decisions are locked in.
- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- You reason best about code that fits into context at once; the more focused the files, the more reliable your edits. Prefer small, focused files over large files that take on too much functionality.
- Files that change together should be placed together. Split by responsibility, not by technical layer.
- In an existing codebase, follow existing patterns. If the codebase uses large files, do not unilaterally refactor—but if the file you are modifying has already become unmanageable, including a split in the plan is reasonable.
This structure determines the task breakdown. Each task should produce an independent, meaningful change.
Task Granularity Boundaries
A task isthe smallest unit that can independently carry its own round of the test loop and is worth a fresh reviewer's scrutiny. When drawing task boundaries: fold setup, configuration, scaffolding, and documentation steps into the task of the deliverable that actually needs them; split only where "a reviewer might reject this task while approving the one next to it." Each task ends with anindependently testable deliverable.
Step Granularity
Each step is one action and has a checkable result:
- "Write a failing test" - one step
- "Run it to confirm it fails" - one step
- "Implement the minimum code to make the test pass" - one step
- "Run the test to confirm it passes" - one step
- "Commit" - one step
Plan Document Header
Every plan must start with this header:
# [功能名称] 实现计划
> **面向 AI 代理的工作者：** 必需子技能：使用 subagent-driven-development（推荐）或 executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
**目标：** [一句话描述要构建什么]
**架构：** [2-3 句话描述方案]
**技术栈：** [关键技术/库]
**规格：** [本计划所实现的规格 / 设计文档路径 —— 计划的论证依据来自规格，所以规格要跟着计划一起走；执行者两份都读]
## 全局约束
[来自规格的项目级要求 —— 版本下限、依赖限制、命名与文案规则、平台要求 —— 每条一行，数值从规格里逐字照抄。每个任务的要求都隐含包含本节。]
## 审查重点（Review Focus）
[规格隐含了、但没有任何任务的测试覆盖到的输入类别或失败模式中，最可能伤到这个软件使用者的五个 —— 每条一行，写明那个输入或条件，以及一个正常人会期待的行为，最可能的排最前。规格是一份愿景文档：它说软件必须做什么，而不是软件会遇到的一切；规格对某种输入没有提及，不等于允许这种输入把程序弄坏。趁规格就在眼前，在这里一次写完这份清单。然后针对每一行，把钉住它的那个测试，按那个任务自己的步骤写法，加进负责那段代码的任务里。]
---
Task Structure
### 任务 N：[组件名称]
**文件：**
- 创建：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 测试：`tests/exact/path/to/test.py`
- [ ] **步骤 1：编写失败的测试**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- [ ] **步骤 2：运行测试验证失败**
运行：`pytest tests/path/test.py::test_name -v`
预期：FAIL，报错 "function not defined"
- [ ] **步骤 3：在 `exact/path/to/file.py` 中实现 `function(input: InputType) -> ResultType`**
当签名和测试还留有选择余地时（用哪个库调用、哪种数据结构），用一行说明做法；只有签名和测试决定不了的算法，才给代码块。
- [ ] **步骤 4：运行测试验证通过**
运行：`pytest tests/path/test.py::test_name -v`
预期：PASS
- [ ] **步骤 5：Commit**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
What a Step Contains
When the implementer can, based on a step,write exactly one reasonable thingAt this point, the step is done. There is only one requirement: unambiguous, not complete. Each type of step carries only what makes it unambiguous, no more:
- Test step: The test's name and its assertions, given in code form, containing the exact values from the spec.
- Code step: The exact signature (name, parameters, return type), the file it lives in, and the specific values pinned down by the spec. The function body is written by the implementer. Only algorithms that the signature and tests cannot determine, or exact copy pinned down by the spec, should have their function bodies written out.
- Verification step: The command to run, and the output that represents passing.
- Referencing another task: That task's Interfaces block states what to use; the plan does not repeat that task's code.
A plan is the set of decisions that the implementer cannot make alone. A plan longer than the code it describes is really just the code written out. Lines that decide nothing ("TBD", "handle edge cases", "add appropriate validation", "write tests for the above code", types or functions not defined by any task) are failures in the opposite direction, and the self-check catches both.
Self-check
After writing the complete plan, review the spec with fresh eyes and check the plan against it. This is a checklist you execute yourself—not subagent dispatch.
1. Spec coverage: Go through every section/requirement in the spec. Can you point to the task that implements it? List all omissions.
2. Step scan: Every step must let the implementer write exactly one reasonable thing, and no step may carry more: lines that decide nothing are gaps, and function bodies already determined by the signature and tests are copying. Fix both.
3. Type consistency: Do the types, method signatures, and property names used in later tasks match those defined in earlier tasks? In task 3 it is called clearLayers() but in task 7 it is called clearFullLayers() is a bug.
4. Review focus: For every input category or failure mode implied by the spec, is there a task whose tests cover it? The five most likely to hurt users that are not covered go into the "Review focus" section, and every line there must add the corresponding test to the responsible task. An empty section means you checked and found none, not that you skipped the check.
5. Proportion: Compare the length of the plan with the spec. A plan several times longer than the spec it implements is a transcript of the program, not a plan. If code blocks make up most of the document, replace function bodies with signatures, test names, and assertions, then check whether every step is still unambiguous.
If you find problems, fix them inline. No need to re-review—fix and keep going. If you find a requirement in the spec with no corresponding task, add a task.
Execution handoff
After saving and self-checking the plan, link the plan to your human partner to read. If they have already explicitly given an execution method, ask them to review the plan and confirm it captures what they want; wait for them to finish reviewing before starting implementation, then follow that established method. Otherwise, ask them to review the plan and choose an execution method before implementation.
When no execution method has been given yet:
"The plan is complete and saved to docs/superpowers/plans/<filename>.md. Please review this plan. Which execution approach would you like to use?
- Subagent-driven - Each task is implemented by a fresh subagent and checked by a fresh reviewer before the next task begins, with a final review covering the entire branch. Most thorough; the cost is a fresh context for each task and each review.
- Native execution - I personally implement each task in the current session in the manner of this runtime environment, and finally a fresh reviewer running on the strongest model checks the entire branch. Cheapest and fastest; independent review only comes at the end. The session can run well on a mid-tier model, because the plan already carries the design.
For this plan, I recommend <one of the two>, because <a sentence derived from the plan: how deeply the tasks depend on each other's interfaces, how many tasks there are, and what the cost of a mistake going live is>. Does this plan capture what you want? Which approach shall we use?"
When an execution approach has already been given:
"The plan is complete and saved to docs/superpowers/plans/<filename>.md. Please review this plan. Does it capture what you want?"
If subagent-driven is chosen:
- Required sub-skill: Use subagent-driven-development
If native execution is chosen:
- Required sub-skill: Use executing-plans