Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d

25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps 2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows 98c3f30 📝 docs(agent_rules): allow plan execution on current branch 16c7230 📝 docs(prompts): define custom verify layering 8efc4dd 🐛 fix(skills): quote commit-message description bc8498f 🐛 fix(ci): install tomli for gitea tests 55cda3b 🐛 fix(tests): report missing toml parser clearly c0729c7 🐛 fix(playbook): import Optional for cli compatibility 63e24bf 📦 deps(skills): sync thirdparty skills d2f9356 🐛 fix(ci): isolate gitea workflow repos 588b81d 🐛 fix(ci): inline gitea workflow bootstrap e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts 2c5050d ♻️ refactor(skills): rename repo skills source dir f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills 234b335 ✨ feat(workflow): add superpowers planning and execution state tracking c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates 2325409 📝 docs(markdown): clarify optional markdownlint usage 214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes a22b324 📝 docs(templates): add execution and memory-bank prompt templates 223a797 📝 docs(templates): update README for Claude Code and current features 4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules 2431c9d 📝 docs: add claude_md config and use cross-platform paths d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root 6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery 6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt 9f8b6b5 📝 docs: update README and config example for Claude Code support 79cff6c 📝 docs(skills): add Claude Code platform support 452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows 7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory 64950e7 📦 deps(skills): sync thirdparty skills a2e3cb0 ✨ feat(playbook): add no_backup deploy controls 8609d59 🐛 fix(docs): repair reference catalog source links 956da11 🐛 fix(playbook): publish hidden ci test fixes 3f67754 📦 deps(skills): sync thirdparty skills 08ca87b 📦 deps(skills): add karpathy thirdparty sync 96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual 3ed5052 📦 deps(skills): sync thirdparty skills 60108dd 📦 deps(skills): sync thirdparty skills da85d4e 🐛 fix(thirdparty): prune nested project snapshots a2a697e 📦 deps(skills): sync thirdparty skills 9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills 33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields 91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update 2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline 5b9c1e3 📦 deps(skills): sync superpowers 2f2d34a 📝 docs(readme): normalize subtree command spacing 62db7db 🐛 fix(ci): serialize superpowers update and sync 3463223 🐛 fix(ci): use literal superpowers sync paths 48f6de8 📦 deps(skills): sync superpowers 4b23529 🔧 chore(ci): merge superpowers update and sync workflow a56d75b 📦 deps(skills): sync superpowers 84bcefa 🔧 chore(ci): use ci[bot] commit author name 00a07e5 📦 deps(skills): sync superpowers 7b84daf 🐛 fix(templates): enforce main loop progress tracking 51373d7 🔧 chore(ci): automate superpowers sync workflow eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block 79755c6 📦 deps(skills): sync superpowers 836d878 📦 deps(skills): sync superpowers 8216c9f 📦 deps(skills): sync superpowers 9439505 🐛 fix(playbook): address reported repo issues git-subtree-dir: docs/standards/playbook git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
2026-05-24 13:04:14 +08:00
parent 35e6a301aa
commit 3d83740f88
292 changed files with 30774 additions and 218828 deletions
@@ -6,10 +6,7 @@

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

-请以 `.agents/` 下的规则为准：
-
- 入口：`.agents/index.md`
- 语言规则：`.agents/{{MAIN_LANGUAGE}}/index.md`
+- [.agents/index.md](.agents/index.md) - 语言规则与工具入口
 <!-- playbook:agents:end -->

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

 - [AGENT_RULES.md](./AGENT_RULES.md) - 执行流程与优先级

-### 项目上下文
+### 项目状态

 - [memory-bank/project-brief.md](memory-bank/project-brief.md) - 项目定位
- [memory-bank/tech-stack.md](memory-bank/tech-stack.md) - 技术栈
- [memory-bank/architecture.md](memory-bank/architecture.md) - 架构设计
+- [memory-bank/active-context.md](memory-bank/active-context.md) - 当前上下文
 - [memory-bank/progress.md](memory-bank/progress.md) - 进度追踪
- [memory-bank/decisions.md](memory-bank/decisions.md) - 架构决策

-### 工作流程
+### 工作流入口

- [docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md) - 需求澄清
- [docs/prompts/coding/review.md](docs/prompts/coding/review.md) - 复盘总结
- [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) - 工作模式参考
+- [docs/prompts/README.md](docs/prompts/README.md) - 提示词与流程入口
 <!-- playbook:templates:end -->

 <!-- playbook:framework:end -->
@@ -9,231 +9,290 @@
 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` | 无                   |
-| **执行计划** | **主循环**             | 代码/配置变更     | **plan_progress.py** |
+- `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 不记录操作状态，执行必须通过主循环完成。
+## 主循环执行契约

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

