🔧 chore(templates): align agent templates and docs

- drop implementation-plan template and references
- add AGENT_RULES.local.md precedence in templates
- add plan meta guidance and CN updates

AGENTS.md

@@ -1,146 +1,143 @@
-# Agent Instructions (playbook)
+# 代理指引（playbook）
 
-> About the special nature of the playbook repo:
+> 关于 playbook 仓库的特殊性：
 >
-> - In the playbook repo: ruleset templates live in `rulesets/`
+> - 在 playbook 仓库中：规则集模板位于 `rulesets/`
-> - In target projects: after sync from playbook, rulesets live in `.agents/`
+> - 在目标项目中：同步后规则集位于 `.agents/`
-> - AI agents read `.agents/` in the target project root (generated by sync_standards.sh)
+> - AI 代理读取目标项目根目录的 `.agents/`（由 sync_standards.sh 生成）
 >
-> This document applies to target projects. The playbook repo itself has no
+> 本文适用于目标项目。playbook 仓库自身没有源代码，不需要 AI 代理规则。
-> source code and does not need AI agent rules.
 
-Use the rules under `.agents/` as the source of truth:
+以 `.agents/` 下规则为准：
 
-- Entry: `.agents/index.md`
+- 入口：`.agents/index.md`
-- Language rules: `.agents/tsl/index.md`, `.agents/cpp/index.md`,
+- 语言规则：`.agents/tsl/index.md`、`.agents/cpp/index.md`、
-  `.agents/python/index.md`, `.agents/markdown/index.md`
+  `.agents/python/index.md`、`.agents/markdown/index.md`
 
 ---
 
-## Three-layer architecture (layered knowledge base)
+## 三层架构（分层知识库）
 
-This repo organizes agent rules and knowledge into three layers:
+本仓库将代理规则与知识分为三层：
 
-### Layer 1: `.agents/` (minimal hard rules, <= 50 lines per language)
+### Layer 1: `.agents/`（最小硬规则，每种语言 ≤ 50 行）
 
-- Load: automatic, always in context
+- 加载：自动，始终在上下文中
-- Content: hard constraints and safety red lines
+- 内容：硬约束与安全红线
-- Role: quick decisions on what can or cannot be done
+- 作用：快速判断能做/不能做
-- Size control: TSL 44 lines | Python 45 lines | C++ 47 lines | Markdown 31 lines
+- 规模控制：TSL 44 行 | Python 45 行 | C++ 47 行 | Markdown 31 行
 
-### Layer 2: `codex/skills/` (on-demand, 100-1000 lines per skill)
+### Layer 2: `codex/skills/`（按需加载，每个 skill 100-1000 行）
 
-- Load: triggered by `$<skill-name>` or inferred by the agent
+- 加载：由 `$<skill-name>` 触发或由代理判定
-- Content: how-to guidance, best practices, workflows
+- 内容：操作指南、最佳实践、工作流
-- Role: detailed guidance on how to do the task
+- 作用：指导具体怎么做
 
-Key skills:
+关键技能：
 
-- `$tsl-guide` - progressive TSL syntax training (basic/advanced/functions/best practices)
+- `$tsl-guide` - TSL 渐进式语法训练（基础/高级/函数/最佳实践）
-- `$commit-message` - commit message convention
+- `$commit-message` - 提交信息规范
-- `$style-cleanup` - formatting/style cleanup
+- `$style-cleanup` - 格式与风格整理
-- `$bulk-refactor-workflow` - safe bulk refactor workflow
+- `$bulk-refactor-workflow` - 安全批量重构流程
 
-### Layer 3: `docs/` (authoritative static docs)
+### Layer 3: `docs/`（权威静态文档）
 
-- Load: on-demand for specific sections
+- 加载：按需读取特定章节
-- Content: full language manuals, code style, toolchain config
+- 内容：完整语言手册、代码风格、工具链配置
-- Role: the final authority
+- 作用：最终权威
-- Conflict handling: when rules conflict, follow `docs/`
+- 冲突处理：规则冲突时以 `docs/` 为准
 
-Note: the function library is split under `docs/tsl/syntax_book/function/`.
+注：函数库拆分在 `docs/tsl/syntax_book/function/` 下。
-Do not load the whole directory. Load only the needed fragments.
+不要加载整个目录，只加载需要的片段。
 
 ---
 
-## Usage scenarios
+## 使用场景
 
