claude-code-swarm 0.3.4 → 0.3.6

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/plugin.json

@@ -1,8 +1,29 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "author": {
     "name": "alexngai"
+  },
+  "mcpServers": {
+    "opentasks": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-opentasks-mcp.sh",
+      "args": [],
+      "env": {
+        "OPENTASKS_WORKING_DIR": "${workspaceFolder}"
+      }
+    },
+    "agent-inbox": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-agent-inbox-mcp.sh",
+      "args": [],
+      "env": {}
+    },
+    "minimem": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/run-minimem-mcp.sh",
+      "args": [],
+      "env": {
+        "MINIMEM_WORKING_DIR": "${workspaceFolder}"
+      }
+    }
   }
 }

package/.claude-plugin/run-agent-inbox-mcp.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# Wrapper script to run agent-inbox MCP server
+# When the sidecar's inbox socket exists, runs in proxy mode (IPC client).
+# Otherwise falls back to standalone mode with its own storage.
+# Exits silently if inbox is not enabled or not installed.
+
+# Check if inbox is enabled in config
+ENABLED=false
+if [ -f .swarm/claude-swarm/config.json ]; then
+  ENABLED=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const envEnabled = (process.env.SWARM_INBOX_ENABLED || '').toLowerCase();
+      const isEnabled = ['true', '1', 'yes'].includes(envEnabled) || c.inbox?.enabled === true;
+      process.stdout.write(isEnabled ? 'true' : 'false');
+    } catch { process.stdout.write('false'); }
+  " 2>/dev/null || echo "false")
+elif [ -n "$SWARM_INBOX_ENABLED" ]; then
+  case "$(echo "$SWARM_INBOX_ENABLED" | tr '[:upper:]' '[:lower:]')" in
+    true|1|yes) ENABLED=true ;;
+  esac
+fi
+
+if [ "$ENABLED" != "true" ]; then
+  # Not enabled — exit silently so Claude Code doesn't show an error
+  sleep 0.1
+  exit 0
+fi
+
+# Read scope from config (defaults to MAP scope or "default")
+SCOPE="default"
+if [ -f .swarm/claude-swarm/config.json ]; then
+  CONFIGURED_SCOPE=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const s = c.inbox?.scope || c.map?.scope || process.env.SWARM_INBOX_SCOPE || '';
+      if (s) process.stdout.write(s);
+    } catch {}
+  " 2>/dev/null)
+  if [ -n "$CONFIGURED_SCOPE" ]; then
+    SCOPE="$CONFIGURED_SCOPE"
+  fi
+fi
+
+if [ -n "$SWARM_INBOX_SCOPE" ]; then
+  SCOPE="$SWARM_INBOX_SCOPE"
+fi
+
+export INBOX_SCOPE="$SCOPE"
+
+# Discover sidecar inbox socket for proxy mode
+# Check well-known paths: .swarm/claude-swarm/tmp/map/inbox.sock
+INBOX_SOCK=""
+if [ -S .swarm/claude-swarm/tmp/map/inbox.sock ]; then
+  INBOX_SOCK=".swarm/claude-swarm/tmp/map/inbox.sock"
+fi
+
+# Also check per-session paths
+if [ -z "$INBOX_SOCK" ] && [ -d .swarm/claude-swarm/tmp/map/sessions ]; then
+  # Find the most recently modified inbox.sock in session dirs
+  INBOX_SOCK=$(find .swarm/claude-swarm/tmp/map/sessions -name inbox.sock -type s 2>/dev/null | head -1)
+fi
+
+# If inbox socket found, enable proxy mode
+if [ -n "$INBOX_SOCK" ]; then
+  export INBOX_SOCKET_PATH="$INBOX_SOCK"
+fi
+
+# Try to find the agent-inbox module entry point
+INBOX_MAIN=""
+
+# 1. Check global npm root (swarmkit installs here)
+GLOBAL_ROOT=$(npm root -g 2>/dev/null)
+if [ -n "$GLOBAL_ROOT" ] && [ -f "$GLOBAL_ROOT/agent-inbox/dist/index.js" ]; then
+  INBOX_MAIN="$GLOBAL_ROOT/agent-inbox/dist/index.js"
+fi
+
+# 2. Check plugin directory's node_modules (dev installs)
+if [ -z "$INBOX_MAIN" ] && [ -n "$CLAUDE_PLUGIN_ROOT" ] && [ -f "$CLAUDE_PLUGIN_ROOT/node_modules/agent-inbox/dist/index.js" ]; then
+  INBOX_MAIN="$CLAUDE_PLUGIN_ROOT/node_modules/agent-inbox/dist/index.js"
+fi
+
+# 3. Fallback: try require.resolve from CWD
+if [ -z "$INBOX_MAIN" ]; then
+  INBOX_MAIN=$(node -e "try { console.log(require.resolve('agent-inbox/dist/index.js')); } catch {}" 2>/dev/null)
+fi
+
+if [ -n "$INBOX_MAIN" ]; then
+  # Uses proxy mode when INBOX_SOCKET_PATH is set, standalone otherwise
+  exec node "$INBOX_MAIN" mcp
+fi
+
+# agent-inbox not installed — log to stderr and exit cleanly
+echo "[agent-inbox-mcp] agent-inbox not found. Install with: npm install -g agent-inbox or install via swarmkit" >&2
+exit 0