-**触发词**：
+- 常规模式：`执行主循环`、`继续执行`、`下一个 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_progress.py` 自动识别当前环境（`windows` / `linux` / `darwin`）
-2. 选择 Plan：
-   - 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md`
-   - 返回第一个可执行的 Plan：
-     - `pending` 或 `in-progress` 的 Plan
-     - `blocked: env:<当前环境>:...` 的 Plan（环境匹配时恢复执行）
-   - 如无可执行 Plan，跳到步骤 7
-   - **注意**：每次 select 会重新扫描 `docs/plans/` 目录，支持动态添加 Plan
-3. 标记开始：
-   - 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md`
-4. 阅读 Plan：
-   - 理解目标、子任务与验证标准
-   - 如果是从 `blocked: env:...` 恢复，只执行列出的 Task
-5. 逐步执行：
-   - 按顺序执行 Task
-   - 每个 Task 完成后进行必要验证（测试/日志/diff）
-   - **Task 失败处理**：
-     - 环境不匹配（`command not found`、路径不存在）→ 记录该 Task 及所需环境，**继续下一个 Task**
-     - 其他阻塞 → 记录原因，跳到步骤 6 标记 Plan blocked
-   - **安全红线**（明文密钥等）→ 立即停止，不继续后续 Plan
-   - 遇到歧义/风险/决策点：
-     - 常规模式：记录到回复中，可询问用户
-     - 无交互模式：按「需要确认的场景」规则自动处理
-6. 记录结果：
-   - 全部完成：`... -status done ...`
-   - 有 Task 因环境跳过：`... -status blocked ... -note "env:<所需环境>:<Task列表>"`
-   - 其他阻塞：`... -status blocked ... -note "<原因>"`
-   - 跳过整个 Plan：`... -status skipped ... -note "<原因>"`
-   - 回到步骤 2 继续下一个 Plan
-7. 汇总报告（所有 Plan 处理完毕后）：
-   - 已完成的 Plan
-   - 阻塞/跳过的 Plan 及原因
-   - 需要在其他环境执行的 Plan（`blocked: env:...`）
-   - 待确认的歧义/风险/决策点
-   - 如需记录重要决策，写入 `memory-bank/decisions.md`
-8. **结束**：主循环终止
+```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 应该可快速完成
- **可验证**：每个 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}}/plan_progress.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 "<原因>"
+```
+
+### Plan 场景下的分支与隔离策略
+
+- 本节仅适用于通过主循环领取并执行 Plan 的场景
+- 默认允许在当前分支直接执行 Plan，包括 `main` / `master`
+- 不强制为 Plan 执行创建隔离工作区、临时分支或 `git worktree`
+- 仅在以下场景使用隔离工作区：
+  - 用户明确要求隔离执行
+  - Plan 文本自身明确要求隔离执行
+  - 当前任务需要并行隔离以避免相互影响
+- 如外部技能、工具或默认流程要求先隔离，再执行 Plan，以本文件和用户当前指令为准
+
+### 执行规则
+
+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**：严格遵循工具参数定义
- **避免循环**：避免重复调用同一工具获取相同信息
- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob
-
-## 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/` 下的规则（如有）
- [ ] 相关测试通过（如有测试且未被豁免）
- [ ] 换行符正确
- [ ] 无语法错误
- [ ] 已通过 `plan_progress.py` 记录 Plan 状态
+- [ ] 相关验证已执行，且测试在未豁免时通过
+- [ ] 换行符与文件格式正确
+- [ ] 无语法错误或明显运行时错误
+- [ ] 已通过 `main_loop.py finish` 写回 Plan 状态

 ---

@@ -11,8 +11,9 @@ templates/
 ├── AGENT_RULES.template.md      # 执行流程模板
 ├── memory-bank/                 # 项目上下文模板
 │   ├── project-brief.template.md
-│   ├── tech-stack.template.md
-│   ├── architecture.template.md
+│   ├── tech-context.template.md
+│   ├── system-patterns.template.md
+│   ├── active-context.template.md
 │   ├── progress.template.md
 │   └── decisions.template.md
 ├── prompts/                     # 提示词库模板
@@ -21,13 +22,16 @@ templates/
 │   │   └── agent-behavior.template.md
 │   ├── coding/
 │   │   ├── clarify.template.md
-│   │   ├── review.template.md
+│   │   ├── verify-change.template.md
+│   │   ├── close-task.template.md
+│   │   ├── update-memory.template.md
 │   │   └── code-review.template.md
-│   └── meta/
-│       └── prompt-generator.template.md
 ├── ci/                          # CI 模板
+│   ├── README.md
 │   └── gitea/
-│       └── .gitea/workflows/
+│       └── .gitea/
+│           ├── workflows/
+│           └── ci/
 ├── cpp/                         # C++ 配置模板
 │   ├── .clang-format
 │   ├── .clangd
@@ -40,59 +44,35 @@ templates/

 ## 文件分类

-从部署角度，文件分为四类：
+从部署角度看，本目录的文件分成三类：

-| 类型 | 说明 | 部署行为 |
-|------|------|----------|
-| **框架模板** | playbook 提供，可随框架升级 | 可覆盖更新 |
-| **项目上下文** | 首次部署后项目填写 | 首次创建，后续保护 |
-| **项目私有** | 项目手动创建 | 不部署 |
-| **参考资料** | 留在 playbook 快照中参考 | 不部署到项目根 |
+- **会同步更新的框架模板**
+  - `AGENT_RULES.md`
+  - `docs/prompts/system/*.md`
+  - `docs/prompts/coding/*.md`
+  - `AGENTS.md`、`CLAUDE.md`（按 playbook 区块更新）
+- **首次创建后由项目维护的上下文文件**
+  - `memory-bank/*.md`
+  - `AGENT_RULES.local.md`
+- **只保留在快照中参考的模板**
+  - `ci/`
+  - `cpp/`
+  - `python/`

-### 框架模板（A类）
+补充说明：

-```
-AGENT_RULES.md
-AGENTS.md（区块更新）
-docs/prompts/system/*.md     # 框架提供
-docs/prompts/coding/*.md     # 框架提供
-docs/prompts/meta/*.md       # 框架提供
-```
-
-### 项目上下文（B类）
-
-```
-memory-bank/
-├── project-brief.md
-├── tech-stack.md
-├── architecture.md
-├── progress.md
-└── decisions.md
-```
-
-> ⚠️ B类文件首次创建后应由项目填写。`force=true` 会覆盖已填写内容（自动备份）。
-
-### 项目私有（C类，不部署）
-
-```
-AGENT_RULES.local.md         # 项目私有规则
-docs/plans/                  # 项目实施计划
-docs/prompts/custom/         # 项目自定义提示词
-docs/prompts/**/*            # 项目新增的文件不会被删除
-```
-
-### 参考资料（D类，不部署到项目根）
-
-```
-# 留在 docs/standards/playbook/templates/ 中参考
-ci/                      # CI 配置
-cpp/                     # C++ 配置
-python/                  # Python 配置
-```
+- `memory-bank/*.md` 首次创建后应由项目填写；`force=true`
+  会覆盖已填写内容并先备份。
+- `AGENT_RULES.local.md` 由 `[sync_rules]` 首次自动创建，
+  后续不再覆盖。
+- `docs/prompts/custom/` 和项目新增的 `docs/prompts/**/*`
+  不会被 playbook 删除。
+- `CLAUDE.md` 如已有 playbook 区块则更新；如未引用
+  `@AGENTS.md` 则追加；如已手工引用 `@AGENTS.md` 则跳过。

 ## 快速部署

