# Nuke Exec

> Use when work should be executed by delegated subagents — a spec produced by nuke-audit, nuke-review, nuke-spec, or nuke-verify ("nuke exec", "execute the fix spec", "nuke fix" — its former name), or a clear task stated inline without a spec ("implement this with agents", "build this cheaply" — formerly nuke-implement). Spec in → phased execution; task in → contract first, then a single-phase execution. For the session's own hands, nuke-code applies; for judging finished work, nuke-verify.

- Skill: `b4r7x/nuke-exec` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add b4r7x/nuke-exec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/nuke-exec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: b4r7x (https://skillmd.com/u/b4r7x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b4r7x/nuke-exec

---


# Nuke Exec

The family's one executor (map: references/family-map.md — producers `spec`/`audit`/`review` feed it; `verify` closes behind it). It runs in one of two input modes, resolved at preflight:

- **spec mode** — the argument is a path to a family spec (fix-spec.md from nuke-audit/nuke-review, spec.md from nuke-spec, an escalation spec from nuke-verify, or any file following references/fix-spec-template.md). Executed phase by phase until everything meets the quality bar recorded in the spec's executor context.
- **task mode** — the argument is task text (or a brief file that is not a family spec). Preflight distills it into a contract — 2–5 falsifiable done-criteria plus non-goals — and the contract is executed as a single phase. No spec required; the contract stands in for one.

Core principle — asymmetric verification: weak generation + strong verification + fix loop = strong output. Validators are always one tier above implementers.

## Arguments

`[mode]` — `light` | `full` | `plan`. If omitted: spec mode uses the `mode:` recorded in the spec header, defaulting to `light`; task mode defaults to `light`. `plan` runs preflight, prints the plan block, and STOPS — nothing is written.
`<input>` — a spec path → spec mode; anything else (inline text, a notes/brief file) → task mode. The spec-mode test is countable, never judged: the file has an `## Executor context` heading, at least one `### Batch` heading, and `Accept:` lines — all three, or it is treated as a task brief and the downgrade is named in the plan block, never silent.
`--ask` — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md).

## Modes

Tier vocabulary (`clerk`/`worker`/`session`/`top`) and per-platform mechanics: references/model-tiers.md. Respect the fallback: platforms without per-agent overrides → every role inherits the session model.

| | **light** — cheap-implementer profile (default) | **full** |
|---|---|---|
| Implementers | `worker`; ceilings per references/fix-spec-template.md rule 8 — ≤3 tasks per batch, ≤3 files per task, one concern ≈ one file as the target | `top`; batches as specced |
| Validators | `session` (one tier above implementers) — one fresh validator per phase | `top` (equal tier but fresh, per the ceiling rule in references/model-tiers.md) — a fresh validation wave per phase |
| Skill loading | mandatory — each implementer loads the skills matching its batch's file types from the file-type → skill map; the nuke-lean charter is part of every implementer prompt — delegated code grows guards and wrappers fastest | same |
| Fix-loop cap per phase | 3 cycles | 5 cycles |
| Final sweep | `session`: one reviewer covering correctness + security + structure/quality, plus the completeness checklist in the same pass | `top`: a correctness+security reviewer, a structure+quality reviewer, and a completeness agent — separate fresh agents |
| Cost stance | lean waves; thoroughness comes from stronger validators, the fix loop, and the final sweep | costs do not matter; as many subagents as needed |

Everything else is shared between input modes: the per-phase loop, the progress file, the gates discipline, and the report.

## Mandates

