[Feature Name] Implementation Plan

[Feature Name] Implementation Plan

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

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]

Global Constraints

[The spec's project-wide requirements — version floors, dependency limits, naming and copy rules, platform requirements — one line each, with exact values copied verbatim from the spec. Every task's requirements implicitly include this section.]

要点说明： - **面向 Agent 的工作者声明**：头部第二行是写给执行 Agent 的强制指令——必须使用 `subagent-driven-development`（推荐）或 `executing-plans` 子技能逐任务实现，且步骤使用 `- [ ]` checkbox 语法跟踪进度。 - **Goal / Architecture / Tech Stack**：分别用一句话、2-3 句、若干条目说明构建目标、方案思路与关键技术栈。 - **Global Constraints（全局约束）**：这是 spec 中项目级要求的逐行誊写——版本下限、依赖限制、命名与文案规则、平台要求——每行一条，**精确值必须从 spec 原样照抄**。该节的所有内容被每个任务**隐式包含**，即每个任务都受其约束。 对照仓库真实文件即可验证这一规范。[2026-03-11-zero-dep-brainstorm-server.md](https://link.gitcode.com/i/d70e58f5a3409c09cf67af6ffadb17e9) 的头部为： ```markdown # Zero-Dependency Brainstorm Server Implementation Plan > **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Replace the brainstorm server's vendored node_modules with a single zero-dependency `server.js` using Node built-ins. **Architecture:** Single file with WebSocket protocol (RFC 6455 text frames), HTTP server (`http` module), and file watching (`fs.watch`). Exports protocol functions for unit testing when required as a module. **Tech Stack:** Node.js built-ins only: `http`, `crypto`, `fs`, `path` **Spec:** `docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`

2026-04-06-worktree-rototill.md 的 Architecture 一句则典型体现了"计划文档可以修改技能文件本身"的元特性："These are markdown skill instruction files, not application code — 'tests' are agent behavior tests using the testing-skills-with-subagents TDD framework."——该计划对技能文件本身做 TDD，"测试"是基于 testing-skills-with-subagents 框架 的 Agent 行为测试（见 tests/claude-code/ 下的测试脚本）。

七、任务结构模板（Task Structure）

计划中的每个任务采用统一模板。以下完整继承自 SKILL.md：

### 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` **Interfaces:** - Consumes: [what this task uses from earlier tasks — exact signatures] - Produces: [what later tasks rely on — exact function names, parameter and return types. A task's implementer sees only their own task; this block is how they learn the names and types neighboring tasks use.] - [ ] **Step 1: Write the failing test** ```python def test_specific_behavior(): result = function(input) assert result == expected ``` - [ ] **Step 2: Run test to verify it fails** Run: `pytest tests/path/test.py::test_name -v` Expected: FAIL with "function not defined" - [ ] **Step 3: Write minimal implementation** ```python def function(input): return expected ``` - [ ] **Step 4: Run test to verify it passes** 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" ```

模板各部分的工程设计意图：

• Files 块：精确到文件路径（Create / Modify / Test 三类），Modify 甚至精确到行号范围（如existing.py:123-145）。零上下文的执行者不需要"找一找"，直接按路径定位。
• Interfaces 块：这是任务间的契约。由于 subagent 驱动模式下"任务的实现者只能看到自己的任务"，Interfaces 块是相邻任务之间传递精确函数名、参数与返回类型的唯一通道。Consumes 声明本任务从更早任务消费什么（精确签名），Produces 声明后续任务依赖什么。
• Step 2 的 Expected: FAIL：失败测试必须先确认失败，这是 TDD 的关键校验——防止写出恒真测试或误判环境。
• Step 5 的 Commit：每个任务以提交收尾，保证频繁提交、每个任务在 git 历史中可独立追踪。subagent-driven-development 的评审包正是基于 commit 区间（BASE..HEAD）生成的。

八、No Placeholders：占位符是计划的失败

SKILL.md 用"plan failures"（计划失败）这一措辞列出永远不得写入的模式：

• "TBD"、"TODO"、"implement later"、"fill in details"；
• "Add appropriate error handling" / "add validation" / "handle edge cases"——笼统的"加错误处理/校验/边界处理"；
• "Write tests for the above"（不给真实测试代码）；
• "Similar to Task N"（要求把代码重复写出来——工程师可能不按顺序读任务）；
• 只描述做什么、不展示怎么做的步骤（代码步骤必须配代码块）；
• 引用任何任务中都不存在的类型、函数或方法。

"Similar to Task N" 一条尤其值得注意：它针对的正是 subagent 执行模式下每个任务只看到自己任务文本的现实，因此跨任务的"参见"引用会被视为缺陷。

九、Self-Review：写完计划后的三步自查

计划写完后，要以全新视角对照 spec 检查。技能强调：这是你自己运行的清单，不是派发 subagent 去做的（与后面第六节的外部评审形成内外两道门）。

1. Spec coverage（规格覆盖）：通读 spec 的每个章节/要求，能否指出实现它的任务？列出缺口。
2. Placeholder scan（占位符扫描）：在计划中搜索上一节列出的红旗模式，发现即修复。
3. Type consistency（类型一致性）：后续任务中使用的类型、方法签名、属性名，是否与早期任务中的定义一致？技能给的例子很直观：Task 3 里叫clearLayers()，Task 7 里变成clearFullLayers()，就是 bug。

发现问题就原地修复，无需重新评审——"just fix and move on"。如果发现 spec 要求没有对应任务，就补上该任务。

十、计划评审：plan-document-reviewer-prompt

除了自查，writing-plans 技能目录还附带一份 plan-document-reviewer-prompt.md 模板，用于在完整计划写完后派发计划评审 subagent（general-purpose）。该模板规定评审者核对四个维度：

模板同时给出校准规则（Calibration）：只标记会在实现中造成真实问题的缺陷——"实现者构建出错误的东西或卡住"才算问题；措辞、风格偏好、"锦上添花"建议不算。原则上"除非存在严重缺口——缺失 spec 要求、步骤自相矛盾、占位内容、任务模糊到无法执行——否则予以批准"。输出格式固定为：

## Plan Review **Status:** Approved | Issues Found **Issues (if any):** - [Task X, Step Y]: [specific issue] - [why it matters for implementation] **Recommendations (advisory, do not block approval):** - [suggestions for improvement]

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers