nelson

name nelson description Orchestrates multi-agent task execution using a Royal Navy squadron metaphor — from mission planning through parallel work coordination to stand-down. Use when work needs parallel agent orchestration, tight task coordination with quality gates, structured delegation with progress checkpoints, or a documented decision log. argument-hint [mission description] paths [".nelson/**"] 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: Reconnaissance — What is the terrain? What are we working with? Intent — What are we really trying to achieve, and why? Effects — What changes must occur to fulfil the intent? Terrain — Where in the codebase does each effect land? Forces — What agents, models, and context do we need? Coordination — What depends on what? What runs in parallel? 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. Workflow Suitability Check: If the mission has large fan-out, repeatable orchestration, codebase-wide analysis, broad migrations, audits, or cross-checking needs, you MUST read references/workflow-doctrine.md and decide whether workflow or hybrid-workflow is appropriate. For workflow modes, add a compact Workflow Charter to the battle plan with execution primitive, suitability, phases, human gates, verification contract, cost guardrail, and fallback mode. For non-workflow modes, include one line: Workflow suitability: not selected because ... . Station 2/3 workflow work should default to hybrid-workflow because human approval belongs between separate workflow runs, not inside one arbitrary mid-run pause. Battle Plan Gate — Standing Order Check: You MUST NOT finalize task assignments until each question below is answered in writing and any triggered standing order remedy has been applied. Show your reasoning — a bare yes/no is not sufficient. becalmed-fleet.md : Should this mission use single-session instead of multi-agent? If yes, skip Step 4 — single-session has no squadron to form. light-squadron.md : Is the task count equal to the number of independent work units, or have tasks been under-split? split-keel.md : Does each task have exclusive file ownership with no conflicts? (This will be automatically verified in Step 4). unclassified-engagement.md : Does every task have a risk tier? all-hands-on-deck.md : Has each task been crewed only with roles its work actually demands? skeleton-crew.md : Would any task deploy exactly one crew member for an atomic task the captain should handle directly? crew-without-canvas.md : Is every agent justified by actual task scope? captain-at-the-capstan.md : For each task with crew, is the captain's role coordination, not implementation? press-ganged-navigator.md : Is the red-cell navigator being assigned implementation work? admiral-at-the-helm.md : Does the battle plan assign any implementation work (excluding permitted read-only recombination) to the admiral? wrong-ensign.md : Do the planned coordination tools match the selected execution mode? pulling-the-oar.md : For tasks that involve dispatched subagents, is the failure-recovery plan to fix the brief and re-dispatch, rather than absorb the work into senior context? If any answer triggers a standing order, you MUST apply the corrective action and re-answer the question before proceeding. For situations not covered by this gate, consult the Standing Orders table below. Persist the drafted plan. Before proceeding to Step 4, write the complete battle plan to {mission-dir}/battle-plan.md using the template at references/admiralty-templates/battle-plan.md . Include the commander's intent verbatim from Estimate §2, each task brief in template form, and the Standing Order Check answers. This is a safe compaction point — admiral state is now fully on disk. Structured Data Capture: Task registration requires owners, which are assigned in Step 4. No nelson-data.py script calls at this step. 4. Form the Squadron Select execution mode per references/squadron-composition.md . If the user explicitly requested a mode, use it — user preference overrides the decision matrix. single-session : sequential tasks, low complexity, or heavy same-file editing. subagents : parallel, fully independent tasks that report only to the admiral. agent-team : captains benefit from a shared task list, peer messaging, or coordinated deliverables; or 4+ captains are needed. workflow : one autonomous dynamic workflow run for large fan-out, repeatable review, broad migration, audit, or cross-checked research. hybrid-workflow : Nelson-gated sequence of workflow stages with human approval between stages. Mode-Tool Consistency Gate: Before assigning ships, confirm your tool usage matches the selected mode by reviewing references/tool-mapping.md : subagents mode: Captains do NOT use TaskCreate , TaskList , TaskGet , TaskUpdate , or SendMessage(type="message") . Captains report via the Agent tool return value only. The admiral uses TaskCreate / TaskUpdate / TaskList to track progress in the session task list (visibility only — captains cannot see these tasks). agent-team mode: Do NOT use Agent with subagent_type to spawn captains (marines still use subagent_type ). Use TeamCreate first, then Agent with team_name + name . Coordinate via TaskList and SendMessage . single-session mode: The admiral uses TaskCreate , TaskUpdate , TaskList , and TaskGet to track progress as it completes each task sequentially. workflow mode: Treat the workflow as a fleet asset, not ordinary captains. Nelson v1 produces a Workflow Charter/prompt and telemetry plan; it does not directly invoke a workflow API or generate runnable .claude/workflows/*.js . hybrid-workflow mode: Treat each workflow stage as a separate fleet asset. Stop at the planned gate, present results, and launch the next workflow run only after explicit approval. Task List Visibility: After selecting the execution mode, create a TaskCreate entry for each battle plan task to make mission progress visible in the Claude Code task list (Ctrl+T). This applies in all execution modes — it is admiral-level visibility tracking, not inter-agent coordination. In workflow and hybrid-workflow , also create visibility entries for workflow phases or gates when they are the operational units being tracked. For each task: subject : Task name from the battle plan (imperative form, e.g., "Refactor auth module") description : One-line deliverable activeForm : Present-continuous form shown in the UI spinner (e.g., "Refactoring auth module") All tasks start as pending . They will be updated with owners and status as the mission progresses. In single-session mode (where Step 4 is otherwise skipped), the admiral still creates these entries before proceeding to Step 5. Assign each task a captain and a ship name from references/crew-roles.md matching task weight (frigate for general, destroyer for high-risk, patrol vessel for small, flagship for critical-path, submarine for research). Finalize ship manifests: confirm crew roles per task, or note "Captain implements directly." Add 1 red-cell navigator for medium/high threat work. Do not exceed 10 squadron-level agents (admiral, captains, red-cell navigator). Crew are additional. If the sailing orders express cost-savings priority, load references/model-selection.md before assigning models. Apply weight-based model selection to all Agent tool calls and include haiku briefing enhancements for agents assigned to haiku. SQUADRON FORMATION ORDERS Mode: [single-session | subagents | agent-team | workflow | hybrid-workflow] Captain count: [N] Ships: [Ship name] — [vessel type] — [one-line task summary] Crew: [roles, or "Captain implements directly"] [repeat for each ship] [Red-cell navigator — HMS X, if present] For workflow and hybrid-workflow , include: WORKFLOW CHARTER Execution primitive: [workflow | hybrid-workflow] Suitability: [why dynamic workflow orchestration is justified] Phases: [probe / full run / stage names] Human gates: [approval points, especially for hybrid-workflow] Verification contract: [how accepted, rejected, and uncertain findings are handled] Cost guardrail: [Sounding-the-Channel probe, scope cap, token/time stop] Fallback mode: [agent-team | single-session] If any tasks are marked admiralty-action-required: yes , append before awaiting approval: ADMIRALTY ACTION LIST — Actions required from Admiralty 1. [Task name] action: [what you must do] timing: [before task starts | after task completes] unblocks: [task name or stand-down] Actions marked `timing: before task starts` require your sign-off before the relevant captain is spawned. Do not spawn any agents, create any tasks, or launch any workflow / hybrid-workflow run until the user approves. If the user requests changes, revise and redisplay before proceeding. Note: For headless and CI invocation, use nelson-data.py headless --auto-approve which combines Steps 1-3 and skips the interactive approval gate. See references/structured-data.md for details. Structured Data Capture: Once formation is approved, use the composite form command (recommended) or the individual commands below. Recommended — composite form command: Write a plan JSON file with the task and squadron definitions, then run a single command: python3 .claude/skills/nelson/scripts/nelson-data.py form \ --mission-dir {mission-dir} \ --plan {mission-dir}/plan-input.json \ --mode [mode] This registers all tasks, records the squadron, computes DAG metrics, and runs the conflict scan in one step. See references/structured-data.md for the plan JSON schema and output format. Alternative — individual commands: python3 .claude/skills/nelson/scripts/nelson-data.py task --mission-dir {mission-dir} --id N --name "..." --owner "..." ... for each task (owners are now known from formation). See references/structured-data.md for task arguments. python3 .claude/skills/nelson/scripts/nelson-data.py plan-approved --mission-dir {mission-dir} to finalise the battle plan and compute DAG metrics.