package/.claude-plugin/run-minimem-mcp.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# Wrapper script to run minimem MCP server
+# Reads provider and directory from swarm config
+# Exits silently if minimem is not enabled or not installed
+
+# Check if minimem is enabled in config
+ENABLED=false
+if [ -f .swarm/claude-swarm/config.json ]; then
+  ENABLED=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const envEnabled = (process.env.SWARM_MINIMEM_ENABLED || '').toLowerCase();
+      const isEnabled = ['true', '1', 'yes'].includes(envEnabled) || c.minimem?.enabled === true;
+      process.stdout.write(isEnabled ? 'true' : 'false');
+    } catch { process.stdout.write('false'); }
+  " 2>/dev/null || echo "false")
+elif [ -n "$SWARM_MINIMEM_ENABLED" ]; then
+  case "$(echo "$SWARM_MINIMEM_ENABLED" | tr '[:upper:]' '[:lower:]')" in
+    true|1|yes) ENABLED=true ;;
+  esac
+fi
+
+if [ "$ENABLED" != "true" ]; then
+  # Not enabled — exit silently so Claude Code doesn't show an error
+  sleep 0.1
+  exit 0
+fi
+
+# Read provider from config (defaults to "auto")
+PROVIDER="auto"
+if [ -f .swarm/claude-swarm/config.json ]; then
+  CONFIGURED_PROVIDER=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const p = process.env.SWARM_MINIMEM_PROVIDER || c.minimem?.provider || '';
+      if (p) process.stdout.write(p);
+    } catch {}
+  " 2>/dev/null)
+  if [ -n "$CONFIGURED_PROVIDER" ]; then
+    PROVIDER="$CONFIGURED_PROVIDER"
+  fi
+fi
+
+if [ -n "$SWARM_MINIMEM_PROVIDER" ]; then
+  PROVIDER="$SWARM_MINIMEM_PROVIDER"
+fi
+
+# Discover memory directory: config dir > .swarm/minimem/ > cwd
+MEMORY_DIR=""
+if [ -f .swarm/claude-swarm/config.json ]; then
+  CONFIGURED_DIR=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const d = process.env.SWARM_MINIMEM_DIR || c.minimem?.dir || '';
+      if (d) process.stdout.write(d);
+    } catch {}
+  " 2>/dev/null)
+  if [ -n "$CONFIGURED_DIR" ]; then
+    MEMORY_DIR="$CONFIGURED_DIR"
+  fi
+fi
+
+if [ -n "$SWARM_MINIMEM_DIR" ]; then
+  MEMORY_DIR="$SWARM_MINIMEM_DIR"
+fi
+
+if [ -z "$MEMORY_DIR" ]; then
+  if [ -d ".swarm/minimem" ]; then
+    MEMORY_DIR=".swarm/minimem"
+  else
+    MEMORY_DIR="."
+  fi
+fi
+
+# Check if global memory should also be searched
+GLOBAL_ARG=""
+if [ -f .swarm/claude-swarm/config.json ]; then
+  USE_GLOBAL=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const envGlobal = (process.env.SWARM_MINIMEM_GLOBAL || '').toLowerCase();
+      const isGlobal = ['true', '1', 'yes'].includes(envGlobal) || c.minimem?.global === true;
+      process.stdout.write(isGlobal ? 'true' : 'false');
+    } catch { process.stdout.write('false'); }
+  " 2>/dev/null || echo "false")
+  if [ "$USE_GLOBAL" = "true" ]; then
+    GLOBAL_ARG="--global"
+  fi
+fi
+
+# Try installed minimem command
+if command -v minimem &> /dev/null; then
+  exec minimem mcp --dir "$MEMORY_DIR" --provider "$PROVIDER" $GLOBAL_ARG
+fi
+
+# minimem not installed — log to stderr and exit cleanly
+echo "[minimem-mcp] minimem CLI not found. Install with: npm install -g minimem" >&2
+exit 0