-### Scenario 1: write a simple TSL function
+### 场景 1：编写简单的 TSL 函数
 
 ```text
-1. Auto read .agents/tsl/index.md (44 lines)
+1. 自动读取 .agents/tsl/index.md（44 行）
-2. Trigger $tsl-guide, load SKILL.md (192 lines)
+2. 触发 $tsl-guide，加载 SKILL.md（192 行）
-3. Generate code
+3. 生成代码
 
-Token cost: ~6,000 tokens
+Token 消耗：~6,000 tokens
 ```
 
-### Scenario 2: write a TSL class
+### 场景 2：编写 TSL 类
 
 ```text
-1. Auto read .agents/tsl/index.md (44 lines)
+1. 自动读取 .agents/tsl/index.md（44 行）
-2. Trigger $tsl-guide, load SKILL.md + references/advanced.md
+2. 触发 $tsl-guide，加载 SKILL.md + references/advanced.md
-3. Generate code
+3. 生成代码
 
-Token cost: ~10,000 tokens
+Token 消耗：~10,000 tokens
 ```
 
-### Scenario 3: find a TSL function library entry
+### 场景 3：查询 TSL 函数库条目
 
 ```text
-1. Auto read .agents/tsl/index.md (44 lines)
+1. 自动读取 .agents/tsl/index.md（44 行）
-2. Trigger $tsl-guide, load references/functions_index.md
+2. 触发 $tsl-guide，加载 references/functions_index.md
-3. Use rg to locate the function fragment
+3. 使用 rg 定位函数片段
-4. Return the answer
+4. 返回答案
 
-Token cost: ~8,000 tokens
+Token 消耗：~8,000 tokens
 ```
 
 ---
 
-## Performance metrics
+## 性能指标
 
-| Metric              | Before     | Now       | Improvement |
+| 指标            | 之前     | 现在     | 改善 |
-| ------------------- | ---------- | --------- | ----------- |
+| --------------- | -------- | -------- | ---- |
-| .agents size        | ~500 lines | 168 lines | -66%        |
+| .agents 规模    | ~500 行  | 168 行   | -66% |
-| Persistent tokens   | ~12,500    | ~4,200    | -66%        |
+| 持久化 tokens   | ~12,500  | ~4,200   | -66% |
-| Avg scenario tokens | ~12,500    | ~10,500   | -16%        |
+| 场景平均 tokens | ~12,500  | ~10,500  | -16% |
 
 ---
 
-## Maintenance principles
+## 维护原则
 
-### .agents/ modification rules
+### .agents/ 修改规则
 
-Do:
+可做：
 
-- Add new security vulnerability types
+- 增加新的安全漏洞类型
-- Update core conventions (file names, format rules)
+- 更新核心约定（文件名、格式规则）
-- Add non-negotiable hard constraints
+- 添加不可妥协的硬性约束
 
-Do not:
+不可做：
 
-- Add recommended best practices (put them in a skill)
+- 添加推荐型最佳实践（放到 skill）
-- Add detailed syntax explanations (put them in a skill or docs)
+- 添加详细语法解释（放到 skill 或 docs）
-- Exceed the 50-line limit (split into skills)
+- 超过 50 行限制（拆分为 skill）
 
-### Skills creation rules
+### Skills 创建规则
 
-Do:
+可做：
 
-- Add new workflows (e.g., code-review)
+- 增加新流程（如 code-review）
-- Teach a new language from scratch (e.g., tsl-guide)
+- 从零教授新语言（如 tsl-guide）
-- Add cross-language common knowledge (e.g., style-cleanup)
+- 添加跨语言通用知识（如 style-cleanup）
 
 ---
 
 ## FAQ
 
-Q: Why is .agents/ so small?
+Q：为什么 .agents 这么小？
-A: Because it is loaded every conversation. Keeping it under 50 lines saves
+A：因为它会在每次对话加载。控制在 50 行内可减少约 71% 的持久 token 消耗。
-about 71% of persistent token usage.
 
-Q: Why does TSL need a dedicated tsl-guide skill?
+Q：为什么 TSL 需要专门的 tsl-guide？
-A: TSL is not pre-trained. The agent needs from-scratch teaching.
+A：TSL 非预训练语言，需要从零教学。
 
-Q: What if my project has custom conventions?
+Q：如果项目有自定义约定怎么办？
-A: Fork playbook into the project (git subtree) and modify the project's
+A：将 playbook 以 git subtree 方式引入项目，并修改项目的 `.agents/`。
-`.agents/`.
 
 ---
 
