pactkit 3.0.1

CODE is the Law. Data is the Truth. Prompt is ONLY instruction. AI is ONLY creativity.

PactKit (Pact 契约 + Kit) is a lightweight dev-enablement scaffold: it gives AI coding assistants the standards, specs and methods of a disciplined engineering workflow, without getting in the way. Ordinary questions and ordinary coding never activate the workflow — you opt in per task. There is no admin plane, no central control, and nothing that cannot be uninstalled.

Deterministic operations run as code, not prompts (CODE is the Law). Decisions are grounded in data, not memory (Data is the Truth). 56 CLI subcommands, 9 specialized agents, 12 commands, 25 skills, and a Plan-Act-Check-Done lifecycle you invoke when you want it. One pip install deploys to all 4 supported IDEs (adapters are opt-in extras).

Supported AI Tools

pactkit init deploys all 4 IDE formats at once. Use --format <name> to target a single IDE.

Gate coverage differs by host: Claude Code and Codex CLI get the full gate set through native hooks; OpenCode and Copilot fall back to the git-hook layer, which covers the commit and push gates but not the pre-tool ones (auth_gate, secrets_gate, tamper_guard, spec_guard).

What it looks like

You:  /project-sprint "Add OAuth2 login"

 Plan   System Architect scans codebase, writes Spec, updates Board
 Act    Senior Developer writes tests first (RED), then code (GREEN)
 Check  QA Engineer runs 6-phase audit (security + quality + spec alignment)
 Done   Repo Maintainer gates regression, archives story, commits

The P.A.C.T. Governance Contract

The name says it all — Pact means covenant. These four principles define the boundary between human intent and AI execution:

P   Prompt   is ONLY instruction   Tells AI how to act — defines process, never state
A   AI       is ONLY creativity    Formatting, summarization, language — never deterministic logic
C   Code     is the Law            Sole executor of deterministic operations — no bypass, no approximation
T   Truth    Data is the Truth     Factual basis for all judgment — no memory, no inference, no fabrication

• If a script exists → use it. Never reimplement in natural language. (C)
• If data is available → read it. Never guess or recall from memory. (T)
• Prompts define HOW, never WHAT. Current state comes from data, not docs. (P)
• AI formats, summarizes, and creates. AI does not parse, compute, or fabricate. (A)

Read the full philosophy: docs/architecture/governance/philosophy.md

Why PactKit?

• P.A.C.T. Governance — A contract between humans and AI agents, with clear boundaries
• Multi-Agent Ensemble — 9 specialized agents collaborate, each with constrained tools
• Full PDCA Lifecycle — Plan -> Act -> Check -> Done, with quality gates at every stage
• Safe by Design — TDD-first, safe regression, pre-existing test protection
• Multi-Tool Support — Works with Claude Code, OpenCode, and Codex CLI
• AI-Native SDLC, Operationalized — The artifact chain, gates, and audit trail that Anthropic's engineering practice describes — running across all 3 hosts

AI-Native SDLC Alignment

Anthropic's engineering team has published their practice for an AI-native software development lifecycle: six stages, each producing a committed artifact, humans at the gates, and the commit chain as the audit trail. PactKit operationalizes that model today — across all 3 supported hosts:

Beyond the published practice: the same governance runs on Claude Code, OpenCode, and Codex CLI; interrupted sessions leave machine-observable outcome_unknown fences that block resume until the gate re-runs; and every gate decision lands in .pactkit/enforcement/ as an audit record.

Installation

pip install pactkit

Requires Python 3.10+ and one of:

• Claude Code
• OpenCode
• Codex CLI

The base install ships the gate chain: pre-commit (Git hook scheduling) and detect-secrets (credential detection) are standard dependencies — no extra required for the default workflow. Host adapters remain opt-in extras:

Optional Extras

pip install pactkit[opencode]    # OpenCode adapter
pip install pactkit[codex]       # Codex CLI adapter
pip install pactkit[lint]        # Includes ruff for lint gate
pip install pactkit[visualize]   # tree-sitter analyzers (Go/Java/TS complexity, layers)
pip install pactkit[test]        # pytest + tomli (Python 3.10) for the test suite
pip install pactkit[all]         # Everything above

