| name | shipspec |
| description | Use when implementing a feature, working from a Jira/task/request link, preparing or validating a spec, coordinating AI agents, collecting verification evidence, or preparing a review/ship handoff with ShipSpec or gsd. |
ShipSpec
ShipSpec is the delivery protocol for turning a request into an implementation-ready spec, agent room, verification evidence, audit trail, and handoff.
When to Use
Use this skill when the user asks to:
- implement a feature or bugfix with ShipSpec/gsd
- start from a Jira, Linear, GitHub issue, task, or plain request
- create or validate a spec before coding
- coordinate planner, builder, tester, reviewer, or release roles
- prove work is ready with verification evidence
- prepare a review, release, or done handoff
Do not use ShipSpec for quick one-off answers that do not edit code or produce a delivery artifact.
Workflow
From the project root, check the current state before editing:
gsd status
gsd next
gsd spec
gsd validate
For the goal-driven path, prefer:
gsd run "<user request or ticket title>"
gsd run prepares or continues the local mission, generates reasoning, prompt, context pack, risk, and UI artifacts, and prints the next best action.
For no-copy Codex handoff, use:
gsd codex
gsd codex prints a short instruction that tells Codex to use $shipspec and read the active mission, prompt, pack, proposal, and tasks from repo files. Prefer this over asking the user to paste long context.
When a repo has many possible AI skills, route before coding:
gsd route
gsd route writes .gsd/routes/<change>.md and recommends skills from the mission, local RAG evidence, likely files, and learned memory. gsd codex includes this route automatically. Read Agentic RAG before choosing optional skills, then use only the skills supported by repo evidence.
For full local Agentic RAG before implementation or review, use:
gsd rag "<question or feature area>"
gsd rag builds a private local index under .gsd/rag/, writes a cited retrieval report for the active change, ranks local files with snippets and reasons, scores context quality, and excludes secrets, dependency folders, build output, binaries, generated files, and huge files. Use it when the AI needs stronger file evidence than the normal context pack.
If there is no active change, create the ShipSpec package from the user's request:
gsd deliver --adaptive "<user request or ticket title>"
For a safe operator-style control loop, use:
gsd operate "<user request or ticket title>"
gsd operate prepares the adaptive package, runs reasoning, runs one safe verify/reflect/learn loop, refreshes gsd ui, and writes .gsd/operations/<change>.md. It does not edit code or deploy.
When the user wants Codex Plan mode to think before coding, generate the active change prompt:
gsd decision "<approved human choice, if one was given>"
gsd prompt
Use gsd decision for explicit human approvals or product choices before regenerating the prompt. Use the generated prompt as the Plan mode handoff. ShipSpec owns facts and files; Codex Plan mode owns reasoning and the implementation plan.
If a change already exists but needs missing artifacts:
gsd intake "<user request or ticket title>"
gsd contract
gsd room
gsd reason
gsd validate
Before claiming implementation is done:
gsd verify --full
gsd review
gsd loop
gsd audit
gsd validate --ready
For UI visibility:
gsd ui
Agent Room
Use .agent/room/<change>/ as the shared working area:
planner.md for scope, acceptance criteria, and unresolved questionsbuilder.md for implementation notestester.md for verification and evidence notesreviewer.md for risks and review findingsrelease.md for final handoff noteshandoff.md for compact cross-agent status
Use .agent/messages/ for short agent-to-agent handoff notes.
Handoff
When handing work back, include:
- active change name
- verification commands and results
.gsd/reports/<change>.md.agent/evidence/<change>.md when present- any audit gaps from
gsd audit
Never say the work is ready unless gsd verify --full and gsd validate --ready have passed, or clearly state what could not be run.
