Nelson

If you believe that what works well for people works well for agents, there's few finer examples of organisational tradition than the Royal Navy to base the rules on. This framework does just that, for Claude Code.

4 risk tiers · 11 damage control procedures · 11 mission templates · 7 crew roles · 16 standing orders

Captain Horatio Nelson — John Francis Rigaud, 1781. Image: Wikimedia Commons

Contents

• Quick Start
• What it does
• Why Nelson?
• How it works
• Prerequisites
• Installation
• Usage
• Customisation
• Plugin file structure
• Mission artifacts
• Compatibility notes
• Star History
• Disclaimer
• License

Quick Start

Install the plugin:

/plugin marketplace add harrymunro/nelson
/plugin install nelson@nelson-marketplace

Describe your mission — Nelson loads automatically, no slash command needed:

Use Nelson to migrate the payment module from Stripe v2 to v3

Nelson will draft sailing orders, present a battle plan for your approval, form a squadron of captains to execute in parallel, run quarterdeck checkpoints, and produce a captain's log when the mission stands down. See Prerequisites for the full agent-team experience with split panes.

What it does

https://github.com/user-attachments/assets/2468679d-39f5-4efb-9d93-43d43eee8907

Nelson gives Claude an eight-step operational framework for tackling complex missions:

1. Sailing Orders — Define the outcome, success metric, constraints, and stop criteria
2. The Estimate — Conduct the 7 Question Maritime Tactical Estimate: reconnaissance, intent, effects, terrain, forces, coordination, and control
3. Battle Plan — Turn approved effects into task assignments with owners, dependencies, and file ownership
4. Form the Squadron — Choose an execution mode (single-session, subagents, agent team, workflow, or hybrid workflow) and size the team
5. Get Permission to Sail — Present the plan for user approval before committing resources
6. Quarterdeck Rhythm — Run checkpoints to track progress, identify blockers, monitor hull integrity, and manage budget
7. Action Stations — Classify tasks by risk tier and enforce verification before marking complete
8. Stand Down — Produce a captain's log with decisions, artifacts, validation evidence, and follow-ups

Why Nelson?

Most agent orchestration tools focus on starting missions. Nelson focuses on completing them safely.

Nelson gives your missions a shared vocabulary: "action stations" instead of "risk tier escalation", "hull integrity" instead of "context window consumption", "man overboard" instead of "stuck agent replacement". The names stick. So do the habits.

• Risk-gated execution — Four station tiers (Patrol through Trafalgar) classify every task before it runs. High-risk work requires human confirmation; low-risk work flows without ceremony.
• Damage control built in — Eleven named procedures for stuck agents, context exhaustion, faulty output, budget overruns, automated alarms, and mission abort. These are protocols, not improvisation.
• A decision log by default — Captain's log, quarterdeck reports, and turnover briefs are written as the mission runs. Every decision is auditable after the session ends.

Nelson coordinates its own development — recent releases have been planned and executed as Nelson missions.

Who is this for?

• You run Claude Code missions spanning multiple files or modules in parallel
• You want structured checkpoints, risk classification, and a decision log
• You've lost work to context exhaustion and want systematic handover procedures
• You care about auditability — knowing what was decided, by which agent, and why

It may be overkill if you're doing a quick, single-file edit.

How Nelson compares

Nelson trades upfront setup time for coordination guarantees:

If you need fast parallel execution with minimal ceremony, OmO or RuFlo may suit you better. If coordination, auditability, and safe scaling matter more than raw tempo, Nelson is the better fit.

How it works

Execution modes

The skill selects one of five execution modes based on your mission:

Dynamic workflows and ultracode

Claude Code dynamic workflows move orchestration into workflow scripts that can fan out to many agents, keep intermediate results in script state, and aggregate broad review or migration results. Nelson does not replace that mechanism. Nelson wraps it with doctrine: Sounding-the-Channel probes, explicit permission gates, cost guardrails, audit logs, and verification contracts before findings or edits are accepted.

ultracode is treated as a Claude Code xhigh effort/automation setting, not a Nelson execution mode. If ultracode or the user chooses a workflow, Nelson still supplies the mission charter, risk tiering, human gates, telemetry expectations, and fallback mode.

Standing goals