Recommended External Tools

These tools enhance PactKit but cannot be distributed via pip. Run pactkit deps check to see what's missing and pactkit deps install for guided platform-aware installation:

Quick Start

# Deploy to all 3 IDEs at once
pactkit init

# Update to latest playbooks (preserves your custom content in CLAUDE.md)
pactkit update

# Deploy to one IDE only
pactkit init --format classic    # Claude Code
pactkit init --format opencode   # OpenCode
pactkit init --format codex      # Codex CLI

Then in any project:

# Clarify — Surface ambiguities before planning
/project-clarify "Add user authentication"

# Plan — Analyze requirements, create Spec
/project-plan "Add user authentication"

# Act — Spec lint + consistency check + TDD implementation
/project-act STORY-001

# Check — Security scan + quality audit (P0-P3 severity)
/project-check

# Done — Regression gate + auto-PR + conventional commit
/project-done

Or run the full cycle in one command:

/project-sprint "Add user authentication"

PDCA+ Workflow

When to Use What

The core loop is Plan → Act → Done. Other commands plug in as needed:

You have a task
  │
  ├─ Vague idea, multiple features? ──→ /project-design
  │
  ├─ Unclear requirement? ──→ /project-clarify → /project-plan
  │
  ├─ Clear feature or bug?
  │   │
  │   ├─ Small fix (1 file, obvious)? ──→ /project-hotfix
  │   │
  │   └─ Needs design? ──→ /project-plan → /project-act
  │       │
  │       ├─ Security-sensitive? ──→ /project-check (QA audit)
  │       │
  │       └─ /project-done
  │           │
  │           ├─ On feature branch? ──→ /project-pr
  │           └─ Ready to release? ──→ /project-release
  │
  └─ Fully automated? ──→ /project-sprint (runs all phases)

Solo developer? Start with /project-plan → /project-act → /project-done. Add /project-hotfix for small fixes and /project-check when security matters.

Embedded Skills (auto-invoked by commands)

Agent Skills (invoked via agent roles)

Agent Ensemble

PactKit deploys 9 specialized agents, each with constrained tools and focused responsibilities:

Skills

PactKit deploys 25 skills. That total is the 12 PDCA commands (registered as skills, so /project-plan and pactkit-visualize deploy the same way) plus the 13 tool skills below, auto-invoked by commands:

13 tool skills (4 scripted + 9 prompt-only):

CLI Subcommands

PactKit ships 56 deterministic CLI subcommands — operations that were previously delegated to AI prompts are now enforced in Python code (the "C" in P.A.C.T.):

Commit Path Convergence (2.26.0)

• Single test executor: worktree and core.hooksPath layouts resolve the real git hooks path — the host PreToolUse pass defers to the shared git pre-commit hook instead of double-running the suite.
• Real incremental selection: a changed test file maps to itself (test_X.py runs test_X.py); an empty mapping runs the fast layer with an explicit full-suite recommendation instead of silently escalating; polyglot repos run every detected workspace's native test command.
• Observability: the gate prints its plan (strategy, reason, command, scope) before any test runs, streams pytest output, and records per-phase timings into the enforcement record.
• Staged-first scope: the gate checks what this commit will introduce (git diff --cached); unstaged work is reported as excluded.

Verification Facts & Governance (2.26.0)

• Verification records are keyed by content fingerprint (cross-story reuse); with no fresh, unambiguous preflight receipt the post-commit stamp lands unattributed instead of guessing a story.
• PreCompact writes a lightweight marker — one context generation per compaction cycle.
• The spec guard binds a receipt only while its spec hash matches and the receipt is fresh (expired/drifted receipts unlock with a reason).
• telemetry.enabled: false skips event-stream writes without touching gate semantics.

Engineering Guidance by Gap (2.26.0)

• The reuse classification (availability / applicability / decisions / evidence) lives once in the shared lifecycle capsule loaded by all four phases; Act loads guidance by gap — an empty pactkit risk result is never "no risk", 0 guides is valid when there is no gap, and confirmed risks past the first three are still read and verified.
• pactkit risk --json returns the full per-concern decisions for review.

