Quick introduction video

Understand Contract Graph.

A repository-native contract graph so the next session can find where a change belongs before reading code.

Quick start · Public beta 0.6.0

Install, then initialise.

0.6.0

In a terminal, install the CLI and run cg init. Then use a chat skill.

In a terminal

npm install --global contract-graph
cg --version
cd your-repository
cg init

In a new chat — existing code, with or without Contract Graph

/cg-warmup

Requires Node.js 18.17 or newer. cg init confirms this directory before writing. Warmup adopts missing contracts, or additively reseeds an existing graph. For a new repository, use /cg-plan or /cg-prototype in chat instead. Upgrading an older install is documented separately.

View package on npm ↗

Executive summary

Durable architectural context for AI coding agents.

Contract Graph is an open-source, repository-native system for helping coding agents locate, plan, implement, and verify changes without rediscovering the entire architecture in every session.

The challenge

Code generation is fast, but each new session still reconstructs ownership, boundaries, and dependencies from scattered implementation details.

The approach

Schema-backed contracts form a traversable graph from repository to module, submodule, component, and implementation.

The practical effect

An agent can route a task to the smallest responsible boundary, use its declared surface, and carry contracts and verification forward with the code.

The mission Scale model-driven development with contracts, not shared context.

The mental model

Route first. Read code second.

A request enters at the repository contract and follows authored routes through progressively smaller responsibilities. Only then does the agent open implementation files.

Contract Graph composition spine: a Project pocket containing Module A nested through a sub-module to a component, and Module B split into two sub-modules. A numbered walk goes request, Project contract, Module A contract, sub-module contract, component contract, then implementation. A dashed uses edge goes from Module B to Module A without ownership.
Nested boxes are pockets. Solid arrows compose the next smaller contract; the dashed arrow is a uses edge with no ownership. The numbered path is one request walking that graph before implementation is opened.

Hierarchy gives the route

Parent and child contracts form the top-down spine. Every reachable unit has one canonical contract and reciprocal edges.

Relationships add context

Dependency, surface, route, invariant, and verification edges explain how a unit participates without flattening the repository into a file graph.

The stopping point is explicit

The graph narrows the search to the smallest responsible boundary and its declared public surface before implementation reading begins.

Workflow

One change moves through four accountable stages.

Each stage produces an artifact the next stage can verify. Stage boundaries preserve review points; execution inside a stage stays continuous and sequential.

  1. 01

    Plan

    Turn the intended outcome into ordered phases with measurable acceptance gates.

    /cg-plan
  2. 02

    Prepare

    Convert one phase into dependency-aware Step briefs with exact editable paths and completion gates.

    /cg-prepare
  3. 03

    Produce

    Execute the earliest ready Step, delivering implementation, tests, contracts, and detectors together.

    /cg-produce
  4. 04

    Sign off

    Verify the accumulated result, repair composition findings, preserve durable knowledge, and close only when green.

    /cg-sign-off

Warmup

Chat skill for existing code with or without Contract Graph: adopt missing contracts, or additively reseed an existing graph without rewriting purpose or product rules.

/cg-warmup

Unblock

Use contract-backed decisions and reversible defaults; consolidate only material owner decisions.

/cg-unblock

Auto-Run

Follow measured handoffs within granted authority, stopping at decisions, failures, limits, or budget.

/cg-auto-run

The contract

One owned boundary. One canonical YAML contract.

A contract lives at <unit>/.agents/cg/contract.yaml. It describes current truth in the context of its parent—not an aspirational architecture and not a generated inventory of files.

  • Purpose and responsibilityWhat the unit owns, and what it explicitly forbids.
  • Public surfaceThe entry points an agent should use instead of bypassing the boundary.
  • Composition and relationsParent, children, and declared dependencies that make the unit reachable.
  • Invariants and verificationWhat must stay true and the commands or detectors that prove it.
  • RoutesTask language that directs an incoming request toward the right contracts.
contract.yaml · simplified
schemaVersion: 1
kind: component
name: payments
purpose: Own payment authorization.

responsibilities:
  owns:
    - Authorize a payment request.
  forbids:
    - Persist customer profiles.

surface:
  - kind: service
    path: src/PaymentService.ts

relations:
  parent: ../.agents/cg/contract.yaml

verification:
  - npm test -- payments

Seeing where you are

The graph is authored, schema-backed, and mechanically checked.

These commands inspect the same disk state the stages use. They do not require the last chat. Contract Graph protects structural truth it can measure while keeping advisory guidance separate from blocking rules.

01

Route resolution

cg contract route --task matches task language against repository-owned routes, then returns the contracts to load.

02

Graph verification

cg verify checks schema shape, reference resolution, reciprocal edges, acyclicity, root reachability, surfaces, and verification links.

03

Coverage discovery

cg modules reads build manifests to expose module roots that remain unmapped or still need recursive descent.

04

Three kinds of guidance

A principles are globally enforced, P rules bind one repository, and E guidance remains non-binding engineering advice.

cg nextcg residuecg verifycg graph showcg contract route --task "…"cg sync

What verification means: the authored graph is internally consistent and its declared checks resolve. It is not a claim that every implementation dependency or exported symbol has been inferred from source.

Adopt it

Choose the path that matches your repository.

Initialisation installs the schemas, bindings, workflow, and eight skills. Run cg init in a terminal. For existing code, with or without Contract Graph, the next chat skill is always /cg-warmup.

Existing code

With or without Contract Graph

  1. In a terminal, create a branch and run cg init.
  2. Reload the IDE so it discovers the bundled skills.
  3. In a new chat, run /cg-warmup. If cg modules still has gaps, that is adoption; if every adapter-detected root is governed, that is reseed.
  4. Review the connected contracts, findings, and consolidated decisions.
  5. Run cg sync && cg verify.

New repository

Design the route before implementation grows.

  1. In a terminal, run cg init.
  2. Write the root contract’s real purpose and boundaries.
  3. Reload the IDE to discover the skills.
  4. In a new chat, begin with /cg-plan or /cg-prototype.
  5. Add each self-sufficient unit’s contract in the Step that creates it.

Already installed: install contract-graph@0.6.0, run cg init in a terminal, reload the IDE, then /cg-warmup in a new chat. Skills and schemas replace; contracts and catalogs stay. See the upgrade guide.

Public beta: review generated governance and proposed structural changes before merging. Warmup describes existing behavior; any restructuring it identifies should become planned delivery work.

Capabilities and limits

Useful now. Not overclaimed.

Built today

Schema-backed contracts, task routing, brownfield discovery, eight lifecycle skills, graph reciprocity, acyclicity, reachability, surface checks, and verification links.

Not claimed

Complete inference of every implementation dependency or exported symbol, proof that architecture matches runtime behavior, or safe arbitrary parallel write sets.

Core principle

The graph remains useful only when contract, detector, implementation, and tests change together. Governance is how that durable context stays trustworthy.

Developers

Install cg, author contracts, and keep implementation aligned with a graph the next session can trust.

Read the developer path →

Architecture

What is mandatory, what is advisory, and what verification actually proves.

Read architecture →

Preprint: doi:10.5281/zenodo.22301753

View the source View on npm

Quick introduction video