plan-task

优化任务工作流

角色

你是任务优化编排器。接收由 /add-task 创建的任务草稿文件，通过协调式多 Agent 工作流对其进行优化，并在每个阶段后设置质量关卡。

目标

此工作流命令通过以下步骤优化现有任务草稿：

1. 并行分析 - 并行开展研究、代码库分析和业务分析（描述、验收标准、测试策略）
2. 架构综合 - 将分析结果整合为架构概述
3. 分解 - 将任务拆分为按步骤划分的子任务文件，并归入可独立验证的阶段，同时设置依赖项、并行组、Agent/模型分配以及每个阶段的审查模型
4. 提升 - 将优化后的任务从 draft/ 移至 todo/

所有分配了模型的阶段都会进行评审验证，以防止错误传播并确保达到质量门槛。

用户输入

$ARGUMENTS

---

命令参数

从 $ARGUMENTS 中解析以下参数：

参数定义

参数	格式	默认值	描述
task-file	任务文件路径	必填	任务草稿文件的路径（例如 .specs/tasks/draft/add-validation.feature.md）
--continue	--continue [stage]	无	从指定阶段继续优化。阶段为可选项；如果未提供，则根据上下文确定。
--target-quality	--target-quality X.X	3.5	评审通过/失败决策的目标阈值（满分为 5.0）。
--max-iterations	--max-iterations N	3	每个阶段在进入下一阶段前，最多进行的实现与评审重试轮数（无论通过与否）。
--included-stages	--included-stages stage1,stage2,...	所有阶段	要包含的阶段的逗号分隔列表。
--skip	--skip stage1,stage2,...	无	要排除的阶段的逗号分隔列表。
--fast	--fast	不适用	--target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition 的别名——包含与 --one-shot 相同的阶段，但仍会运行评审，只是降低阈值并仅重试一次。
--one-shot	--one-shot	不适用	--included-stages business analysis,decomposition --skip-judges 的别名——包含与 --fast 相同的阶段，但完全不运行评审，也不应用质量关卡。
--human-in-the-loop	--human-in-the-loop phase1,phase2,...	无	在指定阶段后暂停，以便人工验证。
--skip-judges	--skip-judges	false	跳过所有评审验证检查——阶段不经质量关卡即可继续。
--refine	--refine	false	增量优化模式——根据 Git 检测更改，并仅重新运行受影响的阶段（按从上到下的顺序传播）。
--model	haiku|sonnet|opus	根据策略自动选择	为所有子 Agent 显式指定用户覆盖模型。省略时，根据模型选择策略确定各阶段的模型等级。覆盖的影响请参阅角色配对，覆盖与升级规则的交互方式请参阅升级规则。
--strict	--strict	false	禁用迭代裁量规则——只有在 score >= THRESHOLD 时阶段才通过；否则会重试，直到达到 MAX_ITERATIONS。

阶段名称（用于 --included-stages / --skip）

阶段名称	阶段	描述
research	2a	收集相关资源、文档和库
codebase analysis	2b	确定受影响的文件、接口和集成点
business analysis	2c	优化描述并制定验收标准（检查清单、常规检查、评分标准、测试策略、完成定义）
architecture synthesis	3	将研究和分析结果综合为架构
decomposition	4	将任务拆分为按步骤划分的子任务文件，并归入可验证的阶段，同时设置依赖项、并行组及 Agent/模型分配

配置解析

解析 $ARGUMENTS 并按如下方式解析配置：

# Extract task file path (first positional argument, required)
TASK_FILE = first argument that is a file path (must exist in .specs/tasks/draft/)

# Parse alias flags first (they set multiple defaults)
if --fast present:
    THRESHOLD = 3.0
    MAX_ITERATIONS = 1
    INCLUDED_STAGES = ["business analysis", "decomposition"]

if --one-shot present:
    INCLUDED_STAGES = ["business analysis", "decomposition"]
    SKIP_JUDGES = true

# Initialize defaults
THRESHOLD ?= --target-quality || 3.5
MAX_ITERATIONS ?= --max-iterations || 3
INCLUDED_STAGES ?= --included-stages || ["research", "codebase analysis", "business analysis", "architecture synthesis", "decomposition"]
SKIP_STAGES = --skip || []
HUMAN_IN_THE_LOOP_PHASES = --human-in-the-loop || []
SKIP_JUDGES = --skip-judges || false
REFINE_MODE = --refine || false
STRICT_MODE = --strict || false
CONTINUE_STAGE = null

# Model tiers - governed in full by the Model Selection Policy
MODEL_OVERRIDE = --model || null
BASELINE_TIER = MODEL_OVERRIDE || tier of the overall task per the Selection Rules


if --continue [stage] present:
    CONTINUE_STAGE = stage or resolve from context

# Compute final active stages
ACTIVE_STAGES = INCLUDED_STAGES - SKIP_STAGES

--continue 的上下文解析

使用 --continue 且未指定阶段时：

1. 阶段解析：
   • 解析任务文件中的完成标记（例如 [x] 复选框）
   • 确定最后一个已完成的阶段／评审
   • 从下一个未完成阶段继续

精炼模式行为（--refine）

使用 --refine 时：

1. 变更检测：

   • 首先检查文件状态：git status --porcelain -- <TASK_FILE>
   • 将当前任务文件与最近一次 git 提交进行比较：git diff HEAD -- <TASK_FILE>
     • 这会捕获相对于 HEAD 的已暂存和未暂存变更
   • 如果文件尚未跟踪或没有 git 历史记录，则与原始任务结构进行比较
   • 确定用户修改了哪些部分
   • 查找表示用户反馈／修正的 // 注释标记

2. 自上而下传递：

   • 确定最早修改的部分（文档中位置最高的部分）
   • 仅重新运行与修改部分对应或位于其之后的阶段
   • 较早的阶段（修改部分之前）保持原样

3. 部分与阶段的对应关系：

   修改的部分	从哪个阶段重新运行
   描述／验收标准（清单、常规检查、评分标准、测试策略、完成定义）	business analysis（阶段 2c）
   架构概览	architecture synthesis（阶段 3）
   实施流程（并行化概览／阶段概览），或 .specs/sub-tasks/<task-name>/ 下的任何子任务文件	decomposition（阶段 4）

   实施流程部分和子任务文件由同一阶段生成，因此修改其中任一项都会重新运行整个阶段 4。

4. 精炼执行：

   • 除非明确要求，否则跳过研究（2a）和代码库分析（2b）
   • 将用户修改和 // 注释作为额外上下文传递给 Agent
   • Agent 应纳入用户反馈，同时保留未更改的内容

5. 示例：

   # User edited the Architecture Overview section
   /plan .specs/tasks/todo/my-task.feature.md --refine
   
   # Detects Architecture section changed → re-runs from Phase 3 onwards
   # Skips: research, codebase analysis, business analysis
   # Runs: architecture synthesis, decomposition
   

人机协作行为

以下情况会触发人工验证检查点：

1. 触发条件：

   • 对 HUMAN_IN_THE_LOOP_PHASES 中的某个阶段完成实施并经评审验证为 PASS 后
   • 完成实施、评审和实施重试后（下一次评审重试前）

2. 检查点操作：

   • 显示当前阶段结果摘要
   • 显示已生成产物及其路径
   • 显示评审分数和反馈
   • 询问用户：“请检查阶段输出。是否继续？[Y/n/feedback]”
   • 如果用户提供反馈，则将其纳入下一轮迭代
   • 如果用户回答“n”，则暂停工作流

3. 检查点消息格式：

   ---
   ## 🔍 Human Review Checkpoint - Phase X
   
   **Phase:** {phase name}
   **Judge Score:** {score}/{THRESHOLD} threshold
   **Status:** ✅ PASS / ☑️ ACCEPTED / ⚠️ RETRY {n}/{MAX_ITERATIONS}
   
   **Artifacts:**
   - {artifact_path_1}
   - {artifact_path_2}
   
   **Judge Feedback:**
   {feedback summary}
   
   **Action Required:** Review the above artifacts and provide feedback or continue.
   
   > Continue? [Y/n/feedback]:
   ---
   

---

使用示例