Enforcement Gates (2.25.0)

The hook layer enforces the rules prompt text can only state — protected branches, specs, credentials, and external effects survive a conflicting instruction instead of losing to it:

All blocks/bypasses are audited (.pactkit/enforcement/) and feed pactkit stats as gate telemetry (per-gate block counts, per-command invocation counts, authorization pairs) — the friction data that decides what to tune next.

Gate Chain: pre-commit + detect-secrets (3.0.0)

The Git-hook layer is pre-commit (the upstream scheduler) plus detect-secrets (the upstream credential engine) — both standard install dependencies, so a plain pip install gets the full chain:

The generated .pre-commit-config.yaml is shareable: entries name pactkit on PATH (never a machine-local absolute path), so the same file works for every developer, on Linux CI, and after a reinstall. Install PactKit per machine (pipx install pactkit); if it is missing, pre-commit stops the commit with Executable \pactkit` not found` — a loud failure, never a silent pass.

pre-push limits (pre-commit's own behaviour, printed by pactkit doctor and listed in the support matrix): a push carrying several refspecs surfaces only its first ref to the policy, and deleting a remote ref does not run the pre-push stage at all. Protected-branch deletion protection belongs on the server, not in a local hook.

Migrate an existing project with pactkit commit-gate --install --migrate (preflight read-only: pactkit commit-gate --install --check) — it also rewrites entries an older PactKit recorded as absolute paths. The first pactkit command in a project after an install or upgrade runs a one-time project-level check (config drift, graph views, gate chain) and reports the exact next command for each finding — nothing is modified.

Codegraph is the single source of code facts (3.0.0)

Code-relationship data comes from Codegraph: queries (pactkit query --callers/--callees/--chain/--impact/--explore), audit insights, and diagrams all read the same index. pactkit visualize renders docs/architecture/graphs/*.mmd as human-readable views from that index — no self-built scanner, and no index means a clear error (pactkit sync first), never a silent fallback.

The legacy MMD tracing engine is retired. Your existing .mmd files are never deleted or rewritten for you — pactkit doctor lists verifiably-old tracing outputs with per-file cleanup advice, and manual diagrams (system_design, workflow, Spec diagrams) remain first-class.

Deployment Architecture

PactKit supports four deployment formats:

Claude Code (Classic)

~/.claude/
├── CLAUDE.md                 <- Project context entry point
├── rules/                    <- 21 rule modules (loaded per-command, not globally)
├── skills/                   <- 25 skill packages (12 commands + 13 tool skills)
└── agents/                   <- 9 agent definitions

Commands are deployed as skills (skills/project-*/SKILL.md), invoked with /project-plan.

OpenCode

~/.config/opencode/
├── AGENTS.md                 <- On-demand @reference index (lazy rule loading)
├── rules/                    <- 21 rule modules
├── commands/                 <- 12 command playbooks (auto-discovered, invoked via /)
├── agents/                   <- 9 agent definitions (mode: subagent)
├── skills/                   <- 13 tool skills (AI agent loads on demand)
└── opencode.json             <- Global config (model routing, instructions)

OpenCode uses dual mechanism: commands/ for user-facing PDCA entry points, skills/ for AI-invoked tools.

Codex CLI

~/.codex/
├── AGENTS.md                 <- Global constitution
├── config.toml               <- Model, sandbox, MCP config
├── rules/                    <- 21 rule modules
├── skills/                   <- 25 skill packages (12 commands + 13 tool skills)
└── .pactkit-version          <- Version marker for updates

Commands are deployed as skills (skills/project-*/SKILL.md), invoked with $project-plan.

Multi-Developer Collaboration

PactKit supports multi-developer workflows with Story ID prefixing:

# In pactkit.yaml
developer: alice

Story IDs become STORY-alice-001, preventing merge conflicts when multiple developers work on separate branches.

Project Structure (PDCA-managed)

PactKit's PDCA lifecycle manages a docs/ directory:

docs/
├── product/
│   ├── stories/                 <- One workflow/task fact file per Story
│   └── sprint_board.md          <- Optional generated read-only projection
├── specs/                       <- The Law — requirement specifications
├── test_cases/                  <- Gherkin acceptance scenarios
└── architecture/
    ├── graphs/                  <- Architecture graph files (Mermaid .mmd)
    ├── governance/
    │   ├── rules.md             <- Architecture decisions and invariants
    │   └── lessons/             <- One immutable record per lesson
    └── snapshots/               <- Versioned architecture graph snapshots

Session context is generated locally at .pactkit/context.md and is ignored by Git.

pactkit.yaml Configuration Reference

Which file is read (per-host since 2026-09-18). Config resolves in layers, lowest precedence first:

So a Claude Code session reads pactkit.yaml then .claude/pactkit.yaml; a bare-terminal git commit reads pactkit.yaml alone. Put policy that must hold everywhere in the shared file, and per-terminal differences in the host file. pactkit schema config prints the host, the layers, and each key's source; pactkit doctor prints the layers too. Copies are no longer flattened automatically — pactkit update --sync-config-copies does that, explicitly, when you want one shared config after all.

Safe Regression

PactKit's safe regression system prevents agents from blindly modifying pre-existing tests:

• TDD Loop — Only iterates on tests created in the current story
• Regression Check — Read-only gate; pre-existing test failure = STOP and report
• Done Gate — Full regression by default; incremental only when ALL safety conditions are met

Hierarchy of Truth (the "T" in P.A.C.T.)

Tier 1: Specs & Test Cases           <- The Law (CODE is the Law)
Tier 2: Tests                        <- The Verification (DATA is the Truth)
Tier 3: Implementation               <- The Mutable Reality

When conflicts arise: Spec wins. Always. The agent modifies code, never the spec.

MCP Integration

As of 2.26.0, PactKit is a lightweight development-enablement scaffold with zero MCP server injection — pactkit init no longer registers any server, and the self-hosted governance MCP server is retired (pactkit mcp prints the retirement note and migration path). Host-side MCP servers you configure yourself (Context7, Playwright, Chrome DevTools, Memory, …) still work: the playbooks reference them conditionally and skip gracefully when unavailable.

All MCP instructions are conditional — gracefully skipped when unavailable.

Upgrading

pip install --upgrade pactkit
pactkit update    # Updates all deployed IDEs

Use pactkit update --format <name> to update a single IDE.

Rolling back is pip install pactkit==<previous-version> followed by pactkit update (pin the adapters to the same window in the same command). pactkit doctor reports a deployment whose files no longer match the installed CLI, which is how a partial rollback shows up.

After an upgrade, the first pactkit command in each project runs a one-time project-level check (config drift, graph views, gate chain) and reports the exact next command for anything stale — see Gate Chain above. It is read-only and runs once per project per version.

Upgrading from a version older than 2.27.0? Audit records written before 2.27.0 could persist credential-shaped text — run the one-time sweep in the credential incident response guide before calling the upgrade done.

Upgrading to 3.0.0

3.0.0 replaces the Git-hook layer and the credential engine, and changes how pactkit.yaml is found. Nothing runs automatically — here is the whole list:

Rolling back a 3.0.0 upgrade: pip install pactkit==2.27.0 (and the adapters in the same command), then pactkit update. To restore the old Git hooks as well, pactkit commit-gate --uninstall-chain removes PactKit's entries and shims without touching your own checks or your baseline.

Restricted and CI Environments

pactkit init and pactkit update accept flags for environments that cannot reach the network or answer prompts:

PactKit never sends your code or usage data anywhere. Telemetry is written locally under .pactkit/events/ and can be turned off with telemetry.enabled: false. The only network access is the package index you install from.

Troubleshooting

Start with pactkit doctor — it reports configuration drift, deployment parity against the installed CLI, adapter version skew, hook registration, and rule health. pactkit doctor --json emits the same data for scripts.

Further reading: the support matrix (hosts × gates × platforms, what each host actually gets), the credential incident response guide (pre-2.27.0 audit-record sweep), and the release & recovery runbook (second-person drill — build, verify, release, recover from the shipped artifacts).

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT