diff --git a/.gitignore b/.gitignore index c4c752d2..6689d177 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ tags reports/ .worktrees/ tmp/ +docs/superpowers/ scripts/__pycache__ tests/__pycache__ diff --git a/README.md b/README.md index 922e6164..0d975fb5 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,9 @@ Playbook：工程规范与代理规则合集，当前覆盖： `templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板： - `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-context、system-patterns、active-context、progress、decisions） -- `templates/prompts/`：工作流入口模板（agent-behavior、clarify、verify-change、close-task、update-memory、code-review） -- `templates/AGENTS.template.md`：路由中心模板（项目主入口） -- `templates/AGENT_RULES.template.md`：执行流程模板 +- `templates/prompts/`：任务入口模板（agent-behavior、clarify、verify-change、close-task、update-memory、code-review），不是流程权威 +- `templates/AGENTS.template.md`：入口导航模板（项目主入口） +- `templates/AGENT_RULES.template.md`：superpowers-first 执行规则模板 ### 快速部署 @@ -95,6 +95,14 @@ python /scripts/playbook.py \ `memory-bank/progress.md`。 真正执行 Plan 仍然走 `main_loop.py claim/finish`。 +完整主链只在 `templates/AGENT_RULES.template.md` 定义，这里不重复展开。 +如果项目采用 `superpowers`： + +- 设计产物落到 `docs/superpowers/specs/` +- 计划产物落到 `docs/superpowers/plans/` +- 状态留痕通过 `playbook.py -record-spec/-record-plan` 与 + `main_loop.py claim/finish` 维护 + 详见：`templates/README.md` ## rulesets/（规则集模板库 - 三层架构） @@ -271,6 +279,7 @@ git commit -m ":package: deps(playbook): add tsl standards" ``` 2. 在目标项目根创建 `playbook.toml`，并用 `deploy_root` 指定项目内的部署根。例如： + - `project_root` 写目标项目根目录。 - `deploy_root` 写目标项目内的相对路径。 - 不要把外部 clone 的路径（如 `/opt/playbook`）写进 `deploy_root`；那只是你执行脚本的位置。 diff --git a/templates/AGENTS.template.md b/templates/AGENTS.template.md index 911ff687..e2346c51 100644 --- a/templates/AGENTS.template.md +++ b/templates/AGENTS.template.md @@ -21,9 +21,9 @@ - [memory-bank/active-context.md](memory-bank/active-context.md) - 当前上下文 - [memory-bank/progress.md](memory-bank/progress.md) - 进度追踪 -### 工作流入口 +### 任务入口 -- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与流程入口 +- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与任务入口 diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md index 9d7e2443..f80a0c68 100644 --- a/templates/AGENT_RULES.template.md +++ b/templates/AGENT_RULES.template.md @@ -2,6 +2,10 @@ 目的：为本仓库提供稳定的执行流程与行为规范。 +本文件是项目内唯一流程约束中心；`docs/superpowers/` +是唯一设计与计划产物中心；执行状态统一写回 +`memory-bank/progress.md`。 + ## 优先级 1. 系统/开发者指令与安全约束 diff --git a/templates/README.md b/templates/README.md index 79af571b..e56e8c4f 100644 --- a/templates/README.md +++ b/templates/README.md @@ -1,14 +1,15 @@ # 项目架构模板 -本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。 +本目录包含以 `superpowers` 为基石的项目模板，用于快速初始化新项目的 +AI 代理工作环境。 ## 目录结构 ```text templates/ ├── README.md # 本文件 -├── AGENTS.template.md # 路由中心模板 -├── AGENT_RULES.template.md # 执行流程模板 +├── AGENTS.template.md # 入口导航模板 +├── AGENT_RULES.template.md # superpowers-first 执行规则模板 ├── memory-bank/ # 项目上下文模板 │ ├── project-brief.template.md │ ├── tech-context.template.md @@ -16,7 +17,7 @@ templates/ │ ├── active-context.template.md │ ├── progress.template.md │ └── decisions.template.md -├── prompts/ # 提示词库模板 +├── prompts/ # 任务入口模板（不是流程权威） │ ├── README.md │ ├── system/ │ │ └── agent-behavior.template.md @@ -48,6 +49,7 @@ templates/ - **会同步更新的框架模板** - `AGENT_RULES.md` + - `docs/prompts/README.md` - `docs/prompts/system/*.md` - `docs/prompts/coding/*.md` - `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新） @@ -69,6 +71,8 @@ templates/ 不会被 playbook 删除。 - `CLAUDE.md` 如已有 playbook 区块则更新；如未引用 `@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。 +- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/` + 只负责把代理导向正确的任务入口。 ## 快速部署 @@ -158,6 +162,12 @@ force = true ### docs/superpowers 命名约定 +`docs/superpowers/` 统一承载设计稿和实施计划： + +- 设计只落到 `specs/` +- 计划只落到 `plans/` +- 执行状态只写回 `memory-bank/progress.md` + 为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用： - `docs/superpowers/specs/YYYY-MM-DD--design.md`： @@ -169,28 +179,20 @@ force = true ### 生命周期总览 -```text -需求澄清 - -> using-superpowers - -> brainstorming - -> docs/superpowers/specs/*.md - -> playbook.py -record-spec - -> writing-plans - -> docs/superpowers/plans/*.md - -> playbook.py -record-plan - -> main_loop.py claim - -> executing-plans - -> [代码类任务] + karpathy-guidelines + .agents + AGENT_RULES - -> main_loop.py finish - -> update-memory / close-task -``` +完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。 +这里仅说明职责分层： + +- `docs/prompts/`：任务入口层，只负责把代理导向正确入口 +- `docs/superpowers/specs/`：设计稿 +- `docs/superpowers/plans/`：实施计划与主执行输入 +- `memory-bank/progress.md`：执行状态留痕 ### 部署后的目录结构 ```text project/ -├── AGENTS.md # 路由中心（Codex 入口） -├── AGENT_RULES.md # 执行流程 +├── AGENTS.md # 入口导航（Codex 入口） +├── AGENT_RULES.md # superpowers-first 执行规则 ├── AGENT_RULES.local.md # 项目私有规则（自动创建，项目维护） ├── CLAUDE.md # Claude Code 入口（按规则维护/追加 playbook 区块） ├── memory-bank/ # 项目上下文 @@ -201,7 +203,7 @@ project/ │ ├── progress.md │ └── decisions.md └── docs/ - ├── prompts/ # 提示词库 + ├── prompts/ # 任务入口层 │ ├── README.md │ ├── system/agent-behavior.md │ └── coding/ @@ -251,33 +253,37 @@ project/ ### prompts/ -工作流程模板（部署后去掉 `.template` 后缀）： +任务入口模板（部署后去掉 `.template` 后缀）： + +其中 `templates/prompts/README.md` 部署后对应 `docs/prompts/README.md`， +作为任务入口索引。 | 文件 | 用途 | 使用场景 | | ----------------------------------- | ------------ | ------------------- | -| `system/agent-behavior.template.md` | 工作流入口 | 选择执行路径 | +| `system/agent-behavior.template.md` | 入口路由模板 | 选择执行路径 | | `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 | | `coding/verify-change.template.md` | 变更验证模板 | 声称完成前验证 | | `coding/close-task.template.md` | 本轮收尾模板 | 一轮工作结束时 | | `coding/update-memory.template.md` | 回写记忆模板 | 上下文变化后回写 | -| `coding/code-review.template.md` | 代码评审流程 | 执行 MR/PR 代码评审 | +| `coding/code-review.template.md` | 代码评审入口 | 执行 MR/PR 代码评审 | ### AGENT_RULES.template.md -执行流程规范，定义 AI 的工作循环和约束。 +执行规则模板，定义 AI 的工作循环和约束。 如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]` 首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。 -计划编排与执行细节建议放在 `prompts/README.md` 或相关 workflow 文档中， +计划编排与执行细节统一指向 `docs/superpowers/`、 +`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`； 这里仅说明模板职责与部署边界。 ### AGENTS.template.md -路由中心模板，作为项目的主入口。 +入口导航模板，作为项目的主入口。 **设计理念**： - **最小化内容**：只包含导航链接，不包含详细规则 -- **结构化导航**：分为核心规则、项目上下文、工作流程三个板块 +- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块 **playbook 标记**（用于自动更新）： diff --git a/templates/memory-bank/project-brief.template.md b/templates/memory-bank/project-brief.template.md index 9c8b6c69..078e98a1 100644 --- a/templates/memory-bank/project-brief.template.md +++ b/templates/memory-bank/project-brief.template.md @@ -35,6 +35,13 @@ - {{CONSTRAINT_1}} +## 成功定义 + + + +- 功能完成的判定标准：{{SUCCESS_1}} +- 本轮不覆盖的内容：{{OUT_OF_SCOPE_1}} + ## 核心概念 diff --git a/templates/memory-bank/tech-context.template.md b/templates/memory-bank/tech-context.template.md index 5fd8efad..e664e204 100644 --- a/templates/memory-bank/tech-context.template.md +++ b/templates/memory-bank/tech-context.template.md @@ -61,6 +61,12 @@ - {{DEPENDENCY_OR_LIMIT_1}} +## 不可假设项 + + + +- {{DO_NOT_ASSUME_1}} + ## 验证约定 diff --git a/templates/prompts/README.md b/templates/prompts/README.md index d4a83396..dce305fe 100644 --- a/templates/prompts/README.md +++ b/templates/prompts/README.md @@ -1,6 +1,8 @@ # 提示词入口 -本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。 +本目录包含 AI 代理的任务入口模板，用于把任务路由到合适的执行路径。 +它是薄入口层，不是流程权威；完整流程与执行约束只在 +`AGENT_RULES.md` 定义。 ## 目录结构 @@ -8,13 +10,13 @@ prompts/ ├── README.md # 本文件 ├── system/ -│ └── agent-behavior.md # 工作流入口 +│ └── agent-behavior.md # 入口路由 ├── coding/ │ ├── clarify.md # 需求澄清模板 │ ├── verify-change.md # 变更验证模板 │ ├── close-task.md # 本轮收尾模板 │ ├── update-memory.md # 回写记忆模板 -│ └── code-review.md # MR/PR 代码评审流程 +│ └── code-review.md # MR/PR 代码评审入口 └── custom/ # 可选：项目私有提示词 ``` @@ -22,53 +24,31 @@ prompts/ | 模板 | 触发场景 | | --------------------- | -------------------- | -| **agent-behavior.md** | 选择工作流入口 | +| **agent-behavior.md** | 选择任务入口 | | **clarify.md** | 需求不明确时澄清 | | **verify-change.md** | 声称完成前做验证 | | **close-task.md** | 本轮工作收尾 | | **update-memory.md** | 上下文变化后回写记忆 | | **code-review.md** | 执行 MR/PR 代码评审 | -| **custom/*.md** | 项目私有补充流程 | +| **custom/\*.md** | 项目私有补充入口 | -## 工作流程 +## 入口边界 -```text -需求不清 → clarify.md - ↓ -入口约束 → using-superpowers - ↓ -头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md - ↓ -spec 完成后 → `playbook.py -record-spec -progress memory-bank/progress.md` - ↓ -生成计划 → $writing-plans skill → docs/superpowers/plans/*.md - ↓ -plan 完成后 → `playbook.py -record-plan -progress memory-bank/progress.md` - ↓ -领取计划 → `main_loop.py claim` - ↓ -执行计划 → `$executing-plans` - ↓ -代码类任务 → `karpathy-guidelines` + `.agents/` + `AGENT_RULES.md` - ↓ -写回状态 → `main_loop.py finish` - ↓ -更新摘要 → update-memory.md - ↓ -验证改动 → verify-change.md - ↓ -本轮收尾 → close-task.md - ↓ -代码评审（有 MR/PR 时）→ code-review.md -``` +- 需求不明确：看 `clarify.md` +- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md` +- 需要验证交付结果：看 `verify-change.md` +- 需要结束本轮并整理交付摘要：看 `close-task.md` +- 需要回写上下文：看 `update-memory.md` +- 需要评审 MR/PR：看 `code-review.md` +- 需要保留设计与计划产物：只写入 `docs/superpowers/` -> `coding/` 下是可被框架覆盖更新的标准模板； -> 项目私有流程应沉淀到 `custom/`。 +> `coding/` 下是可被框架覆盖更新的标准入口模板； +> 项目私有补充入口应沉淀到 `custom/`。 > -> `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`， -> 长期记忆在 `memory-bank/`，状态留痕必须走 -> `playbook.py -record-spec/-record-plan` 与 -> `main_loop.py claim/finish`。 +> `prompts/` 只负责把代理导向正确入口；`AGENT_RULES.md` +> 是唯一流程权威；`AGENT_RULES.local.md` 保存项目私有规则； +> `memory-bank/` 保存项目上下文与状态；`docs/superpowers/` +> 保存设计与计划产物。 --- diff --git a/templates/prompts/coding/clarify.template.md b/templates/prompts/coding/clarify.template.md index 6710d9d3..2b3633dd 100644 --- a/templates/prompts/coding/clarify.template.md +++ b/templates/prompts/coding/clarify.template.md @@ -1,51 +1,53 @@ # 需求澄清模板 ## 何时使用 - 需求描述不明确 -- 存在多种理解方式 -- 缺少关键信息 +- 存在多种合理理解方式 +- 缺少会改变实现路径的关键信息 ---- +## 先读 + +- `AGENT_RULES.md` +- `memory-bank/project-brief.md` +- `memory-bank/active-context.md` + +## 规则 + +- 每轮最多问 1 个问题 +- 只问会改变实现或验证路径的问题 +- 能低风险继续时，优先给出默认项后推进 +- 不重复询问已能从上下文推断的信息 ## 澄清步骤 -### 1. 复述需求 +1. 用自己的话复述当前理解 +2. 识别真正影响实现路径的歧义点 +3. 只提出 1 个最高价值问题 +4. 给出推荐默认项和理由 -```text -我理解你的需求是：[用自己的话复述] +## 输出协议 + +```markdown +## Current Understanding +- ... + +## Open Question +- ... + +## Recommended Default +- ... ``` -### 2. 识别歧义 +## 停止条件 -- 歧义 1：[描述不明确的地方] -- 歧义 2：[可能有多种理解的地方] - -### 3. 提出问题 - -> 只问阻塞问题，最多 1–2 个；优先给出选项让用户选择。 - -- 这个功能是否包括 [场景 A]？ -- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？ - -### 4. 提供选项 - -**选项 A**：[方案描述] - -- 优点：... -- 缺点：... - -**选项 B**：[方案描述] - -- 优点：... -- 缺点：... - -**推荐**：[推荐哪个，为什么] +- 已有足够信息可低风险推进时停止提问 +- 问题不影响实现路径时停止提问 --- diff --git a/templates/prompts/coding/close-task.template.md b/templates/prompts/coding/close-task.template.md index 7454e540..9895e694 100644 --- a/templates/prompts/coding/close-task.template.md +++ b/templates/prompts/coding/close-task.template.md @@ -1,59 +1,66 @@ # 收尾模板 ## 目标 确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。 +## 先读 + +- `AGENT_RULES.md` +- `memory-bank/active-context.md` +- `memory-bank/progress.md` + +## 规则 + +- 如果任务状态变更，优先通过 `main_loop.py finish` 留痕 +- 未验证内容必须显式说明 +- 只写对下一轮仍重要的信息 +- 不手工改写 `workflow-state` 或 `plan-status` 状态块 + ## 执行步骤 -### 1. 核对结果 +1. 核对已完成项与未完成项 +2. 核对已运行验证与未运行验证 +3. 核对 `main_loop.py finish` 是否已经写回 `plan-status` +4. 核对 `workflow-state.phase` 是否与当前结果一致 +5. 如需回写上下文，更新 `active-context`、`progress` 上半部分和 `decisions` +6. 输出本轮摘要与下一步 -- 已完成哪些改动？ -- 哪些内容仍未完成？ -- 是否存在阻塞、风险或待确认事项？ - -### 2. 核对验证 - -- 已运行哪些验证？ -- 哪些验证未运行，原因是什么？ -- 当前结果是否满足本轮交付标准？ - -### 3. 核对状态留痕 +## 状态留痕复核 - `main_loop.py finish` 是否已经写回 `plan-status` - `workflow-state.phase` 是否与当前结果一致 - 如为代码类执行，`workflow-state` 中是否保留了 `executor=executing-plans` 与既定 `constraints` -### 4. 回写上下文 - -- 需要写入 `memory-bank/active-context.md` 的信息 -- 需要写入 `memory-bank/progress.md` 上半部分摘要 -- 需要写入 `memory-bank/decisions.md` 的关键决策 - -### 5. 输出收尾摘要 +## 输出协议 ```markdown -## 本轮结果 +## Completed +- ... -- 已完成：... -- 未完成：... -- 验证：... -- 风险 / 待确认：... -- 下一步：... +## Not Completed +- ... + +## Verification +- ... + +## Risks +- ... + +## Next Steps +- ... ``` -## 原则 +## 停止条件 -- 只写对下一轮仍然重要的信息 -- 未验证的内容必须显式说明 -- 如果任务状态变更，优先通过 `main_loop.py finish` 留痕 -- 不手工改写 `workflow-state` 或 `plan-status` 状态块 +- 如状态未写回，先完成留痕再收尾 +- 如验证不足以支持交付，停止并标记风险 --- diff --git a/templates/prompts/coding/code-review.template.md b/templates/prompts/coding/code-review.template.md index a4c547de..20b7a6c8 100644 --- a/templates/prompts/coding/code-review.template.md +++ b/templates/prompts/coding/code-review.template.md @@ -1,4 +1,4 @@ -# Code Review 流程 +# Code Review 入口 ## 触发场景 @@ -20,62 +20,38 @@ gh pr view gh pr diff ``` -## 评审流程 +## 审查顺序 -逐步执行以下维度。改动简单时可跳过某些步骤。 +1. 先理解业务目标；目标不明确先要求补足上下文 +2. 优先审查 bug、风险、回归和缺失测试 +3. 再审查代码清晰度、KISS 和单一职责 +4. 最后汇总剩余风险与待确认项 -### 1. 理解业务目标 +## 规则 -- 能否理解本次改动的业务目标？ -- 如果目标不明确，先确认再评审。 +- Findings 优先，按严重度排序 +- 每条结论必须附文件路径、行号或可复现依据 +- 没有证据的问题按待确认假设处理 +- 评审不只看 diff，需结合代码库整体上下文 -### 2. High-level Review +## 输出协议 -- 改动是否放在了合适的位置？ -- 是否尽可能复用已有实现？ -- 是否有破坏现有设计与逻辑的可能？ +```markdown +## Findings +1. [severity] path - issue -### 3. Bug 检查 +## Open Questions +- ... -- 是否隐含业务错误、逻辑纰漏或安全问题？ -- **未修改**的相关联代码是否有遗漏？ +## Residual Risk +- ... +``` -### 4. 代码清晰度 +## 停止条件 -- 逻辑是否简洁易懂？ -- 命名是否清晰合理？ -- 一年后再读，是否能轻松理解？ +- 目标不明时停止并要求补足上下文 +- 缺少 diff 或无法读取关键上下文时停止并说明 -### 5. KISS 原则 +--- -- 是否有不必要的复杂度？ -- 是否有未使用的定义、过多参数？ -- 是否重复造轮子？ - -### 6. 单一职责 - -- 每个函数/类是否只做一件事？ -- 文件/类/方法行数是否合理？ - -### 7. 测试覆盖 - -- 复杂业务逻辑（含 if/else/for）是否有测试？ -- 测试是否有效（非空实现）？ -- 不应过度测试无控制逻辑的代码。 - -## 输出 - -评审完成后，总结发现的**重点问题**，按严重性排列。 - -## AI 与人工的分工 - -| 维度 | 负责方 | 说明 | -| -------------------------- | ------------- | ------------------------------------- | -| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 | -| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 | -| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 | -| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 | - -> 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。 -> -> 注意：评审不只看 diff，需结合代码库整体上下文做评估。 +**最后更新**：{{DATE}} diff --git a/templates/prompts/coding/update-memory.template.md b/templates/prompts/coding/update-memory.template.md index 167f06d0..dac9d71b 100644 --- a/templates/prompts/coding/update-memory.template.md +++ b/templates/prompts/coding/update-memory.template.md @@ -1,8 +1,8 @@ # 回写记忆模板 ## 什么时候需要回写 @@ -12,12 +12,17 @@ - 发现新的系统模式或约束 - 做出了值得保留的决策 -## 回写路径 +## 先读 + +- `memory-bank/active-context.md` +- `memory-bank/progress.md` +- `memory-bank/decisions.md` +- `memory-bank/system-patterns.md` + +## 回写目标 ### `memory-bank/active-context.md` -更新： - - 当前目标 - 最近变更 - touched files @@ -25,55 +30,55 @@ ### `memory-bank/progress.md` -更新： - - 先读取 `workflow-state`：当前阶段、spec、plan、executor、constraints - 再读取 `plan-status`：当前 Plan 的机器状态 -- Current Focus -- Recent Changes -- Next Steps -- Open Risks - -只更新上半部分的人类摘要，不修改状态块。 - -推荐写法： - -- `Current Focus`：当前阶段结束后，项目现在最重要的工作 -- `Recent Changes`：本轮实际完成的变更、写回的状态、关键验证结果 -- `Next Steps`：下一轮最自然的 1-3 个动作 -- `Open Risks`：仍未解决的阻塞、环境约束、待确认事项 - -禁止： - -- 手工改写 `` -- 手工改写 `` -- 把临时聊天内容、未验证猜测写进摘要 +- 只更新上半部分的人类摘要，不修改状态块 ### `memory-bank/decisions.md` -仅在出现重要决策时记录 ADR： - - 为什么这样做 - 备选方案是什么 - 影响范围是什么 ### `memory-bank/system-patterns.md` -仅在发现稳定模式时更新： - - 模块边界 - 不变量 - 扩展路径 - 禁止破坏的约束 -## 原则 +## 规则 - 只回写长期有价值的信息 - 临时聊天内容不要写进去 -- 高变化信息放 `active-context`，稳定约束放 `system-patterns` +- 高变化信息放 `active-context`，稳定技术模式放 `system-patterns` +- 流程规则或项目私有约束变更写入 `AGENT_RULES.local.md` - `progress.md` 的状态块只由 `main_loop.py` 维护 - 摘要应与 `workflow-state` / `plan-status` 保持一致 +## 禁止事项 + +- 手工改写 `` +- 手工改写 `` +- 把临时聊天内容、未验证猜测写进摘要 + +## 输出协议 + +```markdown +## Updated Files +- ... + +## New Context +- ... + +## Outstanding Risks +- ... +``` + +## 停止条件 + +- 如果没有值得沉淀的信息，则停止并说明 + --- **最后更新**：{{DATE}} diff --git a/templates/prompts/coding/verify-change.template.md b/templates/prompts/coding/verify-change.template.md index 5c39a9d2..96333222 100644 --- a/templates/prompts/coding/verify-change.template.md +++ b/templates/prompts/coding/verify-change.template.md @@ -1,38 +1,56 @@ # 变更验证模板 ## 验证目标 -- 这次改动要证明什么？ -- 哪些行为必须通过？ -- 哪些验证本轮不做？ +- 这次改动要证明什么 +- 哪些行为必须通过 +- 哪些验证本轮不做 + +## 先读 + +- `AGENT_RULES.md` +- `memory-bank/progress.md` +- 如存在：`docs/prompts/custom/verify.md` + +## 规则 + +- 没有证据，不宣称完成 +- 验证命令必须 fresh run +- 局部修改优先局部验证 +- 不能运行的验证必须写明原因 +- 不手工改写 `workflow-state` 或 `plan-status` 状态块 ## 验证步骤 -### 1. 语法 / 结构检查 +1. 做语法或结构检查，确认改动文件可读、可解析 +2. 运行与本次改动直接相关的验证命令 +3. 记录命令、结果和关键输出 +4. 复核 diff 是否只包含预期修改 +5. 复核 `workflow-state.phase`、`plan-status` 与当前声明一致 +6. 汇总未覆盖项和剩余风险 -- 确认修改文件可读、可解析、无明显结构错误 +## 输出协议 -### 2. 定向验证 +```markdown +## Validated +- ... -- 只跑与本次改动直接相关的验证命令 -- 记录命令、结果和关键输出 -- 如仓库存在项目私有验证提示词（例如 `docs/prompts/custom/verify.md`），先读取并执行其中的附加约束 +## Evidence +- ... -```bash -{{VERIFY_CMD}} +## Not Validated +- ... + +## Risks +- ... ``` -### 3. 差异复核 - -- 核对 diff 是否只包含预期修改 -- 确认没有误删、误改、命名漂移或路径漂移 - -### 4. 状态留痕复核 +## 状态留痕复核 - `workflow-state.phase` 是否与当前声明一致 - `plan-status` 是否已经通过 `main_loop.py finish` 写回 @@ -40,29 +58,10 @@ `executor=executing-plans` `constraints=karpathy-guidelines,.agents,AGENT_RULES` -### 5. 剩余风险 +## 停止条件 -- 本轮未覆盖的验证 -- 环境限制 -- 需要人工确认的点 - -## 输出格式 - -```markdown -## 验证结果 - -- 已验证：... -- 证据：... -- 未验证：... -- 风险：... -``` - -## 原则 - -- 没有证据，不宣称完成 -- 局部修改优先局部验证 -- 不能运行的验证要明确写原因 -- 不手工改写 `workflow-state` 或 `plan-status` 状态块 +- 关键验证失败时停止并汇报 +- 证据不足以支持“完成”结论时停止并汇报 --- diff --git a/templates/prompts/system/agent-behavior.template.md b/templates/prompts/system/agent-behavior.template.md index 64879b3b..7167f5d4 100644 --- a/templates/prompts/system/agent-behavior.template.md +++ b/templates/prompts/system/agent-behavior.template.md @@ -1,49 +1,27 @@ -# 工作流入口 +# 任务入口路由 ## 路由原则 - 需求不明确：先看 `docs/prompts/coding/clarify.md` -- 需要设计或拆解方案：走 - `using-superpowers` → `$brainstorming` → `$writing-plans` -- `brainstorming` 结束后：立即 - `playbook.py -record-spec -progress memory-bank/progress.md` -- `writing-plans` 结束后：立即 - `playbook.py -record-plan -progress memory-bank/progress.md` -- 需要执行已有 Plan：先 `main_loop.py claim`，再走 - `$executing-plans` -- 如为代码类执行：在 `$executing-plans` 前强制叠加 - `karpathy-guidelines`，并同时遵循 `.agents/` 与 `AGENT_RULES.md` +- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md` - 需要确认改动是否站得住：看 `docs/prompts/coding/verify-change.md` - 一轮工作收尾：看 `docs/prompts/coding/close-task.md` - 需要更新上下文：看 `docs/prompts/coding/update-memory.md` - 需要评审 MR/PR：看 `docs/prompts/coding/code-review.md` -## 最小工作流 - -```text -需求不清 -> clarify -需求明确 -> using-superpowers / brainstorming / writing-plans -brainstorming 完成 -> record planning/spec -writing-plans 完成 -> record plan/executor/constraints -进入执行 -> claim -> executing-plans -代码执行 -> + karpathy-guidelines + .agents + AGENT_RULES -执行结束 -> finish -> update-memory -准备交付 -> verify-change -本轮结束 -> close-task -上下文变化 -> update-memory -``` - -## 说明 +## 边界说明 - `prompts/` 是入口，不是规则权威 -- 稳定约束写入 `memory-bank/` 或 `AGENT_RULES.local.md` -- 执行留痕以 `memory-bank/progress.md` 的 - `workflow-state` 与 `plan-status` 为准 +- 完整流程与执行约束只在 `AGENT_RULES.md` +- 项目私有规则写入 `AGENT_RULES.local.md` +- 设计产物只放 `docs/superpowers/specs/` +- 计划产物只放 `docs/superpowers/plans/` +- 项目上下文与执行状态写入 `memory-bank/` --- diff --git a/tests/templates/validate_project_templates.sh b/tests/templates/validate_project_templates.sh index 044d9911..9a761d87 100644 --- a/tests/templates/validate_project_templates.sh +++ b/tests/templates/validate_project_templates.sh @@ -71,6 +71,8 @@ fi if validate_file_exists "$AGENT_RULES_TEMPLATE" "AGENT_RULES.template.md"; then validate_contains "$AGENT_RULES_TEMPLATE" "AGENT_RULES" "包含 AGENT_RULES 标题" validate_contains "$AGENT_RULES_TEMPLATE" "{{DATE}}" "包含 {{DATE}} 占位符" + validate_contains "$AGENT_RULES_TEMPLATE" "docs/superpowers/plans/" "包含 superpowers plans 路径" + validate_contains "$AGENT_RULES_TEMPLATE" "using-superpowers -> brainstorming -> writing-plans" "包含规划主链" fi validate_file_exists "$README_TEMPLATE" "templates/README.md" diff --git a/tests/test_deployment_routes_e2e.py b/tests/test_deployment_routes_e2e.py index ad05186a..2738c98a 100644 --- a/tests/test_deployment_routes_e2e.py +++ b/tests/test_deployment_routes_e2e.py @@ -57,6 +57,7 @@ class DeploymentRoutesE2ETests(unittest.TestCase): for rel in expected: with self.subTest(path=rel): self.assertTrue((project_root / rel).exists(), f"missing: {rel}") + self.assertFalse((project_root / "docs" / "workflows").exists()) def assert_docs_prefix(self, project_root: Path, docs_prefix: str) -> None: agents_index = (project_root / ".agents" / "index.md").read_text(encoding="utf-8") diff --git a/tests/test_sync_directory_actions.py b/tests/test_sync_directory_actions.py index 39b423bf..af7aa947 100644 --- a/tests/test_sync_directory_actions.py +++ b/tests/test_sync_directory_actions.py @@ -66,6 +66,7 @@ deploy_root = "{DEFAULT_DEPLOY_ROOT}" self.assertTrue(custom.exists()) self.assertTrue((prompts / "system" / "agent-behavior.md").is_file()) + self.assertFalse((root / "docs" / "workflows").exists()) def test_sync_memory_bank_force_overwrites_template_files_only(self): with tempfile.TemporaryDirectory() as tmp_dir: diff --git a/tests/test_sync_templates_placeholders.py b/tests/test_sync_templates_placeholders.py index e2372aca..895b4868 100644 --- a/tests/test_sync_templates_placeholders.py +++ b/tests/test_sync_templates_placeholders.py @@ -36,11 +36,18 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): ) self.assertNotIn("{{MAIN_LANGUAGE}}", templates_readme) self.assertNotIn("{{LANGUAGE_1}}", templates_readme) + self.assertNotIn("docs/workflows/", templates_readme) + self.assertNotIn("templates/workflows/", templates_readme) + self.assertIn("docs/superpowers/", templates_readme) + self.assertIn("docs/prompts/README.md", templates_readme) + self.assertIn("完整主链只在 `AGENT_RULES.template.md` 定义", templates_readme) agents_template = (ROOT / "templates" / "AGENTS.template.md").read_text( encoding="utf-8" ) self.assertNotIn("{{MAIN_LANGUAGE}}", agents_template) + self.assertIn("AGENT_RULES.md", agents_template) + self.assertIn("docs/prompts/README.md", agents_template) tech_context_template = ( ROOT / "templates" / "memory-bank" / "tech-context.template.md" @@ -48,36 +55,91 @@ class SyncTemplatesPlaceholdersTests(unittest.TestCase): self.assertNotIn("{{MAIN_LANGUAGE}}", tech_context_template) self.assertNotIn("{{LANGUAGE_1}}", tech_context_template) self.assertNotIn("**主要语言**", tech_context_template) + self.assertIn("## 不可假设项", tech_context_template) + + project_brief_template = ( + ROOT / "templates" / "memory-bank" / "project-brief.template.md" + ).read_text(encoding="utf-8") + self.assertIn("## 成功定义", project_brief_template) update_memory_template = ( ROOT / "templates" / "prompts" / "coding" / "update-memory.template.md" ).read_text(encoding="utf-8") self.assertIn("workflow-state", update_memory_template) self.assertIn("plan-status", update_memory_template) + self.assertIn("## Updated Files", update_memory_template) + self.assertIn("## New Context", update_memory_template) + self.assertIn("## Outstanding Risks", update_memory_template) + self.assertIn("AGENT_RULES.local.md", update_memory_template) close_task_template = ( ROOT / "templates" / "prompts" / "coding" / "close-task.template.md" ).read_text(encoding="utf-8") self.assertIn("main_loop.py finish", close_task_template) self.assertIn("workflow-state.phase", close_task_template) + self.assertIn("## Completed", close_task_template) + self.assertIn("## Not Completed", close_task_template) + self.assertIn("## Verification", close_task_template) + self.assertIn("## Risks", close_task_template) + self.assertIn("## Next Steps", close_task_template) verify_change_template = ( ROOT / "templates" / "prompts" / "coding" / "verify-change.template.md" ).read_text(encoding="utf-8") self.assertIn("workflow-state.phase", verify_change_template) self.assertIn("plan-status", verify_change_template) + self.assertIn("## Validated", verify_change_template) + self.assertIn("## Evidence", verify_change_template) + self.assertIn("## Not Validated", verify_change_template) + self.assertIn("## Risks", verify_change_template) + + clarify_template = ( + ROOT / "templates" / "prompts" / "coding" / "clarify.template.md" + ).read_text(encoding="utf-8") + self.assertNotIn("Vibe-coding", clarify_template) + self.assertIn("## Current Understanding", clarify_template) + self.assertIn("## Open Question", clarify_template) + self.assertIn("## Recommended Default", clarify_template) + + code_review_template = ( + ROOT / "templates" / "prompts" / "coding" / "code-review.template.md" + ).read_text(encoding="utf-8") + self.assertIn("## Findings", code_review_template) + self.assertIn("## Open Questions", code_review_template) + self.assertIn("## Residual Risk", code_review_template) prompts_readme = ( ROOT / "templates" / "prompts" / "README.md" ).read_text(encoding="utf-8") - self.assertIn("playbook.py -record-spec", prompts_readme) - self.assertIn("playbook.py -record-plan", prompts_readme) + self.assertIn("AGENT_RULES.md", prompts_readme) + self.assertIn("docs/superpowers/", prompts_readme) + self.assertIn("不是流程权威", prompts_readme) + self.assertNotIn("playbook.py -record-spec", prompts_readme) + self.assertNotIn("playbook.py -record-plan", prompts_readme) + self.assertNotIn("using-superpowers", prompts_readme) + self.assertNotIn("main_loop.py claim", prompts_readme) + self.assertNotIn("docs/workflows/", prompts_readme) + self.assertIn("设计与计划产物", prompts_readme) agent_behavior_template = ( ROOT / "templates" / "prompts" / "system" / "agent-behavior.template.md" ).read_text(encoding="utf-8") - self.assertIn("playbook.py -record-spec", agent_behavior_template) - self.assertIn("playbook.py -record-plan", agent_behavior_template) + self.assertIn("AGENT_RULES.md", agent_behavior_template) + self.assertIn("AGENT_RULES.local.md", agent_behavior_template) + self.assertIn("docs/superpowers/specs/", agent_behavior_template) + self.assertIn("docs/superpowers/plans/", agent_behavior_template) + self.assertNotIn("using-superpowers", agent_behavior_template) + self.assertNotIn("main_loop.py claim", agent_behavior_template) + self.assertNotIn("playbook.py -record-spec", agent_behavior_template) + self.assertNotIn("playbook.py -record-plan", agent_behavior_template) + self.assertIn("项目上下文与执行状态写入 `memory-bank/`", agent_behavior_template) + + rules_template = ( + ROOT / "templates" / "AGENT_RULES.template.md" + ).read_text(encoding="utf-8") + self.assertIn("唯一流程约束中心", rules_template) + self.assertIn("唯一设计与计划产物中心", rules_template) + self.assertIn("memory-bank/progress.md", rules_template) def test_sync_templates_replaces_playbook_scripts_without_main_language_support(self): with tempfile.TemporaryDirectory() as tmp_dir: