Configuration

PactKit is installed with pip (Installation) and deployed with pactkit init. Without a pactkit.yaml, every component is deployed.

pactkit.yaml

The pactkit.yaml file controls which components are deployed and how they behave.

Location: PactKit auto-detects the config file based on your environment:

Environment	Config Path
Claude Code	`.claude/pactkit.yaml`
OpenCode	`.opencode/pactkit.yaml`

Both paths are checked automatically — no manual configuration needed.

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
`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 8	Constitution rule modules to deploy
`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
`lint_blocking`	bool	`false`	Whether lint failures block commits
`auto_fix`	bool	`false`	Whether to auto-fix lint errors
`e2e`	object	`type: none`	E2E testing strategy configuration
`venv`	object	`auto_detect: true`	Virtual environment detection
`release`	object	`github_release: true`	Release automation behavior
`regression`	object	`strategy: impact`	Impact-based test selection
`check`	object	see below	QA verification behavior
`done`	object	see below	Commit and lesson quality behavior
`agent_models`	object	`{}`	Per-agent model overrides
`command_models`	object	defaults	Per-command model overrides (OpenCode)

All conditional features (CI/CD, issue tracking, hooks, lint blocking) are disabled by default and only activate when explicitly configured.

Multi-Developer Collaboration

Set developer to avoid Story ID conflicts across team members:

developer: alice

Story IDs become STORY-alice-001, STORY-alice-002, etc. Each developer has their own ID namespace.

Model Routing

Configure which model each agent or command uses:

agent_models:
  code-explorer: haiku     # Fast exploration
  system-architect: opus   # Deep analysis
  senior-developer: sonnet # Implementation

command_models:
  project-act: sonnet
  project-done: sonnet

Model shortnames (sonnet, opus, haiku) are automatically resolved to the correct provider format.

PactKit can use codegraph as its graph provider for semantic code queries. Codegraph uses tree-sitter for type-aware call graph resolution, producing 2-3x more edges than PactKit's built-in suffix-match approach.

Installation

npm install -g @colbymchenry/codegraph

Add to your pactkit.yaml:

visualize:
  graph_provider: codegraph

Usage

Once configured, initialize the codegraph database in your project:

codegraph init -i

This generates .codegraph/codegraph.db — a SQLite database with all functions, classes, and call edges. PactKit commands then use this automatically:

pactkit query <function> — find callers/callees via codegraph
pactkit query --callers <function> — reverse lookup (who calls this?)
PDCA commands (Plan/Act/Check/Done) use codegraph for impact analysis

If graph_provider: codegraph is set but .codegraph/codegraph.db is missing, pactkit query will auto-run codegraph init -i when the CLI is on PATH.

Keeping the Graph Fresh

Run codegraph sync after significant code changes, or let PactKit handle it — pactkit visualize --lazy triggers a sync when source files change.

Add .codegraph/ to your .gitignore (it's a build artifact):

.codegraph/

E2E Testing

Configure End-to-End testing strategy in /project-check Phase 4:

e2e:
  type: none        # none | cli | frontend | backend | fullstack
  blocking: false   # Whether E2E failures block /project-done
  test_dir: tests/e2e
  env_file: .env.test
  # api_spec: docs/api/openapi.yaml  # OpenAPI spec path for frontend/backend
  compose_file: docker-compose.test.yml  # Docker Compose for fullstack

E2E Types

Type	Description	Tools
`none`	Skip E2E (default)	—
`cli`	CLI tool testing via subprocess	pytest + subprocess
`frontend`	Browser testing with API mocks	Playwright + MSW
`backend`	API testing with test database	pytest + httpx
`fullstack`	Full stack with docker-compose	docker-compose + Playwright

Configuration Fields

Field	Type	Default	Description
`e2e.type`	string	`none`	E2E strategy to use
`e2e.blocking`	bool	`false`	If `true`, E2E failures block `/project-done`
`e2e.test_dir`	string	`tests/e2e`	Directory for E2E test files
`e2e.env_file`	string	`.env.test`	Test credentials file (API tokens, DB strings)
`e2e.api_spec`	string	`""`	OpenAPI/Swagger spec path (for frontend/backend types)
`e2e.compose_file`	string	`docker-compose.test.yml`	Docker Compose file (for fullstack type)

E2E is opt-in — set type: none (default) to skip. When enabled, tests are generated in /project-check Phase 4 based on the Story's Acceptance Criteria.

Example: CLI Project

For a CLI tool like PactKit itself:

e2e:
  type: cli
  test_dir: tests/e2e/cli

Tests run via pytest using subprocess to invoke CLI commands.

Example: Web Application

For a full-stack web app:

e2e:
  type: fullstack
  blocking: true
  env_file: .env.test

Spins up the stack via docker-compose, runs Playwright tests against real services.

Language Profiles

PactKit auto-detects the project stack and configures the appropriate tools:

Stack	Test Runner	Lint Command
`python`	`pytest tests/`	`ruff check src/ tests/`
`node`	`npx jest`	`npx eslint .`
`go`	`go test ./...`	`golangci-lint run`
`java`	`mvn test`	`mvn checkstyle:check`

Updating

pactkit update                        # Re-deploy all IDEs
pactkit upgrade --format opencode     # Re-deploy single IDE (optional)

Safe to re-run at any time. Re-deploys all managed files while preserving your custom configuration.

Preview

Preview the deployment without modifying production directories:

pactkit init -t /tmp/preview                        # Preview all IDEs
pactkit init --format opencode -t /tmp/oc-preview   # Preview single IDE