# ContractSpec — LLM Guide (Monorepo Summary)

> ContractSpec is the open spec system for AI-native software. It spans contracts, runtime adapters, agent systems, evaluation harnesses, product bundles, apps, examples, tooling, and the Studio operating layer on top.

## What is ContractSpec?

ContractSpec is an **open spec system** and **package ecosystem** for AI-native software. You define contracts in TypeScript, then compose runtime adapters, agent tooling, evaluation flows, UI surfaces, and product shells around those contracts. The goal is safe regeneration, multi-surface consistency, explicit control over AI-written systems, and a clean path into Studio when a team wants the operating product on top.

## Monorepo Structure

Dependency flow goes downward:

**apps/apps-registry → bundles → modules/integrations → libs**

Examples may depend on any lower layer to demonstrate the stack, and tools support the whole repository.

| Layer | Path | Role |
| --- | --- | --- |
| libs | packages/libs/ | Foundational contracts, runtimes, agent systems, harness core, schema, UI primitives, and shared utilities. |
| integrations | packages/integrations/ | Runtime and provider bridges that bind core libs to concrete execution targets. |
| modules | packages/modules/ | Reusable feature and domain modules such as AI chat, provider ranking, notifications, and learning journeys. |
| bundles | packages/bundles/ | Higher-level product composition for workspace, docs/library, marketing, and other broad surfaces. |
| apps | packages/apps/ | Deployable shells such as the CLI, APIs, MCP servers, web apps, and mobile demo. |
| examples | packages/examples/ | Runnable and importable reference implementations used for docs, onboarding, and validation. |
| tools | packages/tools/ | Build, docs, lint, config, and agentpacks tooling used by this repo and downstream consumers. |
| apps-registry | packages/apps-registry/ | Registry-facing app metadata and marketplace surfaces. |

## First-Class Surfaces

- **Contracts and generation**: `@lssm-tech/lib.contracts-spec`, `@lssm-tech/lib.schema`, graph artifacts, drift reports, generation plans, and `@lssm-tech/app.cli-contractspec`.
- **Connect and governed repo workflows**: ContractSpec Connect for context packs, plan packets, patch verdicts, review packets, replay/eval artifacts, and adoption-aware reuse guidance.
- **Builder control plane**: governed authoring, managed/local/hybrid runtime modes, Builder bootstrap presets, previews, readiness gates, exports, and mobile review surfaces.
- **Runtime adapters**: REST, GraphQL, MCP, React runtime packages under `packages/libs/contracts-runtime-*`, the ContractSpec-native translation runtime with optional i18next projection, and Workflow DevKit support via `@lssm-tech/integration.workflow-devkit`.
- **Agent systems**: `@lssm-tech/lib.ai-agent` and `@lssm-tech/module.ai-chat`.
- **Harness and evaluation**: `@lssm-tech/lib.harness` and `@lssm-tech/integration.harness-runtime`.
- **Ranking and MCP workflows**: provider-ranking module and MCP server surfaces.
- **Docs, registry, and Studio**: `bundle.library`, `app.web-landing`, `app.registry-packs`, and ContractSpec Studio messaging/operate surfaces.
- **BillingOS**: `@lssm-tech/lib.billing-spec`, `@lssm-tech/lib.billing-runtime`, `@lssm-tech/lib.billing-france`, and `@lssm-tech/example.billingos-france-sme` model country-neutral quote-to-cash contracts, deterministic provider-free runtime helpers, France readiness metadata, and a replayable SME proof. BillingOS docs explicitly forbid production PA submission, provider credentials, legal/tax advice, payment processing, full accounting claims, and autonomous high-impact billing execution.

## Preferred Entry Points For Agents

