PitWay Documentation

PitWay's full documentation, grouped by section. Start with Getting Started if this is your first time running PitWay.

Getting Started

  • Getting Started -- Install the pitway CLI, run pitway init from your Git repo root, and take your verified first steps with PitWay.

Concepts

  • Milestones -- A milestone is one unit of planned work -- a contract plus a task graph -- moving through PitWay's draft-to-completed state machine.
  • Contracts -- A milestone's contract is a Markdown file with machine-authoritative YAML frontmatter -- the execution boundary a milestone never silently expands beyond.
  • Tasks -- Tasks are a milestone's concrete steps, each mechanically bounded by a write_scope and moved through its own state machine.
  • Evidence -- Every task and milestone check is verified against an approved command and its result recorded as formal evidence, never estimated.
  • Backlog -- backlog captures work discovered mid-task without expanding the current milestone's scope, for promotion into a real task later.
  • Worktrees -- Independent, dependency-free tasks with disjoint write_scope can dispatch concurrently into temporary Git worktrees under parallel_worktrees.

Workflow

  • Review -- milestone-review runs a role-based review workflow -- reviewers produce findings only; PitWay doesn't run reviews or verify reviewer independence.
  • Auto Run -- auto-run manages the authorization that lets task execution continue automatically without stopping for confirmation at every step.
  • Verification -- Two-tier verification: each task is checked against its own approved command, and a mandatory full test suite gates milestone completion.
  • Completion -- milestone-complete is the final mandatory approval gate -- it refuses until every task is done and every verification check is passing.
  • Merge -- milestone-merge lands a completed milestone's dedicated branch into its base branch, idempotently, with full git-safety checks.

Agents

  • Claude Code -- pitway init installs Claude Code slash commands and driver protocol documents by default -- the primary way Claude Code drives PitWay's workflow.
  • OpenCode -- pitway init --opencode installs the same PitWay command surface for OpenCode, in its own file convention, from the shared common layer.
  • Codex -- pitway init --codex installs the same PitWay command surface for Codex, in its own file convention, from the shared common layer.
  • Resume -- pitway resume reconstructs workflow state from .pitway/ and recommends the next action -- the authoritative way to pick a session back up.