Your first run

A run takes a single feature from a one-line description to a finished, tested branch — and optionally a pull request. Here's how to start one, watch it, and read the result.

Prerequisites

• The CLI is installed and your runner is paired (pipemason login).
• You're inside a git repository with a clean working tree.
• The repo has a remote and a sensible base branch (e.g. main).

Start a run

From the root of your repo, describe the change you want in plain language:

pipemason start "add a /healthz endpoint that returns 200"

The runner scaffolds a .pipeline/ workspace if one doesn't already exist, registers the run with the cloud control plane (you'll see a run id), creates a branch, and begins working.

Common flags

The flags you'll use most often:

pipemason start "..." --pr             # open a pull request at finalize
pipemason start "..." --stash          # auto-stash a dirty working tree
pipemason start "..." --base develop   # override base branch detection
pipemason start "..." --no-cloud       # run fully local; skip cloud streaming

What happens during a run

A single agent — the monitor — walks the feature through a fixed sequence of phases, sharing state through files in .pipeline/ rather than chat. As an observer you'll see the run move through phases like these:

1. analyze — turn your request into a frozen spec.
2. contracts — freeze the interfaces between domains.
3. architect — record design decisions per domain.
4. tdd — write failing tests for every acceptance criterion.
5. implement — make the failing tests pass, committing per cycle.
6. e2e / ui / screenshot diff — for web and mobile work only.
7. verify — run quality, security, and accessibility gates.
8. runtime check — boot the app and smoke it.
9. rebase — rebase onto a fresh base branch.
10. finalize — push the branch (and open a PR if requested).

Each iteration appends a structured event to .pipeline/iterations.logand streams to your dashboard. A typical run takes 5–30 minutesdepending on scope.

Watch it live

Open pipemason.com/dashboard to follow the run as it happens: a live event stream, a snapshot of the current pipeline state, and per-phase progress. You can also check status from the terminal at any time:

pipemason status   # prints the current .pipeline/STATE.md

When it finishes

On success the branch is pushed and — if you passed --pr — a pull request URL is captured in the final summary. Review the diff the same way you'd review a teammate's work: read the spec the run froze, the tests it wrote, and the implementation that made them pass.