Skip to content
Back to search

nelson-marketplace

MarketplaceWorks with Claude CodeGitHub

Organisation for Claude Code inspired by time-tested Royal Navy operating procedures.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aspegio-nelson/badge.svg)](/listings/aspegio-nelson)

HTML

<a href="/listings/aspegio-nelson"><img src="/api/listings/aspegio-nelson/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#prerequisites) for the full agent-team experience with split panes.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "nelson-marketplace",
  3. "owner": {
  4. "name": "Harry Munro"
  5. },
  6. "metadata": {
  7. "description": "Royal Navy agent coordination framework for Claude Code"
  8. },
  9. "plugins": [
  10. {
  11. "name": "nelson",
  12. "description": "Royal Navy agent coordination framework — sailing orders, battle plans, action stations, and a captain's log",
  13. "version": "2.4.0",
  14. "author": { "name": "Harry Munro" },
  15. "source": "./",
  16. "repository": "https://github.com/harrymunro/nelson",
  17. "license": "MIT",
  18. "keywords": ["agents", "coordination", "teams", "workflow"],
  19. "category": "workflow"
  20. }
  21. ]
  22. }
README.md · README · 625 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Nelson
  2. [![Version](https://img.shields.io/github/v/release/harrymunro/nelson)](https://github.com/harrymunro/nelson/releases)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  4. [![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-blueviolet)](https://docs.anthropic.com/en/docs/claude-code)
  5. [![Stars](https://img.shields.io/github/stars/harrymunro/nelson)](https://github.com/harrymunro/nelson/stargazers)
  6. **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.**
  7. <!-- markdownlint-disable-next-line MD036 -->
  8. *4 risk tiers · 11 damage control procedures · 11 mission templates · 7 crew roles · 16 standing orders*
  9. <p align="center">
  10. <img src="docs/images/1024px-Young_Nelson-min.jpg" alt="Captain Horatio Nelson" width="500">
  11. <br>
  12. <em>Captain Horatio Nelson — John Francis Rigaud, 1781. Image: Wikimedia Commons</em>
  13. </p>
  14. ## Contents
  15. - [Quick Start](#quick-start)
  16. - [What it does](#what-it-does)
  17. - [Why Nelson?](#why-nelson)
  18. - [How it works](#how-it-works)
  19. - [Prerequisites](#prerequisites)
  20. - [Installation](#installation)
  21. - [Usage](#usage)
  22. - [Customisation](#customisation)
  23. - [Plugin file structure](#plugin-file-structure)
  24. - [Mission artifacts](#mission-artifacts)
  25. - [Compatibility notes](#compatibility-notes)
  26. - [Star History](#star-history)
  27. - [Disclaimer](#disclaimer)
  28. - [License](#license)
  29. ## Quick Start
  30. Install the plugin:
  31. ```
  32. /plugin marketplace add harrymunro/nelson
  33. /plugin install nelson@nelson-marketplace
  34. ```
  35. Describe your mission — Nelson loads automatically, no slash command needed:
  36. ```
  37. Use Nelson to migrate the payment module from Stripe v2 to v3
  38. ```
  39. 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](#prerequisites) for the full agent-team experience with split panes.
  40. ## What it does
  41. https://github.com/user-attachments/assets/2468679d-39f5-4efb-9d93-43d43eee8907
  42. Nelson gives Claude an eight-step operational framework for tackling complex missions:
  43. 1. **Sailing Orders** — Define the outcome, success metric, constraints, and stop criteria
  44. 2. **The Estimate** — Conduct the 7 Question Maritime Tactical Estimate: reconnaissance, intent, effects, terrain, forces, coordination, and control
  45. 3. **Battle Plan** — Turn approved effects into task assignments with owners, dependencies, and file ownership
  46. 4. **Form the Squadron** — Choose an execution mode (single-session, subagents, agent team, workflow, or hybrid workflow) and size the team
  47. 5. **Get Permission to Sail** — Present the plan for user approval before committing resources
  48. 6. **Quarterdeck Rhythm** — Run checkpoints to track progress, identify blockers, monitor hull integrity, and manage budget
  49. 7. **Action Stations** — Classify tasks by risk tier and enforce verification before marking complete
  50. 8. **Stand Down** — Produce a captain's log with decisions, artifacts, validation evidence, and follow-ups
  51. ## Why Nelson?
  52. Most agent orchestration tools focus on starting missions. Nelson focuses on completing them safely.
  53. 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.
  54. - **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.
  55. - **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.
  56. - **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.
  57. Nelson coordinates its own development — recent releases have been planned and executed as Nelson missions.
  58. ### Who is this for?
  59. - You run Claude Code missions spanning multiple files or modules in parallel
  60. - You want structured checkpoints, risk classification, and a decision log
  61. - You've lost work to context exhaustion and want systematic handover procedures
  62. - You care about auditability — knowing what was decided, by which agent, and why
  63. It may be overkill if you're doing a quick, single-file edit.
  64. ### How Nelson compares
  65. Nelson trades upfront setup time for coordination guarantees:
  66. | Approach | Best when | Trade-off |
  67. |---|---|---|
  68. | Nelson Navy structure | You need repeatable quality gates, explicit ownership, and a clear decision log across parallel work | More setup and coordination overhead up front |
  69. | OmO/RuFlo-style rapid flow | You need the fastest possible movement on a narrow, low-risk path | Less formal checkpointing and role separation |
  70. If you need fast parallel execution with minimal ceremony, [OmO](https://github.com/code-yeongyu/oh-my-openagent) or [RuFlo](https://github.com/ruvnet/ruflo) may suit you better. If coordination, auditability, and safe scaling matter more than raw tempo, Nelson is the better fit.
  71. ## How it works
  72. ### Execution modes
  73. The skill selects one of five execution modes based on your mission:
  74. | Mode | When to use | How it works |
  75. |------|------------|--------------|
  76. | `single-session` | Sequential tasks, low complexity, heavy same-file editing | Claude works through tasks in order within one session |
  77. | `subagents` | Parallel tasks where workers only report back to the coordinator | Claude spawns [subagents](https://code.claude.com/docs/en/sub-agents) that work independently and return results |
  78. | `agent-team` | Parallel tasks where workers need to coordinate with each other | Claude creates an [agent team](https://code.claude.com/docs/en/agent-teams) with direct teammate-to-teammate communication |
  79. | `workflow` | Large fan-out audits, repeatable migrations, codebase-wide analysis, or cross-checked research | Nelson writes a Workflow Charter and verification contract for one approved [dynamic workflow](https://code.claude.com/docs/en/workflows) run |
  80. | `hybrid-workflow` | Workflow-suitable missions that need probes, Station 2/3 controls, or human approval between stages | Nelson gates a sequence of separate workflow runs, reviewing telemetry and outputs before the next stage |
  81. ### Dynamic workflows and ultracode
  82. 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.
  83. `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.
  84. ### Standing goals
  85. For long autonomous, headless, or scheduled runs, Nelson aligns with Claude Code's [`/goal`](https://code.claude.com/docs/en/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`.
  86. ### Chain of command
  87. 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.
  88. ```
  89. ┌───────────┐
  90. │ Admiral │
  91. └─────┬─────┘
  92. ┌─────────────┼─────────────┐
  93. ▼ ▼ ▼
  94. ┌───────────┐ ┌───────────┐ ┌───────────┐
  95. │ Captain │ │ Captain │ │ Red-Cell │
  96. │ HMS Daring │ │ HMS Kent │ │ Navigator │
  97. └─────┬─────┘ └─────┬─────┘ └───────────┘
  98. ┌────┼────┐ ┌────┼────┐
  99. ▼ ▼ ▼ ▼ ▼ ▼
  100. XO PWO MEO PWO NO COX
  101. ```
  102. **Squadron level:**
  103. - **Admiral** — Coordinates the mission, delegates tasks, resolves blockers. Coordinates final synthesis but does not perform it directly. There is always exactly one.
  104. - **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.
  105. - **Red-cell navigator** — Challenges assumptions, validates outputs, and checks rollback readiness. Added for medium/high risk work.
  106. **Ship level (crew per captain, 0-4 members):**
  107. | Role | Abbr | Function | When to crew |
  108. |------|------|----------|-------------|
  109. | Executive Officer | XO | Integration & orchestration | 3+ crew or interdependent sub-tasks |
  110. | Principal Warfare Officer | PWO | Core implementation | Almost always (default doer) |
  111. | Navigating Officer | NO | Codebase research & exploration | Unfamiliar code, large codebase |
  112. | Marine Engineering Officer | MEO | Testing & validation | Station 1+ or non-trivial verification |
  113. | Weapon Engineering Officer | WEO | Config, infrastructure & systems integration | Significant config/infra work |
  114. | Logistics Officer | LOGO | Documentation & dependency management | Docs as deliverable, dep management |
  115. | Coxswain | COX | Standards review & quality | Station 1+ with established conventions |
  116. Navigating Officer (NO) and Coxswain (COX) are read-only — they report findings but never modify files.
  117. 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.
  118. 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.
  119. ### Action stations (risk tiers)
  120. Every task is classified into a risk tier before execution. Higher tiers require more controls:
  121. | Station | Name | When | Required controls |
  122. |---------|------|------|-------------------|
  123. | 0 | Patrol | Low blast radius, easy rollback | Basic validation, rollback step |
  124. | 1 | Caution | User-visible changes, moderate impact | Independent review, negative test, rollback note |
  125. | 2 | Action | Security/compliance/data integrity implications | Red-cell review, failure-mode checklist, go/no-go checkpoint |
  126. | 3 | Trafalgar | Irreversible actions, regulated/safety-sensitive | Minimal scope, human confirmation, two-step verification, contingency plan |
  127. <img width="1024" height="559" alt="image" src="https://github.com/user-attachments/assets/2d0bf2ea-3f26-4751-9faa-71eca6be07b3" />
  128. Tasks at Station 1 and above also run a **failure-mode checklist**:
  129. - What could fail in production?
  130. - How would we detect it quickly?
  131. - What is the fastest safe rollback?
  132. - What dependency could invalidate this plan?
  133. - What assumption is least certain?
  134. ### Damage control
  135. 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.
  136. **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:
  137. | Status | Remaining | Action |
  138. |---|---|---|
  139. | Green | 75-100% | Operating normally |
  140. | Amber | 60-74% | Monitor closely, avoid new work |
  141. | Red | 40-59% | Relief on station — begin handover |
  142. | Critical | Below 40% | Immediate relief |
  143. 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.
  144. **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.
  145. **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.
  146. **Other procedures** cover the rest of the failure modes:
  147. - **Man overboard** — replace a stuck agent
  148. - **Partial rollback** — revert faulty work without aborting the mission
  149. - **Crew overrun** — recover from budget exhaustion
  150. - **Scuttle and reform** — abort and reform when the mission cannot succeed
  151. - **Comms failure** — recover from agent-team infrastructure failure
  152. - **Session resumption** — pick up after an interruption
  153. - **Session hygiene** — clean-start procedure for new sessions
  154. - **Escalation** — chain-of-command for issues beyond current authority
  155. ### Conflict radar
  156. 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:
  157. - **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.
  158. - **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.
  159. Both tools are stdlib-only and run as part of the mission workflow without additional setup.
  160. ### Enforcement hooks
  161. Nelson is not purely advisory. A set of Claude Code hooks (`hooks/nelson_hooks.py`) enforce structural guarantees at the tool level:
  162. | Event | Hook | What it enforces |
  163. |---|---|---|
  164. | `PreToolUse` on `Agent` | `preflight` | Station tier gate, file ownership conflicts, mode-tool consistency |
  165. | `PreToolUse` on `TaskCreate` | `session-check` | Captain TaskCreate gate (admiral exception via session marker) |
  166. | `PostToolUse` on `Write`/`Edit` | `brief-validate` | Turnover brief quality gate |
  167. | `TaskCompleted` | `task-complete` | Validation evidence and station controls |
  168. | `TeammateIdle` | `idle-ship` | Paid-off standing order advisory |
  169. | `SessionStart` | `session-init` | Records admiral `transcript_path` for the TaskCreate gate |
  170. 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](#installation) for manual-install caveats.
  171. ### Cross-mission intelligence
  172. 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:
  173. - **`brief`** — pre-mission intelligence brief: relevant patterns, win rate, standing order hot spots, and context-matched precedents drawn from prior missions.
  174. - **`analytics`** — focused metric queries (`success-rate`, `standing-orders`, `efficiency`) with text or JSON output.
  175. - **`history`** / **`index`** — review and rebuild the fleet intelligence index across past missions.
  176. - **`stand-down --adopt/--avoid`** — capture reusable patterns at mission close so the next run benefits.
  177. Running `index` backfills the memory store for missions completed before the feature existed, so upgrading is non-destructive.
  178. ### Admiral synthesis
  179. 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.
  180. ### Templates
  181. Nelson ships eleven structured templates to keep outputs consistent across missions:
  182. | Template | Used for |
  183. |---|---|
  184. | **Sailing Orders** | Mission definition: outcome, constraints, scope, stop criteria |
  185. | **Estimate** | Seven-question analytical scaffold (reconnaissance, intent, effects, terrain, forces, coordination, control) between Sailing Orders and Battle Plan |
  186. | **Battle Plan** | Task breakdown with owners, dependencies, threat tiers, validation requirements |
  187. | **Ship Manifest** | Captain's crew plan: ship name, crew roles, sub-tasks, budget |
  188. | **Crew Briefing** | Per-captain deployment brief: mission context, role, ship, acceptance criteria |
  189. | **Marine Deployment Brief** | Detachment briefing for Royal Marines (recce, assault, sapper) |
  190. | **Quarterdeck Report** | Checkpoint status: progress, blockers, budget tracking, risk updates |
  191. | **Damage Report** | JSON format for hull integrity reporting with token counts and status |
  192. | **Turnover Brief** | Handover for relief on station: progress log, running plot, relief chain |
  193. | **Red-Cell Review** | Adversarial review: challenge summary, checks, recommendation |
  194. | **Captain's Log** | Final report: delivered artifacts, decisions, validation evidence, follow-ups |
  195. <img width="1024" height="559" alt="image" src="https://github.com/user-attachments/assets/5955341c-a251-4e05-b0ed-61f424181201" />
  196. ## Prerequisites
  197. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated
  198. - **Recommended:** Enable [agent teams](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/settings):
  199. ```json
  200. {
  201. "env": {
  202. "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  203. }
  204. }
  205. ```
  206. - **For split-pane visibility:** To see each agent working in its own pane (as shown in the demo video), run Claude Code inside [tmux](https://github.com/tmux/tmux/wiki). Agent teams auto-detect tmux and give every teammate a dedicated split pane so you can watch the whole squadron in action.
  207. ## Installation
  208. ### Plugin install (recommended)
  209. Add the marketplace and install:
  210. ```
  211. /plugin marketplace add harrymunro/nelson
  212. /plugin install nelson@nelson-marketplace
  213. ```
  214. <details>
  215. <summary>Prompt-based install</summary>
  216. Open Claude Code and say:
  217. ```
  218. Install skills from https://github.com/harrymunro/nelson
  219. ```
  220. Claude will clone the repo, copy the skill into your project's `.claude/skills/` directory, and clean up. To install it globally across all projects, ask Claude to install it to `~/.claude/skills/` instead.
  221. </details>
  222. <details>
  223. <summary>Manual install</summary>
  224. Clone the repo and copy the skill directory yourself:
  225. ```bash
  226. # Project-level (recommended for teams)
  227. git clone https://github.com/harrymunro/nelson.git /tmp/nelson
  228. mkdir -p .claude/skills
  229. cp -r /tmp/nelson/skills/nelson .claude/skills/nelson
  230. rm -rf /tmp/nelson
  231. # Or user-level (personal, all projects)
  232. cp -r /tmp/nelson/skills/nelson ~/.claude/skills/nelson
  233. ```
  234. Then commit `.claude/skills/nelson/` to version control so your team can use it.
  235. > **Heads up:** the manual path installs the skill only. Nelson's [enforcement hooks](#enforcement-hooks) and the bundled `settings.json` (which enables agent teams) are wired up automatically by the plugin system via `${CLAUDE_PLUGIN_ROOT}` and are **not** picked up by a skill-only copy. If you rely on the station-tier gate, file ownership checks, or turnover brief validation, use the plugin install above. To enable agent teams with a manual install, add the env var from [Prerequisites](#prerequisites) to your own `settings.json`.
  236. </details>
  237. <details>
  238. <summary>Updating</summary>
  239. For plugin installs, run `/plugin` and either enable auto-updates on `nelson-marketplace` or trigger an update from the marketplace menu. From the command line:
  240. ```
  241. /plugin marketplace update nelson-marketplace
  242. /plugin install nelson@nelson-marketplace
  243. ```
  244. If updates aren't taking effect, remove and re-add the marketplace. For manual installs, delete `skills/nelson/` and repeat the manual install.
  245. </details>
  246. <details>
  247. <summary>Verify installation</summary>
  248. Open Claude Code and ask:
  249. ```
  250. What skills are available?
  251. ```
  252. You should see `nelson` listed. You can also test it by saying "Use Nelson to..." followed by a task.
  253. </details>
  254. <details>
  255. <summary>Installation for Cursor (Experimental)</summary>
  256. If you have a Team Marketplace in Cursor, you can add Nelson there. See [Add a team marketplace](https://cursor.com/docs/plugins#add-a-team-marketplace) in the Cursor documentation. The required GitHub repository URL is `https://github.com/harrymunro/nelson.git`. Once the marketplace is installed, you can install Nelson from it.
  257. If you do not have access to a Team Marketplace, you can install locally on Linux and macOS:
  258. ```bash
  259. cd ~/.cursor/plugins/local
  260. git clone -b main --depth 1 https://github.com/harrymunro/nelson.git
  261. ```
  262. To update the plugin after that:
  263. ```bash
  264. cd ~/.cursor/plugins/local/nelson
  265. git pull
  266. ```
  267. </details>
  268. ## Usage
  269. Nelson is a Claude Code skill — it loads automatically when your request matches. No slash command required. Just describe your mission and mention Nelson.
  270. ### Let Nelson pick the execution mode
  271. Nelson selects the best execution mode (single-session, subagents, agent team, workflow, or hybrid workflow) based on your mission:
  272. ```
  273. Use Nelson to migrate the payment processing module from Stripe v2 to v3
  274. ```
  275. ### Force an agent team
  276. If you want teammate-to-teammate coordination, ask for an agent team explicitly:
  277. ```
  278. Use an agent team with Nelson to refactor the authentication system across
  279. the API layer, frontend, and test suite
  280. ```
  281. ### Go maximal
  282. For the highest-capability run — Opus 4.7 agents, fully crewed ships, maximum coordination:
  283. ```
  284. Use an agent team with Nelson and Opus 4.7 agents with fully crewed ships
  285. to deliver the new billing integration
  286. ```
  287. ### Full sailing orders
  288. For maximum control, provide your own sailing orders:
  289. ```
  290. Use Nelson to deliver this:
  291. Sailing orders:
  292. - Outcome: All API endpoints return consistent error responses
  293. - Success metric: Zero test failures, all error responses match the schema
  294. - Deadline: This session
  295. Constraints:
  296. - Token/time budget: Stay under 50k tokens
  297. - Forbidden actions: Do not modify the database schema
  298. Scope:
  299. - In scope: src/api/ and tests/api/
  300. - Out of scope: Frontend error handling
  301. ```
  302. You can also invoke it directly with the `/nelson` slash command if you prefer.
  303. ## Customisation
  304. 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.
  305. ## Plugin file structure
  306. ```
  307. .claude-plugin/ # Plugin + marketplace manifests
  308. settings.json # Default settings (enables agent teams)
  309. hooks/ # Enforcement hooks (auto-discovered by plugin)
  310. skills/nelson/
  311. ├── SKILL.md # Main skill instructions (entrypoint)
  312. ├── references/ # Supporting docs loaded on demand
  313. │ ├── action-stations.md # Risk tier definitions
  314. │ ├── admiralty-templates/ # 11 structured templates
  315. │ ├── crew-roles.md # Crew role definitions & ship names
  316. │ ├── damage-control/ # 11 recovery procedures
  317. │ ├── goal-alignment.md # Claude Code /goal (standing goal) doctrine
  318. │ ├── standing-orders/ # 16 anti-pattern guards
  319. │ ├── the-estimate.md # 7 Question Maritime Tactical Estimate reference
  320. │ ├── squadron-composition.md # Mode selection & team sizing
  321. │ └── workflow-doctrine.md # Dynamic workflow & ultracode doctrine
  322. └── scripts/ # nelson-data.py, conflict scan, circuit breakers, tests
  323. ```
  324. <details>
  325. <summary>Full file tree</summary>
  326. ```
  327. .claude-plugin/
  328. ├── plugin.json # Plugin manifest
  329. └── marketplace.json # Marketplace definition (self-hosted)
  330. settings.json # Plugin default settings (enables agent teams)
  331. hooks/
  332. ├── hooks.json # Skill-scoped hook configuration (auto-discovered)
  333. ├── nelson_hooks.py # Hook enforcement script (preflight, brief, task, idle)
  334. └── test_nelson_hooks.py # Tests for hook handlers
  335. skills/nelson/
  336. ├── SKILL.md # Main skill instructions (entrypoint)
  337. ├── references/
  338. │ ├── action-stations.md # Risk tier definitions and controls
  339. │ ├── admiralty-templates/ # Individual template files
  340. │ │ ├── battle-plan.md
  341. │ │ ├── captains-log.md
  342. │ │ ├── crew-briefing.md
  343. │ │ ├── damage-report.md
  344. │ │ ├── estimate.md
  345. │ │ ├── marine-deployment-brief.md
  346. │ │ ├── quarterdeck-report.md
  347. │ │ ├── red-cell-review.md
  348. │ │ ├── sailing-orders.md
  349. │ │ ├── ship-manifest.md
  350. │ │ └── turnover-brief.md
  351. │ ├── commendations.md # Recognition signals and correction guidance
  352. │ ├── crew-roles.md # Crew role definitions, ship names, sizing
  353. │ ├── goal-alignment.md # Claude Code /goal (standing goal) doctrine
  354. │ ├── damage-control/ # Individual procedure files
  355. │ │ ├── circuit-breakers.md
  356. │ │ ├── comms-failure.md
  357. │ │ ├── crew-overrun.md
  358. │ │ ├── escalation.md
  359. │ │ ├── hull-integrity.md
  360. │ │ ├── man-overboard.md
  361. │ │ ├── partial-rollback.md
  362. │ │ ├── relief-on-station.md
  363. │ │ ├── scuttle-and-reform.md
  364. │ │ ├── session-hygiene.md
  365. │ │ └── session-resumption.md
  366. │ ├── model-selection.md # Cost-optimized model assignment for agents
  367. │ ├── royal-marines.md # Royal Marines deployment rules
  368. │ ├── squadron-composition.md # Mode selection and team sizing rules
  369. │ ├── structured-data.md # Structured fleet data capture reference
  370. │ ├── the-estimate.md # 7 Question Maritime Tactical Estimate reference
  371. │ ├── tool-mapping.md # Nelson-to-Claude Code tool reference
  372. │ ├── workflow-doctrine.md # Dynamic workflow and ultracode doctrine
  373. │ └── standing-orders/ # Individual anti-pattern files
  374. │ ├── admiral-at-the-helm.md
  375. │ ├── all-hands-on-deck.md
  376. │ ├── awaiting-admiralty.md
  377. │ ├── battalion-ashore.md
  378. │ ├── becalmed-fleet.md
  379. │ ├── captain-at-the-capstan.md
  380. │ ├── crew-without-canvas.md
  381. │ ├── drifting-anchorage.md
  382. │ ├── light-squadron.md
  383. │ ├── paid-off.md
  384. │ ├── press-ganged-navigator.md
  385. │ ├── pressed-crew.md
  386. │ ├── skeleton-crew.md
  387. │ ├── split-keel.md
  388. │ ├── unclassified-engagement.md
  389. │ └── wrong-ensign.md
  390. └── scripts/ # Distributed with the skill (since v1.9.1)
  391. ├── nelson-data.py # CLI entry point for structured data capture
  392. ├── nelson_data_utils.py # Shared I/O, validation, constants
  393. ├── nelson_data_memory.py # Cross-mission memory store (v2.0.0)
  394. ├── nelson_data_lifecycle.py # Mission lifecycle commands
  395. ├── nelson_data_goal.py # Composes a Claude Code /goal condition
  396. ├── nelson_data_fleet.py # Fleet intelligence & analytics
  397. ├── nelson_conflict_scan.py # Pre-flight split-keel scanner
  398. ├── nelson_conflict_radar.py # Runtime file-conflict monitor
  399. ├── nelson_circuit_breakers.py # Automated budget/hull/idle alarms
  400. ├── nelson-phase.py # Deterministic phase engine
  401. └── test_*.py # Test suite (pytest)
  402. agents/
  403. └── nelson.md # Agent definition with skill binding
  404. scripts/
  405. ├── check-references.sh # Cross-reference validation for documentation links
  406. └── count-tokens.py # Token counter for hull integrity monitoring
  407. ```
  408. </details>
  409. `SKILL.md` is the entrypoint Claude reads when the skill is invoked; files in `references/` are loaded on demand rather than all at once. Hooks and scripts under `skills/nelson/scripts/` are wired up automatically by the plugin system via `${CLAUDE_PLUGIN_ROOT}` and ship with the skill on install.
  410. ## Mission artifacts
  411. Each mission creates a timestamped directory for its runtime artifacts. Previous missions are preserved — each run gets its own directory. The `SESSION_ID` suffix is an 8-character hex string generated at session start via `uuidgen`, ensuring **concurrent Nelson sessions** in the same repository create distinct directories.
  412. Nelson writes two kinds of artifacts side by side: **prose** for humans (captain's log, quarterdeck report, turnover briefs) and **structured JSON** for machines (session resumption, hooks, analytics). The JSON files are produced by `nelson-data.py` subcommands called at each workflow step.
  413. <details>
  414. <summary>Artifact directory structure</summary>
  415. ```
  416. .nelson/
  417. ├── missions/{YYYY-MM-DD_HHMMSS}_{SESSION_ID}/
  418. │ ├── captains-log.md — Written at stand-down
  419. │ ├── quarterdeck-report.md — Updated at every checkpoint
  420. │ ├── damage-reports/ — Ship damage reports (JSON)
  421. │ ├── turnover-briefs/ — Ship turnover briefs (markdown)
  422. │ ├── sailing-orders.json — Mission definition (init)
  423. │ ├── battle-plan.json — Tasks, owners, file ownership (plan-approved)
  424. │ ├── mission-log.json — Event stream (events, handoffs, checkpoints)
  425. │ ├── fleet-status.json — Current squadron state (live)
  426. │ └── stand-down.json — Final outcome, decisions, adopted/avoided patterns
  427. └── memory/ — Cross-mission memory store (v2.0.0)
  428. ├── patterns.json — Accumulated adopt/avoid pattern library
  429. └── standing-order-stats.json — Violation frequency & correlations
  430. ```
  431. </details>
  432. ## Compatibility notes
  433. ### Platform support
  434. Nelson is built around **Claude Code orchestration primitives** — shared task lists, peer messaging between agents, subagents, and dynamic workflows. These are the foundation of Nelson's squadron model: captains coordinating in parallel, the admiral running quarterdeck checkpoints, and damage control procedures that keep modern Claude Code orchestration auditable.
  435. | Platform | Status | Notes |
  436. |----------|--------|-------|
  437. | **Claude Code** | Supported | Full support for all five execution modes (single-session, subagents, agent-team, workflow, hybrid-workflow) |
  438. | **Cursor** | Experimental | See installation instructions above |
  439. | **Codex CLI** | Not yet supported | Lacks agent-team primitives. [Agents SDK](https://openai.github.io/openai-agents-python/) orchestration may provide a path — monitoring |
  440. | **OpenCode** | Not yet supported | Agent-team feature exists on dev branch but has not reached stable release |
  441. | **Gemini CLI** | Not yet supported | No multi-agent coordination primitives. Subagent support is single-level only |
  442. **Why not degrade gracefully?** Nelson's value is the coordination layer — quarterdeck rhythm, peer messaging, shared task lists, damage control, crew hierarchy. On a platform without agent teams, Nelson would degrade to "subagents with Royal Navy naming", which doesn't justify the complexity. When these platforms add agent-team support, Nelson will follow.
  443. We are actively tracking multi-agent developments across these platforms. If you're interested in helping bring Nelson to a new platform, [open an issue](https://github.com/harrymunro/nelson/issues).
  444. ### Claude Code specifics
  445. - **Subagents** are a stable Claude Code feature and work out of the box.
  446. - **Agent teams** are experimental and disabled by default. See [Prerequisites](#prerequisites) above for setup. Without agent teams enabled, Nelson falls back to `single-session` or `subagents` mode. Full details: [Agent teams documentation](https://code.claude.com/docs/en/agent-teams).
  447. ## Star History
  448. <a href="https://star-history.com/#harrymunro/nelson&Date">
  449. <picture>
  450. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=harrymunro/nelson&type=Date&theme=dark" />
  451. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=harrymunro/nelson&type=Date" />
  452. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=harrymunro/nelson&type=Date" width="600" />
  453. </picture>
  454. </a>
  455. ### How the star prompt works
  456. On a successful Stand Down, Nelson asks once whether you'd like to star the repo on GitHub. The answer is recorded in `~/.nelson/prefs.json` (`{"star_asked": true}`) and the prompt never repeats — across all your Nelson projects. To skip permanently without seeing the prompt: `mkdir -p ~/.nelson && echo '{"star_asked": true}' > ~/.nelson/prefs.json`.
  457. ## Disclaimer
  458. This project is not associated with, endorsed by, or affiliated with the British Royal Navy or the UK Ministry of Defence. All Royal Navy terminology and references are used purely as a creative framework for organising software development tasks.
  459. ## License
  460. MIT — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.