v1.4.0 — Hull Integrity & Relief on Station

What's New

Hull Integrity Monitoring

Ships can now monitor their context window consumption — the invisible killer of long-running agent missions. The admiral reads exact token counts directly from Claude Code session JSONL files at each quarterdeck checkpoint and maintains a squadron readiness board tracking every ship's health.

Four-tier threshold system based on remaining context capacity:

Status	Remaining	Action
Green	75–100%	Operating normally
Amber	60–74%	Admiral notes on readiness board, captain avoids new work
Red	40–59%	Relief on station — begin handover to a fresh ship
Critical	Below 40%	Immediate relief, cease non-essential activity

No estimation heuristics. No paid APIs. No external dependencies. The token counts come straight from the API usage data that Claude Code already records on every assistant turn.

Relief on Station

When a ship's hull integrity drops to Red, the admiral orchestrates a tactical handover:

1. Damaged ship pauses work and writes a turnover brief to file
2. Admiral spawns a fresh replacement (not necessarily the same ship class)
3. Replacement reads the turnover brief and continues the mission
4. Damaged ship stands down

The turnover brief is comprehensive — mission context, progress log, running plot, files touched, key decisions, hazards, and recommended course of action. Written to file (not a message) to keep the replacement's context clean.

Chained reliefs are supported (A → B → C) with bounded cumulative briefs. Each previous handover gets a single-line summary in the relief chain. Maximum 3 reliefs per task before the admiral should re-scope.

Flagship Self-Monitoring

The admiral monitors its own hull integrity at every checkpoint. At Amber, it begins drafting a flagship turnover brief. At Red, it writes the full brief — including verbatim sailing orders, complete battle plan status, all ship states, and decisions made — and notifies the Admiralty (human) that a new session must take over.

Session Hygiene

New sessions start clean. The admiral clears stale damage reports and turnover briefs from .claude/nelson/ before forming the squadron. Previous session data can optionally be archived. Resumed sessions skip cleanup and read existing reports to recover state.

Token Counter Script

scripts/count-tokens.py — a zero-dependency Python script with three modes:

# Flagship checks itself
python scripts/count-tokens.py --session session.jsonl --ship "HMS Victory"

# Full squadron readiness board
python scripts/count-tokens.py --squadron /path/to/{session-id}/

# Plain text fallback (heuristic)
python scripts/count-tokens.py --file document.txt --ship "HMS Argyll"

The --squadron mode scans the flagship JSONL and all subagent files in {session-id}/subagents/ in one pass. Ships can't easily self-monitor (they don't know their own agent ID), but that's the correct pattern — the flagship monitors everyone.

Other Improvements

• Ambiguity check on briefs — The admiral now reviews the user's brief for ambiguity and asks for clarification before drafting sailing orders
• Documentation file trees synced with current branch state
• Skill alignment with Anthropic's skills guide conventions

New Files

skills/nelson/references/
  admiralty-templates/
    damage-report.md        — JSON template for hull integrity reports
    turnover-brief.md       — Standard and flagship handover briefs
  damage-control/
    hull-integrity.md       — Threshold definitions & squadron readiness board
    relief-on-station.md    — Planned ship replacement procedure
    session-hygiene.md      — Clean start procedure for new sessions
scripts/
  count-tokens.py           — Token counter for hull integrity monitoring

Live Data

Squadron readiness board captured during the session that built this release:

Ship	Tokens	Hull	Status
Flagship	104,365	47%	Red
HMS Kent	26,952	86%	Green
HMS Argyll	29,341	85%	Green
HMS Daring	34,693	82%	Green
HMS Astute	57,269	71%	Amber

The flagship was at Red hull integrity by the end of the mission — proving exactly why this feature is needed.

v1.3.0 — Royal Marines

What's New

Royal Marines

• Captains can now deploy short-lived sub-agents (Royal Marines) for focused sorties during execution
• Three marine specialisations: Recce Marine (exploration), Assault Marine (implementation), Sapper (bash operations)
• Deploy-or-escalate decision tree to distinguish marine work from crew work
• Station-tier integration — Station 2+ deployments require admiral approval
• New standing order: Battalion Ashore prevents misuse of marines for sustained crew work
• Marine deployment brief template added to crew briefings
• Max 2 marines per ship, no recursive spawning

Claude Code Plugin

• Converted Nelson from a .claude/skills/ skill to a standalone Claude Code plugin
• Added .claude-plugin/ metadata for marketplace compliance
• Skill files relocated from .claude/skills/nelson/ to skills/nelson/

Housekeeping

• Moved images from repo root to docs/images/
• Battleships demo improvements

v1.2.0

What's New

CI Pipeline

• Added CI checks for markdown, YAML, link validation, spelling, and cross-reference integrity

Battleships Demo

• Overhauled with game modes, AI opponent, accessibility improvements, and UX polish

Nelson Skill

• Added motivation and graduated discipline system
• Moved crew briefing to after battle plan phase
• Added step gate checks and crew briefing template
• Switched to imperative language throughout

Operational Improvements

• Renamed template index entry for clarity (thanks @EmanuelFaria)

Docs

• Updated README with crew examples and action stations documentation

v1.1.0 — Ship Crew System

Nelson v1.1.0 — Ship Crew System

Introduces a three-tier agent hierarchy: Admiral → Captain → Crew. Captains can now muster specialist crew members within their ships, enabling deeper task decomposition without inflating the squadron.

What's new

Crew system

• Seven crew roles: Executive Officer (XO), Principal Warfare Officer (PWO), Navigating Officer (NO), Marine Engineering Officer (MEO), Weapon Engineering Officer (WEO), Logistics Officer (LOGO), and Coxswain (COX) — each with a defined function and subagent type
• Crew-or-direct decision tree: Structured rules for when a captain should implement directly (atomic tasks) vs. muster 1–4 crew members
• Ship name registry: Named vessels grouped by class — Frigates, Destroyers, Patrol Vessels, Historic Flagships, and Submarines — matched to task weight
• Read-only roles: NO and COX use the Explore subagent type and cannot modify files, enforcing separation of research from implementation

New standing orders

• Captain at the Capstan — Captain must not implement when crew are mustered
• All Hands on Deck — Do not crew roles the task does not need
• Skeleton Crew — Do not spawn a single crew member for an atomic task
• Pressed Crew — Do not assign crew work outside their designated role

New damage control procedures

• Crew Overrun — Recovery when too many crew are active on a ship
• Man Overboard — Recovery when a crew member fails or goes unresponsive

Other changes

• Ship manifest template added for captains to declare crew composition
• Battle plan template updated with crew fields
• Squadron composition updated — squadron cap of 10 agents, plus up to 4 crew per captain
• README updated with crew system docs and chain of command diagram
• Battleships demo expanded significantly

Installation

Open Claude Code and say:

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

Or install manually — see the README for details.

v1.0.1

Nelson v1.0.1

Structural improvements to the skill — breaking monolithic reference docs into routed sub-files for faster, on-demand loading.

What's changed

• Routed standing orders: Each anti-pattern now lives in its own file under standing-orders/, loaded on demand via an index in standing-orders.md
• Routed admiralty templates: Individual template files under admiralty-templates/, replacing the single monolithic file
• Routed damage-control procedures: Individual procedure files under damage-control/, loaded via index routing
• Error recovery & risk decision tree: Added structured error recovery guidance and a risk-level decision tree
• Stale reference fixes: Cleaned up outdated cross-references and minor issues identified during review
• Battleships demo update: Minor improvements to the demo app

Installation

Open Claude Code and say:

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

Or install manually — see the README for details.

v1.0.0

Nelson v1.0.0

The first release of Nelson — a Claude Code skill for coordinating agent work using a Royal Navy operational framework.

What's included

• Six-step mission framework: Sailing Orders → Form the Squadron → Battle Plan → Quarterdeck Rhythm → Action Stations → Stand Down
• Three execution modes: single-session, subagents, and agent-team — automatically selected based on mission complexity
• Four risk tiers (Station 0–3): from low-blast-radius patrol tasks up to irreversible Trafalgar-level operations, each with escalating verification controls
• Structured templates: Sailing Orders, Battle Plan, Quarterdeck Report, Red-Cell Review, and Captain's Log
• Team composition model: Admiral, Captains, and optional Red-cell navigator, scaling from 1 to 10 agents
• OpenAI agent interface: YAML agent definition for interop
• Battleships demo: A vanilla HTML/CSS/JS demo app built using the skill

Installation

Open Claude Code and say:

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

Or install manually — see the README for details.

Requirements

• Claude Code CLI
• For agent teams: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings