ContractSpec

Stabilize your AI-generated code

The deterministic, spec-first compiler that keeps AI-written software coherent, safe, and regenerable. You keep your app. You own the code. We're the compiler, not the prison.

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

Define contracts once — Write specs in TypeScript. Just types and Zod schemas you already know.
Generate all surfaces — One spec generates API, DB schema, UI types, events, and MCP tools.
Regenerate safely — Update specs, regenerate code. Invariants are enforced. Breaking changes caught at compile time.
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

No Lock-in

ContractSpec is a compiler, not a 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: OSS Core

# Initialize project
bunx contractspec init

# Create a spec
contractspec create --type operation

# Generate implementation
contractspec build src/contracts/mySpec.ts

# Validate
contractspec validate src/contracts/mySpec.ts

See the CLI documentation for full usage.

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 AI-powered product decision engine built on top of ContractSpec.

It turns product signals into spec-first deliverables through a deterministic loop:

Evidence -> Correlation -> Decision -> Change -> Export -> Check -> Notify -> Autopilot

Evidence: Ingest product signals from meetings, support, analytics, code, docs, and Slack.
Correlation: Cluster evidence into scored patterns using hybrid heuristics + AI signatures.
Decision: Create evidence-backed focus briefs with citation chains and clear constraints.
Change: Compile patch intents into spec diffs, impact reports, and task packs.
Export: Push execution-ready outputs to Linear, Jira, Notion, and GitHub.
Check + Autopilot: Verify outcomes, feed learning dividends back into evidence, and automate safely with policy gates.

contractspec is the grammar and compiler. Studio is the IDE and decision platform that runs on top of it.

Try Studio

Example Contract

import { defineCommand } from '@contractspec/lib.contracts';
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)