harrymunro/nelson/nelson-2

Nelson

python3 "${CLAUDE_PLUGIN_ROOT}/skills/nelson/scripts/nelson-data.py" status

Execute this workflow for the user's mission.

Write as Nelson's captains would write: concise, elegant, confident. Not eighteenth-century prose — the clear register of an officer who respects the reader's time. The skill's voice sets the example for the admiral's voice.

1. Issue Sailing Orders

• Review the user's brief for ambiguity. If the outcome, scope, or constraints are unclear, ask the user to clarify before drafting sailing orders.
• Write one sentence for outcome, metric, and deadline.
• Set constraints: token budget, reliability floor, compliance rules, and forbidden actions.
• Define what is out of scope.
• Define stop criteria and required handoff artifacts.

You MUST read references/admiralty-templates/sailing-orders.md and use the sailing-orders template when the user does not provide structure.

Example sailing orders summary:

Outcome: Refactor auth module to use JWT tokens
Metric: All 47 auth tests pass, no new dependencies
Deadline: This session
Constraints: Do not modify the public API surface
Out of scope: Migration script for existing sessions

Establish Mission Directory:

• New session: Run nelson-data.py init (see "Structured Data Capture" below). The script owns directory creation: it generates an 8-character hex SESSION_ID, creates .nelson/missions/{YYYY-MM-DD_HHMMSS}_{SESSION_ID}/ with the damage-reports/ and turnover-briefs/ subdirectories, writes sailing-orders.json, mission-log.json, and fleet-status.json, writes .nelson/.active-{SESSION_ID} as the session marker, and prints the mission directory path to stdout. Capture that path as {mission-dir} for the remainder of this mission. The SESSION_ID is the segment after the last underscore in the directory name. If you need a specific SESSION_ID (e.g., testing or resuming a known id), pass --session-id <8-hex>.
• Resumed session: First, attempt auto-recovery by running python3 .claude/skills/nelson/scripts/nelson-data.py recover --missions-dir .nelson/missions. If this finds an active mission with handoff packets, use the structured recovery briefing to resume directly. Otherwise, if you know the SESSION_ID, read .nelson/.active-{SESSION_ID} to recover the mission path. Set that path as {mission-dir}. If you cannot determine your SESSION_ID (e.g., after a full restart), list .nelson/missions/ and present the options to the user for selection. Set the chosen directory as {mission-dir}. Recover state per references/damage-control/session-resumption.md (prefer JSON files, fall back to quarterdeck report prose). Re-establish the standing goal: a /goal is restored automatically on --resume/--continue but not in a fresh session, so if none is active (check with a bare /goal) and sailing-orders.json carries a recorded goal_condition, re-issue it per references/goal-alignment.md.

All mission artifacts — captain's log, quarterdeck reports, damage reports, and turnover briefs — are written inside {mission-dir}.

Structured Data Capture: Run the nelson-data.py script located in the skill's directory (e.g., python3 .claude/skills/nelson/scripts/nelson-data.py init --outcome "..." --metric "..." --deadline "..."). If installed globally, it may be in ~/.claude/skills/nelson/scripts/. init creates the mission directory, the initial JSON files (sailing-orders.json, mission-log.json, fleet-status.json with initial phase SAILING_ORDERS), and the .nelson/.active-{SESSION_ID} marker in one atomic step. See references/structured-data.md for the full argument list.

Phase Advance: After structured data capture, advance the mission phase from SAILING_ORDERS to ESTIMATE:

python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}

Session Hygiene: Execute session hygiene per references/damage-control/session-hygiene.md. Skip this step when resuming an interrupted session.

Standing Goal (optional): For long autonomous, headless (-p), scheduled, or ultracode missions — where standing down too early is the failure mode — offer to set a Claude Code /goal that keeps the session from stopping until the mission is genuinely complete. Compose it from the sailing orders rather than by hand:

python3 .claude/skills/nelson/scripts/nelson-data.py goal-condition \
  --mission-dir {mission-dir} --record

Present the printed /goal ... line for the user to set. If the user already set a /goal before invoking Nelson, do NOT replace it — read it back with a bare /goal, reconcile the sailing orders to it, and only re-issue a composed goal with the user's agreement. Skip this for short interactive missions where the human is steering turn by turn. You MUST read references/goal-alignment.md before setting a goal — the evaluator judges the condition against the conversation transcript only, so completion evidence must be surfaced into chat (this shapes Stand Down in Step 8).

The Estimate opt-in: Before proceeding, ask the user:

"Shall I carry out The Estimate before drafting the Battle Plan? I would recommend it for this mission — [brief reason]."

Give an honest recommendation. For straightforward missions with clear scope in a single subsystem, proceed without the Estimate. For complex, ambiguous, or multi-system missions, recommend conducting it. If the user accepts, proceed to Step 2. If the user declines, record the decision and skip to Step 3:

python3 .claude/skills/nelson/scripts/nelson-data.py skip-estimate \
  --mission-dir {mission-dir} --reason "[one-line rationale]"
python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}
python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}

The first advance moves from SAILING_ORDERS to ESTIMATE. The second advance moves from ESTIMATE to BATTLE_PLAN; the exit validator accepts the transition because skip-estimate has already recorded the opt-out in sailing-orders.json.

2. Conduct The Estimate

Read references/the-estimate.md for the full thought process, and use references/admiralty-templates/estimate.md as the scaffold. Work through seven questions that turn a mission brief into a plan worth executing:

1. Reconnaissance — What is the terrain? What are we working with?
2. Intent — What are we really trying to achieve, and why?
3. Effects — What changes must occur to fulfil the intent?
4. Terrain — Where in the codebase does each effect land?
5. Forces — What agents, models, and context do we need?
6. Coordination — What depends on what? What runs in parallel?
7. Control — Where are the quality gates and intervention points?

Q1 dispatches Explore sub-agents. Send one or more Explore agents into the codebase with a scouting brief derived from the Sailing Orders; synthesise their findings into the Reconnaissance section. Q1 must follow the Explorer discipline rules in references/the-estimate.md (multiple focused dispatches, structured summaries, no raw file contents).

Q2–Q3 and Q4–Q7 are delegated in two separate sub-agent dispatches so Q2–Q7 reasoning does not consume admiral context. The first dispatch (Estimate-Drafter) produces commander's intent and effects after Q1 and before Checkpoint 2; the second dispatch (Estimate-Planner) produces terrain, forces, coordination, and control after Checkpoint 2 approves intent and effects. Both subagents inherit the admiral's model; The Estimate phase is exempt from cost-savings model selection. See references/the-estimate.md for the briefing contents and dispatch templates.

Two checkpoints bracket the analytical work. After Q1, present findings to the user and invite correction or reframing. After Q3, present intent and effects for substantive approval before planning how. Q4-Q7 flow from approved effects and are the admiral's professional judgement — work through them without interrupting the user. Collapse both checkpoints into a single final review only when all three conditions hold: sailing orders specify outcome, metric, and deadline; Q1 reveals no surprises; the work lands in a single subsystem. See references/the-estimate.md for full checkpoint discipline.

Each effect in §3 must carry commander's guidance (how to do it) and acceptance criteria (what must be true when done). Criteria flow through to captains and are verified at stand-down; captains choose the verification method per criterion (test, type-check, lint, review, visual).

Write the estimate to {mission-dir}/estimate.md with one H2 section per question. Split to {mission-dir}/estimate/0N-name.md only when a section grows unwieldy.

Phase Advance: After the user approves the final estimate, advance from ESTIMATE to BATTLE_PLAN:

python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}

3. Draft Battle Plan

When The Estimate has been conducted, the Battle Plan inherits the analytical work: terrain, forces, coordination, and control are already decided. The Battle Plan step is operational — it turns approved effects into task assignments. When the Estimate was skipped, the admiral performs the analysis inline at this step.

Scope preservation: When the Sailing Orders describe extending, expanding, or modifying an existing feature, every task must modify the existing implementation — not create a parallel or replacement implementation. Populate the Modification targets field in each task's brief with the specific functions, env vars, and config identified during Reconnaissance. A task that creates new files, functions, or environment variables where modification of existing ones would satisfy the effect is a planning error.

• Translate each effect from the Estimate (§3) into one or more tasks. Each task must stay within the scope of its parent effect — do not introduce work that the effect does not call for. When the Estimate was skipped, derive tasks directly from the Sailing Orders.
• Prepend the commander's intent paragraph (Estimate §2) to every captain's brief so each ship sails under a shared understanding of purpose.
• Inherit acceptance criteria from the parent effect onto each task. Captains own the choice of verification method per criterion.
• Inherit terrain (file ownership), coordination (dependencies), forces (captain sizing, model class), and control (action-station tier) from the Estimate. When the Estimate was skipped, supply these at this step.
• If cost-savings is a priority, also consider task inputs — avoid multiple agents independently loading the same large inputs into their contexts.
• For each task, note expected crew composition using the crew-or-direct decision tree in references/crew-roles.md. If crew are mustered, list crew roles with sub-tasks and sequence. If the captain implements directly (0 crew), note "Captain implements directly." If the captain anticipates needing marine support, note marine capacity (max 2).
• For each task, consciously mark admiralty-action-required: yes or no.
• Keep one task in progress per agent unless the mission explicitly requires multitasking.

Reference references/admiralty-templates/battle-plan.md for the schema of each captain's brief and references/admiralty-templates/ship-manifest.md for the ship manifest.