Workflows & Stages

Preset workflows

Workflow	Stages
feature	spec → implement → review
bugfix	diagnose → implement → review
hotfix	implement → review
chore	implement → review
refactor	implement → review
research	research → review

Every workflow's first stage is manual — the ticket waits in Backlog until you drag it into the stage's working column — and every workflow terminates in the review stage, which hands the PR to you and moves the ticket to Done. Nothing auto-merges.

Stage vocabulary

• spec — turns the boarded ticket into a spec the implement stage can execute.
• diagnose — must produce a red loop: one already-run failing command that reproduces the bug, committed before implementation starts.
• implement — branches <type>/<slug>, works test-first in vertical slices, commits per slice with the provider's co-author trailer, opens a PR whose body closes the issue. Gated on a committed implementation.md.
• review — two independent passes (Standards: does it follow repo conventions; Spec: does it match the ticket), then a hunk-by-hunk audit. The committed review.md carries a VERDICT: CLEAR or VERDICT: BLOCKING line; blocking kicks the ticket back a turn. On CLEAR, trkr requests your review on the PR and moves the ticket to Done (hand-off).
• research — investigates and commits findings as artifacts; no code changes expected.

implement and review have dedicated built-in prompts; spec, diagnose, and research currently run on the generic autonomous stage prompt, so their contracts above are conventions rather than prompt-enforced. Use a stage's prompt field to substitute your own.

Stage definition

Each stage (StageDef) has:

Field	Meaning
name	Stage name; selects the built-in prompt of the same name when one exists
from	Waiting column — the daemon picks tickets up here (ignored on manual stages)
during	Working column while the session runs
to	Success column
prompt	Custom prompt file, path relative to the repo root
provider	Override the provider for this stage
manual	Daemon only dispatches when a human moves the item into during
gate	Hard gate to pass before advancing (gates reference)

Customizing workflows

Override or disable presets in .trkr.json:

{
  "workflows": {
    "feature": { "stages": [ /* replaces the preset wholesale */ ] },
    "research": null
  },
  "default_workflow": "feature"
}

A definition replaces the preset of the same name entirely; null disables it; omitted names keep their presets. After changing workflows, re-run trkr init to migrate the board's columns.

The autonomous contract

Every stage session operates under the same rules: never ask the user (assumptions are recorded in the artifact under ## Assumptions (autonomous)); satisfy gates, never skip them; failures re-walk as turns; genuinely stuck escalates (Blocked) instead of guessing.