pactkit 2.10.6

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

PactKit (Pact 契约 + Kit) is a governance framework that enforces the P.A.C.T. contract between humans and AI agents. Deterministic operations run as code, not prompts. Decisions are grounded in data, not memory. AI does what it's best at — creativity and language — while code handles everything that must be repeatable and correct.

25 CLI subcommands, 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One pip install deploys to all 3 supported IDEs.

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

Installation

pip install pactkit

Requires Python 3.10+ and one of:

• Claude Code
• OpenCode
• Codex CLI

pip install pactkit automatically installs adapters for all 3 IDEs.

Quick Start

# Deploy to all 3 IDEs at once
pactkit init

# Update to latest playbooks (preserves your config)
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 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands:

CLI Subcommands

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

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/
│   ├── sprint_board.md          <- Current iteration board
│   ├── context.md               <- Auto-generated session context
│   └── archive/                 <- Archived completed stories
├── 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.md           <- Lessons learned per story
    └── snapshots/               <- Versioned architecture graph snapshots

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