pactkit 1.0.0__tar.gz

pactkit-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Report a bug in PactKit
+title: "[BUG] "
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. Run `pactkit init`
+2. Execute `/project-plan "..."`
+3. ...
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- PactKit version: `pactkit version`
+- Python version:
+- OS:
+- AI assistant: (Claude Code / other)

pactkit-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature Request
+about: Suggest a new feature for PactKit
+title: "[FEATURE] "
+labels: enhancement
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+How should it work?
+
+## Alternatives Considered
+
+Any other approaches you've considered.

pactkit-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+<!-- Bullet list of changes -->
+
+## Test Plan
+
+- [ ] All existing tests pass
+- [ ] New tests added for new functionality
+- [ ] Manual verification completed
+
+## Related Issues
+
+<!-- Link to related issues: Fixes #123, Closes #456 -->

pactkit-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest ruff==0.15.1
+          pactkit init
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest tests/ -v

pactkit-1.0.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+*.pyc
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+*.tmp
+*.log
+
+# PactKit - generated artifacts (auto-regenerated by user projects)
+docs/architecture/graphs/
+docs/architecture/snapshots/
+
+# Claude Code local config
+.claude/
+
+# Backup
+*.bak

pactkit-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to PactKit
+
+Thank you for your interest in contributing to PactKit!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/pactkit.git`
+3. Create a branch: `git checkout -b feature/your-feature`
+4. Install in development mode: `pip install -e ".[dev]"`
+5. Run tests: `pytest`
+
+## Development Workflow
+
+PactKit follows its own PDCA workflow:
+
+1. **Plan** — Open an issue describing what you want to change and why
+2. **Act** — Write tests first (TDD), then implement
+3. **Check** — Ensure all tests pass: `pytest`
+4. **Done** — Submit a PR with conventional commit messages
+
+## Commit Messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(scope): add new feature
+fix(scope): fix a bug
+docs(scope): update documentation
+test(scope): add or update tests
+chore(scope): build/tooling changes
+refactor(scope): code refactoring
+```
+
+## Pull Requests
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update documentation if behavior changes
+- All CI checks must pass before merge
+
+## Code of Conduct
+
+Be respectful, constructive, and collaborative. We welcome contributors of all experience levels.

pactkit-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PactKit Contributors
+
+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-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pactkit
+Version: 1.0.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,claude-code,devops,pdca,scaffold,spec-driven,tdd
+Classifier: Development Status :: 4 - Beta
+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
+Description-Content-Type: text/markdown
+
+# PactKit
+
+**Spec-driven agentic DevOps toolkit for AI coding assistants.**
+
+> *"Code by Contract"* — Agree on specs before writing code. Let agents execute.
+
+PactKit is an enterprise-grade **agentic DevOps scaffold** that compiles development workflows, role definitions, and behavioral rules into executable "constitutions" and "playbooks" for AI coding assistants.
+
+## 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
+
+## Quick Start
+
+```bash
+# Install
+pip install pactkit
+
+# Deploy Expert mode (full 13 commands + 9 agents + 3 skills)
+pactkit init
+
+# Or deploy lightweight Common mode (4 basic PDCA commands)
+pactkit init --mode common
+```
+
+Then in any project with Claude Code:
+
+```bash
+# Plan — Analyze requirements, create Spec
+/project-plan "Add user authentication"
+
+# Act — Implement with strict TDD
+/project-act STORY-001
+
+# Check — Security scan + quality audit (P0-P3 severity)
+/project-check
+
+# Done — Safe regression gate + 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 |
+|-------|---------|-------|-------------|
+| **Plan** | `/project-plan` | System Architect | Codebase scan → Spec generation → Board entry |
+| **Act** | `/project-act` | Senior Developer | Visual scan → TDD loop → Regression check |
+| **Check** | `/project-check` | QA + Security | 6-phase deep audit (Security/Quality/Spec alignment) |
+| **Done** | `/project-done` | Repo Maintainer | Safe regression gate → Archive → Conventional commit |
+| **Trace** | `/project-trace` | Code Explorer | Call graph tracing → Sequence diagram |
+| **Draw** | `/project-draw` | Visual Architect | Generate Draw.io XML architecture diagrams |
+| **Doctor** | `/project-doctor` | System Medic | Configuration drift detection → Health report |
+| **Review** | `/project-review` | QA Engineer | PR review with SOLID/Security/Quality checklists |
+| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration |
+| **Hotfix** | `/project-hotfix` | Senior Developer | Fast-track fix bypassing PDCA (with traceability) |
+| **Release** | `/project-release` | Repo Maintainer | Version bump → Archive → Git tag → Changelog |
+| **Design** | `/project-design` | Product Designer | PRD generation → Story decomposition → Board setup |
+
+## 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
+
+Three atomic skills are deployed as standalone scripts:
+
+- **pactkit-visualize** — Code dependency graph (Mermaid): file-level, class-level, call-level
+- **pactkit-board** — Sprint board operations: add story, update task, archive
+- **pactkit-scaffold** — File scaffolding: create spec, test files, git branches, skills
+
+## 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 (docs/specs/*.md)     — The Law
+Tier 2: Tests                        — The Verification
+Tier 3: Implementation               — The Mutable Reality
+```
+
+When conflicts arise: Spec wins. Always.
+
+## Configuration
+
+PactKit deploys to `~/.claude/`:
+
+```
+~/.claude/
+├── CLAUDE.md                 ← Modular constitution (entry point)
+├── rules/                    ← 6 rule modules
+├── commands/                 ← 13 command playbooks
+├── agents/                   ← 9 agent definitions
+└── skills/                   ← 3 skill packages
+    ├── pactkit-visualize/
+    ├── pactkit-board/
+    └── pactkit-scaffold/
+```
+
+## 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 |
+
+All MCP instructions are conditional — gracefully skipped when unavailable.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE)

