shipper next

Usage: shipper next [options]

Advance an issue to the next workflow step

Arguments

Argument	Required	Description	Choices
	yes	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

Advance S#42 to its next workflow stage.

shipper next S#42

Simple-route escalation

Exactly one agent stage runs per invocation. When a shipper:designed issue whose stored route is simple runs the combined implementation-and-delivery step and that step rejects, the command succeeds at shipper:designed and exits 0. Its output states both the rejection and the permanent escalation of the route from simple to complex, so the next invocation runs planning. No second agent stage starts in the same action.

Exit Codes

Code	When
0	The next stage succeeds or returns a reject verdict.
1	Preflight, label validation, stage dispatch, or fail verdict handling fails.
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.
Troubleshooting: missing or duplicate workflow labels
Troubleshooting: failed issues and rollback loops
Troubleshooting: adopted PR closed or superseded