claude-code-swarm 0.3.5 → 0.3.7

package/src/bootstrap.mjs

@@ -12,11 +12,11 @@
 
 import fs from "fs";
 import { execSync } from "child_process";
-import { readConfig, resolveScope } from "./config.mjs";
+import { readConfig, resolveScope, resolveTeamName } from "./config.mjs";
 import { SOCKET_PATH, MAP_DIR, pluginDir, ensureSwarmDir, ensureOpentasksDir, ensureSessionDir, listSessionDirs } from "./paths.mjs";
 import { findSocketPath, isDaemonAlive, ensureDaemon } from "./opentasks-client.mjs";
 import { loadTeam } from "./template.mjs";
-import { killSidecar, startSidecar } from "./sidecar-client.mjs";
+import { killSidecar, startSidecar, sendToInbox } from "./sidecar-client.mjs";
 import { checkSessionlogStatus, syncSessionlog } from "./sessionlog.mjs";
 import { resolveSwarmkit, configureNodePath } from "./swarmkit-resolver.mjs";
 
@@ -316,7 +316,28 @@ export async function bootstrap(pluginDirOverride, sessionId) {
     }
   }
 
-  // 3b. Initial sessionlog sync (fire and forget)
+  // 3b. Register main agent in inbox for message routing
+  if (config.map.enabled && config.inbox?.enabled) {
+    const teamName = resolveTeamName(config);
+    const sPaths = sessionId
+      ? (await import("./paths.mjs")).sessionPaths(sessionId)
+      : { inboxSocketPath: (await import("./paths.mjs")).INBOX_SOCKET_PATH };
+    sendToInbox({
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: {
+          agentId: `${teamName}-main`,
+          name: `${teamName}-main`,
+          role: "orchestrator",
+          scopes: [scope],
+          metadata: { isMain: true, sessionId },
+        },
+      },
+    }, sPaths.inboxSocketPath).catch(() => {});
+  }
+
+  // 3c. Initial sessionlog sync (fire and forget)
   if (config.map.enabled && config.sessionlog.sync !== "off") {
     syncSessionlog(config, sessionId).catch(() => {});
   }

package/src/context-output.mjs

@@ -2,72 +2,249 @@
  * context-output.mjs — Markdown formatting for hook stdout
  *
  * Generates the markdown context that gets injected into Claude's conversation
- * by SessionStart and team-loader hooks.
+ * by SessionStart and team-loader hooks. Also provides buildCapabilitiesContext()
+ * which is shared between SessionStart injection and AGENT.md generation.
  */
 
 import fs from "fs";
 
+// ── Capabilities context (shared between main agent + spawned agents) ────────
+
 /**
- * Format the SessionStart bootstrap context.
+ * Build the unified capabilities context markdown.
+ *
+ * Assembles conditional sections based on which capabilities are enabled.
+ * Used by:
+ *   - formatBootstrapContext() → injected into main agent via SessionStart stdout
+ *   - generateAgentMd() → embedded in each spawned agent's AGENT.md
+ *
+ * @param {object} options
+ * @param {string|null} options.role - null for main agent, role name for spawned agents
+ * @param {boolean} options.opentasksEnabled
+ * @param {string}  options.opentasksStatus - "connected", "enabled", "disabled", etc.
+ * @param {boolean} options.minimemEnabled
+ * @param {string}  options.minimemStatus - "ready", "installed", "disabled"
+ * @param {boolean} options.skilltreeEnabled
+ * @param {string}  options.skilltreeStatus - "ready", "installed", "disabled"
+ * @param {boolean} options.inboxEnabled
+ * @param {boolean} options.meshEnabled
+ * @param {boolean} options.mapEnabled
+ * @param {string}  options.mapStatus - "connected (scope: ...)", "disabled", etc.
+ * @param {string}  options.sessionlogSync - "off", "lifecycle", "metrics", "full"
+ * @param {string}  options.teamName - team name for spawned agent context
+ * @returns {string} Markdown capabilities context
  */