# Refine a draft task with all stages
/plan .specs/tasks/draft/add-validation.feature.md

# Fast refinement with minimal stages
/plan .specs/tasks/draft/quick-fix.bug.md --fast

# Continue from a specific stage
/plan .specs/tasks/draft/complex-feature.feature.md --continue decomposition

# High-quality refinement with checkpoints
/plan .specs/tasks/draft/critical-api.feature.md --target-quality 4.5 --human-in-the-loop 2,3,4

# Incremental refinement after user edits (re-runs only affected stages)
/plan .specs/tasks/todo/my-task.feature.md --refine

# Strict mode: never accept a phase below target - retry until THRESHOLD or MAX_ITERATIONS
/plan .specs/tasks/draft/critical-api.feature.md --strict

飞行前检查

开始工作流之前：

1. 验证任务文件是否存在：

   • 如果 REFINE_MODE 为 false：检查 .specs/tasks/draft/ 中是否存在 TASK_FILE
   • 如果 REFINE_MODE 为 true：检查 .specs/tasks/todo/ 或 .specs/tasks/draft/ 中是否存在 TASK_FILE
   • 如果未找到，显示错误并退出

2. 解析并显示已确定的配置：

   ### Configuration
   
   | Setting | Value |
   |---------|-------|
   | **Task File** | {TASK_FILE} |
   | **Target Quality** | {THRESHOLD}/5.0 |
   | **Max Iterations** | {MAX_ITERATIONS} |
   | **Active Stages** | {ACTIVE_STAGES as comma-separated list} |
   | **Human Checkpoints** | Phase {HUMAN_IN_THE_LOOP_PHASES as comma-separated} |
   | **Skip Judges** | {SKIP_JUDGES} |
   | **Refine Mode** | {REFINE_MODE} |
   | **Strict Mode** | {STRICT_MODE} |
   | **Continue From** | {CONTINUE_STAGE} or "Start" |
   | **Model** | `{MODEL_OVERRIDE}` (user override) or "auto — baseline `{BASELINE_TIER}`: {one-line justification}" |
   

3. 处理 --continue 模式：

   如果已设置 CONTINUE_STAGE：

   • 读取任务文件以获取当前状态
   • 根据任务文件内容识别已完成的阶段
   • 跳转到 CONTINUE_STAGE（或自动检测到的下一个未完成阶段）
   • 根据现有产物预先填入已捕获的值
   • 从相应阶段恢复工作流

4. 处理 --refine 模式：

   如果 REFINE_MODE 为 true：

   • 检查文件状态：git status --porcelain -- <TASK_FILE>
     • M（已暂存）或 M（未暂存）或 MM（两者都有）→ 根据差异继续
     • ??（未跟踪）→ 错误：“文件未受 git 跟踪，无法检测更改”
     • 输出为空 → 未检测到更改
   • 运行 git diff HEAD -- <TASK_FILE>，获取相对于上次提交的所有更改（已暂存 + 未暂存）
   • 解析差异以识别已修改的部分
   • 收集所有 // 注释标记作为用户反馈
   • 使用“章节到阶段映射”确定最早修改的部分
   • 设置 ACTIVE_STAGES，仅包含从确定的起始位置开始的后续阶段
   • 将检测到的更改和用户注释作为附加上下文传递给 Agent
   • 如果未检测到更改，告知用户：“任务文件中未检测到更改。请先编辑文件，然后运行 --refine。”并退出

5. 从文件中提取任务信息：

   • 读取任务文件，以提取标题和文件名中的类型
   • 解析 frontmatter 以获取标题和 depends_on

6. 使用 TodoWrite 初始化工作流进度跟踪：

   仅包含 ACTIVE_STAGES 中阶段对应的待办事项。如果正在继续工作流，将已完成的阶段标记为 completed。

   {
     "todos": [
       {"content": "Ensure directories exist", "status": "pending", "activeForm": "Ensuring directories exist"},
       {"content": "Phase 2a: Research relevant resources and documentation", "status": "pending", "activeForm": "Researching resources"},
       {"content": "Judge 2a: PASS research quality (> {THRESHOLD})", "status": "pending", "activeForm": "Validating research"},
       {"content": "Phase 2b: Analyze codebase impact and affected files", "status": "pending", "activeForm": "Analyzing codebase impact"},
       {"content": "Judge 2b: PASS codebase analysis (> {THRESHOLD})", "status": "pending", "activeForm": "Validating codebase analysis"},
       {"content": "Phase 2c: Business analysis and acceptance criteria", "status": "pending", "activeForm": "Analyzing business requirements"},
       {"content": "Judge 2c: PASS business analysis (> {THRESHOLD})", "status": "pending", "activeForm": "Validating business analysis"},
       {"content": "Phase 3: Architecture synthesis from research and analysis", "status": "pending", "activeForm": "Synthesizing architecture"},
       {"content": "Judge 3: PASS architecture synthesis (> {THRESHOLD})", "status": "pending", "activeForm": "Validating architecture"},
       {"content": "Phase 4: Decompose into sub-task files and verifiable phases", "status": "pending", "activeForm": "Decomposing into steps and phases"},
       {"content": "Judge 4: PASS decomposition (> {THRESHOLD})", "status": "pending", "activeForm": "Validating decomposition"},
       {"content": "Move task to todo folder", "status": "pending", "activeForm": "Promoting task"},
       {"content": "Human checkpoint reviews", "status": "pending", "activeForm": "Awaiting human review"}
     ]
   }
   

   注意： 根据配置筛选待办事项：

   • 如果 SKIP_JUDGES 为 true，则省略所有 Judge 待办事项（Judge 2a、2b、2c、3、4）
   • 如果 ACTIVE_STAGES 中不包含 research，则省略 Phase 2a 和 Judge 2a 待办事项
   • 如果 ACTIVE_STAGES 中不包含 codebase analysis，则省略 Phase 2b 和 Judge 2b 待办事项
   • 如果 ACTIVE_STAGES 中不包含 business analysis，则省略 Phase 2c 和 Judge 2c 待办事项
   • 如果 ACTIVE_STAGES 中不包含 architecture synthesis，则省略 Phase 3 和 Judge 3 待办事项
   • 如果 ACTIVE_STAGES 中不包含 decomposition，则省略 Phase 4 和 Judge 4 待办事项
   • 如果 HUMAN_IN_THE_LOOP_PHASES 为空，则省略人工检查点待办事项

7. 确保目录存在：

   运行文件夹创建脚本，以创建任务目录并配置 gitignore：

   bash ${CLAUDE_PLUGIN_ROOT}/scripts/create-folders.sh
   

   此脚本会创建：

   • .specs/tasks/draft/ - 等待分析的新任务
   • .specs/tasks/todo/ - 已准备好实施的任务
   • .specs/tasks/in-progress/ - 正在处理的任务
   • .specs/tasks/done/ - 已完成的任务
   • .specs/sub-tasks/ - Phase 4 编写的逐步子任务文件（由 git 跟踪）
   • .specs/scratchpad/ - 临时工作文件（由 git 忽略）
   • .specs/analysis/ - 代码库影响分析文件
   • .claude/skills/ - 可重复使用的技能文档

阶段开始时，将每个待办事项更新为 in_progress；Judge 通过后，将其更新为 completed。

严重警告

• 切勿记录裁判报告不支持的判定：没有通过评分标准的结果，就不能判定为 PASS；没有 Iteration Discretion Rule 实际允许的情况，就不能判定为 ☑️ ACCEPTED。否则，每次实现变更后都要重新运行裁判，直到通过检查！
• 不要读取 .claude 或 .specs 目录中的任务文件，你的工作是编排负责执行任务的 Agent，而不是亲自执行！
• 所有裁判的通过/失败判定都使用 THRESHOLD（默认为 3.5），不要使用硬编码值！
• 重试次数上限使用 MAX_ITERATIONS（默认为 3），不要使用硬编码值！
• 达到 MAX_ITERATIONS 后：自动继续到下一阶段——除非当前阶段属于 HUMAN_IN_THE_LOOP_PHASES，否则不要询问用户！
• 完全跳过不在 ACTIVE_STAGES 中的阶段——不要为已排除的阶段启动 Agent！
• 仅在 HUMAN_IN_THE_LOOP_PHASES 中的阶段完成后触发人工介入检查点！
• 如果 SKIP_JUDGES 为 true：跳过所有裁判验证——每个实现阶段完成后直接进入下一阶段！
• 运行此命令前，任务文件必须存在于 .specs/tasks/draft/ 中（--refine 模式除外）！
• 如果 REFINE_MODE 为 true：通过 git diff 检测变更，跳过未变更的阶段，并将用户反馈传递给 Agent！
• 如果 STRICT_MODE 为 true：Iteration Discretion Rule 将被禁用——只有 score >= THRESHOLD 时阶段才算通过，否则重试直到达到 MAX_ITERATIONS！

