shipper implement

Usage: shipper implement [options] [issue]

Implement an issue in a worktree

Arguments

Argument	Required	Description	Choices
[issue]	no	Shipper issue ID, gh:, or GitHub URL	-

Flags

Long	Short	Value	Default	Description	Choices
—mode	-		default	execution mode: headless, interactive, or default	headless, interactive, default
—agent	-		-	agent to use: claude, codex, copilot, grok, or opencode	claude, codex, copilot, grok, opencode
—model	-		-	model to use for the agent CLI	-
—reasoning-effort	-		-	reasoning effort to pass to the agent CLI	-
—disable-mcp	-	-	-	disable MCP server loading for this run	-
—enable-mcp	-	-	-	enable MCP server loading for this run	-

Examples

Implement S#42 in a worktree.

shipper implement S#42

Empty branch verdicts

When implementation finalization finds no content relative to the base branch, a valid terminal result remains authoritative. A reject succeeds and rolls the issue back to shipper:designed; its ordinary rejection record includes the agent’s reason and explains that nothing was published. A fail marks the issue failed and reports the agent’s reason normally.

A no-content accept, or missing, unreadable, or invalid output, still triggers publication refusal and the existing durable failure path. Rejecting work that does contribute content retains the existing publication behavior before rollback.

Delivery

Implementation prepares and delivers the pull request, or the pinned local change when pull requests are disabled, on every route. On acceptance the issue moves to the review-entry state — displayed as PR Open when pull requests are enabled and Change Packaged when they are disabled. A complex-route issue moves there from shipper:planned; a simple-route issue runs one combined implementation-and-delivery step from shipper:designed instead of planning. Delivery uses the same content validation, in-stage correction round, posture gating, and pull-request labeling required for delivery.

Repeat delivery to an already-published branch publishes rewritten history with force-with-lease under rebase integration, so it never overwrites remote commits it has not seen, and reuses an existing open pull request without editing its title or description. A linked pull request that is closed without merging, missing, or a different number than expected fails the run with shipper issue reconcile --repair guidance; no replacement pull request is opened.

Pull-request creation confirmation

When GitHub reports that a pull request already exists, or a protected create attempt does not return confirmed pull-request metadata, implementation performs one guarded confirmation lookup. The lookup is restricted to open pull requests in the target repository with the packaged head branch and attempted base branch, and ignores cross-repository candidates. An eligible candidate follows the ordinary success path; its association, stage advancement, and output do not distinguish it from a freshly created pull request.

If the lookup cannot be verified or returns no eligible candidate, a pull request may already exist on GitHub, but Shipper could not confirm it. The run is unsuccessful, the issue stays at its current stage, no issue comment is posted, and the outcome is explicitly neutral for repository safety-stop accounting. An ordinary later run retries the issue and can reconcile a now-visible pull request through the initial lookup. No reset or recovery command is required.

Exit code 79 indicates that the confirming read exhausted the protected GitHub outage waiting allowance. Other unconfirmed outcomes use exit code 1. Neither exit code creates durable failed state. Once Shipper classifies the outcome as unconfirmed, it does not close, edit, or recreate a pull request. Branch publishing and the attempted create may already have changed GitHub.

A fresh implementation rejection delivers nothing and returns the issue to shipper:designed without closing its pull request or deleting its branch. A fresh simple-route rejection additionally escalates the route permanently to complex, so the next dispatch runs planning. A Rework rejection instead creates a visible operator-decision hold, preserves its exact route, package, pull request, branch, review history, and trigger, and stops automatic dispatch. Ordinary unblock resumes that Rework trigger; use an explicit reset when the underlying premise must change.

Rework and legacy-label compatibility

shipper implement S#123 accepts an issue at shipper:rework or at the legacy shipper:implemented label. During this one-release compatibility window it is treated exactly as Rework. With no issue argument, shipper implement selects Rework (including that raw legacy label) before a shipper:planned issue within the same priority; a simple-route issue at shipper:designed is reached with an explicit reference.

Implementation freezes one situation at entry. A current held-round pin selects review rework; a newer roundless merge-conflict entry selects merge rework; every other case, including an ordinary roundless operator reset, is fresh. Review rework supplies the pinned round, only outstanding local findings and unresolved external threads, and the held round’s ordinal out of five. It requires one nonblank fix or reasoned won’t-fix disposition per target. Successful replies remain durable and are resolved best-effort when autoResolveReviewThreads is enabled. An unreadable pin or dispositions still missing after one correction fail without advancing while preserving branch, pull request, code, and successful replies. Merge rework requires no review reply input.