pactkit-1.0.0/README.md

@@ -0,0 +1,148 @@
+# PactKit
+
+**Spec-driven agentic DevOps toolkit for AI coding assistants.**
+
+> *"Code by Contract"* — Agree on specs before writing code. Let agents execute.
+
+PactKit is an enterprise-grade **agentic DevOps scaffold** that compiles development workflows, role definitions, and behavioral rules into executable "constitutions" and "playbooks" for AI coding assistants.
+
+## 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
+
+## Quick Start
+
+```bash
+# Install
+pip install pactkit
+
+# Deploy Expert mode (full 13 commands + 9 agents + 3 skills)
+pactkit init
+
+# Or deploy lightweight Common mode (4 basic PDCA commands)
+pactkit init --mode common
+```
+
+Then in any project with Claude Code:
+
+```bash
+# Plan — Analyze requirements, create Spec
+/project-plan "Add user authentication"
+
+# Act — Implement with strict TDD
+/project-act STORY-001
+
+# Check — Security scan + quality audit (P0-P3 severity)
+/project-check
+
+# Done — Safe regression gate + 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 |
+|-------|---------|-------|-------------|
+| **Plan** | `/project-plan` | System Architect | Codebase scan → Spec generation → Board entry |
+| **Act** | `/project-act` | Senior Developer | Visual scan → TDD loop → Regression check |
+| **Check** | `/project-check` | QA + Security | 6-phase deep audit (Security/Quality/Spec alignment) |
+| **Done** | `/project-done` | Repo Maintainer | Safe regression gate → Archive → Conventional commit |
+| **Trace** | `/project-trace` | Code Explorer | Call graph tracing → Sequence diagram |
+| **Draw** | `/project-draw` | Visual Architect | Generate Draw.io XML architecture diagrams |
+| **Doctor** | `/project-doctor` | System Medic | Configuration drift detection → Health report |
+| **Review** | `/project-review` | QA Engineer | PR review with SOLID/Security/Quality checklists |
+| **Sprint** | `/project-sprint` | Team Lead | One-command automated PDCA orchestration |
+| **Hotfix** | `/project-hotfix` | Senior Developer | Fast-track fix bypassing PDCA (with traceability) |
+| **Release** | `/project-release` | Repo Maintainer | Version bump → Archive → Git tag → Changelog |
+| **Design** | `/project-design` | Product Designer | PRD generation → Story decomposition → Board setup |
+
+## 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
+
+Three atomic skills are deployed as standalone scripts:
+
+- **pactkit-visualize** — Code dependency graph (Mermaid): file-level, class-level, call-level
+- **pactkit-board** — Sprint board operations: add story, update task, archive
+- **pactkit-scaffold** — File scaffolding: create spec, test files, git branches, skills
+
+## 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 (docs/specs/*.md)     — The Law
+Tier 2: Tests                        — The Verification
+Tier 3: Implementation               — The Mutable Reality
+```
+
+When conflicts arise: Spec wins. Always.
+
+## Configuration
+
+PactKit deploys to `~/.claude/`:
+
+```
+~/.claude/
+├── CLAUDE.md                 ← Modular constitution (entry point)
+├── rules/                    ← 6 rule modules
+├── commands/                 ← 13 command playbooks
+├── agents/                   ← 9 agent definitions
+└── skills/                   ← 3 skill packages
+    ├── pactkit-visualize/
+    ├── pactkit-board/
+    └── pactkit-scaffold/
+```
+
+## 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 |
+
+All MCP instructions are conditional — gracefully skipped when unavailable.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+[MIT](LICENSE)

pactkit-1.0.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pactkit"
+version = "1.0.0"
+description = "Spec-driven agentic DevOps toolkit for AI coding assistants"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Slim" },
+]
+keywords = [
+    "ai",
+    "agent",
+    "spec-driven",
+    "devops",
+    "scaffold",
+    "claude-code",
+    "tdd",
+    "pdca",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://pactkit.dev"
+Repository = "https://github.com/pactkit/pactkit"
+Documentation = "https://pactkit.dev/docs"
+Issues = "https://github.com/pactkit/pactkit/issues"
+
+[project.scripts]
+pactkit = "pactkit.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pactkit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/pactkit/prompts/__init__.py" = ["F401"]
+"src/pactkit/prompts/agents.py" = ["E501"]
+"src/pactkit/prompts/commands.py" = ["E501"]
+"src/pactkit/prompts/references.py" = ["E501"]
+"src/pactkit/prompts/rules.py" = ["E501"]
+"src/pactkit/prompts/skills.py" = ["E501"]
+"src/pactkit/prompts/workflows.py" = ["E501"]
+"src/pactkit/generators/deployer.py" = ["E402"]
+"src/pactkit/skills/*.py" = ["E501", "E701", "E702", "E722", "E731"]
+"src/pactkit/scripts.py" = ["E501"]
+"tests/**/*.py" = ["E402", "E501", "E741", "F841"]

pactkit-1.0.0/src/pactkit/__init__.py

@@ -0,0 +1,3 @@
+"""PactKit - Spec-driven agentic DevOps toolkit."""
+
+__version__ = "1.0.0"

pactkit-1.0.0/src/pactkit/cli.py

@@ -0,0 +1,78 @@
+"""PactKit CLI — Spec-driven agentic DevOps toolkit.
+
+Usage:
+    pactkit init                  # Deploy Expert mode (default)
+    pactkit init --mode common    # Deploy lightweight Common mode
+    pactkit init -t /tmp/preview  # Preview to custom directory
+    pactkit update                # Re-deploy (same as init, idempotent)
+    pactkit version               # Show version
+"""
+import argparse
+import sys
+
+from pactkit import __version__
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="pactkit",
+        description="PactKit — Spec-driven agentic DevOps toolkit",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # pactkit init
+    init_parser = subparsers.add_parser("init", help="Deploy PactKit configuration")
+    init_parser.add_argument(
+        "--mode",
+        choices=["expert", "common"],
+        default="expert",
+        help="Deployment mode: expert (full, default) or common (lightweight)",
+    )
+    init_parser.add_argument(
+        "-t", "--target",
+        type=str,
+        default=None,
+        help="Custom target directory (default: ~/.claude)",
+    )
+
+    # pactkit update (alias for init)
+    update_parser = subparsers.add_parser("update", help="Re-deploy PactKit configuration")
+    update_parser.add_argument(
+        "--mode",
+        choices=["expert", "common"],
+        default="expert",
+        help="Deployment mode: expert (full, default) or common (lightweight)",
+    )
+    update_parser.add_argument(
+        "-t", "--target",
+        type=str,
+        default=None,
+        help="Custom target directory (default: ~/.claude)",
+    )
+
+    # pactkit version
+    subparsers.add_parser("version", help="Show PactKit version")
+
+    args = parser.parse_args()
+
+    if args.command in ("init", "update"):
+        if args.mode == "expert":
+            from pactkit.generators.deployer import deploy
+            deploy()
+        else:
+            from pactkit.common_user import main as common_main
+            # Simulate CLI args for common_user
+            sys.argv = ["pactkit"]
+            if args.target:
+                sys.argv.extend(["-t", args.target])
+            common_main()
+
+    elif args.command == "version":
+        print(f"PactKit v{__version__}")
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()