claude-code-swarm 0.3.23 → 0.3.25

package/src/__tests__/skilltree-client.test.mjs

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { parseSkillTreeExtension, inferProfileFromRole } from "../skilltree-client.mjs";
+import {
+  parseSkillTreeExtension,
+  inferProfileFromRole,
+  computeRoleCriteria,
+} from "../skilltree-client.mjs";
 
 describe("skilltree-client", () => {
   describe("parseSkillTreeExtension", () => {
@@ -123,4 +127,184 @@ describe("skilltree-client", () => {
       expect(inferProfileFromRole("quick-flow-dev")).toBe("implementation");
     });
   });
+
+  describe("computeRoleCriteria — priority chain", () => {
+    const baseManifest = { name: "t", roles: ["worker"] };
+
+    it("uses skilltree extension defaults when no per-role override", () => {
+      const out = computeRoleCriteria("worker", {
+        ...baseManifest,
+        skilltree: { defaults: { profile: "implementation", maxSkills: 4 } },
+      });
+      expect(out).toEqual({ profile: "implementation", maxSkills: 4 });
+    });
+
+    it("merges per-role override over defaults", () => {
+      const out = computeRoleCriteria("worker", {
+        ...baseManifest,
+        skilltree: {
+          defaults: { profile: "implementation", maxSkills: 4 },
+          roles: { worker: { profile: "code-review" } },
+        },
+      });
+      expect(out.profile).toBe("code-review");
+      expect(out.maxSkills).toBe(4);
+    });
+
+    it("openteams loadout.skills overlays on top of skilltree extension", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { profile: "security" } } }],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: { defaults: { profile: "implementation" } },
+        },
+        {},
+        template,
+      );
+      // openteams wins on profile (replace-if-set)
+      expect(out.profile).toBe("security");
+    });
+
+    it("openteams include unions with skilltree extension include", () => {
+      const template = {
+        roles: new Map([
+          [
+            "worker",
+            { loadout: { skills: { include: ["b", "c"] } } },
+          ],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: {
+            roles: { worker: { profile: "x", include: ["a", "b"] } },
+          },
+        },
+        {},
+        template,
+      );
+      expect([...out.include].sort()).toEqual(["a", "b", "c"]);
+    });
+
+    it("openteams max_tokens renames to maxTokens and replaces", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { max_tokens: 30000 } } }],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: { defaults: { profile: "x", maxTokens: 8000 } },
+        },
+        {},
+        template,
+      );
+      expect(out.maxTokens).toBe(30000);
+    });
+
+    it("falls back to config.defaultProfile when no skill-bearing criteria", () => {
+      const out = computeRoleCriteria(
+        "novel-role",
+        baseManifest,
+        { defaultProfile: "documentation" },
+      );
+      expect(out.profile).toBe("documentation");
+    });
+
+    it("falls back to inferProfileFromRole when no defaultProfile", () => {
+      const out = computeRoleCriteria("verifier", baseManifest);
+      expect(out.profile).toBe("testing");
+    });
+
+    it("returns null when no criteria can be derived", () => {
+      const out = computeRoleCriteria("brand-new-role-xyz", baseManifest);
+      expect(out).toBeNull();
+    });
+
+    it("does not invoke fallback chain when criteria already has tags", () => {
+      const out = computeRoleCriteria("worker", {
+        ...baseManifest,
+        skilltree: { defaults: { tags: ["typescript"] } },
+      });
+      expect(out.tags).toEqual(["typescript"]);
+      expect(out.profile).toBeUndefined();
+    });
+
+    it("does not invoke fallback chain when openteams provided include", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { include: ["x"] } } }],
+        ]),
+      };
+      const out = computeRoleCriteria("worker", baseManifest, {}, template);
+      expect(out.include).toEqual(["x"]);
+      // No fallback profile assigned
+      expect(out.profile).toBeUndefined();
+    });
+
+    it("accepts template.roles as a plain object (not just Map)", () => {
+      const template = {
+        roles: { worker: { loadout: { skills: { profile: "security" } } } },
+      };
+      const out = computeRoleCriteria("worker", baseManifest, {}, template);
+      expect(out.profile).toBe("security");
+    });
+
+    it("openteams overlay precedes fallback (no defaultProfile applied if openteams set profile)", () => {
+      const template = {
+        roles: new Map([
+          ["worker", { loadout: { skills: { profile: "security" } } }],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        baseManifest,
+        { defaultProfile: "implementation" },
+        template,
+      );
+      expect(out.profile).toBe("security");
+    });
+
+    it("preserves criteria fields openteams does not declare", () => {
+      const template = {
+        roles: new Map([
+          [
+            "worker",
+            { loadout: { skills: { profile: "security" } } },
+          ],
+        ]),
+      };
+      const out = computeRoleCriteria(
+        "worker",
+        {
+          ...baseManifest,
+          skilltree: {
+            roles: {
+              worker: {
+                profile: "x",
+                tags: ["typescript"],
+                keywords: ["frontend"],
+                maxSkills: 6,
+              },
+            },
+          },
+        },
+        {},
+        template,
+      );
+      expect(out.profile).toBe("security");
+      expect(out.tags).toEqual(["typescript"]);
+      expect(out.keywords).toEqual(["frontend"]);
+      expect(out.maxSkills).toBe(6);
+    });
+  });
 });

