Align instructions with Claude Code agent teams API

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

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

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.

settings.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}

skills/nelson/SKILL.md

@@ -53,24 +53,26 @@ 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.
 
 ## 4. Run Quarterdeck Rhythm
 
 - 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.
 - 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.
 - 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.

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.

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]

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

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.

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.

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.