code-pact

A vendor-neutral control plane for AI coding agents.

Claude Code writes CLAUDE.md. Codex writes AGENTS.md. Cursor writes .cursor/rules/. Each AI coding agent has its own conventions for instruction files, skills, and progress tracking. Switching between them — or running more than one against the same project — means hand-editing parallel state.

code-pact gives any supported agent the same deterministic CLI for fetching task context, recording progress, and verifying completion criteria. The agent calls a small set of commands; code-pact keeps design/ as the structured source of truth and .code-pact/state/progress.yaml as the operational log. Adapters generate the per-agent instruction files so each agent sees its own world without the project state diverging.

v1.0 ships stable adapters for claude-code, codex, and generic. The cursor and gemini-cli adapters are experimental — they ship, they work, but their generated file formats may shift in minor releases to track upstream tooling changes.

# 30-second tour — runs the whole loop in a throwaway sandbox, writes nothing to your repo:
npx code-pact tutorial

Want to drive the loop yourself in a real project? Scaffold the sample TUTORIAL phase, then walk it command by command:

npx code-pact init --non-interactive --agent claude-code --locale en-US --sample-phase
code-pact adapter install claude-code --json
code-pact task prepare TUTORIAL-T1 --agent claude-code --json  # single per-task entry: state + recommendation + the exact commands to run
code-pact task start TUTORIAL-T1
# ... agent implements ...
code-pact verify --phase TUTORIAL --task TUTORIAL-T1           # run the phase's verification commands
code-pact task complete TUTORIAL-T1                            # re-runs verify, appends a done event
code-pact task finalize TUTORIAL-T1 --json                    # preview the design-status flip (dry-run is the default)
code-pact task finalize TUTORIAL-T1 --write --json            # apply it
code-pact validate                                            # CI-friendly health check

task prepare is the recommended per-task entry point: one call returns the current state, the execution recommendation, the context pack metadata, and a commands dictionary with the exact next commands. recommend and task context remain available as standalone diagnostics. (A plain init without --sample-phase starts with an empty roadmap — you add your own phases; see getting-started.)

Status

v1.0 freezes the public CLI surface — flags, exit codes, JSON envelope shapes, and error codes are stable across the v1.x line. The full stability taxonomy (Stable (v1.0) / Stable (human-output) / Experimental / Deprecated) lives in docs/cli-contract.md.

Release notes live in CHANGELOG.md. Upgrade guidance lives in docs/upgrading.md (within v1.x it is just a version bump; pre-v1.0 alpha notes are archived in docs/migration.md).

Install

# One-off invocation (no install)
npx code-pact --version

# Global install
npm install -g code-pact
code-pact --version

Past alpha releases remain available under the alpha dist-tag (npm install code-pact@alpha) for users who pinned to pre-v1.0 behaviour. New projects should use the default (latest) tag.

Contributors can also run from a clone with pnpm link --global, or install a local tarball produced by npm pack — see Development.

Getting started

docs/getting-started.md is the canonical first-thirty-minutes guide. It walks several onboarding approaches side by side:

• Smoke test — code-pact tutorial runs the whole loop end to end in a throwaway sandbox (nothing is written to your repo); or scaffold a real sample phase with init --sample-phase.
• Agent-first — plan prompt --schema-only gives your agent the output shape; it emits a roadmap YAML you ingest with phase import.
• Existing-plan adoption — already have a roadmap.md / TODO.md / draft YAML? plan adopt converts it into phases and tasks deterministically, no AI round-trip.
• Code-pact-first — capture a brief + constitution, then plan prompt and have your agent draft the full roadmap from them.
• Manual — write the roadmap by hand with a mix of interactive wizards and flag-based commands.

They all converge on the same per-task agent loop, entered through task prepare (task prepare → task start → implement → verify → task complete → task finalize). See docs/per-task-loop.md for the lifecycle diagram and a worked example. recommend and task context remain available as standalone diagnostics — task prepare surfaces both for you in one call.

New to the terms used here (context pack, envelope, derived state, …)? The docs/glossary.md defines them in plain language.

Starting fresh, or adopting on an existing repo? Two workflow guides cover each case — greenfield and brownfield. The full documentation index — including the Japanese docs — lives at docs/ (日本語).

Reference docs

| Doc | What it covers | | --- | --- | | docs/per-task-loop.md | The canonical per-task lifecycle — state diagram, the verbs, and a worked example. | | docs/glossary.md | Plain-language definitions for every code-pact term used in the docs. | | docs/positioning.md | What code-pact is, what it deliberately is not, the core CLI surfaces, and the success metrics the project measures itself against. | | docs/agent-contract.md | The v1.11+ agent contract: what code-pact guarantees, what adapter conformance requires of each agent integration, and the recommended per-task lifecycle. | | docs/getting-started.md | First-thirty-minutes guide (onboarding approaches + the per-task loop). | | docs/cli-contract.md | Full flag / exit code / JSON envelope / error code reference and the Stability taxonomy. | | docs/upgrading.md | How to upgrade — additive within v1.x; pointers for coming from a pre-v1.0 alpha. | | docs/troubleshooting.md | Diagnostic code → recovery action for the most common error codes. | | docs/community.md | Where to file issues / discussions / PRs, the GitHub Discussions intent, and the scope-discipline rule for the Non-goals list. |

Maintainers: see docs/dogfood.md (quick guide) and docs/maintainers/operations.md (deeper operations) for running code-pact on code-pact itself.

Supported agents

| Agent | Status | Adapter output | | ------------- | ---------------- | ------------------------------------------------------------------------- | | claude-code | stable | CLAUDE.md, .claude/skills/, .claude/hooks/, .context/claude-code/ | | codex | stable | AGENTS.md, .context/codex/ | | generic | stable | docs/code-pact/agent-instructions.md, .context/generic/ | | cursor | experimental | .cursor/rules/code-pact.mdc (alwaysApply: true), .context/cursor/ | | gemini-cli | experimental | GEMINI.md, .context/gemini-cli/ |

The cursor adapter writes a Cursor Project Rule — .cursor/rules/code-pact.mdc with alwaysApply: true so the agent always sees code-pact's workflow. .cursorrules (the legacy single-file format, deprecated in Cursor 0.43) is not written. The adapter is marked experimental because the .mdc format and placement may shift across Cursor releases.

The gemini-cli adapter writes GEMINI.md at the project root. Gemini CLI auto-discovers GEMINI.md files hierarchically (CWD → parent dirs up to .git, plus ~/.gemini/GEMINI.md). Install Gemini CLI only from the official google-gemini org — typosquat packages have been reported on npm.

The generic adapter writes one human-readable instructions file that you can copy or symlink into any other agent's expected location while the dedicated adapters land.

Non-goals (MVP)

These are deliberate, permanent boundaries — not a backlog. code-pact will not add them; each is ruled out to keep the "agent calls one stable CLI" promise (see docs/positioning.md).

• No LLM API calls — your agent does the inference; code-pact never calls a model.
• No web UI, daemon, or vector database — it runs as a CLI and exits.
• No GitHub / Linear / Jira integration — you wire those into your own agent or CI.
• No multi-agent orchestration — one task, one agent per invocation.
• No RAG / semantic search — context selection is deterministic, not embedding-based.

Requirements

• Node.js >= 22 (LTS or current)
• pnpm (for contributors building from source)

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
node dist/cli.js --version

For dogfooding code-pact against code-pact itself, see docs/dogfood.md.