-使用统一入口 `playbook.py`，配置节存在即启用：
+以下命令假设 **playbook 已经部署到项目内**，使用统一入口 `playbook.py`，配置节存在即启用：

 ```toml
 # playbook.toml
@@ -114,24 +94,48 @@ project_name = "MyProject"
 ```

 ```bash
-python docs/standards/playbook/scripts/playbook.py -config playbook.toml
+python <deploy_root>/scripts/playbook.py -config playbook.toml
 ```

-参数说明见 `playbook.toml.example`（仓库根目录）或 vendoring 后的 `docs/standards/playbook/playbook.toml.example`。
+参数说明见 `playbook.toml.example`（仓库根目录）或项目内的
+`<deploy_root>/playbook.toml.example`。
+
+其中 `<deploy_root>` 默认为 `docs/standards/playbook`，
+也可以按项目配置改成 `custom/playbook` 等自定义目录；
+对应文档入口会变成 `<deploy_root>/docs/...`。
+
+如果你当前是在 **外部 clone 的 playbook 仓库** 中执行，而不是在目标项目内执行快照，请使用：
+
+```bash
+python scripts/playbook.py -config playbook.toml
+```
+
+此时 `[vendor]` 会把快照写入 `<project_root>/<deploy_root>`；
+后续再在目标项目内使用 `<deploy_root>/scripts/playbook.py`
+做同步更新。

 ### 配置节说明

-| 配置节               | 部署内容       | 选项                    |
-| -------------------- | -------------- | ----------------------- |
-| `[sync_rules]`       | AGENT_RULES.md | `force`                 |
-| `[sync_memory_bank]` | memory-bank/   | `project_name`, `force` |
-| `[sync_prompts]`     | docs/prompts/  | `force`                 |
+- `[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`

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

 ### 典型场景

@@ -152,26 +156,63 @@ project_name = "MyProject"
 force = true
 ```

+### docs/superpowers 命名约定
+
+为与 thirdparty `superpowers` 上游当前工作流对齐，建议统一使用：
+
+- `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`：
+  `brainstorming` 产出的设计稿
+- `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`：
+  `writing-plans` 产出的实施计划
+
+其中 `plans/` 为主执行入口；`specs/` 只作为设计背景和上游文档。
+
+### 生命周期总览
+
+```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
+```
+
 ### 部署后的目录结构

 ```text
 project/
-├── AGENTS.md              # 路由中心（主入口）
+├── AGENTS.md              # 路由中心（Codex 入口）
 ├── AGENT_RULES.md         # 执行流程
-├── AGENT_RULES.local.md   # 项目私有规则（可选，手动维护）
+├── AGENT_RULES.local.md   # 项目私有规则（自动创建，项目维护）
+├── CLAUDE.md              # Claude Code 入口（按规则维护/追加 playbook 区块）
 ├── memory-bank/           # 项目上下文
 │   ├── project-brief.md
-│   ├── tech-stack.md
-│   ├── architecture.md
+│   ├── tech-context.md
+│   ├── system-patterns.md
+│   ├── active-context.md
 │   ├── progress.md
 │   └── decisions.md
-└── docs/prompts/          # 提示词库
-    ├── README.md
-    ├── system/agent-behavior.md
-    ├── coding/
-    │   ├── clarify.md
-    │   └── review.md
-    └── meta/prompt-generator.md
+└── docs/
+    ├── prompts/           # 提示词库
+    │   ├── README.md
+    │   ├── system/agent-behavior.md
+    │   └── coding/
+    │       ├── clarify.md
+    │       ├── verify-change.md
+    │       ├── close-task.md
+    │       ├── update-memory.md
+    │       └── code-review.md
+    └── superpowers/
+        ├── specs/         # brainstorming 产物
+        └── plans/         # writing-plans / main_loop 消费
 ```

 ## 占位符说明
@@ -184,13 +225,14 @@ project/
 | `{{PROJECT_NAME}}`        | 项目名称     | ✅ 可选  |
 | `{{PROJECT_GOAL}}`        | 项目目标     | ❌ 手动  |
 | `{{PROJECT_DESCRIPTION}}` | 项目描述     | ❌ 手动  |
-| `{{MAIN_LANGUAGE}}`       | 主语言       | ✅ 可选  |
 | `{{PLAYBOOK_SCRIPTS}}`    | 脚本路径     | ✅ 是    |
 | 其他 `{{...}}`            | 项目特定内容 | ❌ 手动  |

-`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；未配置时保持原样。
-`{{MAIN_LANGUAGE}}` 可通过 `sync_standards.langs[0]` 自动替换；未配置时默认 `tsl`。
-`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径（默认 `docs/standards/playbook/scripts`）。
+`{{PROJECT_NAME}}` 可通过 `sync_memory_bank.project_name` 自动替换；
+未配置时保持原样。
+`{{PLAYBOOK_SCRIPTS}}` 自动替换为 Playbook 脚本路径
+（默认 `docs/standards/playbook/scripts`，
+也可按项目配置改成 `custom/playbook/scripts` 等）。

 ## 模板说明

@@ -198,56 +240,35 @@ project/

 项目上下文文档，用于让 AI 快速理解项目：

-| 文件                        | 用途                 |
-| --------------------------- | -------------------- |
-| `project-brief.template.md` | 项目定位、边界、约束 |
-| `tech-stack.template.md`    | 技术栈、工具链、环境 |
-| `architecture.template.md`  | 架构设计、模块职责   |
-| `progress.template.md`      | 开发进度追踪         |
-| `decisions.template.md`     | 架构决策记录（ADR）  |
+| 文件                          | 用途                       |
+| ----------------------------- | -------------------------- |
+| `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` 后缀）：

-| 文件                                | 用途           | 使用场景               |
-| ----------------------------------- | -------------- | ---------------------- |
-| `system/agent-behavior.template.md` | 工作模式参考   | 切换探索/开发/调试模式 |
-| `coding/clarify.template.md`        | 需求澄清模板   | 需求不明确时           |
-| `coding/review.template.md`         | 复盘总结模板   | Plan 完成后复盘        |
-| `coding/code-review.template.md`    | 代码评审流程   | 执行 MR/PR 代码评审    |
-| `meta/prompt-generator.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 代码评审 |

 ### AGENT_RULES.template.md

 执行流程规范，定义 AI 的工作循环和约束。
