ship-fleet

Ship Fleet — backlog-wide feature orchestrator

Take everything that remains in a repo's feature pipeline and drive it to merged, verified production code. You are the orchestrator: survey the pipeline, build one durable plan-and-ledger (ORCHESTRATOR.md), then conduct concurrent ship-feature:ship-feature runs in dependency order — verifying, merging, and updating the ledger as each lands. One feature = one run; your job is everything between the runs.

preflight → survey → hygiene → artifacts (ORCHESTRATOR.md + hierarchy html, BEFORE execution)
  → serial pre-triage → fleet (dependency-ordered ship-feature runners, global agent budget,
    lane-routed subagents + executor lanes, out-of-family gates, per-item cross-family verify,
    serialized merges, ledger updated after every event)

Everything is discovered inside the project — never hardcode paths. Conventional layout (markdown lane; the tasks lane swaps the ledger/specs for the board, per shipyard's references/tracker-adapter.md): ledger at docs/features-to-triage/LEDGER.md (older repos docs/feature-specs/LEDGER.md — pick what exists, never create both), specs docs/specs/, plans docs/plans/, briefs docs/features-to-triage/, mocks under design/, research docs/deep-research/, DESIGN md at root, worktrees .worktrees/<ID> on ai/<id> (git worktree list is authoritative).

Running as a Gemini model? Read gemini.md in this directory first, then follow this file with the overrides it names. It turns the survey's categorical scopes and the runner brief's ENTIRE-UI clause into counted worklists, makes every ledger status carry the command that produced it, and routes orchestrator-hierarchy.html and the serialized merge to another model. Other models skip it.

Operating discipline

• You stay in-session, holding the map. Runner roles follow the user-selected model policy in shipyard's references/model-lanes.md. Resolve a supported agent/CLI route and observe its execution; do not force every runner to Opus or assume one harness's background behavior applies to another. Keep integration decisions with the conductor.
• ORCHESTRATOR.md is the memory, not the transcript. Update it after every state change; a fresh session must be able to resume the whole fleet from that file alone. After compaction: re-read it, the DESIGN md, and the ledger before acting.
• Plan before execution — both artifacts written, shown, committed before the first slot.
• Dependencies rule the schedule. An item never starts before its internal dependencies have merged (not merely finished). External dependencies flag and skip an item; they never stall the fleet.
• Five concurrent agents is a correctness limit, not a throughput preference. Going wider does not slow a wave down — it kills agents that never emit a token. Measured 2026-08-26: 92 agents died silently, 88 of them at exactly 180.0 seconds, each leaving a four-line transcript ending [Request interrupted by user] with no assistant message and no error row anywhere. A wave of eight that loses three is slower than a wave of five that loses none and looks identical in every counter. Corroborated externally on a different harness: accuracy peaks near five concurrent agents and degrades after, with timeout errors climbing from ~3 to 50. Treat a request to run wider as a request to lose work silently.
• A global agent budget, not two independent caps. Runner slots × each runner's inner ≤4 waves multiply into the same rate limiter — budget the product (default: slots × wave ≤ ~16; keep the number of runners within the resolved user/tool/five-runner cap and reduce inner waves as needed). Record the selected concurrency; ask only if it exceeds existing authorization.
• Take the slot count from harbourmaster:harbourmaster. Its berths.py reports what this Mac can carry right now, and the loop re-reads it on every refill because pressure moves under a long fleet. If the governor is missing or unreadable, use min(2, maxRunners), where maxRunners already respects the user, tool and five-runner caps. A measured zero launches no work; persist the scheduling state and wait through the supported resume mechanism. Resolve its path once in the conductor and pass that path into every runner's brief — a spawned agent does not reliably inherit CLAUDE_PLUGIN_ROOT, so a runner that re-derives the path finds nothing and reports harbourmaster missing on a machine that has it. references/scheduling-and-concurrency.md carries the resolution, the hand-down, and the soft-fail. Say in the go-ahead which slot count you used and whether it was measured.
• Never destroy unmerged work. Cleanup removes only the provably merged or empty; unique commits queue for resume or go to the user.
• Report thinly; artifacts terse. ORCHESTRATOR.md is rows and statuses, never prose.