✨ feat(workflow): add superpowers planning and execution state tracking

2026-05-18 16:28:06 +08:00
parent c1702a667a
commit 234b335663
11 changed files with 1287 additions and 310 deletions
@@ -9,235 +9,278 @@
 3. 仓库规则：`.agents/` 与 `AGENTS.md`
 4. 本文件

-## 安全红线
+## 安全与沟通

- 不得在代码/日志/注释中写入明文密钥、密码、Token
- 修改鉴权/权限逻辑必须说明动机与风险
- 不确定是否敏感时按敏感信息处理
- 执行修改文件系统的命令前，必须解释目的和潜在影响
+### 安全红线

-## 行为准则
+- 不得在代码、日志或注释中写入明文密钥、密码、Token
+- 修改鉴权、权限或敏感数据流时，必须说明动机与风险
+- 不确定是否敏感时，一律按敏感信息处理
+- 执行会修改文件系统的命令前，必须说明目的与潜在影响

-### 项目适应
+### 沟通原则

- **模仿项目风格**：优先分析周围代码和配置，遵循现有约定
- **不假设可用性**：不假设库或框架可用，先验证再使用
- **完整完成请求**：不遗漏用户要求的任何部分
+- 统一使用简体中文
+- 专业、直接、简洁，避免对话填充词
+- 发现用户理解有误时，礼貌纠正
+- 无法满足请求时，简洁说明原因并提供替代方案
+- 不给时间估算，专注事实、风险与下一步
+- 代码块必须标注语言类型
+- 不使用 emoji，除非用户明确要求

-### 技术态度
+## 工作原则

- **准确性优先**：技术准确性优先于迎合用户
- **诚实纠正**：发现用户理解有误时，礼貌纠正
- **先查后答**：不确定时先调查再回答
+- 模仿项目现有风格，先看周围代码、配置和测试再动手
+- 不假设库、框架或命令可用，先验证再使用
+- 完整覆盖用户请求，不遗漏边界条件和收尾工作
+- 技术准确性优先于迎合；不确定时先调查再回答
+- 只做当前任务需要的改动，不顺手加功能、不顺手重构
+- 不为一次性操作增加抽象，不为假设的未来需求设计

-### 避免过度工程
+## 会话启动

- **只做要求的**：不主动添加未要求的功能或重构
- **不过度抽象**：不为一次性操作创建工具函数
- **不为未来设计**：不为假设的未来需求设计
+每次新会话开始时，按顺序加载以下上下文：

-## 沟通原则
+1. `AGENT_RULES.local.md`：项目私有规则（如存在）
+2. `.agents/index.md`：语言规则与工具入口（如存在）
+3. `memory-bank/project-brief.md`：项目定位、边界、约束
+4. `memory-bank/tech-context.md`：技术上下文、工具链、验证命令
+5. `memory-bank/system-patterns.md`：系统模式、边界与不变量
+6. `memory-bank/active-context.md`：当前目标、最近变更、下一步
+7. `memory-bank/decisions.md`：重要决策记录（如存在）
+8. `memory-bank/progress.md`：执行进度与 Plan 状态（如存在）
+9. `docs/superpowers/specs/`：最新设计稿（如存在）
+10. `docs/superpowers/plans/`：相关实施计划（如存在）

- **统一简体中文**：所有回复均使用简体中文
- **简洁直接**：专业、直接、简洁，避免对话填充词
- **拒绝时提供替代**：无法满足请求时，简洁说明并提供替代方案
- **不给时间估算**：专注任务本身，让用户自己判断时间
- **代码块标注语言**：输出代码时标注语言类型
- **不使用 emoji**：除非用户明确要求
+目的：快速建立项目全貌，避免重复解释和重复试错。

-## 上下文加载（每次会话开始）
+## 规划与执行模型

-**必读文档**（按顺序）：
+- 头脑风暴使用 `$brainstorming`，产出
+  `docs/superpowers/specs/*-design.md`
+- 实施计划使用 `$writing-plans`，产出
+  `docs/superpowers/plans/*.md`
+- Plan 生命周期由 `main_loop.py` 协调，并通过
+  `memory-bank/progress.md` 留痕
+- 默认执行器是 `$executing-plans`
+- 代码类执行必须同时遵循：
+  `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`

