PactKit's core methodology is the PDCA cycle — Plan, Act, Check, Done — with quality gates at every stage.

The Hierarchy of Truth

Before understanding the workflow, you must understand the governance model:

Conflict resolution: When Spec conflicts with code, Spec wins — modify the code. Code is never the source of truth.

When to Use What

The core loop is Plan → Act → Done. Other commands plug in as needed:

You have a task
  │
  ├─ Vague idea, multiple features? ──→ /project-design
  │
  ├─ Unclear requirement? ──→ /project-clarify → /project-plan
  │
  ├─ Clear feature or bug?
  │   │
  │   ├─ Small fix (1 file, obvious)? ──→ /project-hotfix
  │   │
  │   └─ Needs design? ──→ /project-plan → /project-act
  │       │
  │       ├─ Security-sensitive? ──→ /project-check (QA audit)
  │       │
  │       └─ /project-done
  │           │
  │           ├─ On feature branch? ──→ /project-pr
  │           └─ Ready to release? ──→ /project-release
  │
  └─ Fully automated? ──→ /project-sprint (runs all phases)

The Core Loop

1. Plan (/project-plan "your requirement")

Agent: System Architect

The architect analyzes requirements and produces:

• Clarification — asks structured questions for ambiguous requirements
• Visual understanding — scans codebase structure before design
• Spec creation — creates docs/specs/{ID}.md with requirements and acceptance criteria
• Board entry — adds a Story to track the work

/project-plan "Add rate limiting to the API endpoints"

2. Act (/project-act STORY-001)

Agent: Senior Developer

The developer implements code strictly per Spec:

• TDD approach — write tests first, then implementation
• Spec compliance — code must satisfy all acceptance criteria
• Iteration limit — max 5 attempts to prevent infinite loops
• Regression check — ensures the entire test suite still passes

3. Done (/project-done)

Agent: Repo Maintainer

The maintainer finalizes the delivery:

• Regression gate — full test suite must pass
• Lint gate — stack-aware lint check
• Coverage check — 3-tier thresholds (≥80% pass, 50-79% warn, <50% block)
• Board hygiene — all tasks checked off, story archived
• Commit — conventional commit format (feat(scope): description)
• Context update — prepare state for next session

Additional Commands

Hotfix (/project-hotfix "fix description") — Quick Fixes

Skip the full PDCA ceremony for small, obvious fixes:

• Fix typos and spelling errors
• Modify configuration files
• Adjust style or formatting
• Fix obvious single-file bugs

/project-hotfix "Fix broken install command in README"

When NOT to use: If the change touches multiple files or requires design decisions, use /project-plan + /project-act instead.

Check (/project-check STORY-001) — QA Audit

Add a quality review layer between Act and Done:

1. Security scan — 8-item OWASP checklist (hardcoded secrets, SQL injection, XSS, auth, rate limiting, error handling, dependencies)
2. Code quality — error handling, performance, boundary conditions, logic correctness
3. Spec alignment — every acceptance criterion mapped to test coverage
4. Test quality gate — detects tautological assertions, missing assertions, over-mocking

Output is a structured verdict with P0-P3 severity levels.

When to use:

• Changes touch security-sensitive code (auth, user input, APIs)
• Large changes where you want an extra review before commit
• You want to generate formal test case documentation

When to skip: Pure documentation changes, or small changes where Done's built-in regression gate is sufficient.

Clarify (/project-clarify "vague idea") — Requirement Clarification

Surface ambiguities before planning:

/project-clarify "I want to add a demo command for new users"
# → Generates 3-6 structured questions (scope, users, constraints, scale, edge cases)
# → You answer
# → Outputs a Clarified Brief ready for /project-plan

Design (/project-design "product vision") — Product Design

For greenfield products or major new feature sets:

• Generates a full PRD (personas, features, architecture, API design)
• Creates HTML prototypes with Tailwind CSS
• Decomposes into multiple Stories with priority scores
• Populates the Sprint Board

/project-design "A CLI tool for managing Docker development environments"

Difference from Plan: Design produces N stories at the product level. Plan produces 1 story at the feature level.

PR (/project-pr) — Pull Request Creation

Auto-generates a structured PR from your Spec and test results:

# On a feature branch after /project-done
/project-pr
# → Generates PR title + body from Spec
# → Pushes branch, creates PR via gh CLI

Release (/project-release) — Version Release

Handles the full release ceremony:

# After bumping version in pyproject.toml
/project-release
# → Architecture snapshot → Git tag → GitHub Release

Sprint (/project-sprint "requirement") — Full Automation

Runs Plan → Act → Check → Done in one command using a multi-agent team:

/project-sprint "Add OAuth2 login"

Each phase runs as a separate subagent (architect, developer, QA, maintainer). Best for well-defined requirements where you trust the full pipeline.

Init (/project-init) — Project Bootstrap

Run once to set up PactKit governance in a new project. Creates pactkit.yaml, architecture graphs, sprint board, and governance files.

Session Context

PactKit maintains docs/product/context.md — an auto-generated file that gives the next session instant awareness of project state:

• Sprint status (in-progress, backlog, done counts)
• Recent completions
• Active branches
• Recommended next action

This file is updated by /project-plan and /project-done.

Standard File Structure