@zhuan-ai/zhuanspec 2.2.4 → 2.4.8

package/dist/core/templates/agents-template.js

@@ -2,17 +2,119 @@ export const agentsTemplate = `# ZhuanSpec 使用说明
 
 面向使用 ZhuanSpec 进行规范驱动开发的 AI 编程助手的说明文档。
 
+---
+
+## ⚡ 三条铁律（不可违反）
+
+> 三条铁律是 ZhuanSpec 工作流的核心约束，任何情况下都必须遵守。
+
+| 铁律 | 含义 | 违反后果 |
+|------|------|---------|
+| **No Spec, No Code** | 没有文档不准写代码 | Propose 阶段产出 spec 才能进入 Apply |
+| **Spec is Truth** | 文档与代码冲突时，错的一定是代码 | 归档时强制校验 Spec-Code 一致性 |
+| **Reverse Sync** | 发现偏差先修 Spec，再修代码 | Apply 阶段每完成一个 Task 做偏差检测 |
+
+### 铁律执行机制
+
+**铁律一执行**：
+- Propose 阶段创建提案后，必须等待用户明确批准（回复"Plan Approved"或选择"批准，进入实施阶段"）才能进入 Apply
+- 自动验证通过后，使用选项式交互（AskUserQuestion）弹出确认对话框
+- 未批准前，PreToolUse Hook 阻断所有代码修改操作
+
+**铁律二执行**：
+- Archive 阶段前，必须验证归档内容与代码实现一致
+- 如不一致，必须先更新归档内容，再完成归档
+- PreArchive Hook 检查 Spec-Code 一致性
+
+**铁律三执行**：
+- Apply 阶段每次 Write/Edit 操作前，PreToolUse Hook 检测偏离
+- **偏离检测触发机制**：
+  - 提案范围外文件修改时自动触发
+  - 用户输入纠正关键词（"不对"、"错了"、"这里应该是"等）时自动触发
+  - 通过读取 \`progress.json\` 的 \`phase\` 字段判断当前阶段
+- 如果修改文件不在提案范围内，触发偏离处理流程：
+  1. 弹出选项式交互：更新提案后继续 / Bug修复豁免 / 取消修改
+  2. 用户选择"更新提案后继续" → AI 进入 Propose 模式 → 自动更新 proposal.md 和 tasks.md → \`zhuanspec validate --auto-fix\` → 返回 Apply 执行原修改
+  3. 用户选择"Bug修复豁免" → 标记为 Bug 修复 → 允许修改，跳过提案流程
+  4. 用户选择"取消" → 不执行修改 → 继续原任务
+- **偏离修正流程**（用户纠正时）：
+  1. 先修改 spec 文件，实时同步用户确认
+  2. 用户确认后修改代码，完成后验证
+  3. 用户确认无误后触发知识沉淀
+
+### AI 自由度控制矩阵
+
+| 阶段 | 自由度 | 允许行为 | 禁止行为 |
+|------|--------|---------|---------|
+| **Propose** | 高 | 探索代码、设计方案、提问澄清 | 编写任何代码 |
+| **Apply** | 零 | 严格按 tasks.md 施工 | 超出提案范围修改、自行添加任务 |
+| **Review** | 中 | 验证实现、生成测试、审查代码 | 修改功能代码 |
+| **Archive** | 低 | 合并规范、生成摘要 | 修改已归档内容 |
+
+---
+
+## 知识库检查
+
+**在任何阶段开始前，必须先检查知识库：**
+
+| 操作 | 命令 | 目的 |
+|------|------|------|
+| 搜索陷阱 | \`rg "[关键词]" zhuanspec/knowledge/troubleshooting/\` | 避免重复踩坑 |
+| 搜索最佳实践 | \`rg "[关键词]" zhuanspec/knowledge/best-practices/\` | 学习成功经验 |
+| 搜索隐式约定 | \`rg "[关键词]" zhuanspec/knowledge/implicit-conventions/\` | 理解团队约定 |
+| 阅读知识索引 | \`cat zhuanspec/knowledge/index.md\` | 了解项目级知识摘要 |
+
+**知识库作用**：
+- 减少重复踩坑，积累项目经验
+- 提供团队隐式约定的书面记录
+- 加速新成员融入和知识传承
+
+---
+
 ## 快速检查清单
 
 - 搜索现有工作：\`zhuanspec spec list --long\`、\`zhuanspec list\`（仅使用 \`rg\` 进行全文搜索）
+- **检查知识库**：\`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践
 - 确定范围：新功能 vs 修改现有功能
 - 选择唯一的 \`change-id\`：kebab-case 格式，动词开头（\`add-\`、\`update-\`、\`remove-\`、\`refactor-\`）
-- 搭建结构：\`proposal.md\`、\`tasks.md\`、\`design.md\`（仅在需要时），以及每个受影响功能的规范增量
+- 搭建结构：\`proposal.md\`、\`tasks.md\`、\`design.md\`，以及每个受影响功能的规范增量
 - 编写增量：使用 \`## ADDED|MODIFIED|REMOVED|RENAMED Requirements\`；每个要求至少包含一个 \`#### Scenario:\`
 - 验证：运行 \`zhuanspec validate [change-id] --strict\` 并修复问题
 - 请求批准：在提案获得批准之前不要开始实施
 
-## 三阶段工作流
+## 进度汇报约定
+
+Apply 阶段执行每个任务时，必须按以下格式输出进度：
+
+**任务开始时**：
+\`\`\`
+━━━ 🚀 开始任务 [X.Y/N] ━━━━━━━━━━━━━━━━
+任务: [任务描述]
+Wave: W/N | Phase: Apply
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+**任务完成后**：
+\`\`\`
+━━━ ✅ 任务完成 [X.Y/N] ━━━━━━━━━━━━━━━━
+已修改: [文件列表]
+下一个: [下一任务ID]
+整体进度: ████████░░░░ XX.X%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+**进度条格式**：
+- 使用 12 个 block 字符（█ 和 ░）
+- 进度百分比 = (已完成任务数 / 总任务数) × 100
+- 保留 1 位小数
+
+**示例**：
+- 3/8 完成 → \`███████░░░░░░░ 37.5%\`
+- 6/8 完成 → \`████████████░░ 75.0%\`
+
+---
+
+## 四阶段工作流
 
 ### 阶段 1：创建变更
 在以下情况下创建提案：
@@ -41,55 +143,229 @@ export const agentsTemplate = `# ZhuanSpec 使用说明
 - 现有行为的测试
 
 **工作流**
