Spec-driven agent orchestration

Context before code.

shipd compiles what you mean into a spec, gates the agent on it, and verifies the result against it, so you ship software you can trust and verify.

Install
$curl -fsSL https://shipd.now/install | shcopy
getting started →
Open by design

Why Shipd?

Shipd captures context unlike any other agent tool. You keep the specs, decisions and standing answers as plain, reviewable files in your repository and your workspace, not behind a login. Every part of shipd is a skill you can pick up on its own. The basics alone plan and build a change, and what they learn lands in a workspace any other skill can use later.

What context before code means

How it works

shipd is a collection of open-source skills built to the agentskills.io standard: together, a holistic end-to-end software delivery pipeline; apart, whichever ones you like. shipd is what you make of it.

Basicsplan, build, onboard
/s:plan <intent>codebase-first · asks once

Plan a change

Reads your codebase first, climbs the question ladder for whatever is left, and compiles intent into a plan, testable requirement deltas and a task list. Stops for your review; it never builds from a guess.

→ plan.md · delta specs · tasks.md — status: ready
/s:build [change]orchestrator · executors · validator

Build a change

Runs the context gate, checks the plan has not been superseded, delegates every task to execution agents one tier down, then lets an independent validator refute each scenario before the semantic review gates the merge.

→ one worktree · one branch · one merged PR
/s:onboardnine steps, you drive

Take the tour

A nine-step walkthrough you drive one step at a time. Steps 1–7 explain the artifacts over a throwaway example, step 8 builds it for real, step 9 hands you your first command.

→ a working example + your first command
Contextturn intent into spec
/s:research <question>cited report

Research a question

Decomposes an open question into bounded parts, searches each, reads the strongest sources and composes a report in which every claim carries a citation. An epic can link it.

→ research/<slug>/report.md, fully cited
/s:video-ingest <file>screen recording → brief

Plan from a recording

Transcribes a screen recording on-device, grounds each spoken claim against the frame that was on screen, and resolves contradictions by recency.

→ brief.md — timestamp · speaker · frame per claim
/s:prd <idea>interrogated, lint-clean

Write a PRD

Interrogates a product idea until it holds up, then installs a lint-clean workspace PRD through the engine's staged emit so epics can cite it.

→ a workspace PRD
/s:duck <idea>read-only critic

Rubber-duck an idea

An adversarial critic for an idea that is not planned yet. It reads the repo, pushes back instead of agreeing, names the strongest alternative and points at the skill that should pick the idea up. It changes nothing.

→ critique · one primary question · the next command
/s:epic <feature>shared decisions · member table

Decompose an epic

Breaks a feature too big for one PR into shared decisions, a design and a table of member changes with complexity ratings, then stops. Members are planned one at a time.

→ epic.md + a risk-ordered member table
/s:document <target>house standard, linted

Write the docs

Authors or rewrites documentation against the shipd documentation standard, classifies each doc as concept, how-to or reference, and lints it clean. Docs only; nothing is shipped.

→ docs that pass the standard's lint
Knowledgedecisions, made once
/s:ask <decision>ask-first, cited

Ask the oracle

An ask-first agent answers one compact decision from your standing positions, with citations, before any person is interrupted. What it cannot answer is queued for a human; the run never blocks.

→ a cited recommendation, or a queued question
/s:teachspec artifacts → wiki

Teach the system

Distills this repo's spec artifacts and answered queue entries into the workspace wiki, interviewing you only on the gaps and contradictions the scan surfaced.

→ wiki pages + drained queue entries
/s:remember <preference>personal memory store

Remember a preference

Captures a durable preference into the personal memory store through one confirmed write. Every future plan consults it before asking you.

→ a memory page in the personal store
/s:memory · /s:forgetread and delete

Browse or forget

List every preference the store holds, or remove one after a single confirmation: the read and delete counterparts to remembering.

→ the stored preferences, edited
Guardingnothing builds on a guess
spec_gate.py <change>deterministic · LLM-free

Gate on context

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

→ ready, or findings attached to the plan
/s:gatesemantic-review status

Install the review gate

Installs the managed files, requires the semantic-review check on the repository and enables auto-merge, taking your consent before anything changes on GitHub.

