📝 docs(templates): refine superpowers prompt boundaries

.gitignore

@@ -22,6 +22,7 @@ tags
 reports/
 .worktrees/
 tmp/
+docs/superpowers/
 
 scripts/__pycache__
 tests/__pycache__

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/prompts/`：任务入口模板（agent-behavior、clarify、verify-change、close-task、update-memory、code-review），不是流程权威
-- `templates/AGENTS.template.md`：路由中心模板（项目主入口）
+- `templates/AGENTS.template.md`：入口导航模板（项目主入口）
-- `templates/AGENT_RULES.template.md`：执行流程模板
+- `templates/AGENT_RULES.template.md`：superpowers-first 执行规则模板
 
 ### 快速部署
 
@@ -95,6 +95,14 @@ python <deploy_root>/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`；那只是你执行脚本的位置。

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) - 提示词与任务入口
 <!-- playbook:templates:end -->
 
 <!-- playbook:framework:end -->

templates/AGENT_RULES.template.md

@@ -2,6 +2,10 @@
 
 目的：为本仓库提供稳定的执行流程与行为规范。
 
+本文件是项目内唯一流程约束中心；`docs/superpowers/`
+是唯一设计与计划产物中心；执行状态统一写回
+`memory-bank/progress.md`。
+
 ## 优先级
 
 1. 系统/开发者指令与安全约束

templates/README.md

@@ -1,14 +1,15 @@
 # 项目架构模板
 
-本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。
+本目录包含以 `superpowers` 为基石的项目模板，用于快速初始化新项目的
+AI 代理工作环境。
 
 ## 目录结构
 
 ```text
 templates/
 ├── README.md                    # 本文件
-├── AGENTS.template.md           # 路由中心模板
+├── AGENTS.template.md           # 入口导航模板
-├── AGENT_RULES.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-<topic>-design.md`：
@@ -169,28 +179,20 @@ force = true
 
 ### 生命周期总览
 
-```text
+完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。
-需求澄清
+这里仅说明职责分层：
-  -> using-superpowers
+
-  -> brainstorming
+- `docs/prompts/`：任务入口层，只负责把代理导向正确入口
-  -> docs/superpowers/specs/*.md
+- `docs/superpowers/specs/`：设计稿
-  -> playbook.py -record-spec
+- `docs/superpowers/plans/`：实施计划与主执行输入
-  -> writing-plans
+- `memory-bank/progress.md`：执行状态留痕
-  -> 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
-```
 
 ### 部署后的目录结构
 
 ```text
 project/
-├── AGENTS.md              # 路由中心（Codex 入口）
+├── AGENTS.md              # 入口导航（Codex 入口）
-├── AGENT_RULES.md         # 执行流程
+├── 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 标记**（用于自动更新）：
 

templates/memory-bank/project-brief.template.md

@@ -35,6 +35,13 @@
 
 - {{CONSTRAINT_1}}
 
+## 成功定义
+
+<!-- 【必填】至少写出本轮或本项目如何判断“完成” -->
+
+- 功能完成的判定标准：{{SUCCESS_1}}
+- 本轮不覆盖的内容：{{OUT_OF_SCOPE_1}}
+
 ## 核心概念
 
 <!-- 【可选】项目特有的术语或概念 -->

templates/memory-bank/tech-context.template.md

@@ -61,6 +61,12 @@
 
 - {{DEPENDENCY_OR_LIMIT_1}}
 
+## 不可假设项
+
+<!-- 【可选】记录 AI 不能默认成立、必须先验证的信息 -->
+
+- {{DO_NOT_ASSUME_1}}
+
 ## 验证约定
 
 <!-- 【可选】什么叫“验证通过” -->

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`
-需求不清 → clarify.md
+- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md`
-    ↓
+- 需要验证交付结果：看 `verify-change.md`
-入口约束 → using-superpowers
+- 需要结束本轮并整理交付摘要：看 `close-task.md`
-    ↓
+- 需要回写上下文：看 `update-memory.md`
-头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md
+- 需要评审 MR/PR：看 `code-review.md`
-    ↓
+- 需要保留设计与计划产物：只写入 `docs/superpowers/`
-spec 完成后 → `playbook.py -record-spec <path> -progress memory-bank/progress.md`
-    ↓
-生成计划 → $writing-plans skill → docs/superpowers/plans/*.md
-    ↓
-plan 完成后 → `playbook.py -record-plan <path> -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
-```
 
-> `coding/` 下是可被框架覆盖更新的标准模板；
+> `coding/` 下是可被框架覆盖更新的标准入口模板；
-> 项目私有流程应沉淀到 `custom/`。
+> 项目私有补充入口应沉淀到 `custom/`。
 >
-> `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`，
+> `prompts/` 只负责把代理导向正确入口；`AGENT_RULES.md`
-> 长期记忆在 `memory-bank/`，状态留痕必须走
+> 是唯一流程权威；`AGENT_RULES.local.md` 保存项目私有规则；
-> `playbook.py -record-spec/-record-plan` 与
+> `memory-bank/` 保存项目上下文与状态；`docs/superpowers/`
-> `main_loop.py claim/finish`。
+> 保存设计与计划产物。
 
 ---
 

templates/prompts/coding/clarify.template.md

@@ -1,51 +1,53 @@
 # 需求澄清模板
 
 <!--
-按需使用：当需求不明确或存在歧义时参考本模板。
+用途：当需求存在歧义时，只补齐会改变实现或验证路径的最小信息。
-Vibe-coding 场景下可跳过，直接开始实现。
+触发：需求不明确、存在两种以上合理实现路径、缺少关键约束时。
 -->
 
 ## 何时使用
 
 - 需求描述不明确
-- 存在多种理解方式
+- 存在多种合理理解方式
-- 缺少关键信息
+- 缺少会改变实现路径的关键信息
 
----
+## 先读
+
+- `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**：[方案描述]
-
-- 优点：...
-- 缺点：...
-
-**推荐**：[推荐哪个，为什么]
 
 ---
 

