pactkit-codex 0.1.0__tar.gz

pactkit_codex-0.1.0/.claude/CLAUDE.local.md

@@ -0,0 +1,70 @@
+# pactkit-codex (v0.1.0)
+
+> PactKit PDCA workflow framework adapted for OpenAI Codex CLI.
+
+## Project Status
+
+**v0.1.0 Feature Complete** — 16 stories/bugs done, 126 tests passing.
+
+Core deployment chain works:
+```bash
+pactkit-codex init --format codex   # Deploy to ~/.codex/
+```
+
+## Architecture Decisions
+
+### Codex CLI Constraints (vs Claude Code)
+
+| Capability | Claude Code | Codex CLI | Our Solution |
+|------------|-------------|-----------|--------------|
+| Multi-agent | Native | Single agent | Prompt-level role conventions |
+| Custom commands | `/project-*` | `/prompts:*` | Deploy to `~/.codex/prompts/` |
+| Rule loading | `@import` | None | Agentic routing (Prerequisites header) |
+| Config | `settings.json` | `config.toml` | Generate with PactKit defaults |
+
+### Dual-File Architecture (STORY-010)
+
+```
+./AGENTS.md                    # PactKit-managed (always regenerated)
+.codex/
+├── pactkit.yaml               # Project config
+└── AGENTS.local.md            # User-owned (never overwritten)
+```
+
+### Per-Command Rule Loading (STORY-011)
+
+Rules extracted to `~/.codex/rules/` (9 files). Each prompt declares its prerequisites:
+```markdown
+## Prerequisites — Read These Rules First
+- `~/.codex/rules/01-core-protocol.md`
+- `~/.codex/rules/09-credential-safety.md`
+```
+
+`COMMAND_RULES_MAP` in `rules.py` is the single source of truth.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/pactkit_codex/generators/deployer.py` | Main deployment orchestrator |
+| `src/pactkit_codex/prompts/rules.py` | Rule modules + COMMAND_RULES_MAP |
+| `src/pactkit_codex/profiles.py` | FormatProfile (paths, config) |
+| `tests/unit/` | 126 unit tests |
+| `tests/e2e/` | E2E deployment verification |
+
+## Deploy Output Structure
+
+```
+~/.codex/
+├── AGENTS.md              # Global constitution (~6KB, roles + routing + rule index)
+├── config.toml            # Model, sandbox, MCP config
+├── rules/                 # 9 rule files (on-demand loading)
+├── prompts/               # 10 command prompts (project-act, project-plan, etc.)
+└── skills/                # 10 skills (visualize, board, scaffold, etc.)
+```
+
+## Future Work
+
+- [ ] Migrate commands to Codex Skills (prompts deprecated upstream)
+- [ ] Add `pactkit-codex update` for incremental upgrades
+- [ ] Test with actual Codex CLI TUI session

pactkit_codex-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,14 @@
+# pactkit-codex — Project Context
+
+## Dev Commands
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Lint
+ruff check src/ tests/
+```
+
+@./docs/product/context.md
+@./.claude/CLAUDE.local.md

pactkit_codex-0.1.0/.claude/pactkit.yaml

