cli reference

pipemason start

Start a single-story run. One ticket → one branch → one PR.

Usage

pipemason start "<ticket-or-prompt>" [flags]

Examples

# Simple feature
pipemason start "add a /version endpoint that returns package.json version"

# With a Jira ticket prefix (becomes part of the branch name)
pipemason start "ABC-1234 passkey login on /sign-in"

# Pin a specific base branch (default: repo's default branch)
pipemason start "ABC-1234 ..." --base release/2026.06

# Skip the analyze phase if you already wrote spec.md
pipemason start "ABC-1234 ..." --spec .pipeline/spec.md

Flags

--base <branch>        Base branch for the new feature branch. Defaults
                       to the repo's default branch (usually main).

--spec <path>          Skip 'analyze'; use the given spec.md as the
                       frozen spec.

--no-pr                Don't open a PR at the end. Useful for testing.

--dry-run              Run 'analyze' + 'plan' only; stop before writing
                       any code. Cheap way to preview what the runner
                       will do.

--label <key=value>    Add a label to the run for filtering on the
                       dashboard. Repeatable.

--retry-budget <n>     Override the per-phase retry budget from
                       config.yml.

What it writes

• .pipeline/spec.md — frozen spec.
• .pipeline/test-plan.md — test rows mapped to every AC.
• .pipeline/contracts/*.ts — cross-domain types touched by the change.
• .pipeline/iterations.log — append-only audit trail.
• A new feature branch with atomic commits.
• An open PR (unless --no-pr) with a summary comment.

Exit codes

0      run complete; PR opened
1      run escalated (printed run id; resume with 'pipemason resume')
2      runner config / pairing problem
3      remote API error / network