pactkit-codex

PactKit PDCA workflow framework adapted for OpenAI Codex CLI.

What is this?

pactkit-codex brings the PactKit spec-driven development workflow to OpenAI's Codex CLI. It deploys:

• AGENTS.md — Global constitution with agent roles and PDCA routing
• Command Skills — PDCA workflow entries ($project-plan, $project-act, etc.)
• Skills — Standalone Python scripts (visualize, board, scaffold)
• Rules — Modular governance rules loaded on-demand per command

Installation

pip install pactkit

pactkit-codex is automatically installed as a dependency of pactkit.

Quick Start

# Deploy PactKit configuration to ~/.codex/
pactkit-codex init

# Update when pactkit-codex is upgraded
pactkit-codex update

# Check version
pactkit-codex version

What Gets Deployed

After running pactkit-codex init:

~/.codex/
├── AGENTS.md              # Global constitution (~6KB)
├── config.toml            # Model, sandbox, MCP config
├── .pactkit-version       # Version marker for updates
├── rules/                 # 9 rule files (on-demand loading)
│   ├── 01-core-protocol.md
│   ├── 02-hierarchy-of-truth.md
│   └── ...
└── skills/                # Skills and PDCA command entries
    ├── pactkit-visualize/
    ├── project-plan/
    ├── pactkit-board/
    └── ...

./                         # Project root
├── AGENTS.md              # Project instructions (PactKit-managed)
└── .codex/
    ├── pactkit.yaml       # Project config
    └── AGENTS.local.md    # Your custom instructions (never overwritten)

Commands

Initialization

pactkit-codex init                    # Full deployment
pactkit-codex init -t /tmp/preview    # Deploy to custom directory

Update

pactkit-codex update                  # Incremental update (if version changed)
pactkit-codex update --if-needed      # Silent no-op if current (for hooks)
pactkit-codex update --force          # Force redeploy even if current
pactkit-codex update --dry-run        # Show what would change

Utilities

pactkit-codex version                 # Show version
pactkit-codex spec-lint <file>        # Validate spec structure
pactkit-codex doctor                  # Check project health
pactkit-codex visualize --lazy        # Generate code dependency graphs

PactKit commands run directly in the current Codex session. They do not dispatch a separate runner, require a run ID, or create a resumable background workflow.

PDCA Workflow Commands

Once deployed, use these commands in Codex CLI (prefix $):

Command	Phase	Purpose
$project-init	Bootstrap	Initialize project governance
$project-design	Plan	Greenfield product design
$project-plan	Plan	Break down requirements into specs
$project-act	Act	Implement code per spec (TDD)
$project-check	Check	QA verification
$project-done	Done	Finalize and document
$project-release	Done	Version release
$project-pr	Done	Create pull request
$project-hotfix	Act	Quick fix bypass
$project-clarify	Plan	Clarify requirements

Project Structure

Your project should have:

your-project/
├── AGENTS.md                    # PactKit-managed (auto-generated)
├── .codex/
│   ├── pactkit.yaml             # Project config
│   └── AGENTS.local.md          # Your custom instructions
├── docs/
│   ├── specs/                   # Requirement specifications
│   │   ├── STORY-001.md
│   │   └── ...
│   └── product/
│       ├── sprint_board.md      # Current sprint tasks
│       └── context.md           # Project context (auto-generated)
└── tests/
    ├── unit/
    └── e2e/

Codex CLI vs Claude Code

This project adapts PactKit for Codex CLI, which has different capabilities:

Feature	Claude Code	Codex CLI	pactkit-codex Solution
Multi-agent	Native	Single agent	Prompt-level role conventions
Custom commands	/project-*	$project-*	Deploy to ~/.codex/skills/project-*/SKILL.md
Rule loading	@import	None	Agentic routing (Prerequisites header)
Config	settings.json	config.toml	Generate with defaults

Configuration

pactkit.yaml

stack: python          # Detected automatically
version: 0.0.1         # Your project version
root: .
developer: ""          # Optional: your name prefix for Story IDs

Custom Instructions

Add your project-specific instructions to .codex/AGENTS.local.md:

# Project Local Instructions

## Build Commands
- Run tests: `pytest tests/ -v`
- Lint: `ruff check src/`

## Project Conventions
- Use snake_case for Python
- All APIs must have OpenAPI docs

This file is never overwritten by pactkit-codex updates.

Development

# Clone
git clone https://github.com/anthropics/pactkit-codex.git
cd pactkit-codex

# Install dev dependencies
pip install -e ".[multilang]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

License

MIT License - see LICENSE for details.

Related Projects

• PactKit — Core framework
• pactkit-opencode — Adapter for OpenCode IDE
• Codex CLI — OpenAI's terminal-based AI coding assistant