For long autonomous, headless, or scheduled runs, Nelson aligns with Claude Code's /goal — a session-scoped Stop hook that keeps the session from stopping until a completion condition is met. Nelson composes the condition from the sailing orders (nelson-data.py goal-condition) so it stays tied to the mission's outcome, metric, and stop criteria, and phrases it against what the goal evaluator can actually see: the conversation transcript. The standing goal and Nelson's Mission Complete Gate reinforce each other — the gate is the discipline the admiral applies, the goal is the harness backstop that enforces it. See references/goal-alignment.md.

Chain of command

Nelson uses a three-tier hierarchy. The admiral coordinates captains, each captain commands a named ship, and crew members aboard each ship do the specialist work.

                          ┌───────────┐
                          │  Admiral  │
                          └─────┬─────┘
                  ┌─────────────┼─────────────┐
                  ▼             ▼             ▼
           ┌───────────┐ ┌───────────┐ ┌───────────┐
           │  Captain   │ │  Captain   │ │ Red-Cell  │
           │ HMS Daring │ │ HMS Kent   │ │ Navigator │
           └─────┬─────┘ └─────┬─────┘ └───────────┘
            ┌────┼────┐   ┌────┼────┐
            ▼    ▼    ▼   ▼    ▼    ▼
           XO  PWO  MEO  PWO  NO  COX

Squadron level:

• Admiral — Coordinates the mission, delegates tasks, resolves blockers. Coordinates final synthesis but does not perform it directly. There is always exactly one.
• Captains — Each commands a named ship. Breaks their task into sub-tasks, crews specialist roles, coordinates crew, and verifies outputs. Implements directly only when the task is atomic. Typically 2-7 per mission.
• Red-cell navigator — Challenges assumptions, validates outputs, and checks rollback readiness. Added for medium/high risk work.

Ship level (crew per captain, 0-4 members):

Navigating Officer (NO) and Coxswain (COX) are read-only — they report findings but never modify files.

Ships are named from real Royal Navy warships, matched roughly to task weight: frigates for general-purpose, destroyers for high-tempo, patrol vessels for small tasks, historic flagships for critical-path, and submarines for research.

Squadron size caps at 10 squadron-level agents (admiral, captains, red-cell navigator). Crew are additional — up to 4 per ship. If a task needs more crew, split it into two ships.

Action stations (risk tiers)

Every task is classified into a risk tier before execution. Higher tiers require more controls:

Tasks at Station 1 and above also run a failure-mode checklist:

• 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?

Damage control

Most agent frameworks assume the happy path. Nelson includes battle-tested procedures for when things go wrong — stuck agents, budget overruns, faulty outputs, and context window exhaustion all have documented recovery paths.

Hull integrity monitoring tracks context window consumption across the squadron. The admiral reads exact token counts from Claude Code session JSONL files at each quarterdeck checkpoint and maintains a squadron readiness board:

Token counts come directly from the API usage data Claude Code records on every assistant turn — no estimation heuristics, no paid APIs, no external dependencies. scripts/count-tokens.py extracts them and produces damage reports.

Relief on station replaces a ship whose context window is depleted. The damaged ship writes a turnover brief to file; a fresh replacement reads it and continues the mission. Chained reliefs (A → B → C) are supported for long-running tasks. The flagship monitors its own hull integrity too and can hand over to a new session.

Circuit breakers layer automated alarms on top of the admiral's checkpoint rhythm — hull integrity, budget burn, cost-per-task, consecutive blockers, and idle timeouts. When a threshold is crossed, an advisory event is appended to the mission log and surfaced to the admiral, who decides the remedy. Circuit breakers do not auto-abort.

Other procedures cover the rest of the failure modes:

• Man overboard — replace a stuck agent
• Partial rollback — revert faulty work without aborting the mission
• Crew overrun — recover from budget exhaustion
• Scuttle and reform — abort and reform when the mission cannot succeed
• Comms failure — recover from agent-team infrastructure failure
• Session resumption — pick up after an interruption
• Session hygiene — clean-start procedure for new sessions
• Escalation — chain-of-command for issues beyond current authority

Conflict radar

When multiple ships work in parallel, undeclared file overlaps are a common source of merge pain. Nelson ships two tools that catch conflicts at different stages:

• Pre-flight conflict scan (nelson_conflict_scan.py) — parses the battle plan before Action Stations, walks the codebase import graph, and flags "split-keel" violations where two captains own files that import each other.
• Runtime conflict radar (nelson_conflict_radar.py) — compares live git status against the battle plan's file ownership declarations during execution and alerts on changed files that have no registered owner.

Both tools are stdlib-only and run as part of the mission workflow without additional setup.

Enforcement hooks

Nelson is not purely advisory. A set of Claude Code hooks (hooks/nelson_hooks.py) enforce structural guarantees at the tool level:

Plugin installs auto-discover hooks/hooks.json and wire these up with no user action. Hooks degrade gracefully: if no active Nelson mission is found, they exit cleanly and do not interfere with non-Nelson workflows. See Installation for manual-install caveats.

Cross-mission intelligence

Nelson accumulates learning across missions in .nelson/memory/. Each completed mission feeds a persistent pattern library (patterns.json) and standing-order violation stats (standing-order-stats.json). Five nelson-data.py subcommands expose this:

• brief — pre-mission intelligence brief: relevant patterns, win rate, standing order hot spots, and context-matched precedents drawn from prior missions.
• analytics — focused metric queries (success-rate, standing-orders, efficiency) with text or JSON output.
• history / index — review and rebuild the fleet intelligence index across past missions.
• stand-down --adopt/--avoid — capture reusable patterns at mission close so the next run benefits.

Running index backfills the memory store for missions completed before the feature existed, so upgrading is non-destructive.

Admiral synthesis

Once every ship has reported on Stand Down, the admiral produces a fleet-wide synthesis — consolidating captain outputs into a single decision record. Boundary controls prevent premature synthesis (before all ships have reported) and keep the admiral out of direct implementation.

Templates

Nelson ships eleven structured templates to keep outputs consistent across missions:

Prerequisites

• Claude Code CLI installed and authenticated
• Recommended: Enable agent teams for the full squadron experience. Nelson works without it (using single-session or subagent modes), but agent teams unlock teammate-to-teammate coordination — the agent-team execution mode. Plugin installs ship a settings.json that enables this automatically. For manual installs, add this to your settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

• For split-pane visibility: To see each agent working in its own pane (as shown in the demo video), run Claude Code inside tmux. Agent teams auto-detect tmux and give every teammate a dedicated split pane so you can watch the whole squadron in action.

Installation

Plugin install (recommended)

Add the marketplace and install:

/plugin marketplace add harrymunro/nelson
/plugin install nelson@nelson-marketplace

Install skills from https://github.com/harrymunro/nelson

# Project-level (recommended for teams)
git clone https://github.com/harrymunro/nelson.git /tmp/nelson
mkdir -p .claude/skills
cp -r /tmp/nelson/skills/nelson .claude/skills/nelson
rm -rf /tmp/nelson

# Or user-level (personal, all projects)
cp -r /tmp/nelson/skills/nelson ~/.claude/skills/nelson

/plugin marketplace update nelson-marketplace
/plugin install nelson@nelson-marketplace

What skills are available?

cd ~/.cursor/plugins/local
git clone -b main --depth 1 https://github.com/harrymunro/nelson.git

cd ~/.cursor/plugins/local/nelson
git pull

Usage

Nelson is a Claude Code skill — it loads automatically when your request matches. No slash command required. Just describe your mission and mention Nelson.

Let Nelson pick the execution mode

Nelson selects the best execution mode (single-session, subagents, agent team, workflow, or hybrid workflow) based on your mission:

Use Nelson to migrate the payment processing module from Stripe v2 to v3

Force an agent team

If you want teammate-to-teammate coordination, ask for an agent team explicitly:

Use an agent team with Nelson to refactor the authentication system across
the API layer, frontend, and test suite

Go maximal

For the highest-capability run — Opus 4.7 agents, fully crewed ships, maximum coordination:

Use an agent team with Nelson and Opus 4.7 agents with fully crewed ships
to deliver the new billing integration

Full sailing orders

For maximum control, provide your own sailing orders:

Use Nelson to deliver this:

Sailing orders:
- Outcome: All API endpoints return consistent error responses
- Success metric: Zero test failures, all error responses match the schema
- Deadline: This session

Constraints:
- Token/time budget: Stay under 50k tokens
- Forbidden actions: Do not modify the database schema

Scope:
- In scope: src/api/ and tests/api/
- Out of scope: Frontend error handling

You can also invoke it directly with the /nelson slash command if you prefer.

Customisation

Edit files under skills/nelson/references/ to adapt Nelson to your team — admiralty-templates/ for reporting style, action-stations.md for risk-tier controls, squadron-composition.md for team sizing rules.

Plugin file structure

.claude-plugin/           # Plugin + marketplace ma