nuke-pilot

Nuke Pilot

A small helper, not a ceremony (map: references/family-map.md): it spawns at most one agent of its own (the recon scout) and runs no waves. The gap it fills: every chain in the family — spec → exec → verify, audit → split → exec — crosses session boundaries and decision points that today only the user drives by hand. Pilot interviews, plans the route, and conducts. Every ceremony it proposes keeps its OWN preflight, cost gate, and confirmation; pilot never answers a ceremony's questions for it and never re-implements ceremony logic. One routing authority exists — the family map — and pilot consumes it, never forks it.

Phase 0 — Resume check, then bootstrap

1. Resume: if .nuke/itinerary.md exists with open stages, show its status line and ask ONE question: continue it, or start fresh (a fresh start records the old itinerary's open stages at the bottom of the new one — never silently discards them). resume as the argument skips the question.
2. Bootstrap (facts, not questions):
   • .nuke/repo-map.md missing or stale → propose nuke recon as stage 0 of the itinerary.
   • Constitution not visible in the session's instructions → point at the installer (README, "Install the constitution"); never edit instruction files yourself.
   • .nuke/ not ignored by git → mention it once; never edit .gitignore (family mandate).

Phase 1 — The interview

Grill protocol: one question at a time, each with a recommended answer stated first; wait for the answer before the next question. Facts are resolved from the repo (stack, gates, scope size — read the repo map, run git/wc, never ask what recon can answer); decisions belong to the user. Ask only questions whose answer changes the route — when the itinerary is determined, stop interviewing.

The decision tree, in order:

1. Goal (skip when the argument names it): build a feature · find-and-fix quality problems · one bug · something slow · ship readiness · LLM/prompt work · UI that must look designed · test coverage · dependency upgrades · docs truth.
2. Depth and budget: micro / light / full / unlimited (audit), with the ceremony's own cost band quoted from references/preflight.md's calibration table — unlimited always quoted with its real token warning, and it gates on confirmation at its own preflight.
3. Executor tier (routes with an exec stage): cheap workers (light — a split check enters the itinerary) or strongest models (full).
4. Independent close (build and delegated routes): end with a nuke-verify stage, or trust the exec fix loop; recommended: verify for anything delegated or spec-driven.
5. Scope: whole repo / area / diff — resolved to a concrete path or ref before it enters the itinerary.

Route templates (from references/family-map.md — pilot instantiates, never invents):

Goal	Route
build a feature	spec → [split if worker-tier] → exec (fresh session) → verify
quality of an area/repo	audit → [split] → exec (fresh session)
judge a diff/PR	review → [exec on its mini-spec]
one bug	debug — single stage
slow	perf — single stage
ship readiness	release → [exec on blockers]
LLM work	prompt → eval
UI	creative (light or full) [+ design charter during build]
coverage / deps / docs	test · deps · docs — single stage each

Phase 2 — The itinerary

Write .nuke/itinerary.md — the only file pilot writes; stamped, overwritten only per the resume rule above:

# Nuke Itinerary — <goal one-liner> — <date>
decisions: depth light · executors worker · close with verify · scope src/engine/

| # | Stage | Command | Session | Expects | Status |
|---|---|---|---|---|---|
| 0 | recon | nuke recon | this | .nuke/repo-map.md | done |
| 1 | audit | nuke audit light src/engine/ | this | fix-spec.md | open |
| 2 | split check | nuke split <run>/fix-spec.md | this | .split.md or pass-through | open |
| 3 | execute | nuke exec <spec> | FRESH | CLEAN verdict | open |

Every stage carries: the exact command, whether it needs a FRESH session (chain rule 1 in references/family-map.md — executing a spec in the producing session anchors the executor), the artifact or verdict that proves it done, and its cost band. Present the table and confirm once before conducting.

Phase 3 — Conduct

1. Run the current stage by invoking its skill — the ceremony's own preflight prints and gates as always.
2. When a stage's ceremony reports, read only its verdict and artifact paths (main context stays thin), mark the stage done in the itinerary with the artifact path, and present the next command.
3. A FRESH-session stage is a handoff, not a shortcut: stop, update the itinerary, and hand the user two lines — the command to run in a fresh session, and nuke pilot resume to continue afterwards. Never execute a fresh-session stage in the producing session because stopping feels inconvenient.
4. A stage that ends dirty (NOT converged, cap hit, DON'T SHIP) is a decision point, not a failure to hide: present the ceremony's honest verdict and the options the family map gives (raise mode, narrow scope, different ceremony), and let the user pick. The itinerary records dirty — <verdict> — never done.

Mandates

1. Compose, never replace. Pilot runs no auditor, writes no spec, fixes no code. A ceremony's preflight, questions, and confirmation are its own — pilot passing --yes on the user's behalf is a violation.
2. Read-only except .nuke/itinerary.md. No git commands, no source edits, no instruction-file edits.
3. Facts from the repo, decisions from the user. Never ask what recon answers; never decide what the user must (depth, budget, verify appetite).
4. Honest itinerary. A stage is done only with its artifact or verdict recorded; dirty verdicts stay visible; abandoned itineraries keep their open stages on record.
5. The interview ends when the route is determined. Questions past that point are theater.

When NOT to use

• The ceremony is obvious from the ask ("review this PR", "why is this slow") → invoke it directly; pilot in between is a toll booth.
• Everyday implementation → the constitution already routes it through nuke-code; pilot is for multi-stage campaigns.
• Mid-ceremony → the running ceremony owns its pipeline; pilot never steers inside one.