-如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
-且不会被 `playbook.py` 覆盖。
-主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单，
-自动选择第一个 pending 的 Plan，并要求通过 `scripts/plan_progress.py` 写入状态。
-
-### 示例：不跑测试的计划提示词
-
-当你需要修改代码但暂时不运行测试时，可用以下提示词生成“可执行且不失败”的实施计划：
-
-```text
-你是 Codex。先使用 $brainstorming。
-目标：修改 <模块/功能>，细节如下：<你的需求>
-约束：
- 不跑任何测试（test/ci），但允许做可通过的局部验证（格式化/静态检查/人工 diff）。
- Plan 不能包含任何必然失败或未确认的任务；所有依赖必须在 brainstorming 阶段确认清楚。
- 采用 writing-plans 的固定头部格式，且在 `---` 之后追加 `## Plan Meta`：
-  - Plan Group: <X>
-  - Parent Plan: <docs/plans/...-design.md>
-  - Verification Scope: local
-  - Verification Gate: must-pass
-
-流程：
-1) 先完成 brainstorming，并输出设计文档 `docs/plans/YYYY-MM-DD-<topic>-design.md`。
-2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”，确认后使用 writing-plans 生成实现计划。
-3) 实现计划内明确标注每步要改的文件与命令；验证步骤只包含可通过的局部验证，不包含测试。
-4) 执行计划并更新 `memory-bank/progress.md`。
-```
+如需项目私有规则，建议维护 `AGENT_RULES.local.md`；该文件通常由 `[sync_rules]`
+首次自动创建，其优先级高于 `AGENT_RULES.md`，且后续不会被 `playbook.py` 覆盖。
+计划编排与执行细节建议放在 `prompts/README.md` 或相关 workflow 文档中，
+这里仅说明模板职责与部署边界。

 ### AGENTS.template.md

@@ -260,23 +281,28 @@ project/

 **playbook 标记**（用于自动更新）：

-| 标记                                    | 用途         | 说明                       |
-| --------------------------------------- | ------------ | -------------------------- |
-| `<!-- playbook:agents:start/end -->`    | 语言规则链接 | 由 `[sync_standards]` 管理 |
-| `<!-- playbook:templates:start/end -->` | 路由链接     | AGENTS.md 始终按区块更新   |
-| `<!-- playbook:framework:start/end -->` | 完整框架     | AGENTS.md 始终按区块更新   |
+- `<!-- playbook:agents:start/end -->`：语言规则链接。
+  由 `[sync_standards]` 管理
+- `<!-- playbook:templates:start/end -->`：路由链接。
+  `AGENTS.md` 始终按区块更新
+- `<!-- playbook:framework:start/end -->`：完整框架。
+  `AGENTS.md` 始终按区块更新

 ### ci/、cpp/、python/

-语言和 CI 配置模板。通过 playbook.py 的 `[vendor]` 复制到快照中：
+语言和 CI 配置模板。通过 playbook.py 的 `[vendor]`
+复制到快照中：

-| 目录        | 内容                                      | 部署位置                 |
-| ----------- | ----------------------------------------- | ------------------------ |
-| `ci/gitea/` | Gitea Actions 工作流                      | 快照 `templates/ci/`     |
-| `cpp/`      | .clang-format, .clangd, CMakeLists.txt 等 | 快照 `templates/cpp/`    |
-| `python/`   | pyproject.toml, .editorconfig 等          | 快照 `templates/python/` |
+- `ci/gitea/`：Gitea Actions 工作流与辅助脚本。
+  部署到快照 `templates/ci/`
+- `cpp/`：`.clang-format`、`.clangd`、`CMakeLists.txt`
+  等文件。
+  部署到快照 `templates/cpp/`
+- `python/`：`pyproject.toml`、`.editorconfig` 等文件。
+  部署到快照 `templates/python/`

 > 注意：这些模板通过 `[vendor]` 复制到快照的 `templates/` 目录，需手动从快照复制到项目根目录使用。
+> 其中 `ci/gitea/` 应按 `templates/ci/README.md` 的说明，整块复制 `.gitea/` 目录，而不只是复制 workflows。

 **使用方式**：

@@ -291,7 +317,7 @@ langs = ["tsl", "cpp", "python"]

 ```bash
 python scripts/playbook.py -config playbook.toml
-# 然后手动从 docs/standards/playbook/templates/ 复制所需配置到项目根目录
+# 然后手动从 <deploy_root>/templates/ 复制所需配置到项目根目录
 ```

 ## 与 playbook 其他部分的关系
@@ -299,19 +325,18 @@ python scripts/playbook.py -config playbook.toml
 ```text
 playbook/
 ├── rulesets/        # 语言级硬规则 → 部署到 .agents/
