agentsystemlabs/core/ship

User-question protocol: Whenever this skill needs the user to pick between options, confirm an action, or answer a multiple-choice prompt, you MUST call the AskUserQuestion tool to render a proper interactive picker. Do NOT print numbered options as plain text and wait for the user to type a number — that produces a degraded UX. Free-form questions (open-ended typing) may be asked in prose, but any time you would write "1) … 2) … 3) …", use AskUserQuestion instead.

ship

The user gave you an engineering goal. Pick the right workflow, pick the right depth, announce both, run the workflow, report. Stop before git.

The tax on a vibe coder is choosing which skill to invoke and how thorough to be. This skill takes that tax off them — without hiding what was decided.

Bundled reference resolution — read before executing anything

This plugin registers exactly one skill: ship. Every workflow and reviewer named in this file and in every playbook it loads — add-feature, reviewer-code, write-tests, plan-red-team, findings-reconciler, etc. — is a bundled file inside this skill, not a separately registered skill or agent. Do not call the `Skill` tool for them and do not pass their names as `subagent_type` — nothing but ship is registered, so both error.

Resolve every bundled reference by reading a file, relative to the ship skill directory (the directory holding THIS file; ${CLAUDE_PLUGIN_ROOT}/skills/ship/ when that env var is set):

• `playbooks/<name>/PLAYBOOK.md` — a workflow or sub-skill. Read it and follow it inline as your next phase of work, carrying the same args (mode=, run-id=, run-ledger=, headless=). Ship-root-relative.
• `subagents/<name>.md` — a reviewer / mapper / verifier / tracer. Read it, then dispatch a fresh subagent with the Agent tool using subagent_type: "general-purpose", passing the file's body as the leading instructions followed by the concrete scope (diff, plan, artifact name, file list). These agents are read-only by role — tell them not to edit files. Dispatch several in one message to run them in parallel; that fan-out and their fresh-context isolation are the entire reason they are subagents rather than inline work — preserve both. Ship-root-relative.
• `references/<file>` — a checklist or reference doc. Relative to the playbook currently being followed (not ship-root). Read it in place. Exception — shared references: when a playbook cites a file as ship's references/<file> (the shared risk-signals.md and run-ledger.md), resolve it at ship-root references/, not the playbook's own folder — those two are single-source and shared across playbooks.

If any instruction still shows an old Skill(skill="X") call or an Agent(subagent_type=agentsystem-core:Y) call, treat it as playbooks/X/PLAYBOOK.md / subagents/Y.md respectively.

Run preamble — announce the plugin version

At the start of every run, read the plugin version from the plugin manifest — ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json if that env var exists, else the .claude-plugin/plugin.json two directories above this skill file — and announce it in the first status line, e.g.:

🚢 /ship (agentsystem-core v0.52.0) — pipeline: …

If the manifest can't be found, say "version unknown" rather than failing. The version line tells the user (and any later defect audit) exactly which generation of the gates ran.

Step 1 — Classify intent

Read the user's prompt and map to one of six core skills:

EVOLVE vs POLISH boundary. EVOLVE is one specific change the user named (whether it's a single-element cosmetic tweak or a behavior extension); POLISH is "apply the checklist" without a specified change. If the user names what to change, it's EVOLVE. If they ask for a pass, it's POLISH. For purely cosmetic single-element changes ("make this button green", "fix the alignment"), route to EVOLVE with mode=fast.

Pre-classification probe (cheap, one search). Verb-mapping alone misleads: "add a settings page" in a repo that already has one is EVOLVE, not CREATE. Before locking a CREATE vs EVOLVE decision, run one quick Glob/Grep for the named artifact — the route path, component name, table, or endpoint. If it already exists → almost always EVOLVE (modify-feature); if it genuinely doesn't → CREATE (add-feature). One probe is far cheaper than a wrong full-pipeline run the user only notices at Step 5. Skip the probe only when the verb is unambiguous ("delete X", "why didn't X fire").

Ambiguous prompts — when two intents are equally plausible (e.g., "rebuild auth" could be EVOLVE or REMOVE+CREATE), ask exactly one disambiguating AskUserQuestion. Don't guess.

Multi-intent prompts — if the user lists clearly separable goals ("add X and remove Y"), execute them sequentially as separate /ship routings, not one combined run. State the order before starting.

Refactor / test-authoring prompts — two common asks sit just outside the six intents but do have a home:

• "refactor this module", "clean this up", "DRY this", "find code smells" → route to simplify (pass scope=<the named path> so it isn't diff-limited). If the "refactor" actually changes behavior, it's EVOLVE → modify-feature instead.
• "write tests for X", "add test coverage", "cover this with tests" → route to write-tests.

Announce these like any other routing (Detected / Mode / Pipeline), then run the bundled playbook inline — read playbooks/simplify/PLAYBOOK.md or playbooks/write-tests/PLAYBOOK.md per Bundled reference resolution.

No-match prompts — if the user's request doesn't fit any intent above (e.g., explain code, document a flow, compare approaches, ask a question about the codebase, brainstorm features, or scaffold a new app from zero), /ship is the wrong tool. Stop and tell the user the request doesn't map to an engineering workflow this skill orchestrates, and — if the match is obvious — point at the matching tool directly (e.g., "review this PR" → /review, "explain this module" → no skill needed, just answer in the conversation).

Step 2 — Infer the depth mode

Three modes — fast, balanced, production. Pick one before announcing.

Risk signals (any one → `production`) — the canonical list lives in `references/risk-signals.md`; the mode-safety overrides in add-feature / modify-feature / remove-feature / fix-bug all cite that same file so the signals can't drift apart. In one line: auth / permissions / payments / secrets / external webhooks; schema migrations or persisted-data rewrites; destructive deletion of an external/public contract; background jobs / queues / cron / email / SMS / imports / exports / file writes / IPC / external APIs; caching / query-invalidation / feature flags / analytics / concurrency-sensitive mutations; or a multi-subsystem change (frontend + backend + DB together).

Tiny-scope signals (all four → `fast`):

• Single file
• Cosmetic / copy / styling only
• No data layer touched
• No new public API surface

Default → `balanced`.

Override: explicit mode=fast, mode=balanced, or mode=production in the user's prompt always wins — except when it conflicts with a high-risk signal (see NEVER below).

Headless option (`headless=true`). Also triggered by the word "headless" anywhere in the invocation. Headless removes user interaction, NOT rigor — it skips QUESTIONS, never QUALITY gates:

• Never call `AskUserQuestion`. Every point where this skill would ask (intent disambiguation at Step 1, production "Proceed with this pipeline?" at Step 3, the mode-conflict prompt in NEVER) auto-resolves with best judgement instead. Record each assumption ("Assumed: EVOLVE over CREATE because the route already exists") in the per-run ledger and surface them all in the Step 5 report.
• Forward `headless=true` to the routed skill (add-feature / modify-feature / fix-bug / etc.) alongside mode=, so its own question points (plan approval, clarify phase) convert to logged-plan-and-proceed under the same contract.
• Every verify/review gate still runs. The routed skill's implementation, verification, gated reviews, and tests execute exactly as the resolved mode dictates. A headless run that shipped without its gates is a defect, not a feature.
• Mode-conflict handling: if mode=fast collides with a high-risk signal, auto-upgrade to the mode the risk demands and record the decision — don't silently honor the dangerous override, and don't ask.

Step 3 — Announce the plan

Output a structured plan block before executing. Format:

Detected: <CREATE | EVOLVE | POLISH | REMOVE | FIX | AUDIT>
Risk:     <low | medium | high — one-line reason>
Mode:     <fast | balanced | production — one-line reason or "user-specified">
Pipeline:
  1. <phase>  → <core skill or sub-skill>
  2. <phase>  → <core skill or sub-skill>
  ...

Pipeline numbering must match what the routed core skill will actually run at the chosen mode (e.g., add-feature mode=production does Clarify → Explore → Design → Plan approval → Implement → Verify → Gated reviews → Tests → Post-steps). Do not invent phases the routed skill won't execute — those become a credibility hole at Step 5.

Create the per-run ledger. Read and follow `references/run-ledger.md`. Generate a unique run ID and write the ledger under the session scratch directory, falling back to .agentsystem/runs/<run-id>.md only when no scratch location exists. Record the goal, intent/mode/risk, base SHA, initial worktree, locked decisions/assumptions, pipeline, and input hash where available.

Update phase/task/reviewer status at every transition. Record file ownership, retries/fallbacks, findings dispositions, exact verification evidence, and terminal state. Never use a fixed .agentsystem/ship-run.md: concurrent sessions would overwrite each other. Step 5 reads this ledger rather than reconstructing the run from memory.

Confirmation gating depends on mode:

In headless runs the production confirm prompt is skipped like the others: print the plan inline, record "proceeded without confirmation (headless)" in the run ledger, and continue.

Step 4 — Execute the routed workflow