use-ship

Ship: Use Ship

Use this skill as Ship's routing brain.

Your job is to choose the smallest useful Ship workflow for the request. Do not force the full pipeline unless the user explicitly wants production delivery or the risk justifies it.

Routing Rule

1. Read the user's request and enough repo context to understand the work.
2. Decide whether the task needs one standalone skill, a phase bundle, or the full /ship:auto workflow.
3. State the chosen route briefly, then invoke the matching skill(s).

Modern Model Contract

Assume the host model is capable and literal:

• Give it the smallest useful route, not a forced ceremony.
• Trust the agent to choose task-local notes and artifact shape.
• Keep hard gates explicit: evidence, tests, reports, PR readiness.
• Prefer provider-neutral roles: host, peer, subagent, reviewer.
• Do not optimize instructions for a named model version; optimize for autonomy, tool use, and strict artifact boundaries.

Phase Bundles

Need	Route
Understand scope, write a plan, de-risk approach	/ship:design
Architecture/API/data model decision	/ship:arch-design, then /ship:design if implementation planning is needed
Implement a well-scoped change	/ship:design → /ship:dev
Implement from an existing approved plan	/ship:dev
Add durable browser/API/CLI coverage	/ship:e2e
Check code correctness	/ship:review
Verify runtime behavior	/ship:qa
Harden a completed change	/ship:e2e → /ship:review → /ship:qa → /ship:refactor
Prepare delivery after work is complete	/ship:handoff
End-to-end production delivery	/ship:auto

YAML Boundary

Ship's auto runner does not prescribe per-stage YAML schemas.

• The durable input is .ship/tasks/<task_id>/input/requirement.md when a full flow is running.
• The orchestrator-owned state is minimal and exists for resume/hooks.
• Agents may create lightweight YAML under .ship/tasks/<task_id>/control/ if it helps the current task, but the agent chooses the shape.
• Markdown artifacts and repository code are the real deliverables.

Production Artifact Organization

When a task needs durable product, design, engineering, quality, delivery, or archive artifacts, use the repository's existing convention first. If there is no convention, create the smallest useful folder under:

docs/ship/<task-id-or-req-id>/
  input/       # raw requirement and source notes
  product/     # clarified requirements and acceptance criteria
  design/      # UI/product design artifacts when needed
  engineering/ # architecture and implementation plans
  quality/     # test plans, QA reports, quality evidence
  delivery/    # handoff, release notes, rollout notes
  archive/     # final summary and decisions

Only create the folders that the task needs. Prefer Markdown. Use YAML or JSON only when a later agent, script, or check will consume the structure. Keep code in the real repository tree; this folder is for durable production artifacts.

Standalone Boundary

Atomic skills must remain usable without /ship:auto or any task directory. If the user names a phase directly, run that phase directly.

Default Choice

When intent is ambiguous, route to a bounded bundle instead of asking for the full pipeline by default. Examples:

• "Plan this" → /ship:design
• "Build this" → /ship:design → /ship:dev
• "Check this change" → /ship:review and/or /ship:qa
• "Make this production-ready" → quality bundle
• "Ship this all the way" → /ship:auto
• "Organize the production docs for this requirement" → create or update the appropriate docs/ship/<task-id-or-req-id>/ artifacts, using focused skills such as /ship:write-docs, /ship:arch-design, or /ship:visual-design