Ship feature

/ship-feature — the feature loop

Codifies the loop this repo ships features with, so a feature is one sentence instead of a re-explanation. Runs the cycle autonomously, stopping ONLY at the two decisions a human owns.

Input: a one-sentence feature description (e.g. "deploy a chat agent that books into the client workspace").

The loop

1. Brainstorm (superpowers:brainstorming) — explore the codebase context, ask the user clarifying questions ONE at a time, propose 2–3 approaches with a recommendation. → GATE 1: user approves the design.
2. Spec — write docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md. Ground every recon-dependent assumption by actually reading the code (dispatch an Explore agent for the seam — don't guess). Commit.
3. Plan (superpowers:writing-plans) — bite-sized TDD tasks, exact files + code, commit-per-task; docs/superpowers/plans/YYYY-MM-DD-<topic>.md. Commit.
4. Build (superpowers:subagent-driven-development) — dispatch a fresh implementer subagent (the maker — model per the tier table below; effort medium). Brief it with: the regression set named, idempotent + soft-fail where it touches shared paths, migrations additive + journal-clean, DI for offline unit tests, TDD (watch each test fail first), commit-per-task — first commit at the first coherent unit; a dead session must cost minutes of salvage, not a wave.
   • Swarm for breadth: parallel scout/Explore agents for recon, parallel per-phase implementers in SEPARATE worktrees where the phases are independent. One strict checker for depth.
5. Verify — run /verify-build as the controller (maker ≠ checker — independently re-run the gate; dispatch the verify-runner agent, plus vision-grader for anything with a visual surface and smoke-runner post-deploy). FAIL → hand back to the implementer; never wave it through.
6. Merge — only on a green verdict. → GATE 2: user makes the merge call (especially with a migration or a behavior change). FF to main; confirm the migration count; push.
7. Memory — write what was non-obvious to memory/ (project state, a new constraint); update the roadmap. Distill any correction the user made into a one-line rule in tasks/lessons.md so the next loop doesn't re-derive it.

Token economics — right-size every dispatch

The loop is already fidelity-routed: subagents are drop-and-retrieve (they read big, return a gist), file handoffs are the manifest, /verify-build is the gate. The leak is routing mechanical work to expensive models and ignoring the token readout. Lock the tier; contract the output.

Model tier per role — LOCK THIS (don't re-decide each dispatch)

role	model	why
scout · locate-a-fact	haiku	Read → return a span; never raw dumps into the controller
grader · vision / verify	haiku (pinned)	Read artifact → {pass, gaps}; pinned in the vision-verify skill so it can't drift
summarizer · classify	haiku	cheap text transform
implementer · brief already contains the code	haiku	transcription + run the tests
implementer · prose brief (the maker)	sonnet	writes real code from a spec, effort medium
implementer · hard / novel / architectural	fable	generation is where the best model's edge is load-bearing
reviewer · normal diff	sonnet	judgment, scaled to the diff's risk
reviewer · hot-path · money · auth · schema · concurrency · subtle	opus	reads a diff at least as well as fable for ~38% of the cost; also decorrelates blind spots when the maker was fable
final whole-branch review	opus	broad, top-tier, once

• Spend fable (Fable 5) on novel GENERATION, not on reading diffs. At $10/$50 + its ~30%-heavier tokenizer, a Fable review costs ~2.6× the identical Opus review with no demonstrated catch-rate edge — and Fable's weekly cap makes it an unreliable default. Reviews default to opus; escalate a review to fable only for a genuinely novel architecture where generation-grade reasoning is required to even understand the diff.
• Prices (per MTok in/out, 2026-07): haiku $1/$5 · sonnet $2/$10 intro ($3/$15 from 2026-09-01 — re-audit this table ~Aug 25) · opus $5/$25 · fable $10/$50 (+~30% tokenizer). Aliases: haiku=Haiku 4.5 · sonnet=Sonnet 5 · opus=Opus 4.8 · fable=Fable 5.
• Enforcement is mechanical, not discipline: the pins live in the NAMED AGENT DEFINITIONS in .claude/agents/ (scout · implementer · reviewer · vision-grader · verify-runner · smoke-runner) — dispatch by subagent_type and do NOT pass a model unless deliberately escalating per this table (fable for novel generation; sonnet for a small normal-diff review). A real session's tier table said grader → haiku and the dispatch still ran Sonnet (~218k tokens, the biggest line item) — a locked table enforced by memory isn't locked; a model: in agent frontmatter is.
• Diff-size router: a ≤~200-line single-task, non-money/auth/concurrency change gets ONE review (skip the per-task + final double-read — they'd read the same lines); <50 LOC mechanical fixes can go haiku-implementer + one sonnet review. Reserve the two-tier review for multi-task branches where the final adds cross-task integration coverage.
• Right-size the task, not just the model. Before a read-a-file / hand-a-file-to-a-subagent step, check the size — if it's big, the task is "grep/jq/node the span", never "Read the whole file" (a haiku scout handed a 242k-token log just fails). Drop+retrieve at the task level: the controller holds the plan + conclusions; files/greps hold the bytes.
• Batch the grade wave when nothing blocks on it: vision-grade fans and other fire-and-forget verification can ride the Batch API (50% off) — a human gate follows anyway, so the async latency is invisible. Never batch interactive stages (recon feeding a live plan, the implementer you're waiting on).

Output contracts (the 5× slice)

Output is ~5× input price and dominates once input is lean:

• Subagents report to a file, return only status + commit shas + a one-line test summary — never paste a full report back into the controller.
• Workflows force structured returns with a schema: instead of prose.
• Implementers return diff-only edits (Edit, not full-file rewrites).
• The controller narrates at most one short line between tool calls — the ledger and tool results carry the record.

Operational rules

• One wave per deploy, one publish per session: batch all finished, reviewed work into ONE fast-forward push to main per deploy cycle; npm version bumps (skills/mcp-server) ride the LAST wave so the human runs npm publish + 2FA exactly once. Never have them publish, then bump.
• Deploy time = recon time: a Vercel build in flight means the next build's scout or a live-smoke watcher is already running in the background. Post-deploy, verify against a cheap unambiguous marker (a changed response field, an auth code) before burning rate-limited smoke actions.
• Session-cap discipline: at most one heavyweight background implementer near the usage cap; inline edits beat a subagent below ~100 changed lines; on any cap warning, commit WIP immediately and shrink to inline.
• Human actions arrive as ONE batch: publishes, env vars, submissions, approvals — a single consolidated queue per wave, never a dribble.

The two gates (the only places this stops)

• Spec approval — the user confirms the design before a plan is written.
• Merge — the user makes the merge/deploy call.

Everything between runs without check-ins. Don't ask "should I continue?" — execute.

Rules

• Loop the build, keep the judgment. This skill ships well-specified BUILD work. Strategy, positioning, and "which approach" calls stay with the user — never loop judgment.
• Maker ≠ checker is non-negotiable — the agent that built it does not verify it.
• Only run the full loop when the work is non-trivial (3+ steps / a migration / shared-path changes). A one-line fix is just a fix.
• Read tasks/lessons.md at the start of every run — it's the constraints file that makes the loop smarter run-over-run.