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).

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.

**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.

**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.

**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.

**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.

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] 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]

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 or create any tasks 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:**
1. `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.
2. `python3 .claude/skills/nelson/scripts/nelson-data.py plan-approved --mission-dir {mission-dir}` to finalise the battle plan and compute DAG metrics.
3. `python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}` to advance from BATTLE_PLAN to FORMATION (validates all tasks have station tiers).
4. `python3 .claude/skills/nelson/scripts/nelson-data.py squadron --mission-dir {mission-dir} --admiral "..." --admiral-model [model] --captain "name:class:model:task_id" ... --mode [mode]` to record squadron composition. Repeat `--captain` for each captain. See `references/structured-data.md` for the full argument list.
5. `python3 .claude/skills/nelson/scripts/nelson_conflict_scan.py --plan {mission-dir}/battle-plan.json` to verify there are no file ownership conflicts. If conflicts are found, you MUST resolve them and update the battle plan before proceeding.
6. `python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}` to advance from FORMATION to PERMISSION.

**Before proceeding to Step 5:** Verify that sailing orders exist, all tasks have owners and deliverables, and every task has an action station tier.

**Crew Briefing:** Spawning and task assignment are two steps. First, spawn each captain with the `Agent` tool, including a crew briefing from `references/admiralty-templates/crew-briefing.md` in their prompt. Then assign work to the existing task entries with `TaskUpdate`. Teammates do NOT inherit the lead's conversation context — they start with a clean slate and need explicit mission context. See `references/tool-mapping.md` for full parameter details by mode.

**Task Status Updates:** After formation, update the task list entries created earlier in this step:
- **`agent-team` mode:** Use `TaskUpdate` to set `owner` to each captain's name and `status` to `in_progress` as captains are spawned. The team's shared task list now serves both visibility and coordination.
- **`subagents` mode:** Use `TaskUpdate` to set `status` to `in_progress` as each captain is dispatched. The admiral tracks these directly.
- **`single-session` mode:** Use `TaskUpdate` to set `status` to `in_progress` as the admiral begins each task.

**Edit permissions:** When spawning any agent whose task involves editing files, set `mode: "acceptEdits"` on the `Agent` tool call. Omitting this can cause a permission race condition that silently stalls the agent at its first edit. When in doubt, include it.

**Turnover Briefs:** When a ship is relieved due to context exhaustion, it writes a typed handoff packet using `python3 .claude/skills/nelson/scripts/nelson-data.py handoff ...` (see `references/structured-data.md`). An optional prose companion brief may also be written using `references/admiralty-templates/turnover-brief.md`. See `references/damage-control/relief-on-station.md` for the full procedure.

## 5. Get Permission to Sail

**Display and Permission Gate:**
1. Display the complete battle plan to the user if `becalmed-fleet.md` is in effect.
2. Display the complete squadron formation to the user if `becalmed-fleet.md` is not in effect. The battle plan (drafted in Step 3) should also be available for review.
3. You are REQUIRED to wait for explicit permission to proceed.

**Phase Advance:** After the user grants permission, log the event and advance:

python3 .claude/skills/nelson/scripts/nelson-data.py event \ --mission-dir {mission-dir} --type permission_granted --checkpoint 0 python3 .claude/skills/nelson/scripts/nelson-phase.py advance --mission-dir {mission-dir}

This transitions the mission from PERMISSION to UNDERWAY, unlocking agent spawning and task creation.

## 6. Run Quarterdeck Rhythm

**Idle notification rule (immediate — do not defer to checkpoint):** Every time an idle notification arrives from a ship, ask three questions before doing anything else:
1. Is this ship's task marked complete?
2. Does any remaining pending task depend on this ship's output?
3. **Agent-team mode only:** Has the admiral received and processed this ship's results?

If the task is complete and no pending task depends on it, proceed to shutdown per `references/standing-orders/paid-off.md`. In agent-team mode, the admiral must confirm receipt of the captain's results before sending `shutdown_request` — retrieve them via `SendMessage` or by reading output files if not already received. In subagents mode, results are returned synchronously by the `Agent` tool, so no additional confirmation is needed. Do not wait for the next checkpoint cadence. Check the current `TaskList` state at the moment the idle notification arrives; each notification is evaluated independently against current state. This applies even when other ships are still running.

**Shutdown attempt ceiling:** If a `shutdown_request` to a ship goes unacknowledged, do not loop indefinitely. After 3 failed attempts to the same agent, abandon the shutdown attempt, note the failure in the captain's log, and continue the mission. If `TeamDelete` is blocked by stuck agents, manual cleanup is available — see `references/damage-control/man-overboard.md` for the procedure.

- Keep admiral focused on coordination and unblock actions.
- The admiral sets the mood of the squadron. Acknowledge progress, recognise strong work, and maintain cheerfulness under pressure.
- **Checkpoint Cadence Gate:** You MUST NOT process a third task completion without writing a quarterdeck checkpoint. Before dispatching new work or processing the next completion, confirm the last checkpoint is no more than 2 completions old. The quarterdeck report is your only recovery point if context compaction occurs — stale reports mean lost coordination state.
- Run a quarterdeck checkpoint after every 1-2 task completions, when a captain reports a blocker, or when a captain goes idle with unverified outputs:
    - Update progress by checking `TaskList` for task states: `pending`, `in_progress`, `completed`.
    - Mark completed tasks with `TaskUpdate` setting `status` to `completed`. In `subagents` and `single-session` modes, the admiral updates the session task list directly; in `agent-team` mode, captains or the admiral update the shared task list.
    - Identify blockers and choose a concrete next action.
    - Use `SendMessage` to unblock captains or redirect their approach.
    - Confirm each crew member has active sub-tasks; flag idle crew or role mismatches.
    - Check for active marine deployments; verify marines have returned and outputs are incorporated.
    - Safety net: if any idle ship with a complete task was missed between checkpoints, apply the `references/standing-orders/paid-off.md` shutdown procedure now before continuing.
    - Track burn against token/time budget.
    - Check hull integrity: collect damage reports from all ships, update the squadron readiness board, and take action per `references/damage-control/hull-integrity.md`. The admiral must also check its own hull integrity at each checkpoint. **Every ship must file a damage report at every checkpoint** to `{mission-dir}/damage-reports/{ship-name}.json` using the schema in `references/admiralty-templates/damage-report.md` — do not skip this when hull is Green.
    - Standing order scan: For each order below, ask "Has this situation arisen since the last checkpoint?" If yes, apply the corrective action now — do not defer.
        - `admiral-at-the-helm.md`: Has the admiral drifted into implementation work (excluding permitted read-only recombination)?
        - `drifting-anchorage.md`: Has any task scope crept beyond the sailing orders? Has any captain created a parallel implementation, duplicate function, or new environment variable instead of extending existing code?
        - `captain-at-the-capstan.md`: Has any captain started implementing instead of coordinating crew?
        - `pressed-crew.md`: Has any crew member been assigned work outside their role?
        - `press-ganged-navigator.md`: Has the red-cell navigator been assigned implementation work?
        - `all-hands-on-deck.md`: Has any ship mustered crew roles that are idle or unjustified?
        - `battalion-ashore.md`: Has any captain deployed marines for crew work or sustained tasks?
        - `wrong-ensign.md`: Is the admiral or any captain using tools from the wrong execution mode?
        - `pulling-the-oar.md`: Has any senior agent (admiral or captain) absorbed work from a failed subagent dispatch instead of fixing the brief and re-dispatching?
    - **Write the quarterdeck report to disk** at `{mission-dir}/quarterdeck-report.md` at every checkpoint using `references/admiralty-templates/quarterdeck-report.md`. Do not skip this when hull is Green — compaction can occur at any time and the on-disk report is the only recovery point. Before writing, if `quarterdeck-report.md` already exists in `{mission-dir}`, find all files matching glob pattern `quarterdeck-report-[0-9]*.md`, determine N as one greater than the highest N found (0 if none exist), rename the existing file to `quarterdeck-report-N.md`, then write the new report. This keeps the latest report at the canonical path while preserving history.
    - **Structured data capture:** Run `python3 .claude/skills/nelson/scripts/nelson-data.py checkpoint --mission-dir {mission-dir} --pending N --in-progress N --completed N ...` with current progress, budget, hull, and decision data. Between checkpoints, run `python3 .claude/skills/nelson/scripts/nelson-data.py event --mission-dir {mission-dir} --type <event_type> ...` for state changes (task completions, blockers, hull threshold crossings, standing order violations). See `references/structured-data.md` for event types and arguments.
    - Check `TaskList` for any tasks with description prefixed `[AWAITING-ADMIRALTY]:`. If any exist, surface the ask to Admiralty immediately — do not batch to the next checkpoint.
    - Cross-reference the battle plan against `TaskList`: for any task marked `admiralty-action-required: yes` in the battle plan that shows status `completed`, confirm there is a quarterdeck log entry recording admiralty sign-off. If no such entry exists, flag to Admiralty for manual verification — the task may have completed without the intended human step.
- Re-scope early when a task drifts from mission metric.
- When a mission encounters difficulties, consult the Damage Control table below for recovery and escalation procedures.

Example quarterdeck checkpoint:

Status: 3/5 tasks complete, 1 blocked, 1 in progress Blocker: HMS Resolute waiting on API schema from HMS Swift Action: Redirect HMS Swift to prioritise schema export Budget: ~40% tokens consumed, on track Hull: All ships green

Reference `references/tool-mapping.md` for coordination tools, `references/admiralty-templates/quarterdeck-report.md` for the report template, and `references/admiralty-templates/damage-report.md` for damage report format. Use `references/commendations.md` for recognition signals and graduated correction. Consult the Standing Orders table below if admiral is doing implementation or tasks are drifting from scope.

## 7. Set Action Stations

- You MUST read and apply station tiers from `references/action-stations.md`.
- Require verification evidence before marking tasks complete:
    - Test or validation output.
    - Failure modes and rollback notes.
    - Red-cell review for medium+ station tiers.
- Trigger quality checks on:
    - Task completion.
    - Agent idle with unverified outputs.
    - Before final synthesis.
- For crewed tasks, verify crew outputs align with role boundaries (consult `references/crew-roles.md` and the Standing Orders table below if role violations are detected).
- Marine deployments follow station-tier rules in `references/royal-marines.md`. Station 2+ marine deployments require admiral approval. Captains use `references/admiralty-templates/marine-deployment-brief.md` when deploying a marine.

Reference `references/admiralty-templates/red-cell-review.md` for the red-cell review template. Consult the Standing Orders table below if tasks lack a tier or red-cell is assigned implementation work.

## 8. Stand Down And Log Action

- Stop or archive all agent sessions, including crew.
- Write the captain's log to `{mission-dir}/captains-log.md`. The log MUST be written to disk — outputting it to chat only does not satisfy this requirement. The captain's log should contain:
    - Decisions and rationale.
    - Diffs or artifacts.
    - Validation evidence.
    - Open risks and follow-ups.
    - Mentioned in Despatches: name agents and contributions that were exemplary.
    - Record reusable patterns and failure modes for future missions.

Reference `references/admiralty-templates/captains-log.md` for the captain's log template and `references/commendations.md` for Mentioned in Despatches criteria.

**Structured Data Capture:** Before writing the captain's log, run `python3 .claude/skills/nelson/scripts/nelson-data.py stand-down --mission-dir {mission-dir} --outcome-achieved --actual-outcome "..." --metric-result "..."` to capture the structured mission summary. See `references/structured-data.md` for the full argument list.

**Task List Cleanup:** Verify all task list entries reflect final state. Mark any remaining `in_progress` tasks as `completed` if their work is done, or note incomplete tasks in the captain's log. This ensures the Claude Code task list shows an accurate final summary.

**Session State Cleanup:** Remove the session state file by deleting `.nelson/.active-{SESSION_ID}`.

**Mission Complete Gate:** You MUST NOT declare the mission complete until `{mission-dir}/captains-log.md` exists on disk and has been confirmed readable. If context pressure is high, write a minimal log noting which sections were abbreviated — but the file must exist. Skipping Step 8 is never permitted.

**GitHub Star Prompt (one-time, success only):** After the Mission Complete Gate passes, ask the user once whether they would like to star the Nelson repo (canonical slug `harrymunro/nelson`). Run all three preflight checks below; if any prints `SKIP`, skip the prompt silently and finish Stand Down.

gh auth status &>/dev/null && echo "GH_OK" || echo "SKIP_NO_GH" python3 - <<'PY' import json, os path = os.path.expanduser('~/.nelson/prefs.json') prefs = {} if os.path.exists(path): try: with open(path, encoding='utf-8') as f: loaded = json.load(f) if isinstance(loaded, dict): prefs = loaded except Exception: prefs = {} print("SKIP_ALREADY_ASKED" if prefs.get('star_asked') is True else "PREFS_OK") PY python3 - <<'PY' import json, os, sys mission_dir = os.environ.get('MISSION_DIR', '{mission-dir}') sd_path = os.path.join(mission_dir, 'stand-down.json') try: with open(sd_path, encoding='utf-8') as f: sd = json.load(f) print("OUTCOME_OK" if sd.get('outcome_achieved') is True else "SKIP_OUTCOME_NOT_ACHIEVED") except Exception: print("SKIP_NO_STAND_DOWN") PY

Substitute `{mission-dir}` with the actual mission directory path (or export `MISSION_DIR` first). If all three lines are `GH_OK`, `PREFS_OK`, `OUTCOME_OK`, invoke `AskUserQuestion` with:

- **Question:** "Nelson helped finish that mission. Would you star the repo on GitHub?"
- **Star Nelson** — "Helps the project grow."
- **Maybe later** — "Skip for now (won't ask again)."

On **Star Nelson**, run `gh api -X PUT /user/starred/harrymunro/nelson` (idempotent — returns 204 whether or not the repo is already starred). If the call fails, print `Couldn't reach GitHub — try 'gh api -X PUT /user/starred/harrymunro/nelson' manually.` and continue. Never let this step block Stand Down.

On any answer (including a custom "Other" response), set `star_asked: true` in `~/.nelson/prefs.json`, preserving any existing keys:

python3 - <<'PY' import json, os path = os.path.expanduser('~/.nelson/prefs.json') os.makedirs(os.path.dirname(path), exist_ok=True) try: with open(path, encoding='utf-8') as f: prefs = json.load(f) if not isinstance(prefs, dict): prefs = {} except Exception: prefs = {} prefs['star_asked'] = True with open(path, 'w', encoding='utf-8') as f: json.dump(prefs, f, indent=2) f.write('\n') PY

This is a single ask per user across all Nelson projects. Either answer locks the prompt forever.

## Standing Orders

Consult the specific standing order that matches the situation. The library is empirically extensible: see `scripts/nelson_data_patterns.py` for the promotion workflow that mines new candidate orders from mission patterns and surfaces them for human review.

| Situation | Standing Order |
|---|---|
| Choosing between single-session and multi-agent | `references/standing-orders/becalmed-fleet.md` |
| Tasks under-split onto fewer captains than independence warrants | `references/standing-orders/light-squadron.md` |
| Deciding whether to add another agent | `references/standing-orders/crew-without-canvas.md` |
| Assigning files to agents in the battle plan | `references/standing-orders/split-keel.md` |
| Task scope drifting from sailing orders | `references/standing-orders/drifting-anchorage.md` |
| Admiral doing implementation instead of coordinating (excluding permitted read-only recombination) | `references/standing-orders/admiral-at-the-helm.md` |
| Assigning work to the red-cell navigator | `references/standing-orders/press-ganged-navigator.md` |
| Tasks proceeding without a risk tier classification | `references/standing-orders/unclassified-engagement.md` |
| Captain implementing instead of coordinating crew | `references/standing-orders/captain-at-the-capstan.md` |
| Crewing every role regardless of task needs | `references/standing-orders/all-hands-on-deck.md` |
| Spawning one crew member for an atomic task | `references/standing-orders/skeleton-crew.md` |
| Assigning crew work outside their role | `references/standing-orders/pressed-crew.md` |
| Captain deploying marines for crew work or sustained tasks | `references/standing-orders/battalion-ashore.md` |
| Captain completed autonomous work and needs human action to continue | `references/standing-orders/awaiting-admiralty.md` |
| Agent completed task with no remaining work in the dependency graph | `references/standing-orders/paid-off.md` |
| Using tools from the wrong execution mode | `references/standing-orders/wrong-ensign.md` |
| Senior absorbing failed subagent's work instead of fixing the brief | `references/standing-orders/pulling-the-oar.md` |

## Damage Control

Consult the specific procedure that matches the situation.

| Situation | Procedure |
|---|---|
| Agent unresponsive, looping, or producing no useful output | `references/damage-control/man-overboard.md` |
| Session interrupted (context limit, crash, timeout) | `references/damage-control/session-resumption.md` |
| Completed task found faulty, other tasks are sound | `references/damage-control/partial-rollback.md` |
| Mission cannot succeed, continuing wastes budget | `references/damage-control/scuttle-and-reform.md` |
| Issue exceeds current authority or needs clarification | `references/damage-control/escalation.md` |
| Ship's crew consuming disproportionate tokens or time | `references/damage-control/crew-overrun.md` |
| Ship's context window depleted, needs replacement | `references/damage-control/relief-on-station.md` |
| Ship context window approaching limits | `references/damage-control/hull-integrity.md` |
| Automated budget, hull, and idle alarms crossing thresholds | `references/damage-control/circuit-breakers.md` |
| Preparing the mission directory at session start | `references/damage-control/session-hygiene.md` |
| Agent team communication failure (lost agent IDs, message bus down) | `references/damage-control/comms-failure.md` |

## Admiralty Doctrine

- Include this instruction in any admiral's compaction summary: Re-read the quarterdeck report at the mission directory path to recover `{mission-dir}`. If the path is unknown, read `.nelson/.active-{SESSION_ID}` if you know the SESSION_ID, otherwise list `.nelson/missions/` and present the options to the user for selection. Then re-read `references/standing-orders/admiral-at-the-helm.md` to confirm you are in coordination role.
- Treat `/compact` as safe at any phase boundary (after Step 1, 2, 3, 4, and at every quarterdeck checkpoint in Step 6). The narrow unsafe window is inside Step 5 — between user approval and the admiral's `permission_granted` / phase advance / agent spawn turn.
- Optimize for mission throughput, not equal work distribution.
- Prefer replacing stalled agents over waiting on undefined blockers.
- Recognise strong performance; motivation compounds across missions.
- Keep coordination messages targeted and concise.
- Escalate uncertainty early with options and one recommendation.

Action Stations

Classify each task before execution. Apply the minimum required controls.

Contents

• Station 0: Patrol
• Station 1: Caution
• Station 2: Action
• Station 3: Trafalgar
• Risk Classification Decision Tree
• Failure-Mode Checklist
• Marine Deployments

Station 0: Patrol

Criteria:

• Low blast radius.
• Easy rollback.
• No sensitive data, security, or compliance impact.

Required controls:

• Basic validation evidence.
• Record rollback step.

Station 1: Caution

Criteria:

• User-visible behavior changes.
• Moderate reliability or cost impact.
• Partial coupling to other tasks.

Required controls:

• Independent review by non-author agent.
• Validation evidence plus negative test or failure case.
• Explicit rollback note in task output.

Station 2: Action

Criteria:

• Security, privacy, compliance, or data integrity implications.
• High customer or financial blast radius.
• Difficult rollback or uncertain side effects.

Required controls:

• Dedicated red-cell navigator participation.
• Adversarial review with failure-mode checklist.
• Pre-merge or pre-release go/no-go checkpoint by admiral.
• Staged rollout or guarded launch when possible.

Station 3: Trafalgar

Criteria:

• Irreversible actions.
• Regulated or safety-sensitive effects.
• Mission failure likely causes severe incident.

Required controls:

• Keep scope minimal and isolate risky changes.
• Require explicit human confirmation before irreversible action.
• Two-step verification and documented contingency plan.
• If controls are unavailable, do not execute.

Risk Classification Decision Tree

Walk through these questions in order. Stop at the first "yes" — that determines the Station tier.

1. Is the action irreversible or regulated?

• Could it destroy data with no backup? → Station 3
• Does it touch regulated, safety-critical, or compliance-governed systems? → Station 3
• Could failure cause a severe incident that cannot be undone? → Station 3
• If none apply, proceed to question 2.

_Examples: Dropping a production database table (Station 3), deleting a cloud storage bucket without snapshots (Station 3), modifying HIPAA-regulated data pipelines (Station 3)._

2. Does it affect security, privacy, or data integrity?

• Does it modify authentication, authorization, or encryption? → Station 2
• Could it expose user data or PII? → Station 2
• Does it have high financial or customer blast radius? → Station 2
• If none apply, proceed to question 3.

_Examples: Changing auth middleware or token validation (Station 2), updating payment processing logic (Station 2), modifying API rate-limiting or access controls (Station 2)._

3. Is the change visible to users or coupled to other work?

• Does it alter user-facing behavior, UI, or API responses? → Station 1
• Could it affect reliability, performance, or cost in a noticeable way? → Station 1
• Is it tightly coupled to other in-flight tasks? → Station 1
• If none apply, proceed to question 4.

_Examples: Changing an API response format (Station 1), updating a shared configuration file (Station 1), refactoring a function used by multiple modules (Station 1)._

4. None of the above? → Station 0

• Low blast radius, easy rollback, no sensitive impact.

_Examples: Renaming an internal variable (Station 0), fixing a typo in a code comment (Station 0), adding a unit test for existing logic (Station 0)._

Failure-Mode Checklist

Run this checklist for Station 1+ tasks.

• What could fail in production?
• How would we detect it quickly?
• What is the fastest safe rollback?
• What dependency could invalidate this plan?
• What assumption is least certain?

Marine Deployments

Marine deployments inherit the parent ship's station tier:

• Station 0-1: Captain deploys at discretion. No admiral approval required.
• Station 2: Captain must signal admiral and receive approval before deploying marines.
• Station 3: Marine deployment is not permitted. All Trafalgar-tier work requires explicit Admiralty (human) confirmation.

Plan Mode for High-Risk Stations

When spawning captains for Station 2 or Station 3 tasks, use mode: "plan" on the Agent tool. This forces the captain into read-only plan mode — they can explore the codebase and design their approach, but cannot write files until the admiral approves their plan.

• Station 2 (Action): Captain submits a plan via ExitPlanMode. Admiral reviews and approves via SendMessage(type="plan_approval_response"). This maps to the existing "admiral go/no-go" requirement.
• Station 3 (Trafalgar): Same flow, but the admiral must also obtain explicit human confirmation before approving the plan. This maps to the existing "human confirmation required" requirement.
• Station 0-1: Plan mode is not required. Captains execute directly.

See references/tool-mapping.md for the full set of coordination tools.

Advanced: TaskCompleted Hook

An optional TaskCompleted hook can enforce quality gate validation before allowing a task to be marked complete. A hook that exits with code 2 rejects the completion and feeds back the reason to the agent.

Nelson ships a TaskCompleted hook in hooks/hooks.json that enforces these quality gates automatically. The hook checks validation evidence, rollback notes, failure cases, and red-cell review based on the task's station tier. It exits with code 2 to reject incomplete tasks with specific feedback.

This supplements the admiral's quarterdeck checkpoint and red-cell review process with deterministic enforcement.

Battle Plan Template

The rendered plan lives at {mission-dir}/battle-plan.md and is the prose authority for the mission — commander's intent and per-task briefs. The structured form at {mission-dir}/battle-plan.json is the execution-data authority (owners, dependencies, station tiers, file ownership). Keep them aligned: edit one, mirror the change in the other.

Every captain's brief opens with the commander's intent from the Estimate (§2) — one paragraph, verbatim. This is how each ship sails under a shared understanding of purpose.

Commander's intent:
[One paragraph from the Estimate §2 — prepended to every captain's brief.]

Task ID:
- Name:
- Owner: [assigned at Step 4 — Form the Squadron]
- Ship (if crewed): [assigned at Step 4 — Form the Squadron]
- Crew manifest (if crewed):
- Deliverable:
- Dependencies:
- Station tier (0-3):
- File ownership (if code):
- Modification targets (if extending): [specific functions, env vars, config to modify — not replace. Omit for greenfield tasks.]
- Acceptance criteria (inherited from effect):
  - [Criterion 1 — captain chooses verification method: test | type-check | lint | review | visual]
  - [Criterion 2 — ...]
- Validation required:
- Rollback note required: yes/no
- admiralty-action-required: yes/no
  - action: [one sentence — what the human must do]
  - timing: before this task starts | after this task completes
  - blocks: [task name or "stand-down"]

Modification targets. When a task extends existing code, the Modification targets field anchors the captain to specific functions, variables, and configuration that must be modified in place. This field flows from the Estimate's Reconnaissance (Q1) and Terrain (Q4) — if those questions identified the existing code, the Battle Plan must preserve that specificity. Omit the field for greenfield tasks where no existing code is being extended.

Acceptance criteria inheritance. Each task inherits the acceptance criteria of its parent effect from the Estimate (§3). Captains own the choice of verification method per criterion (test, type-check, lint, review, or visual). The quarterdeck records each outcome (pass / fail / not-verified) via nelson-data.py estimate-outcome.

JSON schema note: the battle-plan task object accepts an optional acceptance_criteria: list[str] field carrying the inherited criteria. This enables programmatic aggregation of verification outcomes. The task object also accepts an optional modification_targets: list[str] field for tracking the functions, environment variables, or configuration that must be modified in place.

`admiralty-action-required`: Mark yes for any task where a step cannot be completed by an agent — requires the human to interact with an external system, provide credentials or URLs, or take an action only the human can perform. Fill this field consciously for every task; leaving it blank is a claim that the task requires no human action. When marked yes, the admiral will surface this in the Admiralty Action List before agents launch, and the captain will invoke the awaiting-admiralty standing order when the step is reached.

Note on `blocks:` field: The blocks: value names the task that cannot proceed until the human acts. The Admiralty Action List displays this as unblocks: — same task name, inverted label.

Captain's Log Template

Mission summary:
- planned outcome:
- achieved outcome:
- success metric result:

Delivered artifacts:
- artifact:
- location:

Key decisions:
- decision:
- rationale:

Validation evidence:
- evidence:

Open risks:
- risk:
- owner:
- mitigation/next step:

Follow-ups:
- item:
- owner:
- due date:

Mentioned in Despatches:
- agent:
- contribution:

Reusable patterns:
- adopt:
- avoid:

Crew Briefing Template

When spawning each captain, use the Agent tool (see references/tool-mapping.md for parameters by mode). Include this briefing in their prompt. Teammates do not inherit the lead's conversation context — they start with a clean slate and need explicit mission context to operate independently.

Target size: ~500 tokens. Enough for the teammate to work without asking clarifying questions, but not so much that it wastes their context window.

== CREW BRIEFING ==
[Admiral — if this captain is assigned haiku: before sending, read
 references/model-selection.md and insert the three haiku briefing
 enhancement blocks here, then apply haiku tasking discipline to the
 task description below]
Mission: [mission name from sailing orders]
Your Role: Captain [N] — [role description]
Ship: [ship name from battle plan]
Your Task: [specific task from battle plan]
Deliverable: [what you must produce]
Action Station: [0-3] — [Patrol / Caution / Action / Trafalgar]
File Ownership: [files you own — no other agent should edit these]
Dependencies: [tasks that must complete before yours / tasks waiting on yours]
Mission Directory: [{mission-dir} absolute path — use for damage reports and turnover briefs]
Marine Capacity: [0-2, from ship manifest — omit line if 0]
Standing Orders:
- Do NOT implement work outside your assigned task scope
- Do NOT edit files not assigned to you
- If any part of your task is ambiguous, signal the admiral before implementing
- When your task extends existing code, modify the existing implementation in place.
  Do NOT create replacement functions, parallel implementations, or new environment
  variables that duplicate existing ones. If you believe a rewrite is necessary,
  signal the admiral with your rationale before proceeding.
- Report blockers to admiral immediately with options and one recommendation
- Execution mode: [subagents | agent-team] — your available coordination tools are listed in references/tool-mapping.md
- When done, report: deliverable, validation evidence, failure modes, rollback note
- File a damage report to {mission-dir}/damage-reports/{ship-name}.json when your task
  is complete or when hull integrity crosses a threshold (Green → Amber → Red → Critical).
  Use the JSON template from references/admiralty-templates/damage-report.md (fields: ship_name,
  timestamp, hull_integrity_pct, hull_integrity_status, relief_requested, context_summary).
  Estimate hull_integrity_pct from your token usage.
- You may deploy Royal Marines (short-lived sub-agents) for focused sorties.
  Deploy by calling the `Agent` tool with `subagent_type` (see `references/tool-mapping.md`).
  Recce Marine: `Agent` tool with `subagent_type=`"Explore" (read-only recon).
  Assault Marine / Sapper: `Agent` tool with `subagent_type=`"general-purpose".
  Include a deployment brief in the `Agent` prompt (template below).
  Station 2+ marine deployments require admiral approval first.
  Max 2 marines at a time. Marines cannot deploy marines.
- Marines are under your command: deploy at your discretion for Station 0-1 sorties.
  Station 2+: signal admiral and await approval before deploying. Do NOT use marines
  as a substitute for crew on sustained work.
- To muster or pay off crew mid-task, request admiral approval with a brief rationale
  before acting.
- If you reach a step requiring human action (admiralty-action-required: yes), invoke
  the awaiting-admiralty standing order: references/standing-orders/awaiting-admiralty.md
- Shutdown protocol: if you receive `{"type": "shutdown_request"}`, respond immediately
  with `{"type": "shutdown_response"}` and cease all activity. Do NOT respond with an
  idle notification or any other message type.
Marine Deployment Brief: use the full template at
  references/admiralty-templates/marine-deployment-brief.md — it includes model
  assignment guidance and haiku briefing requirements.
== END BRIEFING ==

Field notes

• Mission — Copy verbatim from sailing orders so the teammate shares the same outcome/metric framing.
• Ship — From the ship manifest in the battle plan. Gives the teammate identity and signals task weight (frigate, destroyer, etc.).
• File Ownership — Critical for preventing merge conflicts when multiple agents work in parallel. If no files are assigned, note "No file ownership — research/analysis only."
• Dependencies — List both blocking (what must finish first) and blocked-by (what waits on this task). If none, note "Independent — no dependencies."
• Mission Directory — The absolute path to the current mission directory. Captains use this path when writing damage reports and turnover briefs.
• Marine Capacity — From the ship manifest. Tells the captain how many marines they may deploy (max 2). Omit if 0.
• Standing Orders — Keep these to 4-5 lines. Project-specific standing orders can be appended here. The marine standing order tells captains they CAN deploy marines and where to find the rules — without this, captains have no knowledge of marines.

Damage Report Template

File a damage report to communicate context window usage to the admiral. Store each report as a JSON file at {mission-dir}/damage-reports/{ship-name}.json during a mission.

{
  "ship_name": "",
  "agent_id": "",
  "timestamp": "",
  "token_count": 0,
  "token_limit": 0,
  "hull_integrity_pct": 0,
  "hull_integrity_status": "",
  "relief_requested": false,
  "context_summary": "",
  "report_path": "{mission-dir}/damage-reports/{ship-name}.json"
}

Field Definitions

Hull Integrity Thresholds

Notes

• Hull integrity represents remaining capacity, not usage. A ship at 75% hull integrity has used 25% of its context window.
• Set relief_requested to true when hull integrity drops to Red or Critical. The admiral uses this flag to prioritise relief on station.
• Update the report at each quarterdeck checkpoint or when hull integrity crosses a threshold boundary.
• The admiral reads all damage reports from {mission-dir}/damage-reports/ to build the squadron readiness board.

Read-Only Agent Variant

Agents spawned with subagent_type="Explore" (Navigating Officer, Coxswain, Recce Marines) are read-only — they cannot write files, including damage reports.

These agents report hull integrity via SendMessage to their captain. The captain writes the damage report JSON on their behalf using the same template and field definitions above.

If the read-only agent is a Recce Marine reporting directly to a captain, the captain includes the marine's hull integrity in their own damage report under context_summary.

Estimate Template

Light scaffolding — the admiral writes prose, not forms. See references/the-estimate.md for the thought process behind each section.

# The Estimate — {mission title}

## 1. Reconnaissance
- What terrain was scouted (files, subsystems, external dependencies)
- What Explore agents were dispatched, and what they found
- Notable surprises, constraints, or prior art

## 2. Intent
- Commander's intent (one paragraph, propagates to every captain's brief)
- Why this matters; what success looks like in the user's terms

## 3. Effects

### Effect: {short outcome-focused name}

{One paragraph: what must change, where it lands, why.}

**Commander's guidance:** {library choices, patterns, design decisions.}

