pactkit 2.26.0

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). 52 CLI subcommands, 9 specialized agents, 12 commands, 13 skills, and a Plan-Act-Check-Done lifecycle you invoke when you want it. One pip install deploys to all 3 supported IDEs (adapters are opt-in extras).

Supported AI Tools

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

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 is dependency-light (pyyaml only). Host adapters are opt-in extras — install the ones for the IDEs you use:

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]   # Includes tree-sitter for AST analysis
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 13 skills (4 scripted + 9 prompt-only), auto-invoked by commands:

CLI Subcommands

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

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.

Deployment Architecture

PactKit supports three deployment formats:

Claude Code (Classic)

~/.claude/
├── CLAUDE.md                 <- Project context entry point
├── rules/                    <- 8 rule modules (loaded per-command, not globally)
├── skills/                   <- 21 skill packages (11 commands + 10 embedded)
└── 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/                    <- 8 rule modules (3 core always-load + 6 on-demand)
├── commands/                 <- 11 command playbooks (auto-discovered, invoked via /)
├── agents/                   <- 9 agent definitions (mode: subagent)
├── skills/                   <- 10 skill packages (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/                    <- 8 rule modules
├── skills/                   <- 21 skill packages (11 commands + 10 embedded)
└── .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

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

PactKit conditionally integrates with MCP servers when available:

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.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT