nuke-spec

Nuke Spec

nuke-audit and nuke-spec emit the same executable spec format from opposite inputs: audit compiles problems in existing code into a repair spec; nuke-spec compiles a feature request into a build spec. Both are executed by nuke-exec, and both serve as the intent for nuke-verify. Chain: spec → exec → verify (map: references/family-map.md).

This skill produces the spec and stops — it never implements anything. Its output quality is what lets a cheap implementer succeed: numbered testable requirements, recorded design decisions, and mechanically checkable acceptance criteria stand in for the judgment the implementer does not have.

Arguments

[mode] — light (default) | full | plan (run preflight, print the plan block, STOP — nothing written) <feature> — inline description (nuke-spec add retry with backoff to the fetch layer) or a path to a notes/requirements file [--ask] — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md). Clarifying questions are content, not a cost gate: ambiguity always asks regardless (Mandate 1).

Mode tokens match exactly; anything else in first position is part of the feature description.

Modes

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

	light (default)	full
Recon scout	clerk	session
Requirements distiller	session	session
Designer (loads nuke-think when installed)	session	top
Spec architect	session	top
Completeness reviewer	worker	session
Reviewer loop cap	3	3
Cost stance	lean: one agent per phase	top-tier design and spec; panel-reason the hardest trade-offs

Mandates

1. Clarifying questions are protocol, not weakness. This is the one skill in the family where asking is the job: requirements ambiguous → up to 5 targeted questions BEFORE the plan gate. Never invent a requirement; never ask what recon can answer.
2. Read-only on the codebase. Writes happen only under .nuke/ — the run directory plus the shared .nuke/repo-map.md and .nuke/calibration.log. Never run git add, git commit, or git stash; never edit source or config.
3. Every requirement is testable. A requirement that cannot be verified by observable behavior, a gate, or a quoted line is a wish — rewrite it or move it to non-goals.
4. Main context stays thin. The orchestrator passes paths, not contents; requirements, design, and spec live in the run_dir artifacts.
5. Respect the tier table. Never silently upgrade or downgrade a role's tier.
6. Fresh run directory. Never write into an existing run; if the computed path exists, append -2, -3, … until mkdir succeeds.

Artifacts

run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-spec-<slug>/ (local 24-hour clock).

File	Role
plan.md	Preflight output: feature, clarification answers, scope area, gates, skill map, wave, tiers
requirements.md	Numbered REQ-### requirements, non-goals, constraints + ## Design and ## Decisions
spec.md	The self-contained build spec — nuke-exec executes it; nuke-verify takes it as intent

Pipeline

Phase 0 preflight (clarify → plan → apply → run_dir)
  ─→ Phase 1 requirements ─→ Phase 2 design
  ─→ Phase 3 spec writing (architect ⇄ completeness reviewer, cap 3)
  ─→ Phase 4 handoff (STOP)

Phase 0 — Preflight

Read references/preflight.md and follow its plan-then-apply gate. Spec specifics:

1. Resolve the feature source: inline text, or read the given file (notes, issue export, PRD). Neither resolvable → ask the user and wait.
2. Recon the relevant area. Consume .nuke/repo-map.md when present; otherwise one recon scout maps only what the feature touches: stack and manifests; project instruction files (the conventions the spec must encode); neighboring modules and the existing patterns the feature must follow; the per-path-prefix gates table and file-type → skill map per references/stack-adapters.md.
3. Clarify. Compare the feature description against recon. Genuine ambiguity in scope, behavior, edge cases, or constraints → up to 5 targeted questions, each with concrete options where possible, asked BEFORE the plan gate. Answers are recorded in plan.md; they are requirements input, not suggestions.
4. Plan block: print it (feature one-liner, scope area, mode, wave, tiers, estimate, run_dir) and apply it — gate only with --ask (references/preflight.md). plan → print and STOP. Then create the fresh run_dir and write plan.md into it.

Phase 1 — Requirements (session)

