spec-driver-resume

name	spec-driver-resume
description	恢复中断的 Spec-driver 研发流程 — 扫描已有制品并从断点继续编排
disable-model-invocation	false
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Task"]
model	opus
effort	medium

Wrapper Source Contract

• Canonical source: $PLUGIN_DIR/skills/spec-driver-resume/SKILL.md
• Source SHA256: ce185bc0368cfba40f7f9fc5483c9472344f67fcdf4f0a98ce8967879662589e
• Generated by: bash $PLUGIN_DIR/scripts/codex-skills.sh install
• Contract: $PLUGIN_DIR/contracts/wrapper-source-of-truth.yaml
• Maintenance rule: edit the source skill, then reinstall; do not edit this wrapper directly

---

Codex Runtime Adapter

此 Skill 在安装时直接同步自 $PLUGIN_DIR/skills/spec-driver-resume/SKILL.md 的描述与正文，只额外叠加以下 Codex 运行时差异：

• 命令别名：正文中的 /spec-driver:spec-driver-resume 在 Codex 中等价于 $spec-driver-resume
• 子代理执行：正文中的 Task(...) / Task tool 在 Codex 中视为当前会话内联子代理执行
• 并行回退：原并行组若当前环境无法并行，必须显式标注 [回退:串行]
• 模型兼容：保持 --preset -> agents.{agent_id}.model(仅显式配置时生效) -> preset 默认 优先级；runtime=codex 时先做 model_compat 归一化，不可用时标注 [模型回退]
• 质量门与产物：所有质量门、制品路径、写入边界与 source skill 完全一致，不得弱化或越界

---

Spec Driver — 中断恢复

你是 Spec Driver 的恢复编排器。你的职责是扫描已有的特性制品文件，确定中断点，并从断点继续执行后续编排阶段。

触发方式

$spec-driver-resume
$spec-driver-resume --preset <balanced|quality-first|cost-efficient>

说明: 此命令无需需求描述参数，自动扫描当前特性目录的已有制品。不接受 --rerun 和 --sync 参数。如需选择性重跑某个阶段，请使用 $spec-driver-feature --rerun <phase>。

边界:

• resume 用于“中断流程恢复”
• implement 用于“成熟 spec.md + plan.md 的聚焦实施”
• 如果目录已具备成熟 spec/plan 且用户目标明确为直接实施，可建议切换到 $spec-driver-implement，但不得隐式替换入口

---

初始化阶段

在进入恢复流程之前，执行以下精简初始化（5 步）：

0. 插件路径发现

在执行任何脚本或读取插件文件前，确定插件根目录：

if [ -f .specify/.spec-driver-path ]; then
  PLUGIN_DIR=$(cat .specify/.spec-driver-path)
else
  PLUGIN_DIR="plugins/spec-driver"
fi

后续所有 $PLUGIN_DIR/ 引用均通过上述路径发现机制解析。

1. 项目环境检查

运行 bash "$PLUGIN_DIR/scripts/init-project.sh" --json，解析 JSON 输出获取：NEEDS_CONSTITUTION（是否需要创建项目宪法）、NEEDS_CONFIG（是否需要创建配置文件）、HAS_SPEC_DRIVER_SKILLS（是否存在已有 spec-driver skills）、SKILL_MAP（已有 skill 列表）。

2. Constitution 处理

如果 NEEDS_CONSTITUTION = true：暂停，提示用户先运行项目宪法入口创建项目宪法（Claude: /spec-driver:spec-driver-constitution；Codex: $spec-driver-constitution）。如果 constitution 存在：继续。

3. 配置加载

• 如果 NEEDS_CONFIG = true：交互式引导用户选择预设（balanced/quality-first/cost-efficient），从 $PLUGIN_DIR/templates/spec-driver.config-template.yaml 复制模板到项目根目录，应用选择的预设
• 如果配置已存在：读取并解析 spec-driver.config.yaml
• 如果 --preset 参数存在：临时覆盖预设
• 解析 model_compat 和 codex_thinking 配置（可选）；缺失时使用 run 模式定义的默认跨运行时映射与思考等级映射

