specify

Specify

你正在运行 agent-toolkit 流水线的 specify 阶段，即 Spine 第 2 阶段。你的任务是在进入 plan 和 implement 阶段之前，敲定所有重要的行为与契约决策，同时为本地、可逆且符合惯例的选择保留实现自由度。任何尚未解决的重要决策都会在 implement 阶段被退回。

如果 manifest.class = epic： 请遵循本文件底部的 Epic Specify 路径。Epic specify 仅限于跨领域契约，不涉及每个子项的实现细节。

运行辅助脚本

此技能将辅助脚本打包在自身的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设置为此技能的绝对路径——路径显示在本文件末尾的 此技能的基础目录 处——然后从项目根目录运行脚本（脚本会操作项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。切勿引用 packages/build/——该路径仅存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

采取与 architect 相同的质询立场。重新阅读 references/challenge-protocol.md、references/adversarial-review.md 和 references/engineering-fundamentals.md。针对每项由用户决定的重要事项，推荐最佳方案。仅就公共契约、安全策略、兼容性／迁移、明确的接口边界、不可逆或成本高昂的承诺，以及重要的架构或运维权衡询问用户。对于本地、私有且可逆的选择，自动采用惯常且符合习惯用法的方案；对于确实需要用户决定的事项，沉默绝不代表接受。

前置条件

加载 manifest.yaml。验证：

• phase 为 specify（即 architect 审批已通过）。
• approvals.specify 为 pending。
• architecture.md 存在且有效性检查已通过。
• 如果 class = epic： 跳转到下方的 Epic Specify 部分。

如果前置条件不满足，告知用户问题所在，以及应改为运行哪个步骤。

完整加载 architecture.md。它是你的规范基线。

如果设置了 manifest.language，请使用 idioms 技能加载对应的语言包，以获取界面设计指导。如果未安装匹配的语言包，请说明这一点，并遵循仓库的语言惯例和工具，不要假设存在该语言包的指导。

阶段 1：接口清单

访谈之前，从 architecture.md 中提取：

• 所有新增或修改的接口边界
• 决策中提及的所有接口
• 范围内的所有重构

将它们列为审查范围。仅当选择触及重要性边界时才提问。配置或可观测性细节只有在定义公共／运维契约、安全策略、成本高昂的承诺或重要权衡时，才由用户决定。对于本地、私有且可逆的细节，遵循仓库惯例和习惯用法。

阶段 2：分批确认决策

以简洁的编号批次开展系统性确认访谈。规则：

• 每项都要说明一个由用户决定的重要问题、Agent 的建议、建议理由，以及有意义的替代方案。
• 要求用户对每项明确回应：accept、选择一项替代方案，或给出决定。用户可以按项目编号简洁回复。
• 缺失、含糊或不明确的答案仍标记为 unresolved。只针对未解决的项目跟进；绝不从沉默中推断为接受。
• 仅当答案含糊、引入代码异味或与 idioms pack 冲突时才提出质疑。如果用户推翻质疑，应记录建议、用户决定，以及用户提供的理由。
• 所有由用户决定的重要项目都得到明确确认后即停止。对于遵循仓库约定和 idioms 的本地／私有／可逆细节，不要创建问题或决策台账条目。

检查以下类别，但仅在选择跨越重要性边界时提问：

1. 接口定义 — 精确签名、类型、错误条件、边界情况
2. 数据契约 — 字段名称、类型、必填与可选项、验证规则
3. 错误处理 — architecture.md 中提到的每种故障模式及其处理方式
4. 并发／顺序 — 如果变更涉及并发代码，则确认顺序保证
5. 配置 — 新增配置项、默认值及其验证
6. 迁移／兼容性 — 是否属于破坏性变更？是否需要向后兼容？
7. 测试场景 — 每个确定的接口边界都必须覆盖哪些场景？
8. 可观测性细节 — 精确的指标名称、跟踪跨度、日志级别
9. 重构范围 — 对每项获批重构，明确具体文件／模块及变更内容

工作过程中维护确认台账。每个已解决项目都需要决策 ID、建议、用户明确回复，以及 confirmed 状态。你需要将其用于 decisions.md。

阶段 3：有界的假设式实现审查

确认完成后，严格执行一次 references/adversarial-review.md 中的 SV-* 周期。由一位全新的实现者兼审查者，对 architecture.md、决策草案及相关仓库上下文进行一次全面、只读的假设式实现审查。适用时，深入审查数据／状态、数据结构、接口／特征、错误、安全性、可观测性、简洁性、可维护性及 idioms。不得仅因实现仍有自由度，就规定私有控制流。

将所有发现合并为一个批次。每项发现都须包含稳定的 SV-NNN ID、严重程度 blocker|major、类别 correctness|security|simplicity|maintainability|idioms、证据、具体影响及具体替代方案。不要输出低严重程度的发现或强制要求的 N/A 行。

一次性修复整个批次。仅当修复跨越重要性边界时才征求用户确认；本地／私有／可逆且符合惯例的选择应自动确定。然后启动一位全新的验证者，仅检查原有 ID。验证不得重复发现问题、扩大范围或引入新的低／高严重程度发现。由修复导致的阻断级回归是唯一允许新增 ID 的例外：使用 --regression 记录，在同一有限范围内修正，并在这次有针对性的复验中通过 --regression-resolution 关闭。如果任何 ID 仍未解决，或关闭问题需要广泛调查，则停止，不得延长周期。

使用 review-log.mjs，在当前清单的 specify-N 周期下记录发现与验证。审计者使用共享策略规定的结构化 --finding JSON；验证者必须对每项原始发现提供一个 --resolution SV-NNN=resolved|unresolved。即使审计者批准且未发现问题，仍须由一位独立的验证者进行验证：

node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase specify --cycle specify-N \
  --role auditor --reviewer "<fresh label>" --verdict approved
node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase specify --cycle specify-N \
  --role verifier --reviewer "<distinct fresh label>" --verdict approved

阶段 4：编写 decisions.md

根据 references/templates/decisions.md.tmpl 填写 decisions.md。包括：

• 在决策正文之前列出完整的确认记录
• 所有接口变更（完整且准确）
• 完整的决策日志（批次项 → 建议 → 明确决议、质疑、推翻）
• 范围受限的 SV-* 审查周期及重点验证结果
• 架构协调说明（在 architecture.md 中发现的任何差异及其修复方式）

写入：.changes/active/<id>/decisions.md

如果访谈期间发现了新的 CONTEXT.md 目标，请更新 manifest.yaml context_targets。

阶段 5：协调 architecture.md

对照 decisions.md 检查 architecture.md。如果任何决策变更、澄清或与架构决策相矛盾：

• 更新 architecture.md，以反映经过细化的理解。
• 在 decisions.md 的“Architecture Reconciliation”下记录协调情况。

阶段 6：审批

展示确认记录、已敲定的接口和演练运行结果。请用户确认该记录准确体现了他们的选择。然后询问：

“每一项由用户决定的重要事项都已明确确认，且范围受限的规格审查没有未解决的阻塞问题。你是否批准本次 specify 审批？（这将进入 plan 阶段。）”

批准后：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval specify --approve

告知用户：接下来运行 plan。

处理来自 implement 的退回

如果你正在运行 specify，是因为 implement 退回了任务（而非全新会话），请将其视为修订会话：

• 从 manifest.yaml 加载退回记录。
• 仅处理退回记录中指出的问题。
• 运行当前的 specify-N 正式周期，且仅限于该记录的问题；不要重新开始广泛的探索。如果发现新的重要决策，请确认该决策，并将其记录在退回记录下，而不是扩大周期范围。
• 使用新的决议更新 decisions.md。
• 如有需要，协调 architecture.md。
• 在 manifest.yaml 中，将最新退回记录的 resolution 设为实际决策。不要留空，也不要使用 pending 等占位符。
• 仅重新审批已失效的审批。影响 specify 的退回需要重新执行 specify，然后进入 plan；仅影响 plan 的退回只需重新执行 plan。
• 确认清单中建议的下一阶段，然后再告知用户恢复实施。

参考文件

• references/challenge-protocol.md
• references/adversarial-review.md — 范围受限的 SV-* 审查周期和发现项架构
• references/seam-and-test-taxonomy.md
• references/manifest-schema.md — 退回类型和史诗任务模型
• references/firm-change-protocol.md — 必须更改固定接口时使用
• references/templates/decisions.md.tmpl
• idioms 技能 — 匹配的接口设计指南

---

史诗任务 SPECIFY 路径 — 类别：epic

史诗任务 specify 仅限于跨子任务契约——即多个子任务必须共同遵守的内容。不要深入讨论每个子任务的实现细节；这些内容将在各子任务自己的 specify 会话中处理。

“跨领域”是什么意思

跨领域关注点是指两个或更多子任务都会涉及或依赖的内容。例如：

