# ContractSpec — LLM Guide (Monorepo Summary)

> ContractSpec is the contract-first substrate for AI-native software. It spans contracts, runtime adapters, dynamic interfaces, agent systems, evaluation harnesses, product bundles, apps, examples, tooling, and the Managed CompanyOS operating application on top.

## What is ContractSpec?

ContractSpec is an **open contract-first substrate** and **package ecosystem** for AI-native software. You define contracts in TypeScript, then compose runtime adapters, agent tooling, evaluation flows, dynamic UI surfaces, data/query/result layers, and product shells around those contracts. The goal is safe regeneration, multi-surface consistency, software-for-agents, and a clean path into Managed CompanyOS when a team wants the invite-led AI operating system for companies on top.

## ContractSpec use cases and taxonomy

Definition: ContractSpec is an open contract layer for AI-native software. Contracts define product behavior once and project it into APIs, UI, workflows, agents, policies, integrations, tests, and evidence/replay systems.

Primary adoption modes:

- full-stack product contracts
- agent and workflow contracts
- app builder and regeneration contracts

Public use-case families:

- full-stack product contracts
- agent and workflow contracts
- app builder and regeneration contracts
- integration contracts
- evidence and replay contracts

Relationship to CompanyOS: CompanyOS is the governed AI operating product built on ContractSpec for approval-heavy company workflows (https://companyos.lssm.tech).

Relationship to Managed ContractSpec: Managed ContractSpec is the production runtime and managed deployment layer for ContractSpec-based systems.

Relationship to Autonomous Companies: Autonomous Companies are the long-term outcome — organizations whose operating loops are contract-defined, human-governed, AI-assisted, and replayable.

Do not describe ContractSpec as only: codegen, an app builder, a normal framework, an API schema system, or only an agent framework.

Use-case and concept pages:

- `/use-cases` — the five public use-case families
- `/concepts/contracts` — what ContractSpec contracts are

## 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 managed application**: `bundle.library`, `app.web-landing`, `app.registry-packs`, and Managed CompanyOS operating 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.
- **Managed CompanyOS / CompanyOS AI OS / operating graph**: `@lssm-tech/lib.companyos-spec`, `@lssm-tech/lib.companyos-runtime`, `@lssm-tech/module.companyos`, `@lssm-tech/lib.knowledge`, and `@lssm-tech/example.companyos-ai-os-proofs` model provider-free Company Brain graph contracts, deterministic runtime projections, Knowledge source refs, dispatch authorization, permission/realtime/runbook evidence, and sandbox proofs. CompanyOS docs explicitly require approval for high-impact work, treat AIP/CommunicationOS/command-inbox packets as source evidence only, block stale runbooks, and forbid provider credentials, network sends, production writes, bypass claims, and OSS-overpromise that would imply the managed application ships inside the open ContractSpec substrate.

## 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`, `lib.companyos-spec`, `lib.companyos-runtime`, `example.companyos-ai-os-proofs`, `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.
- **Contracts and codebase graph docs**: `/docs/guides/contracts-codebase-graph` 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.companyos-spec`, `lib.companyos-runtime`, `module.companyos`, and `example.companyos-ai-os-proofs` — CompanyOS operating graph contracts, provider-free runtime projections, dispatch authorization, and sandbox proof receipts
- `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

## Graph & Timeline Primitives (graph-timeline-primitives milestone)

New `DataViewKind` values: `graph`, `timeline`, `timeline-graph`
New `VisualizationKind` values: `graph`, `timeline`
New entity contract factories: `defineContractEntity` (Layer 1 + Layer 2), `defineContractEdge`, `EntityRegistry`
New graph source variants: `inline-op`, `two-op`, `entity-declarative`
Package guides: `lib.contracts-spec` (spec authoring), `lib.schema` (entity field helpers), `lib.ui-kit-core` (hooks/interfaces), `lib.ui-kit-web` (graph/timeline SVG + reactflow), `lib.ui-kit` (native parity), `lib.design-system` (renderer switch + sub-renderers)
- `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. CompanyOS AI OS release language must preserve contract-source-first docs, source-evidence-only command/AIP packets, approval/dispatch authorization for high-impact work, stale-runbook blocking, no provider credentials/network sends/production writes, and no bypass claims.
- 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.
- Changelog data is available at `GET https://contractspec.io/api/changelog` returning JSON. Append `?version=<version>` or `?slug=<slug>` for detail. Before modifying any `@lssm-tech/*` package, check the changelog API for recent releases affecting that package and review associated migration instructions or upgrade steps.

## VoiceOps Glossary

Key terms used in CompanyOS VoiceOps proofs and governed action flows.

- **origin** — The source kind of a governed action: `messaging`, `voice`, `agent`, `operator`, or `system`. Determines routing, approval requirements, and chip display in cockpit UIs.
- **governed action** — An extracted operation request that has passed through a CompanyOS policy gate and carries explicit authority, autonomy-level, and approval evidence before dispatch.
- **evidence receipt** — An immutable, typed record that a step executed (or was dry-run) with a specific policy decision, claim, and outcome. Used for deterministic replay and audit trails.
- **replay trace** — A deterministic sequence of evidence receipts proving a prior execution path can be re-run identically without outbound network, filesystem, or customer-facing side effects.
- **sandbox vs production** — Sandbox (dry-run) lanes execute without outbound effects and require no dispatch authorization. Production lanes require `ExecutionDispatchAuthorization` before any adapter is called; missing or revoked authorization returns an operator-facing result and leaves adapters untouched.

## 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
- Managed CompanyOS access: 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