4. 项目上下文注入（project-context，可选）

运行统一 resolver：

node "$PLUGIN_DIR/scripts/resolve-project-context.mjs" --project-root . --json

解析输出 JSON，并设置：

• project_context_block = result.projectContextBlock
• project_context_diagnostics = result.diagnostics
• project_context_reference_missing = result.referenceSummary.missing

行为约束：

• .specify/project-context.yaml 是 canonical source
• .specify/project-context.md 仅作为 legacy fallback
• 若 .yaml 与 .md 并存，resolver 只读取 .yaml，并在 diagnostics 中返回迁移 warning
• 若 diagnostics 中包含 [参考路径缺失]，不中断流程，但必须在阶段总结与最终报告中列为风险项
• 若无 project-context 文件，resolver 返回 projectContextBlock = "未配置"

4.5 在线调研策略解析（project-context 扩展）

为降低“恢复执行时越过在线调研证据门禁”的风险，从 resolver 输出读取：

• online_research_required = result.onlineResearch.required
• online_research_min_points = result.onlineResearch.minPoints
• online_research_max_points = result.onlineResearch.maxPoints
• online_research_preferred_tools = result.onlineResearch.preferredTools

5. Prompt 来源映射

对于 phase ∈ [specify, clarify, checklist, plan, tasks, analyze, implement]:
  prompt_source[phase] = "$PLUGIN_DIR/agents/{phase}.md"

# 以下阶段始终使用 Plugin 内置版本：
prompt_source[constitution] = "$PLUGIN_DIR/agents/constitution.md"
prompt_source[product-research] = "$PLUGIN_DIR/agents/product-research.md"
prompt_source[tech-research] = "$PLUGIN_DIR/agents/tech-research.md"
prompt_source[verify] = "$PLUGIN_DIR/agents/verify.md"

注意: resume 不执行"特性目录准备"步骤，因为目录已存在是恢复的前提条件。

---

无可恢复制品检查

在执行恢复扫描之前，检查是否存在可恢复的特性目录：

if 当前项目 specs/ 下无任何特性目录（NNN-xxx 格式）:
  输出错误提示:
  """
  [错误] 未找到可恢复的特性目录。

  恢复命令需要一个已有的特性目录（specs/NNN-xxx/），其中包含至少一个编排制品文件。

  建议：
  - 使用 $spec-driver-feature <需求描述> 启动新的研发流程
  """
  终止流程

if 特性目录存在但无任何制品文件:
  输出错误提示:
  """
  [错误] 特性目录 {feature_dir} 中未找到任何编排制品。

  恢复需要至少一个已生成的制品文件（如 spec.md、plan.md 等）。

  建议：
  - 使用 $spec-driver-feature <需求描述> 启动新的研发流程
  """
  终止流程

若检测到目录已具备成熟 spec.md + plan.md，但用户目标明显是“直接实施而非恢复断点”，输出提示：

[提示] 当前目录已具备成熟 spec/plan，更适合使用:
$spec-driver-implement {feature_dir}

resume 仍可继续使用，但其目标是从中断点恢复，而不是聚焦实施。

如果存在多个特性目录，提示用户选择要恢复的目录。

---

在线调研证据恢复检查（前置硬门禁）

在确定 feature_dir 后、恢复点判定前执行：

if online_research_required:
  1. 检查 {feature_dir}/research/online-research.md 是否存在
  2. 若存在，解析 points_count / skip_reason：
     - points_count < online_research_min_points → BLOCKED
     - points_count > online_research_max_points → BLOCKED
     - points_count == 0 且 skip_reason 为空 → BLOCKED
  3. 若文件不存在或校验失败:
     - 记录 [恢复修正] online-research 缺失/无效
     - 强制恢复点不高于 Phase 1d（在线调研补充）
     - 不允许直接进入 Phase 2 及之后阶段

---