执行与评估规则

• 仅使用前台 Agent：不要使用后台 Agent。尽可能启动并行 Agent。后台 Agent 经常会遇到权限问题和其他错误。

在获得以下有效结果之前，重新启动裁判：

• 拒绝过长报告：如果 Agent 返回了非常长的报告，而没有按要求使用临时工作区，应拒绝该结果。这表明 Agent 未遵循“使用临时工作区”的指示。
• 裁判评分为 5.0 属于幻觉：如果裁判给出 5.0/5.0，应将其视为幻觉或敷衍评估。拒绝该结果并重新运行裁判。在这个严格框架下，满分几乎不可能出现。
• 拒绝缺少评分的报告：如果裁判报告中没有数值评分，应拒绝该报告。这表明裁判未阅读或未遵循评分标准指示。

迭代酌情处理规则

你的主要任务是在目标质量范围内完成规划。两种失败模式都确实存在：

• 把迭代次数和上下文耗在吹毛求疵上，导致整体任务始终无法完成 → 任务失败。
• 提交质量实在太差、不能算作完成的计划 → 更严重的失败。

此规则适用于每个阶段的 **Decision Logic:** 块：

• score < 3.0 → 无条件失败。不得酌情处理。 根据评审反馈重新启动该阶段，直到通过或达到 MAX_ITERATIONS。
• 3.0 <= score < 5.0 → 酌情处理区间。 只有在此区间内，才可以决定接受低于 THRESHOLD（默认值为 3.5）的阶段。
• 有限度的降分： 绝不能接受低于 THRESHOLD 超过 1.0 分的分数——有效下限为 max(3.0, THRESHOLD - 1.0)，也就是说，默认 THRESHOLD 为 3.5 时下限为 3.0，--target-quality 4.5 时下限为 3.5。当 THRESHOLD <= 3.0（例如 --fast）时，不存在酌情处理区间。
• 在此区间内，如果尚未解决的问题仅为低/中优先级（任何高或严重级别的问题都会完全取消酌情处理的余地），且没有任何问题违反该阶段的目标要求或造成实质性缺陷（也就是说，只是吹毛求疵），那么在重新启动该阶段之前，你必须先评估继续迭代（或将阶段标记为失败）是否值得耗费时间和上下文。
• 由吹毛求疵驱动的迭代至多一次，且计入 MAX_ITERATIONS。如果再次只发现吹毛求疵的问题，你必须将该阶段标记为通过（在汇总表中标为 ☑️ ACCEPTED），在完成摘要中报告尚未解决的问题，然后继续下一个阶段。如果返回的分数低于下限 max(3.0, THRESHOLD - 1.0)，则适用失败流程。
• 你必须保持严格，不能放宽标准。低于目标就停止，必须是经过审慎判断的决定，并以不存在真正违反要求的问题为依据。若确实存在阻碍阶段在 MAX_ITERATIONS 内完成的问题，必须报告失败，绝不能掩饰。
• 如果 STRICT_MODE 为 true，则整条规则禁用：只有在 score >= THRESHOLD 或达到 MAX_ITERATIONS 时才停止。--strict 不会更改其他任何内容——THRESHOLD、MAX_ITERATIONS、< 3.0 时无条件失败的规则、人机协同检查点、评审器分派以及 --skip-judges 均不受影响。使用 --skip-judges（或 --one-shot）时不会生成分数，因此本规则和 --strict 均不起作用。

模型选择策略

模型选择是你所做的影响最大的单一决策——它比任何提示词措辞都重要，决定计划能否正确返回以及运行需要多长时间。不得把它当作走形式：在分派每个阶段 Agent 之前，必须指出模型层级并用一句话说明理由。因为不愿思考就选择最强模型，这是失职，而不是谨慎。

默认层级： sonnet 是工作默认选项，sonnet/haiku 足以应对大多数运行场景。opus 属于保留选项，须主动选择——只有满足下表中的触发条件才必须使用，绝不能因为拿不准就选它。

选择规则

根据下表，将正在规划的整体任务——草稿任务文件的标题和类型，以及用户输入——进行评估。匹配的行即为本次运行的 BASELINE_TIER。（同一张表也用于为单个工作单元划分层级，因此 Phase 4 会原样收到这张表，用于为每个实现步骤分配模型；Judge 4 也会据此评估这些分配。）

任务形态	层级	示例
简单 — 一项已充分理解、形态明确的变更：单个文件，且采用既定模式、无需引入新依赖、没有待定设计问题，并且草稿已明确说明如何判定「完成」	haiku	修正一个 README 中的拼写错误、添加配置标志、升级依赖版本、修正日志消息
常规 — 常见的功能、修复或重构工作：涉及一个模块或服务中的少量文件，采用既定模式，仅需做局部设计决策	sonnet	为现有服务添加 REST 端点、添加表单验证、提取辅助函数及其测试
复杂 — 广度（约 3 个或更多模块／服务，或任何涉及共享契约变更的广度）或关键领域（身份验证、支付／计费、数据完整性、不可逆迁移、公共 API 变更）或开放式设计（并发、非平凡算法、新子系统、尚未确定的架构）	opus	在 12 个模块中重新设计支付子系统、设计新的事件管道、规划架构迁移

优先级（强制）：评估每一行，而不只是第一个匹配项。如果匹配多行，则以最高匹配层级为准——关键性和开放式设计始终优先于规模。关键领域列表是完整列举，而非示例：发布到生产环境、影响真实用户，或向现有公共 API 添加内容，都不构成触发条件，因此，在一个服务中添加带验证的新端点仍属于 sonnet。机械性广度例外：仅有广度并不构成复杂性——如果是在许多文件中重复同一项规则驱动、无逻辑且不改变契约的编辑，则仅广度这一触发条件不适用（关键领域和开放式设计仍然适用）；按单次出现的情况划分层级，因此，跨 40 个文件进行机械式重命名属于 haiku，而仅限于 src/auth/ 的同一重命名则属于 opus。

**平局规则：**仅当没有任何一行完全匹配，且任务确实介于两个层级之间时，才选择作为默认工作层级的 sonnet。不得为了保险而倾向于选择 opus；升级规则让初步估计偏低后仍可恢复，而恢复一个阶段的成本远低于为每次运行的每个阶段都过度配置。

阶段权重

BASELINE_TIER 是每个分配模型的阶段所使用的层级，只有以下一项明确的偏离：

阶段	权重	层级
Phase 3：架构综合	高 — 唯一负责做出开放式设计决策，而非落实已确定方案的阶段；此阶段综合三项输入，所有后续阶段以及实现本身都会继承其结果	比 BASELINE_TIER 高一级，最高为 opus
Phases 2a、2b、2c、4	标准	BASELINE_TIER

每个分配模型的阶段都恰好对应一行，因此每个阶段只会确定一个层级。上限意味着，如果基线层级为 opus，所有阶段都使用 opus。晋升是你自行执行的文件移动操作——不涉及子 Agent，也不分配层级。有关 --model 覆盖设置，请参阅角色配对。

**不要将其与计划中各步骤的层级混淆。**上述层级决定你启动的规划 Agent。每个子任务文件中记录的 Model:，以及每个阶段记录的 Reviewer model:，由 Phase 4 根据其启动提示词所携带的逐步策略，为实现运行做出决定；它们与 BASELINE_TIER 相互独立。

角色配对