-export function formatBootstrapContext({
-  template,
-  team,
-  mapStatus,
-  sessionlogStatus,
-  sessionlogSync,
-  opentasksStatus,
-  inboxEnabled,
-  minimemStatus,
-  skilltreeStatus,
-}) {
-  const lines = ["## Claude Code Swarm", ""];
+export function buildCapabilitiesContext({
+  role = null,
+  opentasksEnabled = false,
+  opentasksStatus = "disabled",
+  minimemEnabled = false,
+  minimemStatus = "disabled",
+  skilltreeEnabled = false,
+  skilltreeStatus = "disabled",
+  skillProfile = "",
+  inboxEnabled = false,
+  meshEnabled = false,
+  mapEnabled = false,
+  mapStatus = "disabled",
+  sessionlogSync = "off",
+  teamName = "",
+} = {}) {
+  const isAgent = role !== null;
+  const lines = ["## Swarm Capabilities", ""];
 
-  if (template) {
-    lines.push(`Team template configured: **${template}**`);
+  // ── Team Orchestration ───────────────────────────────────────────────
+  lines.push("### Team Orchestration");
+  lines.push("");
+  if (isAgent) {
+    lines.push(`You are part of the **${teamName}** team. The orchestrator spawns and coordinates all teammates — spawned agents cannot spawn other agents.`);
   } else {
-    lines.push("No team template configured.");
+    lines.push("Use `/swarm` to launch a team from the configured topology, or `/swarm <template>` to pick a different one.");
+    lines.push("Available templates: **gsd**, **bmad-method**, **bug-fix-pipeline**, **docs-sync**, **security-audit**, and more.");
+    lines.push("Only the orchestrator spawns teammates — spawned agents cannot spawn other agents.");
   }
+  lines.push("");
 
-  if (mapStatus) {
-    lines.push(`MAP: ${mapStatus}`);
+  // ── Task Management ──────────────────────────────────────────────────
+  lines.push("### Task Management");
+  lines.push("");
+  const otActive = opentasksEnabled && (opentasksStatus === "connected" || opentasksStatus === "enabled");
+  if (otActive) {
+    lines.push("Use **opentasks MCP tools** for task management:");
+    lines.push("- `opentasks__create_task` — create tasks with metadata and links");
+    lines.push("- `opentasks__update_task` — claim, update status, annotate");
+    lines.push("- `opentasks__list_tasks` / `opentasks__query` — check progress, filter by status/assignee");
+    lines.push("Cross-system task graph supports linking (`opentasks__link`) and annotations.");
+    lines.push("Native Claude tasks are auto-federated into the graph via the claude-tasks provider.");
+  } else {
+    lines.push("Use Claude Code native task tools:");
+    lines.push("- `TaskCreate` — create tasks for the team");
+    lines.push("- `TaskUpdate` — claim (set owner), update status");
+    lines.push("- `TaskList` — check progress");
+    lines.push("Tasks are shared team-wide when agents use the same `team_name`.");
   }
+  lines.push("");
 
-  if (sessionlogStatus) {
-    if (sessionlogStatus === "active") {
-      let syncLabel = "";
-      if (sessionlogSync && sessionlogSync !== "off") {
-        syncLabel = ` (MAP sync: ${sessionlogSync})`;
+  // ── Communication ────────────────────────────────────────────────────
+  lines.push("### Communication");
+  lines.push("");
+  lines.push("Use `SendMessage` for quick same-team agent-to-agent messaging:");
+  lines.push("- Direct: `SendMessage(recipient=\"<agent-name>\", content=\"...\")`");
+  lines.push("- Broadcast only when truly necessary (messages every teammate).");
+  lines.push("");
+  if (inboxEnabled) {
+    lines.push("**Structured messaging** via agent-inbox MCP tools (persistent, threaded, cross-system):");
+    lines.push("- `agent-inbox__check_inbox(agentId)` — check for new messages (auto-marks as read)");
+    lines.push("- `agent-inbox__send_message(to, body, from)` — send to an agent, or `agent@system` for federated");
+    lines.push("- `agent-inbox__read_thread(threadTag)` — read full conversation thread");
+    lines.push("- `agent-inbox__list_agents()` — see who is registered (local + federated)");
+    lines.push("");
+    lines.push("Use inbox for: cross-system messages, threaded conversations, delivery tracking, messaging external observers.");
+    lines.push("Use `SendMessage` for: quick same-team coordination that doesn't need persistence.");
+  }
+  if (meshEnabled) {
+    lines.push("Encrypted P2P transport via MeshPeer with agent discovery.");
+  }
+  lines.push("");
+
+  // ── Memory (minimem) ────────────────────────────────────────────────
+  if (minimemEnabled && minimemStatus !== "disabled") {
+    lines.push("### Memory");
+    lines.push("");
+    if (minimemStatus === "ready") {
+      lines.push("Use **minimem MCP tools** for persistent, searchable team memory. Memory is shared team-wide.");
+      lines.push("");
+      lines.push("**Searching (two-phase workflow):**");
+      lines.push("1. `minimem__memory_search(query)` — returns compact index (path, score, preview)");
+      lines.push("2. `minimem__memory_get_details(results)` — fetch full text for relevant results");
+      lines.push("Use `detail: \"full\"` for quick lookups. Filter by type: `type: \"decision\"` (decision, bugfix, feature, discovery, context, note).");
+      lines.push("");
+      lines.push("**Knowledge search** (structured metadata):");
+      lines.push("- `minimem__knowledge_search(query, { domain, entities, minConfidence })` — filter by domain/entity/confidence");
+      lines.push("- `minimem__knowledge_graph(nodeId, depth)` — traverse knowledge relationships");
+      lines.push("- `minimem__knowledge_path(fromId, toId)` — find path between knowledge nodes");
+      lines.push("");
+      if (!isAgent) {
+        lines.push("**Storing memories** (use filesystem tools to write Markdown):");
+        lines.push("- `MEMORY.md` — important decisions and architecture notes");
+        lines.push("- `memory/YYYY-MM-DD.md` — daily logs and session notes");
+        lines.push("- `memory/<topic>.md` — topic-specific files");
+        lines.push("");
+        lines.push("Format entries with a type comment for filtered search:");
+        lines.push("```");
+        lines.push("### YYYY-MM-DD HH:MM");
+        lines.push("<!-- type: decision -->");
+        lines.push("<content>");
+        lines.push("```");
+        lines.push("Types: `decision`, `bugfix`, `feature`, `discovery`, `context`, `note`.");
+        lines.push("Wrap secrets in `<private>` tags to exclude from indexing.");
+        lines.push("");
+        lines.push("**Team strategy**: Search memory before spawning agents for prior context on the user's goal. After team completion, store key decisions and outcomes.");
+        lines.push("");
+      } else {
+        lines.push("**Before major work**: Search memory for relevant prior decisions and context.");
+        lines.push("**After completing work**: Store key decisions and findings using filesystem tools — write to `memory/` files with `<!-- type: decision -->` tags.");
+        lines.push("");
       }
-      lines.push(`Sessionlog: active${syncLabel}`);
-    } else if (sessionlogStatus !== "not installed") {
-      lines.push(`Sessionlog: WARNING — configured but ${sessionlogStatus}`);
+    } else {
+      lines.push(`Memory: ${minimemStatus} (minimem installed but not fully ready).`);
+      lines.push("");
     }
   }
 
-  if (opentasksStatus) {
-    lines.push(`Opentasks: ${opentasksStatus}`);
-    if (opentasksStatus === "connected" || opentasksStatus === "enabled") {
-      lines.push("Use **opentasks MCP tools** (opentasks__create_task, opentasks__update_task, opentasks__list_tasks) for task management instead of native TaskCreate/TaskUpdate/TaskList.");
+  // ── Per-Role Skills (skill-tree) ─────────────────────────────────────
+  if (skilltreeEnabled && skilltreeStatus !== "disabled") {
+    lines.push("### Per-Role Skills");
+    lines.push("");
+    if (isAgent) {
+      lines.push("Your **skill loadout** is embedded in the `## Skills` section above. These are versioned, reusable patterns selected for your role.");
+      if (skillProfile) {
+        lines.push(`Your loadout was compiled from the **${skillProfile}** profile.`);
+      }
+      lines.push("Read and apply these skills to guide your approach — they represent proven patterns for your type of work.");
+    } else {
+      lines.push("Each spawned agent receives a **skill loadout** compiled per-role and embedded in their AGENT.md.");
+      lines.push("Skills are versioned, reusable patterns from the skill-tree library, selected based on role profiles.");
+      lines.push("");
+      lines.push("Loadouts are configured via the `skilltree:` block in team.yaml, or auto-inferred from role names.");
+      lines.push("Built-in profiles: **code-review**, **implementation**, **debugging**, **security**, **testing**, **refactoring**, **documentation**, **devops**.");
+      lines.push("Skills are cached per template — delete the template cache to refresh.");
     }
+    lines.push("");
   }
 
-  if (inboxEnabled) {
-    lines.push("Inbox: enabled (agent-inbox messaging)");
+  // ── External Observability (MAP) ─────────────────────────────────────
+  lines.push("### External Observability");
+  lines.push("");
+  if (mapEnabled) {
+    if (isAgent) {
+      lines.push("MAP is active — lifecycle and task events are emitted automatically by hooks. No direct interaction needed.");
+    } else {
+      lines.push(`MAP: ${mapStatus}`);
+      lines.push("Agent lifecycle and task events are emitted automatically by hooks. No direct MAP interaction needed.");
+    }
+    if (sessionlogSync && sessionlogSync !== "off") {
+      lines.push(`Session trajectory checkpoints synced to MAP (level: ${sessionlogSync}).`);
+    }
+  } else {
+    lines.push("No external observability configured.");
   }
+  lines.push("");
 
-  if (minimemStatus && minimemStatus !== "disabled") {
-    lines.push(`Memory: ${minimemStatus}`);
-    if (minimemStatus === "ready") {
-      lines.push("Use **minimem MCP tools** (minimem__memory_search, minimem__knowledge_search) to recall past decisions and context.");
-    }
+  return lines.join("\n");
+}
+
+// ── SessionStart context ─────────────────────────────────────────────────────
+
+/**
+ * Format the SessionStart bootstrap context.
+ */
+export function formatBootstrapContext({
+  template,
+  team,
+  mapEnabled = false,
+  mapStatus,
+  sessionlogStatus,
+  sessionlogSync,
+  opentasksEnabled = false,
+  opentasksStatus = "disabled",
+  inboxEnabled = false,
+  meshEnabled = false,
+  minimemEnabled = false,
+  minimemStatus = "disabled",
+  skilltreeEnabled = false,
+  skilltreeStatus = "disabled",
+}) {
+  const lines = ["## Claude Code Swarm", ""];
+
+  if (template) {
+    lines.push(`Team template configured: **${template}**`);
+  } else {
+    lines.push("No team template configured.");
   }
+  lines.push("");
 
-  if (skilltreeStatus && skilltreeStatus !== "disabled") {
-    lines.push(`Skills: ${skilltreeStatus} (per-role loadouts from team.yaml)`);
+  // Sessionlog warning (non-capability — surface config issues)
+  if (sessionlogStatus && sessionlogStatus !== "active" && sessionlogStatus !== "not installed") {
+    lines.push(`Sessionlog: WARNING — configured but ${sessionlogStatus}`);
+    lines.push("");
   }
 
-  lines.push("");
+  // Capabilities context
+  lines.push(buildCapabilitiesContext({
+    role: null,
+    opentasksEnabled,
+    opentasksStatus,
+    minimemEnabled,
+    minimemStatus,
+    skilltreeEnabled,
+    skilltreeStatus,
+    inboxEnabled,
+    meshEnabled,
+    mapEnabled,
+    mapStatus: mapStatus || "disabled",
+    sessionlogSync: sessionlogSync || "off",
+  }));
 
   if (team) {
     // Embed the SKILL.md content directly so the agent has the topology immediately
@@ -87,7 +264,6 @@ export function formatBootstrapContext({
   lines.push(
     "Use `/swarm` to launch the team (creates a native Claude Code team)."
   );
-  lines.push("Templates available via openteams: **gsd**, **bmad-method**, **bug-fix-pipeline**, **docs-sync** (and more)");
   lines.push("");
 
   return lines.join("\n");
@@ -95,8 +271,9 @@ export function formatBootstrapContext({
 
 /**
  * Format the team-loaded context output.
+ * Uses buildCapabilitiesContext for coordination/tool instructions.
  */
-export function formatTeamLoadedContext(generatedDir, templatePath, teamName, { opentasksStatus } = {}) {
+export function formatTeamLoadedContext(generatedDir, templatePath, teamName, options = {}) {
   const lines = ["## Claude Code Swarm — Team Loaded", ""];
 
   // Include the catalog if available
@@ -121,13 +298,13 @@ export function formatTeamLoadedContext(generatedDir, templatePath, teamName, {
     "1. Call **TeamCreate** to set up a native Claude Code team"
   );
   lines.push(
-    "2. Create tasks via **TaskCreate** based on the user's goal"
+    "2. Create tasks based on the user's goal"
   );
   lines.push(
     "3. Spawn agents directly as teammates (only you can spawn — teammates cannot spawn other teammates)"
   );
   lines.push(
-    "4. Coordinate the team via **SendMessage** and track progress via **TaskUpdate**"
+    "4. Coordinate the team via **SendMessage** and track progress"
   );
   lines.push("");
   lines.push(
@@ -137,25 +314,22 @@ export function formatTeamLoadedContext(generatedDir, templatePath, teamName, {
     "Read a role's agent prompt before spawning an agent for that role."
   );
   lines.push("");
-  lines.push("### Coordination");
-  lines.push("");
-  if (opentasksStatus === "connected" || opentasksStatus === "enabled") {
-    lines.push("This team uses **opentasks MCP tools** for task management:");
-    lines.push("- **opentasks__create_task / opentasks__update_task / opentasks__list_tasks** for task lifecycle");
-    lines.push("- **SendMessage** for agent-to-agent communication");
-    lines.push("- **TeamCreate** for team setup");
-  } else {
-    lines.push("This team uses Claude Code's native team features:");
-    lines.push("- **TaskCreate/TaskUpdate** for task lifecycle");
-    lines.push("- **SendMessage** for agent-to-agent communication");
-    lines.push("- **TeamCreate** for team setup");
-  }
-  lines.push("");
-  lines.push(
-    "**MAP (if enabled):** Lifecycle events are emitted for external observability."
-  );
-  lines.push("Agents do not interact with MAP directly.");
-  lines.push("");
+
+  // Capabilities context for coordination details
+  lines.push(buildCapabilitiesContext({
+    role: null,
+    opentasksEnabled: options.opentasksEnabled,
+    opentasksStatus: options.opentasksStatus || "disabled",
+    minimemEnabled: options.minimemEnabled,
+    minimemStatus: options.minimemStatus || "disabled",
+    skilltreeEnabled: options.skilltreeEnabled,
+    skilltreeStatus: options.skilltreeStatus || "disabled",
+    inboxEnabled: options.inboxEnabled,
+    meshEnabled: options.meshEnabled,
+    mapEnabled: options.mapEnabled,
+    mapStatus: options.mapStatus || "disabled",
+    sessionlogSync: options.sessionlogSync || "off",
+  }));
 
   return lines.join("\n");
 }

package/src/index.mjs

@@ -41,6 +41,7 @@ export { formatInboxAsMarkdown, formatAge } from "./inbox.mjs";
 
 // Context output
 export {
+  buildCapabilitiesContext,
   formatBootstrapContext,
   formatTeamLoadedContext,
   formatNoTemplateMessage,
@@ -123,6 +124,7 @@ export {
   parseSkillTreeExtension,
   compileRoleLoadout,
   compileAllRoleLoadouts,
+  inferProfileFromRole,
 } from "./skilltree-client.mjs";
 
 // Bootstrap

package/src/sidecar-server.mjs

@@ -176,6 +176,21 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
                 metadata,
               });
               registeredAgents.set(agentId, { name, role, metadata });
+
+              // Also register in inbox storage for message routing
+              if (inboxInstance?.storage) {
+                try {
+                  inboxInstance.storage.putAgent({
+                    agent_id: agentId,
+                    scope,
+                    status: "active",
+                    metadata: { name, role, ...metadata },
+                    registered_at: new Date().toISOString(),
+                    last_active_at: new Date().toISOString(),
+                  });
+                } catch { /* best-effort */ }
+              }
+
               respond(client, { ok: true, agent: result });
             } catch (err) {
               process.stderr.write(
@@ -232,6 +247,21 @@ export function createCommandHandler(connection, scope, registeredAgents, opts =
             } catch {
               // Agent may already be gone
             }
+
+            // Also update inbox storage
+            if (inboxInstance?.storage) {
+              try {
+                inboxInstance.storage.putAgent({
+                  agent_id: agentId,
+                  scope,
+                  status: "disconnected",
+                  metadata: {},
+                  registered_at: new Date().toISOString(),
+                  last_active_at: new Date().toISOString(),
+                });
+              } catch { /* best-effort */ }
+            }
+
             registeredAgents.delete(agentId);
           }
           respond(client, { ok: true });

package/src/skilltree-client.mjs

@@ -135,13 +135,49 @@ export async function compileRoleLoadout(roleName, criteria, config) {
   }
 }
 
+/**
+ * Role name → built-in profile auto-mapping.
+ * Used as fallback when no explicit criteria or default profile is configured.
+ */
+const ROLE_PROFILE_MAP = {
+  executor: "implementation",
+  developer: "implementation",
+  "quick-flow-dev": "implementation",
+  debugger: "debugging",
+  verifier: "testing",
+  qa: "testing",
+  "plan-checker": "code-review",
+  "integration-checker": "code-review",
+  "tech-writer": "documentation",
+  architect: "refactoring",
+  "ux-designer": "documentation",
+  "security-auditor": "security",
+};
+
+/**
+ * Infer a skill-tree profile from a role name.
+ * Returns empty string if no match found.
+ */
+export function inferProfileFromRole(roleName) {
+  // Direct match
+  if (ROLE_PROFILE_MAP[roleName]) return ROLE_PROFILE_MAP[roleName];
+
+  // Partial match (e.g., "senior-developer" matches "developer")
+  for (const [pattern, profile] of Object.entries(ROLE_PROFILE_MAP)) {
+    if (roleName.includes(pattern)) return profile;
+  }
+
+  return "";
+}
+
 /**
  * Compile skill loadouts for all roles in a team manifest.
  * Reads the skilltree extension from the manifest, compiles loadouts per role.
+ * Returns metadata alongside content for richer agent context.
  *
  * @param {object} manifest - Parsed team.yaml manifest
  * @param {object} config - Plugin config (skilltree section)
- * @returns {Promise<object>} Map of roleName → loadout markdown
+ * @returns {Promise<object>} Map of roleName → { content, profile }
  */
 export async function compileAllRoleLoadouts(manifest, config) {
   const { defaults, roles: roleOverrides } = parseSkillTreeExtension(manifest);
@@ -152,20 +188,29 @@ export async function compileAllRoleLoadouts(manifest, config) {
     // Merge defaults with role-specific overrides
     const roleCriteria = roleOverrides[roleName]
       ? { ...defaults, ...roleOverrides[roleName] }
-      : defaults;
+      : { ...defaults };
 
-    // Apply config-level default profile as final fallback
+    // Fallback chain for profile selection
     if (!roleCriteria.profile && !roleCriteria.tags && !roleCriteria.include && !roleCriteria.taskDescription) {
       if (config?.defaultProfile) {
         roleCriteria.profile = config.defaultProfile;
       } else {
-        continue; // No criteria at all — skip
+        // Auto-infer from role name
+        const inferred = inferProfileFromRole(roleName);
+        if (inferred) {
+          roleCriteria.profile = inferred;
+        } else {
+          continue; // No criteria at all — skip
+        }
       }
     }
 
     const loadout = await compileRoleLoadout(roleName, roleCriteria, config);
     if (loadout) {
-      result[roleName] = loadout;
+      result[roleName] = {
+        content: loadout,
+        profile: roleCriteria.profile || "",
+      };
     }
   }