One session-tier agent distills the feature, the clarification answers, and recon into requirements.md:

• Requirements REQ-### — numbered, each stating an observable, testable behavior (REQ-003: a failed fetch retries 3× with exponential backoff starting at 2s). No implementation detail — that is Phase 2's job.
• Non-goals — explicit exclusions, so the implementer and later nuke-verify know where the feature stops.
• Constraints — distilled from project instruction files: conventions, layering rules, gates the change must keep green.

Each REQ-### is phrased so nuke-verify's completeness checker can later map it to evidence (file:line + quote). A requirement the user's answers contradict goes back to the user — never silently resolved.

Phase 2 — Design (session light / top full)

One design agent — it loads nuke-think when installed; this is a judgment role — reads requirements.md plus the recon and appends to requirements.md:

• ## Design — file-by-file plan: files to create or modify, the contracts at each boundary (signatures, data shapes), data flow between them. New code follows the patterns recon found; deviating from them is a decision, recorded.
• ## Decisions — every key decision as one line carrying the strongest rejected alternative: Decision: store retry state in the queue record. Rejected: in-memory map — lost on restart, violates REQ-005.

Hard trade-offs — expensive to reverse, or two plausible designs disagree — get the nuke-think panel protocol, in full mode especially.

Phase 3 — Spec writing (architect ⇄ reviewer)

Read references/fix-spec-template.md first — spec.md follows its conventions with the build-spec deltas:

• Header source: points at requirements.md (<N> requirements, <M> non-goals) instead of a findings ledger; no U-### entries exist; omit the scorecard: line — build specs have none.
• Executor context carries the recon output verbatim: project one-liner, conventions, the per-prefix gates table, tier assignments resolved from references/model-tiers.md, and the file-type → skill map. Embed the REQ-### list verbatim (from requirements.md) so spec.md stands alone as nuke-verify's intent.
• Phase ordering for a build spec: contracts/types/scaffolding → core behavior → integration and wiring → tests → docs. (The template's repair ordering applies to audit specs only.)
• Coverage map: REQ-001 → T-003 · … — every REQ-### maps to ≥1 task.

The architect writes; the completeness reviewer verifies: every REQ-### mapped; no task violates a non-goal; every Accept mechanically checkable (command, named test, or quoted line — template rule 1); batches within a phase touch disjoint files; phases dependency-ordered; gates table and skill map present; every ## Decisions line reflected in the tasks. Reviewer rejects → architect revises → loop, cap 3 cycles. Cap hit → report the open objections honestly; never present a spec the reviewer rejected as if it passed.

Phase 4 — Handoff (STOP)

Report to the user and stop — do NOT start implementing:

• Requirement count, non-goals, clarifications asked and answered
• Spec shape: phases, tasks, batches, decision-log lines
• Artifact paths. Append the run's calibration line to .nuke/calibration.log (format in references/preflight.md)
• The handoff line: "Run the nuke-exec skill on .nuke/<run>/spec.md in a fresh session — or hand spec.md to any AI agent; its Executor context + Execution protocol sections make it self-contained. After implementation, run nuke-verify with intent: .nuke/<run>/spec.md to confirm the build matches the spec."

Orchestration notes

• All orchestrators: the run_dir exists before any agent launches (preflight confirmation creates it); pass that exact path in every prompt. Phases are sequential by design — each consumes the previous phase's artifact; the recon scout inside Phase 0 is the only parallel-friendly role.
• Claude Code: clarifying questions — and the plan gate when --ask engages it — via AskUserQuestion (plan gate options: run / switch mode / narrow scope). Pass model/effort per the tier mapping in references/model-tiers.md.
• Other CLIs: print the questions and the plan block; wait for replies. Without per-agent model overrides, every role inherits the session model — the protocol still holds.
• Amplifiers: the file-type → skill map is recorded in the spec's executor context for implementers to load at execution time; the designer and architect may consult those skills for the area's idioms, but nuke-think is the mandatory load for judgment.