Verification scope

The complex route runs the commands and manual observations the plan mapped to the steps and acceptance criteria it changed. The simple route has no published plan, so it builds the same mapping internally from the accepted design, its implementation units, and every acceptance criterion. Both add the repository’s named fast static checks and leave reserved checks to Shipper and CI unless a concrete obligation cannot be credibly verified without the exact reserved check. See verification ownership.

Exit Codes

Code	When
0	The stage completes successfully or returns a reject verdict.
1	Preflight, validation, GitHub, agent, or fail verdict handling fails.
79	Clean GitHub-outage waiting is exhausted. The issue retains its stage and remains eligible in a later run.
82	An attended TTY agent session actually starts but ends without complete valid artifacts. The issue retains its entry stage as a neutral operator cancellation.

Constraints

Rework is the recommended preserving reset from PR Open, Ready, or Rework, and from a failed issue without a stage. It requires an open linked PR under GitHub PR policy or a reachable pinned local change under no-PR policy. Legacy reviewed labels normalize to PR Open for this check. All routes retain their route; early stages do not qualify merely because they hold a package. Missing, closed, merged, or unverifiable evidence refuses the reset without changes; inspect or repair the association with shipper issue reconcile --repair, or recover the local package first. Rework preserves the package, association, branches, worktrees, route and review history, and clears failure. Repeat Rework resets are real operations. Next, Ship, and auto-ship dispatch Rework to implementation, which freezes one situation for the run: a current held-round pin selects review rework; otherwise a newer roundless merge-conflict entry selects merge rework; every other case is a roundless continuation of the retained packaged change with no correction delta, new reset instruction, accepted plan, or accepted design. Review rework consumes the pinned round, outstanding local findings, and supplied unresolved external threads, requires one nonblank fix or reasoned won’t-fix disposition per target, and durably delivers successful replies with configured best-effort resolution. An unreadable pin or dispositions still missing after one correction fail without advancing. Merge rework requires no review replies. Every situation reuses the preserved branch and open pull request without editing its metadata. Every successful explicit packaged preserving reset and eligible active packaged-change recovery restarts the five-round review allowance, including repeated Rework resets, unchanged revisions, and exhausted allowances. Package identity, full review history, findings, dispositions, and Rework context are preserved; renewal resolves no findings and grants no approval. Eligibility, destinations, and independent retry limits are unchanged. Count completed approved, addressed, superseded, and zero-finding reviews since the latest established renewal in append order; attempts without a completed review consume nothing. The first five completed reviews may reject into Rework; a sixth rejection enters durable Failed over Rework and retains its round, while a sixth approval may advance under existing approval rules. Automatic transitions and rejections, ordinary retries, restart/resume, grooming recovery, superseded-branch restoration, refused actions, and cancellation do not renew. Renewal belongs to the local logical commit even when projection repair is pending; repair grants no second renewal. A committed pending action reports its operation ID and says not to repeat it: store access finishes the existing operation. Recovery uses Recovery committed; local recovery pending for this outcome. For pre-release retained packages, affirmative historical preserving reset or packaged-recovery evidence, including recorded Rework operator-reset history, establishes the latest renewal. Without such evidence the existing full count remains. Upgrade alone leaves Failed intact. Current-allowance progress can be 0 of 5 or 6 of 5; historical round numbers and order never change and may exceed six. Replacement package identities start independently.
—disable-mcp and —enable-mcp are mutually exclusive
After an attended TTY agent session actually starts, Shipper validates its artifacts once. Complete valid artifacts finish normally even after a nonzero agent exit; missing, partial, or invalid artifacts cancel with exit 82. Cancellation retains the entry stage with null repository-safety impact, runs no correction or agent retry, creates no failed or recovery state, and requires no recovery action. Saved headless groom questions remain resumable. Committed workflow-branch HEAD is reused with continuation context on a later invocation while uncommitted work is removed during teardown. Compound next, ship, and automatic grooming runs start no later stage or issue after cancellation. This terminal outcome is distinct from the resumable exit-75 pause. Non-interactive runs retain their bounded output correction, retry, failure, and recovery behavior.