• 子任务 A 生成、子任务 B 消费的共享消息格式或线路协议
• 多个子任务都会引用的共享数据结构（领域类型、错误枚举）
• 所有子任务都会读取的配置架构
• 组件之间的事件或通知契约
• 所有子任务必须保持一致的错误处理惯例

如果某个契约或接口只属于一个子任务，则不属于跨领域内容——在此处跳过，由该子任务的 specify 处理。

Epic Specify 阶段

阶段 E1：识别横切事项

从 architecture.md 中提取：

• “Proposed Child Changes”部分中标记为供多个子项共用的每个接口
• 多个子项都会跨越的每个接缝
• 明确列出的任何“cross-cutting concerns to resolve in specify”部分

将它们列出。这些是本次会话唯一涉及的内容。

阶段 E2：批量决策（仅限横切事项）

严格限定范围，遵循标准重要性边界和确认纪律。只询问关于共享公共契约、安全策略、兼容性／迁移、明确接缝、高成本承诺，或会对多个子项产生实质影响的架构／运维权衡的问题。对于局部／私有／可逆的常规选择，自动决定。检查：

• 每个共享接口的确切类型签名、消息格式和错误类型
• 每个共享契约由哪个子项负责（编写），哪些子项使用
• 版本控制／演进规则：在 Epic 进行期间，共享接口能否变更而不破坏其他子项？
• 顺序约束：如果子项 A 产出的接口由子项 B 使用，A 的接口是否必须在 B 开始 specify 前完成？

阶段 E3：有界的跨子项审查

对所有跨子项契约，恰好执行一个 SV-* 周期。由一位新的评审者进行一次全面的“假设将据此实现”审查，覆盖每个子项边界及所有适用的审查维度。提交一份汇总的 blocker／major 问题批次，使用稳定的 SV-NNN ID，并包含规定的类别、证据、具体影响和替代方案。仅修正一次，且只就重要决策询问用户。由一位新的验证者仅检查原始 ID；最多允许一次有针对性的修正／重新验证，不得重复发现问题，也不得提出新的 low／major 发现。将此周期记录在 Dry-Run Findings 下。如果仍有原始 blocker，不要拆分 Epic。

按照标准流程，通过 review-log.mjs 在当前 specify-N 阶段记录审计者和验证者。

阶段 E4：编写 Epic 的 decisions.md

编写 decisions.md，涵盖：

• 所有横切接口定义（完整且精确）
• 所有权映射：每个共享接口由哪个子项编写
• 子项之间的顺序约束
• Dry-run 发现及其解决方案
• 本文档明确的 OUT OF SCOPE 内容（留待各子项的 specify 阶段处理）

写入：.changes/active/<id>/decisions.md

阶段 E5：批准 + 自动拆分（由你执行，而非用户）

首先，批准 specify：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval specify --approve

然后立即自动运行 epic-split——不要要求用户手动执行。读取 architecture.md 中的“Proposed Child Changes”部分，以及 decisions.md 中关于顺序／所有权的决策，构造 children JSON，并运行：

node "$SKILL_DIR/scripts/epic-split.mjs" --epic <id> --children '[
  {
    "title": "Child 1 title",
    "class": "feature",
    "language": "rust",
    "notes": "Brief scope: what this child owns, what interfaces it produces, what it depends on from sibling children. 2-3 sentences."
  },
  {
    "title": "Child 2 title",
    "class": "feature",
    "language": "rust",
    "notes": "..."
  }
]'

每个子项都会获得一个 architect-seed.md，其中包含该子项的备注，并可隐式访问 Epic 的架构和决策，作为父级上下文。

epic-split 完成后，告知用户：

"Epic 已拆分。已创建 [N] 个子项变更。每个子项的 architect 会话都会继承此 Epic 的架构和决策，作为父级上下文。

按深度优先方式推进：先将一个子项完整推进至 archive-ready（architect → specify → plan → implement → archive-ready），再开始下一个。 不要单独归档已完成的子项：Epic 会保留所有已达到 archive-ready 的子项，并在所有子项都准备就绪后，通过一次协调且经过验证的操作统一归档。

建议顺序（基于依赖关系）：

1. [child-id-1] — [标题]（无依赖，从此项开始）
2. [child-id-2] — [标题]（依赖子项 1 的 X 接口） ...

独立的子项可以并行推进，但每个子项仍须从头到尾完成整个流程。准备好后，在第一个子项上运行 architect。随时可以询问“接下来做什么”以查看进度。"