-├── codex/skills/    # 按需加载的技能
+├── skills/          # 按需加载的技能（thirdparty/ 为第三方同步）
 ├── docs/            # 权威静态文档
 ├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
 └── scripts/
-    ├── playbook.py        # 统一入口：vendor/sync_rules/sync_memory_bank/sync_prompts/sync_standards/...
-    └── plan_progress.py   # Plan 选择与进度记录
+    └── playbook.py    # 统一入口：vendor / sync_*
 ```

 ## 完整部署流程

 ```bash
 # 1. 准备配置并执行统一入口
-python docs/standards/playbook/scripts/playbook.py -config playbook.toml
+python <deploy_root>/scripts/playbook.py -config playbook.toml

 # 2. 编辑 memory-bank/*.md 填写项目信息

@@ -320,4 +345,4 @@ python docs/standards/playbook/scripts/playbook.py -config playbook.toml

 ---

-**最后更新**：2026-01-26
+**最后更新**：2026-05-18
@@ -11,7 +11,7 @@

 ## 使用（Gitea Actions）

-前提：目标项目已经 vendoring Playbook（例如 `docs/standards/playbook/`）。
+前提：目标项目已经把 Playbook 部署到项目内（例如 `docs/standards/playbook/`）。

 复制到目标项目根目录：

@@ -29,47 +29,38 @@ jobs:
          echo "========================================"

          REPO_NAME="${{ github.event.repository.name }}"
-          REPO_DIR="${{ env.WORKSPACE_DIR }}/$REPO_NAME"
          TOKEN="${{ secrets.WORKFLOW }}"
+          mkdir -p "${{ env.WORKSPACE_DIR }}"
+          REPO_DIR="$(mktemp -d "${{ env.WORKSPACE_DIR }}/${REPO_NAME}.XXXXXX")"
          if [ -n "$TOKEN" ]; then
            REPO_URL="https://oauth2:${TOKEN}@${GITHUB_SERVER_URL#https://}/${{ github.repository }}.git"
          else
            REPO_URL="${GITHUB_SERVER_URL}/${{ github.repository }}.git"
          fi

-          if [ -d "$REPO_DIR" ]; then
-            if [ -d "$REPO_DIR/.git" ]; then
-              cd "$REPO_DIR"
-              git clean -fdx
-              git reset --hard
-              git fetch --all --tags --force --prune --prune-tags
-            else
-              rm -rf "$REPO_DIR"
-            fi
-          fi
-
-          if [ ! -d "$REPO_DIR/.git" ]; then
-            mkdir -p "${{ env.WORKSPACE_DIR }}"
-            git clone "$REPO_URL" "$REPO_DIR"
-            cd "$REPO_DIR"
-          fi
+          git clone "$REPO_URL" "$REPO_DIR"

          TARGET_SHA="${{ github.sha }}"
          TARGET_REF="${{ github.ref }}"
-          if git cat-file -e "$TARGET_SHA^{commit}" 2>/dev/null; then
-            git checkout -f "$TARGET_SHA"
+          if git -C "$REPO_DIR" cat-file -e "$TARGET_SHA^{commit}" 2>/dev/null; then
+            git -C "$REPO_DIR" checkout -f "$TARGET_SHA"
          else
            if [ -n "$TARGET_REF" ]; then
-              git fetch origin "$TARGET_REF"
-              git checkout -f FETCH_HEAD
+              git -C "$REPO_DIR" fetch origin "$TARGET_REF"
+              git -C "$REPO_DIR" checkout -f FETCH_HEAD
            else
-              git checkout -f "${{ github.ref_name }}"
+              git -C "$REPO_DIR" checkout -f "${{ github.ref_name }}"
            fi
          fi

          git config --global --add safe.directory "$REPO_DIR"
-          echo "REPO_DIR=$REPO_DIR" >> $GITHUB_ENV
+          echo "REPO_DIR=$REPO_DIR" >> "$GITHUB_ENV"
      - name: 🧪 Lint commit message / PR title
        run: |
          cd "$REPO_DIR"
          python3 .gitea/ci/commit_message_lint.py