templates/prompts/coding/close-task.template.md

@@ -1,59 +1,66 @@
 # 收尾模板
 
 <!--
-用途：一轮实现或一个 Plan 结束后做收尾
+用途：一轮实现或一个 Plan 结束后形成可交付摘要，并把下一轮仍重要的信息留痕。
-触发：准备结束当前任务、切换上下文、交付结果前
+触发：准备结束当前任务、切换上下文、交付结果前。
 -->
 
 ## 目标
 
 确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。
 
+## 先读
+
+- `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` 状态块
 
 ---
 

templates/prompts/coding/code-review.template.md

@@ -1,4 +1,4 @@
-# Code Review 流程
+# Code Review 入口
 
 ## 触发场景
 
@@ -20,62 +20,38 @@ gh pr view <PR_NUMBER>
 gh pr diff <PR_NUMBER>
 ```
 
-## 评审流程
+## 审查顺序
 
-逐步执行以下维度。改动简单时可跳过某些步骤。
+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 原则
+---
 
-- 是否有不必要的复杂度？
+**最后更新**：{{DATE}}
-- 是否有未使用的定义、过多参数？
-- 是否重复造轮子？
-
-### 6. 单一职责
-
-- 每个函数/类是否只做一件事？
-- 文件/类/方法行数是否合理？
-
-### 7. 测试覆盖
-
-- 复杂业务逻辑（含 if/else/for）是否有测试？
-- 测试是否有效（非空实现）？
-- 不应过度测试无控制逻辑的代码。
-
-## 输出
-
-评审完成后，总结发现的**重点问题**，按严重性排列。
-
-## AI 与人工的分工
-
-| 维度                       | 负责方        | 说明                                  |
-| -------------------------- | ------------- | ------------------------------------- |
-| Bug、逻辑漏洞、安全问题    | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
-| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳     |
-| 架构合理性、业务对齐       | **人工**      | AI 反馈少且准确率低，需人工把关       |
-| 兼容性、历史债务、战略取舍 | **人工**      | 依赖背景知识，AI 难以判断             |
-
-> 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。
->
-> 注意：评审不只看 diff，需结合代码库整体上下文做评估。

templates/prompts/coding/update-memory.template.md

@@ -1,8 +1,8 @@
 # 回写记忆模板
 
 <!--
-用途：在任务完成、方向切换或发现新规律后更新 memory-bank
+用途：在任务完成、方向切换或发现新规律后更新 memory-bank。
-触发：完成一轮实现、形成新决策、当前焦点变化时
+触发：完成一轮实现、形成新决策、当前焦点变化时。
 -->
 
 ## 什么时候需要回写
@@ -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`：仍未解决的阻塞、环境约束、待确认事项
-
-禁止：
-
-- 手工改写 `<!-- workflow-state:start/end -->`
-- 手工改写 `<!-- plan-status:start/end -->`
-- 把临时聊天内容、未验证猜测写进摘要
 
 ### `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` 保持一致
 
