Skip to main content

pactkit-codex

PactKit PDCA workflow framework adapted for OpenAI Codex CLI.

PyPI version Python 3.10+ License: MIT

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.

Metadata

Release files for pactkit-codex 4.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pactkit-codex 4.4.1
File Size Uploaded Provenance Actions
pactkit_codex-4.4.1.tar.gz 35.2 kB With provenance Details for pactkit_codex-4.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pactkit-codex 4.4.1
File Interpreter ABI Platform Actions
pactkit_codex-4.4.1-py3-none-any.whl Python 3 none any Details for pactkit_codex-4.4.1-py3-none-any.whl

Total release size: 60.4 kB

Release files / pactkit_codex-4.4.1.tar.gz

Download URL pactkit_codex-4.4.1.tar.gz
Size 35.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e8f462488b75b3f286b643762eb4d20cc9fa4cd601823cc2ed1134889c8e168b
BLAKE2b-256 checksum
How to use checksums
36cffcf2b359088235604de2a4387bca754845aa8fd3da4ca1d39885ce99108d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / pactkit_codex-4.4.1-py3-none-any.whl

Download URL pactkit_codex-4.4.1-py3-none-any.whl
Size 25.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07b336a28057dda868bcae53ba631e32f416812804e00213b15bc60e800af729
BLAKE2b-256 checksum
How to use checksums
c2ae6a31468aa3990a7749169aa4a8c6c319c7063a5bad44b3793eea7987d2ac
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for pactkit-codex 4.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pactkit_codex-4.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.4.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page