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. When Spec conflicts with tests, Spec wins — modify the tests. Code is never the source of truth.

The Four Phases

1. Plan (/project-plan)

Agent: System Architect

The architect analyzes requirements and produces a Spec:

0. Init Guard — automatically checks if the project is initialized; runs /project-init if needed
1. Visual Scan — run visualize to understand current codebase structure
2. Logic Trace — if modifying existing logic, run /project-trace first
3. Design — update the high-level design diagram
4. Spec — create docs/specs/{ID}.md with RFC 2119 requirements and Given/When/Then acceptance criteria
5. Board — add a Story to the Sprint Board

2. Act (/project-act)

Agent: Senior Developer

The developer implements code strictly per Spec, following TDD:

1. Read Spec — understand the requirements
2. Test First — write unit tests (RED)
3. Implement — write code to make tests pass (GREEN)
4. Verify — ensure the full test suite passes

3. Check (/project-check)

Agent: QA Engineer

The QA engineer runs a 6-phase deep audit:

1. Security scan (OWASP baseline)
2. Test case generation (Gherkin scenarios)
3. Layer decision (API-level or browser-level testing)
4. Test execution
5. Spec alignment verification
6. PASS / FAIL verdict

4. Done (/project-done)

Agent: Repo Maintainer

The maintainer finalizes the delivery:

1. Clean — remove temporary files
2. Regression Gate — run full test suite; stop if anything fails
3. Hygiene — confirm all Board tasks are checked off
4. Archive — move completed Stories to archive
5. Commit — conventional commit (feat(scope): description)

Sprint Automation

Run the entire PDCA cycle in one command:

/project-sprint "Add user authentication"

This orchestrates all four phases automatically using a multi-agent team. Requires the Opus model for agent coordination.

File Structure