-## Related docs
+## 相关文档
 
-- Skills usage guide: `SKILLS.md`
+- Skills 使用指南：`SKILLS.md`
-- Development standards: `docs/index.md`
+- 开发规范：`docs/index.md`
-- Project README: `README.md`
+- 项目 README：`README.md`

README.md

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

docs/tsl/syntax_book/function/11_web_development.md

@@ -3,7 +3,7 @@
 #### 内容
 
 - TSL的Web支持
-- .Web Tools
+- Web 工具（.Web Tools）
 
 #### TSL的Web支持
 
@@ -289,7 +289,7 @@ http://www.webiste.com/foo.tsl?name=jack&email=jack@abc.com
 
 可以用上面的方式提取数据
 
-#### .Web Tools
+#### Web 工具（.Web Tools）
 
 ##### 内容
 

templates/AGENTS.template.md

@@ -1,12 +1,13 @@
-# Agent Instructions
+# 代理指引
 
 <!-- playbook:framework:start -->
 
 ## 规则优先级
 
 1. 系统/开发者指令与安全约束
-2. 仓库规则：`.agents/` 与本文件
+2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
-3. `AGENT_RULES.md` - 执行流程
+3. 仓库规则：`.agents/` 与本文件
+4. `AGENT_RULES.md` - 执行流程
 
 ---
 
@@ -24,6 +25,7 @@
 
 ### 核心规则
 
