📝 docs(playbook): update prompts and sync notes

README.md

@@ -46,7 +46,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）
 `templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板：
 
 - `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-stack、architecture、progress、decisions）
-- `templates/prompts/`：工作流程模板（agent-behavior、clarify、verify）
+- `templates/prompts/`：工作流程模板（agent-behavior、clarify、review）
 - `templates/AGENTS.template.md`：路由中心模板（项目主入口）
 - `templates/AGENT_RULES.template.md`：执行流程模板
 

playbook.toml.example

@@ -17,13 +17,16 @@
 
 [sync_memory_bank]
 # 同步 memory-bank/（配置节存在即启用）
+# 只更新框架提供的文件，项目新增的文件不会被删除
+# ⚠️ force=true 会覆盖已填写的项目信息（自动备份）
 # project_name = "MyProject"    # 可选：替换 {{PROJECT_NAME}}
-# force = false                 # 可选：覆盖已有目录（会先备份）
+# force = false                 # 可选：覆盖已有文件（会先备份）
 # no_backup = false             # 可选：跳过备份
 
 [sync_prompts]
 # 同步 docs/prompts/（配置节存在即启用）
-# force = false                 # 可选：覆盖已有目录（会先备份）
+# 只更新框架提供的文件，项目新增的文件不会被删除
+# force = false                 # 可选：覆盖已有文件（会先备份）
 # no_backup = false             # 可选：跳过备份
 
 [sync_standards]

templates/README.md

@@ -19,9 +19,11 @@ templates/
 │   ├── README.md
 │   ├── system/
 │   │   └── agent-behavior.template.md
-│   └── coding/
+│   ├── coding/
-│       ├── clarify.template.md
+│   │   ├── clarify.template.md
-│       └── verify.template.md
+│   │   └── review.template.md
+│   └── meta/
+│       └── prompt-generator.template.md
 ├── ci/                          # CI 模板
 │   └── gitea/
 │       └── .gitea/workflows/
@@ -35,6 +37,58 @@ templates/
     └── ...
 ```
 
+## 文件分类
+
+从部署角度，文件分为四类：
+
+| 类型 | 说明 | 部署行为 |
+|------|------|----------|
+| **框架模板** | playbook 提供，可随框架升级 | 可覆盖更新 |
+| **项目上下文** | 首次部署后项目填写 | 首次创建，后续保护 |
+| **项目私有** | 项目手动创建 | 不部署 |
+| **参考资料** | 留在 playbook 快照中参考 | 不部署到项目根 |
+
+### 框架模板（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 配置
+```
+
 ## 快速部署
 
 使用统一入口 `playbook.py`，配置节存在即启用：
@@ -74,7 +128,8 @@ python docs/standards/playbook/scripts/playbook.py -config playbook.toml
 
 - **配置节存在即启用**：只写需要同步的配置节
 - **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制
-- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（memory-bank/ 和 prompts/ 会先备份）
+- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
+- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
 - **占位符替换**：自动替换 `{{DATE}}`、`{{PLAYBOOK_SCRIPTS}}` 等
 
 ### 典型场景
@@ -112,9 +167,10 @@ project/
 └── docs/prompts/          # 提示词库
     ├── README.md
     ├── system/agent-behavior.md
-    └── coding/
+    ├── coding/
-        ├── clarify.md
+    │   ├── clarify.md
-        └── verify.md
+    │   └── review.md
+    └── meta/prompt-generator.md
 ```
 
 ## 占位符说明
@@ -151,21 +207,22 @@ project/
 
 ### prompts/
 
-工作流程模板：
+工作流程模板（部署后去掉 `.template` 后缀）：
 
-| 文件                                | 用途         |
+| 文件                                | 用途           | 使用场景               |
-| ----------------------------------- | ------------ |
+| ----------------------------------- | -------------- | ---------------------- |
-| `system/agent-behavior.template.md` | AI 行为规范  |
+| `system/agent-behavior.template.md` | 工作模式参考   | 切换探索/开发/调试模式 |
-| `coding/clarify.template.md`        | 需求澄清模板 |
+| `coding/clarify.template.md`        | 需求澄清模板   | 需求不明确时           |
-| `coding/verify.template.md`         | 验证检查清单 |
+| `coding/review.template.md`         | 复盘总结模板   | Plan 完成后复盘        |
+| `meta/prompt-generator.template.md` | 元提示词生成器 | 创建新的专用提示词     |
 
 ### AGENT_RULES.template.md
 
 执行流程规范，定义 AI 的工作循环和约束。
 如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
 且不会被 `playbook.py` 覆盖。
-主循环会根据 `memory-bank/progress.md` 的 Plan 状态与 `docs/plans/` 文件名日期，
+主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单，
-自动选择最新未完成的 Plan，并要求通过 `scripts/plan_progress.py` 写入进度。
+自动选择第一个 pending 的 Plan，并要求通过 `scripts/plan_progress.py` 写入状态。
 
 ### 示例：不跑测试的计划提示词
 

tests/README.md

@@ -11,6 +11,8 @@ tests/
 │   └── test_playbook_cli.py        # playbook.py 基础功能测试
 ├── test_format_md_action.py        # format_md 动作测试
 ├── test_gitattributes_modes.py     # gitattr_mode 行为测试
+├── test_sync_directory_actions.py  # sync_memory_bank/sync_prompts 行为测试
+├── test_vendor_snapshot_templates.py # vendor 快照模板完整性测试
 ├── test_plan_progress_cli.py       # plan_progress CLI 测试
 ├── test_superpowers_list_sync.py   # superpowers 列表一致性测试
 ├── test_sync_templates_placeholders.py # 占位符替换测试（sync_rules/sync_standards）