Docs

The idea behind shipd.

shipd is a spec-driven delivery system for AI coding agents. Instead of prompting an agent and hoping the result matches what you meant, it makes the agent converge on a specification first — a plan, testable requirement deltas, and a mechanical task list — and only builds once a deterministic context gate confirms nothing is missing.

The spec, not the chat transcript, is the single source of context every agent works from — so what got built and what was asked for are the same document, checked into your repository. What is shipd? tells the whole story.

Start here

  • What is shipd?

    The mental model behind shipd: specs as compiled context, and the delivery loop that turns ideas into verified changes.

  • Getting started

    A guided first session with shipd, from install to a merged pull request.

Reference

  • Command cheatsheet

    Every shipd command at a glance: the /s: skills and the shipd CLI verbs.

  • PRD reference

    The PRD formats in full: header keys, the three template tiers, the status vocabulary, and the command surfaces that read them.

  • Copilot review reference

    What the review gate installs, how it derives a verdict from a review, and the settings that govern it.

  • Semantic review reference

    The --json finding payload, the lint configuration key, and the output of the prior verb.

Concepts

  • The oracle

    How the oracle answers routine decisions from durable knowledge before anyone is interrupted.

  • Guardrails

    The rulebook that reminds agents of repo conventions as they work.

  • The supersession gate

    How shipd detects a planned change that main has already implemented.

  • PRDs

    The discover phase as an artifact: where a PRD is stored, how it resolves across a workspace, and the interview that writes one.

  • Workspaces

    The workspace model in one page: what a workspace repo is, plus a linked guide of five part pages.

  • The shipd review inside GitHub Copilot code review

    The shipd semantic review running inside GitHub Copilot code review, and the merge gate it powers.

  • The semantic review

    What the review reads, the passes that look past the changed lines, and how it rates what it finds.

Workspaces

  • Getting started with workspaces

    Machine setup, creating a job workspace, checking it into git, and the day-to-day verbs.

  • Nesting and external stores

    Filing a job workspace beneath a base one, and relocating shipd artifacts out of member repos with store_root.

  • Team workspaces

    Several engineers on one workspace repo: what travels between them, the consent gate, and the conflict surfaces.

  • Headless consumers

    The minimal footprint a CI job, bot, or cloud agent needs to read a workspace.

  • Multi-workspace repos

    The two shapes for carrying several workspaces in one repo, with layouts, storage tables, and trade-offs.

  • The member map

    The machine-local file that records where a workspace's member repos live and which workspace a checkout belongs to.

How the skills overlap

PipelineOrchestrationMemory
Spec,
build, ship
Epics, driven
Decisions
that stick
Unattended
Asks
first
Evidence
Compounds
  • Spec, build, ship — the pipeline, one change end to end: s:onboard, s:doctor, s:duck, s:plan, s:fix, s:review, s:drive, s:gate, s:status, s:document, s:worktree-hooks
  • Epics, driven — orchestration across many changes: s:epic, s:prd, s:initiative, s:workspace, s:explain
  • Decisions that stick — memory that outlives a change: s:remember, s:memory, s:forget
  • Unattended — s:build, s:autopilot
  • Asks first — s:ask
  • Evidence — s:research, s:video-ingest
  • Compounds — s:teach

See the full cheatsheet