Shipwright

At a glance

• Outcome: Runs coding-agent work from framing through an explicit bet and witnessed acceptance criteria.
• Status: Works as a private tool built June–July 2026. Remains in use on the author’s projects.
• Role: Solo.
• Stack & libraries: Uses TypeScript for a harness-agnostic core containing the state machine, renderers and disk format. Adds a Pi extension, Codex drive CLI, shared Claude Code MCP server and read-only local viewer.
• Source: Private across seven repositories: one Pi package containing the core, one Claude Code edition and five companion packages.
• Limitations: Supports one person’s workflow with incomplete ports. Tests core harness independence, but conformance checks serialized bytes instead of replaying every port end to end; some help text still uses Pi commands. Keeps variants in separate repositories beside their harnesses.

Workflow model

Tracks code, symbols, systems, decisions, invariants and goals, plus active files, assumptions and failed approaches. Uses LSPs or repository maps instead of replacing them. Draws on Shape Up and BMad, adding expert input and verification.

Defines nine phases: Frame, Shape, Bet, Elaborate, Plan, Execute, Verify, Retro and Ship. Frame selects a model-recommended, person-approved track: tiny runs three phases (Frame, Execute, Verify), small five, medium seven and large nine. Large gates Bet and Ship; medium persists Bet before Plan and gates Ship; tiny and small continue without persisted gates unless stopped.

Workflow spine

Stores state, ledger, checkpoint, task graph and phase artifacts as plain files called the spine. Pins exact bytes with golden fixtures and rejects schema changes without migration fixtures. Runs under Pi, Codex and Claude Code, supports API-free viewing and resumes crashes from disk.

Tests every core source file and fails on any harness SDK import, preventing harness coupling.

Verification and control

• Pairs every acceptance criterion with a harness command and records its exit code. Produces evidence listing changes, verified checks, failures and skipped work with reasons. Sets verified only after at least one check exits 0 without kills or skips; otherwise sets verification_incomplete for missing commands, killed processes or empty lists.
• Persists dismissed gates and presents them again after resume, preventing cancellation from becoming approval.
• Appends one delta ledger entry after leaving a phase. Records primary, supporting and test files; first-run commands; decisions; changed assumptions, questions and failed approaches; and verification. Avoids appends when re-entering a phase and lets later sessions read results without replaying work.
• Re-prompts from the checkpoint between gates and asks one function whether to continue. Stops for witnessed verification, a person-gated decision, a user-only question, spent budget or a stall. Sets Frame budgets by track to 3, 5, 8 or 12; escalates after three identical fingerprints of working set, failure memory, open questions and activity counter. Prints every stop reason on one line.
• Serves read-only review through the artifact viewer. Prevents gate decisions, task edits and artifact mutations, separating review from approval.

Companion packages

Maintains five standalone tested packages: pi-distill extracts structured command output; pi-archetypes curates code patterns; pi-crew spawns subagents in nested processes; pi-flight writes one compact local-only JSONL event per line; pi-blueprint renders the ledger as static HTML. Prefers machine-readable output to human-output parsing and shaped context to added context.

Clankkers extends the event log and gate model from one workflow to durable supervision of many agent processes.