Recipes

Recipes are task walkthroughs for readers who already know the Shipper job they want to complete and need the shortest safe path through it. For CI or container token authentication, use the Containers reference. For failed runs and common recovery paths, start with failed issues and rollback loops.

Next-step presentation

The desktop board uses five columns: Design · Plan · Implement · Review · Ready. Cards currently in Rework appear in Implement with a Rework badge, which disappears on return to Review. CLI/MCP status keeps six next-step groups, including Rework; desktop Implement combines their Implement and Rework groups, with attention exclusions unchanged. A designed simple issue next needs Implement; complex or undecided issues next need Plan. Ready means ready for final integration, not shipped. Existing records receive this presentation without migration or reprocessing.

Before choosing a recovery recipe, distinguish the next-step name from a completed-stage reset argument: the Plan column targets designed, while --to planned next needs Implement. Route-aware reset choices retain backward eligibility, failed retry, preserving Rework, active restrictions, confirmations, work-loss warnings, and work-preservation guarantees. A non-failed same-column drop is a no-op; a simple Plan drop refuses without changing route. Design clears the route.

See Next-step presentation for the complete mapping, count and attention rules, compatible response fields, and automatic label-description refresh. Recovery recipes below continue to use the existing completed-stage command arguments.

Adopt an existing repo

Goal

Initialize Shipper in an existing GitHub-backed repository and bring open GitHub issues into the Shipper workflow without recreating them.

Preconditions

You are in the root of a Git checkout with a GitHub remote.
git, gh, and shipper are installed.
GitHub authentication works through gh auth login, or the environment exports GH_TOKEN or GITHUB_TOKEN.
At least one open GitHub issue does not already have a shipper: label.

Steps

Verify GitHub auth before you initialize Shipper:
Terminal window
```
gh auth status
```
In token-based environments, confirm one of the supported token variables is present instead:
Terminal window
```
test -n "${GH_TOKEN:-${GITHUB_TOKEN:-}}"
```
Configure Shipper from the repository root:
Terminal window
```
shipper setup
```
Let shipper setup record repository settings and sync the Shipper workflow labels in GitHub. This step must run before adoption so shipper adopt can move issues into a configured workflow. If the repo team shares committed Shipper configuration, run shipper setup --repo before committing .shipper/.

If the repo team shares Shipper configuration, commit the generated setup:

git status --short .shipper/
git add .shipper/
git commit -m "chore: initialize shipper"

Adopt one existing GitHub issue by URL:

shipper adopt https://github.com/owner/repo/issues/42

Or adopt every open issue that does not already have a shipper: label:
Terminal window
```
shipper adopt --all
```

Verification

Confirm committed Shipper configuration when the team uses shipper setup --repo:

test -f .shipper/settings.json

Confirm the targeted GitHub issue now carries shipper:new:

gh issue view <github-issue-number> --json labels -q '.labels[].name' | grep '^shipper:new$'

You can also view adopted issues through Shipper:

shipper issue list --status new

Run a fully local repository

Goal

Run the complete Shipper workflow with no git remote: keep issue state and reviews locally, package the implemented change as a recorded local change, and merge by advancing the local target branch.

Set up the repository

Initialize a repository with an explicit base branch and create its first commit. Shipper uses that commit to establish repository lineage.

mkdir fully-local-project
cd fully-local-project
git init --initial-branch=main
printf '# Fully local project\n' > README.md
git add README.md
git commit -m "chore: initialize repository"

Confirm that no remote is configured. This command should print nothing:
Terminal window
```
git remote
```
Create deterministic committed Shipper configuration for Codex:
Terminal window
```
shipper setup --repo --agent codex
```

Inspect and commit the generated repository configuration:

git status --short .shipper/
git diff -- .shipper/
git add .shipper/
git commit -m "chore: configure shipper"

Confirm the effective repository posture:
Terminal window
```
shipper status
```
The configuration section includes:
```
Posture: Fully local
```
That name represents the effective none / none / local transport, pull-request, and review delivery policy.

Run the workflow

Create an issue and keep the emitted S#<id> for the remaining commands:
Terminal window
```
shipper new "Add the first project feature"
```
Groom the local issue (the examples below use S#123):
Terminal window
```
shipper groom S#123
```
Advance with shipper next S#123 one stage at a time, or use shipper ship S#123 to continue automatically. The local display sequence is Plan (complex or undecided) or Implement (simple), Implement after planning, Review, and then Ready after an accepted review. A rejected review enters Rework with the same pinned local package.
Terminal window
```
shipper next S#123
```
shipper implement S#123 produces packaged work awaiting Review, and the stored stage is shipper:pr-open. In this posture it pins the source revision and complete change metadata in a local change record and appends workflow history; it does not create a pull request.

shipper pr review S#123 reviews the pinned local three-dot diff and writes a locally held round without posting to GitHub. Shipper applies the same derived gate as hosted review: accepted work advances directly to Ready, while a rejection pins the round and enters Rework. The next advance runs implementation in the review-rework situation. PR Open remains only for legacy work already parked there.
If a stage crashes after packaging and marks the issue failed, recover the pinned local change explicitly:
Terminal window
```
shipper recover S#123
```
Recovery returns the issue to Review, preserves the full pinned revision and source branch, and keeps earlier locally held review rounds. A source branch that advanced past the pinned revision remains eligible as long as it still contains that revision.
Before merging, inspect the compact review-round list and then one complete round. Copy the round ID shown by the first command into the second:
Terminal window
```
shipper issue view S#123
shipper issue view S#123 --review-round <round-id>
```
When the issue reaches Ready, merge the recorded change:
Terminal window
```
shipper merge S#123
```
Shipper advances the local main target branch and completes the local issue. With no transport, it does not publish that branch anywhere.

Inspect the completed state

Confirm both Shipper state and local git history:

shipper status
shipper issue view S#123
git status
git log --oneline --decorate -10