package/src/agent-generator.mjs

@@ -7,7 +7,16 @@
 
 import fs from "fs";
 import path from "path";
+import yaml from "js-yaml";
 import { buildCapabilitiesContext } from "./context-output.mjs";
+import { materializeLoadout } from "./loadout-materializer.mjs";
+
+/**
+ * Default command path for the scope-check PreToolUse hook.
+ * Claude Code expands ${CLAUDE_PLUGIN_ROOT} at runtime.
+ */
+const DEFAULT_HOOK_COMMAND =
+  "${CLAUDE_PLUGIN_ROOT}/scripts/scope-check.mjs";
 
 /**
  * Parse team.yaml without js-yaml dependency (basic YAML subset).
@@ -43,6 +52,67 @@ export function parseBasicYaml(content) {
   return result;
 }
 
+/**
+ * Build the frontmatter lines for an AGENT.md file.
+ *
+ * When `loadout` is provided, uses the loadout-materializer to produce
+ * enriched frontmatter (mcpServers, disallowedTools, hooks, capabilities).
+ * Otherwise falls back to the minimal legacy shape (name, description,
+ * model, tools).
+ *
+ * Returns an array of lines (no leading/trailing `---`).
+ */
+export function buildAgentFrontmatterLines({
+  roleName,
+  teamName,
+  description,
+  model,
+  tools,
+  loadout,
+  template,
+  hookCommand,
+  scopeFilePath,
+  projectPath,
+  position,
+}) {
+  if (!loadout) {
+    // Legacy minimal frontmatter — preserved verbatim for back-compat.
+    const lines = [];
+    lines.push(`name: ${teamName}-${roleName}`);
+    lines.push(`description: "${(description ?? "").replace(/"/g, '\\"')}"`);
+    if (model) lines.push(`model: ${model}`);
+    if (tools && tools.length > 0) {
+      lines.push(`tools: [${tools.join(", ")}]`);
+    }
+    return lines;
+  }
+
+  // Loadout-enriched frontmatter via materializer.
+  const { frontmatter } = materializeLoadout({
+    role: { name: roleName, description },
+    loadout,
+    template,
+    options: {
+      teamName,
+      hookCommand,
+      scopeFilePath,
+      projectPath,
+      nativeTools: tools,
+      position,
+    },
+  });
+  if (model) frontmatter.model = model;
+
+  // Serialize via js-yaml and split into lines so the caller can emit
+  // them between `---` fences.
+  const dumped = yaml.dump(frontmatter, {
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: false,
+  });
+  return dumped.replace(/\n+$/, "").split("\n");
+}
+
 /**
  * Determine which tools an agent needs based on role name, manifest, and position.
  */