+## 禁止事项
+
+- 手工改写 `<!-- workflow-state:start/end -->`
+- 手工改写 `<!-- plan-status:start/end -->`
+- 把临时聊天内容、未验证猜测写进摘要
+
+## 输出协议
+
+```markdown
+## Updated Files
+- ...
+
+## New Context
+- ...
+
+## Outstanding Risks
+- ...
+```
+
+## 停止条件
+
+- 如果没有值得沉淀的信息，则停止并说明
+
 ---
 
 **最后更新**：{{DATE}}

templates/prompts/coding/verify-change.template.md

@@ -1,38 +1,56 @@
 # 变更验证模板
 
 <!--
-用途：在声明“完成 / 修复 / 可交付”前，明确验证范围与证据
+用途：在声明“完成 / 修复 / 可交付”前，用 fresh run 证明改动成立。
-触发：代码修改、配置修改、模板修改、规则修改后
+触发：代码、配置、模板、规则修改后；准备交付结果前。
 -->
 
 ## 验证目标
 
-- 这次改动要证明什么？
+- 这次改动要证明什么
-- 哪些行为必须通过？
+- 哪些行为必须通过
-- 哪些验证本轮不做？
+- 哪些验证本轮不做
+
+## 先读
+
+- `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
+- ...
 
-- 只跑与本次改动直接相关的验证命令
+## Evidence
-- 记录命令、结果和关键输出
+- ...
-- 如仓库存在项目私有验证提示词（例如 `docs/prompts/custom/verify.md`），先读取并执行其中的附加约束
 
-```bash
+## Not Validated
-{{VERIFY_CMD}}
+- ...
+
+## 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` 状态块
 
 ---
 

templates/prompts/system/agent-behavior.template.md

@@ -1,49 +1,27 @@
-# 工作流入口
+# 任务入口路由
 
 <!--
-本文件不重复定义核心规则；它只负责把任务路由到合适的工作流入口。
+本文件不重复定义核心规则；它只负责把任务路由到合适的任务入口。
 安全红线、验证要求、主循环规则见 AGENT_RULES.md。
 -->
 
 ## 路由原则
 
 - 需求不明确：先看 `docs/prompts/coding/clarify.md`
-- 需要设计或拆解方案：走
+- 需要判断设计、计划或执行路径：先回到 `AGENT_RULES.md`
-  `using-superpowers` → `$brainstorming` → `$writing-plans`
-- `brainstorming` 结束后：立即
-  `playbook.py -record-spec <path> -progress memory-bank/progress.md`
-- `writing-plans` 结束后：立即
-  `playbook.py -record-plan <path> -progress memory-bank/progress.md`
-- 需要执行已有 Plan：先 `main_loop.py claim`，再走
-  `$executing-plans`
-- 如为代码类执行：在 `$executing-plans` 前强制叠加
-  `karpathy-guidelines`，并同时遵循 `.agents/` 与 `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`
+- 完整流程与执行约束只在 `AGENT_RULES.md`
-- 执行留痕以 `memory-bank/progress.md` 的
+- 项目私有规则写入 `AGENT_RULES.local.md`
-  `workflow-state` 与 `plan-status` 为准
+- 设计产物只放 `docs/superpowers/specs/`
+- 计划产物只放 `docs/superpowers/plans/`
+- 项目上下文与执行状态写入 `memory-bank/`
 
 ---
 

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"

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")

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:

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("AGENT_RULES.md", prompts_readme)
-        self.assertIn("playbook.py -record-plan", 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("AGENT_RULES.md", agent_behavior_template)
-        self.assertIn("playbook.py -record-plan", 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: