A lightweight protocol framework for auditable human-AI software development | v1.12.0 中文: README.zh.md
PACT is a lightweight protocol framework for building software with AI while keeping product intent, implementation scope, and verification evidence explicit.
It turns AI-assisted development from an open-ended chat into a staged workflow: define intent, write a behavior contract, implement against that contract, verify with real outputs, then archive what changed.
PACT keeps the daily feature loop lightweight, but feature work is anchored by two global spines: the Product Spine in PAD.md and the Architecture Spine in architecture.md. A feature should explain where it fits in the core business flow and which module / entity boundaries it touches before it enters build.
PACT is designed for product-minded builders, solo developers, and small teams who want AI to move faster without losing control of scope, state, and quality.
It is not a code generator, an agent scheduler, or a replacement for CI/CD. It is the protocol layer that keeps human decisions and AI execution aligned.
Core idea: Define behavior before implementation. Verify behavior before shipping.
Use PACT when:
- You are building a product with AI assistance and need the work to remain auditable.
- You want clear handoffs between product intent, implementation, verification, and release.
- You are a solo developer, product-minded builder, or small team working feature by feature.
- You prefer explicit contracts and checkpoints over relying on long prompts.
Avoid PACT when:
- You need a general-purpose task manager or multi-agent scheduler.
- You need deployment, monitoring, incident response, or CI/CD orchestration.
- You are solving high-risk security, financial, concurrency, or performance problems without specialist review.
Before adopting, check whether your project falls within PACT's applicable scope.
- Transaction consistency and concurrency races — boundaries B-H02 / B-H05
- Financial operations and sensitive data — boundaries B-H03 / B-H06
- Cross-user aggregation / real-time communication — boundaries B-H01 / B-H04
- Code performance (N+1, slow queries, etc.) — runtime boundary scan in
/pact.build
PACT will actively stop you in these situations but does not propose solutions. Pair with specialized reviews (security / performance / DBA). The detect-and-halt behavior is itself one of the framework's deliverables.
- Production deployment, monitoring, alerting
- Multi-developer concurrent development conflicts
- CI/CD pipelines and release management
PACT does not engage with these — use other toolchains.
Install details: INSTALL.md Full usage guide: USAGE.md Global Spine Lite guide: docs/concepts/global-spine-lite.md Design Attachments Lite guide: docs/concepts/design-attachments-lite.md Existing project adoption: docs/migration/adopt-global-spine-lite.md
# Recommended: install directly into a project from GitHub
curl -fsSL https://raw.githubusercontent.com/Hypho/pact/main/scripts/install-from-github.sh | bash -s -- --target your-project --mode auto
# Windows PowerShell: install into the current directory
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/Hypho/pact/main/scripts/install-from-github.ps1 | iex"
# From a cloned PACT repository
bash scripts/install-pact.sh --target your-project --mode auto
# In Claude Code, run:
/pact.init # Project initialization (one-time)
/pact.scope # Scope and risk-boundary assessment (recommended before first feature)
# Optional installed-project self-check
cd your-project
bash .pact/bin/pact.sh check --project
# Framework maintainers: see RELEASE.md for release checksThe remote installer copies PACT files directly into the target project. Runtime checks still require bash.
PACT is tool-agnostic at the protocol layer, with first-class Claude Code support and adapter files for Codex and Cursor.
| Tool | Support | Entry point |
|---|---|---|
| Claude Code | First-class | docs/adapters/claude-code.md |
| Codex | Compatible | docs/adapters/codex.md |
| Cursor | Compatible | docs/adapters/cursor.md |
For non-Claude tools, use docs/adapters/prompts.md.
AGENTS.md is the portable agent entry. CLAUDE.md is the Claude Code runtime entry. Both summarize the same PACT protocol, but .pact/core/workflow.md and .pact/core/constitution.md remain the source files for workflow facts and hard constraints.
Claude Code plugin marketplace installation is planned, not the current primary installation path.
See examples for runnable completed feature flows:
- todo-feature shows the smallest useful flow with validation and storage failure handling.
- secure-notes shows a more realistic ownership boundary with denied cross-user access and verification evidence.
- order-flow shows Global Spine Lite: PAD business flow, architecture boundaries, PID flow mapping, and flow evidence in verify.
Per-feature flow: pid → contract → build → verify → ship
Every 3–5 features: retro
The canonical workflow definition is .pact/core/workflow.md. README, adapter files, and command files should summarize that reference instead of redefining a different flow.
| Command | When | Responsibility |
|---|---|---|
/pact.init |
Project start (one-time) | Interactive init; generates constitution, PAD draft, state |
/pact.scope |
Recommended before first feature; re-run when risk boundaries or product direction change | PACT applicability and risk-boundary assessment; FDG is optional |
/pact.pid |
Each feature start | Define feature intent, run boundary detection, generate PID Card |
/pact.contract |
After pid | Generate behavior contract (FC/NF entries) as the baseline for build and verify |
/pact.build |
After contract | TDD implementation (tests first, then code) |
/pact.verify |
After build | Adversarial verification: construct edge inputs, issue verdict based on real runtime output |
/pact.ship |
After verify PASS | Smoke tests, record completion, archive contract |
/pact.retro |
Every 3–5 features | Review contract quality, clean up technical debt |
your-project/
├── CLAUDE.md ← Hot layer, auto-loaded at session start
│ Contains: startup sequence / execution model / commands / file assembly rules
├── .claude/
│ └── commands/ ← 8 command files (per-command protocols)
│ ├── pact.init.md
│ ├── pact.scope.md
│ ├── pact.pid.md
│ ├── pact.contract.md
│ ├── pact.build.md
│ ├── pact.ship.md
│ ├── pact.verify.md
│ └── pact.retro.md
└── .pact/
├── state.md ← Hot layer, cross-session state machine
├── core/
│ ├── constitution.md ← Warm layer: project charter, hard constraints + file-naming rules
│ └── architecture.md ← Cold layer: load on demand
├── schemas/
│ ├── state.schema.json ← Draft structured state schema for future migration
│ └── queue.schema.json ← Draft structured queue schema, not active in v1.x
├── state.example.json ← Example only, not a runtime source
├── queue.example.json ← Example only, not a runtime source
├── scope/
│ ├── boundaries.md ← Boundary checklist (B-H / B-M risk rules)
│ └── fitness.md ← Adaptation assessment output (/pact.scope)
├── specs/ ← Project instances (generated by commands, not blank templates)
│ ├── PAD.md ← Product Architecture Document (/pact.init draft)
│ ├── FDG.md ← Optional Feature Dependency Graph (/pact.scope, explicit opt-in)
│ └── [feature]-pid.md ← Per-feature PID Cards (/pact.pid)
├── contracts/ ← Behavior contracts
│ ├── [feature].md ← Active feature contract
│ └── archive/ ← Completed contracts (/pact.ship)
├── templates/ ← Blank reference templates (never filled directly)
│ ├── PAD.md / FDG.md / IFD.md
│ ├── pid-card.md / contract.md / verify.md
│ ├── exec-plan.md / handover.md
│ └── README.md
├── hooks/
│ └── check-state.sh ← SessionStart hook (validates state.md vs filesystem)
├── exec-plans/
│ ├── active/ ← Active large-feature plans
│ └── completed/
├── knowledge/
│ ├── [feature]-verify.md ← Verify record (verdict + adversarial test results)
│ ├── tech-debt.md ← Technical debt tracking
│ ├── decisions/ ← Architecture decision archive
│ ├── errors/ ← Failure records
│ ├── handover/
│ └── archive/ ← Historical state / completed feature archive
└── tests/
├── features/
├── fixtures/
└── api/
All contract / verify / exec-plan / pid-card paths are derived from the feature-name field in state.md, following rules defined in constitution.md. The startup check compares the phase declared in state.md against the corresponding files; mismatch halts execution.
PACT adds global constraints without adding daily workflow steps:
PAD.mdis the Product Spine: product goal, core users and scenarios, core business flow, core entities and states, UX consistency rules, and feature type definitions.architecture.mdis the Architecture Spine: architecture principles, module boundaries, entity ownership, state machine ownership, permission location, write boundaries, dependency direction, and ADR triggers.- PID Cards map each feature to a PAD flow step or explicitly mark it as auxiliary, admin, or experimental.
- Build checks implementation against the Architecture Spine when a feature touches modules, entities, state machines, permissions, or dependencies.
This is not a PRD system or architecture governance platform. It is a lightweight global constraint layer for the existing pid -> contract -> build -> verify -> ship loop.
In v1.x, .pact/state.md remains the human-readable source of truth. PACT also includes a draft .pact/schemas/state.schema.json to define the future structured state shape, but it does not change the current runtime behavior.
PACT also includes draft-only structured examples for future migration: .pact/state.example.json, .pact/schemas/queue.schema.json, and .pact/queue.example.json. These are not runtime truth sources in v1.x.
State changes that tools need to perform should go through the controlled state entry:
bash .pact/bin/pact.sh state validate
bash .pact/bin/pact.sh state enqueue <feature>
bash .pact/bin/pact.sh state set-phase <phase>
bash .pact/bin/pact.sh state complete
bash .pact/bin/pact.sh state fail-verifypact-check.sh validates the basic state.md structure, runs logical consistency checks, and covers common invalid states with fixtures.
For time-based health diagnostics, run:
bash .pact/bin/pact.sh check --stalePACT checks that behavior contracts and verification records are structurally valid:
- contracts must include FC entries and explicit out-of-scope boundaries
- contracts must not contain obvious template placeholders
- verify records must include exactly one strict
verdict = PASS|FAIL|INCONCLUSIVEline - verify records reject speculative language such as "should", "expected", and "theoretically"
- PASS verify records must include a runtime evidence marker such as
output:orcommand:
PACT includes a command guard that checks whether a /pact.* command is allowed to start based on state.md and required artifacts.
bash .pact/bin/pact-guard.sh pid
bash .pact/bin/pact-guard.sh contract
bash .pact/bin/pact-guard.sh build
bash .pact/bin/pact-guard.sh verify
bash .pact/bin/pact-guard.sh shipThe guard does not execute commands, generate files, or modify state. It only reports whether the command may start.
PACT keeps agent entry files short and operational. Root AGENTS.md should point to the canonical workflow, use phase decisions and Don't/Do guidance, and avoid large reference lists. Module-level agent entries can be created from .pact/templates/module-AGENTS.md when a submodule needs local patterns or ownership boundaries.
bash .pact/bin/pact.sh lint-agents --allpact-lint-agents.sh checks the basic shape of agent entry files so they do not drift into long warning lists or unbounded documentation indexes.
Global Spine Lite checks:
bash .pact/bin/pact.sh lint-pad <file>
bash .pact/bin/pact.sh lint-architecture <file>
bash .pact/bin/pact.sh lint-pid <file|--all>These are lightweight structure checks. They do not grade product quality, UX quality, or architecture quality.
/pact.scope checks whether PACT is appropriate for the project and identifies risk boundaries before feature work starts.
It outputs one of three usage modes:
PACT-onlyPACT + specialist reviewDo not use PACT alone
FDG generation is optional. It should only be generated when the developer explicitly provides 3+ known features and wants dependency planning.
/pact.pid scans the current feature against boundaries.md:
| Level | Scope | Response |
|---|---|---|
| High risk (B-H) | Real-time comms / concurrent writes / financial ops / cross-user aggregation / multi-table transactions / sensitive data | Hard halt, wait for human decision |
| Mid risk (B-M) | Complex permissions / file handling / third-party integration / async tasks / complex queries / schema changes | Advisory note, may continue |
Large-feature gating (spans 3+ modules / schema changes / needs 2+ sessions / depends on 3+ unfinished features) → mandatory execution plan, requires human confirmation.
PACT now treats feature size as a protocol concern. A feature should fit one complete contract -> build -> verify -> ship loop. /pact.pid flags broad work early, and contract lint rejects contracts with more than 7 FC entries so oversized work is split or planned before build.
Durable cross-feature engineering knowledge belongs in .pact/knowledge/patterns.md. /pact.ship may promote stable learnings into this file, and /pact.retro cleans stale or story-specific entries. It is not a progress log or a replacement for AGENTS/module handover files.
Not code review, but active falsification. For each FC entry, construct edge inputs, run them for real, capture real output; inferential language is prohibited. Three possible verdicts: PASS / FAIL (roll back to build) / INCONCLUSIVE (triaged via a three-option protocol).
Semantic versioning: MAJOR.MINOR.PATCH
| Position | Trigger | Typical change |
|---|---|---|
| MAJOR | Breaking protocol change; initialized projects cannot upgrade smoothly | Commands added/removed/renamed; state-machine phase changes; file-naming rule changes; directory restructure |
| MINOR | Backward-compatible protocol extension | New optional Step or check; new template; new non-mandatory sub-protocol; hook capability enhancement |
| PATCH | No new standalone capability | Wording / typo fixes; internal consistency fixes; responsibility narrowing; template alignment; small adjustments to existing checks |
Version numbers change only for release-worthy change sets. Small edits may accumulate in local work or normal commits before a release. Milestones get git tags (
v1.0.0,v1.1.0,v2.0.0). Keep the last 10 entries in the table below; older entries move toCHANGELOG.md.
Detailed release notes are maintained in CHANGELOG.md. Release process details are documented in RELEASE.md.
| Version | Date | Core changes |
|---|---|---|
| v1.12.0 | 2026-05-07 | Adds Design Attachments Lite for optional product, sequence, and interaction design guidance; tightens spine checks and adoption docs |
| v1.11.0 | 2026-05-07 | Adds Global Spine Lite with Product Spine, Architecture Spine, spine lint checks, and an order-flow example |
| v1.10.0 | 2026-05-06 | Adds feature sizing, reusable patterns, and draft structured state / queue schemas |
| v1.9.0 | 2026-05-05 | Adds controlled state operations, logical state consistency checks, verify failure recovery, and stale diagnostics |
| v1.8.0 | 2026-04-30 | Adds AGENTS entry quality linting, module-level AGENTS templates, and clearer cross-tool entry responsibilities |
| v1.7.1 | 2026-04-28 | Adds a secure notes example, consolidates example and workflow references, and clarifies Windows self-check guidance |
| v1.7.0 | 2026-04-28 | Adds GitHub remote installers, automatic install mode detection for source installers, and direct project installation guidance |
| v1.6.1 | 2026-04-27 | Narrows /pact.scope to applicability and risk-boundary assessment; makes FDG optional; clarifies lower-frequency release rules |
| v1.6.0 | 2026-04-27 | Adds command guard for pid / contract / build / verify / ship entry checks and integrates guard fixtures into self-check |
| v1.5.0 | 2026-04-27 | Adds contract and verify lint scripts, fixtures, and self-check integration for behavior contract and verification record structure |
| v1.3.3 | 2026-04-27 | Adds CHANGELOG.md as canonical release history and requires changelog coverage in repository self-checks |