ContractSpec

Website: https://contractspec.io

Stabilize your AI-generated code

The open spec system for AI-native software. Define explicit contracts, keep every surface aligned, regenerate safely, and adopt Studio when you want the operating layer on top.

The Problem

In 2025, "vibe coding" and AI agents generate enormous amounts of code. But they have critical limitations:

• Can't enforce invariants — AI-generated code drifts from business rules over time
• Break multi-surface consistency — API, DB, UI, and events get out of sync
• Hallucinate refactors — AI "improvements" introduce subtle bugs and break contracts
• Destroy long-term maintainability — No source of truth, no safe regeneration path

The result: Teams ship fast initially, then spend months untangling AI-generated spaghetti.

How ContractSpec Works

1. Define contracts once — Write specs in TypeScript. Just types and Zod schemas you already know.
2. Generate all surfaces — One spec generates API, DB schema, UI types, events, and MCP tools.
3. Regenerate safely — Update specs, regenerate code. Invariants are enforced. Breaking changes caught at compile time.
4. AI reads specs — AI agents read contracts as their source of truth, not implementations.

What Gets Generated

From a single contract spec:

Surface	Output
REST API	Type-safe endpoints with validation
GraphQL	Schema and resolvers
Database	Prisma migrations and types
MCP Tools	AI agent tool definitions
Client SDK	Type-safe API clients
UI Components	React forms and views

Open, Ejectable Foundation

ContractSpec is an open system, not a closed platform:

• ✅ Generated code is standard TypeScript you can read and modify
• ✅ Uses standard tech (Prisma, GraphQL, Zod, React)
• ✅ No proprietary runtime — eject anytime, keep everything
• ✅ Incremental adoption — start with one module, expand at your pace

Quick Start

Choose one verified starting path. For the public CLI onboarding flows below, use Bun on Linux or macOS.

Greenfield

bun add -D contractspec
contractspec quickstart
contractspec onboard
contractspec init
contractspec create --type operation
contractspec generate
contractspec ci

Brownfield OpenAPI Import

bun add -D contractspec
contractspec init
contractspec openapi import path/to/openapi.yaml
contractspec ci

Example-First Exploration

bun add -D contractspec
contractspec examples list
contractspec examples init crm-pipeline

See the CLI documentation and tutorials for the maintained onboarding flows.

Support Matrix

Area	Supported Path
Package manager	bun 1.3.x is first-class for CLI onboarding and daily use
Operating system	Linux and macOS are covered by packaged smoke tests; Windows is not yet a supported CLI onboarding target
Alternate package managers	npm and pnpm can install libraries, but the contractspec CLI onboarding path is not yet certified on them
Greenfield onboarding	contractspec quickstart + contractspec onboard + contractspec init
Brownfield onboarding	contractspec openapi import
Example exploration	contractspec examples list + contractspec examples init
CI validation	contractspec ci (--check-drift optional when generated artifacts are part of the contract)
Diagnostics	contractspec doctor (read-only), contractspec doctor --fix (repair mode)

Connect For Coding-Agent Safety

ContractSpec Connect keeps risky coding-agent actions attached to local, reviewable artifacts instead of adapter-specific prompt rules.

• contractspec connect context projects repo state and impacted surfaces into a task-scoped ContextPack.
• contractspec connect plan compiles a PlanPacket before risky edits or shell execution.
• contractspec connect verify emits PatchVerdict decisions for file edits and commands, with review and replay artifacts under .contractspec/connect/.
• connect.adoption in .contractsrc.json can mirror the local adoption catalog and prefer workspace or ContractSpec reuse before greenfield implementation.

See the maintained walkthroughs in Connect in a repo and the Connect spec page.

Builder Control Plane

Builder is the governed authoring control plane that sits on top of the OSS foundation. It keeps multimodal capture, provider routing, readiness, preview, export, and mobile review explicit instead of hiding them inside a frontier coding agent.

• Builder workspace config supports runtimeMode: "managed" | "local" | "hybrid".
• Preset-driven bootstrap now uses canonical managed_mvp, local_daemon_mvp, and hybrid_mvp values.
• Builder API defaults and local runtime metadata live in .contractsrc.json, so CLI, editors, and hosted shells can resolve the same control-plane settings.

