How commands work

A worktree is a second checkout of the same repository — its own files on its own branch, sharing one history with your main checkout, with no second clone required. Before anything is written, the command fetches origin and cuts that branch from origin/<default-branch>. That fetch is the pull-latest step — a new worktree always starts from the current base, with no separate pull to remember.

By default the worktree lives inside the repo under .shipmates/worktrees/, one directory per issue or bundle, and the run adds that path to .gitignore for you. A repo that prefers the older layout can put it next to the checkout instead, but the effect is the same:

# default (nested)
<repo>/.shipmates/worktrees/issue-42

# optional sibling layout
../<repo>--issue-42

Parallel runs never collide, and an abandoned run is a directory you can delete. Re-running the same issue reuses its worktree and branch rather than starting over. If the base branch has moved on, the run syncs first — rebase or merge, whichever your contributing docs prefer — and a sync that cannot complete cleanly stops the run with the failure instead of guessing.

Everything — builds, tests, fixes, commits — happens inside that worktree. Your checkout and the base branch are untouched until a merge lands.

The run polls the checks on the exact commit it pushed. Three outcomes are handled, not two: green, red, and no check suite appears at all — an empty result is its own failure mode, not “still pending”.

Red: the run pulls the real failure log, fixes the cause, pushes, and polls the new head again. The loop is bounded — three fix rounds by default. If checks are still red after that, it stops and hands you the log rather than reviewing code it cannot verify.

No suite: after a bounded wait, the run root-causes why the trigger never fired instead of waiting indefinitely or merging a workflow guess to see what happens.

Reviewers only ever see a green, pushed head — never a local diff. If your repository has no CI at all, the run says so and treats the static self-check as the gate, stating the reduced assurance explicitly.

Every acceptance cycle has a mandatory core: the product-manager checks the change against the ticket’s acceptance criteria, and the principal-engineer checks boundary integrity, scope discipline, and the repository’s own quality bar.

Specialists are pulled by what the plan flagged, not by a fixed roster: an architect for new subsystems, schema, or cross-module change; a ux-ui-designer for on-screen UI; an art-director for rendered art; an sdet when the plan asks for a specialist test review; a devops-engineer for pipelines and packaging; a technical-writer for documented behaviour or a public API; a security-engineer for auth, secrets, crypto, or untrusted input; a performance-engineer for a claimed win or a known hot path; a site-reliability-engineer for runtime behaviour and rollout; a data-scientist when the deliverable is an analysis or a model.

A seat whose criteria do not hold is gated out on purpose — a recorded result, not an omission, and part of what keeps a run affordable.

Verdicts are ACCEPT or REJECT (PASS/FAIL for test seats; nits are allowed). Any REJECT or FAIL goes to a fixer and the board re-sits on the new delta: the failers review the change, a prior ACCEPT carries unless the delta can invalidate it, and a seat the delta newly trips may join. Like the CI loop, this is bounded — then it escalates to you with the reasons.

Epic runs review once at the top: unit commands defer their board to a single integration board on the epic pull request, so a five-story epic pays for one thorough reversal rather than five rushed ones. The board can be turned off explicitly; no command skips it silently.

Manual (default). The run stops at a green, reviewed pull request and hands you the link. Merging it closes the issues named in the body, because every one is written as its own closing keyword.

Automatic (opt-in). Once every gate passes, the run squash-merges, deletes the branch, and confirms the issues closed. The merge is bound to the exact head the board reviewed: if the head moved after review, the merge refuses instead of landing unverified code.

Epic runs. Unit pull requests merge automatically into the epic’s integration branch so the checklist can complete, while the epic pull request into your default branch stays yours to merge.

A security-sensitive change never auto-merges onto the default branch on its own — that run is forced to manual regardless of the setting.

• Bundling is a recommendation you accept. When the leading ticket is small, the run can propose cohesive siblings that share one plan, worktree, validation pass, and review. It always asks before widening the run.
• Independent work runs in parallel. File-disjoint slices build concurrently up to a bounded worker cap, each in its own worktree, one writer per checkout. Dependent work stays sequential.
• Seats are value-gated; models are chosen at spawn. Mechanical work goes to the cheapest capable model; planning, architecture, security, and acceptance get the stronger reasoning.
• Agents return decisions, not transcripts. Verdict first, then the evidence that supports it, then blockers — never a replay of every step.
• Nits are absorbed, not filed. Cheap in-scope findings are fixed on the same pull request under a cap; leftovers are noted on the PR, and a run opens at most a couple of follow-up issues.

The contributor-level detail, including the model-routing rule and the exact defaults, is in docs/COST.md.

New here? Start with the install reference, then open /shipmates-ship-issue and point it at a real ticket. The harness matrix records what has been verified on which harness, and architecture explains how one crew compiles into each harness’s native payload.