@@ -0,0 +1,140 @@
+# PactKit Configuration
+# Edit this file to customize which components are deployed.
+# Remove items from a list to disable them. Default: all enabled.
+
+version: "2.4.0"
+stack: auto
+root: .
+developer: ""
+
+# Agents — AI role definitions
+agents:
+  - code-explorer
+  - product-designer
+  - qa-engineer
+  - repo-maintainer
+  - security-auditor
+  - senior-developer
+  - system-architect
+  - system-medic
+  - visual-architect
+
+# Commands — PDCA playbooks
+commands:
+  - project-act
+  - project-check
+  - project-clarify
+  - project-design
+  - project-done
+  - project-hotfix
+  - project-init
+  - project-plan
+  - project-pr
+  - project-release
+  - project-sprint
+
+# Skills — tool scripts
+skills:
+  - pactkit-analyze
+  - pactkit-board
+  - pactkit-doctor
+  - pactkit-draw
+  - pactkit-release
+  - pactkit-review
+  - pactkit-scaffold
+  - pactkit-status
+  - pactkit-trace
+  - pactkit-visualize
+
+# Rules — constitution modules
+rules:
+  - 01-core-protocol
+  - 02-hierarchy-of-truth
+  - 03-file-atlas
+  - 04-routing-table
+  - 05-workflow-conventions
+  - 06-mcp-integration
+  - 07-shared-protocols
+  - 08-architecture-principles
+  - 09-sectional-write
+
+# CI/CD — set provider to github or gitlab to generate pipeline config
+ci:
+  provider: none
+  # runner: ubuntu-latest
+  # language_version: "3.11"
+  # github_host: ""  # GHE server (empty = github.com)
+  # actions_ref: ""  # GHE actions prefix
+
+# Issue Tracker — set provider to github to link stories to issues
+issue_tracker:
+  provider: none
+
+# Hooks — safe, report-only hook templates (command-type only)
+hooks:
+  post_test_coverage: false
+  pre_commit_lint: false
+  pre_push_check: false
+
+# Lint — configure lint behavior in /project-done
+lint_blocking: false
+auto_fix: false
+
+# Virtual Environment — configure venv detection and paths
+venv:
+  auto_detect: true
+
+# Release — configure release automation behavior
+release:
+  github_release: false
+
+# Regression — configure impact-based test selection strategy
+regression:
+  strategy: impact
+  max_impact_tests: 50
+
+# Check — configure QA verification behavior
+check:
+  security_checklist: true
+  security_scope_override: none
+
+# Done — configure commit and lesson quality behavior
+done:
+  lesson_quality_threshold: 15
+
+# E2E Testing — configure end-to-end test strategy (none|cli|frontend|backend|fullstack)
+e2e:
+  type: none
+  blocking: false
+  test_dir: tests/e2e
+  env_file: .env.test
+  api_spec: ""  # OpenAPI spec path for frontend/backend
+  compose_file: docker-compose.test.yml  # for fullstack
+
+# Visualize — configure directory scan exclusions
+visualize:
+  scan_excludes:
+    - venv
+    - _venv
+    - .venv
+    - .env
+    - env
+    - __pycache__
+    - .git
+    - .claude
+    - tests
+    - docs
+    - node_modules
+    - site-packages
+    - dist
+    - build
+
+# Command Models — override model per command for OpenCode deployment
+command_models:
+  project-act: sonnet
+  project-check: sonnet
+  project-done: sonnet
+  project-hotfix: sonnet
+  project-init: sonnet
+  project-pr: sonnet
+  project-release: sonnet

pactkit_codex-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+*.log

pactkit_codex-0.1.0/AGENTS.md

@@ -0,0 +1,4 @@
+# pactkit-codex
+
+@./docs/product/context.md
+output MUST use Chinese

