📝 docs(tsl): clarify syntax constraints and enhance test infrastructure

- Add TSF file naming constraint to syntax/02_core_model.md - Clarify semicolon rules: syntax facts vs style preferences - Separate control flow end semicolon rules (syntax allows both) - Add function body semicolon requirements to syntax/05_functions_and_calls.md - Move style preferences to code_style.md (control flow end semicolons) - Remove cross-references from syntax docs to maintain independence - Enhance Gitea workflow emoji for better CI output readability - Fix CI test path from tests/ to test/ - Organize agent test results under test/agent/result/ directory - Add complete Chinese translation of test cases (test_cases_zh.md) - Clean up .gitignore to use unified test/agent/result/ directory - Remove obsolete agent test artifacts (REPORTS_LOCATION.md, old results) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-06-21 17:04:50 +08:00
parent 6026401907
commit 8b93311cae
138 changed files with 7018 additions and 1705 deletions
@@ -6,7 +6,7 @@

 <!-- playbook:agents:start -->

- [.agents/index.md](.agents/index.md) - 语言规则与工具入口
+- [.agents/index.md](.agents/index.md) - 语言规则索引
 <!-- playbook:agents:end -->

 <!-- playbook:templates:start -->
@@ -15,7 +15,7 @@

 执行任何项目任务前，必须先读取：

- [AGENT_RULES.md](./AGENT_RULES.md) - Playbook 规则入口，负责执行流程、优先级与会话启动加载
+- [AGENT_RULES.md](./AGENT_RULES.md) - 执行规则与工作流入口

 ### 项目状态

@@ -2,44 +2,24 @@

 目的：为本仓库提供稳定的执行流程与行为规范。

-本文件是项目内唯一流程约束中心；`docs/superpowers/`
+本文件是框架流程约束基线；`docs/superpowers/`
 是唯一设计与计划产物中心；执行状态统一写回
 `memory-bank/progress.md`。

 ## 优先级

-1. 系统/开发者指令与安全约束
+1. 系统/开发者指令
 2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
 3. 仓库规则：`.agents/` 与 `AGENTS.md`
 4. 本文件

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

 - 统一使用简体中文
 - 专业、直接、简洁，避免对话填充词
 - 发现用户理解有误时，礼貌纠正
- 无法满足请求时，简洁说明原因并提供替代方案
+- 无法满足请求时，简洁说明原因；如有可行替代方案则一并给出
 - 不给时间估算，专注事实、风险与下一步
- 代码块必须标注语言类型
- 不使用 emoji，除非用户明确要求
-
-## 工作原则
-
- 模仿项目现有风格，先看周围代码、配置和测试再动手
- 不假设库、框架或命令可用，先验证再使用
- 完整覆盖用户请求，不遗漏边界条件和收尾工作
- 技术准确性优先于迎合；不确定时先调查再回答
- 只做当前任务需要的改动，不顺手加功能、不顺手重构
- 不为一次性操作增加抽象，不为假设的未来需求设计

 ## 项目边界

@@ -49,10 +29,9 @@
  业务文档或当前项目私有规则
 - 除非用户明确要求维护、升级或调试 Playbook 本身，不得修改
  `{{PLAYBOOK_ROOT}}/` 下内容
- 当前项目已生效的规则入口是项目根目录的 `AGENT_RULES.md`、
-  `AGENT_RULES.local.md`、`AGENTS.md` 与 `.agents/`
- `{{PLAYBOOK_ROOT}}/templates/` 与 `{{PLAYBOOK_ROOT}}/rulesets/`
-  是模板源；不要把它们当作当前项目已生效规则
+- 当前项目的生效规则是项目根目录的 `AGENT_RULES.md`、`AGENT_RULES.local.md`、
+  `AGENTS.md` 与 `.agents/`；`{{PLAYBOOK_ROOT}}/templates/` 与
+  `{{PLAYBOOK_ROOT}}/rulesets/` 只是模板源，不是当前项目已生效规则
 - 可按 `.agents/` 指向读取 `{{PLAYBOOK_ROOT}}/docs/` 作为标准文档；
  读取不代表该目录属于业务改动范围
 - 搜索、批量修改、代码审查、归档/提交时，默认排除 `{{PLAYBOOK_ROOT}}/`；
@@ -60,53 +39,41 @@

 ## 会话启动

-每次新会话开始时，按顺序加载以下上下文：
+每次新会话开始时，按以下建议顺序加载上下文以快速建立项目全貌；
+清单中文件不存在则跳过：

