ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

All-in-one example · Release Steward

Keep consumer code compatible through approved migration pull requests.

The Autonomous Release Steward turns one immutable provider revision into a bounded patch, independent verification, deterministic CI evidence, and a draft pull request that humans still control.

Mission

Concrete mission

Find consumer usages affected by an Acme Billing API revision, coordinate a safe migration, and open one verified draft pull request without gaining merge authority.

Run the credential-free fixture

bun run --cwd packages/examples/agent-application-foundation \
  example:release-steward
import {
  runReleaseStewardExample,
} from "@lssm-tech/example.agent-application-foundation/release-steward";

const result = await runReleaseStewardExample({
  topology: "vercel-railway-supabase",
});

if (result.scenario.autoMerge !== false) {
  throw new Error("The reference steward must never auto-merge.");
}

console.log(result.stages);
console.log(result.readiness.status); // "candidate"

End-to-end workflow

Every transition produces replayable evidence and preserves the source, plan, patch, policy, and approval boundary.

immutable provider revision
  → verify source and content digest
  → scan affected consumer usages
  → impact, migration, and verification subagents
  → bind plan, patch, policy, and evidence digests
  → human approval
  → apply exactly once
  → deterministic CI
  → draft pull request (auto-merge: false)
  → durable observation and governed improvement

The multi-agent team

Each participant receives only the capability and repository authority required by its role.

impact-analyst

Locates affected usages and emits source-linked impact evidence without repository write authority.

migration-implementer

Creates only the bounded candidate patch authorized by the migration plan.

independent-verifier

Checks provenance, patch scope, CI, security, approval bindings, and rollback evidence.

multiplayer operators

Authorized teammates can watch, comment, redirect, pause, resume, approve, or hand off the replayable session.

Non-negotiable guardrails

Approval is digest-bound

Any source, plan, patch, policy, or evidence change invalidates approval and returns the case to review.

Effects are exactly once

Patch application and draft-PR creation use stable idempotency keys, and replay proves effects are not duplicated.

The pull request stays a draft

The agent never receives merge authority. Consumer repository governance owns merge decisions.

Learning remains governed

Consented and redacted feedback may improve rules or prompts only after evaluation, approval, canary, observation, expiry, and rollback gates.

Durability, improvement, and portability

A leased worker retries recoverable failures, audits dead letters, and observes the draft PR. Consented redacted feedback may improve prompt or rule configuration through evaluation, approval, canary, expiry, and rollback. Workflow DevKit and preview EVE remain replaceable adapters.

Multi-agent and multiplayer

Bounded subagents, elastic teams, shared sessions, intervention, and replay.

Durable loops

Leases, retries, cancellation, dead letters, checkpoints, and kill switches.

Governed improvement

Evaluate, approve, canary, observe, expire, and roll back changes.

Portable deployment

Workflow DevKit or EVE on replaceable infrastructure topologies.

Evidence-based qualification

Local fixtures remain candidate until exact-environment live suites pass.

Readiness boundary

Candidate, not qualified

The fixture validates local contracts and deterministic invariants. It does not certify repository permissions, providers, CI, isolation, restore, failover, canary, or rollback behavior in a consumer environment.

AI agent package reference

Reference application guide

OSS docsagentsStart with OSS. Adopt Studio when you want the operating layer.
Previous

All-in-one agent examples

Compare complete Release Steward and Company Intelligence Scout applications that combine multi-agent execution, durable loops, governed improvement, deployment portability, and qualification.

Next

Build a Company Intelligence Scout

Build a policy-controlled multi-agent application that discovers companies, offerings, jobs, people, and eligible contacts from cited public-web evidence.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

ManifestoContract-first APISpec-driven development