This page explains PactKit's design principles. It's useful for understanding why the toolkit is built the way it is.

Design Principles

PactKit follows these core principles:

1. Open-Closed Principle (OCP) — Extend by adding, not modifying. New formats, agents, or rules are added through configuration rather than code changes.

2. Single Source of Truth — Each concept lives in exactly one place. Specs define requirements, the Board tracks work, code implements behavior.

3. Prompt-First — Behavioral changes are prompt modifications before code changes. AI behavior is tuned through prompts, which is cheaper and more flexible than code.

4. Conditional by Default — All optional features (CI/CD, hooks, integrations) are disabled by default and only activate when explicitly enabled.

5. Spec is Law — When conflicts arise between Spec, tests, and code, the Spec wins. Code adapts to Spec, never the reverse.

Component Overview

PactKit consists of four main component types:

These components work together to implement the PDCA cycle, with each agent responsible for a specific phase.

PDCA Data Flow

User requirement
  → Plan phase → System Architect → Spec + Board entry
  → Act phase  → Senior Developer → Tests + Implementation
  → Check phase → QA Engineer → Verification + Verdict
  → Done phase → Repo Maintainer → Commit + Archive

Cross-Session State

PactKit maintains project state across sessions through standard markdown files:

These files are human-readable and version-controlled, ensuring transparency and auditability.

Multi-Format Support

PactKit deploys to multiple AI tools through format profiles:

Each format receives the same core functionality, adapted to the target tool's conventions.

Contributing

PactKit is open source. Contributions are welcome for:

• Bug fixes and improvements
• Documentation enhancements
• New language stack profiles
• Integration examples

See our GitHub Issues to report bugs or request features.