pactkit_codex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Anthropic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pactkit_codex-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: pactkit-codex
+Version: 0.1.0
+Summary: PactKit PDCA workflow framework adapted for OpenAI Codex CLI
+Project-URL: Homepage, https://github.com/anthropics/pactkit-codex
+Project-URL: Repository, https://github.com/anthropics/pactkit-codex
+Project-URL: Documentation, https://github.com/anthropics/pactkit-codex#readme
+Project-URL: Issues, https://github.com/anthropics/pactkit-codex/issues
+Author: Slim
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,code-assistant,code-quality,codex,codex-cli,developer-tools,devops,openai,pdca,scaffold,spec-driven,tdd
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: multilang
+Requires-Dist: tree-sitter-go>=0.25; extra == 'multilang'
+Requires-Dist: tree-sitter-java>=0.23; extra == 'multilang'
+Requires-Dist: tree-sitter-typescript>=0.23; extra == 'multilang'
+Requires-Dist: tree-sitter>=0.25; extra == 'multilang'
+Description-Content-Type: text/markdown
+
+# pactkit-codex
+
+> PactKit PDCA workflow framework adapted for [OpenAI Codex CLI](https://github.com/openai/codex).
+
+[![PyPI version](https://badge.fury.io/py/pactkit-codex.svg)](https://pypi.org/project/pactkit-codex/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is this?
+
+**pactkit-codex** brings the [PactKit](https://github.com/pactkit/pactkit) spec-driven development workflow to OpenAI's Codex CLI. It deploys:
+
+- **AGENTS.md** — Global constitution with agent roles and PDCA routing
+- **Command prompts** — 10 PDCA workflow commands (`/project-plan`, `/project-act`, etc.)
+- **Skills** — Standalone Python scripts (visualize, board, scaffold)
+- **Rules** — Modular governance rules loaded on-demand per command
+
+## Installation
+
+```bash
+pip install pactkit-codex
+```
+
+## Quick Start
+
+```bash
+# 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
+│   └── ...
+├── prompts/               # 10 PDCA command prompts
+│   ├── project-plan.md
+│   ├── project-act.md
+│   └── ...
+└── skills/                # 10 skill directories
+    ├── pactkit-visualize/
+    ├── 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
+
+```bash
+pactkit-codex init                    # Full deployment
+pactkit-codex init -t /tmp/preview    # Deploy to custom directory
+```
+
+### Update
+
+```bash
+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
+
+```bash
+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
+```
+
+## PDCA Workflow Commands
+
+Once deployed, use these commands in Codex CLI:
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/prompts:project-init` | Bootstrap | Initialize project governance |
+| `/prompts:project-design` | Plan | Greenfield product design |
+| `/prompts:project-plan` | Plan | Break down requirements into specs |
+| `/prompts:project-act` | Act | Implement code per spec (TDD) |
+| `/prompts:project-check` | Check | QA verification |
+| `/prompts:project-done` | Done | Finalize and document |
+| `/prompts:project-release` | Done | Version release |
+| `/prompts:project-pr` | Done | Create pull request |
+| `/prompts:project-hotfix` | Act | Quick fix bypass |
+| `/prompts: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-*` | `/prompts:*` | Deploy to `~/.codex/prompts/` |
+| Rule loading | `@import` | None | Agentic routing (Prerequisites header) |
+| Config | `settings.json` | `config.toml` | Generate with defaults |
+
+## Configuration
+
+### pactkit.yaml
+
+```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`:
+
+```markdown
+# 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
+
+```bash
+# 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](LICENSE) for details.
+
+## Related Projects
+
+- [PactKit](https://github.com/pactkit/pactkit) — Original framework for Claude Code
+- [Codex CLI](https://github.com/openai/codex) — OpenAI's terminal-based AI coding assistant

pactkit_codex-0.1.0/README.md

@@ -0,0 +1,196 @@
+# pactkit-codex
+
+> PactKit PDCA workflow framework adapted for [OpenAI Codex CLI](https://github.com/openai/codex).
+
+[![PyPI version](https://badge.fury.io/py/pactkit-codex.svg)](https://pypi.org/project/pactkit-codex/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is this?
+
+**pactkit-codex** brings the [PactKit](https://github.com/pactkit/pactkit) spec-driven development workflow to OpenAI's Codex CLI. It deploys:
+
+- **AGENTS.md** — Global constitution with agent roles and PDCA routing
+- **Command prompts** — 10 PDCA workflow commands (`/project-plan`, `/project-act`, etc.)
+- **Skills** — Standalone Python scripts (visualize, board, scaffold)
+- **Rules** — Modular governance rules loaded on-demand per command
+
+## Installation
+
+```bash
+pip install pactkit-codex
+```
+
+## Quick Start
+
+```bash
+# 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
+│   └── ...
+├── prompts/               # 10 PDCA command prompts
+│   ├── project-plan.md
+│   ├── project-act.md
+│   └── ...
+└── skills/                # 10 skill directories
+    ├── pactkit-visualize/
+    ├── 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
+
+```bash
+pactkit-codex init                    # Full deployment
+pactkit-codex init -t /tmp/preview    # Deploy to custom directory
+```
+
+### Update
+
+```bash
+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
+
+```bash
+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
+```
+
+## PDCA Workflow Commands
+
+Once deployed, use these commands in Codex CLI:
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/prompts:project-init` | Bootstrap | Initialize project governance |
+| `/prompts:project-design` | Plan | Greenfield product design |
+| `/prompts:project-plan` | Plan | Break down requirements into specs |
+| `/prompts:project-act` | Act | Implement code per spec (TDD) |
+| `/prompts:project-check` | Check | QA verification |
+| `/prompts:project-done` | Done | Finalize and document |
+| `/prompts:project-release` | Done | Version release |
+| `/prompts:project-pr` | Done | Create pull request |
+| `/prompts:project-hotfix` | Act | Quick fix bypass |
+| `/prompts: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-*` | `/prompts:*` | Deploy to `~/.codex/prompts/` |
+| Rule loading | `@import` | None | Agentic routing (Prerequisites header) |
+| Config | `settings.json` | `config.toml` | Generate with defaults |
+
+## Configuration
+
+### pactkit.yaml
+
+```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`:
+
+```markdown
+# 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
+
+```bash
+# 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](LICENSE) for details.
+
+## Related Projects
+
+- [PactKit](https://github.com/pactkit/pactkit) — Original framework for Claude Code
+- [Codex CLI](https://github.com/openai/codex) — OpenAI's terminal-based AI coding assistant

pactkit_codex-0.1.0/docs/architecture/governance/lessons.md

@@ -0,0 +1,7 @@
+# Lessons Learned
+
+> Decisions and insights recorded during development.
+
+| Date | Lesson | Source |
+|------|--------|--------|
+| 2026-03-25 | Project initialized — greenfield, no source code yet | /project-init |