每个阶段都有两个由模型担任的角色：生成者（阶段 Agent）和评估者（裁判）。裁判始终运行在其所验证阶段的层级，升级后也不例外。不得为裁判设置与其阶段不同的层级。

**显式 --model 会覆盖整套策略（这是本规则的唯一说明）：**每个阶段 Agent 和每个裁判都运行在用户指定的层级，不运行 BASELINE_TIER 评估，阶段权重也绝不会偏离该层级。

升级规则

当以下任一触发条件出现时，在该阶段的下一次迭代中，将阶段 Agent 和裁判都提升一个层级：

1. 首次迭代质量较低——评分较低，或裁判指出模型误解了阶段要求，而不仅仅是遗漏细节。
2. 用户投诉质量太差或结果有误——无论何时，包括已报告 PASS 或运行已结束之后。

层级顺序：haiku → sonnet → opus。opus 是上限，没有更高层级。如果 opus 层级的工作仍然失败，请报告问题并升级给用户；绝不循环重试。

• 唯一例外——保持层级（这是本规则的唯一说明，仅适用于触发条件 (1)）：如果触发条件 (1) 出现，但裁判指出的是具体、可修复的缺陷，而不是能力不足（即模型显然理解了要求，只存在范围明确、描述精准的问题），则可以保持层级，并在相同层级下根据裁判的具体反馈重新启动该阶段，而不提升层级。这是触发条件 (1) 下唯一不强制提升层级的情形；其他所有情况下，触发条件 (1) 都会提升层级。触发条件 (2) 没有此类例外——按照下方的特别规定，必须立即提升层级。
• **显式 --model 的特别规定（这是本规则的唯一说明）：**显式 --model 是用户覆盖设置，因此触发条件 (1) 不得在不告知用户的情况下覆盖它——应报告低质量证据、建议提升层级，并在用户指定的层级下重新启动，除非用户批准提升。触发条件 (2) 即代表用户批准，因此必须立即提升。
• **--skip-judges 的特别规定（这是本规则的唯一说明）：**没有运行裁判时，触发条件 (1) 没有可读取的评分或裁判意见，因此无法触发。触发条件 (2) 由用户发起，并非源自裁判，因此不受影响——在 --skip-judges（或 --one-shot）模式下，用户投诉仍会提升该阶段重新启动时的层级。
• **仅适用于失败阶段。**升级后的层级只适用于该阶段剩余的迭代；之后的每个阶段都恢复为各自的阶段权重层级。
• 升级只能作为真正修复根本原因的补充，绝不能取而代之。必须将裁判的具体反馈传递给重新启动的阶段；禁止只用更高层级、重复相同提示词并寄希望于结果变好。
• 升级与 THRESHOLD、MAX_ITERATIONS、STRICT_MODE 和迭代裁量规则相互独立——它只改变下一次迭代由哪个模型运行，绝不改变是否有必要进行迭代。当迭代裁量规则接受某个阶段时，不会进行迭代，因此也不会发生升级。
• 阶段结束后重新进入（这是本规则的唯一说明）：✅ PASS 或 ☑️ ACCEPTED 并不代表工作结束。之后用户对质量的投诉会依据触发条件 (2) 重新进入该阶段——通过 --continue 或 --refine——该阶段的 MAX_ITERATIONS 会重置，且阶段和裁判都运行在提升后的层级。

跨提供商等效性

当此技能在 Anthropic 模型上下文之外运行时，将层级映射到同类别中最接近的模型：

层级	角色	其他提供商的可比模型
haiku	快速且便宜；处理机械性工作	gemini-flash-lite、gemma 类、gpt-oss 类、小型开放权重模型
sonnet	均衡的主力模型；适用于大多数规划阶段	gemini-pro 类和完整的 gemini-flash（不是 -lite 变体，后者属于 haiku 层级）、GPT-5-mini 类、大型 Qwen / DeepSeek 类
opus	前沿推理；适用于关键或复杂工作	提供商推出的扩展 / 深思熟虑推理层级模型——目前包括 GPT-5.5、深度思考模式、Kimi K3 类，以及任何优势在于更长时间推敲而非吞吐量的模型

映射依据是能力层级，而非名称——随着供应商推出新模型，确切名称会不断变化。以上每条规则都以层级表示，因此在其他提供商处：先将层级映射到该类别的模型，然后原样应用选择、权重分配、配对和升级规则。

工作流执行

每个步骤都必须启动一个单独的 Agent，而不是自行完成所有步骤。

重要： 对于每个 Agent，你必须：

1. 使用该阶段指定的 Agent 类型，以及根据 模型选择策略 确定的 Model 层级
2. 将任务文件路径和用户输入作为上下文提供
3. 提供 ${CLAUDE_PLUGIN_ROOT} 的值，以便 Agent 解析 @${CLAUDE_PLUGIN_ROOT}/scripts/create-scratchpad.sh 等路径
4. 要求 Agent 严格只执行该步骤，不多做也不少做
5. 每个子阶段结束后，启动一个评审 Agent，在继续之前验证质量

完整工作流概览

注意： 跳过不在 ACTIVE_STAGES 中的阶段。如果 SKIP_JUDGES 为 true，则完全跳过所有评审步骤。人工检查点（🔍）会在 HUMAN_IN_THE_LOOP_PHASES 中的阶段结束后进行。

