Configuration — PactKit Docs

This page covers the pip install deployment. If you installed via the Claude Code Plugin, all components are deployed automatically and pactkit.yaml is not used.

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.

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

On this page