See Host the Builder workbench and Builder control plane.

First-Class Surfaces

• Contracts and generation: @contractspec/lib.contracts-spec, the main CLI, and runtime adapters for REST, GraphQL, MCP, and React.
• Connect and governed repo workflows: ContractSpec Connect for context packs, plan packets, patch verdicts, local review packets, replay, and evaluation artifacts.
• Builder control plane: governed authoring, provider routing, runtime modes, previews, readiness gates, exports, and mobile review surfaces.
• Agent and chat runtime: @contractspec/lib.ai-agent and @contractspec/module.ai-chat for tool-aware, MCP-aware, agent-governed experiences.
• Harness and evaluation: @contractspec/lib.harness and @contractspec/integration.harness-runtime for controlled inspection, replay, evaluation, and proof-oriented workflows.
• Ranking and MCP operations: provider-ranking module and MCP surfaces for ingesting benchmarks, refreshing rankings, and serving leaderboards.
• Docs, registry, and Studio: the public docs/web app, the agentpacks registry surfaces, and ContractSpec Studio's trusted operating loop.

Trust & Verification

• Published npm packages are shipped from provenance-enabled GitHub Actions runs, and each release run uploads a manifest artifact with package name, version, dist-tag, tarball filename, and SHA256.
• Release communication is now changeset-backed in two files: .changeset/<slug>.md for package/version intent and .changeset/<slug>.release.yaml for summary, migration guidance, validation commands, and evidence.
• Run bun run release:build to materialize the compact current-release manifests used by GitHub Release notes and upgrade guidance.
• Run contractspec release build --scope all --output generated/releases/history before building full historical changelog surfaces.
• Run bun run repo:health in this repo to reproduce the baseline trust checks locally: doctor, contract CI, and example validation.
• Verify the published CLI tag with npm view contractspec dist-tags --json.
• Verify a specific published package with npm view contractspec@<version> dist.tarball dist.integrity --json.
• Security disclosure and support expectations are documented in SECURITY.md.

Release Capsules

Every publishable changeset should leave behind both:

• .changeset/<slug>.md for package bumps and reader-facing change intent
• .changeset/<slug>.release.yaml for structured release metadata such as audiences, migration steps, upgrade steps, validation commands, and evidence

Use:

contractspec release init
contractspec release build
contractspec release check --strict

This keeps current-release upgrade prompts and maintainer guidance compact. Full historical changelog builds should use the explicit history output path.

GitHub Actions Quickstart

Use the ContractSpec actions directly; this repo's workflows are thin wrappers around them.

PR checks

name: ContractSpec PR
on: pull_request
jobs:
  contractspec:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: ContractSpec PR checks
        uses: lssm-tech/contractspec/packages/apps/action-pr@main
        with:
          generate-command: 'bun contractspec generate'

Drift check

name: ContractSpec Drift
on:
  push:
    branches: [main]
jobs:
  contractspec:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: ContractSpec drift check
        uses: lssm-tech/contractspec/packages/apps/action-drift@main
        with:
          generate-command: 'bun contractspec generate'

Notes: add pull-requests: write permissions for PR comments, and add contents: write + pull-requests: write for drift PR creation.

Inputs (defaults)

Action	Input	Default	Notes
PR	package-manager	bun	bun, npm, pnpm, yarn
PR	working-directory	.	Repo root or package path
PR	report-mode	summary	summary, comment, both, off
PR	enable-drift	true	Runs generate + drift check
PR	fail-on	any	breaking, drift, any, never
PR	generate-command	required	Required when drift enabled
PR	contracts-dir	empty	Directory for contract changes
PR	contracts-glob	empty	Glob for contract changes
Drift	generate-command	required	Regenerate artifacts
Drift	on-drift	fail	fail, issue, pr
Drift	drift-paths-allowlist	empty	Comma-separated globs

Sample output

## ContractSpec Report

### 1) What changed

2 contract file(s) changed.

ContractSpec Studio

ContractSpec Studio is the operating product built on top of ContractSpec.

It starts with one trusted product loop for certified live signals, reviewed drafts, supervised exports, and scheduled checks:

Activate -> Connect -> Draft -> Review -> Export -> Check

• Operate: Run the trusted loop with certified connectors, reviewed work drafts, guarded exports, and follow-up checks.
• Explore: Scan any company's public signals to generate Spec Packs, Drift Registers, competitive analysis, and other structured deliverables.
• Current certified wedge: Sandbox activation, PostHog, Slack, GitHub, Linear, and Notion.
• Governance first: Self-serve workspaces stay draft-only before export, with policy gates, audit trails, retention controls, and no autopilot code push, PR merge, or deployment in v0.

contractspec is the open foundation: contracts, generation, runtimes, harnesses, and agent-facing surfaces. Studio is the operating layer that runs on top of it across web, API, and MCP surfaces.

Try Studio

Example Contract

import { defineCommand } from '@contractspec/lib.contracts-spec';
import { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';

const UserInput = new SchemaModel({
  name: 'UserInput',
  fields: {
    email: { type: ScalarTypeEnum.Email(), isOptional: false },
    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
  },
});

export const CreateUser = defineCommand({
  meta: {
    name: 'user.create',
    version: '1.0.0',
    description: 'Register a new user',
    owners: ['team-auth'],
    tags: ['auth'],
  },
  io: {
    input: UserInput,
    output: new SchemaModel({
      name: 'UserOutput',
      fields: {
        id: { type: ScalarTypeEnum.String(), isOptional: false },
      },
    }),
  },
  policy: {
    auth: 'anonymous',
  },
});

Packages

Contracts Core

npm	Package	Description
	@contractspec/lib.contracts-spec	Core contract declarations, registries, policy, workflow, and shared spec types
	@contractspec/lib.contracts-integrations	Integration definitions (providers, capabilities, connection/runtime metadata)
	@contractspec/lib.schema	Schema definitions for multi-surface consistency
	@contractspec/app.cli-contractspec	CLI for creating, generating, validating, and running CI checks

Contracts Runtime Adapters

npm	Package	Description
	@contractspec/lib.contracts-runtime-client-react	React runtime adapters for forms and feature rendering
	@contractspec/lib.contracts-runtime-server-rest	REST server adapters (rest-next-app, rest-express, rest-elysia, generic)
	@contractspec/lib.contracts-runtime-server-graphql	GraphQL runtime adapter (graphql-pothos)
	@contractspec/lib.contracts-runtime-server-mcp	MCP runtime adapter (provider-mcp + MCP registrars)

AI & Evolution

npm	Package	Description
	@contractspec/lib.ai-agent	AI agent orchestration with contract governance
	@contractspec/module.ai-chat	Reusable AI chat system
	@contractspec/lib.evolution	Auto-evolution and safe regeneration

Runtime, MCP & Evaluation

npm	Package	Description
	@contractspec/lib.harness	Harness orchestration, evidence, policy, replay, and evaluation runtime
	@contractspec/integration.harness-runtime	Runtime adapters for browser, sandbox, artifact, and MCP-backed harness targets
	@contractspec/module.provider-ranking	Ranking pipelines, storage, and orchestration for provider benchmark data
	@contractspec/app.provider-ranking-mcp	MCP server for ranking ingest, refresh, leaderboards, and model-profile queries

Testing & Quality

npm	Package	Description
	@contractspec/lib.testing	Golden tests for safe regeneration verification
	@contractspec/lib.observability	Tracing, metrics, and structured logging

Legacy Package

npm	Package	Description
	@contractspec/lib.contracts (deprecated)	Deprecated monolith kept as migration marker; use split packages above

Who It's For

AI-Native Startups & Technical Founders

• Using Cursor, Copilot, Claude, or AI agents heavily
• Messy AI-generated backends, inconsistent APIs
• Need to stabilize without rewriting

Small Teams with AI-Generated Chaos

• Shipped fast with AI, now have tech debt
• Multiple surfaces out of sync
• Need incremental stabilization

AI Dev Agencies

• Building many projects for clients
• Need reusable templates and consistent quality
• Need professional handoff artifacts

Learn More

• Website
• CLI Documentation
• Examples

License

MIT