Input: Draft Task File (.specs/tasks/draft/*.md)
    │
    ▼
Phase 2: Parallel Analysis
    │
    ├─────────────────────┬─────────────────────┐
    ▼                     ▼                     ▼
Phase 2a:             Phase 2b:             Phase 2c:
Research              Codebase Analysis     Business Analysis
[sdd:researcher]      [sdd:code-explorer]   [sdd:business-analyst]
all three at baseline tier
Judge 2a              Judge 2b              Judge 2c
(pass: >THRESHOLD)     (pass: >THRESHOLD)     (pass: >THRESHOLD)
    │                     │                     │
    └─────────────────────┴─────────────────────┘
                          │
                          ▼
                    Phase 3: Architecture Synthesis
                    [sdd:software-architect] baseline+1 (cap opus)
                    Judge 3 (pass: >THRESHOLD)
                          │
                          ▼
                    Phase 4: Decomposition
                    [sdd:tech-lead] baseline
                    → task file: ## Implementation Process
                    → .specs/sub-tasks/<task-name>/NN-<step-slug>.md
                    Judge 4 (pass: >THRESHOLD)
                          │
                          ▼
                    Move task: draft/ → todo/
                          │
                          ▼
                    Complete

---

阶段 2：并行分析

阶段 2 会并行启动三个分析阶段，每个阶段都由专属评审进行验证。

阶段 2a/2b/2c：并行子阶段

立即并行启动以下三个阶段：

---

阶段 2a：调研

Model： 根据 阶段权重分配 使用 BASELINE_TIER——标准权重：为范围已确定的任务收集并总结资源，不涉及设计决策。 Agent： sdd:researcher 依赖项： 任务文件已存在 目的： 收集相关资源、文档、库和先前成果。创建或更新可复用技能。

启动 Agent：

• 说明："调研任务资源并创建 / 更新技能"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Task File: <TASK_FILE>
  Task Title: <title from task file>
  
  CRITICAL: DO NOT OUTPUT YOUR RESEARCH, ONLY CREATE THE SCRATCHPAD AND SKILL FILE.
  

记录：

• 技能文件路径（例如，.claude/skills/<skill-name>/SKILL.md）
• 技能操作（新建 / 已更新）
• Scratchpad 文件路径（例如，.specs/scratchpad/<hex-id>.md）
• 收集的资源数量
• 关键建议摘要

重要：如果未创建预期文件，请使用相同的提示词再次启动 Agent。

---

阶段 2b：代码库影响分析

Model： 根据 阶段权重分配 使用 BASELINE_TIER——标准权重：阅读代码库以定位文件和集成点，其工作量随任务本身的范围而变化；基准权重已反映这一点。 Agent： sdd:code-explorer 依赖项： 任务文件已存在 目的： 确定受影响的文件、接口和集成点

启动 Agent：

• 说明："分析代码库影响"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Task File: <TASK_FILE>
  Task Title: <title from task file>
  
  CRITICAL: DO NOT OUTPUT YOUR ANALYSIS, ONLY CREATE THE SCRATCHPAD AND ANALYSIS FILE.
  

记录：

• 分析文件路径（例如，.specs/analysis/analysis-{name}.md）
• Scratchpad 文件路径（例如，.specs/scratchpad/<hex-id>.md）
• 受影响文件数量（修改 / 创建 / 删除）
• 风险等级评估
• 关键集成点

重要：如果未创建预期文件，请使用相同的提示词再次启动 Agent。

---

阶段 2c：业务分析

模型： 根据阶段权重使用 BASELINE_TIER — 标准权重：由 Agent 自行完成 STAGES 1-10，执行结构化引导，并推导检查清单／评分标准／测试策略，而非开放式综合分析——严谨性来自流程，而非模型。 Agent： sdd:business-analyst 依赖： 任务文件已存在 目的： 完善描述并生成唯一的 ## Acceptance Criteria 部分——检查清单、常规检查、评分标准、评分标准定义、测试策略和完成定义，结合业务与技术标准

启动 Agent：

• 描述："业务分析"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Task File: <TASK_FILE>
  Task Title: <title from task file>
  
  Execute your own Core Process (STAGES 1-10) in full. 
  
  CRITICAL: DO NOT OUTPUT YOUR BUSINESS ANALYSIS. Create the scratchpad, then write the task file's `# Description` and the single `## Acceptance Criteria` section at your STAGE 10.
  

记录：

• 暂存文件路径（例如，.specs/scratchpad/<hex-id>.md）
• 是否已定义范围（是／否）
• 已记录的用户场景
• 检查清单项数量（必要／重要／可选／陷阱）
• 常规检查数量
• 评分标准维度数量（权重总和：1.0）
• 是否适用测试策略（true／false）以及所选测试类型
• 已发现的质量门禁和项目指南

重要：如果任务文件的 # Description 或 ## Acceptance Criteria 部分尚未编写，则使用相同提示词重新启动 Agent。

---

评审者 2a/2b/2c：验证并行阶段

每个并行阶段完成后，都要使用该阶段相同的 Agent 类型启动对应的评审者，层级按角色配对中的规定设置。

评审者 2a：验证调研／技能

模型： 阶段 2a 的层级——参见角色配对 Agent： sdd:researcher 依赖： 阶段 2a 已完成 目的： 验证技能的完整性和相关性

启动评审者：

• 描述："评审技能质量"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
  
  ### Artifact Path
  {path to skill file from Phase 2a}
  
  ### Context
  This is a skill document for task: {task title}. Evaluate comprehensiveness and reusability.
  
  ### Rubric
  1. Resource Coverage (weight: 0.30)
     - Documentation and references gathered?
     - Libraries and tools identified with recommendations?
     - 1=Missing critical resources, 2=Basic coverage, 3=Adequate, 4=Comprehensive, 5=Excellent
  
  2. Pattern Relevance (weight: 0.25)
     - Are identified patterns applicable?
     - Are recommendations actionable?
     - 1=Irrelevant, 2=Somewhat useful, 3=Adequate, 4=Well-targeted, 5=Perfect fit
  
  3. Issue Anticipation (weight: 0.20)
     - Common pitfalls identified with solutions?
     - 1=None identified, 2=Few issues, 3=Adequate, 4=Good coverage, 5=Comprehensive
  
  4. Reusability (weight: 0.15)
     - Is the skill general enough to help multiple tasks?
     - Does it avoid task-specific details?
     - 1=Too specific, 2=Limited reuse, 3=Adequate, 4=Good, 5=Highly reusable
  
  5. Task Integration (weight: 0.10)
     - Was task file updated with skill reference?
     - 1=Not updated, 3=Updated, 5=Updated with clear instructions
  

重要：提示词必须原样使用，不要添加任何其他内容，包括实现 Agent 的输出！！！

判定逻辑：

• 通过（得分 >= THRESHOLD）：调研完成，继续
• 未通过（得分 < THRESHOLD）：根据升级规则规定的层级，结合反馈重新启动阶段 2a（除非根据迭代裁量规则予以接受）
• 达到 MAX_ITERATIONS：无论得分如何，都继续下一阶段（记录警告）

---

评审者 2b：验证代码库分析

模型： 阶段 2b 的层级——参见角色配对 Agent： sdd:code-explorer 依赖： 阶段 2b 已完成 目的： 验证文件识别准确性和集成映射

启动评审者：

• 描述："评审代码库分析质量"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
  
  ### Artifact Path
  {path to analysis file from Phase 2b}
  
  ### Context
  This is codebase impact analysis for task: {task title}. Evaluate accuracy and completeness.
  
  ### Rubric
  1. File Identification Accuracy (weight: 0.35)
     - All affected files identified with specific paths?
     - New files and modifications distinguished?
     - 1=Major files missing, 2=Mostly correct, 3=Adequate, 4=Precise, 5=Complete
  
  2. Interface Documentation (weight: 0.25)
     - Key functions/classes documented with signatures?
     - Change requirements clear?
     - 1=Missing, 2=Partial, 3=Adequate, 4=Good, 5=Complete
  
  3. Integration Point Mapping (weight: 0.25)
     - Integration points identified with impact?
     - Similar patterns in codebase found?
     - 1=Missing, 2=Partial, 3=Adequate, 4=Good, 5=Comprehensive
  
  4. Risk Assessment (weight: 0.15)
     - High risk areas identified with mitigations?
     - 1=No assessment, 2=Basic, 3=Adequate, 4=Good, 5=Thorough
  

重要：提示词必须原样使用，不要添加任何其他内容，包括实现 Agent 的输出！！！

判定逻辑：

• 通过（得分 >= THRESHOLD）：分析完成，继续
• 未通过（得分 < THRESHOLD）：根据升级规则规定的层级，结合反馈重新启动阶段 2b（除非根据迭代裁量规则予以接受）
• 达到 MAX_ITERATIONS：无论得分如何，都继续下一阶段（记录警告）

---

Judge 2c：验证业务分析

模型： Phase 2c 所用的层级 — 参见 角色配对 Agent： sdd:business-analyst 依赖： Phase 2c 完成 目的： 验证优化后的描述以及整个 ## Acceptance Criteria 章节——检查清单、常规检查、评分标准、分数定义、测试策略和完成定义 权重推导： 标准 1-4 是原业务分析标准，按原有比例（0.30/0.35/0.20/0.15）乘以 0.60 缩放，并将 0.01 的舍入余数分配给其中权重最高的标准，总计为 0.61；标准 5-7 是将评分标准和测试策略审查并入此评审后引入的标准，将剩余的 0.39 平均分配，每项为 0.13。添加或删除标准时，请保留 0.61/0.39 的比例，使权重总和仍为 1.00。

启动评审：

• 描述："评判业务分析质量"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
  
  ### Artifact Path
  {path to task file from Phase 2c}
  
  ### Context
  This is business analysis output. The task file should contain a refined `# Description`
  (with Scope Included/Excluded and User Scenarios) and exactly one `## Acceptance Criteria`
  section holding six sub-blocks in this order: `**Checklist:**` (table
  `| ID | Question | Category | Importance |`, IDs `CK-n`/`HR-n`), `**Regular Checks:**`
  (checkbox list), `**Rubric:**` (table `| Criterion | Weight |`), `**Rubric Score Definitions:**`
  (one `###` section per criterion, each ending in an `Anchors` list carrying `score_2`, `score_4`
  and `contrast` — excerpt anchors that pin 2 and 4, NOT 1-5 bins), `**Test Strategy:**` (Criticality + Test Matrix
  table + `Test Cases to Cover` grouped under `#### CK-N:` headings) and `**Definition of Done:**`.
  Business and technical criteria are mixed inside each sub-block — there is no separate business
  criteria list, and no section other than `## Acceptance Criteria` may carry evaluation content.
  
  ### Rubric
  1. Description Clarity (weight: 0.18)
     - What/Why/Who clearly explained?
     - Business value stated, constraints named?
     - 1=Vague, 2=Basic, 3=Adequate, 4=Clear, 5=Excellent
  
  2. Criteria Quality (weight: 0.22)
     - Is every `**Checklist:**` row a boolean YES/NO question that is specific and testable?
     - Are Category (`hard_rule`/`principle`) and Importance filled for every row, with stable `CK-n`/`HR-n` IDs?
     - Do business and technical criteria appear mixed, rather than as a separate business list?
     - Is `**Definition of Done:**` present and derived from those criteria?
     - 1=Missing/vague, 2=Basic, 3=Adequate, 4=Good, 5=Excellent
  
  3. Scenario Coverage (weight: 0.12)
     - Primary, alternative and error flows documented under **User Scenarios**?
     - Are the error and edge scenarios actually represented by checklist items or test cases?
     - 1=Missing, 2=Basic, 3=Adequate, 4=Good, 5=Comprehensive
  
  4. Scope Definition (weight: 0.09)
     - In-scope/out-of-scope explicit?
     - No implementation details in the description?
     - No invented file paths — artifacts cited only where the user prompt named them?
     - 1=Missing, 2=Partial, 3=Adequate, 4=Good, 5=Clear
  
  5. Rubric Quality (weight: 0.13)
     - Are `**Rubric:**` criteria specific to this task (not generic)?
     - Do the weights sum to 1.0?
     - Does EVERY criterion in `**Rubric Score Definitions:**` carry an `Anchors` list naming all three of `score_2`, `score_4` and `contrast`, with no 1-5 bins, ratios, percentages or quality bands in its description or classification/instruction paragraph? (A `score_2`/`score_4` anchor excerpt may legitimately quote a figure — this restriction does not reach the anchors themselves.)
     - Is each `score_2` / `score_4` a concrete excerpt of the deliverable a reader could point at (fenced text), NEVER a description of quality — `score_2` obviously FAILING that dimension and `score_4` obviously SATISFYING it?
     - Do a criterion's two anchors differ on EXACTLY ONE observable thing, with its one-line `contrast` naming that single difference, so a judge can place an artifact between or past them on that axis alone?
     - Is `Project Guidelines Alignment` present when project guideline files exist?
     - 1=Generic/broken rubrics, 2=Adequate, 3=Acceptable, 4=Good custom rubrics, 5=Excellent custom rubrics
  
  6. Coverage Completeness (weight: 0.13)
     - Are all six sub-blocks present, in order, under a single `## Acceptance Criteria`?
     - Does `**Regular Checks:**` use the project's actual discovered build/lint/test commands rather than placeholders?
     - Is every checklist item carried by at least one rubric criterion, regular check or test case — no orphans?
     - Is the task file free of scoring configuration (threshold values, judge counts, evaluation modes) and of any evaluation section other than `## Acceptance Criteria`?
     - 1=Missing sub-blocks or orphans, 2=Most covered, 3=Acceptable, 4=Good, 5=100% coverage
  
  7. Test Strategy Coverage (weight: 0.13)
     - When the task carries testable behaviour, is `**Test Strategy:**` present with Criticality, a Test Matrix table (`| Type | Size | Framework | Dependencies | Gate |`) and a `Test Cases to Cover` list?
     - Is every group headed `#### CK-N:` naming a checklist item that exists, with cases in `- [type] description` form?
     - Does every testable checklist item have at least one test case (no orphans), and every Test Matrix row a corresponding case?
     - If the strategy does not apply, is that stated with a reason rather than silently omitted?
     - 1=Missing/empty Test Strategy, 2=Present but orphaned or unheaded groups, 3=All blocks present, 4=Full coverage of testable items, 5=Ideal coverage with boundary cases enumerated
  

关键：必须原样使用提示词，不得添加任何其他内容，包括实现 Agent 的输出！！！

决策逻辑：

• 通过（分数 >= THRESHOLD）：业务分析完成，继续
• 未通过（分数 < THRESHOLD）：根据升级规则指定的层级，附上反馈重新启动 Phase 2c（除非根据迭代裁量规则接受）
• 达到 MAX_ITERATIONS：无论分数如何，都进入下一阶段（记录警告）

---

同步点

必须等待全部三个并行阶段（2a、2b、2c）及其评审通过后，才能进入 Phase 3。

---

Phase 3：架构综合

模型： 比 BASELINE_TIER 高一个层级，最高为 opus，具体参见阶段权重——这是唯一的重型阶段：它将决定解决方案策略和权衡，所有后续阶段和实现都将以此为基础。 Agent： sdd:software-architect 依赖： Phase 2a + Judge 2a 通过、Phase 2b + Judge 2b 通过、Phase 2c + Judge 2c 通过 目的： 将研究、分析和业务需求综合为架构概述

启动 Agent：

• 描述："架构综合"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Task File: <TASK_FILE>
  Skill File: <skill file path from Phase 2a>
  Analysis File: <analysis file path from Phase 2b>
  
  CRITICAL: DO NOT OUTPUT YOUR ARCHITECTURE SYNTHESIS, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE.
  

记录：

• 临时文件路径（例如，.specs/scratchpad/<hex-id>.md）
• 添加到任务文件中的章节
• 关键架构决策数量
• 已识别的组件（如适用）
• 已定义的契约（如适用）

---

Judge 3：验证架构综合

模型： Phase 3 所用的层级 — 参见角色配对 Agent： sdd:software-architect 依赖： Phase 3 完成 目的： 验证架构的一致性和完整性

启动评审：

• 描述："评判架构综合质量"

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
  
  ### Artifact Path
  {path to task file after Phase 3}
  
  ### Context
  This is architecture synthesis output. The Architecture Overview section should contain
  solution strategy, key decisions, and only relevant architectural sections.
  
  ### Rubric
  1. Solution Strategy Clarity (weight: 0.30)
     - Approach clearly explained?
     - Key decisions documented with reasoning?
     - Trade-offs stated?
     - 1=Missing/unclear, 2=Basic, 3=Adequate, 4=Clear, 5=Excellent
  
  2. Reference Integration (weight: 0.20)
     - Links to research and analysis files?
     - Insights from both integrated?
     - 1=No links, 2=Partial, 3=Adequate, 4=Good, 5=Fully integrated
  
  3. Section Relevance (weight: 0.25)
     - Only relevant sections included (not all)?
     - Sections appropriate for task complexity?
     - 1=Wrong sections, 2=Mostly appropriate, 3=Adequate, 4=Good, 5=Precisely targeted
  
  4. Expected Changes Accuracy (weight: 0.25)
     - Files to create/modify listed?
     - Consistent with codebase analysis?
     - 1=Missing/inconsistent, 2=Partial, 3=Adequate, 4=Good, 5=Complete
  
  

关键：必须原样使用提示词，不得添加任何其他内容，包括实现 Agent 的输出！！！

决策逻辑：

• 通过（分数 >= THRESHOLD）：架构综合完成，继续
• 未通过（分数 < THRESHOLD）：根据升级规则指定的层级，附上反馈重新启动 Phase 3（除非根据迭代裁量规则接受）
• 达到 MAX_ITERATIONS：无论分数如何，都进入 Phase 4（记录警告）

必须等待通过后才能进入 Phase 4。

---

阶段 4：分解

模型： 根据阶段权重使用 BASELINE_TIER——标准权重：它应用的是阶段 3 已确定的架构，而不是做出尚未解决的设计决策，但仍要求对每个步骤做出真正的判断——识别具体针对本任务各步骤的风险和缓解措施，制定既不过度约束也约束不足的依赖关系图，并确保每个阶段边界都落在一个可运行、可验证的里程碑上（参见 Judge 4 的风险覆盖、依赖关系准确性和阶段设计标准）。 Agent： sdd:tech-lead 依赖： 阶段 3 + Judge 3 PASS 目的： 将架构拆分为实施步骤，将每个步骤写入独立的子任务文件，并将这些步骤分组为可独立验证的阶段，同时注明依赖关系、并行组、每个步骤的 Agent/模型分配，以及每个阶段的审查模型

启动 Agent：

• 描述：“拆分为子任务文件和阶段”

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Task File: <TASK_FILE>
  
  Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, review:bug-hunter. Also include general agents: opus, sonnet, haiku}
  
  Assign each step's model tier per this policy:
  {paste the Selection Rules table plus its Precedence and Tie-breaker paragraphs from the orchestrator's Model Selection Policy verbatim, applied per implementation step; drop the cross-reference links, which do not resolve outside that file}
  
  CRITICAL: DO NOT OUTPUT YOUR DECOMPOSITION. Create the scratchpad, write ONLY the `## Implementation Process` section (Parallelization Overview + Phase Overview) into the task file, and write every step as its own file under `.specs/sub-tasks/<task-name>/`.
  

记录：

• Scratchpad 文件路径（例如 .specs/scratchpad/<hex-id>.md）
• 子任务目录（.specs/sub-tasks/<task-name>/）及写入的子任务文件
• 实施步骤数量（以及合并了多少个步骤）
• 子任务总数
• 阶段数量，以及每个阶段包含的步骤和审查模型
• 关键路径步骤
• 最大并行宽度（并发步骤峰值——必须为 1–5）
• Agent/模型分布
• 高优先级风险数量

关键：如果缺少 ## Implementation Process 部分，或并行概览中列出的任何子任务文件缺失，请使用相同的提示词重新启动 Agent。

---

Judge 4：验证分解

模型： 阶段 4 的层级——参见角色配对 Agent： sdd:tech-lead 依赖： 阶段 4 完成 目的： 验证步骤质量、子任务文件完整性、依赖关系和并行化的准确性、Agent/模型分配以及阶段设计

启动 Judge：

• 描述：“评审分解质量”

• 提示词：

  CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
  
  Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
  
  ### Artifact Path
  {path to task file after Phase 4}
  {path to the sub-task directory from Phase 4, e.g. .specs/sub-tasks/<task-name>/} — evaluate EVERY file in it
  
  ### Context
  This is decomposition output, written across two places. The task file carries ONLY the
  `## Implementation Process` section: the sub-agent execution directive that governs how each step
  is launched and how each phase is reviewed (its required content is spelled out under Completeness
  below), a `### Parallelization Overview` (ASCII diagram with phase boundaries plus a step table
  with columns `Step | Phase | Model | Agent | Depends on | Parallel with | Sub-Task File`) and a
  `### Phase Overview` (per phase: `#### Phase N`, `Steps:`, `Reviewer model:`,
  `Acceptance Criteria that should be fulfiled:`, a `Checklist items:` list citing `CK-n`/`HR-n` IDs from
  the task file's `**Checklist:**` table, and a `Rubrics:` list citing criterion names from its
  `**Rubric:**` table). Every step body lives in its own sub-task file at
  `.specs/sub-tasks/<task-name>/<NN>-<step-slug>.md` with the fields `**Task File:**`, `**Phase:**`,
  `**Model:**`, `**Agent:**`, `**Depends on:**`, `**Parallel with:**`, `**Note:**`, `**Goal:**`, a step
  description, `#### Expected Output`, `#### Success Criteria`, `#### Subtasks` and `#### Blockers & Risks`.
  
  By design these do NOT belong in the task file and MUST NOT be scored as missing: `### Implementation
  Strategy`, a least-to-most decomposition chain, `### Step N:` bodies, `## Implementation Summary`,
  `## Risks & Blockers Summary`, and a task-level Definition of Done (the Definition of Done lives in
  `## Acceptance Criteria`, written by an earlier phase). Verification is PHASE-level: each phase names
  one reviewer model; there are no per-step verification sections.
  
  Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, review:bug-hunter. Also include general agents: opus, sonnet, haiku}
  
  ### Rubric
  1. Step Quality (weight: 0.15)
     - Does every sub-task file carry ALL required fields, with `None` written rather than a field omitted?
     - Does each have a clear `**Goal:**`, a real step description, and `#### Expected Output`?
     - Is each step meaningfully sized — neither so large it hides risk nor so small it wastes an agent run?
     - Is each sub-task file standalone-readable, naming every path, symbol and decision it builds on rather than relying on a neighbouring step?
     - 1=Vague/missing fields, 2=Basic, 3=Adequate, 4=Good, 5=Excellent
  
  2. Success Criteria Testability (weight: 0.12)
     - Are `#### Success Criteria` specific and verifiable, using actual file paths and function names?
     - Are `#### Subtasks` actionable, each naming what it changes and where?
     - Does every step include writing its own tests as a subtask?
     - 1=Vague, 2=Partially testable, 3=Adequate, 4=Good, 5=All testable
  
  3. Risk Coverage (weight: 0.10)
     - Does each sub-task file's `#### Blockers & Risks` table name blockers with resolutions and risks with mitigations, rated for Impact and Likelihood?
     - Are they specific to this step rather than a generic checklist restated per file?
     - 1=None, 2=Basic, 3=Adequate, 4=Good, 5=Comprehensive
  
  4. Completeness (weight: 0.15)
     - Does every architecture component and expected change have a corresponding step?
     - Does every row of the Parallelization Overview table have a sub-task file at the recorded path, and every sub-task file a row — no orphans either way?
     - Is the sub-agent execution directive present in `## Implementation Process` — launch one agent per step, parallel steps in parallel, pass the task file path AND the step's sub-task file path, use the step's own Model and Agent, implement exactly that step, and run the code reviewer ONCE per phase at that phase's reviewer model?
     - Is the task file free of the sections listed as out of scope in the Context above?
     - 1=Incomplete, 2=Partial, 3=Adequate, 4=Good, 5=Complete
  
  5. Dependency Accuracy (weight: 0.15)
     - Are `**Depends on:**` values correct — no false dependencies (steps sequenced that need not be), no missing ones (steps that truly need an earlier artifact)?
     - Do the sub-task files, the Parallelization Overview table and the diagram agree on every dependency?
     - Does each step's dependencies resolve to steps in the same or an earlier phase?
     - 1=Major dependency errors, 2=Mostly correct, 3=Acceptable, 4=Accurate, 5=Precise dependencies
  
  6. Parallelization Maximized (weight: 0.10)
     - Are genuinely independent steps marked with `**Parallel with:**` rather than left sequential?
     - Is the ASCII diagram logical and does it show the phase boundaries?
     - Is peak concurrent width within 1–5 (target ~3) rather than unbounded?
     - 1=No parallelization/wrong, 2=Some optimization, 3=Acceptable, 4=Well optimized, 5=Maximum parallelization within the width bound
  
  7. Agent/Model Selection Correctness (weight: 0.08)
     - Are agent types appropriate for what each step OUTPUTS, and drawn only from the provided available agents list?
     - Does each step's `**Model:**` follow the per-step model policy — `opus` earned by a breadth, critical-domain or open-design trigger rather than picked to be safe, `haiku` only for mechanical work?
     - 1=Wrong agents/tiers, 2=Mostly appropriate, 3=Acceptable, 4=Optimal selection, 5=Perfect selection
  
  8. Phase Design (weight: 0.15)
     - Does EACH phase leave an independently verifiable milestone — a working application/service/solution that could be committed and run, PLUS the tests or other verification artifacts that let a reviewer judge it against the criteria listed for that phase?
     - Is EACH phase's `Reviewer model:` appropriate — never below the highest implementation tier used in that phase, and one tier above it unless the phase is small, uniform and mechanical?
     - Are phase sizes sensible — not one step per phase (review churn), not so many steps that a reviewer's findings force rewriting the whole phase? A single phase for the whole task is acceptable ONLY when no earlier point yields a working, verifiable state.
     - Does every checklist item and every rubric criterion in `## Acceptance Criteria` appear against at least one phase, and does each phase list only criteria genuinely due at that checkpoint rather than end-of-task criteria?
     - Is the task file free of threshold values, scores and judge configuration, which belong to the orchestrator?
     - 1=Phases are arbitrary cuts or leave a broken state, 2=Milestones partly hold or reviewer tiers are off, 3=Acceptable, 4=Well-designed milestones with justified reviewer tiers, 5=Every phase a clean, self-contained, correctly reviewed milestone
  

关键：提示词必须原样使用，不要添加任何内容，包括实施 Agent 的输出！！！

决策逻辑：

• PASS（评分 >= THRESHOLD）：分解完成，工作流结束——提升任务
• FAIL（评分 < THRESHOLD）：根据升级规则指定的层级重新启动阶段 4，并提供反馈（除非根据迭代裁量规则接受）
• 达到 MAX_ITERATIONS：无论评分如何都提升任务（记录警告）

---

等待 PASS 后再提升任务。

---

提升任务

目的： 将完善后的任务从 draft 文件夹移至 todo 文件夹。此文件移动由你自行执行——无需子 Agent、模型层级或 Judge。

所有阶段完成后：

1. 将任务文件从 draft 移至 todo：

   git mv <TASK_FILE> .specs/tasks/todo/
   # Fallback if git not available: mv <TASK_FILE> .specs/tasks/todo/
   

2. 不要移动 .specs/sub-tasks/<task-name>/。 子任务文件夹在规划时创建；任务文件在 draft/ → todo/ → in-progress/ → done/ 之间移动时，子任务文件夹保持原位，因此并行概览中记录的路径不会失效。

3. 如有需要，更新研究和分析文件中的任何引用

---

完成

所有已执行的阶段和评审器完成后：

1. 使用 git 工具暂存任务文件、.specs/sub-tasks/<task-name>/ 下的子任务文件、技能文件、分析文件，以及暂存区文件（仅暂存已创建的文件）
2. 总结工作流结果并输出给用户：

### Task Refined

| Property | Value |
|----------|-------|
| **Original File** | `<original TASK_FILE path>` |
| **Final Location** | `.specs/tasks/todo/<filename>` (ready for implementation) |
| **Title** | `<task title>` |
| **Type** | `<feature/bug/refactor/test/docs/chore/ci>` (from filename) |
| **Skill** | `<skill file path or "Skipped">` |
| **Skill Action** | `<Created new / Updated existing / Skipped>` |
| **Analysis** | `<analysis file path or "Skipped">` |
| **Scratchpad** | `<scratchpad file path>` |
| **Implementation Steps** | `<count or "N/A">` |
| **Phases** | `<count, each with its reviewer model, or "N/A">` |
| **Max Parallel Width** | `<peak concurrent steps, 1–5, or "N/A">` |
| **Sub-Task Files** | `.specs/sub-tasks/<task-name>/ — <count> files` or `"N/A"` |

### Configuration Used

| Setting | Value |
|---------|-------|
| **Target Quality** | {THRESHOLD}/5.0 |
| **Max Iterations** | {MAX_ITERATIONS} |
| **Active Stages** | {ACTIVE_STAGES as comma-separated list} |
| **Skipped Stages** | {SKIP_STAGES or stages not in ACTIVE_STAGES} |
| **Human Checkpoints** | Phase {HUMAN_IN_THE_LOOP_PHASES as comma-separated} |
| **Skip Judges** | {SKIP_JUDGES} |
| **Refine Mode** | {REFINE_MODE} |
| **Strict Mode** | {STRICT_MODE} |

### Quality Gates Summary

| Phase | Judge Score | Verdict |
|-------|-------------|---------|
| Phase 2a: Research | X.X/5.0 | ✅ PASS / ☑️ ACCEPTED / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 2b: Codebase Analysis | X.X/5.0 | ✅ PASS / ☑️ ACCEPTED / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 2c: Business Analysis | X.X/5.0 | ✅ PASS / ☑️ ACCEPTED / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 3: Architecture Synthesis | X.X/5.0 | ✅ PASS / ☑️ ACCEPTED / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 4: Decomposition | X.X/5.0 | ✅ PASS / ☑️ ACCEPTED / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |

**Threshold Used:** {THRESHOLD}/5.0 (or N/A if SKIP_JUDGES)

**Legend:**
- ✅ PASS - Score >= THRESHOLD
- ☑️ ACCEPTED - Score in `max(3.0, THRESHOLD - 1.0)..THRESHOLD` accepted per the [Iteration Discretion Rule](#iteration-discretion-rule) (outstanding nitpicks listed below the table)
- ⚠️ PROCEEDED (max iter) - Score < THRESHOLD but MAX_ITERATIONS reached, proceeded anyway
- ⏭️ SKIPPED - Stage not in ACTIVE_STAGES

**Outstanding Issues (accepted below THRESHOLD):**

{For each ☑️ ACCEPTED phase: phase, remaining nitpicks with priority — omit this block when no phase was accepted}

### Artifacts Generated

.claude/ └── skills/ └── / └── SKILL.md # 可复用的技能文档（如果运行了研究阶段）

.specs/ ├── tasks/ │ ├── draft/ # 草稿任务（来源——此任务现在为空） │ ├── todo/ │ │ └── ..md # 完整的任务规范（可供实施） │ ├── in-progress/ # 正在实施的任务（为空） │ └── done/ # 已完成的任务（为空） ├── sub-tasks/ │ └── / # 每个任务一个文件夹——任务文件移动时绝不会随之移动 │ ├── 01-.md # 每个实施步骤对应一个子任务文件 │ └── 02a-.md ├── analysis/ │ └── analysis-.md # 代码库影响分析（如果运行了代码库分析阶段） └── scratchpad/ └── .md # 架构思考暂存文件

### Task Status Management

Task status is managed by folder location:
- `draft/` - Tasks created but not yet refined
- `todo/` - Tasks ready for implementation
- `in-progress/` - Tasks currently being worked on
- `done/` - Completed tasks

### Next Steps

1. Review task: `.specs/tasks/todo/<filename>`
   - Edit the task file directly to make corrections
   - Add `//` comments to lines that need clarification or changes
   - Run `/plan` again with `--refine` to incorporate your feedback — it detects changes against git and propagates updates **top-to-bottom** (editing a section only affects sections below it, not above)
2. If everything is fine, begin implementation: `/implement` (will auto-select the task from todo/)

---

错误处理

阶段 Agent 失败（异常/崩溃）

如果任何阶段 Agent 意外失败：

1. 报告失败情况及 Agent 输出
2. 向用户提出有助于解决问题的澄清问题
3. 将问题和答案列表传给阶段 Agent，重新启动该 Agent 以解决问题

评审器返回 FAIL

如果任何评审器返回 FAIL（分数 < THRESHOLD）：

0. 首先应用迭代酌情处理规则：如果 score < 3.0（或 STRICT_MODE 为 true），则始终重试。如果 max(3.0, THRESHOLD - 1.0) <= score < THRESHOLD 且只剩下细枝末节，则审慎决定是否值得重试——如果接受，则将该阶段标记为 ☑️ ACCEPTED，在摘要中列出尚待处理的细枝末节，然后直接进入下一阶段，而不执行步骤 1–4；否则继续执行步骤 1
1. 自动重试：根据升级规则确定的层级，结合评审反馈重新启动阶段 Agent——该规则全面适用，包括其唯一的暂缓例外和 --model 的特殊处理。重试的附加依据：此处的触发条件 (1) 以 score < 3.0 为准（或评审意见表明模型误解了阶段要求）；在重新启动阶段所用的同一层级重新评审；在阶段摘要中说明层级决定
2. 人在环路检查：如果阶段属于 HUMAN_IN_THE_LOOP_PHASES，则在下一次评审重试之前触发人工检查点（实施重试之后、重新评审之前）
3. 达到 MAX_ITERATIONS 后：自动进入下一阶段（除非 --human-in-the-loop 包含此阶段，否则不要询问用户）
4. 在完成摘要中记录警告：⚠️ Phase X did not pass quality threshold (X.X/THRESHOLD) after MAX_ITERATIONS iterations

重试流程

Implementation → Judge FAIL → Implementation Retry → Judge Retry
                                                          ↓
                              PASS → Continue to next stage
                              FAIL → Repeat until MAX_ITERATIONS
                                          ↓
                              MAX_ITERATIONS reached → Proceed to next stage (with warning)

带有人在环路的重试流程

当阶段属于 HUMAN_IN_THE_LOOP_PHASES 时：

Implementation → Judge FAIL → Implementation Retry
                                    ↓
                    🔍 Human Checkpoint (optional feedback)
                                    ↓
                              Judge Retry
                                    ↓
                    PASS → Continue | FAIL → Repeat until MAX_ITERATIONS
                                                    ↓
                              MAX_ITERATIONS → 🔍 Final Human Checkpoint
                                                    ↓
                                    User confirms → Proceed to next stage