@@ -79,6 +149,11 @@ export function determineTools(roleName, manifest, position, options = {}) {
 
 /**
  * Generate a Claude Code AGENT.md file content for a single role.
+ *
+ * When `loadout` is provided, the frontmatter is enriched via the
+ * loadout-materializer — adds mcpServers, disallowedTools, hooks,
+ * capabilities, and generator marker fields. When omitted, falls back
+ * to the legacy minimal frontmatter shape.
  */
 export function generateAgentMd({
   roleName,
@@ -103,19 +178,30 @@ export function generateAgentMd({
   mapEnabled,
   mapStatus,
   sessionlogSync,
+  // Loadout materialization (all optional — fall back to legacy frontmatter if absent)
+  loadout,
+  template,
+  hookCommand,
+  scopeFilePath,
+  projectPath,
 }) {
   const lines = [];
 
   // Claude Code AGENT.md frontmatter
   lines.push("---");
-  lines.push(`name: ${teamName}-${roleName}`);
-  lines.push(`description: "${description.replace(/"/g, '\\"')}"`);
-  if (model) {
-    lines.push(`model: ${model}`);
-  }
-  if (tools && tools.length > 0) {
-    lines.push(`tools: [${tools.join(", ")}]`);
-  }
+  lines.push(...buildAgentFrontmatterLines({
+    roleName,
+    teamName,
+    description,
+    model,
+    tools,
+    loadout,
+    template,
+    hookCommand: hookCommand || DEFAULT_HOOK_COMMAND,
+    scopeFilePath,
+    projectPath,
+    position,
+  }));
   lines.push("---");
   lines.push("");
 
@@ -292,6 +378,41 @@ export async function generateAllAgents(templateDir, outputDir, options = {}) {
 
       const tools = determineTools(roleName, manifest, position, options);
 
+      // Compute the scope file path the per-agent hook will read at runtime.
+      // Default: sibling of the agents output dir (<output>/../scope/<role>.json).
+      // When the role has a loadout, we ALSO write the scope file there so
+      // the frontmatter's SCOPE_FILE path always resolves at runtime.
+      const scopeDirAbs = options.scopeBasePath
+        ? path.resolve(options.scopeBasePath)
+        : path.resolve(absOutputDir, "..", "scope");
+      const scopeFileAbs = path.join(scopeDirAbs, `${roleName}.json`);
+      const scopeFilePath = options.projectPath
+        ? path.relative(options.projectPath, scopeFileAbs)
+        : scopeFileAbs;
+
+      if (role?.loadout) {
+        try {
+          const { scopeFile: scopeFileContent } = materializeLoadout({
+            role: {
+              name: roleName,
+              description: role.description,
+              displayName: role.displayName,
+            },
+            loadout: role.loadout,
+            template,
+            options: { teamName, scopeFilePath },
+          });
+          fs.mkdirSync(scopeDirAbs, { recursive: true });
+          fs.writeFileSync(
+            scopeFileAbs,
+            JSON.stringify(scopeFileContent, null, 2),
+            "utf-8"
+          );
+        } catch {
+          // Non-fatal — frontmatter still references the path; hook fails open
+        }
+      }
+
       const agentMd = generateAgentMd({
         roleName,
         teamName,
@@ -301,6 +422,12 @@ export async function generateAllAgents(templateDir, outputDir, options = {}) {
         tools,
         skillContent: roleSkill.content,
         manifest,
+        // Loadout integration (only kicks in when role.loadout is set in openteams)
+        loadout: role?.loadout,
+        template,
+        scopeFilePath,
+        projectPath: options.projectPath,
+        hookCommand: options.hookCommand,
         opentasksEnabled: options.opentasksEnabled,
         opentasksStatus: options.opentasksStatus,
         minimemEnabled: options.minimemEnabled,

package/src/context-output.mjs

@@ -7,6 +7,8 @@
  */
 
 import fs from "fs";
+import path from "path";
+import { formatHealthReport } from "./mcp-health-checker.mjs";
 
 // ── Capabilities context (shared between main agent + spawned agents) ────────
 
@@ -259,6 +261,36 @@ export function formatBootstrapContext({
 
     lines.push(`Agent prompts: \`${team.outputDir}/agents/<role>.md\``);
     lines.push("");
+
+    // MCP health report (from loadout-aware caching) — non-blocking, informational.
+    // Only surface when the team declared providers or any loadout referenced
+    // a server; otherwise skip silently to avoid noise in non-loadout templates.
+    try {
+      const healthPath = path.join(team.outputDir, "mcp-health.json");
+      if (fs.existsSync(healthPath)) {
+        const report = JSON.parse(fs.readFileSync(healthPath, "utf-8"));
+        const anything =
+          (report.ok?.length ?? 0) +
+          (report.missing?.length ?? 0) +
+          (report.refs?.length ?? 0) +
+          (report.disabled?.length ?? 0) +
+          (report.orphanedReferences?.length ?? 0);
+        if (anything > 0) {
+          const rendered = formatHealthReport(report, { teamName: team.teamName });
+          lines.push(rendered);
+          lines.push("");
+          if (report.missing?.length > 0 || report.orphanedReferences?.length > 0) {
+            lines.push(
+              "Run `/swarm-mcp check` for details or `/swarm-mcp install <name>` " +
+                "to explicitly add a declared provider to your `.mcp.json`."
+            );
+            lines.push("");
+          }
+        }
+      }
+    } catch {
+      // Non-fatal — health is informational, never blocks bootstrap.
+    }
   }
 
   lines.push(