claude-code-swarm 0.0.1 → 0.3.3

package/docs/implementation-plan.md

@@ -0,0 +1,635 @@
+# Implementation Plan
+
+Concrete implementation steps for the MAP + sessionlog integration, based on `docs/design.md`.
+
+## Current state
+
+```
+hooks/hooks.json              ← SessionStart: inline shell command (~1 long line)
+settings.json                 ← env: AGENT_TEAMS=1, permissions: openteams/npm
+scripts/team-loader.sh        ← Used by /swarm skill, NOT by the SessionStart hook
+scripts/generate-agents.mjs   ← Templates → AGENT.md (includes openteams messaging)
+skills/swarm/SKILL.md          ← /swarm skill definition
+.claude-plugin/plugin.json     ← Plugin manifest v0.1.0
+```
+
+Key observation: the current `SessionStart` hook and `team-loader.sh` are separate code paths. The hook is a minimal inline check; `team-loader.sh` does the actual generation and is invoked by the `/swarm` skill. This separation is intentional — the hook just announces the plugin, while `/swarm` does the heavy lifting.
+
+We keep this separation. The new `bootstrap.sh` replaces the inline hook command but stays lightweight (config check, status reporting, sidecar launch). It does NOT generate agents or load teams — that's still `/swarm`'s job.
+
+---
+
+## Phase 1: Foundation
+
+**Goal:** Replace inline hook with `bootstrap.sh`, add new hook events, update config/permissions.
+
+### 1.1 Create `scripts/bootstrap.sh`
+
+The unified `SessionStart` entry point. Replaces the inline command in `hooks/hooks.json`.
+
+```bash
+#!/usr/bin/env bash
+# bootstrap.sh — SessionStart hook for claude-code-swarm
+# Reads .claude-swarm.json, checks integrations, starts MAP sidecar if configured.
+# Output goes to stdout → injected into Claude's context.
+
+set -euo pipefail
+
+PLUGIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG_FILE=".claude-swarm.json"
+
+# ── 1. Read config ───────────────────────────────────────────────────────────
+TMPL=""
+MAP_ENABLED="false"
+MAP_SERVER=""
+MAP_SCOPE=""
+MAP_SYSTEM_ID=""
+MAP_SIDECAR="session"
+SESSIONLOG_ENABLED="false"
+
+if [ -f "$CONFIG_FILE" ]; then
+  eval "$(node -e "
+    const c = JSON.parse(require('fs').readFileSync('$CONFIG_FILE', 'utf-8'));
+    console.log('TMPL=' + JSON.stringify(c.template || ''));
+    console.log('MAP_ENABLED=' + JSON.stringify(String(c.map?.enabled || false)));
+    console.log('MAP_SERVER=' + JSON.stringify(c.map?.server || 'ws://localhost:8080'));
+    console.log('MAP_SCOPE=' + JSON.stringify(c.map?.scope || ''));
+    console.log('MAP_SYSTEM_ID=' + JSON.stringify(c.map?.systemId || 'system-claude-swarm'));
+    console.log('MAP_SIDECAR=' + JSON.stringify(c.map?.sidecar || 'session'));
+    console.log('SESSIONLOG_ENABLED=' + JSON.stringify(String(c.sessionlog?.enabled || false)));
+  " 2>/dev/null)"
+fi
+
+# Auto-derive scope from template name if not set
+if [ -n "$TMPL" ] && [ -z "$MAP_SCOPE" ]; then
+  MAP_SCOPE="swarm:$TMPL"
+fi
+
+# ── 2. Ensure openteams is available ─────────────────────────────────────────
+if ! command -v openteams &>/dev/null; then
+  echo "Installing openteams..." >&2
+  npm install -g openteams 2>&1 >&2 || true
+fi
+
+# ── 3. Check sessionlog status ───────────────────────────────────────────────
+SESSIONLOG_STATUS="not installed"
+if command -v sessionlog &>/dev/null; then
+  if sessionlog status --json 2>/dev/null | node -e "
+    const s = JSON.parse(require('fs').readFileSync('/dev/stdin','utf-8'));
+    process.exit(s.enabled ? 0 : 1);
+  " 2>/dev/null; then
+    SESSIONLOG_STATUS="active"
+  else
+    SESSIONLOG_STATUS="installed but not enabled"
+  fi
+fi
+
+# ── 4. Start MAP sidecar if configured ───────────────────────────────────────
+MAP_STATUS="disabled"
+if [ "$MAP_ENABLED" = "true" ]; then
+  # Ensure MAP SDK is available
+  if ! node -e "require('@multi-agent-protocol/sdk')" 2>/dev/null; then
+    echo "Installing @multi-agent-protocol/sdk..." >&2
+    npm install -g @multi-agent-protocol/sdk 2>&1 >&2 || true
+  fi
+
+  mkdir -p .generated/map
+
+  if [ "$MAP_SIDECAR" = "session" ]; then
+    # Start sidecar as background process
+    node "$PLUGIN_DIR/scripts/map-sidecar.mjs" \
+      --server "$MAP_SERVER" \
+      --scope "$MAP_SCOPE" \
+      --system-id "$MAP_SYSTEM_ID" \
+      --roles-file ".generated/map/roles.json" \
+      &>/dev/null &
+    echo $! > .generated/map/sidecar.pid
+    MAP_STATUS="connected (scope: $MAP_SCOPE)"
+  elif [ "$MAP_SIDECAR" = "persistent" ]; then
+    # Check if persistent sidecar is running
+    if [ -S .generated/map/sidecar.sock ]; then
+      MAP_STATUS="connected via persistent sidecar (scope: $MAP_SCOPE)"
+    else
+      MAP_STATUS="WARNING: persistent sidecar not running"
+    fi
+  fi
+fi
+
+# ── 5. Output context ────────────────────────────────────────────────────────
+echo "## Claude Code Swarm (openteams)"
+echo ""
+
+if [ -n "$TMPL" ]; then
+  echo "Team template configured: **$TMPL**"
+else
+  echo "No team template configured."
+fi
+
+echo "MAP: $MAP_STATUS"
+
+if [ "$SESSIONLOG_ENABLED" = "true" ]; then
+  if [ "$SESSIONLOG_STATUS" = "active" ]; then
+    echo "Sessionlog: active"
+  else
+    echo "Sessionlog: WARNING — configured but $SESSIONLOG_STATUS"
+  fi
+fi
+
+echo ""
+echo "Use \`/swarm\` to launch the team, or \`/swarm <template>\` for a specific template."
+echo "Built-in templates: **get-shit-done**, **bmad-method**"
+```
+
+### 1.2 Update `hooks/hooks.json`
+
+Replace inline command with `bootstrap.sh`. Add hooks for MAP events.
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$(dirname \"$0\")/../scripts/bootstrap.sh\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(dirname \"$0\")/../scripts/map-hook.mjs\" inject"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(dirname \"$0\")/../scripts/map-hook.mjs\" agent-spawning"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(dirname \"$0\")/../scripts/map-hook.mjs\" agent-completed"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(dirname \"$0\")/../scripts/map-hook.mjs\" turn-completed"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Note on path resolution:** `$(dirname "$0")` refers to the hooks directory in Claude Code plugin hooks. Need to verify this works — may need to use an absolute path via `PLUGIN_DIR` env var set in `settings.json`, or have `bootstrap.sh` set it.
+
+**Alternative:** Set `CLAUDE_CODE_SWARM_DIR` in `settings.json` env and reference that.
+
+### 1.3 Update `settings.json`
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(openteams *)",
+      "Bash(npm install -g openteams)",
+      "Bash(npm install -g @multi-agent-protocol/sdk)",
+      "Bash(npm install -g sessionlog)",
+      "Bash(node *)"
+    ]
+  }
+}
+```
+
+### 1.4 Update `.gitignore`
+
+```
+.generated/
+node_modules/
+agents/
+```
+
+Already correct — `.generated/` covers MAP inbox/pid/socket files.
+
+---
+
+## Phase 2: MAP Sidecar + Outbound Events
+
+**Goal:** Create the sidecar process and event emission hook helper.
+
+### 2.1 Create `scripts/map-sidecar.mjs`
+
+The persistent process. Key responsibilities:
+- Connect to MAP server via WebSocket
+- Register root agent
+- Listen for incoming messages → write to `inbox.jsonl`
+- Accept outbound events via UNIX socket → forward to MAP server
+- Register/unregister team agents on spawn/complete commands from hooks
+- Self-terminate after 30 min inactivity (session mode safety net)
+
+```
+Sidecar responsibilities:
+1. Parse CLI args (--server, --scope, --system-id, --roles-file)
+2. Read .claude-swarm.json for team config
+3. AgentConnection.connect(server, { name, role, scopes: [scope] })
+4. Create UNIX socket at .generated/map/sidecar.sock
+5. Listen on socket for hook commands:
+   - { action: "emit", event: {...} }           → agent.send(scope, event)
+   - { action: "register", agent: {...} }       → register child agent
+   - { action: "unregister", agentId: "..." }   → unregister child agent
+   - { action: "state", state: "busy" }         → agent.updateState()
+6. agent.onMessage(msg => appendFile(inbox.jsonl, JSON.stringify(msg)))
+7. Inactivity timer: reset on any socket command; SIGTERM self after 30min
+8. SIGTERM handler: agent.disconnect(), unlink socket/pid, exit
+```
+
+**Implementation structure:**
+
+```javascript
+#!/usr/bin/env node
+// map-sidecar.mjs — MAP sidecar for claude-code-swarm
+
+import { AgentConnection } from '@multi-agent-protocol/sdk';
+import net from 'net';
+import fs from 'fs';
+import path from 'path';
+
+// Parse args
+// Connect to MAP server
+// Create UNIX socket server
+// Handle commands from hooks
+// Write incoming messages to inbox
+// Manage inactivity timeout
+// Handle SIGTERM for cleanup
+```
+
+### 2.2 Create `scripts/map-hook.mjs`
+
+Hook helper script. Called by each hook with an action argument. Reads stdin for hook event data.
+
+Actions:
+- `inject` — Read inbox.jsonl, format as markdown, output to stdout, truncate inbox
+- `agent-spawning` — Parse PreToolUse(Task) stdin, emit swarm.agent.spawned + swarm.task.dispatched
+- `agent-completed` — Parse PostToolUse(Task) stdin, emit swarm.agent.completed + swarm.task.completed
+- `turn-completed` — Parse Stop stdin, emit swarm.turn.completed + update state to idle
+
+Each emit action:
+1. Try connect to sidecar UNIX socket
+2. If connected: send command, done
+3. If not connected + session mode: attempt auto-recovery (restart sidecar, wait 2s)
+4. If still not connected: fire-and-forget via direct WebSocket
+5. If fire-and-forget fails: silently drop (never block the agent)
+
+```javascript
+#!/usr/bin/env node
+// map-hook.mjs — Hook helper for claude-code-swarm MAP integration
+
+import fs from 'fs';
+import net from 'net';
+import path from 'path';
+
+const action = process.argv[2]; // inject | agent-spawning | agent-completed | turn-completed
+
+// Read .claude-swarm.json for config
+// Read stdin for hook event data
+
+switch (action) {
+  case 'inject':
+    // Read inbox, format, output, truncate
+    break;
+  case 'agent-spawning':
+    // Check if agent name matches topology role
+    // If yes: send register + task.dispatched to sidecar
+    // If no: send only task.dispatched (no MAP registration)
+    break;
+  case 'agent-completed':
+    // Send unregister + task.completed to sidecar
+    break;
+  case 'turn-completed':
+    // Send state update + turn.completed to sidecar
+    break;
+}
+```
+
+### 2.3 Sidecar → Hook role matching
+
+The hook needs to know which agent names are topology roles (to register them) vs internal subagents (to ignore). Two approaches:
+
+**Option A:** At `/swarm` launch time, write `.generated/map/roles.json` with the role list from `team.yaml`. The hook reads this file.
+
+**Option B:** The sidecar loads the role list at startup and the hook asks the sidecar "is this a team role?" via the socket.
+
+**Go with A** — simpler, no round-trip. The `/swarm` skill already parses `team.yaml` and can write this file. The `bootstrap.sh` can also do it from the template config.
+
+`.generated/map/roles.json`:
+```json
+{
+  "team": "get-shit-done",
+  "roles": ["orchestrator", "roadmapper", "verifier", "planner", "executor", ...],
+  "root": "orchestrator",
+  "companions": ["roadmapper", "verifier"]
+}
+```
+
+---
+
+## Phase 3: MAP Inbound + Recovery
+
+**Goal:** Inject MAP messages into agent context, auto-recover crashed sidecar.
+
+### 3.1 Inbox injection (`inject` action)
+
+In `map-hook.mjs`, the `inject` action:
+
+1. Check if `.generated/map/inbox.jsonl` exists and has content
+2. If empty: exit 0 with no output (don't inject empty context)
+3. Parse each line as JSON (`Message` type)
+4. Format as structured markdown:
+   ```
+   ## [MAP] N pending messages
+
+   **From <name>** (role: <role>, Ns ago)
+   > <payload summary>
+   > Priority: <priority>
+   ```
+5. Write formatted output to stdout
+6. Truncate inbox file (or rename to `.processed`)
+
+### 3.2 Auto-recovery logic
+
+In `map-hook.mjs`, before any action that requires the sidecar:
+
+```javascript
+async function ensureSidecar(config) {
+  // 1. Try connect to socket
+  const sock = tryConnect('.generated/map/sidecar.sock');
+  if (sock) return sock;
+
+  // 2. Check if session mode (we manage the sidecar)
+  if (config.map.sidecar !== 'session') return null;
+
+  // 3. Check PID file
+  const pid = readPidFile('.generated/map/sidecar.pid');
+  if (pid && isProcessAlive(pid)) {
+    // Sidecar is running but socket not ready yet — wait briefly
+    await waitForSocket('.generated/map/sidecar.sock', 1000);
+    return tryConnect('.generated/map/sidecar.sock');
+  }
+
+  // 4. Sidecar is dead — restart
+  const child = spawn('node', [
+    path.join(pluginDir, 'scripts/map-sidecar.mjs'),
+    '--server', config.map.server,
+    '--scope', config.map.scope,
+    // ...
+  ], { detached: true, stdio: 'ignore' });
+  child.unref();
+  fs.writeFileSync('.generated/map/sidecar.pid', String(child.pid));
+
+  // 5. Wait for socket
+  await waitForSocket('.generated/map/sidecar.sock', 2000);
+  return tryConnect('.generated/map/sidecar.sock');
+}
+```
+
+---
+
+## Phase 4: Team Agent Registration
+
+**Goal:** Sidecar registers team-level agents in MAP on spawn.
+
+### 4.1 Role matching in `map-hook.mjs`
+
+When `agent-spawning` action fires:
+
+```javascript
+case 'agent-spawning': {
+  const hookData = JSON.parse(await readStdin());
+  const agentName = hookData.tool_input?.name || '';
+  const roles = JSON.parse(fs.readFileSync('.generated/map/roles.json', 'utf-8'));
+
+  // Extract role name from agent name (e.g., "gsd-executor" → "executor")
+  // Or match directly against roles list
+  const matchedRole = roles.roles.find(r =>
+    agentName === r ||
+    agentName === `${roles.team}-${r}` ||
+    agentName.endsWith(`-${r}`)
+  );
+
+  const sidecar = await ensureSidecar(config);
+  if (!sidecar) break;
+
+  if (matchedRole) {
+    // Register as team agent in MAP
+    sidecar.write(JSON.stringify({
+      action: 'register',
+      agent: {
+        agentId: `${roles.team}-${matchedRole}`,
+        name: matchedRole,
+        role: matchedRole,
+        parent: currentAgentId,
+        scopes: [config.map.scope]
+      }
+    }) + '\n');
+  }
+
+  // Always emit spawn event
+  sidecar.write(JSON.stringify({
+    action: 'emit',
+    event: {
+      type: 'swarm.agent.spawned',
+      agent: agentName,
+      role: matchedRole || 'internal',
+      parent: currentAgentId,
+      isTeamRole: !!matchedRole,
+      task: hookData.tool_input?.prompt?.substring(0, 200)
+    }
+  }) + '\n');
+  break;
+}
+```
+
+### 4.2 Unregistration on completion
+
+When `agent-completed` action fires:
+
+```javascript
+case 'agent-completed': {
+  const hookData = JSON.parse(await readStdin());
+  const agentName = hookData.tool_input?.name || '';
+  const roles = JSON.parse(fs.readFileSync('.generated/map/roles.json', 'utf-8'));
+
+  const matchedRole = roles.roles.find(r => /* same matching logic */);
+
+  const sidecar = await ensureSidecar(config);
+  if (!sidecar) break;
+
+  if (matchedRole) {
+    sidecar.write(JSON.stringify({
+      action: 'unregister',
+      agentId: `${roles.team}-${matchedRole}`
+    }) + '\n');
+  }
+
+  sidecar.write(JSON.stringify({
+    action: 'emit',
+    event: {
+      type: 'swarm.agent.completed',
+      agent: agentName,
+      role: matchedRole || 'internal',
+      parent: currentAgentId,
+      status: 'completed'
+    }
+  }) + '\n');
+  break;
+}
+```
+
+---
+
+## Phase 5: Native Teams Integration
+
+**Goal:** Replace all openteams runtime CLI usage with Claude Code native team features. openteams is now config/generation only.
+
+### 5.1 Update `skills/swarm/SKILL.md`
+
+The `/swarm` skill now:
+1. Calls `openteams generate all` to produce role artifacts (unchanged)
+2. Calls `TeamCreate` to set up a native Claude Code team
+3. Spawns a **coordinator agent** (the root role) with `team_name`
+4. The coordinator manages everything: spawning companions/workers, creating tasks, coordinating via SendMessage
+
+### 5.2 Update `scripts/generate-agents.mjs`
+
+In `determineTools()`: add `TaskList`, `TaskUpdate`, `SendMessage` for all agents; `TaskCreate` for root/companions. Remove `TodoWrite`.
+
+In `generateAgentMd()`: replace the "Team Coordination" section:
+
+**Remove all openteams CLI references:**
+- `openteams task list/update` — replaced by `TaskList`/`TaskUpdate`
+- `openteams template emit/events` — replaced by `SendMessage`
+- `openteams message send/poll` — replaced by `SendMessage`
+- MAP scope references — agents don't need to know about MAP
+
+**Replace with:**
+- `SendMessage` usage instructions with role-specific communication patterns from topology
+- `TaskList`/`TaskUpdate` for task management; `TaskCreate` for root/companions
+- Topology-derived routing patterns (from `manifest.communication.routing.peers`)
+- Signal emission/subscription mapped to SendMessage guidance
+- Optional MAP note: "lifecycle events emitted automatically, no interaction needed"
+
+### 5.3 Update `scripts/team-loader.sh`
+
+Replace openteams CLI instructions with native team references:
+- `TeamCreate` for team setup
+- `TaskCreate`/`TaskUpdate` for task lifecycle
+- `SendMessage` for agent-to-agent communication
+
+Keep `roles.json` generation (still needed for MAP hook role matching).
+
+### 5.4 Update `scripts/bootstrap.sh`
+
+Minor text updates:
+- Remove "(openteams)" from header
+- Update `/swarm` description to mention native teams
+
+---
+
+## Phase 6: Polish
+
+### 6.1 Update `CLAUDE.md`
+
+Reflect new architecture:
+- openteams is config/generation only (no runtime CLI usage)
+- Claude Code native teams handle all runtime coordination (TeamCreate, TaskCreate/TaskUpdate, SendMessage)
+- MAP handles external observability only
+- Coordinator agent pattern: `/swarm` → TeamCreate → spawn coordinator → coordinator manages team
+
+### 6.3 Update `.claude-plugin/plugin.json`
+
+Bump version to `0.2.0`.
+
+### 6.4 Error handling
+
+- `map-hook.mjs`: all operations wrapped in try/catch, never exit non-zero (don't block agent)
+- `map-sidecar.mjs`: reconnection on WebSocket drop (MAP SDK has built-in reconnection support)
+- `bootstrap.sh`: all failures are warnings, never `exit 1`
+
+---
+
+## Dependency graph
+
+```
+Phase 1 (foundation)
+  ├── bootstrap.sh
+  ├── hooks.json update
+  └── settings.json update
+       │
+Phase 2 (sidecar + outbound)
+  ├── map-sidecar.mjs  ← depends on Phase 1 (hooks.json wiring)
+  └── map-hook.mjs     ← depends on Phase 1 (hooks.json wiring)
+       │
+Phase 3 (inbound + recovery)
+  └── inject action + auto-recovery  ← depends on Phase 2 (sidecar exists)
+       │
+Phase 4 (agent registration)
+  └── role matching + register/unregister  ← depends on Phase 2 (sidecar)
+       │                                     depends on Phase 5.3 (roles.json)
+Phase 5 (code gen updates)
+  ├── generate-agents.mjs update  ← independent
+  ├── team-loader.sh update       ← independent
+  └── roles.json writing          ← independent
+       │
+Phase 6 (polish)
+  └── docs, SKILL.md, error handling  ← depends on all above
+```
+
+Phases 2-4 are sequential (each builds on the previous). Phase 5 is independent and can be done in parallel with Phase 2.
+
+---
+
+## Testing approach
+
+### Manual testing
+
+1. **Phase 1:** Start a Claude Code session with the plugin installed. Verify `bootstrap.sh` output appears in context. Test with/without `.claude-swarm.json`.
+
+2. **Phase 2:** Start a MAP server (`npx @multi-agent-protocol/server`). Configure `.claude-swarm.json` with `map.enabled: true`. Verify sidecar starts. Use a `ClientConnection` script to subscribe and verify events appear when agents are spawned.
+
+3. **Phase 3:** Send a message to the sidecar's agent via MAP. Verify it appears in the next turn's context. Kill the sidecar mid-session, verify auto-recovery on next prompt.
+
+4. **Phase 4:** Launch `/swarm get-shit-done`. Verify team agents appear in MAP agent list. Verify internal subagents do NOT appear.
+
+### Automated testing (future)
+
+- Unit tests for `map-hook.mjs` actions (mock stdin, verify output)
+- Integration test: sidecar + MAP server + hook simulation
+- Recovery test: kill sidecar, verify hook restarts it