1. **Respect the mode and the tier table.** Never silently upgrade or downgrade a role's tier. Light never spawns a validation wave where one validator suffices; full never shrinks a wave to save tokens.
2. **Main context stays thin.** The orchestrator reads only the spec or contract, the progress file, and agent summaries. All implementation and validation detail lives inside subagents.
3. **Fix everything.** Every task, every severity — including low and info. Skipping anything is failure, not triage.
4. **Implementers never validate their own work.** Validation is always fresh agents, one tier above.
5. **No `git add` / `git commit` / `git stash`. No `.bak` files.** The working tree is left for human review.
6. **Evidence before claims.** No success statement without pasted gate output — verbatim, never summarized — and per-task validated acceptance criteria.
7. **Escalate instead of guessing.** An implementer whose task's `Accept:` (or done-criterion) is not mechanically checkable (grep, test run, or quoted line) stops and returns the task to the orchestrator with the ambiguity named — it never improvises an interpretation.
8. **Escalate instead of stretching (task mode).** More than 5 done-criteria, contradictory requirements, or >~10 files → STOP and recommend nuke-spec (spec → exec). A hard design call → nuke-think before dispatch. Implementers never receive a vague ask — a cheap model amplifies vagueness into invention.
9. **The ledger precedes the wave.** No implementation wave dispatches before the plan block has printed and `exec-plan.md` (or task mode's `plan.md`), `exec-progress.md` with every phase listed as `pending`, and `exec.md` exist on disk. Any of them missing, or exec-progress.md listing fewer phases than the spec → back to Phase 0. None of this waits on the user — materialize, then move, same turn.

## Phase 0 — Preflight

Read references/preflight.md and run its steps. Preflight never asks — the plan prints and the run starts (`--ask` is the only gate, `plan` the only stop) — but it always **materializes before it moves**: the run ledger below is written to disk first, wave 1 dispatches immediately after, in the same turn.

**Spec mode:**

1. Read the spec fully. It is self-contained: executor context (quality bar + tier assignments), per-path-prefix Gates table, file-type → skill map, dependency-ordered phases, batches, tasks, coverage map including `U-###` unverified entries.
2. **Re-measure every task yourself** — files touched and touched-file mass (`wc -l`, run now) against the tier ceilings in references/fix-spec-template.md rule 8. Never trust the spec's own sizing: an architect that wrote oversized tasks did not flag them either. Any task over the executing tier's ceiling → apply the nuke-split protocol inline now (seam rules and all), write `<spec>.split.md` next to the original, execute that instead, and note `split: applied inline (N tasks → M)` in the plan block. Oversized work is never handed to an implementer that cannot hold it — and never bounced back to the user to go run nuke-split by hand.
3. If an `exec-progress.md` (or a legacy `fix-progress.md`) exists next to the spec, resume from the first incomplete phase instead of starting over.

**Task mode:**

1. **Contract** (Mandate 8): distill the task into 2–5 falsifiable done-criteria, non-goals, and constraints from the repo's instruction files — read now, not recalled. A brief file is consumed as-is when its criteria are falsifiable. No resolvable contract → ask the user.
2. **Shape the work**: read the files the task will touch (orchestrator-level skim: exports, structure — not full contents into context); cut the file plan into batches of disjoint files at the worker ceilings of references/fix-spec-template.md rule 8 (≤3 files per task, ≤3 tasks per batch — one concern ≈ one file as the target, the same cut nuke-split makes on specs). The contract + batches form a single-phase plan executed by the shared loop below.

**Both modes — baseline.** Resolve the per-path-prefix gates table and the file-type → skill map (references/stack-adapters.md; spec mode reads them from the spec), run every matching row once, then act by row:

| Baseline result | Action |
|---|---|
| gate passes | record PASS — any later failure in its rows belongs to this run; never written off as "pre-existing" |
| gate runs, code or tests fail | spec mode: adopt as the run's first task. Task mode: record in the plan block; later phases prove no NEW failures — fixing it is offered, never silently absorbed into the contract |
| gate cannot run (missing install, misdeclared command) | unblock protocol in references/preflight.md: fix the tooling first, then take the real baseline |
| an area has no gates | gateless-repo rule in references/stack-adapters.md: bootstrap a minimal gate as the first task, or declare `gates: NONE — validation is review-only`. Never silently validate against nothing |

**The run ledger — materialized in order, then the wave (Mandate 9):**

1. Print the plan block with the full round breakdown — always printed, never asked about (gate only with `--ask`; `plan` → print and stop):

   ```
   ## Nuke Preflight — nuke-exec (spec mode)
   spec: .nuke/2026-07-02-141530-src-engine/fix-spec.md · mode: light
   phases: 3 · batches: 7 · tasks: 19 · re-measured: 0 oversized (wc -l)
   phase 1 (structural): 1.A [T-001..T-003] · 1.B [T-004..T-005]
   phase 2 (extractions): 2.A [T-006..T-010] · 2.B [T-011..T-014] · 2.C [T-015..T-016]
   phase 3 (tests + docs): 3.A [T-017..T-019]
   tiers: implementers worker · validators session · final sweep session
   skill map: .ts → typescript-best-practices · .tsx → react-senior-guide
   baseline: tests PASS · typecheck PASS · lint FAIL (2 errors → adopted as T-000)
   estimate: exec band — ~10–16 agents (7 implementers + per-phase validators + fix cycles)
   ```

   Task mode: the phase lines are replaced by the contract (done-criteria + non-goals) and its batch list.
2. Write the preflight record: spec mode → `exec-plan.md` next to the spec (never `plan.md`, so a spec run's own plan.md survives); task mode → `plan.md` in a fresh `run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-exec-<slug>/`, on collision append `-2`, `-3`, ….
3. Write `exec-progress.md` beside it, prepopulated with EVERY phase, its batches, and its task range — all `pending` (format below; task mode: the contract as one phase with its batches). This is the file resume reads — a run that skipped it cannot be resumed.
4. Write `exec.md` next to that — the evidence record: per-batch results, validator verdicts per cycle, gate outputs verbatim, final verdict. The Report reads from exec.md; exec-progress.md tracks phase state.
5. Dispatch wave 1 — same turn, nothing to wait for.

### Progress format (`exec-progress.md`)

Written at Phase 0 exactly in this shape — every phase listed before any of them runs, all `pending`. Updated after EVERY validation cycle (the Cycles column), not just at phase completion, and reprinted to the user at each phase boundary.

```markdown
# Exec Progress
input: fix-spec.md (spec mode) | mode: light | started: 2026-07-02
baseline: tests PASS · typecheck PASS · lint FAIL (2 errors — adopted as task T-000)

| Phase | Batches | Tasks | Status | Cycles | Notes |
|---|---|---|---|---|---|
| 1 — structural | 1.A, 1.B | T-001..T-005 | pending | — | |
| 2 — extractions | 2.A, 2.B, 2.C | T-006..T-016 | pending | — | |
| 3 — tests + docs | 3.A | T-017..T-019 | pending | — | |
```

## Per-phase loop

For each phase in spec order (task mode: the contract is one phase):

1. **Implementation wave** — one subagent per batch, all batches of the phase in parallel (they touch disjoint files by construction). Each implementer receives:
   - the spec's Executor context block + only its own tasks, copied **verbatim** — task text, file lists, and `Accept:` lines exactly as the spec wrote them, never paraphrased by the orchestrator; paraphrase is where constraints die (task mode: the contract verbatim + its batch)
   - write ownership of only its batch's files
   - the mandatory skill list for its file types from the file-type → skill map, plus the nuke-lean charter — load before writing
   - return format: per task → status, files changed with line refs, deviations from the spec or contract; a non-checkable `Accept:` → escalate per Mandate 7
2. **Validation** — fresh subagents one tier above the implementers, never the implementers (light: one `session` validator for the whole phase; full: a `top` wave). Validators receive the spec or contract, the diff, and repo access — never the implementers' reasoning; the missing anchoring is the design:
   - per task: acceptance criteria (task mode: done-criteria, `met | partial | unmet`) verified mechanically with file:line evidence and a quoted line each
   - re-audit of every changed file against the quality bar — hunting issues the changes *introduced* (new duplication, new slop, broken callers of changed contracts, regressions, convention drift) via the four charter bundles of references/lens-catalog.md over the diff and its blast radius. Findings use the family schema (lens + severity + justification, file:line, quoted source, numbered trace, proposed fix, refutation attempt); a finding missing a field is invalid and must not be reported
   - **re-judge every `U-###` entry** the coverage map routes to this phase (spec mode): real → add to the fix loop as a task; not real → close with a written reason in `exec-progress.md`
   - run the Gates-table rows matching the phase's changed path prefixes, full output captured
3. **Fix loop** — any failed criterion, failed gate, escalated task, or new finding of **any** severity → dispatch fix subagents with the exact findings → re-run validation; bump the phase's Cycles column in `exec-progress.md` every cycle. Repeat until clean. Cap per phase (light: 3 cycles, full: 5) — if hit, stop, record honest status in `exec-progress.md`, and report the remaining issues. Never proceed past a dirty phase.
4. Mark the phase `done` in `exec-progress.md` only when validation is fully clean, and reprint the progress table to the user before dispatching the next phase.

## Final verification

After the last phase:

1. Every Gates-table row — capture outputs verbatim.
2. Final sweep over the complete changed-file set, per the mode table above.
   - Completeness checklist: every T-### / done-criterion done, every coverage-map ID (F-###/REQ-###) resolved, every U-### fixed or closed-with-reason, no `.bak` files, no debug leftovers, no commented-out code.
3. Anything found → one more fix loop, then re-sweep.

## Report

- Input mode, the final `exec-progress.md` table verbatim, issue counts fixed per phase, U-### dispositions (spec mode)
- Gate outputs (verbatim — no summaries in place of evidence)
- Append the run's calibration line to `.nuke/calibration.log` (format in references/preflight.md)
- Verdict: **"CLEAN — every task validated, all gates pass, working tree ready for review (nothing committed)"** — or the honest list of remaining blockers and exactly where the run stopped
- Task mode: recommend **nuke-verify** with the contract as intent when the user wants an independent second pass on the delegated build.

## Orchestration notes

- **Claude Code:** Workflow tool (phases map to `phase()`, batches to `parallel()`, the fix loop to a while-loop) or parallel Agent calls with `run_in_background`. Pass `model`/`effort` per agent from the tier table in references/model-tiers.md. With `--ask`: the gate via AskUserQuestion, options run / switch mode / narrow scope.
- **Codex / OpenCode / Cursor / other CLIs:** spawn subagents per batch, mapping tiers to their model flags. Sequential fallback: one batch at a time, each in a FRESH context, same validation protocol.
- If the environment offers isolated worktrees and two batches unexpectedly conflict, isolate them; otherwise serialize the conflicting batches — never let two agents write the same file concurrently.