-0. 审查 \`zhuanspec/project.md\`、\`zhuanspec list\` 和 \`zhuanspec list --specs\` 以了解当前上下文。
-1. **强制澄清检查（必须首先执行）**：分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、实现细节、数据获取来源、服务分层、依赖关系、优先级、验收标准等......）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测或创建提案，严禁要求用户手动输入大段文字。
-
-   ⚠️ **检查点 [强制澄清]**：
-   必须在 tasks.md 中记录澄清结果，添加 "## 澄清日志" 章节：
-   - 如果进行了提问：记录每个问题及用户的回答
-   - 如果无需澄清：写明"状态：已完成 - 无需澄清"并简要说明理由
-   - 此章节不能为空或仅包含 HTML 注释
-   - 未完成此检查点前禁止继续编写提案
-
-2. 选择一个唯一的动词开头的 \`change-id\`，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\`、可选的 \`design.md\` 和规范增量。
-3. 使用 \`## ADDED|MODIFIED|REMOVED Requirements\` 起草规范增量，每个要求至少包含一个 \`#### Scenario:\`。
-4. 运行 \`zhuanspec validate <id> --strict\` 并在分享提案之前解决所有问题。
+0. **检查知识库、加载项目知识并审查项目**：
+   - 运行 \`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践，避免重复踩坑
+   - 阅读 \`zhuanspec/knowledge/index.md\` 了解项目级知识摘要
+   - **加载项目知识**：调用 \`@skill:load-project-knowledge\` 进行渐进式加载：
+     * 输入：domain（当前项目）、keywords（从需求描述提取）
+     * 获取：matched_services（涉及的服务列表）、search_priority（检索优先路径）、architecture_constraints（架构约束）
+     * 使用：后续代码定位使用 search_priority 限定范围，方案设计检查 architecture_constraints
+     * 兼容策略：若未找到 project.md 或关键词无匹配，输出警告并使用全局检索
+   - 阅读 \`zhuanspec/project.md\` 了解项目约定（提示："✓ Loaded project.md"）
+   - 审查 \`zhuanspec/project.md\`，\`zhuanspec list\` 和 \`zhuanspec list --specs\` 以了解当前上下文。
+1. **强制询问测试用例（TDD 模式检查点，必须首先执行）**：
+   - 使用选项式交互询问："请提供相关的测试用例（可选），可以是：本地目录路径、在线链接（将通过 zzcase-data-fetcher skill 获取）、或跳过此步骤继续常规流程"
+   - 用户选择"提供测试用例"：进入 TDD 驱动模式
+     * 明确告知：测试用例将用于需求定义、单元测试生成、实施验证
+     * 在 proposal.md 创建 "Test Case Coverage" 部分
+     * 在 tasks.md 使用 \`@test-case:TC-XXX\` 标签关联任务
+     * 创建 test-cases.md 记录测试用例详情
+   - 用户选择"跳过"：继续常规流程（即提案无需考虑测试case）
+
+   ⚠️ **CHECKPOINT [TDD-MODE]**:
+   - TDD 模式下，Apply 阶段每个任务完成后需验证对应测试用例通过
+   - Review 阶段包含测试覆盖率检查
+   - 测试用例在 TDD 模式下发挥关键验证作用，确保代码符合预期行为
+
+2. **强制澄清检查（必须执行，不可跳过）**：分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、实现细节、数据获取来源、服务分层、依赖关系、优先级、验收标准等......）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测或创建提案，严禁要求用户手动输入大段文字。
+
+   ⚠️ **CHECKPOINT [PRE-CLARIFICATION]**:
+   You MUST record the pre-clarification result in tasks.md under "## Pre-Clarification Log":
+   - If questions were asked: Record each question and the user's answer
+   - If no clarification needed: Write "Status: COMPLETED - No clarification needed" with brief justification
+   - This section MUST NOT be empty or contain only HTML comments
+   - NEVER proceed to proposal writing without completing this checkpoint
+
+3. 选择一个唯一的动词开头的 \`change-id\`，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\`、\`design.md\` 和规范增量。
+4. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
+5. 当解决方案跨越多个系统、引入新模式或在提交规范之前需要权衡讨论时，在 \`design.md\` 中捕获架构推理。
+6. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
+7. **发现可用 Skill 并创建 tasks.md**：
+   - 运行 \`zhuanspec skills list --json\` 获取当前环境中可用的 skill 列表及其 description
+   - 在 \`proposal.md\` 的 **Skill Mapping** 段中基于 skill description 进行语义匹配：
+     - 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
+     - 只有当实现区域的实际功能与 skill description 明确匹配时才关联
+     - 简单的代码修改（如枚举值增删）应匹配通用编码规范 skill，而非架构级 skill
+     - 避免仅因模块名称或文件路径中的关键词而错误匹配
+     - 在表格中说明匹配理由
+   - 将 \`tasks.md\` 起草为有序的小型、可验证工作项列表
+   - 使用 \`@skill:<real-skill-name>\` 标注与 skill 匹配的任务（支持多个：\`@skill:name1,name2\`）
+   - 仅当 skill 明确匹配任务时才标注，没有匹配的 skill 可省略标签
+
+   ⚠️ **CHECKPOINT [SKILL-TAGGING]**:
+   1. You MUST run \`zhuanspec skills list\` first and record discovered skills in the Skill Mapping table
+   2. Every task MUST have either @skill:real-skill-name or @skill:none
+   3. If @skill:none, you MUST provide a justification (e.g., "pure config change, no skill applies")
+   4. @skill names MUST match exactly the names returned by \`zhuanspec skills list\` — do NOT invent skill names
+   5. The Skill Mapping table in tasks.md MUST NOT be empty
+   6. validate --strict will verify all @skill names exist in the known skill list
+
+   ⚠️ **CHECKPOINT [TASK-ORDERING]**:
+   1. Tasks in tasks.md MUST be organized under Wave headers (### Wave 1, ### Wave 2, etc.)
+   2. Wave assignment must be computed from @depends relationships (Wave 1 = no deps, Wave N = depends on Wave N-1)
+   3. No task may appear before a task it depends on
+   4. You MUST add a "## Dependency Analysis" section at the end with "Status: COMPLETED"
+   5. validate --strict will verify task ordering matches computed waves
+
+8. **测试 case 处理（仅 TDD 模式）**：
+
+   **⚠️ 模式判断**：根据以下条件判断当前是哪种模式：
+   - **有 case 模式**：用户提供测试 case 来源（taskId/bicId）、用户要求 TDD 工作流、或明确要求设计测试 case
+   - **无 case 模式**：普通 spec-driven 工作流，用户未提供测试 case 相关信息
+
+   **【有 case 模式】**（必须执行以下步骤）：
+   - 获取测试 case 来源：
+     * 通过 taskId/bicId 获取测试 case（使用 MCP 工具 \`zzcase_get_api_report_queryBaseCase\`）
+     * 手动录入测试 case
+   - **【强制】创建 test-cases.md 文件**：
+     * 使用 \`getTestCasesTemplate\` 模板（从 \`src/core/templates/index.ts\` 导出）
+     * 文件路径：\`changes/<change-id>/test-cases.md\`
+     * 填写获取时间、来源（taskId/bicId/manual）、测试 case 详情
+     * 每个 TC-XXX 必须包含：前置条件、测试步骤、预期结果、验收点
+   - 在 \`tasks.md\` 增加 **Test Case Coverage** 表格（四列格式）：
+     | Task | 测试 Case ID | 测试 Case 文件路径 | 覆盖场景 |
+     |------|-------------|-------------------|----------|
+     * "测试 Case 文件路径" 列填写 BIC 路径层级格式
+   - 使用 \`@test-case:TC-XXX\` 关联任务与测试 case
+
+   ⚠️ **CHECKPOINT [TEST-CASE-COVERAGE]**（仅适用于有 case 模式）:
+   1. 每个 Requirement 应至少对应一个测试 case
+   2. 测试 case 应覆盖正向和异常场景
+   3. **必须创建 test-cases.md 文件**（使用 \`getTestCasesTemplate\` 模板）
+   4. Test Case Coverage 表格必须包含四列：Task、测试 Case ID、测试 Case 文件路径、覆盖场景
+   5. validate --strict 会验证测试 case 覆盖率（**阻塞级别**）
+
+   **【无 case 模式】**（跳过测试 case 相关步骤）：
+   - 不创建 test-cases.md
+   - tasks.md 不需要 Test Case Coverage 段
+   - validate --strict 的 test-case-coverage 规则自动跳过（SKIPPED）
+   - 单测统一在 Review 阶段处理
+
+9. 【自动验证与修复】：
+   运行 \`zhuanspec validate <id> --strict --auto-fix\` 进行验证：
+   - 如果验证通过（PASS）：继续下一步
+   - 如果验证失败（FAIL）：自动触发修复循环：
+     * CLI 自动分析错误原因
+     * CLI 自动生成修复方案并执行
+     * 重新验证（最多 3 次循环）
+     * 循环结束后仍未通过：输出错误报告，等待人工干预
+   - 验证通过后，输出提案摘要
+
+10. 【输出提案摘要】：
+   • 变更原因、内容、影响范围
+   • 关键 Requirements
+   • 任务数量和 Wave 分布
+
+11. 【选项式交互确认】：
+   使用 AskQuestion 工具弹出确认对话框：
+   \`\`\`
+   问题: "请确认是否批准此提案？"
+   选项：
+     A) 批准，进入实施阶段
+     B) 需要修改提案内容
+     C) 暂不批准，稍后处理
+     D) 其他（请在后续补充说明）
+   \`\`\`
+
+   用户选择处理：
+   • 选择"批准"：创建 \`.approved\` 文件，进入 Apply 阶段
+   • 选择"修改"：返回步骤 4 修改提案内容
+   • 选择"暂不"：保持提案状态，等待后续处理
+   • 选择"其他"：等待用户补充说明后继续
+
+   ⚠️ **CHECKPOINT [PLAN-APPROVED]**:
+   - 用户必须明确选择"批准"选项才能进入 Apply 阶段
+   - 未批准前禁止任何代码修改操作
+   - PreToolUse Hook 会阻断未批准状态的 Write/Edit 操作
 
 ### 阶段 2：实施变更
 
+**前置检查**：
+- ⚠️ **CHECKPOINT [PLAN-APPROVED]**: \`.approved\` 文件必须存在。未批准的提案禁止实施。
+  - PreToolUse Hook 会阻断未批准状态的 Write/Edit 操作
+  - 如果 \`.approved\` 不存在，提示用户先完成 Proposal 阶段的批准流程
+
 将这些步骤作为待办事项跟踪，逐一完成。
 
-1. **阅读 proposal.md** - 了解要构建的内容
-2. **阅读 design.md**（如果存在） - 审查技术决策
-3. **阅读 tasks.md** - 获取实施清单
-4. **判断执行模式** - 根据 tasks.md 内容选择执行策略：
-   - **如果 tasks.md 包含 \`@depends\` 依赖声明**（存在 \`<execution_plan>\`）：
-     → 按【任务执行编排】规则执行（见下方"任务执行编排"章节）
+0. **检查知识库、加载项目知识并阅读 proposal.md**：
+   - 运行 \`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关最佳实践和陷阱
+   - **加载项目知识**：调用 \`@skill:load-project-knowledge\` 进行渐进式加载：
+     * 输入：domain（当前项目）、keywords（从 tasks.md 提取）
+     * 获取：matched_services、search_priority、architecture_constraints
+     * 使用：代码定位使用 search_priority 限定范围，避免全局检索偏差
+   - 阅读 \`zhuanspec/project.md\` 了解项目约定（提示："✓ Loaded project.md"）
+   - 阅读 proposal.md - 了解要构建的内容
+1. **阅读 design.md**（如果存在） - 审查技术决策
+2. **阅读 tasks.md** - 获取实施清单
+3. **判断执行模式** - 根据 tasks.md 内容选择执行策略：
+   - **如果 tasks.md 包含 \`@depends\` 依赖声明**：
+     → 按 Wave 并行执行（使用 superpowers:subagent-driven-development skill）
    - **如果 tasks.md 无依赖声明**：
-     → 按顺序执行（见下方步骤 5-7）
-5. **按顺序实施任务**（无依赖声明时）- 按顺序完成。如果任务标注了 \`@skill:<skill-name>\`，直接调用对应 skill
-6. **确认完成** - 在更新状态之前确保 \`tasks.md\` 中的每个项目都已完成
-7. **更新清单** - 所有工作完成后，将每个任务设置为 \`- [x]\`，以便列表反映实际情况
-8. **代码审查**（可选） - 基于生成的上下文文件审查已实施的代码，检查：
-   - 代码规范和约定合规性
-   - 逻辑正确性
-   - 性能问题和潜在瓶颈
-   - 安全性问题
-   - 最佳实践遵循情况
-   - 对于 Java 代码：特别关注 Java 特定的模式、约定和潜在问题
-   - 此步骤是可选的，如果跳过不会阻塞工作流
-   - 如果发现问题，应在归档之前解决
-9. **批准门槛** - 在提案经过审查和批准之前不要开始实施
-
-### 阶段 3：归档变更
-部署后，创建单独的 PR：
-- 将 \`changes/[name]/\` → \`changes/archive/YYYY-MM-DD-[name]/\`
-- 如果功能已更改，更新 \`specs/\`
-- 对于仅工具类的变更，使用 \`zhuanspec archive <change-id> --skip-specs --yes\`（始终显式传递变更 ID）
-- 运行 \`zhuanspec validate --strict\` 以确认归档的变更通过检查
+     → 按顺序执行
+4. **按顺序实施任务**（无依赖声明时）- 保持编辑最小化。如果任务标注了 \`@skill:<skill-name>\`，直接调用对应 skill
+   - **阶段职责要求**：Apply 阶段不生成单测文件；单测统一在 Review 阶段生成与验证。
+5. **确认完成** - 在更新状态之前确保 \`tasks.md\` 中的每个项目都已完成
+6. **更新清单** - 所有工作完成后，将每个任务设置为 \`- [x]\`
+
+
+### 阶段 3：Review
+
+**检查知识库、project.md 并执行审查**：
+- 运行 \`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关审查最佳实践
+- 阅读 \`zhuanspec/project.md\` 了解项目约定（提示："✓ Loaded project.md"）
+
+执行 \`zhuanspec review <change-id>\`，启动三轨并行审查：
+
+**三轨并行机制**：
+- 使用 Agent 工具启动 3 个 subagent 并行执行
+- **Code Review subagent**：调用 \`code-review-expert\` skill
+- **Unit Test subagent**：调用 \`generate-mockito-unit-test-skill\` skill
+- **Spec-Code Consistency subagent**：执行一致性检查
+
+**Subagent 自闭环**：
+- 每个 subagent 内部独立修复循环（最多3轮）
+- 发现问题时立即修复，然后重新检查
+- 输出独立报告文件：
+  - \`code-review-result.json\`
+  - \`unit-test-result.json\`
+  - \`spec-consistency-result.json\`
+- 汇总生成 \`review-report.md\`
+
+**验收标准**：
+- review passed
+- critical = 0
+- 单测通过
+- 三轨全部 PASS
+
+### 阶段 4：归档变更
+
+**前置检查**：
+- ⚠️ **CHECKPOINT [REVIEW-PASSED]**: Review 阶段必须通过（三轨全部 PASS）
+  - \`review-report.md\` 存在且显示 passed
+  - \`code-review-result.json\`: critical = 0
+  - \`unit-test-result.json\`: tests passed
+  - \`spec-consistency-result.json\`: passed
+
+**步骤**：
+0. **检查知识库**：运行 \`rg "[关键词]" zhuanspec/knowledge/\` 搜索是否有需要沉淀的知识
+1. **确定变更 ID**：运行 \`zhuanspec list\` 确认要归档的变更
+2. **验证 Review 门禁**：确认上述四个结果文件存在且全部通过
+3. **运行归档命令**：执行 \`zhuanspec archive <id> --yes\`（仅工具类工作使用 \`--skip-specs\`）
+4. **验证归档结果**：运行 \`zhuanspec validate --strict\` 确认通过
+5. **知识沉淀（手动补充）**：调用 \`@skill:zhuanspec:knowledge\` 从会话记忆补充知识
+   - CLI 已自动从变更目录提取结构化知识
+   - AI 需从会话补充隐式约定、调试发现等
+6. **会话分析**：调用 \`@skill:session-analytics\` 分析会话指标数据
+7. **输出反馈链接**：告知用户填写使用反馈：
+   📋 https://doc.weixin.qq.com/forms/AJ4AfQfgAAwACwAAwaVABsCNqDXIKn8sf
 
 ## 执行任何任务之前
 
+**知识库检查：**
+- [ ] 搜索相关陷阱：\`rg "[关键词]" zhuanspec/knowledge/troubleshooting/\`
+- [ ] 搜索最佳实践：\`rg "[关键词]" zhuanspec/knowledge/best-practices/\`
+- [ ] 阅读知识索引：\`cat zhuanspec/knowledge/index.md\`
+
 **上下文检查清单：**
 - [ ] 在 \`specs/[capability]/spec.md\` 中阅读相关规范
 - [ ] 检查 \`changes/\` 中的待处理变更是否存在冲突
@@ -98,6 +374,7 @@ export const agentsTemplate = `# ZhuanSpec 使用说明
 - [ ] 运行 \`zhuanspec list --specs\` 查看现有功能
 
 **创建规范之前：**
+- **检查知识库**：\`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践
 - 始终检查功能是否已存在
 - 优先修改现有规范而不是创建重复项
 - 使用 \`zhuanspec show [spec]\` 审查当前状态
@@ -105,231 +382,120 @@ export const agentsTemplate = `# ZhuanSpec 使用说明
 
 ## 强制澄清工作流
 
-在创建任何提案文件之前，必须执行强制澄清检查。这是不可跳过的步骤。
+> **核心原则**：遇到任何模糊点，必须澄清。严禁猜测、臆测、自行假设。
 
-**重要原则：先查阅后询问，避免过度询问**
+### 澄清闭环机制
 
-在询问之前，必须先查阅以下来源，只有在确实无法从这些来源确定时才询问：
-- 现有规范（\`zhuanspec/specs/\`）
-- 项目约定（\`zhuanspec/project.md\`）
-- 代码库结构和现有模式
-- 上下文文件和相关变更
+在创建任何提案文件之前，必须执行以下流程：
 
-### 何时需要澄清
-
-在以下情况下，**且无法从现有规范、项目约定、代码库结构中确定时**，必须停止并提问（包括但不限于）：
-- **范围不明确**：用户请求的范围边界不清楚（例如："改进性能"、"优化代码"）
-- **技术选择不明确**：有多种实现方式，但用户未指定偏好，且无法从现有代码模式中确定（例如：使用哪种数据库、哪种框架）
-- **优先级不明确**：多个需求但未说明优先级或顺序
-- **验收标准不明确**：不清楚如何判断完成或成功
-- **实现细节不明确**：不清楚如何实现或实现细节不明确，且无法从代码库分析中确定（例如：如何获取数据、如何处理错误、如何优化性能）
-- **代码改动位置不明确**：不清楚需要修改哪些文件、在哪些位置进行修改，且无法从代码库结构分析中确定
-- **代码分层架构不明确**：如果涉及服务分层（如 4 层架构、3 层架构等），不清楚各层的职责和改动位置，且无法从现有代码结构或规范中确定
-- **数据获取来源不明确**：不清楚从哪里获取数据，且无法从现有代码或规范中确定（例如：从数据库、API、文件、外部服务、历史逻辑复用）
-- **服务分层不明确**：不清楚服务分层，且无法从现有代码结构或规范中确定（例如：前端、后端、数据库、API、服务、4层架构、3层架构、2层架构、领域模型）
-- **依赖关系不明确**：不清楚依赖关系，且无法从代码库分析中确定（例如：依赖哪些服务、依赖哪些库、依赖哪些组件）
-- **上下文信息缺失**：缺少必要的背景信息来理解需求，且无法从现有规范或代码中获取
-- **歧义性表述**：用户请求可以用多种方式理解，且无法从上下文确定
-- **其他不明确**：其他不明确的情况，且无法从现有来源确定
+\`\`\`
+┌─────────────────────────────────────────────────────────────┐
+│  1. 查阅现有来源                                             │
+│     → 规范、项目约定、代码库、上下文文件                      │
+│     → 尝试从这些来源确定信息                                  │
+├─────────────────────────────────────────────────────────────┤
+│  2. 识别模糊点                                               │
+│     → 分析用户请求，列出不确定的方面                          │
+│     → 排除可以从现有来源确定的方面                            │
+├─────────────────────────────────────────────────────────────┤
+│  3. 判断提问策略                                             │
+│     → 如果仍有模糊点：必须提问                                │
+│     → 如果全部明确：继续创建                                  │
+├─────────────────────────────────────────────────────────────┤
+│  4. 生成澄清问题                                             │
+│     → 优先检查 superpowers:brainstorming 是否可用            │
+│     → 可用：调用该技能生成高质量问题                          │
+│     → 不可用：直接使用 AskUserQuestion                       │
+├─────────────────────────────────────────────────────────────┤
+│  5. 选项式交互                                               │
+│     → 2-5 个预设选项 + "其他"兜底                             │
+│     → 等待用户选择                                            │
+├─────────────────────────────────────────────────────────────┤
+│  6. 处理"其他"选项                                           │
+│     → 用户选择"其他"后针对性追问                              │
+│     → 仍优先使用选项式                                       │
+├─────────────────────────────────────────────────────────────┤
+│  7. 开始创建                                                 │
+│     → 只有在所有模糊点都明确后才能创建提案                    │
+└─────────────────────────────────────────────────────────────┘
+\`\`\`
 
-### 何时不需要澄清
+### 提问策略选择
 
-在以下情况下，**不应询问**，应直接使用从现有来源获取的信息：
-- **信息已明确**：用户请求中已经明确说明了相关信息
-- **可从规范获取**：信息可以从现有规范（\`zhuanspec/specs/\`）中获取
-- **可从项目约定获取**：信息可以从项目约定（\`zhuanspec/project.md\`）中获取
-- **可从代码库分析获取**：信息可以通过分析代码库结构、现有模式、相关文件获取
-- **可从上下文获取**：信息可以从上下文文件、相关变更、历史记录中获取
-- **符合常见模式**：实现方式符合项目中的常见模式或最佳实践，无需特别询问
+| 技能可用性 | 提问方式 | 说明 |
+|-----------|---------|------|
+| superpowers:brainstorming 可用 | 调用技能生成问题 | 高质量、结构化的澄清问题 |
+| superpowers:brainstorming 不可用 | AskUserQuestion 直接提问 | 选项式交互，简洁高效 |
 
-**原则**：如果可以通过查阅现有来源确定信息，就不要询问用户，以提高效率。
+### Brainstorming 调用边界
 
-### 澄清问题格式
+**适用场景**：
+| 场景类型 | 调用方式 | 说明 |
+|----------|---------|------|
+| **复杂模糊** | superpowers:brainstorming | 跨模块、新架构、多方案选择 |
+| **简单澄清** | AskUserQuestion 直接提问 | 参数调整、范围边界、单一选择 |
+| **已完整需求** | 跳过澄清 | 用户提供完整需求文档 |
 
-**必须使用选项式交互，严禁要求用户手动输入文字回答。**
+**调用约束**：
+- 仅使用 brainstorming 的**澄清提问能力**（步骤3：逐一提问澄清）
+- **不进入完整设计流程**（步骤4-9：方案对比、设计文档）
+- **不触发 writing-plans skill**（属于 Apply 阶段）
+- 获得澄清后立即返回 ZhuanSpec 提案流程
 
-使用编辑器提供的结构化问答工具（如 Cursor 的 \`AskQuestion\` 工具、Claude Code 的交互式选择等）向用户提问，将每个澄清问题转化为带预设选项的选择题：
+### 选项式交互格式
 
-**格式要求：**
+**必须遵守**：
 - 每个问题提供 2-5 个预设选项
-- 每个问题末尾包含一个"其他"选项，以覆盖未列出的情况
-- 允许用户多选（当问题可能有多个答案时设置 \`allow_multiple: true\`）
-- 选项文本要简洁明了，必要时附带简短说明
-- 如果有多个独立的澄清问题，合并到同一次问答交互中（一次性展示多个问题）
-
-**标准格式模板：**
+- 末尾包含"其他"选项作为兜底
+- 禁止要求用户手动输入大段文字
 
-\`\`\`
-使用 AskQuestion 工具提问，结构如下：
-
-问题 1: "关于 [不确定的方面]：[具体问题]"
-选项：
-  A) [选项1 - 简短说明]
-  B) [选项2 - 简短说明]
-  C) [选项3 - 简短说明]
-  D) 其他（请在后续补充说明）
-
-问题 2: "关于 [另一个方面]：[具体问题]"
-选项：
-  A) [选项1]
-  B) [选项2]
-  C) 其他
-\`\`\`
-
-**工具调用示例（Cursor AskQuestion）：**
+**示例**：
 \`\`\`json
 {
   "questions": [
     {
       "id": "scope",
-      "prompt": "关于改进范围：您希望改进哪些方面？",
+      "prompt": "您希望改进哪些方面？",
       "options": [
-        {"id": "security", "label": "安全性（如双因素认证）"},
-        {"id": "ux", "label": "用户体验（如简化流程）"},
-        {"id": "performance", "label": "性能（如响应时间优化）"},
+        {"id": "security", "label": "安全性"},
+        {"id": "ux", "label": "用户体验"},
+        {"id": "performance", "label": "性能"},
         {"id": "other", "label": "其他"}
       ],
       "allow_multiple": true
-    },
-    {
-      "id": "priority",
-      "prompt": "如果有多个改进点，优先级如何？",
-      "options": [
-        {"id": "security_first", "label": "安全性优先"},
-        {"id": "ux_first", "label": "用户体验优先"},
-        {"id": "all_equal", "label": "同等重要，一起做"}
-      ]
     }
   ]
 }
 \`\`\`
 
-**原则：**
-- 永远不要让用户从零开始输入答案，总是提供可选的选项
-- 选项应覆盖最常见的答案场景
-- "其他"选项作为兜底，确保不遗漏特殊情况
-- 用户选择"其他"后，再针对性地追问细节
-
-### 禁止行为
-
-在遇到模糊需求时，**严禁**以下行为：
-- ❌ 自行推测用户意图
-- ❌ 基于"最佳猜测"创建提案
-- ❌ 假设用户想要什么
-- ❌ 跳过澄清直接创建文件
-- ❌ 使用模糊的表述来掩盖不确定性
-- ❌ 要求用户手动输入大段文字来回答澄清问题（必须使用选项式交互）
+### 常见模糊点清单
 
-### 澄清流程
+| 类别 | 需澄清的情况 |
+|------|-------------|
+| **范围** | 边界不明确（"改进性能"、"优化代码"） |
+| **技术** | 多种实现方式但未指定偏好 |
+| **优先级** | 多个需求但未说明顺序 |
+| **验收** | 不清楚如何判断完成 |
+| **实现** | 数据获取来源、服务分层、依赖关系不明确 |
+| **位置** | 代码改动位置不明确 |
 
-1. **查阅现有来源**：首先查阅现有规范、项目约定、代码库结构、上下文文件等，尝试从这些来源获取所需信息
-2. **识别模糊点**：仔细分析用户请求，列出所有不确定的方面，**但排除那些可以从现有来源确定的方面**
-3. **判断是否需要询问**：对于每个不确定的方面，判断是否可以从现有来源确定：
-   - 如果可以确定，则使用从现有来源获取的信息，不询问
-   - 如果无法确定，则标记为需要询问
-4. **构造选项式问题**：将所有需要询问的模糊点转化为带预设选项的选择题，尽量合并到一次交互中
-5. **使用工具提问**：调用编辑器的结构化问答工具（如 \`AskQuestion\`）一次性展示所有问题和选项，等待用户选择
-6. **等待用户选择**：必须等待用户选择答案，不能继续
-7. **处理"其他"选项**：如果用户选择了"其他"，再针对该问题追问具体细节（仍优先使用选项式，如确实无法预设则允许简短文字输入）
-8. **确认理解**：在开始创建文件前，简要总结理解以确保准确
-9. **开始创建**：只有在所有必要的模糊点都明确后，才能开始创建提案文件
+### 禁止行为
 
-### 示例
+| ❌ 禁止 | 原因 |
+|--------|------|
+| 自行推测用户意图 | 违反三条铁律 |
+| 跳过澄清直接创建文件 | 违反 No Spec, No Code |
+| 要求用户手动输入大段文字 | 效率低、体验差 |
 
-**用户请求**："改进登录功能"
+---
 
-**分析过程**：
-1. 首先查阅现有规范（\`zhuanspec/specs/\`）中是否有登录相关的规范
-2. 查阅项目约定（\`zhuanspec/project.md\`）了解项目架构和约定
-3. 分析代码库结构，了解现有的登录实现方式
-4. 如果从这些来源无法确定改进范围，则使用选项式交互询问
+### 与三条铁律的关系
 
-**必须使用选项式交互提问**（仅在无法从现有来源确定时）：
-
-\`\`\`json
-{
-  "questions": [
-    {
-      "id": "improvement_scope",
-      "prompt": "您希望改进登录功能的哪些方面？",
-      "options": [
-        {"id": "security", "label": "安全性（如添加双因素认证）"},
-        {"id": "ux", "label": "用户体验（如简化登录流程）"},
-        {"id": "performance", "label": "性能（如优化登录响应时间）"},
-        {"id": "other", "label": "其他"}
-      ],
-      "allow_multiple": true
-    },
-    {
-      "id": "tech_preference",
-      "prompt": "您有特定的技术偏好吗？",
-      "options": [
-        {"id": "jwt", "label": "JWT Token 认证"},
-        {"id": "session", "label": "Session 认证"},
-        {"id": "oauth", "label": "OAuth 第三方集成"},
-        {"id": "no_preference", "label": "无偏好，由你推荐"},
-        {"id": "other", "label": "其他"}
-      ]
-    },
-    {
-      "id": "priority",
-      "prompt": "如果有多个改进点，优先级如何？",
-      "options": [
-        {"id": "security_first", "label": "安全性优先"},
-        {"id": "ux_first", "label": "用户体验优先"},
-        {"id": "perf_first", "label": "性能优先"},
-        {"id": "all_equal", "label": "同等重要，一起做"}
-      ]
-    }
-  ]
-}
-\`\`\`
-
-**实现细节相关示例**（仅在无法从代码库分析确定时询问）：
-
-**用户请求**："重构用户认证服务"
-
-**如果无法从代码库分析确定，使用选项式交互提问**：
-
-\`\`\`json
-{
-  "questions": [
-    {
-      "id": "change_scope",
-      "prompt": "重构涉及哪些改动？",
-      "options": [
-        {"id": "modify_existing", "label": "修改现有认证服务类"},
-        {"id": "new_service", "label": "创建新的服务层"},
-        {"id": "both", "label": "两者都涉及"},
-        {"id": "other", "label": "其他"}
-      ]
-    },
-    {
-      "id": "layer_scope",
-      "prompt": "改动应该在哪些层进行？",
-      "options": [
-        {"id": "controller", "label": "Controller 层"},
-        {"id": "service", "label": "Service 层"},
-        {"id": "repository", "label": "Repository 层"},
-        {"id": "all", "label": "全部层"}
-      ],
-      "allow_multiple": true
-    },
-    {
-      "id": "refactor_strategy",
-      "prompt": "重构策略偏好？",
-      "options": [
-        {"id": "incremental", "label": "渐进式重构（逐步替换）"},
-        {"id": "rewrite", "label": "完全重写"},
-        {"id": "strangler", "label": "绞杀者模式（新旧并行后切换）"},
-        {"id": "no_preference", "label": "无偏好，由你推荐"}
-      ]
-    }
-  ]
-}
-\`\`\`
-
-**注意**：如果可以从现有代码结构、规范或项目约定中确定这些信息，则不应询问，直接使用从现有来源获取的信息。
+| 铁律 | 澄清工作流体现 |
+|------|---------------|
+| **No Spec, No Code** | 澄清完成后才能创建提案 |
+| **Spec is Truth** | 澄清结果写入 tasks.md 的"澄清日志" |
+| **Reverse Sync** | Apply 阶段偏离时重新进入澄清流程 |
 
 ### 搜索指导
 - 枚举规范：\`zhuanspec spec list --long\`（或使用 \`--json\` 用于脚本）
@@ -378,6 +544,11 @@ zhuanspec validate [change] --strict
 \`\`\`
 zhuanspec/
 ├── project.md              # 项目约定
+├── knowledge/              # 项目级知识库
+│   ├── index.md            # 知识索引
+│   ├── troubleshooting/    # 常见问题与陷阱
+│   ├── best-practices/     # 最佳实践
+│   └── implicit-conventions/ # 隐式约定
 ├── specs/                  # 当前真实状态 - 已构建的内容
 │   └── [capability]/       # 单一聚焦的功能
 │       ├── spec.md         # 要求和场景
@@ -386,7 +557,7 @@ zhuanspec/
 │   ├── [change-name]/
 │   │   ├── proposal.md     # 原因、内容、影响
 │   │   ├── tasks.md        # 实施清单
-│   │   ├── design.md       # 技术决策（可选；见标准）
+│   │   ├── design.md       # 技术决策（必选；知识提取来源）
 │   │   └── specs/          # 增量变更
 │   │       └── [capability]/
 │   │           └── spec.md # ADDED/MODIFIED/REMOVED
@@ -482,14 +653,9 @@ The system SHALL provide...
 4. 必须在文件末尾添加 "## 依赖分析" 章节并标明"状态：已完成"
 5. validate --strict 会验证任务排序是否与计算的波次匹配
 
-5. **在需要时创建 design.md：**
-如果以下任何情况适用，则创建 \`design.md\`；否则省略：
-- 横切变更（多个服务/模块）或新的架构模式
-- 新的外部依赖或重要的数据模型更改
-- 安全性、性能或迁移复杂性
-- 在编码之前从技术决策中受益的模糊性
+5. **创建 design.md（必选）**：
+每个提案都必须创建 \`design.md\`，记录技术决策和架构思考：
 
-最小 \`design.md\` 骨架：
 \`\`\`markdown
 ## 背景
 [背景、约束、利益相关者]
@@ -505,6 +671,12 @@ The system SHALL provide...
 ## 风险 / 权衡
 - [风险] → 缓解措施
 
+## 最佳实践
+[实施过程中的最佳实践建议]
+
+## 隐式约定
+[团队特有的隐式约定或默认行为]
+
 ## 迁移计划
 [步骤、回滚]
 
@@ -512,6 +684,10 @@ The system SHALL provide...
 - [...]
 \`\`\`
 
+**重要**：design.md 是知识提取的主要来源，归档时会自动提取其中的"决策"、"最佳实践"、"隐式约定"沉淀到项目知识库。
+- [...]
+\`\`\`
+
 ## 规范文件格式
 
 ### 关键：场景格式
@@ -785,5 +961,96 @@ AI 助手在执行时**必须**按照 \`<scheduling_summary>\` 中的指令启
 1. 仍按 wave 顺序执行任务
 2. 每个 task 执行前，清理不相关的 skill 上下文
 3. 每个 task 执行后，仅保留完成摘要，避免上下文累积膨胀
+
+---
+
+## Apply 阶段专用 Agent
+
+Apply 阶段使用两种专用 Agent 类型执行代码实施任务，由编排 Agent（主 Agent）根据任务标注选择。
+
+**Agent 定义文件路径**（供 Claude/Cursor 等工具注册）：
+- \`agents/zhuanspec/apply-agent.md\` - 普通代码实施 Agent
+- \`agents/zhuanspec/tdd-apply-agent.md\` - TDD 模式 Agent
+
+### Agent 类型选择规则
+
+| 条件 | Agent 类型 | 定义文件 |
+|------|-----------|---------|
+| 任务无 \`@test-case\` 标注 | \`applyAgent\` | \`agents/zhuanspec/apply-agent.md\` |
+| 任务有 \`@test-case:TC-XXX\` 标注 | \`tddApplyAgent\` | \`agents/zhuanspec/tdd-apply-agent.md\` |
+
+### Agent 使用方式
+
+编排 Agent（主 Agent）在 Wave 并行执行时：
+
+1. **选择 Agent**：根据任务的 \`@test-case\` 标注选择对应 Agent 类型
+2. **加载 Agent 定义**：读取对应 Agent 定义文件获取完整指令
+3. **注入上下文**：
+   - 当前 task 的完整描述
+   - 相关 spec 文件内容
+   - Rules 和 Knowledge（踩坑警告、最佳实践）
+   - 前序 wave 完成摘要
+4. **启动 Subagent**：使用 Agent tool 启动 subagent
+5. **处理状态报告**：根据 Agent 返回的 Status 执行后续操作
+
+### Rules 和 Knowledge 注入（关键）
+
+编排 Agent MUST 在每个 subagent prompt 中注入以下上下文：
+
+**Rules 加载**（根据 @skill 选择性注入）：
+- \`api-design.md\` - 前后端接口设计规范（涉及 Controller/API 时）
+- \`dao-standards.md\` - Java DAO 层规范（涉及 DAO 时）
+- \`coding-standards.md\` - KF 后端编码规则（涉及 Java 代码时）
+- \`java-db-schema-standards.md\` - MySQL 数据库建表改表规范
+
+**Knowledge 加载**（MUST 始终注入）：
+- \`knowledge/index.md\` - 知识索引摘要
+- 相关 \`best-practices/\` 内容（最佳实践）
+- 相关 \`troubleshooting/\` 内容（踩坑警告）
+
+### 状态处理策略
+
+| Status | 处理方式 |
+|--------|---------|
+| **DONE** | 继续下一任务，记录完成摘要 |
+| **DONE_WITH_CONCERNS** | 评估 concerns，正确性问题先修复，观察性问题记录后继续 |
+| **BLOCKED** | 评估 blocker 类型：提供上下文/换更强模型/拆分任务/修改计划 |
+| **NEEDS_CONTEXT** | 提供缺失信息并重新启动 subagent |
+
+### Subagent 上下文隔离规则
+
+**必须注入**：
+- 当前 task 的完整描述和验收标准
+- 当前 task 关联的 \`@skill\` 内容
+- 相关的 spec 文件路径和内容（仅限该 task 涉及的部分）
+- 前序 wave 的完成摘要（而非完整输出）
+- Rules 和 Knowledge 上下文
+
+**禁止注入**：
+- 其他 wave 的 task 详情
+- 不相关的 skill 内容
+- 其他 subagent 的完整输出
+
+---
+
+### Rules 和 Knowledge 注入示例
+
+编排 Agent 在启动 subagent 时的 prompt 示例：
+
+\`\`\`markdown
+## Rules 和 Knowledge 上下文（必须遵循）
+
+### 相关 Rules
+[根据 @skill 标注注入对应 rules 内容，如 api-design.md]
+
+### Knowledge - 最佳实践
+[注入 best-practices 内容]
+
+### Knowledge - 踩坑警告
+[注入 troubleshooting 内容，如有]
+
+⚠️ **重要**: 以下 rules 和 knowledge MUST 在实施过程中遵循。
+如有任何不确定，报告 NEEDS_CONTEXT 状态。
+\`\`\`
 `;
 //# sourceMappingURL=agents-template.js.map