shipper plan

Usage: shipper plan [options] [issue]

Create an implementation plan for an issue

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

Create an implementation plan for S#42.

shipper plan S#42

Route-incompatible refusal

An issue whose stored route is simple runs one combined implementation-and-delivery step instead of planning. Invoking shipper plan on such an issue refuses with a message naming the route and pointing at shipper implement S#42. It creates no shipper:planned state and does not silently run implementation instead.

Verification planning

The generated plan maps every relevant plan step and every acceptance criterion to an exact repository-root command or an observable manual result, and lists the repository’s named lint, type-check, and other designated fast static checks once rather than per step. It does not reproduce the repository’s complete pre-push command set. 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

—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.