{"id":49986764,"url":"https://github.com/toshtag/code-pact","last_synced_at":"2026-06-02T03:01:58.489Z","repository":{"id":358233468,"uuid":"1239639354","full_name":"toshtag/code-pact","owner":"toshtag","description":"Vendor-neutral control plane for AI coding agents. Deterministic CLI surface for context fetch, verify, and progress. Stable in v1.0 for claude-code / codex / generic; cursor / gemini-cli experimental.","archived":false,"fork":false,"pushed_at":"2026-05-30T07:56:55.000Z","size":2943,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T08:21:52.016Z","etag":null,"topics":["agent","ai","ai-agents","claude","claude-code","cli","codex","cursor","design","developer-tools","gemini-cli","spec-driven"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/code-pact","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toshtag.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T09:40:01.000Z","updated_at":"2026-05-30T07:56:33.000Z","dependencies_parsed_at":"2026-05-22T05:02:22.457Z","dependency_job_id":null,"html_url":"https://github.com/toshtag/code-pact","commit_stats":null,"previous_names":["toshtag/code-pact"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/toshtag/code-pact","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshtag%2Fcode-pact","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshtag%2Fcode-pact/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshtag%2Fcode-pact/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshtag%2Fcode-pact/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toshtag","download_url":"https://codeload.github.com/toshtag/code-pact/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toshtag%2Fcode-pact/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33803734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-agents","claude","claude-code","cli","codex","cursor","design","developer-tools","gemini-cli","spec-driven"],"created_at":"2026-05-19T00:11:03.930Z","updated_at":"2026-06-02T03:01:58.484Z","avatar_url":"https://github.com/toshtag.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# code-pact\n\n[![npm version](https://img.shields.io/npm/v/code-pact)](https://www.npmjs.com/package/code-pact)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js version](https://img.shields.io/node/v/code-pact)](package.json)\n\n**A vendor-neutral control plane for AI coding agents.**\n\nClaude 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.\n\n`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.\n\nv1.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.\n\n```sh\n# 30-second tour — runs the whole loop in a throwaway sandbox, writes nothing to your repo:\nnpx code-pact tutorial\n```\n\nWant to drive the loop yourself in a real project? Scaffold the sample `TUTORIAL` phase, then walk it command by command:\n\n```sh\nnpx code-pact init --non-interactive --agent claude-code --locale en-US --sample-phase\ncode-pact adapter install claude-code --json\ncode-pact task prepare TUTORIAL-T1 --agent claude-code --json  # single per-task entry: state + recommendation + the exact commands to run\ncode-pact task start TUTORIAL-T1\n# ... agent implements ...\ncode-pact verify --phase TUTORIAL --task TUTORIAL-T1           # run the phase's verification commands\ncode-pact task complete TUTORIAL-T1                            # re-runs verify, appends a done event\ncode-pact task finalize TUTORIAL-T1 --json                    # preview the design-status flip (dry-run is the default)\ncode-pact task finalize TUTORIAL-T1 --write --json            # apply it\ncode-pact validate                                            # CI-friendly health check\n```\n\n`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](docs/getting-started.md).)\n\n## Status\n\nv1.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`](docs/cli-contract.md#stability-taxonomy-v10).\n\nRelease notes live in [`CHANGELOG.md`](CHANGELOG.md). Upgrade guidance lives in [`docs/upgrading.md`](docs/upgrading.md) (within v1.x it is just a version bump; pre-v1.0 alpha notes are archived in [`docs/migration.md`](docs/migration.md)).\n\n## Install\n\n```sh\n# One-off invocation (no install)\nnpx code-pact --version\n\n# Global install\nnpm install -g code-pact\ncode-pact --version\n```\n\nPast 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.\n\nContributors can also run from a clone with `pnpm link --global`, or install a local tarball produced by `npm pack` — see [Development](#development).\n\n## Getting started\n\n[`docs/getting-started.md`](docs/getting-started.md) is the canonical first-thirty-minutes guide. It walks several onboarding approaches side by side:\n\n- **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`.\n- **Agent-first** — `plan prompt --schema-only` gives your agent the output shape; it emits a roadmap YAML you ingest with `phase import`.\n- **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.\n- **Code-pact-first** — capture a brief + constitution, then `plan prompt` and have your agent draft the full roadmap from them.\n- **Manual** — write the roadmap by hand with a mix of interactive wizards and flag-based commands.\n\nThey all converge on the same per-task agent loop, entered through `task prepare` (`task prepare` → `task start` → implement → `verify` → `task complete` → `task finalize`). `task prepare` also returns a `lifecycleMode` (`full_loop` / `record_only` / `decision_loop`) recommending how heavy that loop should be — e.g. `record_only` lets a small, strongly-verified task record completion via `task record-done` instead of the full loop. See [`docs/per-task-loop.md`](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.\n\nNew to the terms used here (context pack, envelope, derived state, …)? The [`docs/glossary.md`](docs/glossary.md) defines them in plain language.\n\n**Starting fresh, or adopting on an existing repo?** Two workflow guides cover each case — [greenfield](docs/workflows/greenfield.md) and [brownfield](docs/workflows/brownfield-feature.md). The full documentation index — including the Japanese docs — lives at [`docs/`](docs/README.md) ([日本語](docs/ja/README.md)).\n\n## Reference docs\n\n| Doc | What it covers |\n| --- | --- |\n| [`docs/per-task-loop.md`](docs/per-task-loop.md) | The canonical per-task lifecycle — state diagram, the verbs, and a worked example. |\n| [`docs/glossary.md`](docs/glossary.md) | Plain-language definitions for every `code-pact` term used in the docs. |\n| [`docs/positioning.md`](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. |\n| [`docs/agent-contract.md`](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. |\n| [`docs/getting-started.md`](docs/getting-started.md) | First-thirty-minutes guide (onboarding approaches + the per-task loop). |\n| [`docs/cli-contract.md`](docs/cli-contract.md) | Full flag / exit code / JSON envelope / error code reference and the Stability taxonomy. |\n| [`docs/upgrading.md`](docs/upgrading.md) | How to upgrade — additive within v1.x; pointers for coming from a pre-v1.0 alpha. |\n| [`docs/troubleshooting.md`](docs/troubleshooting.md) | Diagnostic code → recovery action for the most common error codes. |\n| [`docs/community.md`](docs/community.md) | Where to file issues / discussions / PRs, the GitHub Discussions intent, and the scope-discipline rule for the Non-goals list. |\n\nMaintainers: see [`docs/dogfood.md`](docs/dogfood.md) (quick guide) and [`docs/maintainers/operations.md`](docs/maintainers/operations.md) (deeper operations) for running `code-pact` on `code-pact` itself.\n\n## Supported agents\n\n| Agent         | Status           | Adapter output                                                            |\n| ------------- | ---------------- | ------------------------------------------------------------------------- |\n| `claude-code` | stable           | `CLAUDE.md`, `.claude/skills/`, `.claude/hooks/`, `.context/claude-code/` |\n| `codex`       | stable           | `AGENTS.md`, `.context/codex/`                                            |\n| `generic`     | stable           | `docs/code-pact/agent-instructions.md`, `.context/generic/`               |\n| `cursor`      | **experimental** | `.cursor/rules/code-pact.mdc` (`alwaysApply: true`), `.context/cursor/`   |\n| `gemini-cli`  | **experimental** | `GEMINI.md`, `.context/gemini-cli/`                                       |\n\nThe `cursor` adapter writes a [Cursor Project Rule](https://cursor.com/docs/context/rules) — `.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.\n\nThe `gemini-cli` adapter writes [`GEMINI.md`](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.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.\n\nThe `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.\n\n## Non-goals (MVP)\n\nThese 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`](docs/positioning.md#what-code-pact-is-not)).\n\n- **No LLM API calls** — your agent does the inference; `code-pact` never calls a model.\n- **No web UI, daemon, or vector database** — it runs as a CLI and exits.\n- **No GitHub / Linear / Jira integration** — you wire those into your own agent or CI.\n- **No multi-agent orchestration** — one task, one agent per invocation.\n- **No RAG / semantic search** — context selection is deterministic, not embedding-based.\n\n## Requirements\n\n- Node.js \u003e= 22 (LTS or current)\n- pnpm (for contributors building from source)\n\n## Development\n\n```sh\npnpm install\npnpm typecheck\npnpm test\npnpm build\nnode dist/cli.js --version\n```\n\nFor dogfooding `code-pact` against `code-pact` itself, see [`docs/dogfood.md`](docs/dogfood.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoshtag%2Fcode-pact","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoshtag%2Fcode-pact","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoshtag%2Fcode-pact/lists"}