Metadata-Version: 2.4
Name: pactkit
Version: 2.1.0
Summary: Spec-driven agentic DevOps toolkit for AI coding assistants
Project-URL: Homepage, https://pactkit.dev
Project-URL: Repository, https://github.com/pactkit/pactkit
Project-URL: Documentation, https://pactkit.dev/docs
Project-URL: Issues, https://github.com/pactkit/pactkit/issues
Author: Slim
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,claude,claude-code,code-assistant,code-quality,developer-tools,devops,multi-agent,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
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/pactkit/pactkit/main/docs/assets/logo.png" alt="PactKit" width="480" />
</p>

<p align="center">
  <a href="https://pypi.org/project/pactkit/"><img src="https://img.shields.io/pypi/v/pactkit" alt="PyPI version" /></a>
  <a href="https://pypi.org/project/pactkit/"><img src="https://img.shields.io/pypi/pyversions/pactkit" alt="Python" /></a>
  <a href="https://github.com/pactkit/pactkit/actions/workflows/ci.yml"><img src="https://github.com/pactkit/pactkit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
</p>

<p align="center"><strong>Ship features with AI agents that follow specs, not vibes.</strong></p>

> PactKit gives AI coding assistants a structured operating system — 9 specialized agents, 11 commands, 10 skills, and a full Plan-Act-Check-Done lifecycle. One `pip install` and your AI assistant writes specs before code, runs TDD, and never commits without passing tests.

### Supported AI Tools

| Tool | Format | Command |
|------|--------|---------|
| **Claude Code** | Classic | `pactkit init` |
| **OpenCode** | OpenCode | `pactkit init --format opencode` |

### 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
```

## Why PactKit?

AI coding assistants are powerful but unpredictable without structure. PactKit adds a **spec-driven governance layer**:

- **Spec is the Law** — Specifications are the single source of truth (Spec > Tests > Code)
- **Multi-Agent Ensemble** — 9 specialized agents collaborate, each with defined roles
- **Full PDCA Lifecycle** — Plan -> Act -> Check -> Done, with quality gates at every stage
- **Safe by Design** — TDD-first development, safe regression testing, pre-existing test protection
- **Multi-Tool Support** — Works with Claude Code and OpenCode (with model routing)

## Installation

```bash
pip install pactkit
```

Requires Python 3.10+ and one of:
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- [OpenCode](https://opencode.ai)

## Quick Start

### Claude Code

```bash
# Deploy full toolkit
pactkit init

# Update to latest playbooks (preserves your config)
pactkit update
```

### OpenCode

```bash
# Deploy to OpenCode (global: ~/.config/opencode/)
pactkit init --format opencode

# Update existing deployment
pactkit upgrade --format opencode
```

Then in any project:

```bash
# 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:

```bash
/project-sprint "Add user authentication"
```

## PDCA+ Workflow

| Phase | Command | Agent | What Happens |
|-------|---------|-------|-------------|
| **Clarify** | `/project-clarify` | System Architect | Ambiguity detection -> Structured questions -> Clarified brief |
| **Plan** | `/project-plan` | System Architect | Clarify gate -> Codebase scan -> Spec generation -> Board entry |
| **Act** | `/project-act` | Senior Developer | Spec lint -> Consistency check -> TDD loop -> Regression check |
| **Check** | `/project-check` | QA + Security | 8-item security checklist + quality audit + spec alignment |
| **Done** | `/project-done` | Repo Maintainer | Regression gate -> Archive -> Conventional commit |
| **Release** | `/project-release` | Repo Maintainer | Version bump -> Snapshot -> Git tag -> GitHub Release |
| **PR** | `/project-pr` | Repo Maintainer | Push branch -> Create pull request via gh CLI |
| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration |
| **Hotfix** | `/project-hotfix` | Senior Developer | Fast-track fix bypassing PDCA (with traceability) |
| **Init** | `/project-init` | System Architect | Bootstrap project structure and governance |
| **Design** | `/project-design` | Product Designer | PRD generation -> Story decomposition -> Board setup |

### Embedded Skills (auto-invoked by commands)

| Skill | Embedded In | Purpose |
|-------|-------------|---------|
| Trace | Plan Phase 1, Act Phase 1 | Deep code tracing and execution flow analysis |
| Release | Release Phase 1 | Version release: snapshot, archive, Git tag |

### Agent Skills (invoked via agent roles)

| Skill | Available To | Purpose |
|-------|-------------|---------|
| Draw | visual-architect, system-architect | Generate Draw.io XML architecture diagrams |
| Status | system-medic | Project state overview |
| Doctor | system-medic | Diagnose project health |
| Review | qa-engineer | PR Code Review |
| Analyze | senior-developer (Act inline) | Cross-artifact consistency check: Spec <-> Board <-> Test Cases |

## Agent Ensemble

PactKit deploys 9 specialized agents, each with constrained tools and focused responsibilities:

| Agent | Role | Core Capability |
|-------|------|----------------|
| System Architect | Architecture design | Maintain Intent Graph, write Specs |
| Senior Developer | Full-stack development | TDD loop, call chain analysis, hotfix |
| QA Engineer | Quality gates | Deep check (P0-P3), PR review |
| Security Auditor | Security audit | OWASP scanning, threat modeling |
| Repo Maintainer | Repository ops | Cleanup, archiving, Git conventions, releases |
| System Medic | System diagnostics | Configuration drift repair |
| Visual Architect | Architecture visualization | Draw.io XML generation |
| Code Explorer | Code tracing | Call graph + sequence diagram |
| Product Designer | Product design | PRD, story decomposition, board init |

## Skills

PactKit deploys 10 skills (3 scripted + 7 prompt-only), auto-invoked by commands:

| Skill | Type | Purpose |
|-------|------|---------|
| **pactkit-visualize** | Scripted | Code dependency graph (Mermaid): file-level, class-level, call-level |
| **pactkit-board** | Scripted | Sprint board operations: add story, update task, archive |
| **pactkit-scaffold** | Scripted | File scaffolding: create spec, test files, git branches, skills |
| **pactkit-trace** | Prompt-only | Deep code tracing and execution flow analysis |
| **pactkit-draw** | Prompt-only | Generate Draw.io XML architecture diagrams |
| **pactkit-analyze** | Prompt-only | Cross-artifact consistency check: Spec <-> Board <-> Test Cases |
| **pactkit-status** | Prompt-only | Cold-start project overview (sprint + git + health) |
| **pactkit-doctor** | Prompt-only | Configuration drift detection and health report |
| **pactkit-review** | Prompt-only | PR code review with SOLID/Security/Quality checklists |
| **pactkit-release** | Prompt-only | Version bump, architecture snapshot, git tag |

## Deployment Architecture

PactKit supports two deployment formats:

### Claude Code (Classic)

```
~/.claude/
├── CLAUDE.md                 <- Modular constitution (entry point with @import)
├── rules/                    <- 7 rule modules
├── commands/                 <- 11 command playbooks
├── agents/                   <- 9 agent definitions
└── skills/                   <- 10 skill packages
```

### OpenCode

```
~/.config/opencode/
├── AGENTS.md                 <- Slim header (rules loaded via instructions)
├── rules/                    <- 7 rule modules (loaded via opencode.json instructions)
├── commands/                 <- 11 command playbooks (with model: routing)
├── agents/                   <- 9 agent definitions (mode: subagent)
├── skills/                   <- 10 skill packages (with SKILL.md frontmatter)
└── opencode.json             <- Global config (instructions, provider preserved)
```

Key OpenCode differences:
- **Rules**: Loaded via `opencode.json` `instructions: ["rules/*.md"]` (no `@import`)
- **Agents**: `mode: subagent`, no `name` field, tools as record format
- **Commands**: `agent: build` + `model: provider/model-id` (model routing)
- **Config**: `pactkit.yaml` in `.opencode/` (not `.claude/`)
- **Model routing**: Commands auto-route to Sonnet for implementation, inherit main model for planning

## Multi-Developer Collaboration

PactKit supports multi-developer workflows with Story ID prefixing:

```yaml
# 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

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `stack` | string | auto-detected | Project stack (`python`, `node`, `go`, `java`) |
| `version` | string | current | PactKit version that generated the config |
| `developer` | string | `""` | Developer prefix for Story IDs (multi-developer collaboration) |
| `agents` | list | all 9 | Agent definitions to deploy |
| `commands` | list | all 11 | Command playbooks to deploy |
| `skills` | list | all 10 | Skills to deploy |
| `rules` | list | all 7 | Constitution rule modules to deploy |
| `exclude` | object | `{}` | Components to exclude (e.g., `exclude.agents: [agent-name]`) |
| `ci` | object | `provider: none` | CI/CD pipeline generation (`github`, `gitlab`, `none`) |
| `issue_tracker` | object | `provider: none` | External issue tracker (`github`, `none`) |
| `hooks` | object | disabled | Opt-in hook templates (pre-commit, post-test, pre-push) |
| `lint_blocking` | bool | `false` | Whether lint failures block commits |
| `auto_fix` | bool | `false` | Whether to auto-fix lint errors |
| `agent_models` | object | `{}` | Per-agent model overrides (`haiku`, `sonnet`, `opus`, `inherit`) |
| `command_models` | object | defaults | Per-command model overrides for OpenCode deployment |

## 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

```
Tier 1: Specs & Test Cases           <- The Law
Tier 2: Tests                        <- The Verification
Tier 3: Implementation               <- The Mutable Reality
```

When conflicts arise: Spec wins. Always.

## MCP Integration

PactKit conditionally integrates with MCP servers when available:

| MCP Server | Purpose | PDCA Phase |
|------------|---------|------------|
| Context7 | Library documentation lookup | Act |
| shadcn | UI component search/install | Design |
| Playwright | Browser automation testing | Check |
| Chrome DevTools | Performance/console/network | Check |
| Memory | Cross-session knowledge graph | Plan/Act/Done |
| Draw.io | Architecture diagram instant preview | Plan, Design |

All MCP instructions are conditional — gracefully skipped when unavailable.

## Upgrading

```bash
pip install --upgrade pactkit
pactkit update                    # Claude Code
pactkit upgrade --format opencode # OpenCode
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

[MIT](LICENSE)
