spec-driver-sync

name	spec-driver-sync
description	聚合功能规范为产品级活文档与 doc 上游事实源 — 将 specs/ 下的增量 spec 合并为 current-spec.md，并生成最小产品 Catalog
disable-model-invocation	false
allowed-tools	["Read","Write","Glob","Bash"]
model	sonnet
effort	medium

Wrapper Source Contract

• Canonical source: $PLUGIN_DIR/skills/spec-driver-sync/SKILL.md
• Source SHA256: 1169e22f5424f923a552c92d7f9078877467109c250c8c8f910efc65befbb1ea
• 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-sync/SKILL.md 的描述与正文，只额外叠加以下 Codex 运行时差异：

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

---

Spec Driver — 产品规范聚合

你是 Spec Driver 的产品规范聚合器。你的职责是将 specs/ 下的增量功能规范智能合并为产品级活文档 current-spec.md，并生成配套的 entity.yaml / catalog-index.yaml / scorecard-report / adoption-report，让产品事实层同时具备人读正文、机器可读目录、持续治理报告和本地 adoption 反馈四种形态。

触发方式

$spec-driver-sync

说明: 此命令无需参数，直接执行聚合流程。不接受 --resume、--rerun、--preset 等参数。

---

插件路径发现

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

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

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

---

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

在执行聚合前执行以下检查：

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
• 若存在 .specify/project-context.suggestions.yaml 或 .specify/project-context.suggestions.md，读取为 project_context_suggestions_block
• project_context_suggestions_block 仅作 advisory-only 建议，不覆盖用户显式输入或 project-context 正文
• 若 diagnostics 中包含 [参考路径缺失]，不中断流程，但必须在聚合报告中列为风险项
• 若无 project-context 文件，resolver 返回 projectContextBlock = "未配置"
• 若无 suggestions 文件，设置 project_context_suggestions_block = "无建议"

---

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

为降低“仅依赖本地 spec 聚合，遗漏外部标准/竞品变化”的风险，从 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

---

在线调研补充与硬门禁

执行条件: online_research_required = true

1. 编排器亲自执行在线调研（不委派子代理），执行 0..online_research_max_points 个调研点
2. 写入 .specify/research/sync-online-research.md（目录不存在则先创建）
3. 文件必须包含以下结构化字段（可用 YAML Front Matter 或等价键值区块）：
   • required: true
   • mode: sync
   • points_count: {N}
   • tools: [..]
   • queries: [..]
   • findings: [..]
   • impacts_on_product_spec: [..]
   • skip_reason: "{原因}"（仅当 points_count = 0 时必填）
4. 执行硬门禁：
   • points_count < online_research_min_points → BLOCKED
   • points_count > online_research_max_points → BLOCKED
   • points_count == 0 且 skip_reason 为空 → BLOCKED
5. BLOCKED 时暂停并提示：A) 补齐 sync-online-research.md 后继续 | B) 关闭在线调研要求后重试

执行条件（未要求在线调研）: online_research_required = false

• 输出: [sync] 在线调研补充 [已跳过 - 项目未要求在线调研]

---

前置检查

在执行聚合之前，检查 specs/ 目录状态：

if specs/ 目录不存在:
  输出错误提示:
  """
  [错误] 未找到 specs/ 目录。

  产品规范聚合需要 specs/ 目录下存在至少一个功能规范目录（如 specs/001-xxx/spec.md）。

  建议：
  - 使用 $spec-driver-feature <需求描述> 启动研发流程，生成首个功能规范
  - 或手动创建 specs/ 目录结构
  """
  终止流程

if specs/ 下无 NNN-* 功能目录或所有目录中均无 spec.md:
  输出错误提示:
  """
  [错误] specs/ 目录下未找到任何功能规范。

  聚合需要至少一个 specs/NNN-xxx/spec.md 文件。

  建议：
  - 使用 $spec-driver-feature <需求描述> 生成功能规范
  - 确认 spec 文件位于 specs/{编号}-{名称}/spec.md 路径下
  """
  终止流程

---

聚合流程

目的：将 specs/NNN-xxx/ 下的增量功能规范智能合并为 specs/products/<product>/current-spec.md 产品级活文档，并在其中产出一份可供 spec-driver-doc 消费的“对外文档摘要”；随后通过确定性 helper 生成 specs/products/<product>/_generated/entity.yaml、specs/products/_generated/catalog-index.yaml、specs/products/<product>/_generated/scorecard-report.md/.json、specs/products/_generated/scorecard-index.yaml 以及 specs/products/spec-driver/_generated/adoption-report.md/.json。

适用场景：

• 实现完成后同步产品全景文档
• 定期批量合并多个迭代的 spec
• 新成员 onboarding 前生成产品现状文档
• 为 spec-driver-doc 生成 README / 使用文档提供单一事实源

执行步骤

[1/4] 正在扫描功能规范...

1. 扫描 specs/ 下所有 NNN-* 功能目录
2. 读取 prompt_source[sync]（始终使用 Plugin 内置版本）

[2/4] 正在聚合产品规范...

