pipemason

guides

Your first run

A real walkthrough of a single-feature run, end to end. By the end you'll have a tested branch, an opened PR, and a clear picture of what each phase wrote.

0. Prerequisites

  • You've completed the Quickstart (runner installed + paired + Anthropic key in shell).
  • You have a git repo with at least one domain pipemason can detect (a package.json, Podfile, etc).
  • GitHub is connected on /dashboard/settings (so pipemason can push and open a PR).

1. Initialise the repo

cd ~/your-repo
pipemason init

The runner scans for domains, writes .pipeline/, and commits a starter config.yml. Review the diff, edit anything that looks off (domain list, default branch, allowed commands), and commit.

git add .pipeline/ && git commit -m "init pipemason workspace"

2. Start the run

Pick a real, narrowly-scoped feature ticket. The tighter the scope, the better the result on a first run.

pipemason start "ABC-1234 add a /version endpoint that returns package.json version"

The runner prints a run id (a ULID) and a dashboard URL. Keep the URL open — that's where you watch progress live.

3. Watch each phase write its artifact

The dashboard streams phase transitions as they happen. In your repo, each phase commits one or more frozen artifacts under .pipeline/:

  • analyze writes spec.md — the version-endpoint feature, in pipemason's own words.
  • plan writes test-plan.md — every AC mapped to ≥1 test row.
  • contracts writes (or amends) contracts/api.ts with the new GET /version typed contract.
  • test-red adds a failing supertest in api/test/version.test.ts.
  • impl adds the route handler and greens the red test.
  • review + verify + pr push the branch and open the PR.

4. Review the PR

The PR body summarises what shipped, links to the run, and embeds the phase artifacts inline. You'll see frozen spec.md, test counts, lint / typecheck results, and any deviations the runner flagged.

Tip

Treat the spec like a contract. If the spec drifted from what you actually wanted, the right fix is usually to amend the ticket and re-run — not to hand-patch the PR.

5. When something goes wrong

On your first few runs you'll probably hit one of:

  • The spec doesn't match your intent — your ticket was ambiguous. Edit the ticket; re-run with the same command.
  • A phase escalates — read Handling escalations.
  • The runner can't push — GitHub isn't connected, or the OAuth scopes are stale. Reconnect on the settings page.