package/.claude-plugin/run-opentasks-mcp.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Wrapper script to run opentasks MCP server
+# Reads scope from swarm config, defaults to "tasks"
+# Exits silently if opentasks is not enabled or not installed
+
+# Check if opentasks is enabled in config
+ENABLED=false
+if [ -f .swarm/claude-swarm/config.json ]; then
+  ENABLED=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const envEnabled = (process.env.SWARM_OPENTASKS_ENABLED || '').toLowerCase();
+      const isEnabled = ['true', '1', 'yes'].includes(envEnabled) || c.opentasks?.enabled === true;
+      process.stdout.write(isEnabled ? 'true' : 'false');
+    } catch { process.stdout.write('false'); }
+  " 2>/dev/null || echo "false")
+elif [ -n "$SWARM_OPENTASKS_ENABLED" ]; then
+  case "$(echo "$SWARM_OPENTASKS_ENABLED" | tr '[:upper:]' '[:lower:]')" in
+    true|1|yes) ENABLED=true ;;
+  esac
+fi
+
+if [ "$ENABLED" != "true" ]; then
+  # Not enabled — exit silently so Claude Code doesn't show an error
+  # Sleep briefly then exit so the MCP transport doesn't see an immediate close
+  sleep 0.1
+  exit 0
+fi
+
+# Read scope from config
+SCOPE="tasks"
+if [ -f .swarm/claude-swarm/config.json ]; then
+  CONFIGURED_SCOPE=$(node -e "
+    try {
+      const c = JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json', 'utf-8'));
+      const s = c.opentasks?.scope || process.env.SWARM_OPENTASKS_SCOPE || '';
+      if (s) process.stdout.write(s);
+    } catch {}
+  " 2>/dev/null)
+  if [ -n "$CONFIGURED_SCOPE" ]; then
+    SCOPE="$CONFIGURED_SCOPE"
+  fi
+fi
+
+if [ -n "$SWARM_OPENTASKS_SCOPE" ]; then
+  SCOPE="$SWARM_OPENTASKS_SCOPE"
+fi
+
+# Build socket path arg if daemon socket exists
+SOCKET_ARG=""
+for SOCK in .swarm/opentasks/daemon.sock .opentasks/daemon.sock .git/opentasks/daemon.sock; do
+  if [ -S "$SOCK" ]; then
+    SOCKET_ARG="--socket $SOCK"
+    break
+  fi
+done
+
+# Try installed opentasks command
+if command -v opentasks &> /dev/null; then
+  exec opentasks mcp --scope "$SCOPE" $SOCKET_ARG
+fi
+
+# opentasks not installed — log to stderr and exit cleanly
+echo "[opentasks-mcp] opentasks CLI not found. Install with: npm install -g opentasks" >&2
+exit 0

package/.gitattributes

@@ -0,0 +1,3 @@
+
+# OpenTasks merge driver for graph.jsonl
+.opentasks/graph.jsonl merge=opentasks

package/.opentasks/config.json

@@ -0,0 +1,9 @@
+{
+  "version": "1.0",
+  "location": {
+    "hash": "5bkyrjlx",
+    "uuid": "7b496a03-dd73-4d0b-a243-d9108ecc2f20",
+    "name": "claude-code-swarm"
+  },
+  "connections": []
+}

package/CLAUDE.md

@@ -1,16 +1,19 @@
 # claude-code-swarm
 
-Claude Code plugin that launches agent teams from openteams YAML topologies, using Claude Code's native team features for coordination and optional MAP (Multi-Agent Protocol) for external observability.
+Claude Code plugin that launches agent teams from openteams YAML topologies, using Claude Code's native team features for coordination, optional MAP (Multi-Agent Protocol) for external observability, and optional OpenTasks for cross-system task graph integration.
 
 ## What this plugin does
 
 This plugin bridges [openteams](https://github.com/alexngai/openteams) team templates with Claude Code's native agent teams. It provides:
 
 1. **SessionStart hook** (`scripts/bootstrap.mjs`) — Reads `.swarm/claude-swarm/config.json`, installs deps, initializes swarmkit project packages, starts MAP sidecar if configured, and injects team context
-2. **MAP integration** (`scripts/map-sidecar.mjs`, `scripts/map-hook.mjs`) — Persistent sidecar for external observability via MAP server (lifecycle events, agent registration)
-3. **`/swarm` skill** (`skills/swarm/SKILL.md`) — User-invocable skill to select a template, create a native Claude Code team via `TeamCreate`, and spawn a coordinator agent
-4. **Agent generator** (`scripts/generate-agents.mjs`) — Converts openteams YAML templates into Claude Code AGENT.md files with native team tool instructions
-5. **Team loader** (`scripts/team-loader.mjs`) — Resolves templates, generates artifacts (with per-template caching), writes roles.json for MAP hook integration
+2. **MAP integration** (`scripts/map-sidecar.mjs`, `scripts/map-hook.mjs`) — Persistent sidecar for external observability via MAP server (lifecycle events, agent registration, task bridge events)
+3. **OpenTasks integration** (`src/opentasks-client.mjs`, MCP server) — Optional cross-system task graph that federates Claude Tasks, MAP tasks, and external systems. Registered as an MCP server for agent use; bridge hooks emit task events to MAP for observability
+4. **`/swarm` skill** (`skills/swarm/SKILL.md`) — User-invocable skill to select a template, create a native Claude Code team via `TeamCreate`, and spawn a coordinator agent
+5. **Agent generator** (`scripts/generate-agents.mjs`) — Converts openteams YAML templates into Claude Code AGENT.md files with native team tool instructions
+6. **Team loader** (`scripts/team-loader.mjs`) — Resolves templates, generates artifacts (with per-template caching), writes roles.json for MAP hook integration
+7. **minimem integration** (MCP server) — Optional agent memory with semantic search. Registered as an MCP server; agents use memory tools to recall past decisions and context
+8. **skill-tree integration** (`src/skilltree-client.mjs`) — Optional per-role skill loadouts compiled from team.yaml `skilltree:` extension and embedded in AGENT.md files at generation time
 
 ## Plugin structure
 
@@ -29,6 +32,8 @@ claude-code-swarm/
 │   ├── sidecar-client.mjs        # UNIX socket client + recovery
 │   ├── sidecar-server.mjs        # UNIX socket server + command handler
 │   ├── map-events.mjs            # Event builders + emit (sidecar → fallback)
+│   ├── opentasks-client.mjs      # OpenTasks daemon IPC client (socket discovery, task CRUD, sync)
+│   ├── skilltree-client.mjs     # Skill-tree loadout compilation (per-role, cached)
 │   ├── sessionlog.mjs            # Session detection, trajectory checkpoints, sync
 │   ├── template.mjs              # Template resolution + openteams generation
 │   ├── agent-generator.mjs       # AGENT.md generation (tools, frontmatter)
@@ -108,6 +113,42 @@ MAP options:
 - `auth.token` — Authentication token appended as a query parameter to the server URL
 - `auth.param` — Query parameter name for the token (default: `token`)
 
+### With MeshPeer transport (agentic-mesh)
+```json
+{
+  "template": "gsd",
+  "map": {
+    "server": "ws://localhost:8080"
+  },
+  "mesh": {
+    "enabled": true
+  }
+}
+```
+
+When enabled, the sidecar uses an embedded MeshPeer (from agentic-mesh) instead of a direct MAP SDK WebSocket connection. This provides encrypted P2P transport, agent discovery via MapServer registry, and federation with hop/loop detection. Agent-inbox integration gives structured messaging, threading, and delivery tracking.
+
+If agentic-mesh is not available, the sidecar falls back to the direct MAP SDK WebSocket connection automatically.
+
+Mesh options:
+- `enabled` — Enable MeshPeer transport (default: `false`)
+- `peerId` — MeshPeer peer ID (default: `<teamName>-sidecar`)
+- `mapServer` — Optional MAP server URL for hybrid mode (mesh + MAP bridge)
+
+### With OpenTasks
+```json
+{
+  "template": "gsd",
+  "opentasks": {
+    "enabled": true
+  }
+}
+```
+
+When enabled, the plugin registers an OpenTasks MCP server that agents can use for cross-system task operations (`create_task`, `update_task`, `link`, `annotate`, `list_tasks`, `query`). The MCP server communicates with the OpenTasks daemon over a Unix socket. When both OpenTasks and MAP are enabled, `PostToolUse(opentasks)` hooks bridge MCP tool use into MAP task events for observability.
+
+OpenTasks is independent from Claude's native task system — native tasks have their own `claude://` provider in the OpenTasks graph (see Task concepts below).
+
 ### With sessionlog → MAP sync
 ```json
 {
@@ -128,6 +169,61 @@ When both MAP and sessionlog are active, the plugin bridges sessionlog's session
 
 Requires sessionlog to be installed and active independently (`sessionlog enable`).
 
+### With minimem (agent memory)
+```json
+{
+  "template": "gsd",
+  "minimem": {
+    "enabled": true,
+    "provider": "auto"
+  }
+}
+```
+
+When enabled, the plugin registers a minimem MCP server that agents can use for semantic memory search (`memory_search`, `memory_get_details`, `knowledge_search`, `knowledge_graph`, `knowledge_path`). Memories are stored as Markdown files in `.swarm/minimem/` and indexed with vector embeddings + BM25 hybrid search. Memory is shared team-wide — all agents search the same store.
+
+Minimem options:
+- `enabled` — Enable minimem integration (default: `false`)
+- `provider` — Embedding provider: `openai`, `gemini`, `local`, `auto`, `none` (default: `auto`)
+- `global` — Also search the user's global memory store at `~/.minimem` (default: `false`)
+- `dir` — Custom memory directory path (default: `.swarm/minimem/`)
+
+### With skill-tree (per-role skill loadouts)
+```json
+{
+  "template": "gsd",
+  "skilltree": {
+    "enabled": true,
+    "defaultProfile": "implementation"
+  }
+}
+```
+
+When enabled, the plugin compiles per-role skill loadouts from the team.yaml `skilltree:` extension namespace and embeds them in each agent's AGENT.md at generation time. Skills are cached per template alongside other artifacts.
+
+Define per-role loadouts in team.yaml:
+```yaml
+skilltree:
+  defaults:
+    profile: implementation
+    maxSkills: 6
+  roles:
+    orchestrator:
+      profile: code-review
+    executor:
+      profile: implementation
+      tags: [development]
+    verifier:
+      profile: testing
+    debugger:
+      profile: debugging
+```
+
+Skill-tree options:
+- `enabled` — Enable skill-tree integration (default: `false`)
+- `basePath` — Path to skill-tree storage directory (default: `.swarm/skill-tree/`)
+- `defaultProfile` — Default profile when no role-specific criteria exist (default: `""`)
+
 ### Available templates
 
 Templates are provided by the openteams package (installed via swarmkit). Built-in templates include:
@@ -158,8 +254,20 @@ All config values can be overridden via `SWARM_*` environment variables. Priorit
 | `map.sidecar` | `SWARM_MAP_SIDECAR` | string | `session` |
 | `map.auth.token` | `SWARM_MAP_AUTH_TOKEN` | string | `""` |
 | `map.auth.param` | `SWARM_MAP_AUTH_PARAM` | string | `token` |
+| `opentasks.enabled` | `SWARM_OPENTASKS_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
+| `opentasks.scope` | `SWARM_OPENTASKS_SCOPE` | string | `""` |
 | `sessionlog.enabled` | `SWARM_SESSIONLOG_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
 | `sessionlog.sync` | `SWARM_SESSIONLOG_SYNC` | string | `off` |
+| `minimem.enabled` | `SWARM_MINIMEM_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
+| `minimem.provider` | `SWARM_MINIMEM_PROVIDER` | string | `auto` |
+| `minimem.global` | `SWARM_MINIMEM_GLOBAL` | boolean (`true`/`1`/`yes`) | `false` |
+| `minimem.dir` | `SWARM_MINIMEM_DIR` | string | `""` |
+| `skilltree.enabled` | `SWARM_SKILLTREE_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
+| `skilltree.basePath` | `SWARM_SKILLTREE_BASE_PATH` | string | `""` |
+| `skilltree.defaultProfile` | `SWARM_SKILLTREE_DEFAULT_PROFILE` | string | `""` |
+| `mesh.enabled` | `SWARM_MESH_ENABLED` | boolean (`true`/`1`/`yes`) | `false` |
+| `mesh.peerId` | `SWARM_MESH_PEER_ID` | string | `""` |
+| `mesh.mapServer` | `SWARM_MESH_MAP_SERVER` | string | `""` |
 
 MAP is implicitly enabled when `map.server` is configured (in file or via `SWARM_MAP_SERVER`). Use `SWARM_MAP_ENABLED=false` to explicitly disable.
 
@@ -168,6 +276,22 @@ Example — point to a MAP server in CI (implicitly enables MAP):
 SWARM_MAP_SERVER=ws://map.ci.internal:8080 claude
 ```
 
+## Task concepts
+
+There are three distinct "task" systems in play. They are independent — each has its own storage and lifecycle:
+
+- **Claude Native Tasks** (`TaskCreate`/`TaskUpdate`/`TaskList`/`TaskStop`) — Team-wide coordination between agents. Stored by Claude Code's internal task system. The OpenTasks `claude-tasks` provider surfaces these as `claude://` nodes in the graph via a filesystem-backed `ClaudeTaskStore` adapter with chokidar file watching — no swarm hooks needed to sync them.
+
+- **OpenTasks** (MCP tools: `create_task`, `update_task`, `link`, etc.) — Cross-system persistent task graph stored in JSONL. Federates tasks from multiple providers (`native://`, `claude://`, `map://`, `beads://`, etc.) via edges. Optional — enabled via `opentasks.enabled` config.
+
+- **MAP Tasks** — Remote tasks on a MAP server, surfaced as `map://` nodes by the OpenTasks MAP provider. Ephemeral/pass-through — no local cache. Used for cross-system coordination when agents on different MAP-connected systems need to share tasks.
+
+The swarm plugin's role is **observability bridging**, not task creation:
+- `PostToolUse(TaskCreate/TaskUpdate)` → emits MAP bridge events so external observers can see native task activity
+- `PostToolUse(opentasks)` → emits MAP bridge events when agents use opentasks MCP tools
+- `TaskCompleted` → updates the opentasks graph + emits MAP bridge event
+- Agent spawning/completion hooks manage MAP agent lifecycle only (not task creation)
+
 ## Architecture
 
 ### Team launch flow
@@ -198,28 +322,54 @@ All hooks use MAP SDK primitives — no custom `swarm.*` event types. Clients su
 - `trajectory.checkpoint` for sessionlog sync
 
 Hook dispatch:
-1. **UserPromptSubmit** → `map-hook.mjs inject`: reads MAP inbox, injects external messages into context
-2. **PreToolUse(Task)** → `map-hook.mjs agent-spawning`: spawns agent via `conn.spawn()` (server auto-emits `agent_registered`), sends `task.dispatched` message
-3. **PostToolUse(Task)** → `map-hook.mjs agent-completed`: marks agent done via `conn.callExtension("map/agents/unregister")` (server auto-emits `agent_unregistered`), sends `task.completed` message
-4. **Stop** → `map-hook.mjs turn-completed`: updates sidecar state via `conn.updateState("idle")` (server auto-emits `agent_state_changed`)
-5. **Stop** → `map-hook.mjs sessionlog-sync`: reads sessionlog state, reports `trajectory/checkpoint` to MAP (falls back to `trajectory.checkpoint` message payload if server doesn't support trajectory)
-6. **SubagentStart** → `map-hook.mjs subagent-start`: spawns subagent via `conn.spawn()` with `role: "subagent"`
-7. **SubagentStop** → `map-hook.mjs subagent-stop`: marks subagent done
-8. **TeammateIdle** → `map-hook.mjs teammate-idle`: updates teammate state to idle
-9. **TaskCompleted** → `map-hook.mjs task-completed`: sends `task.completed` message
+1. **UserPromptSubmit** → `map-hook.mjs inject`: reads MAP inbox, injects external messages into context. Forwards incoming `task.*` events to the opentasks graph if `opentasks.enabled`
+2. **PostToolUse(opentasks)** → `map-hook.mjs opentasks-mcp-used`: bridges opentasks MCP tool use into MAP task events (`bridge-task-created`, `bridge-task-status`, `bridge-task-assigned`, `task.linked`, `task.sync`). Gated on both `opentasks.enabled` and `map.enabled`
+3. **PostToolUse(TaskCreate)** → `map-hook.mjs native-task-created`: emits `bridge-task-created` + `bridge-task-assigned` to MAP. Observability only — native tasks enter the opentasks graph via the `claude-tasks` provider, not this hook
+4. **PostToolUse(TaskUpdate)** → `map-hook.mjs native-task-updated`: emits `bridge-task-status` to MAP. Observability only
+5. **TaskCompleted** → `map-hook.mjs task-completed`: updates task in opentasks daemon (`updateTask`) + emits `bridge-task-status` to MAP
+6. **Stop** → `map-hook.mjs turn-completed`: updates sidecar state via `conn.updateState("idle")` (server auto-emits `agent_state_changed`)
+7. **Stop** → `map-hook.mjs sessionlog-sync`: reads sessionlog state, reports `trajectory/checkpoint` to MAP (falls back to `trajectory.checkpoint` message payload if server doesn't support trajectory)
+8. **SubagentStart** → `map-hook.mjs subagent-start`: spawns subagent via `conn.spawn()` with `role: "subagent"`
+9. **SubagentStop** → `map-hook.mjs subagent-stop`: marks subagent done
+10. **TeammateIdle** → `map-hook.mjs teammate-idle`: updates teammate state to idle
 
 ### MAP sidecar
 
-The sidecar (`scripts/map-sidecar.mjs`) is a persistent Node.js process that:
+The sidecar (`scripts/map-sidecar.mjs`) is a persistent Node.js process with two transport modes:
+
+**Mesh mode** (preferred, when `mesh.enabled: true`):
+- Creates an embedded MeshPeer (from agentic-mesh) for encrypted P2P transport
+- Passes the MeshPeer to agent-inbox Phase 2 integration for structured messaging, agent registry, and federation
+- Agent lifecycle (spawn/done) handled by inbox registry, with MAP registration for external observability
+- Task bridge events, trajectory checkpoints, and state updates go through the MeshPeer connection
+- Falls back to WebSocket mode automatically if agentic-mesh is unavailable
+
+**WebSocket mode** (fallback/default):
 - Connects to the MAP server via WebSocket with auto-reconnection
-- Listens on a UNIX socket (`.swarm/claude-swarm/tmp/map/sidecar.sock`) for commands from hooks
-- Writes incoming external MAP messages to `.swarm/claude-swarm/tmp/map/inbox.jsonl`
-- Manages agent lifecycle via SDK primitives: `conn.spawn()` for registration, `conn.callExtension("map/agents/unregister")` for deregistration, `conn.updateState()` for state changes
-- Sends task lifecycle as typed message payloads via `conn.send()`
-- Reports trajectory checkpoints via `trajectory/checkpoint` (with `trajectory.checkpoint` message fallback)
-- Self-terminates after 30 minutes of inactivity (session mode)
+- Agent lifecycle via MAP SDK primitives: `conn.spawn()`, `conn.callExtension("map/agents/unregister")`, `conn.updateState()`
+- Agent-inbox shares the MAP connection for messaging (legacy integration)
+
+Both modes:
+- Listen on a UNIX socket (`.swarm/claude-swarm/tmp/map/sidecar.sock`) for commands from hooks
+- Manage agent-inbox on a separate IPC socket for messaging
+- Send task lifecycle as typed message payloads via `conn.send()`
+- Report trajectory checkpoints via `trajectory/checkpoint` (with broadcast fallback)
+- Self-terminate after 30 minutes of inactivity (session mode)
+
+The hook helper (`scripts/map-hook.mjs`) includes best-effort auto-recovery: if the sidecar is down, it attempts to restart it, with a fire-and-forget fallback (mesh or direct WebSocket) if recovery fails.
+
+### OpenTasks integration
+
+The plugin integrates with OpenTasks at two levels:
+
+**MCP server** — Registered in `plugin.json` as an MCP server (`run-opentasks-mcp.sh`). Conditionally started based on `opentasks.enabled` config. Agents use MCP tools (`create_task`, `update_task`, `link`, `annotate`, `list_tasks`, `query`) to interact with the OpenTasks daemon over a Unix socket.
+
+**Daemon IPC client** (`src/opentasks-client.mjs`) — Direct IPC to the OpenTasks daemon for hook-initiated operations. Socket discovery follows priority: `.swarm/opentasks/` → `.opentasks/` → `.git/opentasks/` → walk up. Used by:
+- `task-completed` hook → `updateTask()` to mark tasks closed
+- `inject` hook → `pushSyncEvent()` to forward incoming MAP `task.*` events to the graph
+- `map-events.mjs` → `handleTaskCreated()`/`handleTaskCompleted()` (available for two-step pattern: create in opentasks + emit MAP bridge event)
 
-The hook helper (`scripts/map-hook.mjs`) includes best-effort auto-recovery: if the sidecar is down, it attempts to restart it, with a fire-and-forget direct WebSocket fallback if recovery fails.
+**Relationship to native Claude Tasks** — Native tasks (`TaskCreate`/`TaskUpdate`) enter the OpenTasks graph via the `claude-tasks` provider (in the OpenTasks project), which uses a filesystem-backed `ClaudeTaskStore` adapter with chokidar file watching. The swarm plugin does NOT need to push native tasks into OpenTasks — the provider handles this reactively. The swarm hooks for `PostToolUse(TaskCreate/TaskUpdate)` only emit MAP bridge events for observability.
 
 ### Agent registration
 
@@ -230,20 +380,23 @@ Only topology-defined roles (from `team.yaml`) get full MAP agent registrations
 All logic lives in `src/` as importable ES modules. Scripts in `scripts/` are thin CLI wrappers (~20-30 lines each) that parse args, call `src/` functions, and handle stdout/stderr.
 
 ```
-src/config.mjs          ← readConfig(), resolveScope(), resolveTeamName()
-src/paths.mjs            ← SWARM_DIR, CONFIG_PATH, TMP_DIR, TEAMS_DIR, MAP_DIR, teamDir()
-src/roles.mjs            ← readRoles(), matchRole(), writeRoles()
-src/inbox.mjs            ← readInbox(), clearInbox(), formatInboxAsMarkdown()
-src/map-connection.mjs   ← connectToMAP(), fireAndForget(), fireAndForgetTrajectory()
-src/sidecar-client.mjs   ← sendToSidecar(), ensureSidecar(), startSidecar()
-src/sidecar-server.mjs   ← createSocketServer(), createCommandHandler()
-src/map-events.mjs       ← sendCommand(), emitPayload(), build*Command(), build*Payload()
-src/sessionlog.mjs       ← findActiveSession(), buildTrajectoryCheckpoint(), syncSessionlog()
-src/template.mjs         ← resolveTemplatePath(), listAvailableTemplates(), generateTeamArtifacts()
-src/agent-generator.mjs  ← generateAllAgents(), generateAgentMd()
-src/context-output.mjs   ← format*Context(), format*Message()
-src/bootstrap.mjs        ← bootstrap() — full SessionStart orchestration
-src/index.mjs            ← barrel re-export of public API
+src/config.mjs            ← readConfig(), resolveScope(), resolveTeamName()
+src/paths.mjs              ← SWARM_DIR, CONFIG_PATH, TMP_DIR, TEAMS_DIR, MAP_DIR, teamDir()
+src/roles.mjs              ← readRoles(), matchRole(), writeRoles()
+src/inbox.mjs              ← readInbox(), clearInbox(), formatInboxAsMarkdown()
+src/map-connection.mjs     ← connectToMAP(), fireAndForget(), fireAndForgetTrajectory()
+src/mesh-connection.mjs    ← createMeshPeer(), createMeshInbox(), meshFireAndForget()
+src/sidecar-client.mjs     ← sendToSidecar(), ensureSidecar(), startSidecar()
+src/sidecar-server.mjs     ← createSocketServer(), createCommandHandler()
+src/map-events.mjs         ← sendCommand(), emitPayload(), build*Command(), handle*Event()
+src/opentasks-client.mjs   ← createTask(), updateTask(), pushSyncEvent(), findSocketPath()
+src/skilltree-client.mjs   ← parseSkillTreeExtension(), compileRoleLoadout(), compileAllRoleLoadouts()
+src/sessionlog.mjs         ← findActiveSession(), buildTrajectoryCheckpoint(), syncSessionlog()
+src/template.mjs           ← resolveTemplatePath(), listAvailableTemplates(), generateTeamArtifacts()
+src/agent-generator.mjs    ← generateAllAgents(), generateAgentMd()
+src/context-output.mjs     ← format*Context(), format*Message()
+src/bootstrap.mjs          ← bootstrap() — full SessionStart orchestration
+src/index.mjs              ← barrel re-export of public API
 ```
 
 ## Key dependencies
@@ -255,7 +408,11 @@ Local (installed via `npm install --production` in plugin directory):
 Global (managed by swarmkit, installed on demand during bootstrap):
 - **openteams** — team topology parsing and artifact generation (always installed)
 - **@multi-agent-protocol/sdk** — MAP protocol client (installed when `map.enabled: true`)
+- **agentic-mesh** — encrypted P2P mesh transport with embedded MeshPeer (installed when `mesh.enabled: true`)
+- **agent-inbox** — MAP-native message router with structured messaging (installed when `inbox.enabled: true`)
 - **sessionlog** — git-integrated session capture (installed when `sessionlog.enabled: true`)
+- **minimem** — file-based memory with vector search (installed when `minimem.enabled: true`)
+- **skill-tree** — versioned skill library with serving layer (installed when `skilltree.enabled: true`)
 
 Runtime:
 - **Claude Code agent teams** — enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json
@@ -267,4 +424,7 @@ Runtime:
 - Switching between templates is instant if previously cached — artifacts are stored per template in `.swarm/claude-swarm/tmp/teams/<template>/`
 - openteams is config/generation only — Claude Code native teams handle all runtime coordination, MAP handles external observability
 - All logic is in `src/` modules — scripts are thin wrappers, making functions importable and testable
+- Agent spawning/completion hooks are purely MAP agent lifecycle — they do not create or complete tasks. Task creation is handled by agents using `TaskCreate` (native) or opentasks MCP tools
+- Native Claude tasks enter the OpenTasks graph via the `claude-tasks` provider's filesystem watcher, not via swarm hooks. Swarm hooks for `TaskCreate`/`TaskUpdate` only emit MAP bridge events
+- The `opentasks-client.mjs` communicates with the OpenTasks daemon via JSON-RPC 2.0 over Unix socket with best-effort auto-recovery
 - See `docs/design.md` for detailed architecture decisions and `docs/implementation-plan.md` for phase breakdown