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

Run four commands.

Beta

Install the CLI, initialise a repository, then reload your coding environment.

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

Requires Node.js 18.17 or newer. cg init confirms this directory before writing. For existing code, continue with /cg-warmup (adoption if roots are unmapped, reseed if the graph is already connected). For a new repository, use /cg-plan. Upgrading 0.3.0 or 0.4.0 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.

Request
Repository
Module
Submodule
Component or library
Implementation

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

Adoption for existing code, or additive reseed after a package upgrade: discover or extend contracts without rewriting existing 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 seven skills. The next step differs for brownfield, an existing graph, and greenfield code.

Existing repository

Map what is already true.

  1. Create a branch and run cg init.
  2. Reload the IDE so it discovers the bundled skills.
  3. Run /cg-warmup in a new AI session. If cg modules still has gaps, that is adoption; if every adapter-detected root is governed, that is reseed. cg modules lists those roots, not every directory that already has a contract.
  4. Review the connected contracts, findings, and consolidated decisions.
  5. Run cg sync && cg verify.

New repository

Design the route before implementation grows.

  1. Run cg init.
  2. Write the root contract’s real purpose and boundaries.
  3. Reload the IDE to discover the skills.
  4. Begin with /cg-plan.
  5. Add each self-sufficient unit’s contract in the Step that creates it.

Already on 0.3.0 or 0.4.0: install contract-graph@0.5.0, run cg init --yes --docs docs, reload the IDE, then /cg-warmup. Skills and schemas replace; contracts and catalogs stay. A stored all profile expands. A connected graph takes the reseed path. 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, seven 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.

View the source View on npm

Quick introduction video