+
+      - name: 🧹 清理临时仓库
+        if: always()
+        run: |
+          rm -rf "$REPO_DIR"
@@ -0,0 +1,48 @@
+# 当前上下文
+
+<!--
+填写指南：
+- 本文件记录高频变化的上下文，供 AI 在跨 Session 时快速恢复工作状态
+- 保持简洁，只写“现在仍然重要”的信息
+- 任务完成或方向切换后及时更新
+-->
+
+## Current Goal
+
+<!-- 当前最重要的目标；一句话即可 -->
+
+- {{CURRENT_GOAL}}
+
+## Recent Changes
+
+<!-- 最近完成且会影响后续判断的变更 -->
+
+- {{RECENT_CHANGE_1}}
+
+## Touched Files
+
+<!-- 最近修改或正在关注的关键文件 -->
+
+- `{{FILE_1}}` - {{FILE_1_REASON}}
+
+## Open Questions
+
+<!-- 尚未确认、但会影响实现或验证的事项 -->
+
+- {{QUESTION_1}}
+
+## Next Steps
+
+<!-- 接下来最优先的 1-3 步 -->
+
+1. {{NEXT_STEP_1}}
+
+## Session Notes
+
+<!-- 只记录本轮最容易忘的上下文 -->
+
+- {{SESSION_NOTE_1}}
+
+---
+
+**最后更新**：{{DATE}}
@@ -1,44 +0,0 @@
-# 架构设计
-
-<!--
-填写指南：
- 【必填】：项目启动前必须填写
- 【可选】：按需填写，可随项目发展补充
- 小项目可只填核心模块，架构图可后补
-->
-
-## 整体架构
-
-<!-- 【可选】项目成熟后补充 -->
-
-```txt
-{{ARCHITECTURE_DIAGRAM}}
-```
-
-## 核心模块
-
-<!-- 【必填】至少列出主要模块 -->
-
-### {{MODULE_1}}
-
-**职责**：{{MODULE_1_DESC}}
-
-## 关键约束
-
-<!-- 【可选】 -->
-
- {{CONSTRAINT_1}}
-
-## 扩展点
-
-<!-- 【可选】大项目建议填写 -->
-
-### {{EXTENSION_1}}
-
-**步骤**：
-
-1. {{STEP_1}}
-
---
-
-**最后更新**：{{DATE}}
@@ -1,4 +1,54 @@
-# Plan 状态
+# 当前进展
+
+<!--
+填写指南：
+- 上半部分给人类和 AI 快速恢复上下文
+- 中间的 workflow-state 块记录当前阶段、spec、plan 与执行约束
+- 下半部分的 plan-status 块由 main_loop.py 维护，是唯一权威状态源
+-->
+
+## Current Focus
+
+- {{CURRENT_FOCUS}}
+
+## Recent Changes
+
+- {{RECENT_CHANGE_1}}
+
+## Next Steps
+
+1. {{NEXT_STEP_1}}
+
+## Open Risks
+
+- {{RISK_1}}
+
+## 状态块示例
+
+以下示例仅用于说明结构，真实状态由 `main_loop.py` 维护：
+
+```text
+## Workflow State
+<!-- workflow-state:start -->
+phase: planning
+spec: docs/superpowers/specs/2026-05-18-demo-design.md
+plan: docs/superpowers/plans/2026-05-18-demo.md
+executor: executing-plans
+constraints: karpathy-guidelines,.agents,AGENT_RULES
+<!-- workflow-state:end -->
+
+## Plan Status
+<!-- plan-status:start -->
+- [ ] `2026-05-18-demo.md` pending
+<!-- plan-status:end -->
+```
+
+## Workflow State
+
+<!-- workflow-state:start -->
+<!-- workflow-state:end -->
+
+## Plan Status

 <!-- plan-status:start -->
 <!-- plan-status:end -->
@@ -0,0 +1,60 @@
+# 系统模式与约束
+
+<!--
+填写指南：
+- 本文件记录跨模块稳定成立的实现模式，而不是一次性的设计草图
+- 优先记录：模块边界、数据流、不变量、扩展路径、禁止破坏的约束
+- 小项目可只保留最关键的 2-3 个部分
+-->
+
+## 模块边界
+
+<!-- 至少列出主要模块及其职责边界 -->
+
+### {{MODULE_1}}
+
+- **职责**：{{MODULE_1_DESC}}
+- **输入**：{{MODULE_1_INPUT}}
+- **输出**：{{MODULE_1_OUTPUT}}
+- **不应负责**：{{MODULE_1_NON_GOAL}}
+
+## 关键数据流
+
+<!-- 描述系统中的主路径；按“输入 -> 处理 -> 输出”写 -->
+
+1. {{FLOW_STEP_1}}
+2. {{FLOW_STEP_2}}
+3. {{FLOW_STEP_3}}
+
+## 核心不变量
+
+<!-- 这些约束一旦被破坏，系统行为就可能失真 -->
+
+- {{INVARIANT_1}}
+
+## 常见实现模式
+
+<!-- 给 AI 明确“这里通常怎么改” -->
+
+### {{PATTERN_1}}
+
+- **适用场景**：{{PATTERN_1_SCENARIO}}
+- **推荐做法**：{{PATTERN_1_APPROACH}}
+- **避免事项**：{{PATTERN_1_AVOID}}
+
+## 扩展路径
+
+<!-- 新增功能时，优先走哪些入口或目录 -->
+
+1. {{EXTENSION_STEP_1}}
+2. {{EXTENSION_STEP_2}}
+
+## 禁止破坏的约束
+
+<!-- 记录兼容性、安全性或组织层面的硬约束 -->
+
+- {{DO_NOT_BREAK_1}}
+
+---
+
+**最后更新**：{{DATE}}
@@ -0,0 +1,72 @@
+# 技术上下文与工具链
+
+<!--
+填写指南：
+- 本文件记录“如何在这个仓库里安全工作”
+- 优先填写命令、环境、入口路径、依赖限制
+- 未填写的占位符保持原样或删除整行
+-->
+
+## 核心技术
+
+<!-- 【必填】项目主要语言、框架、运行时 -->
+
+- {{TECH_1}}
+
+## 项目结构
+
+<!-- 【必填】至少列出关键目录 -->
+
+```text
+{{PROJECT_NAME}}/
+├── {{DIR_1}}/           # {{DIR_1_DESC}}
+└── memory-bank/         # 项目上下文
+```
+
+## 关键入口
+
+<!-- 【必填】AI 最常用的入口文件、命令或目录 -->
+
+- `{{ENTRY_PATH_1}}` - {{ENTRY_PATH_1_DESC}}
+
+## 开发环境
+
+<!-- 【必填】至少填写验证相关命令 -->
+
+**必需工具**：
+
+- {{TOOL_1}}
+
+**运行测试**：
+
+```bash
+{{TEST_CMD}}
+```
+
+**格式化 / Lint**：
+
+```bash
+{{FORMAT_OR_LINT_CMD}}
+```
+
+## 环境与平台差异
+
+<!-- 【可选】如 Windows/Linux/macOS 行为不同，写在这里 -->
+
+- {{ENV_DIFF_1}}
+
+## 依赖与限制
+
+<!-- 【可选】外部服务、私有依赖、危险命令、慢命令 -->
+
+- {{DEPENDENCY_OR_LIMIT_1}}
+
+## 验证约定
+
+<!-- 【可选】什么叫“验证通过” -->
+
+- {{PASS_CONDITION_1}}
+
+---
+
+**最后更新**：{{DATE}}
@@ -1,64 +0,0 @@
-# 技术栈与工具链
-
-<!--
-填写指南：
- 【必填】：项目启动前必须填写
- 【可选】：按需填写，可随项目发展补充
- 未填写的占位符保持原样或删除整行
-->
-
-## 核心技术
-
-<!-- 【必填】 -->
-
-**主语言**：{{MAIN_LANGUAGE}}
-
-**文件类型**：{{FILE_TYPES}}
-
-## 项目结构
-
-<!-- 【必填】 -->
-
-```text
-{{PROJECT_NAME}}/
-├── {{DIR_1}}/           # {{DIR_1_DESC}}
-└── memory-bank/         # 项目上下文
-```
-
-## 开发环境
-
-<!-- 【必填】至少填写运行测试命令 -->
-
-**必需工具**：
-
- {{TOOL_1}}
-
-**运行测试**：
-
-```bash
-{{TEST_CMD}}
-```
-
-## 依赖管理
-
-<!-- 【可选】 -->
-
-**外部依赖**：
-
- {{EXTERNAL_DEP_1}}
-
-## 测试策略
-
-<!-- 【可选】大项目建议填写 -->
-
-**测试类型**：
-
- {{TEST_TYPE_1}}
-
-**验证标准**：
-
- {{PASS_CONDITION_1}}
-
---
-
-**最后更新**：{{DATE}}
@@ -1,6 +1,6 @@
-# 提示词库
+# 提示词入口

