New to the whole idea? /s:onboard runs a nine-step guided tour in a throwaway sandbox — nothing in your repositories is touched. The steps below unpack each command.
Install
The installer runs a doctor check — it verifies every prerequisite and prints the exact command to fix anything missing. It refuses to run half-configured.
Set up the statusline
Your coding agent reserves one line at the bottom of every session; shipd puts the spec in flight on it — name, lifecycle status, task progress — live. For the question you'll ask most (is it still going, and how far along?) you never run a command again.
Status is colored by lifecycle — draft grey through verified green. Epic members show their position (EPIC: export-cli, spec 2/5); during an autopilot run a breathing dot pulses with the run's heartbeat. No live change reads ☕ no active specs.
Plan — converge on the spec
Describe the change in prose. The Planner investigates your codebase first and asks only what it genuinely cannot infer, then names the change, opens a dedicated worktree, writes its artifacts — and stops. No code is written at this stage.
Read the three files. Right now the entire change is markdown — a wrong assumption costs one edit to fix. After the build it costs a rework. Planning ends with a deterministic context gate: pass promotes to ready; fail parks it rejected with the gaps written into plan.md — the engine refuses to build on guesses.
Build — gated, refuted, merged
The Orchestrator adopts the change in its worktree, delegates the checklist to execution sub-agents one model tier down, and keeps tasks.md current — boxes flip, the counter climbs. Done means verified against the delta spec's WHEN/THEN scenarios, not a vibe of "seems done".
Three durable outcomes, in three places:
Watch the board
The shipd CLI fronts the engine's read verbs — no raw script paths, JSON-first output for tooling.
The questions worth asking.
Which agents and models does it work with?
shipd ships as a plugin for Claude Code today — its skills are invoked as /s:plan, /s:build, /s:status inside your session. The spec engine underneath is deliberately LLM-free: exact-keyed CRUD over markdown, driven by plain scripts. No model ever reads or writes the library directly.
Roles are model-tiered, not model-locked: the orchestrator plans on the strongest model available, execution agents run one tier down, and the pipeline is config-defined — stages can be skipped, replaced, or extended per workspace, so other runtimes can slot in as the distribution opens up.
What does shipd see of my code? What leaves my machine?
The spec library lives in your repository, under your version control — .shipd/ is just markdown you can read, diff, and delete. Agents access your code the same way your coding-agent session already does; shipd adds no second channel.
Heavy inputs stay local by design: video ingest transcribes and diarizes screen recordings entirely on-device — no cloud transcription, no vision APIs — and only the cited brief enters the repo. Audio, frames, and raw transcripts never land in a checkout or a PR.
What if the validator is wrong?
The validator can only be wrong in the safe direction. It's adversarial — it tries to refute scenarios against the real, running code. A false refutation sends the change back to the execution agents; nothing is lost but time. And it never merges anything alone: CI must pass and the semantic review must be explicitly dispositioned by design.
When the earlier context gate finds a plan lacking, it doesn't guess — the plan parks as rejected with its findings written into plan.md, and a human enriches it before anything builds. Every guard is also inspectable and overridable: a refused transition tells you why, and --force exists when you know better.