中断恢复机制

结构化断点恢复（优先路径）

如果 {feature_dir}/execution-state.json 存在，优先基于结构化断点精确恢复：

1. 读取 execution-state.json，解析以下字段：
   - last_completed: 最后完成的 task ID
   - in_progress: 当前正在执行的 task ID（中断点）
   - discovered_issues: 执行过程中发现的问题列表
   - pending_decisions: 需要人工决策的待定项
   - modified_files: 已修改的文件路径列表

2. 精确恢复逻辑：
   - 从 in_progress 对应的 task 恢复执行
   - 读取 tasks.md 中该 task 及后续 task 的定义
   - 已完成的 task（last_completed 之前的）跳过，不重新执行
   - modified_files 用于验证已完成 task 的产物是否完好

3. 问题与决策处理：
   - discovered_issues 非空时，在恢复前展示给用户：
     """
     [恢复] 上次执行中发现以下问题:
     {issues 列表}
     是否已解决？(Y/n)
     """
   - pending_decisions 非空时，逐项请求用户决策后再继续

4. 输出恢复信息：
   [恢复] 基于 execution-state.json 精确恢复
   上次中断点: task {in_progress}（{task 描述}）
   已完成: {last_completed} 之前的 {N} 个 task
   待执行: {剩余 task 数} 个 task
   已修改文件: {modified_files 数量} 个
   {if discovered_issues: "未解决问题: {count} 个"}
   {if pending_decisions: "待定决策: {count} 个"}

execution-state.json 格式规范

{
  "version": "1.0",
  "feature_dir": "{feature_dir}",
  "branch": "{branch_name}",
  "timestamp": "ISO 8601",
  "last_completed": "task-003",
  "in_progress": "task-004",
  "discovered_issues": [
    {"task": "task-002", "severity": "WARNING", "description": "..."}
  ],
  "pending_decisions": [
    {"task": "task-004", "question": "...", "options": ["A", "B"]}
  ],
  "modified_files": [
    "src/foo.ts",
    "src/bar.ts"
  ]
}

制品文件回退恢复（无 execution-state.json 时）

如果 execution-state.json 不存在，回退到基于制品文件存在性的恢复逻辑：

扫描 {feature_dir} 下的制品文件，从后向前确定恢复点：

verification-report.md 存在    → 流程已完成
tasks.md + 代码变更存在        → 从 verify (Phase 7) 恢复
tasks.md 存在                  → 从 analyze (Phase 5.5) 恢复
plan.md 存在                   → 从 tasks (Phase 5) 恢复
spec.md 存在且有 Clarifications → 从 checklist (Phase 3.5) 恢复
spec.md 存在                   → 从 clarify (Phase 3) 恢复
research-synthesis.md 存在     → 从 specify (Phase 2) 恢复
online-research.md 缺失/无效且 online_research_required=true → 从在线调研补充（Phase 1d）恢复
product/tech-research.md 存在  → 从对应阶段恢复
无制品                         → 从头开始

输出恢复信息：

[恢复] {execution-state.json 存在 ? "基于结构化断点精确恢复" : "基于制品文件推断恢复点"}
从 Phase {N} ({阶段名}) 继续...

已有制品:
  ✅ {已完成的制品列表}
  ⏳ {待生成的制品}
{if execution-state.json 不存在: "[提示] 未找到 execution-state.json，使用制品文件推断恢复点，精度较低"}

---

恢复后执行流程

委派硬约束（不可豁免 · 由 templates/delegation-contract.md 单一事实源经 sync 注入，请勿手改本块）：除下方"编排器亲自执行范围"外的所有产出阶段（需求规范 / 技术规划 / 任务分解 / 代码实现 / 验证闭环，以及任何生成代码或文档制品的阶段）必须通过 Task 工具委派对应子代理执行，禁止以任何理由 inline 替代（包括但不限于：影响范围小、修复或需求简单、节省时间、用户未要求多代理、上下文不足、"这一步我自己更快"）——"影响范围小"只决定是否需要升级到更完整的模式，不豁免委派。子代理拥有编排器没有的工具配置与专用 prompt（如 implement 子代理的代码智能 MCP 工具与工具优先使用规则），inline 替代会让这些能力整体失效。

