Purpose

Define explicit input/output schemas for artifacts passed between agents or pipeline stages. Every producer knows exactly what shape to emit; every consumer knows exactly what shape to expect. Eliminates silent data-loss and schema drift across multi-agent workflows.

When to use

• A multi-agent workflow hands data from one stage to another and the schema is undocumented.
• An agent's output is consumed by a downstream agent and validation is missing.
• Contract versioning is needed because the artifact shape is evolving across iterations.
• A new pipeline stage is being added and its expected inputs/outputs must be specified.

Do NOT use when

• The task is a single-agent, single-step operation with no handoff.
• An existing contract file already fully covers the artifact shape (update it instead).
• The work is pure prose generation where structured schemas add no value.

Operating procedure

1. Run

   grep -r "contract" --include="*.md" --include="*.json" --include="*.yaml"

   in the repo to find existing contract definitions.
2. List every pipeline stage involved in the workflow in a numbered table:

   | # | Stage | Producer Agent | Consumer Agent |

   .
3. For each stage boundary, write a JSON Schema or TypeScript interface defining the artifact with required fields, types, and descriptions.
4. Add a

   version

   field (semver string) to every contract schema — start at

   1.0.0

   for new contracts.
5. Define validation rules: list which fields are required vs. optional, acceptable value ranges, and enum constraints.
6. Write a

   validate_artifact(data, schema)

   pseudocode block showing how the consumer should reject malformed input.
7. Create a producer/consumer pairing table:

   | Contract Name | Producer | Consumer | Version | Breaking Change Policy |

   .
8. Add a

   _contract_meta

   envelope to each artifact specifying

   schema_version

   ,

   produced_by

   ,

   produced_at

   (ISO-8601), and

   checksum

   (SHA-256 of payload).
9. Run a dry-run validation: pick one real or sample artifact, apply the schema, and list any violations found.
10. Write the final contract files to

    contracts/

    (or the repo's equivalent directory), one file per stage boundary.

Decision rules

• If a field is consumed by any downstream agent, it is

  required

  — never silently optional.
• If two producers emit the same artifact type, unify into one schema and version it; do not fork.
• Breaking changes (removing fields, narrowing types) require a major version bump and a migration note.
• Non-breaking changes (adding optional fields) require a minor version bump.
• If a consumer receives an artifact that fails validation, it must halt and return a structured error — never silently drop fields.

Output requirements

1. Contract Schema — one JSON Schema or TypeScript interface per stage boundary.
2. Pairing Table — maps every producer to every consumer with version and change policy.
3. Validation Report — dry-run results showing pass/fail per field for a sample artifact.
4. Migration Notes — for any version bump, a list of what changed and how consumers should adapt.

References

• references/delegate-contracts.md

  — patterns for structuring delegation handoff.

• references/checkpoint-rules.md

  — when to checkpoint before/after artifact production.
• JSON Schema specification (https://json-schema.org/) for schema authoring.

Related skills

• autonomous-run-control

  — contracts govern what a run must produce before it can terminate.

• collaboration-checkpoints

  — checkpoints often trigger contract validation.

• goal-decomposition

  — decomposed tasks need contracts at each task boundary.

• verification-before-advance

  — verification uses contracts as the acceptance criteria.

Failure handling

• Missing contract: If no contract exists for a stage boundary, create one before allowing data to flow — never infer schema from a single sample.
• Schema mismatch: If a produced artifact fails validation, block the pipeline and emit a diff showing expected vs. actual shape.
• Version conflict: If producer and consumer expect different versions, halt and surface both versions for reconciliation.
• Ambiguous ownership: If no single agent owns a contract, assign ownership explicitly before proceeding.