Configuration (.trkr.json)

Written to the repo root by trkr init. Board identity fields are managed by trkr; the rest are yours to edit.

{
  "projectId": "PVT_…",
  "projectNumber": 7,
  "projectUrl": "https://github.com/users/you/projects/7",
  "statusFieldId": "PVTSSF_…",
  "repo": "owner/name",
  "workflowFieldId": "PVTSSF_…",
  "workflowOptionIds": { "feature": "abc123" },
  "agentFieldId": "PVTSSF_…",
  "agentOptionIds": { "claude": "def456" },

  "default_workflow": "feature",
  "workflows": { "research": null },
  "provider": "claude",
  "providers": { },
  "max_turns": 3,
  "orchestrator": true,
  "validate": {
    "build": "pnpm build && npm pack",
    "artifacts": ["*.tgz"]
  },
  "telemetry": { "retain": "14d", "maxBytes": 10485760 }
}

Managed fields (written by init)

Field	Meaning
projectId	Projects v2 node id
projectNumber	Project number
projectUrl	Board URL
statusFieldId	Status single-select field id
repo	owner/name
workflowFieldId	Workflow single-select field id
workflowOptionIds	Workflow name → option id cache
agentFieldId	Agent single-select field id
agentOptionIds	Provider name → option id cache

User fields

Field	Default	Meaning
default_workflow	"feature"	Fallback when a ticket has no workflow or the classifier picks an unknown one
workflows	presets	Per-name overrides: a WorkflowDef replaces the preset wholesale, null disables it, omitted names keep presets (details)
provider	"claude"	Repo-default provider name
providers	built-ins	Named provider definitions, merged over built-ins (details)
max_turns	3	Verification turns before a ticket is Blocked (a plateau — no improvement between turns — blocks earlier)
orchestrator	true	Triage agent on failed turns: files findings as linked fix tickets, records justified dismissals, and can escalate to a human early. false disables; { "provider": "…" } overrides its provider. It never grants extra turns or clears a verdict — the deterministic re-walk/block path is always the fallback
validate	off	Enables the black-box validate stage on every code workflow (not research): build is a shell command run in the ticket's worktree, artifacts are worktree-relative paths (shell globs allowed) copied into the sandbox, optional provider overrides the session's provider (details)
telemetry.retain	"14d"	Rotated span-file retention (<n>d|h|m)
telemetry.maxBytes	10 MiB	Rotate spans.jsonl beyond this size

Per-stage provider routing

Every stage in a workflows override takes an optional provider naming any entry in providers — so spec and review can run a strong model while implement runs a cheap one. Missions-style routing looks like:

{
  "providers": {
    "claude-strong": { "run": "claude -p {promptFile} --model opus --permission-mode bypassPermissions" },
    "claude-fast": { "run": "claude -p {promptFile} --model sonnet --permission-mode bypassPermissions" }
  },
  "workflows": {
    "feature": { "stages": [
      { "name": "spec", "from": "Backlog", "during": "Spec", "to": "Implement", "manual": true, "provider": "claude-strong", "gate": { "artifacts": ["spec.md", "contract.md"] } },
      { "name": "implement", "from": "Implement", "during": "Implement", "to": "Review", "provider": "claude-fast", "gate": { "artifacts": ["implementation.md"], "sections": { "implementation.md": ["Implemented", "Left undone", "Commands run", "Discovered issues"] } } },
      { "name": "review", "from": "Review", "during": "Review", "to": "Done", "provider": "claude-strong", "gate": { "artifacts": ["review.md"], "verdict": "review.md" } }
    ] }
  }
}

The validate stage's provider comes from validate.provider; the orchestrator's from orchestrator.provider.

Runtime files

Daemon runtime state lives in .trkr/ (self-ignored, never committed):

• .trkr/worktrees/<issue> — per-ticket git worktree, reused across a ticket's stages and turns, removed when the ticket clears the terminal stage
• .trkr/validate/<issue> — the validate stage's sandbox: contract.md plus artifact/, and nothing else
• .trkr/orchestrate/ — orchestrator decision files, one per triaged turn
• .trkr/intake/ — intake prompt files and spec output
• .trkr/telemetry/ — span JSONL and per-ticket turn context
• Session logs and rendered prompts, anchored to the main repo root