3. 通过 Task tool 委派 sync 子代理：

Task(
  description: "聚合产品规范",
  prompt: "{sync 子代理 prompt}" + "{上下文注入: specs 目录列表、每个 spec.md 的完整内容}",
  subagent_type: "general-purpose",
  model: "opus"  // 聚合分析始终用 opus
)

上下文注入块（追加到 sync 子代理 prompt 末尾）：

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

**specs 目录**: {project_root}/specs/
**功能目录列表**: {NNN-xxx 目录名列表}
**产品映射文件**: {project_root}/specs/products/product-mapping.yaml（如存在）
**产品模板**: $PLUGIN_DIR/templates/product-spec-template.md
**已有产品文档**: {specs/products/ 下已有的产品目录列表（如有）}
**项目上下文**: {project_context_block}
**上下文建议（只读）**: {project_context_suggestions_block}
---

[3/4] 正在生成产品活文档...

1. 解析 sync 子代理返回：
   • 生成的产品数量和文件路径
   • 每个产品的聚合统计
   • 未分类 spec 列表（如有）

[4/4] 正在生成产品治理事实...

2. 执行确定性 helper 生成 Catalog：

node "$PLUGIN_DIR/scripts/generate-product-entity-catalog.mjs" --project-root "{project_root}" --json

3. 解析 helper 返回：

   • specs/products/<product>/_generated/entity.yaml
   • specs/products/_generated/catalog-index.yaml
   • 缺失 current-spec.md / quality report 时的 warning

4. 执行 workflow registry helper（若当前产品包含 spec-driver）：

node "$PLUGIN_DIR/scripts/generate-workflow-registry.mjs" --project-root "{project_root}" --json

5. 执行 product quality helper 生成产品级文档质量报告：

node "$PLUGIN_DIR/scripts/generate-product-quality-reports.mjs" --project-root "{project_root}" --json

6. 执行 scorecard helper 生成持续治理报告：

node "$PLUGIN_DIR/scripts/generate-product-scorecards.mjs" --project-root "{project_root}" --json

7. 执行 adoption helper 生成本地使用与卡点分析：

node "$PLUGIN_DIR/scripts/generate-adoption-insights.mjs" --project-root "{project_root}" --json

8. 执行 Project Context suggestions helper，把治理与 adoption 信号转成只读建议：

node "$PLUGIN_DIR/scripts/generate-project-context-suggestions.mjs" --project-root "{project_root}" --json

9. 解析 helper 返回：

   • specs/products/<product>/_generated/quality-report.md
   • specs/products/<product>/_generated/quality-report.json
   • specs/products/_generated/quality-report-index.yaml
   • specs/products/<product>/_generated/scorecard-report.md
   • specs/products/<product>/_generated/scorecard-report.json
   • specs/products/_generated/scorecard-index.yaml
   • specs/products/spec-driver/_generated/adoption-report.md
   • specs/products/spec-driver/_generated/adoption-report.json
   • .specify/project-context.suggestions.yaml
   • .specify/project-context.suggestions.md
   • 基于 quality-report / verification-report 的 warning

10. 输出聚合完成报告：

══════════════════════════════════════════
  Spec Driver - 产品规范聚合完成
══════════════════════════════════════════

扫描 spec 数: {总数}
产品数: {产品数}

聚合结果:
  ✅ {产品 A}: {N} 个 spec → specs/products/{产品 A}/current-spec.md
     功能: {M} 个活跃 FR, {K} 个已废弃
  ✅ {产品 B}: {N} 个 spec → specs/products/{产品 B}/current-spec.md
     功能: {M} 个活跃 FR

文档质量:
  {产品 A}: {完整章节数}/14 主章节完整
    待补充: {待补充章节名列表}
    对外文档摘要: {完整/部分/待补充}
  {产品 B}: {完整章节数}/14 主章节完整
    对外文档摘要: {完整/部分/待补充}

产品映射: specs/products/product-mapping.yaml
doc 上游摘要: 已写入 current-spec.md 的“对外文档摘要（供 spec-driver-doc 使用）”区块
实体目录:
  ✅ {产品 A}: specs/products/{产品 A}/_generated/entity.yaml
  ✅ {产品 B}: specs/products/{产品 B}/_generated/entity.yaml
Catalog 索引: specs/products/_generated/catalog-index.yaml
持续治理:
  ✅ {产品 A}: specs/products/{产品 A}/_generated/scorecard-report.md
  ✅ {产品 B}: specs/products/{产品 B}/_generated/scorecard-report.md
Scorecard 索引: specs/products/_generated/scorecard-index.yaml
本地反馈:
  ✅ spec-driver: specs/products/spec-driver/_generated/adoption-report.md
  数据源: .specify/runs/*.jsonl（本地，不默认提交）
在线调研证据: {if online_research_required: ".specify/research/sync-online-research.md"}{if not online_research_required: "跳过（项目未要求）"}
══════════════════════════════════════════

Prompt 来源

prompt_source[sync] = "$PLUGIN_DIR/agents/sync.md"  // 始终使用内置版本