- **`/llms`** or **`/llms.txt`**: this monorepo summary.
- **`/llms/[slug]`**: preferred per-package guide. Example slugs: `lib.ai-agent`, `lib.harness`, `module.ai-chat`, `bundle.library`, `app.web-landing`, `app.registry-packs`.
- **`/llms-full.txt`**: aggregated README corpus for all packages. Large file; use only when broad repository context is necessary.
- **Generative Core docs**: `/docs/generative-core` describes graph inspect/export, drift check, generation plan/apply, repair proposal, and Connect-gated write expectations.

## Recommended Package Guides

- `lib.contracts-spec` — foundational contracts, registries, capabilities, and shared execution primitives
- `lib.billing-spec`, `lib.billing-runtime`, and `lib.billing-france` — BillingOS country-neutral contracts, deterministic runtime helpers, and France readiness pack; pair with `example.billingos-france-sme` for the replay proof and safety boundaries
- `lib.translation-runtime` — ContractSpec-first i18n runtime, ICU formatting, SSR snapshots, locale fallback, overrides, diagnostics, and optional i18next adapter
- `lib.ai-agent` — core agent runtime, tools, sessions, memory, approvals, and telemetry
- `lib.harness` — harness orchestration, policy, replay, and evidence normalization
- `integration.harness-runtime` — browser, sandbox, artifact, and MCP-backed harness runtime adapters
- `module.ai-chat` — packaged AI chat feature surface with presentation and provider bindings
- `integration.workflow-devkit` — Workflow DevKit compilation, runtime bridging, reconnectable chat routes, and Workflow-backed agent adapters
- `module.provider-ranking` — ranking ingestion, storage, and orchestration layer
- `bundle.workspace` — CLI/editor/repository workflow composition
- `bundle.library` — docs, templates, integrations, shell, and MCP composition
- `app.cli-contractspec` — main CLI for init, generate, doctor, CI, and example flows
- `app.web-landing` — public docs, marketing, registry, and `/llms*` delivery shell
- `app.registry-packs` — agentpacks registry API and MCP surface
- `tool.agentpacks` is exposed as slug `agentpacks` — pack-based agent config generation across Cursor, Codex, Claude Code, Copilot, Gemini, and more

## Key Principles

1. Define contracts before implementation.
2. Treat contracts and documented package surfaces as the source of truth for AI agents.
3. Keep dependency flow downward and apps thin.
4. Use standard TypeScript and composable packages rather than hidden proprietary runtimes.
5. Prefer package-local `README.md` and `AGENTS.md` when working inside a specific package.

## Release Workflow

- Treat `.changeset/<slug>.md` and `.changeset/<slug>.release.yaml` as the canonical release-facing source of truth for user and contributor workflow changes.
- Run `contractspec release build` before building changelog or upgrade surfaces that depend on generated release manifests.
- Packages are resolved from private GitHub Packages. Consumer docs must keep access requests, `GITHUB_PACKAGES_TOKEN`, `.npmrc`/Bun scope config, and GitHub Actions token guidance aligned with `/docs/getting-started/private-registry`.
- When a release changes public workflow expectations, keep root docs, package docs, website docs, graph/generation docs, and `/llms*` summaries aligned with the release capsule. BillingOS release language must preserve the country-neutral core, France-readiness-only pack, no production PA/provider credentials, and no autonomous high-impact execution boundaries.
- When a release adds or changes public example template previews, keep package READMEs, module/examples preview guidance, marketing/web docs, paired changeset/release capsules, generated registries, and `/llms*` package guides aligned. Rich previews must stay package-native or explicitly approved, deterministic, provider-free, and backed by docs/sandbox/LLMS/source fallback links.

## Resources

- Website: https://contractspec.io
- Documentation: https://www.contractspec.io/docs
- GitHub: https://github.com/lssm-tech/contractspec
- GitHub Packages registry: https://npm.pkg.github.com
- Studio: https://www.contractspec.studio
- Translation runtime docs: /docs/libraries/translation-runtime
- Translation runtime package guide: /llms/lib.translation-runtime
- Full package corpus: /llms-full.txt