Superpowers Writing Plans (袁文同优化版)

Create detailed multi-step implementation plans from specs, with precise file edits, code examples, tests, verification, TDD, DRY, and small tasks for smooth...

Security Scan

Instruction-only planning skill whose requests and runtime instructions match its description — no installs, no credentials, and no unexpected exfiltration, but it will create files/commits and can orchestrate other skills so review any execution before letting it run.

Purpose & Capability

Name/description (produce detailed multi-step implementation plans with exact file edits, tests, commands) align with the SKILL.md. The skill requests no binaries, env vars, or installs, which is proportionate for an instruction-only planner. References to other 'superpowers' skills (brainstorming, subagent, finishing-branch) are reasonable coordination points, not unexplained credential requests.

Instruction Scope

Instructions are precise and limited to planning tasks: produce markdown plans saved under docs/superpowers/plans/, enumerate exact files/lines/code/tests, and propose git commands and pytest invocations. This stays within the stated purpose. Note: the skill expects to run in a repository/work directory and recommends committing and branching; if executed automatically it could create/overwrite files and perform git operations — so users should ensure execution happens in an isolated branch or sandbox and review generated commits before merging.

Install Mechanism

No install spec and no code files — lowest-risk category. Nothing will be downloaded or written to disk by an installer as part of skill installation itself.

Credentials

No environment variables, credentials, or config paths are requested. The only operational requirements are repository access and typical developer tooling (git, pytest) implied by the instructions — those are proportional to producing executable implementation plans.

Persistence & Privilege

always is false and the skill does not request persistent platform privileges. It recommends dispatching subagents (via another skill) for execution, which increases blast radius only if you allow automated execution of tasks or grant other skills additional privileges. Autonomous invocation is allowed by default on the platform but that is not unique to this skill.

Assessment

This is an instruction-only planning tool and is internally coherent: it won't install software or ask for secrets. However, its runtime instructions create files, run git commands, and may suggest running tests and dispatching subagents. Before using it: (1) restrict execution to a dedicated feature branch or sandbox repo to avoid accidental overwrites; (2) review any generated plan file and commits before merging or executing tasks; (3) be cautious if you enable automated execution/subagent dispatch — inspect and vet the referenced subagent skills (e.g. superpowers-subagent-dev and superpowers-finishing-branch) before granting them permissions; (4) verify you want the agent to run git/pytest commands in your environment. If you want purely advisory output, use the skill but do not allow it to execute tasks or write files automatically.

Superpowers Writing Plans - 写实现计划

概述

写全面的实现计划，假设执行者对代码库零上下文、品味可疑。记录他们需要知道的一切：每个任务要修改的文件、代码、可能需要检查的测试和文档、如何测试。给出完整计划为小粒度任务。DRY。YAGNI。TDD。频繁 commit。

假设执行者是个有技能的开发者，但几乎不了解我们的工具集或问题领域。假设他们不太懂好的测试设计。

开始时宣布： "我正在用 writing-plans 技能创建实现计划。"

上下文： 这应该在专门的工作目录中运行（由 brainstorming 技能创建）。

保存计划到： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

范围检查

如果规格涵盖多个独立子系统，应该在 brainstorming 阶段已分解为子项目规格。如果没有，建议分解为独立计划——每个子系统一个。每个计划应产生可工作、可测试的软件。

文件结构

在定义任务之前，映射哪些文件将被创建或修改，每个文件负责什么。这是分解决策被锁定的地方。

• 用清晰边界和定义好接口的设计单元。每个文件应该有一个明确职责。
• 你能放进脑子里的代码你推理得最好，编辑也更可靠。偏好更小、专注的文件，不要大的什么都做的文件。
• 一起变更的文件应该放一起。按职责拆分，不是按技术层。
• 现有代码库中，遵循已有模式。如果代码库用大文件，不要单方面重构——但如果修改的文件已经长得太大，在计划中包含拆分是合理的。

这个结构指导任务分解。每个任务应该产生能独立理解的有意义的变更。

小粒度任务

每步是一个动作（2-5 分钟）：

• "写失败的测试" — 一步
• "运行确保它失败" — 一步
• "写最少代码让测试通过" — 一步
• "运行确保测试通过" — 一步
• "Commit" — 一步

计划文档头部

每个计划必须以此头部开始：

# [功能名] 实现计划

**目标：** [一句话描述构建内容]

**架构：** [2-3 句话描述方法]

**技术栈：** [关键技术和库]

---

任务结构

### 任务 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：写最少的实现代码

def function(input):
    return expected

• 步骤 4：运行测试验证它通过

运行：pytest tests/path/test.py::test_name -v 预期：PASS

• 步骤 5：Commit

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"

## 无占位符

每步必须包含执行者需要的实际内容。以下是**计划失败**——永远不要写：
- "TBD"、"TODO"、"稍后实现"、"填细节"
- "添加适当的错误处理"/"添加验证"/"处理边界情况"
- "为上述写测试"（没有实际测试代码）
- "类似于任务 N"（重复代码——执行者可能按顺序读任务）
- 描述做什么而不展示怎么做的步骤（代码步骤必须有代码块）
- 引用任何任务中未定义的类型、函数或方法

## 自审

写完完整计划后，用新眼光看规格并检查计划：

**1. 规格覆盖：** 浏览规格每个部分/需求。能指向实现它的任务吗？列出任何缺口。

**2. 占位符扫描：** 在计划中搜索红旗——上述"无占位符"部分的任何模式。修复它们。

**3. 类型一致性：** 在后续任务中使用的类型、方法签名和属性名与前面定义的一致吗？任务 3 中的 `clearLayers()` 和任务 7 中的 `clearFullLayers()` 是 bug。

发现问题，内联修复。不需要重新审查——修复并继续。如果发现规格需求没有任务，加任务。

## 工作目录说明（OpenClaw 适配）

Superpowers 原版使用 git worktree 做隔离工作区。在 OpenClaw 环境中：
- 使用 git branch 创建特性分支
- 在分支上工作，完成后 merge 或 PR
- 保持工作目录整洁，与主分支隔离

**工作流程：**
```bash
# 从当前分支创建特性分支
git checkout -b feature/<feature-name>

# 实现（按计划任务）
# ...

# 完成时
git checkout main && git merge feature/<feature-name>

执行移交

保存计划后，提供执行选择：

"计划写完保存到 docs/superpowers/plans/<filename>.md。两种执行选项：

1. 子 Agent 驱动（推荐） — 我为每个任务 dispatch 新的 subagent，任务间审查，快速迭代

2. 顺序执行 — 在本 session 按批次执行任务，有审查检查点

选择哪种？"

如果选择子 Agent 驱动：

• 需要 superpowers-subagent-dev 技能
• 每个任务新鲜 subagent + 两阶段审查

如果选择顺序执行：

• 在本 session 按计划任务顺序执行
• 每个任务后运行验证
• 完成后调用 superpowers-finishing-branch 清理