How it works

From stated intent to a merged, verified pull request.

Every change flows through the same five stages, with a context gate before any code is written and an independent validation before anything merges. Gates are only ever skipped through explicit configuration.

01
Intent
prose · brief · recording

An idea, a research report — or a screen recording. shipd turns a recording into a cited brief, grounded frame by frame: every claim carries a timestamp, a speaker, and the frame that was on screen when it was said.

→ research/<slug>/report.md · video/<slug>/brief.md
02
Converge
codebase-first investigation

Agents investigate your codebase first, climb the question ladder for what's left, and compile intent into three reviewable artifacts: a plan with its decisions, testable requirement deltas per capability, and a mechanical task list.

→ plan.md · specs/<capability>/spec.md · tasks.md
03
Gate
deterministic · LLM-free engine

A context-sufficiency gate checks the plan against the real codebase before a line of code is written. Insufficient context parks the plan as rejected for human enrichment — the system never builds on a guess.

→ status: ready | rejected (with findings in plan.md)
04
Build & refute
orchestrator · executors · validator

The orchestrator designs on the strongest model; execution agents one tier down claim tasks atomically. Then an independent validator tries to refute every scenario in the spec against the real, running code. Refuted goes back; only confirmed moves on.

→ one change · one worktree · one branch · one PR
05
Ship & record
CI + semantic review · auto-merge

CI and a semantic review that must be explicitly dispositioned gate the merge. On ship, the deltas merge into a versioned capability library and the change archives — the system always knows exactly what it can do.

→ verified/<capability>/spec.md · completed/<date>-<change>/
the capability library compiles context for the next change
The question ladder

Most questions never reach you.

Before shipd asks you anything, it climbs a ladder: the codebase first, then the workspace wiki and personal memory store, then an "ask-first" oracle holding your standing positions. Only a question none of them can answer reaches a human — and once you answer, the answer is recorded so it's never asked twice.

01Codebase investigationanswers most
The plan reads before it asks: call sites, tests, config, and the verified capability specs from every change that already shipped. Most questions die here — the repository already answers them.
↓ escalates only if unanswered
The workspace wiki holds the job's recorded decisions; your personal memory store holds preferences that follow you across projects. Both are consulted silently. Every /s:teach adds coverage, so this rung catches more the longer you use it.
↓ escalates only if unanswered
An ask-first agent holding your standing positions, answering on your behalf with citations. Every consultation is recorded in the plan as a Q<n> ledger entry — and /s:teach <change> Q<n> replays one so you can correct a position it got wrong.
↓ escalates only if unanswered
Only a question no lower rung can answer reaches you. Your answer is written back into the wiki and the oracle's positions — so the same question never climbs the ladder again. The goal: a path you're needed on less and less.
every answer you give teaches a lower rung — over time, less escalates to you
Division of labor

Three roles, tiered by model strength.

ORCHESTRATOR
Plans and designs
Runs on the strongest model. Owns investigation, the spec, and the architecture of every change.
EXECUTION AGENTS
Claim and implement
One tier down. Claim tasks atomically from the task list and implement against the spec — never the transcript.
VALIDATOR
Tries to break it
Independent and adversarial. Attempts to refute every scenario in the spec against the real, running code before anything merges.
every change:worktreebranchPRCIsemantic review (explicitly dispositioned)mergedcapability library
Autopilot

One human approval: the epic.

The autopilot picks up an approved epic in whatever state it's in and drives it as far as it can go, gating when needed. Members you already planned run on your specs; the rest it plans itself from the context you've provided. A member the gate finds lacking is parked as rejected for you to enrich — the run continues without it. A live board tracks every run.

the autopilot pipeline · per member, sequential, risk-ordered
1 · you approve the epic
the only human touchpoint on the happy path
2 · plan
3 · context gate
insufficient? side branch:
wiki → memory → oracle
still open → parked as rejected
you enrich → ↺ rejoins at plan
other members continue meanwhile
4 · build
execution agents claim tasks atomically
5 · refute
validator attacks every scenario
6 · ci + review
7 · merged ↺ next member
a parked member pauses only itself — the run continues with the rest and reports it

Try it on your next change.

GET STARTEDREAD THE FAQ