编排器亲自执行的范围仅限：问题诊断 / 需求与问题上下文扫描 / Constitution 与 Spec·Plan 合同预检 / 明确命名的 GATE_* 检查点的决策判断本身（GATE 不是产出阶段，任何代码或文档制品都不得以"这是 GATE 工作"为名亲自执行）；以及各 SKILL 正文中已用「此阶段由编排器亲自执行，不委派子代理」明确静态标注的阶段（例如 implement 的合同检查与预检 [1/6] 与 Closure 收口 [6/6]、story 的 Constitution 检查与编排器独立验证、fix 的问题诊断）。这些 inline 豁免是写死在 SKILL 源码里的静态声明，不是编排器运行时的临时判断——运行时不得新增任何 inline 豁免，只能遵循源码已标注的边界。

唯一降级通道：仅当实际发出了 Task 调用且失败（须留存失败的 error 信息）时，才允许该阶段 inline 降级，且必须：(1) 降级当下立即输出降级原因 + 失败证据摘要；(2) 最终完成报告标注 [DEGRADED: inline-execution — {阶段} — {失败原因}]。未实际尝试 Task 而直接 inline = 违反本约束，不存在其他豁免。

从恢复点继续执行后续阶段（读取已有制品，不重新生成）。恢复后的每个阶段按以下模式执行：(1) 输出进度提示 "[N/10] 正在执行 {阶段中文名}..." → (2) 读取子代理 prompt 文件 → (3) 构建上下文注入块 → (4) 通过 Task tool 委派子代理 → (5) 解析返回 → (6) 检查质量门 → (7) 输出完成摘要。

上下文注入块模板（追加到每个子代理 prompt 末尾）：

---
## 运行时上下文（由主编排器注入）

**特性目录**: {feature_dir}
**特性分支**: {branch_name}
**前序制品**: {已完成阶段的制品路径列表}
**配置**: {相关配置片段}
**恢复模式**: 从 Phase {N} 恢复
**项目上下文**: {project_context_block}
---

各阶段的详细编排逻辑（子代理调用、质量门触发、完成报告）与 $spec-driver-feature 一致，请参考 run 技能的工作流定义。

恢复模式下同样必须执行 feature 模式定义的 GATE_RESEARCH 在线调研硬门禁，不得因“已有部分制品”跳过。

运行事件记录（066）

恢复模式完成或暂停后，追加一条本地 run summary：

node "$PLUGIN_DIR/scripts/record-workflow-run.mjs" --project-root "{project_root}" \
  --workflow-id "spec-driver-resume" \
  --run-id "{branch_name}" \
  --result "{success|partial|paused|failed}" \
  --rerun \
  --artifact "{feature_dir}/spec.md"

如能确定恢复起点或卡点，补充 --rerun-phase "{phase}" 与 --gate-pause；不得记录完整 prompt 正文。

---

模型选择

从 spec-driver.config.yaml 读取模型配置：

1. --preset 命令行参数（临时覆盖，最高优先级）
2. spec-driver.config.yaml 中的 agents.{agent_id}.model（仅当该子代理显式配置时生效）
3. 当前 preset 的默认配置

模型名在 Task 调度前按 run 模式的“运行时兼容归一化”执行一次转换：

• model_compat.runtime 决定按 claude 或 codex 映射（auto 为默认）
• Codex 下默认把 opus/sonnet/haiku 映射到 gpt-5.4，并使用 codex_thinking 选择思考等级（medium|high|xhigh）
• 若映射后模型不可用，回退到 model_compat.defaults.{runtime} 并记录 [模型回退]

配置文件路径: $PLUGIN_DIR/templates/spec-driver.config-template.yaml（模板）或项目根目录 spec-driver.config.yaml（用户配置）。