-本目录包含 AI 代理的工作流程参考模板。
+本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。

 ## 目录结构

@@ -8,44 +8,67 @@
 prompts/
 ├── README.md              # 本文件
 ├── system/
-│   └── agent-behavior.md  # 工作模式参考
+│   └── agent-behavior.md  # 工作流入口
 ├── coding/
 │   ├── clarify.md         # 需求澄清模板
-│   ├── review.md          # 复盘总结模板
+│   ├── verify-change.md   # 变更验证模板
+│   ├── close-task.md      # 本轮收尾模板
+│   ├── update-memory.md   # 回写记忆模板
 │   └── code-review.md     # MR/PR 代码评审流程
-└── meta/
-    └── prompt-generator.md # 元提示词生成器
+└── custom/                # 可选：项目私有提示词
 ```

 ## 使用方式

-| 模板                    | 触发场景                       |
-| ----------------------- | ------------------------------ |
-| **agent-behavior.md**   | 切换工作模式（探索/开发/调试） |
-| **clarify.md**          | 需求不明确时澄清               |
-| **review.md**           | Plan 完成后复盘总结            |
-| **code-review.md**      | 执行 MR/PR 代码评审            |
-| **prompt-generator.md** | 创建新的专用提示词             |
+| 模板                  | 触发场景             |
+| --------------------- | -------------------- |
+| **agent-behavior.md** | 选择工作流入口       |
+| **clarify.md**        | 需求不明确时澄清     |
+| **verify-change.md**  | 声称完成前做验证     |
+| **close-task.md**     | 本轮工作收尾         |
+| **update-memory.md**  | 上下文变化后回写记忆 |
+| **code-review.md**    | 执行 MR/PR 代码评审  |
+| **custom/*.md**       | 项目私有补充流程     |

 ## 工作流程

-```
+```text
 需求不清 → clarify.md
    ↓
-头脑风暴 → $brainstorming skill
+入口约束 → using-superpowers
    ↓
-生成计划 → $writing-plans skill → docs/plans/*.md
+头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md
    ↓
-执行计划 → AGENT_RULES 主循环（留痕）
+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
-    ↓
-完成复盘 → review.md
-    ↓
-沉淀提示词 → prompt-generator.md（可选）
 ```

-> **核心规则在 `AGENT_RULES.md`**，第三方 skills 负责规划，主循环负责执行和留痕。
+> `coding/` 下是可被框架覆盖更新的标准模板；
+> 项目私有流程应沉淀到 `custom/`。
+>
+> `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`，
+> 长期记忆在 `memory-bank/`，状态留痕必须走
+> `playbook.py -record-spec/-record-plan` 与
+> `main_loop.py claim/finish`。

 ---

