pipemason

concepts

Runs

A run is one feature ticket → one branch → one PR. It's the atomic unit pipemason ships. When you type pipemason start "..." you create a run.

What a run does

A run takes an English-language request (a Jira ticket, a chat message, a sentence in your terminal) and walks it through a multi-phase pipeline. The output is a feature branch with atomic commits, a PR opened against your default branch, and an audit trail under .pipeline/.

Anatomy

Every run has:

  • A ULID for stable referencing (printed by the runner; visible in the dashboard URL).
  • A branch derived from the ticket name (e.g. feature/ABC-1234-add-passkey-login).
  • A base branch — usually main, but for stacked work in a program it's the branch of an upstream story.
  • A phase that changes as the pipeline advances (the dashboard shows the current one live).
  • A status in { pending | running | complete | failed | escalated | cancelled }.
  • Aggregate counters: iterations, tokens in/out, cost estimate.

State that lives on disk

.pipeline/
├── config.yml                # repo-level config
├── STATE.md                  # current run state
├── spec.md                   # frozen spec from your input
├── contracts/                # frozen interfaces between domains
├── iterations.log            # append-only audit trail
├── decisions.md              # ADRs written during the run
└── ROADMAP.md                # story DAG (program mode only)

Everything decided during the run gets written here. Re-runs and reviewers read the same files, so the audit trail is the source of truth — not a transcript.

How a run advances

The pipeline runs a defined sequence of phases — analyze → plan → contracts → red tests → implementation → review → end-to-end → audits → verify → PR. Each phase has an input artifact, an output artifact, and a gate the pipeline checks before advancing. Phases that don't apply (e.g. no e2e on a docs-only change) are skipped by their gates.

See Phases for the full table of what each phase writes and what its gate checks.

When a run fails

If a phase's gate fails, the pipeline retries inside the same phase with adjusted instructions. The retry budget is set per phase in .pipeline/config.yml. If retries are exhausted, the run escalates: the dashboard surfaces the failing artifact, and the run pauses waiting on you. You can resume with pipemason resume after editing the upstream artifact, or cancel with pipemason cancel. See Handling escalations for the full workflow.

Runs inside programs

When you start a program (pipemason program start) the program decomposes the intent into a DAG of stories. Each story becomes a run, dispatched when its dependencies are met. Runs inside a program use the same phase machine — they just inherit base branches from upstream stories instead of always branching off main.

Runs · Pipemason Docs