Shipwright

A gated agentic dev lifecycle for Cursor and Claude Code. Traceable specs, a per-task red → green → refactor loop (TDD + optional quality signal), then verify → review → ship with decision-log provenance — all driven by sw- commands.

Orchestrators advance on green and halt at human gates (freeze, merge, feedback routing). Shipwright never auto-merges.

Plan policy: orchestration.planPolicy defaults to canonical (byte-identical to pre-022). Live proposed on /sw-deliver is opt-in only — see configuration.

• Traceable specs — frozen PRDs, tasks, and amendments live in your repo (optional issue-store backend stores them as provider issues — opt-in, default unchanged)
• issue-native dev-tracking — under issue-store: gap issues, commit/PR linkage with safe close-on-merge, doc-review via integrity-checked issue comments, and milestone grouping (; inert for file-store users)
• issue-derived planning graph — under issue-store: read-only INDEX/living-status from issue labels, epic/sub-issue phase hierarchy with checkbox fallback, redacted cross-project recall, and inFlight tracking-issue safety (; inert for file-store users)
• Deliver entry — /sw-deliver run accepts a frozen task-list path, --unit-id, or --issue (issue-store); /sw-status and planning-graph.py status report unified unit status (backlog | planned | in-progress | complete)
• WorkflowGraph runtime — after cutover, orchestrated deliver and doc/debug/feedback paths dispatch through the shared WorkflowGraph IR (scripts/graph/); live node progress and per-node explain stay on /sw-status and status_integrity.py — no graph-prefixed slash commands
• Workflow invariants — INVARIANTS.md documents four enforcement-backed guarantees (required-capability nonskip, monotone re-detect, authorized reduction only, absolute floor); regenerate CAPABILITIES.md via python3 "${CURSOR_PLUGIN_ROOT}/scripts/sw-run.py" capability_docs.py generate
• Graph runtime — after cutover, WorkflowGraph is the production execution runtime for deliver/doc/debug/feedback (status/explain on existing sw- commands; see graph-domain terminology)
• Async graph runtime — GraphScheduler single owning loop with concurrent node admission; orchestrator conductor fan-out is orthogonal (not a second scheduler)
• Authenticated cache — .cursor/sw-graph-cache/ MAC-trusted store separate from run journals; run-scope dogfood default (graphExecution.cache.scope: run)
• ExecutionBackend boundary — host-authoritative terminal envelopes for node work (scripts/graph/execution_backend.py); backend values advisory only
• Quick graph-native ship — /sw-ship compiles Quick tier to fixed WorkflowGraph; operator entry unchanged
• Retrospective closure — /sw-retrospective --post-merge closes linked planning-store units via planning_store.py close-delivery-units; gap resolved status transitions only through that loop
• Gated ship loop — verify, review, CI truth, stabilize; you merge
• Compounding memory — post-ship retro and durable project learnings
• Workflow intelligence invariants — four fail-closed assurance rules with enforcement paths in INVARIANTS.md; triage monotonic merge in scripts/triage_lib.py; TraceRef/CoverageEdge predicates in scripts/graph/traceability.py

flowchart LR
 CAP["Capture<br/>/sw-note · /sw-feedback"] --> EXP["Explore<br/>/sw-explore<br/>(optional)"]
 CAP --> SPEC["Specify<br/>/sw-doc"]
 EXP --> SPEC
 SPEC --> BUILD["Build<br/>/sw-deliver · /sw-ship"]
 BUILD --> MERGE([You merge — only human gate])
 MERGE --> LEARN["Learn<br/>/sw-retrospective"]
 OPS["Debug<br/>/sw-debug"] -.-> SPEC
 LEARN -.->|learnings| CAP

Loading

Adopter lifecycle: Capture → Explore → Specify → Build → Learn. Capture (/sw-note, /sw-feedback) and Explore (/sw-explore) are optional — skip either when scope is already clear and route directly to /sw-doc or /sw-deliver run. Routing examples:

/sw-note add "billing portal idea"          # Capture only
/sw-explore idea "billing portal pricing"   # Optional explore before spec
/sw-doc                                      # Specify → freeze → tasks
/sw-deliver run docs/prds/<n>-*/tasks-*.md  # Build to merge gate
/sw-retrospective --post-merge             # Learn after merge

New here? Read Getting started for guided persona paths, or jump to the deep-dive workflow guide. Legacy docs/guides/ paths remain as durable public redirect stubs.

Prerequisites

Check you have the essentials:

git --version && python3 --version

• Python ≥ 3.10 and git — the only runtime dependencies for install, hooks, gates, and tests
• Host credential — set host.credentialRef in .cursor/workflow.config.json and add a machine-local selector entry (~/.config/shipwright/credential-selector.json). During the one-release tokenEnv alias window, GITHUB_TOKEN (or host.tokenEnv) names the presence env var for an environment backend — no host CLI required.

Native keystore and platform matrix

On macOS and Windows workstations (not Linux, not containers), selector entries may use the keystore backend to read secrets from the native OS store (Keychain / Credential Manager) via ctypes — Shipwright does not use the Python keyring package. On Linux and in containers, use environment or github_cli instead; selecting keystore fails closed. Full matrix: configuration — per-platform backend matrix.

Install

Shipwright installs once per machine; you configure it per project repo. Once installed, sw- commands appear in the palette (e.g. /sw-init, /sw-doc).

Adopter vs contributor

Path	Audience	Setup
Adopter (default)	Using Shipwright in your projects	Install via uv tool or pipx (see below), then shipwright init --integration <host> in each repo
Contributor	Developing Shipwright itself	Clone this repo, run python3 scripts/install.py, then /sw-init in the clone

Adopters do not need to clone this repository. Contributors use the clone path — see Getting started — Contributor path and CONTRIBUTING.md for development workflow.

Adopter install: use uv tool or pipx to install in an isolated environment (avoids PEP 668 conflicts on modern systems), then initialize each project repo:

# Option 1: uv (recommended) — replace vX.Y.Z with desired release tag
uv tool install shipwright --from git+https://github.com/grdavies/shipwright.git@vX.Y.Z

# Option 2: pipx
pipx install git+https://github.com/grdavies/shipwright.git@vX.Y.Z

# Then configure each project
cd /path/to/your-project
shipwright init --integration cursor   # or claude-code | codex

See releases for available versions. See Getting started for additional install options including release wheels and the contributor clone path.

Contributor (clone this repo)

git clone https://github.com/grdavies/shipwright
cd shipwright
python3 scripts/install.py
/sw-init

Run Developer: Reload Window in Cursor. install.py mirrors the plugin locally and installs the editable shipwright console; /sw-init configures this repository for development.

Cursor (legacy inline clone snippet)

git clone https://github.com/grdavies/shipwright
cd shipwright
python3 scripts/install.py # copies dist/cursor/ → ~/.cursor/plugins/local/shipwright

Run Developer: Reload Window in Cursor. Override the destination: python3 scripts/install.py /path/to/dest.

Scripts access in consumer repos

After install, consumer project repos stay zero-footprint — /sw-init does not emit repo-local script façades. Helpers resolve from the installed plugin via install-root sw-run.py:

python3 "${CURSOR_PLUGIN_ROOT}/scripts/sw-run.py" wave_deliver.py -- --help

See Getting started — Scripts access and configuration — Scripts resolution.

Claude Code

git clone https://github.com/grdavies/shipwright
cd shipwright

Point your Claude Code plugin path at <shipwright-repo>/dist/claude-code/, or copy that tree into your Claude plugins directory per Claude Code docs. Reload Claude Code.

Configuration

Install the plugin once per machine; configure it per project repo with /sw-init (/sw-setup is a deprecated alias with identical behavior).

Open your target project repo and run /sw-init. It walks through project setup and writes .cursor/workflow.config.json — without writing repo-local Shipwright script façades. Consumer helpers resolve through the installed plugin via install-root sw-run.py (python3 "${CURSOR_PLUGIN_ROOT}/scripts/sw-run.py" <helper> [-- ARGS]). See Scripts resolution.

1. Memory provider — in-repo (default, committed markdown store) or another catalog-registered id (seeded: recallium). Operators select; authors register new providers in the catalog. Unknown ids fail closed at config write and hook resolve. For in-repo, choose committed (PR-reviewable) or local (gitignored).
2. Review provider — none (default) or coderabbit (opt-in AI review on PRs).
3. Project type + verify — detects manifests at repo root and proposes real verify.* commands from fixed presets (never vacuous placeholders).
4. Doc→implementation boundary (doc.afterTasks) — confirm (default) · stop · auto.
5. Guardrails — enforceBeforeSubmit (default on) and requireRuleClass (default off).
6. Model tier defaults — four-tier models block plus per-command routing from bundled defaults.

Re-run /sw-init at any time — it acts as a doctor against an existing config, surfaces version drift (configuredWith stamp vs installed plugin), and offers consent-gated refresh.

Base branch: workflow entry captures your trunk base (name + SHA) before worktrees are created; terminal PRs target that persisted base — not a hardcoded main. See configuration.

Worktree invariant: implementation never starts on bare trunk — use /sw-worktree and a feature branch. Review: review.provider defaults to none; CodeRabbit is opt-in. The canonical way to disable external AI review is review.provider: "none".

Configure verify.lint / verify.typecheck / verify.test so /sw-verify runs real checks. Full walkthrough and schema: configuration.

Deliver autonomy

After cutover, /sw-deliver (and the other orchestrators) compile onto WorkflowGraph as the sole production execution runtime — plan with --explain-plan, watch live nodes via /sw-status.

/sw-deliver runs an autonomous conductor by default (deliver.autonomy.mode: autonomous): it self-continues through phase dispatch, merge, and bookkeeping without per-step re-prompts. The legitimate halt set is minimal — terminal merge to main, exhausted remediation, destructive/ambiguous git, checkpoints (doc.afterTasks, supervised mode), phase timeout, external-wait exhaustion, or run-level budget (deliver.autonomy.maxRunMinutes / maxIterations). Parallel phases dispatch within worktree.parallelCeiling when the plan allows.

Living-doc currency: under file-store, post-cutover docs/planning/INDEX.md (unified INDEX) plus legacy projections docs/prds/INDEX.md, COMPLETION-LOG.md, and GAP-BACKLOG.md reconcile in-loop on the feature branch; drift hard-blocks the terminal gate. Under issue-store (planning.store.backend), those surfaces are derived or projected from the planning store — doc commands (/sw-amend, /sw-freeze, /sw-tasks) must not instruct hand-edits to INDEX/COMPLETION-LOG/GAP-BACKLOG in the code repo; mechanical reconcile projects to the store (or a gitignored cache) instead. Path keys: planningDir (canonical) with legacy prdsDir/tasksDir aliases pre-cutover.

Doc traceability: Full-tier PRDs carry brainstorm: frontmatter; writable brainstorms gain prd: back-links at draft/freeze time.

First run

1. /sw-doc — triage → (brainstorm) → PRD → review → freeze → single-pass /sw-tasks.
2. /sw-deliver run <frozen-tasks> — drives every phase to one merge gate; you merge.

Quick fixes skip the doc pipeline — see Getting started.

Workstreams

Four lifecycle workstreams sit on the foundation. Each has an orchestrator that chains atomic sw- commands; every atomic stays independently runnable.

Workstream	Orchestrator	Chain	Does not
Document	/sw-doc	triage → brainstorm (Full) → PRD → review → freeze → tasks	implement or merge
Implement	/sw-deliver	run → per-phase /sw-ship → auto-merge → terminal PR → main	bypass /sw-ship or auto-merge to main
Debug	/sw-debug	triage signal → RCA → route by fix size	implement or merge
Feedback	/sw-feedback	normalize + redact → route to debug / gaps / brainstorm	analyze or dispatch without confirmation

