shipper design

Usage: shipper design [options] [issue]

Run technical design review on an issue

Arguments

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

Flags

Long	Short	Value	Default	Description	Choices
—enable-adversarial-review	-	-	-	enable adversarial design review for this run	-
—disable-adversarial-review	-	-	-	disable adversarial design review for this run	-
—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

Run technical design for S#42.

shipper design S#42

Enable adversarial design review for this invocation only.

shipper design S#42 --enable-adversarial-review

Issue route decision

Design decides the issue’s route and declares it on every accepted design. The route is simple or complex and determines which stages the issue passes through: a complex-route issue runs planning and implementation as separate stages, while a simple-route issue runs one combined implementation-and-delivery step and never records shipper:planned.

Design defaults to simple and routes complex only when an exclusion clearly applies: a clear exclusion needs specific evidence tied to its rule, such as named artifacts, an identified seam or new test infrastructure, or a concrete open question or alternative; production code changes span more than one package or component or alter a cross-package contract (documentation, tests, fixtures, and generated reference output do not count); it changes durable saved workflow data, stage result exchange, Shipper’s bundled stage prompts, user-visible configuration or stages, or the set of available agent tools; it adds a dependency or touches build or CI configuration; the change is large or adds an architectural seam; verifying it requires new test infrastructure; or design cannot state the approach in a few sentences without open questions. Post-merge, live-environment, or operator acceptance steps do not exclude simple. General uncertainty is not an exclusion. Only a rejected combined implementation permanently escalates to complex; findings after an accepted implementation follow normal review and Rework implementation.

A route and a nonblank one-line reason are required on an accepted design result. Omitting either is invalid stage output: the stage’s bounded correction pass retries with feedback naming what is missing, and exhausting it fails the issue with the ordinary operator guidance. There is no setting that disables routing and no silent default.

The accepted design review carries an ## Issue Route section stating the route and its reason. The durable audit trail is the ## Issue Route Changed entry in the issue’s workflow history, written whenever an accepted design changes the stored route. Routes are monotonic: an undecided route may become either, simple may escalate to complex, and complex never returns to simple.

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.
—enable-adversarial-review and —disable-adversarial-review are mutually exclusive