-1. `AGENT_RULES.local.md`：项目私有规则（如存在）
-2. `.agents/index.md`：语言规则与工具入口（如存在）
+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/`：相关实施计划（如存在）
+7. `memory-bank/decisions.md`：重要决策记录
+8. `memory-bank/progress.md`：执行进度与 Plan 状态
+9. `docs/superpowers/specs/`：最新设计稿
+10. `docs/superpowers/plans/`：相关实施计划

-目的：快速建立项目全貌，避免重复解释和重复试错。
-
-在完成本节启动加载前，不得修改文件、运行项目命令或给出实现结论。
+**执行约束**：加载顺序可调整，但在处理首个实质性任务前（修改文件、运行项目命令、给出实现结论），必须先完成上述相关上下文加载。

 ## 规划与执行模型

- 头脑风暴使用 `$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`
-
-重要约束：
+> 记号约定：`$<skill-name>` 表示在对话中点名触发的 skill（如
+> `$brainstorming`）；无 `$` 的同名 skill 指其阶段或产物，二者指向同一 skill。
+> `using-superpowers` 是会话启动时判断并加载适用 skill 的入口 skill。

 - 规划阶段必须走 `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`、
+- `$brainstorming` 产出 `docs/superpowers/specs/*-design.md`；写出 spec 后
+  立即用 `playbook.py -record-spec` 记录 `phase=planning` 与 `spec=<path>`
+- `$writing-plans` 产出 `docs/superpowers/plans/*.md`；写出 plan 后立即用
+  `playbook.py -record-plan` 记录 `plan=<path>`、`executor=executing-plans`、
  `constraints=karpathy-guidelines,.agents,AGENT_RULES`
- spec/plan 产出阶段不单独提交或归档，只做文件落地与状态留痕；
-  如外部 skill 要求写完 spec 或 plan 后立即提交，以本文件为准推迟到
-  Plan 完成后统一处理
- 未领取 Plan 前，不得直接进入 `$executing-plans`
- 已领取 Plan 后，默认执行使用 `$executing-plans`
- `$subagent-driven-development` 仅在 Plan 或平台明确要求时使用，
-  不是默认执行器
- 执行完成后，必须先运行 `main_loop.py finish` 写回状态，
-  再更新 `progress.md` 上半部分摘要，并按主循环收尾要求归档当前
-  Plan 变更
+- spec/plan 产出阶段不单独提交或归档，只做文件落地与状态留痕；如外部 skill
+  要求写完后立即提交，以本文件为准，推迟到 Plan 完成后统一处理
+- Plan 生命周期由 `main_loop.py` 协调，通过 `memory-bank/progress.md` 留痕
+- Plan 执行入口只能是主循环：领取前不得进入 `$executing-plans`，领取后默认用
+  `$executing-plans` 执行，`$subagent-driven-development` 仅在 Plan 或平台明确要求时使用
+- 代码类执行必须同时遵循 `$karpathy-guidelines`、`.agents/`、`AGENT_RULES.md`
+- 执行完成后按「Plan 完成归档契约」收尾

 ### 条件触发 Skills

@@ -128,17 +95,13 @@

 - `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 不得包含必然失败或未确认的内容；未确认项须在 `$brainstorming`
+  阶段解决后才能产出 Plan
+- Plan 内验证必须是当前阶段可通过的局部验证；跨 Plan 的集成验证自成一个独立 Plan
+- 每个 Plan 应自身可独立交付，不依赖其他 Plan 的执行结果；有先后顺序的工作
+  放入同一 Plan 的有序 Task，不跨 Plan 表达执行依赖
 - 不因等待确认而中断可执行步骤；待确认事项写入回复
 - 每个 Plan 应小步、可验证、可快速完成

@@ -168,7 +131,7 @@

 ### 领取与写回

-领取命令：
+**领取 Plan**：

 ```bash
 python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
@@ -177,68 +140,33 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
  -owner "<当前session或agent标识>"
 ```

-该命令会在锁保护下串行完成三件事：
+该命令在锁保护下完成：自动识别当前环境（windows/linux/darwin）、校验 Plan Meta、优先恢复 `in-progress`、选择第一个可执行 Plan、写入 `claimed_by`/`claimed_at` 并清理上一轮 `verification`。

- 自动识别当前环境：`windows`、`linux`、`darwin`
- 校验 Plan 文件包含必需 `Plan Meta`
- 已有 `in-progress` 优先恢复
- 如无 `in-progress`，按 Plan 文件顺序选择第一个可执行 Plan：
-  `pending` 或 `blocked: env:<当前环境>:...`
- 将选中的 Plan 写成 `in-progress`
- 在 `workflow-state` 写入 `claimed_by`、`claimed_at`，并清理上一轮
-  `verification`
+stdout 必须包含 `PLAN=<path>`；如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`。

-这里的锁保护的是 `progress.md` 状态块更新，避免多个 session
-同时读写时发生覆盖。
-
-stdout 必须包含：
-
- `PLAN=<path>`
- 如为环境恢复，还会附带 `NOTE=env:<环境>:<Task列表>`
-
-规划与执行留痕示例：
-
-```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
-```
-
-写回命令示例：
+**写回状态**：

 ```bash
+# 完成
 python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
-  -plan <plan> \
-  -status done \
+  -plan <plan> -status done \
  -progress memory-bank/progress.md \
  -verified "<本轮已通过的验证命令或证据>"
-```

-```bash
+# 阻塞（环境）
 python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
-  -plan <plan> \
-  -status blocked \
+  -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 \
+  -plan <plan> -status blocked|skipped \
  -progress memory-bank/progress.md \
  -note "<原因>"
 ```

-只读状态命令：
+**查看状态**（只读，不修改 progress.md）：

 ```bash
 python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
@@ -246,14 +174,24 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
  -progress memory-bank/progress.md
 ```

-`status` 只汇总 `pending`、`in-progress`、`done`、`blocked`、
-`skipped` 和当前 `workflow-state`，不得修改 `progress.md`。
+**规划留痕**：
+
+```bash
+# brainstorming 完成后
+python {{PLAYBOOK_SCRIPTS}}/playbook.py \
+  -record-spec docs/superpowers/specs/<topic>-design.md \
+  -progress memory-bank/progress.md
+
+# writing-plans 完成后
+python {{PLAYBOOK_SCRIPTS}}/playbook.py \
+  -record-plan docs/superpowers/plans/<topic>.md \
+  -progress memory-bank/progress.md
+```

 ### Plan 场景下的执行上下文与隔离策略

 - 本节仅适用于通过主循环领取并执行 Plan 的场景
- 默认允许在当前项目上下文直接执行 Plan
- 不强制为 Plan 执行创建隔离上下文
+- 默认在当前项目上下文直接执行 Plan，不强制创建隔离上下文
 - 仅在以下场景使用隔离工作区：
  - 用户明确要求隔离执行
  - Plan 文本自身明确要求隔离执行
@@ -264,71 +202,50 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \

 1. 先 `claim`，拿到 `PLAN=` 后再读取 Plan 内容
 2. 如返回 `NOTE=env:...`，本轮只执行列出的 Task
-3. 默认执行器是 `$executing-plans`；代码类任务在执行前必须显式
-   加载 `karpathy-guidelines`
-4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan 本身；
-   如发生冲突，以优先级更高的规则为准
+3. 代码类任务在执行前必须显式加载 `$karpathy-guidelines`
+4. 执行时同时遵循 `.agents/`、`AGENT_RULES.md` 和 Plan
 5. 按顺序执行 Task，并完成 Plan 约定的验证
 6. 环境不匹配时，记录所需环境和 Task，继续处理本 Plan
   其余可执行 Task
 7. 其他阻塞写回 `blocked`；永久放弃写回 `skipped`
-8. 触碰安全红线时立即停止，不继续后续 Plan
-9. 常规模式下可对高风险事项向用户确认；无交互模式按本文件
-   的“需要确认的场景”自动处理
-10. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后
-    再领取下一个
-11. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
+8. 遇到决策点时按「需要确认的场景」处理：常规模式下满足该节
+   条件的先向用户确认；无交互模式按该节自动处理
+9. 每次 `claim` 只领取一个 Plan；写回并归档当前 Plan 变更后
+   再领取下一个
+10. 全部 Plan 处理完后，统一汇总完成项、阻塞项、跳过项、
    环境需求与待确认事项

 ### Plan 完成归档契约

- 归档指按当前项目约定创建可回溯的交付记录；具体机制由项目本地规则
-  或用户指令定义
- `main_loop.py finish -status done` 只负责写回机器状态，不代表 Plan
-  已完成交付；memory 更新或回复摘要也不等同于归档
- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个
-  Plan；归档方式由项目约定决定
- spec/plan 本身属于后续 Plan 交付边界的一部分，不在规划阶段拆成独立
-  归档/提交单元
- 收尾顺序：
+**核心原则**：
+
+- Plan `done` 后必须完成当前 Plan 变更的归档/提交，然后才能继续领取下一个 Plan
+- `main_loop.py finish -status done` 只负责写回机器状态，不自动提交或归档，不代表已完成交付
+- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断
+
+**收尾顺序**：

 1. 完成 Plan 约定验证
-2. 运行 `main_loop.py finish -status done -verified "<证据>"`
-   写回状态
+2. 运行 `main_loop.py finish -status done -verified "<证据>"` 写回状态
 3. 必要时更新 `progress.md` 上半部分摘要和相关 memory
 4. 检查当前变更清单与差异
 5. 只归档/提交当前 Plan 相关改动

- 当前 Plan 相关改动包括但不限于：
-  - 本轮代码、配置、测试、模板改动
-  - 当前 Plan 文件（创建、补充、勾选 Task、记录结果等）
-  - `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status`
-    与摘要更新
-  - 必要 memory 更新，例如 `active-context.md`、`decisions.md`
- Plan 范围是归档/提交边界，不以整个工作区是否干净作为唯一判断
- 允许存在其他 session 的未归档改动，只要它们不属于当前 Plan、
-  不与当前 Plan 范围冲突、且不会被混入本轮归档/提交
- 不得由 `main_loop.py finish` 自动执行提交或变更归档
- 不得把用户已有改动或其他 Plan 的改动混入当前 Plan 交付单元
+**当前 Plan 相关改动包括**：
+
+- 本轮代码、配置、测试、模板改动
+- 当前 Plan 文件（创建、补充、勾选 Task、记录结果等）
+- `memory-bank/progress.md` 中本轮 `workflow-state`、`plan-status` 与摘要更新
+- 必要 memory 更新（如 `active-context.md`、`decisions.md`）
+
+**归档约束**：
+
+- 不得把用户已有改动或其他 Plan/session 的改动混入当前 Plan 交付单元；
+  这类改动只要不属于、不冲突当前 Plan，允许其未归档共存
 - 如 Plan `done` 后没有当前 Plan 相关差异，必须在回复中说明无归档原因
- 如当前 Plan 相关差异仍未归档，只能声明“状态已写回，交付未完成”，
-  不得声明 Plan 完成
- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的
-  局部成果需要保留时才归档/提交
- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异属于
-  其他 session 或其他 Plan，保留在原处并在报告中说明
- 如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户
-  确认；无交互模式写入风险并停止继续领取
-
-## 通用执行约束
-
-### 代码与配置修改
-
- 必须先读文件再修改
- 遵循 `.agents/`、项目代码风格和现有命名约定
- 只改必要部分，不顺手重构无关内容
- 执行与改动相称的验证；如有相关测试且未被豁免，必须通过
- 遵循项目声明的换行与文件格式规则
+- 如当前 Plan 相关差异仍未归档，只能声称「状态已写回，交付未完成」，不得声称 Plan 完成
+- `blocked` / `skipped` 不默认归档/提交代码改动；只有状态留痕或已验证的局部成果需要保留时才归档
+- 继续领取下一个 Plan 前，必须确认当前 Plan 无遗留差异；如剩余差异与当前 Plan 或下一个 Plan 的预期范围冲突，常规模式先向用户确认；无交互模式将当前 Plan 写回 `blocked` 并记录冲突，继续领取下一个

 ### 决策与留痕

@@ -340,9 +257,8 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
  阶段变化或执行结束后整理/替换摘要，不做无限追加
 - `active-context.md` 是短期上下文快照，不是长期日志；
  只保留当前 Plan / 下一轮仍重要的目标、变化、文件与下一步
- 同一错误重复两次以上时，立即更新
-  `AGENT_RULES.local.md` 或 `memory-bank/decisions.md`
- 发现项目特有规律时，沉淀到 `AGENT_RULES.local.md`
+- 同一错误重复两次以上，或发现项目特有规律时，沉淀到
+  `AGENT_RULES.local.md`（决策类记入 `memory-bank/decisions.md`）

 ### 归档操作

@@ -351,44 +267,43 @@ python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
 - 不跳过项目约定的归档前检查
 - 如项目没有归档机制，在回复中列出本轮交付的文件清单与验证证据

-### 工具使用
-
- 独立步骤尽可能并行执行
- 严格遵循工具参数定义与 schema
- 优先使用专用工具，不重复探测同一信息
- 文本搜索优先使用 `rg`
-
 ## 需要确认的场景

 ### 常规模式

+执行 Plan 过程中，遇到以下决策点先向用户确认：
+
 - 需求不明确，或存在多种可行方案
 - 需要行为、兼容性或性能取舍
 - 涉及架构变更、破坏性修改或约束冲突
 - 风险较高，且继续执行可能放大返工成本

-### 无交互模式
-
- 安全红线：立即停止，不继续后续 Plan
- 架构变更、兼容性问题、破坏性修改：写回 `blocked`
- 多种可行方案：选择最保守方案，并在报告中说明理由
- 一般歧义、风险或决策点：记录到报告，继续执行安全部分
-
-### 可以直接执行
+以下 Plan 改动可直接推进，无需确认：

 - 明显的 bug 修复
 - 符合现有模式的小改动
 - 测试用例补充或局部验证补齐

+### 无交互模式
+
+严格按 Plan 的 Task 执行，不自行做设计决策；一个 Plan 卡住不影响其余 Plan，
+继续领取下一个，直到所有 Plan 处理完毕：
+
+- Task 明确可执行：直接执行
+- Task 存在歧义或需要未在 Plan 中确认的设计决策：写回 `blocked`，不猜测、不替代设计
+  （此类决策本应在 `$brainstorming` 阶段解决，缺失说明 Plan 不合格）
+- 需要架构变更、破坏性修改，且 Plan 未明确授权：写回 `blocked`
+- 环境不匹配：记录 `env:<环境>:<Task列表>`，跳过该 Task，继续本 Plan 其余 Task
+
+每个被 `blocked` 的 Plan 记录原因，继续领取下一个，不因单个 Plan 卡住而中止整批。
+
 ## Session 收尾

- 汇总已完成、阻塞、跳过的 Plan 及原因
- 标出需要其他环境处理的事项：`env:<环境>:<Task列表>`
- 必要时将重要结论写入 `memory-bank/decisions.md`
- 出现以下情况时，建议开启新 Session：
-  - 当前方向明显跑偏
-  - 讨论阶段产出多个候选方案，准备进入执行
-  - Session 过长，开始重复犯同类错误
+出现以下情况时，建议开启新 Session：
+
+- 当前方向明显跑偏
+- 讨论阶段产出多个候选方案，准备进入执行
+- Session 过长，开始重复犯同类错误

 ## 验证清单

@@ -1,202 +1,188 @@
 # 项目架构模板

-本目录包含以 `superpowers` 为基石的项目模板，用于快速初始化新项目的
-AI 代理工作环境。
+本目录包含基于 superpowers 工作流的项目模板，用于快速初始化 AI 代理工作环境。
+
+## 与 Playbook 其他部分的关系
+
+```text
+playbook/
+├── rulesets/        # 语言级硬规则 → 部署到 .agents/
+├── skills/          # 按需加载的技能
+├── docs/            # 权威静态文档
+├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
+└── scripts/
+    └── playbook.py    # 统一入口
+```
+
+部署方式详见主 README.md 的"在其他项目中使用本 Playbook"章节。

 ## 目录结构

 ```text
 templates/
-├── README.md                    # 本文件
 ├── AGENTS.template.md           # 入口导航模板
-├── AGENT_RULES.template.md      # superpowers-first 执行规则模板
-├── memory-bank/                 # 项目上下文模板
-│   ├── project-brief.template.md
-│   ├── tech-context.template.md
-│   ├── system-patterns.template.md
-│   ├── active-context.template.md
-│   ├── progress.template.md
-│   └── decisions.template.md
-├── prompts/                     # 任务入口模板（不是流程权威）
-│   ├── README.md
-│   ├── system/
-│   │   └── agent-behavior.template.md
-│   ├── coding/
-│   │   ├── clarify.template.md
-│   │   ├── verify-change.template.md
-│   │   ├── close-task.template.md
-│   │   ├── update-memory.template.md
-│   │   └── code-review.template.md
-├── ci/                          # CI 模板
-│   ├── README.md
-│   └── gitea/
-│       └── .gitea/
-│           ├── workflows/
-│           └── ci/
-├── cpp/                         # C++ 配置模板
-│   ├── .clang-format
-│   ├── .clangd
-│   └── ...
-└── python/                      # Python 配置模板
-    ├── .editorconfig
-    ├── pyproject.toml
-    └── ...
+├── AGENT_RULES.template.md      # superpowers 执行规则模板
+├── memory-bank/                 # 项目上下文模板（6 个）
+├── prompts/                     # 任务入口模板（6 个 + README）
+├── ci/                          # CI 配置模板
+├── cpp/                         # C++ 工具链模板
+└── python/                      # Python 工具链模板
 ```

-## 文件分类
+## 模板分类

-从部署角度看，本目录的文件分成三类：
+从部署和维护角度，模板分为三类：

- **会同步更新的框架模板**
-  - `AGENT_RULES.md`
-  - `docs/prompts/README.md`
-  - `docs/prompts/system/*.md`
-  - `docs/prompts/coding/*.md`
-  - `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
- **首次创建后由项目维护的上下文文件**
-  - `memory-bank/*.md`
-  - `AGENT_RULES.local.md`
- **只保留在快照中参考的模板**
-  - `ci/`
-  - `cpp/`
-  - `python/`
+### 1. 框架模板（会自动更新）

-补充说明：
+这些文件由 playbook 框架维护，每次同步时可能更新：

- `memory-bank/*.md` 首次创建后应由项目填写；`force=true`
-  会覆盖已填写内容并先备份。
- `AGENT_RULES.local.md` 由 `[sync_rules]` 首次自动创建，
-  后续不再覆盖。
- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*`
-  不会被 playbook 删除。
- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用
-  `@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。
- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/`
-  只负责把代理导向正确的任务入口。
+- `AGENT_RULES.md`
+- `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
+- `docs/prompts/README.md`
+- `docs/prompts/system/*.md`
+- `docs/prompts/coding/*.md`

-## 快速部署
+### 2. 项目上下文（首次创建后由项目维护）

-以下命令假设 **playbook 已经部署到项目内**，使用统一入口 `playbook.py`，配置节存在即启用：
+这些文件首次创建后应由项目填写，`force=true` 会覆盖已填写内容并先备份：
+
+- `memory-bank/*.md`
+- `AGENT_RULES.local.md`（首次自动创建，后续不再覆盖）
+
+### 3. 参考模板（需手动复制）
+
+这些模板保留在快照中供参考，需手动复制到项目根目录：
+
+- `ci/`：Gitea Actions 工作流
+- `cpp/`：C++ 工具链配置
+- `python/`：Python 工具链配置
+
+**补充说明**：
+
+- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*` 不会被 playbook 删除
+- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用 `@AGENTS.md` 则追加；如已手工引用则跳过
+- 流程约束统一收敛到 `AGENT_RULES.md`；`docs/prompts/` 只负责把代理导向正确的任务入口
+
+## 部署方式
+
+使用 `playbook.py` 统一入口部署，通过配置节控制同步内容：

 ```toml
 # playbook.toml
-[playbook]
-project_root = "/path/to/project"
-playbook_root = "docs/standards/playbook"
-install_mode = "snapshot"
-
-# 同步 AGENT_RULES.md（配置节存在即启用）
-[sync_rules]
-# force = true  # 可选，强制覆盖已存在的文件
-
-# 同步 memory-bank/（配置节存在即启用）
-[sync_memory_bank]
-project_name = "MyProject"
-# force = true  # 可选，强制覆盖（会先备份）
-
-# 同步 docs/prompts/（配置节存在即启用）
-[sync_prompts]
-# force = true  # 可选，强制覆盖（会先备份）
+[sync_rules]           # 同步 AGENT_RULES.md
+[sync_memory_bank]     # 同步 memory-bank/
+[sync_prompts]         # 同步 docs/prompts/
 ```

-```bash
-python <playbook_root>/scripts/playbook.py -config playbook.toml
-```
+详细配置说明见主 README.md 和 playbook.toml.example。

-参数说明见 `playbook.toml.example`（仓库根目录）或项目内的
-`<playbook_root>/playbook.toml.example`。
+## 模板说明

-其中 `<playbook_root>` 默认为 `docs/standards/playbook`，
-也可以按项目配置改成 `custom/playbook` 等自定义目录；
-对应文档入口会变成 `<playbook_root>/docs/...`。
+### memory-bank/

-如果你当前是在 **外部 clone 的 playbook 仓库** 中执行，而不是在目标项目内执行快照，请使用：
+项目上下文文档，用于让 AI 快速理解项目：

-```bash
-python scripts/playbook.py -config playbook.toml
-```
+| 文件                          | 用途                       |
+| ----------------------------- | -------------------------- |
+| `project-brief.template.md`   | 项目定位、边界、约束       |
+| `tech-context.template.md`    | 技术上下文、工具链、入口   |
+| `system-patterns.template.md` | 系统模式、边界、不变量     |
+| `active-context.template.md`  | 当前目标、最近变更、下一步 |
+| `progress.template.md`        | 人类摘要 + Plan 状态块     |
+| `decisions.template.md`       | 架构决策记录（ADR）        |

-此时 `install_mode = "snapshot"` 会把快照写入 `<project_root>/<playbook_root>`；
-后续再在目标项目内使用 `<playbook_root>/scripts/playbook.py`
-做同步更新。
+### prompts/

-### 配置节说明
+任务入口模板，部署后去掉 `.template` 后缀。`prompts/README.md` 作为任务入口索引。

- `[sync_rules]`：部署 `AGENT_RULES.md`；必要时创建 `.local.md`。
-  选项：`force`、`no_backup`、`date`
- `[sync_memory_bank]`：部署 `memory-bank/`。
-  选项：`project_name`、`force`、`no_backup`、`date`
- `[sync_prompts]`：部署 `docs/prompts/`。
-  选项：`force`、`no_backup`、`date`
- `[sync_standards]`：部署 `.agents/<lang>/`。
-  选项：`langs`、`gitattr_mode`、`no_backup`
- `[install_skills]`：部署到 `~/.agents/skills/` 或
-  `~/.claude/skills/`。
-  选项：`mode`、`skills`、`agents_home`、`skill_link`、
-  `no_backup`
+| 文件                                | 用途         | 使用场景            |
+| ----------------------------------- | ------------ | ------------------- |
+| `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 代码评审 |

- **配置节存在即启用**：只写需要同步的配置节
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制
- **CLAUDE.md**：自动检测/创建；如已存在 playbook 区块则更新，如未引用 `@AGENTS.md` 则追加，否则跳过
- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
- **no_backup**：默认 false；设为 true 时跳过备份直接覆盖
- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
- **占位符替换**：自动替换 `{{DATE}}`、`{{PROJECT_NAME}}`、`{{PLAYBOOK_ROOT}}`、`{{PLAYBOOK_SCRIPTS}}`
+### AGENT_RULES.template.md

-### 典型场景
+执行规则模板，定义 AI 的工作循环和约束。如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]` 首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 playbook 覆盖。

-```toml
-# 场景 1：初次部署（全部）
-[sync_rules]
-[sync_memory_bank]
-project_name = "MyProject"
-[sync_prompts]
+计划编排与执行细节统一指向 `docs/superpowers/`、`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`。

-# 场景 2：框架升级（只更新规则）
-[sync_rules]
-force = true
+### AGENTS.template.md

-# 场景 3：重置项目上下文
-[sync_memory_bank]
-project_name = "MyProject"
-force = true
-```
+入口导航模板，作为项目的主入口（Codex 入口）。

-### docs/superpowers 命名约定
+**设计理念**：
+
+- **最小化内容**：只包含导航链接，不包含详细规则
+- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块
+
+**playbook 标记**（用于自动更新）：
+
+- `<!-- playbook:agents:start/end -->`：语言规则链接，由 `[sync_standards]` 管理
+- `<!-- playbook:templates:start/end -->`：路由链接，`AGENTS.md` 始终按区块更新
+- `<!-- playbook:framework:start/end -->`：完整框架，`AGENTS.md` 始终按区块更新
+
+### superpowers 工作流约定

 `docs/superpowers/` 统一承载设计稿和实施计划：

- 设计只落到 `specs/`
- 计划只落到 `plans/`
- 执行状态只写回 `memory-bank/progress.md`
-
-为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用：
-
- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`：
-  `brainstorming` 产出的设计稿
- `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`：
-  `writing-plans` 产出的实施计划
+- **设计稿**：`specs/YYYY-MM-DD-<topic>-design.md`（`brainstorming` 产出）
+- **实施计划**：`plans/YYYY-MM-DD-<topic>.md`（`writing-plans` 产出）
+- **执行状态**：回写到 `memory-bank/progress.md`

 其中 `plans/` 为主执行入口；`specs/` 只作为设计背景和上游文档。

-### 生命周期总览
-
-完整主链只在 `AGENT_RULES.template.md` 定义；本文件不重复展开。
-这里仅说明职责分层：
+**生命周期**：

 - `docs/prompts/`：任务入口层，只负责把代理导向正确入口
 - `docs/superpowers/specs/`：设计稿
 - `docs/superpowers/plans/`：实施计划与主执行输入
 - `memory-bank/progress.md`：执行状态留痕

+完整主链只在 `AGENT_RULES.template.md` 定义。
+
+### 语言配置模板（ci/、cpp/、python/）
+
+语言和 CI 配置模板，`install_mode = "snapshot"` 安装快照时会复制这些模板：
+
+- `ci/gitea/`：Gitea Actions 工作流与辅助脚本，部署到快照 `templates/ci/`
+- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt` 等文件，部署到快照 `templates/cpp/`
+- `python/`：`pyproject.toml`、`.editorconfig` 等文件，部署到快照 `templates/python/`
+
+**使用方式**：这些模板保留在快照中供参考，需手动复制到项目根目录使用。其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录。
+
+## 技术细节
+
+### 占位符说明
+
+模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
+
+| 占位符                    | 说明         | 自动替换 |
+| ------------------------- | ------------ | -------- |
+| `{{DATE}}`                | 日期         | ✅ 是    |
+| `{{PROJECT_NAME}}`        | 项目名称     | ✅ 可选  |
+| `{{PLAYBOOK_ROOT}}`       | Playbook 根  | ✅ 是    |
+| `{{PLAYBOOK_SCRIPTS}}`    | 脚本路径     | ✅ 是    |
+| `{{PROJECT_GOAL}}`        | 项目目标     | ❌ 手动  |
+| `{{PROJECT_DESCRIPTION}}` | 项目描述     | ❌ 手动  |
+| 其他 `{{...}}`            | 项目特定内容 | ❌ 手动  |
+
+- `{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样
+- `{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录（默认 `docs/standards/playbook`）
+- `{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`）
+
 ### 部署后的目录结构

 ```text
 project/
 ├── AGENTS.md              # 入口导航（Codex 入口）
-├── AGENT_RULES.md         # superpowers-first 执行规则
+├── AGENT_RULES.md         # superpowers 执行规则
 ├── AGENT_RULES.local.md   # 项目私有规则（自动创建，项目维护）
-├── CLAUDE.md              # Claude Code 入口（按规则维护/追加 playbook 区块）
+├── CLAUDE.md              # Claude Code 入口
 ├── memory-bank/           # 项目上下文
 │   ├── project-brief.md
 │   ├── tech-context.md
@@ -219,143 +205,6 @@ project/
        └── plans/         # writing-plans / main_loop 消费
 ```

-## 占位符说明
-
-模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
-
-| 占位符                    | 说明         | 自动替换 |
-| ------------------------- | ------------ | -------- |
-| `{{DATE}}`                | 日期         | ✅ 是    |
-| `{{PROJECT_NAME}}`        | 项目名称     | ✅ 可选  |
-| `{{PROJECT_GOAL}}`        | 项目目标     | ❌ 手动  |
-| `{{PROJECT_DESCRIPTION}}` | 项目描述     | ❌ 手动  |
-| `{{PLAYBOOK_ROOT}}`       | Playbook 根  | ✅ 是    |
-| `{{PLAYBOOK_SCRIPTS}}`    | 脚本路径     | ✅ 是    |
-| 其他 `{{...}}`            | 项目特定内容 | ❌ 手动  |
-
-`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；
-未配置时保持原样。
-`{{PLAYBOOK_ROOT}}` 自动替换为项目内 Playbook 根目录
-（默认 `docs/standards/playbook`，
-也可按项目配置改成 `custom/playbook` 等）。
-`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径
-（默认 `docs/standards/playbook/scripts`，
-也可按项目配置改成 `custom/playbook/scripts` 等）。
-
-## 模板说明
-
-### memory-bank/
-
-项目上下文文档，用于让 AI 快速理解项目：
-
-| 文件                          | 用途                       |
-| ----------------------------- | -------------------------- |
-| `project-brief.template.md`   | 项目定位、边界、约束       |
-| `tech-context.template.md`    | 技术上下文、工具链、入口   |
-| `system-patterns.template.md` | 系统模式、边界、不变量     |
-| `active-context.template.md`  | 当前目标、最近变更、下一步 |
-| `progress.template.md`        | 人类摘要 + Plan 状态块     |
-| `decisions.template.md`       | 架构决策记录（ADR）        |
-
-### prompts/
-
-任务入口模板（部署后去掉 `.template` 后缀）：
-
-其中 `templates/prompts/README.md` 部署后对应 `docs/prompts/README.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 代码评审 |
-
-### AGENT_RULES.template.md
-
-执行规则模板，定义 AI 的工作循环和约束。
-如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]`
-首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。
-计划编排与执行细节统一指向 `docs/superpowers/`、
-`playbook.py -record-spec/-record-plan` 与 `main_loop.py claim/finish`；
-这里仅说明模板职责与部署边界。
-
-### AGENTS.template.md
-
-入口导航模板，作为项目的主入口。
-
-**设计理念**：
-
- **最小化内容**：只包含导航链接，不包含详细规则
- **结构化导航**：分为核心规则、项目上下文、任务入口三个板块
-
-**playbook 标记**（用于自动更新）：
-
- `<!-- playbook:agents:start/end -->`：语言规则链接。
-  由 `[sync_standards]` 管理
- `<!-- playbook:templates:start/end -->`：路由链接。
-  `AGENTS.md` 始终按区块更新
- `<!-- playbook:framework:start/end -->`：完整框架。
-  `AGENTS.md` 始终按区块更新
-
-### ci/、cpp/、python/
-
-语言和 CI 配置模板。`install_mode = "snapshot"` 安装快照时会复制这些模板：
-
- `ci/gitea/`：Gitea Actions 工作流与辅助脚本。
-  部署到快照 `templates/ci/`
- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt`
-  等文件。
-  部署到快照 `templates/cpp/`
- `python/`：`pyproject.toml`、`.editorconfig` 等文件。
-  部署到快照 `templates/python/`
-
-> 注意：这些模板会复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。
-> 其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录，而不只是复制 workflows。
-
-**使用方式**：
-
-```toml
-# playbook.toml - 生成包含这些模板的快照
-[playbook]
-project_root = "/path/to/project"
-playbook_root = "docs/standards/playbook"
-install_mode = "snapshot"
-
-[sync_standards]
-langs = ["tsl", "cpp", "python"]
-```
-
-```bash
-python scripts/playbook.py -config playbook.toml
-# 然后手动从 <playbook_root>/templates/ 复制所需配置到项目根目录
-```
-
-## 与 playbook 其他部分的关系
-
-```text
-playbook/
-├── rulesets/        # 语言级硬规则 → 部署到 .agents/
-├── skills/          # 按需加载的技能（thirdparty/ 为第三方同步）
-├── docs/            # 权威静态文档
-├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
-└── scripts/
-    └── playbook.py    # 统一入口：snapshot install / sync_*
-```
-
-## 完整部署流程
-
-```bash
-# 1. 准备配置并执行统一入口
-python <playbook_root>/scripts/playbook.py -config playbook.toml
-
-# 2. 编辑 memory-bank/*.md 填写项目信息
-
-# 3. 替换剩余的 {{PLACEHOLDER}} 占位符
-```
-
 ---

-**最后更新**：2026-05-18
+**最后更新**：2026-06-17
@@ -1,126 +0,0 @@
-# 提示词生成器（元提示词）
-
-<!--
-用途：根据场景自动生成专用提示词
-原理：α-prompts（生成）+ Ω-prompts（优化）递归循环
-->
-
-## 何时使用
-
- 需要为新场景创建专用提示词
- 现有提示词不满足特定需求
- 需要批量生成同类提示词
-
---
-
-## 生成流程（α循环）
-
-### 1. 分析场景
-
-```markdown
-**场景名称**：[名称]
-**目标用户**：[AI/人类/两者]
-**触发条件**：[何时使用这个提示词]
-**预期输出**：[使用后应该产出什么]
-```
-
-### 2. 提取约束
-
-```markdown
-**必须做**：
- 约束1
- 约束2
-
-**禁止做**：
- 禁止1
- 禁止2
-
-**边界条件**：
- 边界1
- 边界2
-```
-
-### 3. 生成草稿
-
-```markdown
-# [提示词标题]
-
-<!--
-用途：[一句话描述]
-触发：[触发条件]
-->
-
-## 何时使用
-
- 场景1
- 场景2
-
-## [核心内容]
-
-[根据场景填充]
-
-## [约束/原则]
-
- 约束1
- 约束2
-
---
-
-**最后更新**：{{DATE}}
-```
-
---
-
-## 优化流程（Ω循环）
-
-### 1. 评估维度
-
-| 维度       | 问题                   |
-| ---------- | ---------------------- |
-| **清晰度** | 指令是否明确无歧义？   |
-| **完整度** | 是否覆盖所有必要场景？ |
-| **简洁度** | 是否有冗余内容可删除？ |
-| **可操作** | AI 能否直接执行？      |
-
-### 2. 迭代优化
-
-```text
-草稿 → 评估 → 修改 → 再评估 → ... → 定稿
-```
-
-### 3. 验证测试
-
- 用实际场景测试提示词效果
- 收集反馈，持续迭代
-
---
-
-## 提示词模板库
-
-### 标准结构
-
-```markdown
-# [标题]
-
-<!--
-用途：
-触发：
-->
-
-## 何时使用
-## [核心内容]
-## [约束/原则]
-
---
-
-**最后更新**：{{DATE}}
-```
-
-### 命名规范
-
- 文件名：`[动词]-[对象].template.md`
- 示例：`clarify-requirement.template.md`
-
---
-
-**最后更新**：{{DATE}}
@@ -2,7 +2,7 @@

 <!--
 本文件不重复定义核心规则；它只负责把任务路由到合适的任务入口。
-安全红线、验证要求、主循环规则见 AGENT_RULES.md。
+验证要求、主循环规则见 AGENT_RULES.md。
 -->

 ## 路由原则