-1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件）
-2. `.agents/index.md` - 语言规则入口（如存在）
-3. `memory-bank/project-brief.md` - 项目定位、边界、约束
-4. `memory-bank/tech-stack.md` - 技术栈、工具链
-5. `memory-bank/architecture.md` - 架构设计、模块职责
-6. `memory-bank/decisions.md` - 重要决策记录（如存在）
-7. `memory-bank/progress.md` - 执行进度与状态（如存在）
-8. `docs/plans/` - 最新实施计划（如存在）
+重要约束：

-**目的**：让 AI 快速理解项目全貌，避免重复解释。
+- 规划阶段必须走 `using-superpowers -> brainstorming -> writing-plans`
+- `brainstorming` 写出 spec 后，立即用 `playbook.py -record-spec`
+  记录 `phase=planning` 与 `spec=<path>`
+- `writing-plans` 写出 plan 后，立即用 `playbook.py -record-plan`
+  记录 `plan=<path>`、`executor=executing-plans`、
+  `constraints=karpathy-guidelines,.agents,AGENT_RULES`
+- 未领取 Plan 前，不得直接进入 `$executing-plans`
+- 已领取 Plan 后，默认执行使用 `$executing-plans`
+- `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用，
+  不是默认执行器
+- 执行完成后，必须先运行 `main_loop.py finish` 写回状态，
+  再更新 `progress.md` 上半部分摘要

-## 规划与执行分工
+### Plan 要求

-| 阶段         | 工具                   | 产出              | 留痕                       |
-| ------------ | ---------------------- | ----------------- | -------------------------- |
-| 头脑风暴     | `$brainstorming` skill | 设计思路          | 无                         |
-| 生成计划     | `$writing-plans` skill | `docs/plans/*.md` | 无                         |
-| **执行计划** | **`main_loop.py` 主循环** | 代码/配置变更     | **`memory-bank/progress.md`** |
+- `Plan Meta` 必填，位于 Plan 头部 `---` 之后、Task 1 之前
+- `Plan Meta` 至少包含：
+  - `Plan Group`
+  - `Parent Plan`
+  - `Verification Scope`
+  - `Verification Gate`
+- Plan 中不得包含必然失败或依赖未确认的信息
+- 未确认项必须在 `$brainstorming` 阶段解决后，才能产出 Plan
+- Plan 内验证必须是当前阶段可通过的局部验证
+- 需要集成验证的内容，放入上层或集成 Plan
+- Plan 生成完成后，执行入口只能是主循环
+- 代码类 Plan 应显式声明执行约束：
+  `karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`
+- 不因等待确认而中断可执行步骤；待确认事项写入回复
+- 每个 Plan 应小步、可验证、可快速完成

-> **重要**：第三方 skills 只用于规划，不负责执行留痕。收到执行触发词后，不得直接使用 `$executing-plans`，也不得直接使用 `$subagent-driven-development`；必须先运行 `main_loop.py claim` 领取 Plan，再通过 `main_loop.py finish` 写回结果。
+## 主循环执行契约

-## 主循环
+### 触发方式

-**触发词**：
+- 常规模式：`执行主循环`、`继续执行`、`下一个 Plan`
+- 无交互模式：`自动执行所有 Plan`

-| 触发词                                  | 模式       | 说明                   |
-| --------------------------------------- | ---------- | ---------------------- |
-| `执行主循环`、`继续执行`、`下一个 Plan` | 常规模式   | 遇确认场景可询问用户   |
-| `自动执行所有 Plan`                     | 无交互模式 | 不询问，按规则自动处理 |
+### Plan 状态

-**Plan 状态**：
+- `pending`：待执行
+- `in-progress`：执行中，用于恢复中断任务
+- `done`：已完成
+- `blocked`：阻塞，需人工介入或切换环境
+- `skipped`：永久跳过，不再执行

-| 状态        | 含义                      |
-| ----------- | ------------------------- |
-| pending     | 待执行                    |
-| in-progress | 执行中（崩溃恢复用）      |
-| done        | 已完成                    |
-| blocked     | 阻塞（需人工介入）        |
-| skipped     | 跳过（Plan 不再需要执行） |
+`skipped` 如需恢复，必须手动改回 `pending`。

-> 说明：`skipped` 仅用于永久不再执行；如需恢复执行，需手动改回 `pending`。
+### 环境阻塞格式

-**环境阻塞格式**：`blocked: env:<环境>:<Task列表>`
+- 格式：`env:<环境>:<Task列表>`
+- 示例：`env:windows:Task2,Task4`
+- `Task` 列表必须使用英文逗号分隔，且不要包含空格

- 示例：`blocked: env:windows:Task2,Task4`
- 含义：需要在指定环境执行列出的 Task
- 约束：`Task` 列表使用英文逗号分隔，不要包含空格，便于解析
+### 领取与写回

-**流程**：
+领取命令：

-1. 领取 Plan：
-   - 运行 `python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim -plans docs/plans -progress memory-bank/progress.md`
-   - 该命令会**原子化**完成三件事：
-     - 自动识别当前环境（`windows` / `linux` / `darwin`）
-     - 选择第一个可执行的 Plan（优先恢复 `in-progress`，其次 `pending`，最后 `blocked: env:<当前环境>:...`）
-     - 将选中的 Plan 写成 `in-progress`
-   - stdout 必须包含 `PLAN=<path>`；如果是从环境阻塞恢复，还会附带 `NOTE=env:<环境>:<Task列表>`
-   - 如无可执行 Plan，跳到步骤 6
-2. 阅读领取结果：
-   - 记录 `PLAN=` 返回的路径
-   - 如果 stdout 含 `NOTE=env:...`，本轮只执行列出的 Task
-3. 阅读 Plan：
-   - 理解目标、子任务与验证标准
-   - **注意**：Plan 文档中的 execution handoff / REQUIRED SUB-SKILL 仅作参考；如与本文件冲突，一律以主循环为准
-4. 逐步执行：
-   - 按顺序执行 Task
-   - 每个 Task 完成后进行必要验证（测试/日志/diff）
-   - **Task 失败处理**：
-     - 环境不匹配（`command not found`、路径不存在）→ 记录该 Task 及所需环境，**继续下一个 Task**
-     - 其他阻塞 → 记录原因，跳到步骤 6 标记 Plan blocked
-   - **安全红线**（明文密钥等）→ 立即停止，不继续后续 Plan
-   - 遇到歧义/风险/决策点：
-     - 常规模式：记录到回复中，可询问用户
-     - 无交互模式：按「需要确认的场景」规则自动处理
-5. 写回结果：
-   - 全部完成：
-     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status done -progress memory-bank/progress.md`
-   - 有 Task 因环境跳过：
-     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status blocked -progress memory-bank/progress.md -note "env:<所需环境>:<Task列表>"`
-   - 其他阻塞：
-     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status blocked -progress memory-bank/progress.md -note "<原因>"`
-   - 跳过整个 Plan：
-     - `python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish -plan <plan> -status skipped -progress memory-bank/progress.md -note "<原因>"`
-   - 写回后回到步骤 1 继续下一个 Plan
-6. 汇总报告（所有 Plan 处理完毕后）：
-   - 已完成的 Plan
-   - 阻塞/跳过的 Plan 及原因
-   - 需要在其他环境执行的 Plan（`blocked: env:...`）
-   - 待确认的歧义/风险/决策点
-   - 如需记录重要决策，写入 `memory-bank/decisions.md`
-7. **结束**：主循环终止
+```bash
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
+  -plans docs/superpowers/plans \
+  -progress memory-bank/progress.md
+```

-## Plan 规则
+该命令会在锁保护下串行完成三件事：

- **Plan Meta 必填**：Plan 头部 `---` 之后、Task 1 之前插入 `## Plan Meta`，包含：
-  - `Plan Group`（归类任务）
-  - `Parent Plan`（上层/集成计划链接）
-  - `Verification Scope`（local 或 integration）
-  - `Verification Gate`（must-pass）
- **不允许中断任务**：Plan 中不应包含必然失败或依赖未确认的信息；未确认项必须在 `$brainstorming` 阶段解决后再产出 Plan
- **验证必须可通过**：Plan 内验证应为当前阶段可通过的局部验证；需要集成验证的内容放入上层/集成 Plan
- **执行入口唯一**：Plan 生成完成后，后续执行只能由主循环驱动；不得按 Plan 头部说明直接切换到 `$executing-plans` 或 `$subagent-driven-development`
- 不因等待确认而中断可执行步骤；待确认事项在回复中列出
- 每轮只处理一个 Plan
- **小步快跑**：每个 Plan 应该可快速完成
- **可验证**：每个 Plan 必须包含验证步骤
+- 自动识别当前环境：`windows`、`linux`、`darwin`
+- 按顺序选择可执行 Plan：
+  `in-progress` > `pending` > `blocked: env:<当前环境>:...`
+- 将选中的 Plan 写成 `in-progress`

-## 复利工程
+这里的锁保护的是 `progress.md` 状态块更新，避免多个 session
+同时读写时发生覆盖。

-每次 Session 结束时：
+stdout 必须包含：

- **同一错误发生 2 次以上** → 立即更新 `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`，避免下次重蹈
- **发现项目特有规律**（如特定模块的注意事项、常见陷阱）→ 沉淀到 `AGENT_RULES.local.md`
+- `PLAN=<path>`
+- 如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`

-> 目标：让每次 Session 的起点比上次更高。
+规划与执行留痕示例：

-## 执行约束
+```bash
+# brainstorming 完成后
+python {{PLAYBOOK_SCRIPTS}}/playbook.py \
+  -record-spec docs/superpowers/specs/<topic>-design.md \
+  -progress memory-bank/progress.md
+```

-### 代码修改
+```bash
+# writing-plans 完成后
+python {{PLAYBOOK_SCRIPTS}}/playbook.py \
+  -record-plan docs/superpowers/plans/<topic>.md \
+  -progress memory-bank/progress.md
+```

- **必须先读文件再修改**：不读文件就提议修改是禁止的
- **必须运行测试验证**：相关测试必须通过
- **遵循换行规则**：遵循 `.gitattributes` 规则
- **命名一致性**：遵循项目现有的命名风格
- **最小改动原则**：只修改必要的部分，不顺手重构
+写回命令示例：

-### 决策记录
+```bash
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
+  -plan <plan> \
+  -status done \
+  -progress memory-bank/progress.md
+```

- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
- **待确认事项**：在回复中列出并等待确认
- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/main_loop.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威）
+```bash
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
+  -plan <plan> \
+  -status blocked \
+  -progress memory-bank/progress.md \
+  -note "env:<所需环境>:<Task列表>"
+```
+
+```bash
+python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
+  -plan <plan> \
+  -status blocked|skipped \
+  -progress memory-bank/progress.md \
+  -note "<原因>"
+```
+
+### 执行规则
+
+1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容
+2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task
+3. 默认执行器是 `$executing-plans`；代码类任务在执行前必须显式
+   加载 `karpathy-guidelines`
+4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan 本身；
+   如发生冲突，以优先级更高的规则为准
+5. 按顺序执行 Task，并完成 Plan 约定的验证
+6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan
+   其余可执行 Task
+7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped`
+8. 触碰安全红线时立即停止，不继续后续 Plan
+9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件
+   的“需要确认的场景”自动处理
+10. 每次 `claim` 只领取一个 Plan；写回后再领取下一个
+11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
+    环境需求与待确认事项
+
+## 通用执行约束
+
+### 代码与配置修改
+
+- 必须先读文件再修改
+- 遵循 `.agents/`、项目代码风格和现有命名约定
+- 只改必要部分，不顺手重构无关内容
+- 执行与改动相称的验证；如有相关测试且未被豁免，必须通过
+- 遵循 `.gitattributes` 等换行与文件格式规则
+
+### 决策与留痕
+
+- 重要决策记录到 `memory-bank/decisions.md`
+- 待确认事项在回复中显式列出
+- `workflow-state` 和 `plan-status` 只能通过
+  `{{PLAYBOOK_SCRIPTS}}/main_loop.py` 维护
+- `progress.md` 上半部分的人类摘要在阶段变化或执行结束后同步更新
+- 同一错误重复两次以上时，立即更新
+  `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`
+- 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md`

 ### Git 操作

- **不使用 --amend**：除非用户明确要求，总是创建新提交
- **不使用 --force**：特别是推送到 main/master，如用户要求必须警告风险
- **不跳过 hooks**：不使用 `--no-verify`
+- 不使用 `--amend`，除非用户明确要求
+- 不使用 `--force`；如用户坚持，必须先说明风险
+- 不使用 `--no-verify` 跳过 hooks

-## 工具使用
+### 工具使用

- **并行执行**：独立的工具调用尽可能并行执行
- **遵循 schema**：严格遵循工具参数定义
- **避免循环**：避免重复调用同一工具获取相同信息
- **优先专用工具**：文件操作用专用文件工具（非 cat/sed），搜索用专用搜索工具（非 grep/find）
-
-## Context 管理
-
-以下情况应建议用户**开启新 Session**：
-
- 当前方向明显跑偏，需要从头重新理解需求
- 讨论阶段产生了多个候选方案，进入执行阶段时应清空对话
- Session 过长导致注意力涣散，重复犯同类错误
-
-> 新 Session 在干净 context 下工作效果更好；切换不是失败，是重置起点。
+- 独立步骤尽可能并行执行
+- 严格遵循工具参数定义与 schema
+- 优先使用专用工具，不重复探测同一信息
+- 文本搜索优先使用 `rg`

 ## 需要确认的场景

-**常规模式**（可交互）：
+### 常规模式

- 需求不明确或存在多种可行方案
- 需要行为/兼容性取舍
- 风险或约束冲突
- **架构变更**：影响多个模块的修改
- **性能权衡**：需要在性能和可维护性之间选择
- **兼容性问题**：可能破坏现有用户代码
+- 需求不明确，或存在多种可行方案
+- 需要行为、兼容性或性能取舍
+- 涉及架构变更、破坏性修改或约束冲突
+- 风险较高，且继续执行可能放大返工成本

-**无交互模式**（自动处理）：
+### 无交互模式

-| 场景                       | 处理方式                           |
-| -------------------------- | ---------------------------------- |
-| 安全红线                   | 立即停止，不继续后续 Plan          |
-| 架构变更/兼容性/破坏性修改 | 标记 blocked，跳到下一个 Plan      |
-| 多种可行方案               | 选择最保守方案，记录选择理由到报告 |
-| 歧义/风险/决策点           | 记录到报告，继续执行               |
+- 安全红线：立即停止，不继续后续 Plan
+- 架构变更、兼容性问题、破坏性修改：写回 `blocked`
+- 多种可行方案：选择最保守方案，并在报告中说明理由
+- 一般歧义、风险或决策点：记录到报告，继续执行安全部分

-**可以不确认**（两种模式通用）：
+### 可以直接执行

 - 明显的 bug 修复
 - 符合现有模式的小改动
- 测试用例补充
+- 测试用例补充或局部验证补齐
+
+## Session 收尾
+
+- 汇总已完成、阻塞、跳过的 Plan 及原因
+- 标出需要其他环境处理的事项：`env:<环境>:<Task列表>`
+- 必要时将重要结论写入 `memory-bank/decisions.md`
+- 出现以下情况时，建议开启新 Session：
+  - 当前方向明显跑偏
+  - 讨论阶段产出多个候选方案，准备进入执行
+  - Session 过长，开始重复犯同类错误

 ## 验证清单

-每个 Plan 完成后，必须验证：
+每个 Plan 完成后，至少确认：

 - [ ] 代码修改符合 `.agents/` 下的规则（如有）
- [ ] 相关测试通过（如有测试且未被豁免）
- [ ] 换行符正确
- [ ] 无语法错误
+- [ ] 相关验证已执行，且测试在未豁免时通过
+- [ ] 换行符与文件格式正确
+- [ ] 无语法错误或明显运行时错误
 - [ ] 已通过 `main_loop.py finish` 写回 Plan 状态

 ---