{"id":34768435,"url":"https://github.com/lssm-tech/contractspec","last_synced_at":"2026-03-10T01:09:46.242Z","repository":{"id":330857926,"uuid":"1094284986","full_name":"lssm-tech/contractspec","owner":"lssm-tech","description":"The deterministic, spec-first compiler that keeps AI-written software coherent, safe, and regenerable.","archived":false,"fork":false,"pushed_at":"2026-03-07T19:00:22.000Z","size":73109,"stargazers_count":4,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-07T19:55:20.033Z","etag":null,"topics":["contracts","sdd","spec-driven-development","specs","vibe-coding"],"latest_commit_sha":null,"homepage":"https://contractspec.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lssm-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-11T14:04:16.000Z","updated_at":"2026-03-07T19:00:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lssm-tech/contractspec","commit_stats":null,"previous_names":["lssm-tech/contractspec"],"tags_count":139,"template":false,"template_full_name":null,"purl":"pkg:github/lssm-tech/contractspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lssm-tech%2Fcontractspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lssm-tech%2Fcontractspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lssm-tech%2Fcontractspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lssm-tech%2Fcontractspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lssm-tech","download_url":"https://codeload.github.com/lssm-tech/contractspec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lssm-tech%2Fcontractspec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30280380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T01:43:35.720Z","status":"online","status_checked_at":"2026-03-09T02:00:08.011Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contracts","sdd","spec-driven-development","specs","vibe-coding"],"created_at":"2025-12-25T07:50:44.380Z","updated_at":"2026-03-10T01:09:46.222Z","avatar_url":"https://github.com/lssm-tech.png","language":"TypeScript","readme":"# ContractSpec\n\n[![npm version](https://img.shields.io/npm/v/contractspec)](https://www.npmjs.com/package/contractspec)\n[![npm downloads](https://img.shields.io/npm/dt/contractspec)](https://www.npmjs.com/package/contractspec)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/lssm-tech/contractspec)\n\nWebsite: [https://contractspec.io](https://contractspec.io)\n\n**Stabilize your AI-generated code**\n\nThe 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://www.contractspec.io/icon.png\" alt=\"ContractSpec Logo\" width=\"300\" height=\"300\"\u003e\n\u003c/p\u003e\n\n## The Problem\n\nIn 2025, \"vibe coding\" and AI agents generate enormous amounts of code. But they have critical limitations:\n\n- **Can't enforce invariants** — AI-generated code drifts from business rules over time\n- **Break multi-surface consistency** — API, DB, UI, and events get out of sync\n- **Hallucinate refactors** — AI \"improvements\" introduce subtle bugs and break contracts\n- **Destroy long-term maintainability** — No source of truth, no safe regeneration path\n\n**The result:** Teams ship fast initially, then spend months untangling AI-generated spaghetti.\n\n## How ContractSpec Works\n\n1. **Define contracts once** — Write specs in TypeScript. Just types and Zod schemas you already know.\n2. **Generate all surfaces** — One spec generates API, DB schema, UI types, events, and MCP tools.\n3. **Regenerate safely** — Update specs, regenerate code. Invariants are enforced. Breaking changes caught at compile time.\n4. **AI reads specs** — AI agents read contracts as their source of truth, not implementations.\n\n## What Gets Generated\n\nFrom a single contract spec:\n\n| Surface           | Output                              |\n| ----------------- | ----------------------------------- |\n| **REST API**      | Type-safe endpoints with validation |\n| **GraphQL**       | Schema and resolvers                |\n| **Database**      | Prisma migrations and types         |\n| **MCP Tools**     | AI agent tool definitions           |\n| **Client SDK**    | Type-safe API clients               |\n| **UI Components** | React forms and views               |\n\n## No Lock-in\n\nContractSpec is a **compiler**, not a platform:\n\n- ✅ Generated code is **standard TypeScript** you can read and modify\n- ✅ Uses **standard tech** (Prisma, GraphQL, Zod, React)\n- ✅ **No proprietary runtime** — eject anytime, keep everything\n- ✅ **Incremental adoption** — start with one module, expand at your pace\n\n## Quick Start: OSS Core\n\n```bash\n# Initialize project\nbunx contractspec init\n\n# Create a spec\ncontractspec create --type operation\n\n# Generate implementation\ncontractspec build src/contracts/mySpec.ts\n\n# Validate\ncontractspec validate src/contracts/mySpec.ts\n```\n\nSee the [CLI documentation](packages/apps/cli-contractspec/README.md) for full usage.\n\n## GitHub Actions Quickstart\n\nUse the ContractSpec actions directly; this repo's workflows are thin wrappers around them.\n\n### PR checks\n\n```yaml\nname: ContractSpec PR\non: pull_request\njobs:\n  contractspec:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: ContractSpec PR checks\n        uses: lssm-tech/contractspec/packages/apps/action-pr@main\n        with:\n          generate-command: 'bun contractspec generate'\n```\n\n### Drift check\n\n```yaml\nname: ContractSpec Drift\non:\n  push:\n    branches: [main]\njobs:\n  contractspec:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: ContractSpec drift check\n        uses: lssm-tech/contractspec/packages/apps/action-drift@main\n        with:\n          generate-command: 'bun contractspec generate'\n```\n\nNotes: add `pull-requests: write` permissions for PR comments, and add `contents: write` + `pull-requests: write` for drift PR creation.\n\n### Inputs (defaults)\n\n| Action | Input                   | Default   | Notes                               |\n| ------ | ----------------------- | --------- | ----------------------------------- |\n| PR     | `package-manager`       | `bun`     | `bun`, `npm`, `pnpm`, `yarn`        |\n| PR     | `working-directory`     | `.`       | Repo root or package path           |\n| PR     | `report-mode`           | `summary` | `summary`, `comment`, `both`, `off` |\n| PR     | `enable-drift`          | `true`    | Runs generate + drift check         |\n| PR     | `fail-on`               | `any`     | `breaking`, `drift`, `any`, `never` |\n| PR     | `generate-command`      | required  | Required when drift enabled         |\n| PR     | `contracts-dir`         | empty     | Directory for contract changes      |\n| PR     | `contracts-glob`        | empty     | Glob for contract changes           |\n| Drift  | `generate-command`      | required  | Regenerate artifacts                |\n| Drift  | `on-drift`              | `fail`    | `fail`, `issue`, `pr`               |\n| Drift  | `drift-paths-allowlist` | empty     | Comma-separated globs               |\n\n### Sample output\n\n```markdown\n## ContractSpec Report\n\n### 1) What changed\n\n2 contract file(s) changed.\n```\n\n## ContractSpec Studio\n\n[ContractSpec Studio](https://www.contractspec.studio) is the AI-powered product decision engine built on top of ContractSpec.\n\nIt turns product signals into spec-first deliverables through a deterministic loop:\n\n```text\nEvidence -\u003e Correlation -\u003e Decision -\u003e Change -\u003e Export -\u003e Check -\u003e Notify -\u003e Autopilot\n```\n\n- **Evidence**: Ingest product signals from meetings, support, analytics, code, docs, and Slack.\n- **Correlation**: Cluster evidence into scored patterns using hybrid heuristics + AI signatures.\n- **Decision**: Create evidence-backed focus briefs with citation chains and clear constraints.\n- **Change**: Compile patch intents into spec diffs, impact reports, and task packs.\n- **Export**: Push execution-ready outputs to Linear, Jira, Notion, and GitHub.\n- **Check + Autopilot**: Verify outcomes, feed learning dividends back into evidence, and automate safely with policy gates.\n\n`contractspec` is the grammar and compiler. Studio is the IDE and decision platform that runs on top of it.\n\n[**Try Studio**](https://www.contractspec.studio)\n\n## Example Contract\n\n```typescript\nimport { defineCommand } from '@contractspec/lib.contracts';\nimport { SchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';\n\nconst UserInput = new SchemaModel({\n  name: 'UserInput',\n  fields: {\n    email: { type: ScalarTypeEnum.Email(), isOptional: false },\n    name: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },\n  },\n});\n\nexport const CreateUser = defineCommand({\n  meta: {\n    name: 'user.create',\n    version: '1.0.0',\n    description: 'Register a new user',\n    owners: ['team-auth'],\n    tags: ['auth'],\n  },\n  io: {\n    input: UserInput,\n    output: new SchemaModel({\n      name: 'UserOutput',\n      fields: {\n        id: { type: ScalarTypeEnum.String(), isOptional: false },\n      },\n    }),\n  },\n  policy: {\n    auth: 'anonymous',\n  },\n});\n```\n\n## Packages\n\n### Contracts Core\n\n| npm                                                                                                                                                                | Package                                                                                      | Description                                                                     |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts-spec)](https://www.npmjs.com/package/@contractspec/lib.contracts-spec)                 | [`@contractspec/lib.contracts-spec`](packages/libs/contracts-spec/README.md)                 | Core contract declarations, registries, policy, workflow, and shared spec types |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts-integrations)](https://www.npmjs.com/package/@contractspec/lib.contracts-integrations) | [`@contractspec/lib.contracts-integrations`](packages/libs/contracts-integrations/README.md) | Integration definitions (providers, capabilities, connection/runtime metadata)  |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.schema)](https://www.npmjs.com/package/@contractspec/lib.schema)                                 | [`@contractspec/lib.schema`](packages/libs/schema/README.md)                                 | Schema definitions for multi-surface consistency                                |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/app.cli-contractspec)](https://www.npmjs.com/package/@contractspec/app.cli-contractspec)             | [`@contractspec/app.cli-contractspec`](packages/apps/cli-contractspec/README.md)             | CLI for creating, generating, validating, and running CI checks                 |\n\n### Contracts Runtime Adapters\n\n| npm                                                                                                                                                                                    | Package                                                                                                          | Description                                                                    |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts-runtime-client-react)](https://www.npmjs.com/package/@contractspec/lib.contracts-runtime-client-react)     | [`@contractspec/lib.contracts-runtime-client-react`](packages/libs/contracts-runtime-client-react/README.md)     | React runtime adapters for forms and feature rendering                         |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts-runtime-server-rest)](https://www.npmjs.com/package/@contractspec/lib.contracts-runtime-server-rest)       | [`@contractspec/lib.contracts-runtime-server-rest`](packages/libs/contracts-runtime-server-rest/README.md)       | REST server adapters (`rest-next-app`, `rest-express`, `rest-elysia`, generic) |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts-runtime-server-graphql)](https://www.npmjs.com/package/@contractspec/lib.contracts-runtime-server-graphql) | [`@contractspec/lib.contracts-runtime-server-graphql`](packages/libs/contracts-runtime-server-graphql/README.md) | GraphQL runtime adapter (`graphql-pothos`)                                     |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts-runtime-server-mcp)](https://www.npmjs.com/package/@contractspec/lib.contracts-runtime-server-mcp)         | [`@contractspec/lib.contracts-runtime-server-mcp`](packages/libs/contracts-runtime-server-mcp/README.md)         | MCP runtime adapter (`provider-mcp` + MCP registrars)                          |\n\n### Legacy Package\n\n| npm                                                                                                                                      | Package                                                                         | Description                                                            |\n| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.contracts)](https://www.npmjs.com/package/@contractspec/lib.contracts) | [`@contractspec/lib.contracts` (deprecated)](packages/libs/contracts/README.md) | Deprecated monolith kept as migration marker; use split packages above |\n\n### AI \u0026 Evolution\n\n| npm                                                                                                                                      | Package                                                            | Description                                     |\n| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------- |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.ai-agent)](https://www.npmjs.com/package/@contractspec/lib.ai-agent)   | [`@contractspec/lib.ai-agent`](packages/libs/ai-agent/README.md)   | AI agent orchestration with contract governance |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.evolution)](https://www.npmjs.com/package/@contractspec/lib.evolution) | [`@contractspec/lib.evolution`](packages/libs/evolution/README.md) | Auto-evolution and safe regeneration            |\n\n### Testing \u0026 Quality\n\n| npm                                                                                                                                              | Package                                                                    | Description                                     |\n| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------- |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.testing)](https://www.npmjs.com/package/@contractspec/lib.testing)             | [`@contractspec/lib.testing`](packages/libs/testing/README.md)             | Golden tests for safe regeneration verification |\n| [![npm downloads](https://img.shields.io/npm/dt/@contractspec/lib.observability)](https://www.npmjs.com/package/@contractspec/lib.observability) | [`@contractspec/lib.observability`](packages/libs/observability/README.md) | Tracing, metrics, and structured logging        |\n\n## Who It's For\n\n**AI-Native Startups \u0026 Technical Founders**\n\n- Using Cursor, Copilot, Claude, or AI agents heavily\n- Messy AI-generated backends, inconsistent APIs\n- Need to stabilize without rewriting\n\n**Small Teams with AI-Generated Chaos**\n\n- Shipped fast with AI, now have tech debt\n- Multiple surfaces out of sync\n- Need incremental stabilization\n\n**AI Dev Agencies**\n\n- Building many projects for clients\n- Need reusable templates and consistent quality\n- Need professional handoff artifacts\n\n## Learn More\n\n- [Website](https://contractspec.io)\n- [CLI Quick Start](packages/apps/cli-contractspec/QUICK_START.md)\n- [Agent Modes](packages/apps/cli-contractspec/AGENT_MODES.md)\n- [Examples](packages/examples/)\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flssm-tech%2Fcontractspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flssm-tech%2Fcontractspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flssm-tech%2Fcontractspec/lists"}