mcpField
C
contract-builder

contract-builder

github.com/magebyte-zeroAgent 工作流87658 次安装3 天前更新
代码仓库

关于 contract-builder

将规划产物整理为单一执行契约的 Agent 技能，面向处理现有 legacy 变更的工作流。它映射需求、设计和任务，并要求契约经过批准后才能进入构建。

主要功能

  1. 01汇总意图、范围与约束
  2. 02映射需求、场景及测试义务
  3. 03按任务组整理执行批次
  4. 04检查需求覆盖和跨批依赖
  5. 05支持 legacy Hotfix 精简契约
  6. 06批准后记录状态并推进阶段

适用场景

  1. 01为现有 legacy 变更生成执行契约
  2. 02检查规格需求是否落实到批次和测试
  3. 03在范围或设计变更后判断契约是否过期

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/magebyte-zero/spec-superflow --skill contract-builder

安装后在 Claude Code 中输入/contract-builder确认已加载。

详细介绍

合同构建器

捆绑运行时

执行下方 CLI 命令行之前，请将开头的 SSF 替换为 node "<plugin-root>/scripts/spec-superflow.mjs"；<plugin-root> 是本文件上两级目录的绝对路径。切勿直接运行 SSF，也不要调用 PATH 中的 ssf。

仅用于旧版兼容：新的计划变更使用 proposal.md + tasks.md，并运行 SSF workflow start --path planned。不要为它们生成合同，也不要再请求第二次批准。只有现有的旧版变更才需要阅读其余说明。

将规划资料转换为单一执行交接文档：execution-contract.md。使用 SSF runtime asset read templates/execution-contract.md 加载基准模板。

生成前请阅读：.spec-superflow.yaml（尤其是 dp_0_decisions）、 proposal.md、specs/、design.md、tasks.md，然后使用 SSF runtime asset read docs/artifact-contract.md 加载 docs/artifact-contract.md。

在编写合同前进入 bridging；如果已处于该状态，则跳过状态转换。遵守已配置的 specs/design 省略规则。引用需求 ID 和任务 ID，而不是复制其完整文本；保留范围、义务、测试和审查政策。

产物语言

从 dp_0_decisions 中读取 artifact_language=<concrete-language>。生成 execution-contract.md 时，使用该解析值所指定的语言，并与已批准的规划资料语言保持一致。必须原样保留架构关键字和代码标识符；语言一致性要求适用于说明性文字和标题。如果具体产物语言缺失或仍为 auto，请在编写合同前返回 workflow-start，而不要猜测或默认使用英语。

产物映射

来源提取内容
proposal.md → ## Why + ## What Changes意图锁定（问题 + 范围）
proposal.md → ## Scope > ### Out of Scope范围界定
specs/ → 每个 ### Requirement:已批准需求、场景、测试义务
design.md → ## Decisions架构、接口、依赖约束
tasks.md → 编号任务组执行批次、完成定义、审查时机

交叉核对：需求覆盖

定稿前：

  1. 列出 specs/ 中的每一项 SHALL/MUST
  2. 验证每一项都体现在已批准行为中、有对应的测试义务，并至少出现在一个批次中
  3. 在升级规则中标记未映射的需求
  4. 记录跨批次依赖

合同结构

必须清楚说明：已批准行为、范围外事项、约束、批次、测试义务、审查关卡，以及必须退回规划阶段的条件。优先精简，不要重复规划细节。

批准模型（DP-3）

草拟后：总结交接规则，指出歧义并标记未映射的需求。若已有明确批准涵盖此合同，则沿用；否则，请求一次批准，并同时列出仍待决定的规划事项和默认的 Native 执行选项。仅批准范围，并不代表批准尚未展示的合同。切勿要求用户对同一份未变更的合同重复批准。批准后：

SSF state set <change-dir> dp_3_result "approved: <summary>"
SSF state set <change-dir> dp_3_timestamp now
SSF state rebuild <change-dir>

批准后推进状态：

SSF state transition <change-dir> approved-for-build

DP-3 是硬性关卡——没有这份记录，不得实施。

过期合同检测

出现以下情况时刷新合同：proposal 中的范围发生变化、specs 中的需求发生变化、design 中的约束发生变化、tasks 中的批次发生重大变化，或合同不再符合意图。

Hotfix 模式

仅为旧版 Hotfix 生成最简合同：意图锁定（一句话）、任务列表（编号）、批准关卡（DP-3）。跳过范围界定、构建规则、审查关卡和测试证据。仍需获得 DP-3 批准。快速直接执行和直接事件 Hotfix 不会调用此技能；它们使用已签署的回执，并以 test_result: pass 结束。

防护规则

  • 如仍有歧义，不要继续实施
  • 不要代替用户批准合同
  • 不要因为规划文档看起来完整就跳过合同
  • 标记未映射的需求；不要默默舍弃

生成后

在上述 DP-3 序列中，已批准的合同会在受保护的转换前由 state rebuild 记录。这适用于 Full 和旧版 Hotfix。不要仅为掩盖未经批准的内容更改而刷新哈希值。

异常处理

  • 解析失败：报告具体文件和章节。建议重新运行 spec-writer。
  • 缺少文件：列出所有缺失的制品。转回 spec-writer。
  • 用户中断：恢复时重新读取所有制品；通过内容比较检查合同是否过时。
  • 验证失败：在升级规则和审批摘要中标记未映射的需求。

评论

支持 Markdown