**Acceptance criteria:**
- {Criterion 1 — paired with verification method in captain's work}
- {Criterion 2}
- {Criterion 3}

### Effect: {next effect}
...

## 4. Terrain
- Files and modules each effect lands on
- Test suites affected
- Blast radius per effect

## 5. Forces
- Captains required (ship class, model, number)
- Crew roles where applicable
- Red-cell navigator? Marines?

## 6. Coordination
- Dependency graph (what must precede what)
- Parallel tracks
- Shared artifacts or coordination surfaces

## 7. Control
- Quality gates (where verification runs)
- Intervention points (where the user may wish to inspect)
- Action-station tiers per task
- Rollback plan

Notes for the admiral:

• One H2 per question. Write in prose; bullets are a fallback, not a default.
• Each effect in §3 must carry commander's guidance and at least one acceptance criterion.
• Cross-reference sections naturally ("the auth effect from §3", not "Effect AC-1").
• Addenda (dated, appended under the relevant section) are how the estimate evolves — do not rewrite history.

Marine Deployment Brief Template

== MARINE DEPLOYMENT BRIEF ==
Ship: [parent ship name]
Detachment: [Recce Marine / Assault Marine / Sapper]
Model: [assigned model — see Model Assignment in references/royal-marines.md]
[If assigned haiku — add identity anchor, output format, and task decomposition blocks
 from references/model-selection.md, and apply haiku tasking discipline to Objective,
 Scope, and Report back below]
Objective: [single clear sentence]
Scope: [what to do, and explicitly what NOT to do]
Report back: [what findings/outputs to return]
Constraints:
- Do NOT modify files outside objective scope
- Do NOT spawn sub-agents
- Report findings to captain, do not act beyond objective
== END BRIEF ==

Quarterdeck Report Template

Mission directory:
Checkpoint time:

Progress:
- pending:
- in_progress:
- completed:

Blockers:
- blocker:
  owner:
  next action:
  eta:

Budget:
- token/time spent:
- token/time remaining:

Hull integrity (squadron readiness board):
- ship: [ship name]
  hull_pct: [percentage]
  status: [Green / Amber / Red / Critical]
  relief_requested: [yes / no]
- ship:
  hull_pct:
  status:
  relief_requested:

Admiral hull integrity:
- hull_pct:
- status:

Standing order violations:
- order: (none / list each triggered since last checkpoint)
  corrective action taken:
- order:
  corrective action taken:

Risk updates:
- new/changed risks:
- mitigation:

Signal flag (if any):
- recognition:

Admiral decision:
- continue / rescope / stop:
- rationale:

Red-Cell Review Template

Target task/artifact:

Challenge summary:
- Primary assumption being tested:
- Likely failure mode:
- Blast radius if wrong:

Checks run:
- check:
- result:

Recommendation:
- approve / revise / block:
- required changes:

Sailing Orders Template

Sailing orders:
- Outcome:
- Success metric:
- Deadline:

Constraints:
- Token/time budget:
- Reliability floor:
- Compliance/safety constraints:
- Forbidden actions:

Scope:
- In scope:
- Out of scope:

Stop criteria:
- Stop when:

Required handoff artifacts:
- Must produce:

Ship Manifest Template

Ship:
- Name:
- Captain:
- Task:
- Crew manifest:
  - [Role Abbr]: [Sub-task description]
  - [Role Abbr]: [Sub-task description]
- Marine capacity: [0-2]
- Sub-task sequence:
  1. [Sub-task] (dependencies: none)
  2. [Sub-task] (dependencies: 1)
- Estimated token budget:

Turnover Brief Template

Typed Handoff Packet (Primary)

The primary turnover format is a structured JSON handoff packet written by nelson-data.py handoff. See references/structured-data.md for the schema and command reference.

The typed packet is written to {mission-dir}/turnover-briefs/{ship-name}-{timestamp}.json. The replacement ship reads this JSON file as its first action.

Prose Turnover Brief (Companion)

When a typed handoff packet has been written, the damaged ship may optionally also write a prose companion brief to {mission-dir}/turnover-briefs/{ship-name}-{timestamp}.md using the template below. This prose version supplements the JSON packet with a human-readable narrative for manual review. It is not the primary recovery artifact.

If nelson-data.py handoff is unavailable (e.g., script error, pre-upgrade missions), the prose brief below serves as the fallback format.

== TURNOVER BRIEF ==
Ship: [ship name and class]
Role: [Captain N — role description]
Timestamp: [when this brief was written]
Reason for relief: [Red hull / Critical hull / degraded output / requested]

Mission context:
- Mission: [mission name from sailing orders]
- Outcome: [outcome from sailing orders]
- Success metric: [metric from sailing orders]

Task assignment:
- Task ID: [from battle plan]
- Task name: [from battle plan]
- Deliverable: [what must be produced]
- Action station: [0-3]
- File ownership: [files assigned to this task]
- Dependencies: [upstream and downstream tasks]

Progress log:
- [Completed item 1 — specific description of what was done]
- [Completed item 2 — specific description of what was done]
- [...]

Running plot (work in progress when relieved):
- [What was being worked on at the time of relief]
- [Current state of that work — how far along, what remains]
- [Any partial outputs saved and where to find them]

Files touched:
- [file path] — [description of changes made]
- [file path] — [description of changes made]
- [...]

Key decisions made:
- [Decision 1] — Rationale: [why this choice was made]
- [Decision 2] — Rationale: [why this choice was made]
- [...]

Hazards and blockers:
- [Hazard or blocker 1 — current status and impact]
- [Hazard or blocker 2 — current status and impact]
- [None discovered, if applicable]

Recommended course of action:
- [What the replacement should do first]
- [What to do next]
- [What to avoid or watch out for]

Relief chain:
- [Previous Ship Name] | [time on station] | [key accomplishment] | [reason for relief]
- [Previous Ship Name] | [time on station] | [key accomplishment] | [reason for relief]
- [This is the first ship on this task, if no previous reliefs]

== END TURNOVER BRIEF ==

Flagship Turnover Brief

When the admiral hands over, append these additional sections after the standard fields. The flagship brief replaces the "Task assignment" section with full squadron state.

== FLAGSHIP TURNOVER BRIEF ==
Ship: Flagship [name]
Role: Admiral
Timestamp: [when this brief was written]
Reason for relief: [hull integrity level and percentage if known]

Sailing orders:
- Outcome: [verbatim from sailing orders]
- Success metric: [verbatim from sailing orders]
- Deadline: [verbatim from sailing orders]
- Constraints: [verbatim from sailing orders]
- Out of scope: [verbatim from sailing orders]

Battle plan status:
- Task [ID]: [name] | Owner: [ship] | Status: [pending/in_progress/completed] | Notes: [brief]
- Task [ID]: [name] | Owner: [ship] | Status: [pending/in_progress/completed] | Notes: [brief]
- [...]

Squadron state:
- [Ship name] ([class]) | Captain [N] | Task: [ID] | Hull: [Green/Amber/Red/Critical] | Status: [active/relieved/stood down]
- [Ship name] ([class]) | Captain [N] | Task: [ID] | Hull: [Green/Amber/Red/Critical] | Status: [active/relieved/stood down]
- [...]

Key decisions made:
- [Decision 1] — Rationale: [why]
- [Decision 2] — Rationale: [why]
- [...]

Active blockers and risks:
- [Blocker/risk] — Owner: [who] — Status: [open/mitigating/resolved]
- [...]

Pending escalations:
- [Escalation description] — Awaiting: [Admiralty decision / agent response]
- [None, if applicable]

Quarterdeck rhythm:
- Cadence: [e.g., every 15 minutes]
- Last checkpoint: [timestamp or checkpoint number]
- Next scheduled checkpoint: [timestamp or checkpoint number]

Relief chain:
- [Previous Admiral session] | [time on station] | [key accomplishment] | [reason for relief]
- [This is the first admiral on this mission, if no previous reliefs]

Recommended course of action:
- [What the new admiral should do first]
- [Priority items requiring immediate attention]
- [Ships that may need relief soon]

== END FLAGSHIP TURNOVER BRIEF ==

Field Notes

• Write to file, not message. The turnover brief is written to disk so the replacement ship can read it without the brief consuming message context. This keeps the replacement's context window clean for actual work.
• Be specific in the progress log. "Implemented the auth module" is insufficient. "Implemented JWT validation in src/auth/validate.ts with RS256 signing, added tests in tests/auth.test.ts covering expired/malformed/valid tokens" gives the replacement ship enough detail to continue.
• Running plot is critical. The replacement must know exactly what was in flight, not just what was finished. Include file paths, function names, and the specific point where work stopped.
• Keep the relief chain bounded. Each previous relief gets one line. Do not paste previous turnover briefs into the chain — summarize them. If the chain reaches 3 entries, the admiral should re-scope the task rather than adding a fourth.
• Flagship briefs copy sailing orders verbatim. The new admiral session has no memory of the original orders. Copy them in full rather than summarizing.

Commendations and Conduct

Recognition and correction during missions. Loaded on demand.

Signal Flags

When acknowledging progress in quarterdeck reports or coordination messages, keep praise specific and brief:

• "Well fought clearing that blocker ahead of schedule."
• "Handsomely done on the failure-mode analysis."
• "Ship in good order — clean handoff to MEO for validation."
• "Good instinct surfacing that dependency early."

Avoid generic praise. Tie recognition to observable actions or deliverables.

Mentioned in Despatches

Record exemplary performance in the Captain's Log. Name the agent and their contribution:

• "Captain of HMS Argyll: Proactive rollback testing prevented Station 2 regression."
• "PWO aboard HMS Kent: Clear documentation enabled seamless handoff."
• "Red-cell navigator: Identified auth edge case missed in initial review."

Criteria:

• Proactive risk mitigation or blocker resolution.
• Output quality that required minimal rework.
• Initiative that advanced mission goals beyond assigned scope.
• Coordination that unblocked other agents.

Graduated Discipline

Correction MUST be proportional. Progress through levels. At Level 2 and above, the correction MUST be applied before the mission proceeds — do not defer corrections to a later checkpoint.

Level 1 — Signal

First occurrence, low impact, easily corrected.

Admiral or captain provides direct guidance in a coordination message. Reference the relevant standing order.

Example: "Keep the admiral on coordination, not implementation — see standing-orders/admiral-at-the-helm.md."

Level 2 — Standing Order Remedy

Repeated issue or moderate impact.

Apply the formal remedy from the relevant standing order. Log the correction in the quarterdeck report.

Level 3 — Damage Control

Severe impact, mission-threatening, or remedy failed.

Invoke the relevant damage control procedure: man overboard, partial rollback, scuttle and reform, or escalation.

Do not skip levels unless the issue is immediately mission-critical. At any level, a standing order violation that is not corrected MUST block forward progress until resolved.

Morale Awareness

Watch for indirect signals:

• Task velocity slowing (may indicate confusion or unclear orders).
• Terse coordination messages (may indicate frustration).
• Blocker accumulation (agents may need unblocking, not replacing).
• Idle time with unverified outputs (unclear expectations).

Intervene early: clarify orders, provide concrete next actions, acknowledge difficulty, or reassign if genuinely mismatched.

Crew Roles Reference

The admiral uses this file during formation to determine initial crew composition for each ship. Captains use it when requesting mid-task crew adjustments (with admiral approval).

Crew-or-Direct Decision

Choose the first condition that matches.

1. If the task is atomic, requires no file reads or research, and can be completed in a single pass, captain implements directly (0 crew). 2. If the task has one clear deliverable (including tasks that require reading files or light research), crew 1 PWO. 3. If the task needs exploration, testing, or a second specialism, crew PWO + 1 specialist. 4. If the task has multiple interdependent sub-tasks, crew XO + PWO + up to 2 specialists.

Never exceed 4 crew per ship. If the task demands more, split it into two ships.

Crew Sizing

Role Definitions

Read-Only Roles

NO and COX use the Explore subagent type. They cannot modify files. They report findings to the captain or XO, who decides how to act on them.

Role Boundaries

Each crew member works strictly within their role definition. A PWO does not run tests (that is the MEO). A NO does not write code (they report findings). See standing order standing-orders/pressed-crew.md for the anti-pattern.

Ship Name Registry

Admiral assigns a ship name to each captain during squadron formation. Choose names that roughly match task weight.

Frigates (general-purpose tasks)

Argyll, Kent, Lancaster, Richmond, Somerset, Portland, Iron Duke, St Albans

Destroyers (high-tempo or high-risk tasks)

Daring, Dauntless, Diamond, Dragon, Defender, Duncan

Patrol Vessels (small tasks)

Forth, Medway, Trent, Tamar, Spey

Historic Flagships (critical-path tasks)

Victory, Warspite, Vanguard, Ark Royal

Submarines (stealth or research tasks)

Astute, Ambush, Artful, Audacious

Crew Standing Orders

The following standing orders apply specifically to crew operations:

• standing-orders/captain-at-the-capstan.md — Captain must not implement when crew are mustered.
• standing-orders/all-hands-on-deck.md — Do not crew roles the task does not need (too many crew).
• standing-orders/skeleton-crew.md — Do not spawn a single crew member for an atomic task (too few crew).
• standing-orders/pressed-crew.md — Do not assign crew work outside their designated role (wrong crew).

Royal Marines

Marines are NOT crew. They are short-lived sub-agents a captain deploys for discrete objectives outside the crew's task scope. See references/royal-marines.md for deployment rules and specialisations.

Key distinction: Crew subdivide the ship's deliverable. Marines execute independent sorties in support of the ship's task.

Circuit Breakers: Automated Budget Alarms

Use to supplement the admiral's checkpoint rhythm with automatic, threshold-based alarms. Circuit breakers surface advisories when resource thresholds are crossed — they do not abort ships or auto-execute damage control. The admiral decides the remedy.

What They Are

Circuit breakers are a set of named thresholds evaluated at two points:

1. At each quarterdeck checkpoint, by nelson-data.py checkpoint, against the freshly-written fleet-status.json and mission log. 2. On `TeammateIdle` hook fires, for per-ship idle timeouts, via the idle-ship hook handler.

When a threshold is crossed, a circuit_breaker_tripped event is appended to mission-log.json with the value, the threshold, and the recommended damage control procedure. The admiral sees a single advisory line per trip on stdout (or stderr for the idle-ship hook) and decides what to do.

Circuit breakers are advisory in the current release. A future strict mode may auto-trigger relief on station for hull breaches or auto-abort on catastrophic budget overrun.

Thresholds and Defaults

The enabled key (default true) is a master switch.

Configuration

Circuit breaker thresholds live under sailing-orders.json > circuit_breakers. The admiral can edit this file directly after nelson-data init:

{
  "version": 1,
  "outcome": "...",
  "budget": {"token_limit": 100000, "time_limit_minutes": 120},
  "circuit_breakers": {
    "hull_integrity_threshold": 75,
    "budget_alarm_ratio": 0.75,
    "idle_timeout_minutes": 5,
    "enabled": true
  }
}

Unknown keys are silently ignored so typos cannot secretly override defaults. Missing keys fall back to the defaults in nelson_circuit_breakers.py.

To disable all circuit breakers for a mission (e.g. a smoke test mission), set enabled: false.

Output Format

When a checkpoint trips a breaker, nelson-data.py checkpoint prints one line per trip to stdout after the checkpoint summary:

[nelson-data] Checkpoint 3 recorded
Fleet: 1/4 done | Budget: 80.0% | Hull: 4G 0A 0R 0C | Blockers: 0
[CIRCUIT BREAKER: budget_alarm] Budget alarm: 80% of tokens spent with only 25% of tasks complete. Elevate to Station 2 and review scope.

The same trip is appended to mission-log.json as:

{
  "type": "circuit_breaker_tripped",
  "checkpoint": 3,
  "timestamp": "2026-04-11T12:34:56Z",
  "data": {
    "type": "budget_alarm",
    "value": {"spent_ratio": 0.8, "completion_ratio": 0.25},
    "threshold": {"spent_ratio": 0.7, "completion_ratio": 0.4},
    "action": "admiral-review",
    "message": "Budget alarm: 80% of tokens spent with only 25% of tasks complete. ..."
  }
}

This record is the authoritative trail for post-mission analysis — nelson-data history and the cross-mission memory store will see circuit breaker events and can correlate them with outcomes.

Idle Timeout: How the Hook Tracks State

The TeammateIdle hook does not receive an idle duration in its payload. To compute elapsed idle time, the circuit breaker keeps a small state file at <mission-dir>/idle-tracker.json:

1. First time TeammateIdle fires for ship X → record {X: "2026-04-11T12:00:00Z"} and emit no advisory. 2. Subsequent fires → compute elapsed from the stored timestamp. If elapsed ≥ idle_timeout_minutes, emit the man-overboard advisory. 3. When a ship's task becomes completed (the paid-off standing order path), its tracker entry is cleared.

Tracker state is best-effort: if the file cannot be written, the breaker silently degrades.

Fleet-Status Budget Extensions

Each checkpoint now writes two new fields under fleet-status.json > budget:

• burn_rate_per_task — tokens_spent / completed, rounded to integer. None when no tasks have completed.
• projected_budget_at_completion — burn_rate_per_task × total. None when burn_rate_per_task is None or total == 0.

These are advisory projections, not guarantees. They exist so the admiral (and any future planner) can read a single field and see where the mission is heading without re-computing from raw counters.

When Circuit Breakers Are Not Enough

Circuit breakers are a backstop, not a substitute for:

• The quarterdeck checkpoint rhythm — breakers run at checkpoint time but the admiral still owns the decision.
• Hull integrity reports — breakers detect a breach only if the ship has filed a damage report or the squadron readiness board has been updated.
• Standing orders — breakers do not evaluate anti-patterns; that is the admiral's standing-order check at each decision point.

If a circuit breaker fires repeatedly for the same root cause, that is signal that a new standing order may be warranted. See docs/ for how standing orders are added.

Relationship to Other Procedures

• Hull integrity (hull-integrity.md): the hull-integrity circuit breaker is a secondary alarm on top of the damage-report-driven readiness board. It catches misses.
• Crew overrun (crew-overrun.md): the cost-per-task circuit breaker detects overruns by burn-rate spike rather than by captain self-report.
• Man overboard (man-overboard.md): the idle-timeout circuit breaker catches stuck ships the admiral has not yet noticed.
• Scuttle and reform (scuttle-and-reform.md): the consecutive-failures circuit breaker triggers this consideration without the admiral having to count blockers manually.

Communications Failure: Agent Team Infrastructure

Use when agent team communication fails — agent IDs become unreachable, SendMessage returns errors, or the shared task list becomes inaccessible.

This procedure covers infrastructure-level failures where the communication channel itself is broken, not agent-level issues (for stuck or unresponsive agents that are still reachable, use man-overboard.md).

Symptoms

• SendMessage fails with agent ID not found or similar errors.
• Multiple ships become unreachable simultaneously.
• TaskList or TaskGet returns errors or stale data.
• Ship results cannot be retrieved despite the agent having completed work.

Procedure

1. Admiral records which ships are unreachable and which tasks they owned. 2. Admiral checks TaskList for any results that were written before the failure. 3. For each lost ship: a. Check if the ship wrote any output to disk (files, partial deliverables) that can be recovered. b. Record the ship's last known status and any recovered outputs in the quarterdeck report. 4. Admiral assesses mission viability:

• If enough work is complete to finish the mission with remaining ships, redistribute lost tasks to reachable ships or spawn new sub-agents.
• If the agent team infrastructure is fully down, fall back to subagents mode for remaining work. Spawn replacement captains as independent sub-agents and brief them with recovered context.
• If the mission cannot continue, invoke scuttle-and-reform.md.

5. Admiral MUST NOT take over implementation work from lost ships. The admiral-at-the-helm standing order applies even during infrastructure failures. Spawn replacement agents instead. 6. Log the communications failure, affected ships, recovered outputs, and remedial action in the quarterdeck report.

Prevention

• For missions with 4+ ships, prefer writing intermediate outputs to disk rather than relying solely on the message bus for result delivery.
• Include explicit "write checkpoint to disk" instructions in crew briefings for long-running tasks.
• At each quarterdeck checkpoint, verify all ships are still reachable before continuing.

Crew Overrun: Ship Budget Recovery

Use when a ship's crew is consuming disproportionate tokens or time relative to its task weight.

1. Captain pauses all crew activity on the ship. 2. Captain reviews each crew member's progress against their assigned sub-task and estimated budget. 3. Captain identifies the source of overrun: scope creep, blocked crew member, or mismatched role assignment. 4. Captain takes corrective action:

• If scope creep: descope the sub-task to its original definition.
• If blocked: resolve the blocker or reassign the sub-task to a different crew member.
• If role mismatch: reassign the sub-task to the correct role or handle it directly.

5. Captain resumes crew activity with a revised budget allocation. 6. If the ship cannot recover within budget, captain escalates to admiral with a summary and recommendation: extend budget, descope the ship's task, or split the remaining work into a second ship.

See damage-control/circuit-breakers.md for the automated cost_per_task_overrun alarm that can catch overruns between captain self-reports.

Escalation: Chain of Command

Escalation flows upward: Crew to Captain to Admiral to Admiralty (human).

Triggers

Note: The following entry documents a planned, expected handoff — not a failure condition. It is listed here so that any captain encountering this situation without a prior briefing has a defined path.

| Captain has reached a planned human-action step (admiralty-action-required: yes) and cannot continue | Captain invokes the awaiting-admiralty standing order |

Procedure

1. The agent encountering the issue pauses work on the affected task. 2. Agent reports to admiral with: issue summary, options considered, and one recommendation. 3. Admiral evaluates whether the issue can be resolved within current authority:

• If yes: admiral decides and documents the rationale.
• If no: admiral escalates to Admiralty (human) with a summary and recommendation.

4. Admiralty provides direction. 5. Admiral communicates the decision to the affected agent and updates the battle plan. 6. Agent resumes work under the new direction.

Authority Boundaries

• Crew member: Can resolve issues within their sub-task scope. Must escalate anything affecting other crew members or the ship's deliverable to captain.
• Captain: Can resolve issues within their own task scope. Must escalate anything affecting other tasks, shared resources, or mission scope.
• Admiral: Can re-assign tasks, replace agents, adjust timelines, elevate action stations, and descope within the original sailing orders. Must escalate scope changes, budget extensions, and abort decisions.
• Admiralty (human): Final authority on scope, budget, and abort. All irreversible or high-blast-radius decisions require Admiralty confirmation.

Hull Integrity: Context Window Management

Use to monitor and manage context window consumption across the squadron.

Hull Integrity Thresholds

Each ship maintains a hull integrity percentage representing its remaining context window capacity.

Squadron Readiness Board

The admiral maintains a readiness board to track hull integrity across all ships. Build the board by reading damage reports from {mission-dir}/damage-reports/.

1. At each quarterdeck checkpoint, collect the latest damage report from every active ship. 2. List each ship with its hull integrity status, percentage, and whether relief is requested. 3. Flag any ship at Red or Critical for immediate attention. 4. Record the board in the quarterdeck report under the "Hull integrity (squadron readiness board):" section.

The readiness board gives the admiral a single view of squadron endurance and drives decisions about task reassignment, descoping, and relief.

Integration with Quarterdeck Rhythm

Check hull integrity at every quarterdeck checkpoint:

1. Each captain files a damage report using the template from references/admiralty-templates/damage-report.md. 2. Admiral reads all damage reports and updates the squadron readiness board. 3. If any ship has crossed a threshold boundary since the last checkpoint, admiral takes the action defined for that threshold. 4. Admiral records hull integrity status in the quarterdeck report.

Between checkpoints, captains file an immediate damage report when hull integrity crosses any threshold boundary. Do not wait for the next scheduled checkpoint to report a status change.

Relief on Station

Trigger relief on station when a ship reaches Red hull integrity. Execute as follows:

1. Admiral spawns a replacement ship with the same role and ship class. 2. The outgoing captain writes a handoff summary: task definition, completed sub-tasks, partial outputs, known blockers, and file ownership. 3. Admiral briefs the replacement captain with the handoff summary and the original crew briefing. 4. Replacement captain resumes from the last verified checkpoint, not from scratch. 5. Admiral updates the battle plan to reflect the new ship assignment. 6. Admiral issues a shutdown request to the outgoing ship.

If multiple ships reach Red simultaneously, prioritise relief for the ship closest to Critical.

Flagship Self-Monitoring

The admiral must monitor its own hull integrity with the same discipline applied to the squadron.

1. Admiral tracks its own token usage and calculates hull integrity at each checkpoint. 2. For Amber, Red, and Critical flagship actions, follow the procedure in references/damage-control/relief-on-station.md. The admiral does not wait for Critical — losing coordination state at Critical cannot be recovered.

Relationship to Other Damage Control Procedures

Hull integrity monitoring works alongside existing damage control procedures:

• Session Resumption (session-resumption.md): Use when hull integrity reaches Critical and the session must end. The session resumption procedure picks up from the last quarterdeck report.
• Crew Overrun (crew-overrun.md): A crew overrun accelerates hull integrity loss. When a captain detects a crew overrun, the corrective action should account for the ship's current hull integrity — a ship already at Amber has less margin to absorb an overrun than one at Green.
• Man Overboard (man-overboard.md): Replacing a stuck agent consumes additional context. Factor hull integrity into the decision to replace versus descope.
• Scuttle and Reform (scuttle-and-reform.md): When the flagship reaches Red and multiple ships are also at Red or Critical, consider scuttling the current mission and reforming with fresh context rather than attempting piecemeal relief.

Automated Circuit Breaker

In addition to the damage-report-driven readiness board, Nelson's automated circuit breakers emit a hull_integrity_breach advisory at each checkpoint when any ship's hull_integrity_pct falls at or below circuit_breakers.hull_integrity_threshold (default 80%). See damage-control/circuit-breakers.md for thresholds, configuration, and output format.

Advanced: TeammateIdle Hook

Nelson ships a TeammateIdle hook in hooks/hooks.json that triggers an automatic check when a captain goes idle. The hook reads fleet status to determine whether the ship's task is complete and whether pending dependents remain. If the task is complete with no dependents, it advises executing the paid-off standing order. This supplements the quarterdeck checkpoint rhythm with event-driven monitoring.

Man Overboard: Stuck Agent Replacement

Use when an agent is unresponsive, looping, or producing no useful output. For infrastructure-wide communication failures (multiple agents unreachable, message bus down), see comms-failure.md instead.

1. Admiral identifies the stuck agent and its assigned task. 2. Admiral records the agent's last known progress and any partial outputs. 3. Admiral issues a shutdown request to the stuck agent. 4. Admiral spawns a replacement agent with the same role. 5. Admiral briefs the replacement with: task definition, dependencies, partial outputs, and known blockers. 6. Replacement agent resumes from the last verified checkpoint, not from scratch. 7. Admiral updates the battle plan to reflect the new assignment.

Crew Variant

Use when a crew member aboard a ship is stuck, looping, or unresponsive. The captain handles recovery at ship level.

1. Captain identifies the stuck crew member and their assigned sub-task. 2. Captain records the crew member's last known progress and any partial outputs. 3. Captain issues a shutdown request to the stuck crew member. 4. Captain spawns a replacement crew member with the same role. 5. Captain briefs the replacement with: sub-task definition, dependencies, partial outputs, and known blockers. 6. Replacement crew member resumes from the last verified checkpoint, not from scratch. 7. Captain updates the ship manifest to reflect the new assignment. 8. If the same role fails twice, captain escalates to admiral with a summary and recommendation.

Manual Cleanup Fallback

Use when the shutdown attempt ceiling is exhausted (3 failed attempts) and TeamDelete is blocked by stuck agents that will not respond to shutdown requests. This is a last resort — always attempt graceful shutdown first.

1. Admiral confirms that 3 shutdown attempts have failed and TeamDelete is blocked. 2. Admiral runs the following commands to remove the stuck team manually:

• rm -rf ~/.claude/teams/{team-name} — removes the team registration
• rm -rf ~/.claude/tasks/{team-name} — removes associated task data

3. Admiral verifies the team no longer appears in active team listings. 4. Admiral records the affected agents and the manual cleanup action in the captain's log. 5. Admiral spawns a fresh replacement team and re-issues the affected tasks from the last verified checkpoint.

Partial Rollback: Reverting Without Losing Progress

Use when a completed task is found to be faulty but other completed tasks are sound.

1. Admiral identifies the faulty task and its downstream dependents. 2. Admiral marks the faulty task as in_progress and all dependents as pending. 3. If the faulty task produced code changes, revert those changes using version control. 4. If the faulty task produced non-code artifacts, archive them with a reverted label. 5. Re-assign the faulty task to the original owner or a replacement agent. 6. Agent re-executes the task from its original definition with the failure mode documented as a constraint. 7. Once the re-executed task is verified, unblock and resume dependent tasks.

Relief on Station: Context Window Exhaustion

Use when a ship's context window is depleted and a fresh ship must take over its task.

Relief on station is a planned handover. For stuck or unresponsive agents, use man-overboard.md. For unplanned session interruptions, use session-resumption.md.

Trigger Conditions

Initiate relief when any of the following are true:

• Ship reports Red hull integrity (40-59% context remaining).
• Ship reports Critical hull integrity (below 40% context remaining).
• Admiral observes degraded output quality (repetition, missed instructions, shallow reasoning).
• Ship explicitly requests relief.

Hull integrity monitoring may surface context exhaustion before crew overrun is noticed. If a ship is burning context fast, check both this procedure and crew-overrun.md.

Relief Sequence

1. Admiral signals the damaged ship to prepare for turnover. 2. Damaged ship pauses current work and commits or saves any in-progress outputs. 3. Damaged ship writes a typed handoff packet by running python3 .claude/skills/nelson/scripts/nelson-data.py handoff --mission-dir {mission-dir} --ship-name "..." --task-id N --task-name "..." --handoff-type relief_on_station ... (see references/structured-data.md for full arguments). This writes a JSON handoff packet to {mission-dir}/turnover-briefs/{ship-name}-{timestamp}.json and logs the relief_on_station event. Optionally, the ship may also write a prose companion brief to {mission-dir}/turnover-briefs/{ship-name}-{timestamp}.md using references/admiralty-templates/turnover-brief.md for human readability. 4. Damaged ship signals admiral that the handoff packet is written and provides the file path. 5. Admiral spawns a replacement ship. The replacement need not be the same ship class — select the class that matches the characteristics of the remaining work (e.g., swap a destroyer for a frigate if the remaining work is lighter). 6. Admiral briefs the replacement ship with a crew briefing that includes the handoff packet file path. The replacement reads the JSON handoff packet as its first action. 7. Admiral reassigns the task to the replacement ship. 8. Admiral updates the task list entry with TaskUpdate to reflect the replacement ship as the new owner. 9. Admiral issues a shutdown request to the damaged ship. 10. Admiral updates the battle plan to reflect the new ship assignment.

Flagship Self-Monitoring

The admiral must monitor its own hull integrity at every quarterdeck checkpoint.

Green Hull Integrity (75-100% remaining)

No action required. Continue normal operations.

Amber Hull Integrity (60-74% remaining)

1. Admiral notes hull status in the quarterdeck report. 2. Admiral begins drafting a flagship turnover brief in the background, capturing current mission state incrementally. 3. Admiral considers whether remaining coordination work can complete within budget. If not, begin planning the handover early.

Red Hull Integrity (40-59% remaining)

1. Admiral writes a typed handoff packet via nelson-data.py handoff --handoff-type relief_on_station ... to {mission-dir}/turnover-briefs/flagship-{timestamp}.json. Additionally, write a prose flagship turnover brief to {mission-dir}/turnover-briefs/flagship-{timestamp}.md containing:

• Full sailing orders (copied verbatim).
• Battle plan with current task statuses, owners, and ship assignments.
• All active ship statuses and their hull integrity levels.
• Key decisions made during the mission and their rationale.
• Active blockers, risks, and pending escalations.
• Quarterdeck rhythm cadence and next scheduled checkpoint.
• Relief chain history (see below).

2. Admiral notifies Admiralty (human) that the flagship is handing over and provides the turnover brief path. 3. Admiralty starts a new session. The new admiral reads the flagship turnover brief as its first action and resumes from the last quarterdeck checkpoint.

Critical Hull Integrity (below 40% remaining)

1. Execute the Red procedure immediately. Do not wait for the next checkpoint. 2. Prioritize writing the flagship turnover brief over all other coordination work.

Chained Reliefs

When a task requires multiple handovers (A hands to B, B hands to C), maintain institutional memory without unbounded growth.

1. Each handoff packet includes a relief_chain array listing all previous handovers for this task. The handoff command validates that this array does not exceed 3 entries. 2. Each entry in the relief chain contains ship name, reason for relief, and handoff time. 3. The current ship writes a full handoff packet for its own work. Previous ships' work is represented only by their relief chain entries, not by appending their full packets. 4. Maximum 3 reliefs per task. If a third replacement is needed, the admiral should re-scope the task — it is likely too large or poorly defined for a single ship. 5. The relief chain gives the replacement ship a lineage of what has been tried and accomplished without consuming excessive context.

Crew Variant

When a crew member aboard a ship exhausts their context, the captain handles relief at ship level.

1. Captain identifies the crew member at Red or Critical hull integrity. 2. Captain instructs the crew member to write a handoff packet (or turnover brief if the crew member cannot run nelson-data.py) to file. 3. Captain spawns a replacement crew member and provides the handoff packet path. 4. Captain issues a shutdown request to the exhausted crew member. 5. Captain updates the ship manifest to reflect the new assignment. 6. If the same role requires relief twice, captain escalates to admiral — the sub-task may need re-scoping.

Scuttle and Re-Form: Mission Abort

Use when the mission cannot succeed under current conditions and continuing wastes budget.

Triggers:

• Budget (token or time) is exhausted with critical tasks still pending.
• Mission outcome is no longer achievable due to discovered constraints.
• Admiral determines that remaining risk exceeds acceptable threshold.

Procedure:

1. Admiral halts all in-progress work immediately. 2. Each agent saves current partial outputs and documents their last known state. 3. Admiral produces an abort log using the Captain's Log Template with:

• Reason for abort.
• Tasks completed and their outputs.
• Tasks abandoned and their partial state.
• Conditions required before re-attempting the mission.

4. Admiral marks all task list entries as completed (for finished tasks) or updates their description to note they were abandoned (for incomplete tasks). This ensures the user's Ctrl+T display does not show stale in-progress tasks. 5. Admiral issues shutdown requests to all agents. 6. Admiral presents the abort log to the human (Admiralty) with a recommendation: retry with new constraints, descope, or abandon.

Session Hygiene: Clean Start Procedure

Use at the start of a new Nelson session to prepare the mission directory before any ships are launched.

Directory Structure

Nelson stores each mission's data in a timestamped directory under .nelson/missions/:

.nelson/missions/{YYYY-MM-DD_HHMMSS}_{SESSION_ID}/
  captains-log.md         — Written at stand-down
  quarterdeck-report.md   — Updated at every checkpoint
  damage-reports/         — Ship damage reports (JSON)
  turnover-briefs/        — Ship turnover briefs (markdown)

Each mission gets its own directory. Previous missions are preserved automatically — there is no need to archive or delete old data.

Responsibility

The admiral executes session hygiene at Step 1 (Issue Sailing Orders), before forming the squadron or launching any ships.

Procedure: New Session

1. Confirm this is a genuinely new session, not a resumption. If resuming, skip this procedure entirely and follow the Resumed Session procedure below. 2. Verify that nelson-data.py init (Step 1, "Structured Data Capture") has been run. It creates the mission directory, the damage-reports/ and turnover-briefs/ subdirectories, the three initial JSON files, and the .nelson/.active-{SESSION_ID} marker in one step. Confirm {mission-dir} is set to the path the script printed. 3. Note that session hygiene is complete. Proceed to form the squadron.

Procedure: Resumed Session

1. If you know the SESSION_ID for this session, read .nelson/.active-{SESSION_ID} to recover the mission directory path and set it 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}. 2. Read existing damage reports from {mission-dir}/damage-reports/ to establish hull integrity for each ship. 3. Read existing turnover briefs from {mission-dir}/turnover-briefs/ to recover task state. 4. Follow damage-control/session-resumption.md for the full resumption procedure.