/sw-deliver is the default implementation path once /sw-doc produces a frozen task list — the "play button" that drives every phase of a feature to one human merge gate. Mode auto-detect picks phase-mode from --task-list vs multi-feature from --items/--edges. Use --dry-run for plan-only output; re-run run to resume after interrupt. Run the manual /sw-ship atomics directly only for Quick-tier hotfixes, debugging, or single-phase reruns.

/sw-cleanup is a standalone maintenance utility — not a workstream. After /sw-deliver detects the feature branch has merged it suggests a cleanup run; you confirm before any deletion. Prunes merged local and remote branches, stale worktrees, and completed deliver run-state. Dry-run by default.

→ Full per-tier flows, diagrams, and sample prompts: workflow guide.

Tiers

/sw-triage scores work deterministically; /sw-doc respects the result.

	Quick	Standard	Full
Scope	0–1 files, low risk	2–5 files, bounded	6+ files or ambiguous
Docs	skipped	PRD → freeze → tasks	brainstorm → PRD → freeze → tasks
Entry	manual /sw-ship	/sw-deliver run	/sw-deliver run

Risk floor: auth, payment, migration, webhook force at least Standard. Ambiguity bump: maybe, explore, TBD push a tier up. Details in the workflow guide.

Documentation layout

Canonical adopter guides live in core/documentation/. Platform emitters copy this tree to <install-root>/documentation/ in packaged installs — that install-root path is the authoritative home for adopters.

Public redirect stubs under docs/guides/ keep legacy GitHub paths alive; each stub points to the matching core/documentation/ page.

Capability docs (CAPABILITIES.md, core/providers/issues/CAPABILITIES.md, and core/sw-reference/capability-family-matrices.*) are generated from the machine-readable registry (core/sw-reference/capability-registry.json via scripts/capability_docs.py) — edit the registry and regenerate; do not hand-edit the markdown.

Guide	Purpose
Getting started	Adoption arc and first paths
Commands	Orchestrators vs atomics (includes /sw-note local notebook capture)
Workflows	End-to-end flows
Graph domain terminology	Planning vs execution graph vocabulary
Configuration	/sw-init knobs (issue-store providers include Linear)
CAPABILITIES.md	Generated from core/sw-reference/capability-registry.json — do not edit by hand
Style guide	Writing conventions
Glossary	Coined terms
Decision tree	Command routing
Testing	Verification and CI expectations
Trust anchors	Dist-only install trust verification

Public path redirects

Public stub	Canonical install-root page
docs/guides/getting-started.md	core/documentation/getting-started.md
docs/guides/commands.md	core/documentation/commands.md
docs/guides/workflows.md	core/documentation/workflows.md
docs/guides/configuration.md	core/documentation/configuration.md
Other docs/guides/*.md	Matching core/documentation/*.md

Learn more

Doc	Audience
Getting started	First run + persona quick paths
Workflow guide	Tiers, per-workstream flows, diagrams, prompts
Commands	Full command taxonomy
Configuration	/sw-init + every config key
CONTRIBUTING.md	Developing the plugin
PROVENANCE.md	Upstream sources

Acknowledgements

Shipwright builds on ideas and patterns from several open-source projects. We're grateful to their authors and contributors.

Project	Role in Shipwright	Repo
compound-engineering	Persona panel doc review, brainstorm dialogue, retro/compounding chain, and debug RCA patterns — adapted and integrated throughout the documentation and implementation workstreams	everyinc/compound-engineering-plugin
caveman	Ultra-compressed communication mode that powers Shipwright's token-efficient orchestration chat (lite → full → ultra intensity levels)	juliusbrussee/caveman

The compound-engineering plugin in particular gave Shipwright its doc-review persona panel, the one-question-at-a-time brainstorm dialogue, and the retro → compound → memory-sync chain. Those foundations let us focus on the durable delivery loop and gating mechanics rather than rebuilding from scratch. Thank you.

License

MIT