@@ -0,0 +1,60 @@
+# 收尾模板
+
+<!--
+用途：一轮实现或一个 Plan 结束后做收尾
+触发：准备结束当前任务、切换上下文、交付结果前
+-->
+
+## 目标
+
+确认当前任务已经形成可交付结果，并把后续工作所需的信息留痕。
+
+## 执行步骤
+
+### 1. 核对结果
+
+- 已完成哪些改动？
+- 哪些内容仍未完成？
+- 是否存在阻塞、风险或待确认事项？
+
+### 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
+## 本轮结果
+
+- 已完成：...
+- 未完成：...
+- 验证：...
+- 风险 / 待确认：...
+- 下一步：...
+```
+
+## 原则
+
+- 只写对下一轮仍然重要的信息
+- 未验证的内容必须显式说明
+- 如果任务状态变更，优先通过 `main_loop.py finish` 留痕
+- 不手工改写 `workflow-state` 或 `plan-status` 状态块
+
+---
+
+**最后更新**：{{DATE}}
@@ -69,12 +69,12 @@ gh pr diff <PR_NUMBER>

 ## AI 与人工的分工

-| 维度 | 负责方 | 说明 |
-| ---- | ------ | ---- |
-| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
-| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 |
-| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 |
-| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 |
+| 维度                       | 负责方        | 说明                                  |
+| -------------------------- | ------------- | ------------------------------------- |
+| Bug、逻辑漏洞、安全问题    | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
+| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳     |
+| 架构合理性、业务对齐       | **人工**      | AI 反馈少且准确率低，需人工把关       |
+| 兼容性、历史债务、战略取舍 | **人工**      | 依赖背景知识，AI 难以判断             |

 > 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。
 >
@@ -1,66 +0,0 @@
-# 复盘模板
-
-<!--
-用途：Plan 或阶段完成后的回顾总结
-触发：主循环汇总报告时、阶段性工作完成时
-->
-
-## 何时使用
-
- 一批 Plan 执行完毕后
- 阶段性工作告一段落
- 遇到重大阻塞需要总结
-
---
-
-## 复盘格式
-
-```markdown
-# 复盘: [日期/阶段名称]
-
-## 完成情况
-
-### 已完成
- [x] Plan 1: 简述
- [x] Plan 2: 简述
-
-### 阻塞
- [ ] Plan 3: 阻塞原因
-
-### 跳过
- [ ] Plan 4: 跳过原因
-
-## 关键发现
-
-### 做得好的
- 发现1
- 发现2
-
-### 待改进
- 问题1 → 建议改进方式
- 问题2 → 建议改进方式
-
-## 决策记录
-
-| 决策 | 理由 | 影响 |
-|------|------|------|
-| 决策1 | 为什么 | 影响范围 |
-
-## 下一步
-
- [ ] 待处理事项1
- [ ] 待处理事项2
-```
-
---
-
-## 复盘原则
-
- **客观记录**：如实记录完成/阻塞/跳过
- **提取经验**：总结做得好的和待改进的
- **决策留痕**：重要决策记录到 decisions.md
- **明确下一步**：列出后续待处理事项
-
---
-
-**最后更新**：{{DATE}}
@@ -0,0 +1,79 @@
+# 回写记忆模板
+
+<!--
+用途：在任务完成、方向切换或发现新规律后更新 memory-bank
+触发：完成一轮实现、形成新决策、当前焦点变化时
+-->
+
+## 什么时候需要回写
+
+- 当前目标已经变化
+- 最近改动会影响下一轮判断
+- 发现新的系统模式或约束
+- 做出了值得保留的决策
+
+## 回写路径
+
+### `memory-bank/active-context.md`
+
+更新：
+
+- 当前目标
+- 最近变更
+- touched files
+- 下一步
+
+### `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`
+- `progress.md` 的状态块只由 `main_loop.py` 维护
+- 摘要应与 `workflow-state` / `plan-status` 保持一致
+
+---
+
+**最后更新**：{{DATE}}
@@ -0,0 +1,69 @@
+# 变更验证模板
+
+<!--
+用途：在声明“完成 / 修复 / 可交付”前，明确验证范围与证据
+触发：代码修改、配置修改、模板修改、规则修改后
+-->
+
+## 验证目标
+
+- 这次改动要证明什么？
+- 哪些行为必须通过？
+- 哪些验证本轮不做？
+
+## 验证步骤
+
+### 1. 语法 / 结构检查
+
+- 确认修改文件可读、可解析、无明显结构错误
+
+### 2. 定向验证
+
+- 只跑与本次改动直接相关的验证命令
+- 记录命令、结果和关键输出
+- 如仓库存在项目私有验证提示词（例如 `docs/prompts/custom/verify.md`），先读取并执行其中的附加约束
+
+```bash
+{{VERIFY_CMD}}
+```
+
+### 3. 差异复核
+
+- 核对 diff 是否只包含预期修改
+- 确认没有误删、误改、命名漂移或路径漂移
+
+### 4. 状态留痕复核
+
+- `workflow-state.phase` 是否与当前声明一致
+- `plan-status` 是否已经通过 `main_loop.py finish` 写回
+- 如为代码类任务，`workflow-state` 中是否保留：
+  `executor=executing-plans`
+  `constraints=karpathy-guidelines,.agents,AGENT_RULES`
+
+### 5. 剩余风险
+
+- 本轮未覆盖的验证
+- 环境限制
+- 需要人工确认的点
+
+## 输出格式
+
+```markdown
+## 验证结果
+
+- 已验证：...
+- 证据：...
+- 未验证：...
+- 风险：...
+```
+
+## 原则
+
+- 没有证据，不宣称完成
+- 局部修改优先局部验证
+- 不能运行的验证要明确写原因
+- 不手工改写 `workflow-state` 或 `plan-status` 状态块
+
+---
+
+**最后更新**：{{DATE}}
@@ -84,7 +84,7 @@

 ### 2. 迭代优化

-```
+```text
 草稿 → 评估 → 修改 → 再评估 → ... → 定稿
 ```

@@ -1,61 +1,49 @@
-# 工作模式参考
+# 工作流入口

 <!--
-本文件定义三种工作模式，供 AI 根据任务类型选择。
-核心规则（安全红线、验证清单等）见 AGENT_RULES.md。
+本文件不重复定义核心规则；它只负责把任务路由到合适的工作流入口。
+安全红线、验证要求、主循环规则见 AGENT_RULES.md。
 -->

-## 模式 1: 探索模式（Explore）
+## 路由原则

-**目的**：理解代码库、分析问题、收集信息
+- 需求不明确：先看 `docs/prompts/coding/clarify.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
+```

-**适用场景**：
+## 说明

- 理解某个模块的实现
- 分析 bug 的根本原因
- 评估功能实现的可行性
-
---
-
-## 模式 2: 开发模式（Develop）
-
-**目的**：实现功能、修复 bug、重构代码
-
-**行为**：
-
- 先读取相关文件，理解现有逻辑
- 进行精确修改
- 修改后运行测试验证
-
-**适用场景**：
-
- 实现新功能
- 修复已知 bug
- 优化性能
-
---
-
-## 模式 3: 调试模式（Debug）
-
-**目的**：诊断问题、对比差异、验证行为
-
-**行为**：
-
- 收集相关日志和输出
- 分析差异原因
- 修复后重新验证
-
-**适用场景**：
-
- 测试失败
- 输出不符合预期
- 性能问题诊断
+- `prompts/` 是入口，不是规则权威
+- 稳定约束写入 `memory-bank/` 或 `AGENT_RULES.local.md`
+- 执行留痕以 `memory-bank/progress.md` 的
+  `workflow-state` 与 `plan-status` 为准

 ---