Rotated Report Files

Within each mission directory, rotated checkpoint files may be present:

• quarterdeck-report-0.md, quarterdeck-report-1.md, etc.
• captains-log-0.md, captains-log-1.md, etc.

These are intentionally preserved as checkpoint history — they record the state of the reports at each checkpoint within that mission. They do not require cleanup because:

1. Each mission has its own timestamped directory (.nelson/missions/{YYYY-MM-DD_HHMMSS}_{SESSION_ID}/) 2. Rotated files within a mission directory are historical artifacts of that mission's execution 3. Previous missions are preserved automatically, so the checkpoint history is part of the permanent record for that mission

You may review checkpoint history by reading the rotated files in the mission directory. You should not delete them.

Browsing Previous Missions

Previous missions remain on disk at .nelson/missions/. To review past mission logs, list the directory contents sorted by name (which sorts chronologically by date/time).

Session Resumption: Picking Up Mid-Mission

Use when a session is interrupted (context limit, crash, timeout) and work must continue.

1. Auto-recovery (preferred): Run python3 .claude/skills/nelson/scripts/nelson-data.py recover --missions-dir .nelson/missions. If an active mission is found, the command outputs a structured recovery briefing with fleet status, handoff packets, pending tasks, and recommended actions. Use this output to resume directly, skipping manual directory selection. 2. Manual recovery (fallback): If auto-recovery is unavailable, and you know the SESSION_ID, read .nelson/.active-{SESSION_ID} to recover the mission directory path and set it 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}. 3. Recover state from structured data:

• If {mission-dir}/fleet-status.json exists, read it for quick state recovery (task progress, hull status, budget, blockers).
• If {mission-dir}/turnover-briefs/ contains .json handoff packets, read the most recent packet for each ship to recover per-ship task state. These provide structured data about completed subtasks, partial outputs, blockers, and next steps.
• If {mission-dir}/mission-log.json exists, read it for full event history — task completions, relief chains, standing order violations, and admiral decisions.
• These JSON files provide faster, more reliable state recovery than re-parsing quarterdeck report prose.
• Fallback: If no JSON files are present, read {mission-dir}/quarterdeck-report.md to establish last known state.
• Sub-fallback: If the canonical quarterdeck-report.md is also missing (e.g. crash during report rotation), check for {mission-dir}/quarterdeck-report-N.md files (where N is a number). Use the file with the highest N value — it contains the most recent checkpoint data. The same fallback applies to captains-log.md / captains-log-N.md.
• The recovery briefing surfaces a "Fleet status may be stale" warning when last_updated is older than 10 minutes or when mission-log.json has events newer than last_event_id. When the warning appears, verify in-progress task state against handoff packets and file state before resuming — do not trust the cached progress counters.

4. List all tasks and their statuses: pending, in_progress, completed. 5. For each in_progress task, verify partial outputs against the task deliverable. If a handoff packet exists for the task, use its state.partial_outputs and state.next_steps to guide verification. 6. Discard any unverified or incomplete outputs that cannot be confirmed correct. 7. Re-issue sailing orders with the original mission outcome and updated scope reflecting completed work. 8. Re-form the squadron at the minimum size needed for remaining tasks. 9. Resume quarterdeck rhythm from the next scheduled checkpoint.

Safe compaction windows. State is fully persisted at every phase boundary: after Sailing Orders (Step 1), after the Estimate (Step 2), after the Battle Plan is drafted to disk (Step 3), after Formation (Step 4), and at every quarterdeck checkpoint (Step 6). The one unsafe window is inside Step 5: between the user granting permission and the admiral logging permission_granted + advancing to UNDERWAY + spawning agents — that whole sequence is a single tightly coupled turn.

Model Selection

Use this reference when the sailing orders express cost-savings priority. It governs model assignment for all squadron agents.

Detecting Cost-Savings Intent

Nelson infers cost-savings priority from natural language in the sailing orders or initial prompt. Signals include phrases such as:

• "keep costs low", "stay within budget", "budget is a concern"
• "use cheaper models", "use haiku where possible"
• "be aggressive with cost savings", "minimize spend"

The intensity of the language calibrates the aggressiveness of weight adjustment (see Hybrid Adjustment below).

Default Weight Table

Threshold Rule

In cost-savings mode:

• Weight ≤ 4 after adjustment → assign haiku
• Weight ≥ 5 after adjustment → inherit admiral's model

Estimate Phase Carve-Out

The Estimate phase (Q1–Q7) is exempt from cost-savings model adjustment. All Estimate subagents — Explorer dispatches at Q1 and the Q2–Q3 / Q4–Q7 dispatches — inherit the admiral's model.

Rationale: planning quality dominates downstream execution quality. A weaker model in The Estimate produces poorer terrain assessments, looser commander's guidance, and weaker acceptance criteria, which the squadron then carries into implementation. Degrading the Estimate to save tokens is a false economy.

When invoking Estimate subagents:

• Omit the model: parameter on the Agent tool call so the subagent inherits the admiral's model.
• Do not apply the haiku briefing enhancement blocks below — they are conditional on haiku assignment, which does not occur during The Estimate.
• Cost-savings adjustment resumes at Battle Plan and Formation steps, where it applies normally.

Hybrid Adjustment

The tasking agent adjusts default weights before assignment:

• Raise weight when the task involves judgment, edge cases, or verification that exceeds the role default.
• Lower weight when the task is more atomic or contained than the role default suggests.

Scale of adjustment calibrates to intensity of cost-savings request:

• Modest language ("keep costs low") → modest pressure; don't push roles at 5–6 below the threshold unless clearly justified.
• Emphatic language ("be aggressive") → willing to push roles normally at 5–6 through the threshold when the task is contained.

No hard bounds are set. The admiral uses judgment.

Model Assignment Rules

• The admiral's model is never overridden.
• All agents at weight ≥ 5 inherit the admiral's model. Omit the `model` parameter entirely in the Task tool call — do not specify "sonnet", as that alias resolves to an older version and does not match the admiral's model.
• For haiku agents (weight ≤ 4), always specify model: "haiku" explicitly.
• Display weight and assigned model in the squadron formation summary alongside ship names and tasks.

Briefing Enhancements (haiku agents only)

These requirements apply whenever any tasking agent — admiral, captain, or crew — assigns haiku to a subordinate. When assigning haiku, add three blocks to that agent's briefing:

1. Identity Anchor (top of briefing)

You are Claude, operating as a subagent in a real multi-agent software development system. The Royal Navy terms used for coordination (admiral, captain, crew, etc.) are metaphors — this is not roleplay. Your task is [plain-language description of role].

2. Explicit Output Format

Specify exactly what to return: format, required fields, length, and what to omit. Remove ambiguity. Example:

Return a JSON object with keys status, summary, and files_changed. Do not include implementation reasoning or next steps.

3. Task Decomposition Prompt

Before executing, list your steps as a numbered plan. If any step is unclear, flag it now rather than guessing.

These three blocks are conditional on haiku assignment. Do not include them in standard (non-cost-savings) briefings or in briefings for agents assigned the admiral's model.

Tasking Agent Discipline (haiku agents only)

Whoever writes the task — admiral, captain, or crew — must compensate for reduced inferencing capacity by making the task itself precise. Vague instructions are not rescued by the briefing enhancement blocks above.

Each haiku task description must include:

Explicit Constraints

State what the agent must not do, must not touch, and must stay within. Do not rely on the agent to infer scope limits from context.

Example: "Only read files under src/auth/. Do not modify any file. Do not follow imports outside that directory."

Definition of Done

State a concrete, testable condition that signals the task is complete. Avoid open-ended outcomes.

Example: "Done when you have returned a JSON list of all public method names in JwtMiddleware. Stop after that — do not analyze their bodies."

Escalation Triggers

State the specific conditions under which the agent must stop and report rather than proceed. Do not expect haiku to self-identify when it is out of depth.

Example: "If the file does not exist, or if you find more than one class matching that name, stop and report what you found. Do not guess which one to use."

These requirements are conditional on haiku assignment. Standard briefings for agents on the admiral's model do not require this level of prescription.

Royal Marines

Royal Marines are short-lived sub-agents a captain deploys for focused, independent objectives in service of the ship's task. They are doctrinally distinct from crew: crew subdivide the ship's deliverable, marines execute discrete sorties and return.

Deploy-or-Escalate Decision

Choose the first condition that matches.

1. Quick recon of unfamiliar area → Recce Marine 2. Targeted fix or small implementation to unblock ship → Assault Marine 3. Quick config/build/infra task → Sapper 4. Sustained work, own deliverable, needs file ownership → NOT a marine. Request a new ship from the admiral. 5. Work that subdivides the ship's main deliverable → NOT a marine. Crew the role instead.

Marine Specialisations

Read-Only Specialisation

Recce Marines use the Explore subagent type. They cannot modify files. They report findings to the captain, who decides how to act on them.

Deployment Rules

• Max 2 marines per ship at any time. If the task needs more, it is crew work or a new ship.
• Marines cannot deploy marines. No recursion permitted.
• Marines report only to their deploying captain. They do not communicate with crew or other ships.
• Captain must verify marine output before incorporating it into the ship's deliverable.
• Marines do not get ship names. Identify them as: RM Detachment, HMS [Ship] — [objective].

Action Station Interaction

Marine deployments inherit the parent ship's station tier:

• Station 0-1: Captain deploys at discretion. No admiral approval required.
• Station 2: Captain must signal admiral and receive approval before deploying marines.
• Station 3: Marine deployment is not permitted. All Trafalgar-tier work requires explicit Admiralty (human) confirmation.

Recovery

Marine recovery is simple. No separate damage-control procedure is needed.

• If a marine is stuck or unresponsive, captain abandons the deployment.
• Captain either redeploys a fresh marine or handles the objective directly.
• If the same marine objective fails twice, captain escalates to admiral.

Model Assignment

The deploying captain applies the same weight-based model judgment the admiral uses for squadron agents. The default weight for a Royal Marine is 3, but adjust before assigning:

