diff --git a/CLAUDE.md b/CLAUDE.md index e339fa9..a61a2bd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,6 +8,7 @@ Nelson is a Claude Code skill for coordinating agent work using Royal Navy termi .claude-plugin/ plugin.json — Plugin manifest marketplace.json — Marketplace definition (self-hosted) +settings.json — Plugin default settings (enables agent teams) skills/nelson/ SKILL.md — Main entrypoint (what Claude reads) references/ — Supporting docs loaded on demand @@ -23,6 +24,7 @@ skills/nelson/ session-hygiene.md — Clean start procedure for new sessions royal-marines.md — Royal Marines deployment rules & specialisations squadron-composition.md — Mode selection & team sizing rules + tool-mapping.md — Nelson-to-Claude Code tool reference standing-orders/ — One file per anti-pattern, loaded on demand agents/ — Agent interface definitions demos/ — Example applications built with Nelson diff --git a/README.md b/README.md index 9a5ddbc..f2e1e14 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Nelson gives Claude a six-step operational framework for tackling complex missio ## Prerequisites - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated -- **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. Enable it in your [settings.json](https://code.claude.com/docs/en/settings): +- **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): ```json { @@ -258,6 +258,7 @@ The skill includes structured templates for consistent output across missions: .claude-plugin/ ├── plugin.json # Plugin manifest └── marketplace.json # Marketplace definition (self-hosted) +settings.json # Plugin default settings (enables agent teams) skills/nelson/ ├── SKILL.md # Main skill instructions (entrypoint) └── references/ @@ -287,6 +288,7 @@ skills/nelson/ │ └── session-resumption.md ├── royal-marines.md # Royal Marines deployment rules ├── squadron-composition.md # Mode selection and team sizing rules + ├── tool-mapping.md # Nelson-to-Claude Code tool reference └── standing-orders/ # Individual anti-pattern files ├── admiral-at-the-helm.md ├── all-hands-on-deck.md @@ -301,7 +303,7 @@ skills/nelson/ ├── split-keel.md └── unclassified-engagement.md agents/ -└── nelson.md # Subagent definition +└── nelson.md # Agent definition with skill binding scripts/ └── count-tokens.py # Token counter for hull integrity monitoring ``` diff --git a/agents/nelson.md b/agents/nelson.md index e8de53d..dab1744 100644 --- a/agents/nelson.md +++ b/agents/nelson.md @@ -1,8 +1,12 @@ --- name: nelson description: Coordinates multi-agent work using Royal Navy squadron patterns with sailing orders, risk-tiered quality gates, and a captain's log. +skills: + - nelson --- # Nelson -Use /nelson to run a Royal Navy agent mission with sailing orders, action stations, and a captain's log. +Royal Navy agent coordinator. Use `/nelson` to run a mission with sailing orders, action stations, and a captain's log. + +This agent configures the nelson skill as its primary capability. For direct invocation, use the `/nelson` slash command instead. diff --git a/settings.json b/settings.json new file mode 100644 index 0000000..b360c69 --- /dev/null +++ b/settings.json @@ -0,0 +1,5 @@ +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} diff --git a/skills/nelson/SKILL.md b/skills/nelson/SKILL.md index 124a70c..db9ba16 100644 --- a/skills/nelson/SKILL.md +++ b/skills/nelson/SKILL.md @@ -53,7 +53,7 @@ You MUST consult the Standing Orders table below when assigning files or if scop **Before proceeding to Step 4:** Verify sailing orders exist, squadron is formed, and every task has an owner, deliverable, and action station tier. -**Crew Briefing:** When spawning each teammate via `Task()`, you MUST include a crew briefing using the template from `references/admiralty-templates/crew-briefing.md`. Teammates do NOT inherit the lead's conversation context — they start with a clean slate and need explicit mission context to operate independently. +**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 create and assign work with `TaskCreate` + `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. **Turnover Briefs:** When a ship is relieved due to context exhaustion, it writes a turnover brief using `references/admiralty-templates/turnover-brief.md`. See `references/damage-control/relief-on-station.md` for the full procedure. @@ -61,9 +61,10 @@ You MUST consult the Standing Orders table below when assigning files or if scop - 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. -- Run checkpoints at fixed cadence (for example every 15-30 minutes): -- Update progress by task state: `pending`, `in_progress`, `completed`. +- Run a quarterdeck checkpoint after every 2-3 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`. - 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. - Track burn against token/time budget. @@ -71,6 +72,7 @@ You MUST consult the Standing Orders table below when assigning files or if scop - Re-scope early when a task drifts from mission metric. - When a mission encounters difficulties, you MUST consult the Damage Control table below for recovery and escalation procedures. +See `references/tool-mapping.md` for the full set of coordination tools. You MUST use `references/admiralty-templates/quarterdeck-report.md` for the quarterdeck report template. You MUST use `references/admiralty-templates/damage-report.md` for damage report format. You MUST consult the Standing Orders table below if admiral is doing implementation or tasks are drifting from scope. diff --git a/skills/nelson/references/action-stations.md b/skills/nelson/references/action-stations.md index 7eb0bf1..994a856 100644 --- a/skills/nelson/references/action-stations.md +++ b/skills/nelson/references/action-stations.md @@ -111,3 +111,38 @@ 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. + +Example hook configuration in `.claude/settings.json`: + +```json +{ + "hooks": { + "TaskCompleted": [ + { + "hooks": [ + { + "type": "command", + "command": "echo 'Verify: validation evidence present, rollback note included, station tier controls satisfied'" + } + ] + } + ] + } +} +``` + +This is an opt-in enhancement. Quality gates work without hooks via the admiral's quarterdeck checkpoint and red-cell review process. diff --git a/skills/nelson/references/admiralty-templates/crew-briefing.md b/skills/nelson/references/admiralty-templates/crew-briefing.md index 2eafbd5..5a9a0b4 100644 --- a/skills/nelson/references/admiralty-templates/crew-briefing.md +++ b/skills/nelson/references/admiralty-templates/crew-briefing.md @@ -1,6 +1,6 @@ # Crew Briefing Template -When spawning each teammate via `Task()`, 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. +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. @@ -21,13 +21,13 @@ Standing Orders: - Report blockers to admiral immediately with options and one recommendation - When done, report: deliverable, validation evidence, failure modes, rollback note - You may deploy Royal Marines (short-lived sub-agents) for focused sorties. - Deploy by calling the Task tool directly (NOT via bash/CLI — use the built-in Task tool). - Recce Marine: Task tool with subagent_type="Explore" (read-only recon). - Assault Marine / Sapper: Task tool with subagent_type="general-purpose". - Include a deployment brief in the Task prompt (template below). + 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. -Marine Deployment Brief (include in marine's Task prompt): +Marine Deployment Brief (include in marine's Agent prompt): == MARINE DEPLOYMENT BRIEF == Ship: [your ship name] Detachment: [Recce Marine / Assault Marine / Sapper] diff --git a/skills/nelson/references/admiralty-templates/damage-report.md b/skills/nelson/references/admiralty-templates/damage-report.md index 2264044..5b6f4fc 100644 --- a/skills/nelson/references/admiralty-templates/damage-report.md +++ b/skills/nelson/references/admiralty-templates/damage-report.md @@ -47,3 +47,11 @@ File a damage report to communicate context window usage to the admiral. Store e - 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 `.claude/nelson/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`. diff --git a/skills/nelson/references/damage-control/hull-integrity.md b/skills/nelson/references/damage-control/hull-integrity.md index a14c7a5..f38dbb6 100644 --- a/skills/nelson/references/damage-control/hull-integrity.md +++ b/skills/nelson/references/damage-control/hull-integrity.md @@ -65,3 +65,28 @@ Hull integrity monitoring works alongside existing damage control procedures: - **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. + +## Advanced: TeammateIdle Hook + +An optional `TeammateIdle` hook can trigger an automatic hull integrity check when a captain goes idle unexpectedly. This supplements the quarterdeck checkpoint rhythm with event-driven monitoring. + +Example hook configuration in `.claude/settings.json`: + +```json +{ + "hooks": { + "TeammateIdle": [ + { + "hooks": [ + { + "type": "command", + "command": "echo 'Captain idle — check hull integrity and task status'" + } + ] + } + ] + } +} +``` + +This is an opt-in enhancement. Hull integrity monitoring works without hooks via the quarterdeck checkpoint rhythm. diff --git a/skills/nelson/references/squadron-composition.md b/skills/nelson/references/squadron-composition.md index 510306c..9f930bd 100644 --- a/skills/nelson/references/squadron-composition.md +++ b/skills/nelson/references/squadron-composition.md @@ -38,3 +38,15 @@ Choose the first condition that matches. ## 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. diff --git a/skills/nelson/references/tool-mapping.md b/skills/nelson/references/tool-mapping.md new file mode 100644 index 0000000..cd11bb4 --- /dev/null +++ b/skills/nelson/references/tool-mapping.md @@ -0,0 +1,27 @@ +# Tool Mapping Reference + +Maps Nelson operations to Claude Code tool calls by execution mode. + +## Tool Reference + +| Nelson Operation | Claude Code Tool | Mode | +|---|---|---| +| Form the squadron | `TeamCreate` | agent-team | +| Spawn captain | `Agent` with `team_name` + `name` | agent-team | +| Spawn captain | `Agent` with `subagent_type` | subagents | +| Create task | `TaskCreate` | agent-team | +| Assign task to captain | `TaskUpdate` with `owner` | agent-team | +| Check task progress | `TaskList` / `TaskGet` | agent-team | +| Message a captain | `SendMessage(type="message")` | agent-team | +| Broadcast to squadron | `SendMessage(type="broadcast")` | agent-team | +| Shut down a ship | `SendMessage(type="shutdown_request")` | agent-team / subagents | +| Respond to shutdown | `SendMessage(type="shutdown_response")` | agent-team | +| Deploy Royal Marine | `Agent` with `subagent_type` | all modes | +| Approve captain's plan | `SendMessage(type="plan_approval_response")` | agent-team | +| Stand down squadron | `TeamDelete` | agent-team | + +## Mode Differences + +- **`subagents` mode:** No shared task list. The admiral tracks state directly and captains report only to the admiral. Use the `Agent` tool to spawn captains. +- **`agent-team` mode:** The task list (`TaskCreate`, `TaskList`, `TaskGet`, `TaskUpdate`) is the shared coordination surface. Captains can message each other via `SendMessage`. Use `TeamCreate` first, then spawn captains with the `Agent` tool using `team_name` and `name` parameters. +- **`single-session` mode:** No spawning. The admiral executes all work directly.