Overview
Write comprehensive implementation plans, assuming the executing engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files each task touches, code, tests, docs they may need to check, how to test. Break the full plan into small tasks for them. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know much about good test design.
At the start, announce: "I'm using the writing-plans skill to create the implementation plan."
Context: If working in an isolated worktree, it should already have been created at execution time via the superpowers:using-git-worktrees skill.
Save the plan to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
- (the user's preference for the plan location overrides this default)
Scope Check
If the spec covers multiple independent subsystems, it should already have been split into sub-project specs during brainstorming. If not, suggest splitting it into multiple separate plans — one per subsystem. Each plan should be able to independently produce working, testable software.
File Structure
Before defining tasks, first sort out which files will be created or modified, and what each file is responsible for. This is where decomposition decisions get locked in.
- Design units with clear boundaries and explicit interfaces. Each file should have one clear responsibility.
- You reason best about code that fits into context at one time; your edits are also more reliable when files are focused. Prefer smaller, more focused files over large files that take on too many responsibilities.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow existing patterns. If the codebase uses large files, don't unilaterally refactor - but if the file you're modifying has already become unwieldy, including a split in the plan is reasonable.
This structure will guide task decomposition. Each task should produce a self-contained change that also makes sense on its own.
Small Task Granularity
Each step is one action (2-5 minutes):
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step
Plan Document Header
Each plan must start with this header:
# [Feature Name] 实施计划
> **给 agentic workers：** REQUIRED SUB-SKILL: 使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans，逐 task 实现此 plan。Steps 使用 checkbox（`- [ ]`）语法进行跟踪。
**目标：** [One sentence describing what this builds]
**架构：** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---
Task Structure
### Task N: [Component Name]
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
- [ ] **Step 1: 编写失败测试**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- [ ] **Step 2: 运行测试以验证它失败**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL，包含 "function not defined"
- [ ] **Step 3: 编写最小 implementation**
```python
def function(input):
return expected
```
- [ ] **Step 4: 运行测试以验证它通过**
Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
No Placeholders
Every step must contain the actual content the engineer needs. These are plan failures — never write:
- "TBD", "TODO", "implement later", "fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above" (without actual test code)
- "Similar to Task N" (duplicate code — the engineer may read tasks out of order)
- Steps that only describe what to do without showing how to do it (code steps need code blocks)
- Referencing types, functions, or methods that are not defined in any task
Remember
- Always use exact file paths
- Every step must have complete code — if a step changes code, show the code
- Exact commands and expected output
- DRY, YAGNI, TDD, frequent commits
Self-Review
After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
1. Spec coverage： Review each section/requirement in the spec. Can you point to a task that implements it? List any gaps.
2. Placeholder scan： Search your plan for red flags — any patterns from the "No Placeholders" section above. Fix them.
3. Type consistency： Do the types, method signatures, and property names you use in later tasks match what was defined in earlier tasks? A function named clearLayers()in Task 3 but named clearFullLayers() in Task 7 is a bug.
If you find issues, fix them inline. No need to re-review — continue after fixing. If you find a spec requirement with no corresponding task, add that task.
Execution Handoff
After saving the plan, offer execution options:
"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 is chosen:
- REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
- Use a fresh subagent per task + two-stage review
If Inline Execution is chosen:
- REQUIRED SUB-SKILL: Use superpowers:executing-plans
- Batch execution with review checkpoints