• Raise weight when the objective requires judgment, interpretation, or navigating unfamiliar territory.
• Lower weight when the objective is fully specified and purely mechanical.

If the adjusted weight is ≤ 4 (or cost-savings mode is active), assign haiku and apply the haiku briefing enhancements and tasking discipline from references/model-selection.md. Do not assign haiku and then write a vague brief — the two requirements go together.

Deployment Template

When deploying a marine, use the briefing template at admiralty-templates/marine-deployment-brief.md.

Squadron Composition Reference

Use this file to choose execution mode and team size.

Mode Selection

User preference override: If the user explicitly requests a specific execution mode (e.g., "use agent teams"), that request MUST be honoured. User preference takes priority over the decision matrix below. Do not second-guess or override the user's choice.

Evaluate all three conditions and select the best fit. When two modes could apply, prefer the one that gives captains more autonomy.

• single-session: Work is sequential, tightly coupled, or mostly in the same files.
• subagents: Work is parallel and each captain's task is fully independent — no shared coordination surface needed.
• agent-team: Work is parallel and captains benefit from a shared task list, peer messaging, or coordinated deliverables. Also use when 4+ captains are needed, or when the user requests it.

Decision Matrix

Team Sizing

The right number of captains equals the number of independently executable work units — not a complexity tier. Before choosing a number, map the dependency graph and count how many tasks can run concurrently with zero shared state. That count is the target.

Zero shared state means: no file ownership overlap AND no sequencing dependency (task B does not require the output of task A). Peer coordination across module boundaries (e.g., agreeing on an API contract) is permitted and handled by the admiral.

• Assign one captain per independent work unit.
• Only merge tasks onto one captain when they share files, have a sequencing dependency, or are so small that agent setup cost clearly exceeds the work itself.
• Add 1 red-cell navigator at medium/high threat.
• Keep one admiral only.
• Squadron cap: 10 squadron-level agents (admiral, captains, red-cell navigator). Crew are additional — up to 4 per captain, governed by references/crew-roles.md.

An analysis mission with 8 independent sections warrants 8 captains. An implementation mission with 3 independent modules warrants 3. When in doubt, add a captain — idle context is cheap; serialized work is slow. In cost-optimized missions (sailing orders with token-budget priority), consult references/model-selection.md before defaulting to maximum parallelism.

Role Guide

• admiral: Defines sailing orders, delegates, tracks dependencies, resolves blockers. May perform read-only recombination of completed ship outputs once all ships have reported successfully, but MUST NOT perform generative synthesis directly — assign a captain or dedicate a synthesis task for that.
• captain: Commands a ship. Breaks task into sub-tasks, coordinates crew, verifies outputs. Implements directly only when the task is atomic (0 crew). Initial crew composition is set by the admiral at formation; captains may request mid-task adjustments with admiral approval.
• Crew roles: Executive Officer (XO), Principal Warfare Officer (PWO), Navigating Officer (NO), Marine Engineering Officer (MEO), Weapon Engineering Officer (WEO), Logistics Officer (LOGO), Coxswain (COX). See references/crew-roles.md for role definitions and crewing rules.
• red-cell navigator: Challenges assumptions, validates outputs, checks rollback readiness.

Anti-Patterns

See the Standing Orders table in SKILL.md for the full list of standing orders and known anti-patterns.

Worktree Isolation

When file ownership boundaries are hard to draw or multiple captains must modify overlapping files, use isolation: "worktree" on the Agent tool. This gives each captain an isolated copy of the repository via a git worktree.

Worktree isolation is a stronger alternative to the file-ownership approach in standing-orders/split-keel.md. Use it when:

• Multiple captains need to edit the same files.
• Merge conflict risk is high and the split-keel standing order cannot resolve it.
• Tasks are large enough that the merge cost is justified.

Trade-off: Worktree isolation prevents conflicts during execution but requires merging changes afterward. The admiral is responsible for coordinating the merge.

Standing Order: Admiral at the Helm

The admiral MUST NOT perform implementation work. Implementation work (writing code, editing files, running tests) remains strictly delegated to ships.

The synthesis boundary: Coordination means issuing orders, tracking progress, resolving blockers, and running checkpoints. Read-only recombination — combining text from completed ship reports already present in the admiral's context, without generating new analysis, code, or deliverables beyond what ships produced — is permitted for the admiral only once all ships have reported successful completion with no open blockers or unresolved failures.

Do not dispatch additional sub-agents just to combine data you already have in context. Once the ships have completed their individual implementation tasks and reported back, the admiral may recombine those results without generating new content. The admiral is also permitted to write the captain's log (Step 6) and other coordination artifacts.

Symptoms of a violation:

• Admiral writes code, edits files, or runs tests directly.
• Captains sit idle waiting for direction while admiral is heads-down on implementation.
• Quarterdeck rhythm breaks because admiral is unavailable for checkpoint reviews.
• Blockers accumulate without resolution.
• Admiral spawns a sub-agent purely to concatenate or summarize text already present in the context window.
• Battle plan assigns generative synthesis to the admiral rather than a captain.

Remedy: Admiral MUST delegate all implementation to captains. If the admiral is doing implementation, stop immediately, spawn a captain, and delegate. If the work is read-only recombination of completed ship outputs already present in context (i.e., no new generation required), the admiral may proceed without delegation.

Standing Order: All Hands on Deck

Do not crew every role when the task does not require it.

Symptoms:

• Ship musters 4 crew for a task that needs only a PWO.
• Crew members with no meaningful sub-task sit idle or invent busywork.
• Token budget burns on coordination overhead that exceeds the work itself.
• Captain spends more time briefing and reviewing crew than the task warrants.

Remedy: Crew only the roles the task demands. Start with a PWO and add specialists only when there is a concrete sub-task that matches their role definition. Refer to the crew sizing table in references/crew-roles.md.

Standing Order: Awaiting Admiralty

A captain that has reached a planned human-action step and completed all autonomous work must invoke this standing order.

Status convention: TaskUpdate accepts only pending, in_progress, and completed as status values. awaiting-admiralty is a naming convention, not a status enum. Prefix the task description with [AWAITING-ADMIRALTY]: and leave status as in_progress.

Trigger: Captain completes all autonomous work for a task and reaches a step marked admiralty-action-required: yes.

Captain's procedure: 1. Complete all work that does not require human input. Write all produced artifacts to disk. 2. Call TaskUpdate to prefix the task description with [AWAITING-ADMIRALTY]: and leave status as in_progress (do not set status to completed). 3. Report to admiral with three elements:

• What was completed (artifact name and location).
• Exact ask: what the human must do and what to return.
• What is blocked until this resolves.

4. Do not attempt to continue, skip, or substitute. Wait for a SendMessage from the admiral relaying the admiralty's input. Take no further action until that message arrives. Do not poll. Normal hull-integrity procedures continue to apply while holding — if context pressure builds before the SendMessage arrives, signal the admiral so a turnover brief can be written before context exhaustion.

Admiral's procedure on receiving this report: 1. Surface to Admiralty immediately — do not defer to the next scheduled quarterdeck checkpoint. 2. Place any dependent tasks on hold. 3. When Admiralty provides the input, relay it to the captain via SendMessage, call TaskUpdate to remove the [AWAITING-ADMIRALTY]: prefix from the description, and confirm status remains in_progress. 4. Record the resolved value in the quarterdeck report.

Battalion Ashore

Rule: Do not deploy marines for work that belongs to the ship's crew or warrants a new ship.

Symptoms

• Captain deploys marines constantly instead of using mustered crew.
• Marine objectives expand beyond single sorties.
• Marines editing files outside the ship's ownership.
• More marines deployed than crew mustered.

Remedy

• Use crew for sub-tasks of the ship's deliverable.
• Escalate to admiral for sustained independent work that needs its own ship.
• Marines are for focused sorties only — quick recon, targeted fixes, one-shot tasks.

See references/royal-marines.md for the deploy-or-escalate decision tree.

Standing Order: Becalmed Fleet

Do not create an agent team for work that is mostly linear and sequential.

Symptoms:

• Captains idle waiting on a single predecessor task.
• Token budget burns on coordination overhead with no parallel throughput gain.
• Tasks form a long chain with no independent branches.

Remedy: Use single-session mode. Only form a squadron when at least two tasks can run concurrently.

Standing Order: Captain at the Capstan

The captain must not perform implementation work when crew are mustered.

Symptoms:

• Captain writes code, edits files, or runs tests while crew members are active.
• Crew sit idle waiting for direction while captain is heads-down on implementation.
• Ship-level coordination breaks because captain is unavailable to review crew outputs.
• Sub-task blockers accumulate without resolution.

Remedy: Captain must delegate all implementation to crew and stay focused on coordination: assigning sub-tasks, reviewing crew outputs, resolving blockers within the ship, and reporting progress to admiral.

Standing Order: Crew Without Canvas

Do not add agents without reducing the critical path length of the mission.

Symptoms:

• More captains are active but the mission does not finish sooner.
• Coordination messages increase while throughput stays flat.
• Token budget inflates with no improvement in mission metric.

Remedy: Before adding an agent, identify the specific critical-path task it will parallelize. If no such task exists, do not add the agent.

Standing Order: Drifting Anchorage

Do not allow tasks to expand scope beyond the original sailing orders without re-scoping.

Symptoms:

• Captains add features or refactors not in the battle plan.
• Mission metric is no longer connected to active work.
• Token and time budgets overrun without corresponding mission progress.
• Captain creates new functions, files, or environment variables that duplicate existing ones instead of extending them.
• Existing implementation is deprecated, bypassed, or shadowed rather than modified.

Remedy: When scope drift is detected during a quarterdeck checkpoint, re-scope the task or split it. Work that falls outside the sailing orders must be deferred or explicitly added with admiral approval.

When a captain creates a parallel implementation instead of extending existing code, direct the captain to remove the duplicate and modify the existing implementation. If the task is already completed, apply partial rollback per references/damage-control/partial-rollback.md and re-task with explicit modification targets.

Standing Order: Light Squadron

Do not group independent tasks onto fewer captains than their independence warrants.

Symptoms:

• Multiple sections, documents, or code areas are bundled onto one captain when they share no files and have no sequencing dependency.
• The captain serializes work that could run concurrently, extending wall-clock time with no benefit.
• The battle plan has fewer captains than there are independent work units.
• Admiral defaults to a fixed captain count without first counting the parallelizable leaves.

Remedy: Split bundled tasks onto separate captains. The number of captains should equal the number of truly independent work units, bounded by the squadron cap.

Ask: "What is the maximum number of tasks that can run concurrently with zero shared state?" That number is the target captain count.

Only bundle tasks onto one captain when they:

• Share files where parallel edits would produce unresolvable merge conflicts (same functions, tight coupling) — use isolation: "worktree" when files overlap but merge cost is justified (see squadron-composition.md), or
• Have a genuine sequencing dependency (task B requires output of task A), or
• Are so small that the context-setup cost of a separate agent clearly exceeds the work itself.

See also standing-orders/crew-without-canvas.md for the inverse risk: do not add agents without reducing critical path length.

Standing Order: Press-Ganged Navigator

Do not use the red-cell navigator as a general-purpose task runner.

Symptoms:

• Red cell is assigned implementation tickets rather than review gates.
• Quality challenges stop appearing in quarterdeck reports.
• Verification evidence comes from the same agent that wrote the code.

Remedy: Keep the red-cell navigator exclusively on review, challenge, and validation duties. Never assign implementation tasks to the navigator.