mcpField
C
contract-builder

contract-builder

github.com/magebyte-zeroAgent workflows87658 installsUpdated 2d ago
Repository

About contract-builder

An Agent skill that turns planning artifacts into a single execution contract for workflows handling existing legacy changes. It maps requirements, design, and tasks, and requires contract approval before build work proceeds.

Key features

  1. 01Consolidates intent, scope, and constraints
  2. 02Maps requirements, scenarios, and test obligations
  3. 03Organizes execution batches from task groups
  4. 04Checks requirement coverage and cross-batch dependencies
  5. 05Supports minimal contracts for legacy Hotfixes
  6. 06Records approval and advances workflow state

Use cases

  1. 01Generate an execution contract for an existing legacy change
  2. 02Check whether spec requirements map to batches and tests
  3. 03Assess contract staleness after scope or design changes

Install

Copy the command and run it in a terminal.

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

After installing, type/contract-builderin Claude Code to confirm it loaded.

Details

From the project README

Contract Builder

Bundled runtime

Before executing a CLI line below, replace its leading SSF with node "<plugin-root>/scripts/spec-superflow.mjs"; <plugin-root> is the absolute directory two levels above this file. Never run SSF literally or call an ssf from PATH.

Legacy compatibility only: new planned changes use proposal.md + tasks.md and SSF workflow start --path planned. Do not generate a contract or request a second approval for them. Read the remaining instructions only for an existing legacy change.

Converts planning artifacts into a single execution handshake: execution-contract.md. Load the baseline with SSF runtime asset read templates/execution-contract.md.

Read before generating: .spec-superflow.yaml (especially dp_0_decisions), proposal.md, specs/, design.md, tasks.md, then load docs/artifact-contract.md with SSF runtime asset read docs/artifact-contract.md.

Enter bridging before writing the contract; skip the transition if already there. Honor configured specs/design omissions. Reference requirement IDs and task IDs instead of copying their full text; preserve scope, obligations, tests, and review policy.

Artifact Language

Read artifact_language=<concrete-language> from dp_0_decisions. Generate execution-contract.md in the same language as that resolved value and the approved planning artifacts. Preserve required schema keywords and code identifiers verbatim; language consistency applies to explanatory prose and headings. If the concrete artifact language is missing or still auto, route back to workflow-start before writing the contract instead of guessing or silently defaulting to English.

Artifact Mapping

SourceExtract
proposal.md → ## Why + ## What ChangesIntent Lock (problem + scope)
proposal.md → ## Scope > ### Out of ScopeScope Fence
specs/ → each ### Requirement:Approved Requirements, Scenarios, Test Obligations
design.md → ## DecisionsArchitecture, Interface, Dependency Constraints
tasks.md → numbered task groupsExecution Batches, Completion Definitions, Review Timing

Cross-Check: Requirement Coverage

Before finalizing:

  1. List every SHALL/MUST from specs/
  2. Verify each is reflected in Approved Behavior, has a test obligation, and appears in at least one batch
  3. Flag unmapped requirements in Escalation Rules
  4. Note cross-batch dependencies

Contract Structure

Must make obvious: approved behavior, out-of-scope, constraints, batches, test obligations, review gates, and conditions that force a rewind to planning. Prefer compression over repeating planning details.

Approval Model (DP-3)

After drafting: summarize handoff rules, identify ambiguity and flag unmapped requirements. Reuse explicit approval already covering this exact contract; otherwise request it once, together with any still-pending planning decisions and the default Native execution choice. Approval of scope alone does not approve a contract that has not been shown. Never ask the user to approve the same unchanged contract twice. After approval:

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

Advance the state after approval:

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

DP-3 is a hard gate — no implementation without this record.

Stale Contract Detection

Refresh if: scope changed in proposal, requirements changed in specs, constraints changed in design, batches changed materially in tasks, or the contract no longer matches intent.

Hotfix Mode

Generate a minimal contract only for a legacy Hotfix: Intent Lock (one sentence), Task List (numbered), Approval Gate (DP-3). Skip Scope Fence, Build Rules, Review Gates, Test Evidence. Still requires DP-3 approval. Quick direct execution and direct incident Hotfix do not invoke this skill; they use the signed receipt and finish with test_result: pass instead.

Guardrails

  • Do not continue to implementation if ambiguity remains
  • Do not approve the contract on the user's behalf
  • Do not skip the contract because planning docs look complete
  • Flag unmapped requirements; do not silently drop them

Post-Generation

The approved contract is recorded by state rebuild in the DP-3 sequence above, before the guarded transition. This applies to Full and legacy Hotfix. Do not refresh hashes merely to suppress an unapproved content change.

Exception Handling

  • Parse failures: Report specific file and section. Suggest re-running spec-writer.
  • Missing files: List every missing artifact. Route back to spec-writer.
  • User interruption: Re-read all artifacts on resume; check contract staleness via content comparison.
  • Validation failure: Flag unmapped requirements in Escalation Rules and approval summary.

Comments

Markdown supported