→ PRs blocked until the review is dispositioned
/s:status [change]lifecycle, guarded

Guard a transition

Reports a change's lifecycle position, validates its structure, or runs a guarded transition that asks before forcing past a guard.

→ draft → ready → active → complete → verified
/s:doctorread-only preflight

Diagnose the setup

A read-only preflight reporting ok, warn or fail per check. Proposes one remedy per remediable finding and runs only what you consent to, then re-runs and reports before and after.

→ a green preflight, or the exact blocker named
shipd lint [change]grammar · coverage · consistency

Validate the library

Structurally validates specs and change deltas: requirement grammar, scenario coverage and delta consistency against the capability library.

→ findings with file + line · an exit code for CI
Validationchecked, not assumed
s:validatorindependent · adversarial

Refute every scenario

An independent validator spawned by build tries to refute every scenario in the spec against the real, running code, and returns one verdict per scenario. Refuted goes back; only confirmed moves on.

→ confirmed or refuted, with evidence, per scenario
/s:reviewAST-aware · cohorts

Review a diff

A semantic review of local changes against a base ref: files grouped into cohorts, changed signatures chased to their call sites, findings rated high, medium or low, and a ship-it or fix-required verdict posted to the PR.

→ findings by cohort · a verdict on the PR
/s:fix <symptom>spec-grounded repair

Fix a bug

Retrieves the related specs, reproduces the failure and repairs the code that drifted from documented behaviour, with a regression test. Never edits a spec, never opens a PR.

→ a reproduction · a regression test · a fix
/s:drive <instructions>real browser, Playwright

Drive the app

Drives a real browser to operate your app and verify a change against it: probes the live DOM before authoring a selector, waits for a named completion signal, and ends on a pass or fail verdict backed by console and network evidence.

→ PASS or FAIL, with evidence
/s:demo <change>branded video

Record a demo

Records a branded demo video of a change, through the browser for a web app or a terminal tape for a CLI, and stops on a missing tool rather than attempting a doomed recording.

→ a branded demo video
Workspacesone job, many repos
/s:workspace clone <url>one job, many repos

Stand up a workspace

Creates, inspects, clones or syncs a portable workspace: a manifest plus job wiki whose member repos materialize on this machine via the sync ladder of worktree, reference-clone or full clone.

→ a ready cross-repo job directory
/s:worktree-hookspost-worktree setup

Script a fresh worktree

Authors and registers the setup scripts every fresh worktree runs, so a new change branch starts with its dependencies and environment in place.

→ registered worktree hooks
/s:initiativebriefs · outcomes

Track an initiative

Authors a lint-clean outcome brief from a workspace-first interview, reports every initiative's requirement progress, reviews a brief's outcomes, or attaches one to an epic.

→ a brief · outcome progress · an epic tag
Managementepics, delivered and watched
/s:autopilot <epic>plan → gate → build → PR

Deliver an epic unattended

One human approval, the epic, and every unplanned member is driven plan, gate, build and merged PR in risk-ascending order, one worktree and branch each. A parked member pauses only itself.

→ member PRs + a resume pointer per parked member
/s:explain <epic>under 100 lines

Explain an epic

Reads an epic through the engine and explains what it is for, the decisions holding it up, how its members compose and where delivery stands, with a diagram only where one carries structure.

→ a short explanation of the epic
shipd boardfull-screen board

Watch delivery live

The full-screen delivery board: what is in flight, what is parked, what merged this week and which agent is doing what right now.

→ the live board, or JSON for your own tooling
shipd list · shipd metricsJSON-first

List and measure

In-flight changes across the repo root and every worktree, plus throughput metrics derived from the immutable archive.

→ human-readable or JSON-first output

Shipd builds itself

386
changes shipped by its own pipeline
62
verified capabilities in the library
18
epics — autopilot delivers approved ones unattended
review-verifier-rubricshipped
review-stage-rubricsshipped
review-revert-to-260shipped
review-rating-verifiershipped
review-drift-spawnshipped
+ 381 more shipped · lifecycle: draft → ready → active → complete → verified

Shipd: your personal software delivery system

$curl -fsSL https://shipd.now/install | sh
then, in your repo: /s:plan → /s:build → merged PR