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

templates/README.md

@@ -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