+- **项目私有规则**：[AGENT_RULES.local.md](./AGENT_RULES.local.md)
 - **执行流程**：[AGENT_RULES.md](./AGENT_RULES.md)
 - **AI 行为规范**：[docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
 
@@ -34,7 +36,6 @@
 - **架构设计**：[memory-bank/architecture.md](memory-bank/architecture.md)
 - **进度追踪**：[memory-bank/progress.md](memory-bank/progress.md)
 - **架构决策**：[memory-bank/decisions.md](memory-bank/decisions.md)
-- **实施计划**：[memory-bank/implementation-plan.md](memory-bank/implementation-plan.md)
 
 ### 工作流程
 
@@ -48,10 +49,11 @@
 
 **AI 应该做的**：
 
-1. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
+1. 读取 [AGENT_RULES.local.md](./AGENT_RULES.local.md)（如存在）
-2. 读取 [memory-bank/](memory-bank/) 核心文档
+2. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
-3. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
+3. 读取 [memory-bank/](memory-bank/) 核心文档
-4. 查看 `docs/plans/` 下最新计划（如有）或 `memory-bank/implementation-plan.md`
+4. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
+5. 查看 `docs/plans/` 下最新计划（如有）
 <!-- playbook:framework:end -->
 
 ---

templates/AGENT_RULES.template.md

@@ -5,18 +5,19 @@
 ## 优先级
 
 1. 系统/开发者指令与安全约束
-2. 仓库规则：`.agents/` 与 `AGENTS.md`
+2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
-3. 本文件
+3. 仓库规则：`.agents/` 与 `AGENTS.md`
+4. 本文件
 
 ## 上下文加载（每次会话开始）
 
 **必读文档**（按顺序）：
 
-1. `memory-bank/project-brief.md` - 项目定位、边界、约束
+1. `AGENT_RULES.local.md` - 项目私有规则（如存在，优先级高于本文件）
-2. `memory-bank/tech-stack.md` - 技术栈、工具链
+2. `memory-bank/project-brief.md` - 项目定位、边界、约束
-3. `memory-bank/architecture.md` - 架构设计、模块职责
+3. `memory-bank/tech-stack.md` - 技术栈、工具链
-4. `docs/plans/` - 最新实施计划（如存在）
+4. `memory-bank/architecture.md` - 架构设计、模块职责
-5. `memory-bank/implementation-plan.md` - 当前实施计划（如存在）
+5. `docs/plans/` - 最新实施计划（如存在）
 
 **目的**：让 AI 快速理解项目全貌，避免重复解释。
 
@@ -33,6 +34,13 @@
 
 ## 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 中所有可执行的子任务
 - 若因缺少信息/决策而阻塞：在 `memory-bank/progress.md` 记录阻塞原因

templates/README.md

@@ -14,8 +14,7 @@ templates/
 │   ├── tech-stack.template.md
 │   ├── architecture.template.md
 │   ├── progress.template.md
-│   ├── decisions.template.md
+│   └── decisions.template.md
-│   └── implementation-plan.template.md
 ├── prompts/                     # 提示词库模板
 │   ├── README.md
 │   ├── system/
@@ -82,13 +81,13 @@ scripts\sync_templates.bat -project-root C:\path\to\project -full
 project/
 ├── AGENTS.md              # 路由中心（主入口）
 ├── AGENT_RULES.md         # 执行流程
+├── AGENT_RULES.local.md   # 项目私有规则（可选，手动维护）
 ├── memory-bank/           # 项目上下文
 │   ├── project-brief.md
 │   ├── tech-stack.md
 │   ├── architecture.md
 │   ├── progress.md
-│   ├── decisions.md
+│   └── decisions.md
-│   └── implementation-plan.md
 └── docs/prompts/          # 提示词库
     ├── README.md
     ├── system/agent-behavior.md
@@ -123,7 +122,6 @@ project/
 | `architecture.template.md`        | 架构设计、模块职责   |
 | `progress.template.md`            | 开发进度追踪         |
 | `decisions.template.md`           | 架构决策记录（ADR）  |
-| `implementation-plan.template.md` | 当前实施计划         |
 
 ### prompts/
 
@@ -138,6 +136,31 @@ project/
 ### AGENT_RULES.template.md
 
 执行流程规范，定义 AI 的工作循环和约束。
+如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
+且不会被同步脚本覆盖。
+
+### 示例：不跑测试的计划提示词
+
+当你需要修改代码但暂时不运行测试时，可用以下提示词生成“可执行且不失败”的实施计划：
+
+```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`。
+```
 
 ### AGENTS.template.md
 

templates/memory-bank/implementation-plan.template.md

@@ -1,91 +0,0 @@
-# 当前实施计划
-
-## 计划状态
-
-**计划名称**: {{PLAN_NAME}}
-**开始时间**: {{START_DATE}}
-**当前状态**: 进行中 / 已完成 / 已暂停
-
----
-
-## 目标
-
-{{PLAN_GOAL}}
-
-**成功标准**:
-
-- [ ] {{SUCCESS_CRITERIA_1}}
-- [ ] {{SUCCESS_CRITERIA_2}}
-- [ ] {{SUCCESS_CRITERIA_3}}
-
----
-
-## 实施步骤
-
-### 阶段 1: {{PHASE_1_NAME}}
-
-#### 步骤 1.1: {{STEP_1_1}}
-
-- [ ] {{TASK_1_1_1}}
-- [ ] {{TASK_1_1_2}}
-
-**验证**: {{VERIFICATION_1_1}}
-
-#### 步骤 1.2: {{STEP_1_2}}
-
-- [ ] {{TASK_1_2_1}}
-- [ ] {{TASK_1_2_2}}
-
-**验证**: {{VERIFICATION_1_2}}
-
----
-
-### 阶段 2: {{PHASE_2_NAME}}
-
-#### 步骤 2.1: {{STEP_2_1}}
-
-- [ ] {{TASK_2_1_1}}
-- [ ] {{TASK_2_1_2}}
-
-**验证**: {{VERIFICATION_2_1}}
-
----
-
-## 当前进度
-
-### 已完成
-
-- {{COMPLETED_PHASE}}
-
-### 进行中
-
-- {{IN_PROGRESS_STEP}}
-
-### 待开始
-
-- {{PENDING_STEP}}
-
----
-
-## 风险与问题
-
-### 风险
-
-1. **{{RISK_1}}**
-   - 风险：{{RISK_1_DESC}}
-   - 缓解：{{RISK_1_MITIGATION}}
-
-### 已解决的问题
-
-1. {{RESOLVED_ISSUE_1}}
-
----
-
-## 下一步行动
-
-- [ ] {{NEXT_ACTION_1}}
-- [ ] {{NEXT_ACTION_2}}
-
----
-
-**最后更新**：{{DATE}}

tests/templates/validate_project_templates.sh

@@ -79,7 +79,7 @@ echo ""
 echo "🔍 验证 memory-bank 模板"
 
 MEMORY_BANK_DIR="$TEMPLATES_DIR/memory-bank"
-for name in project-brief tech-stack architecture progress decisions implementation-plan; do
+for name in project-brief tech-stack architecture progress decisions; do
     validate_file_exists "$MEMORY_BANK_DIR/$name.template.md" "memory-bank/$name.template.md"
 done