squads-cli 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -20,6 +20,17 @@ interface SquadContext {
     /** Cooldown between executions in seconds */
     cooldown?: number;
 }
+/**
+ * Resolved skill with path and source information.
+ */
+interface ResolvedSkill {
+    /** Skill name (directory or reference name) */
+    name: string;
+    /** Absolute path to the skill directory */
+    path: string;
+    /** Where the skill was found */
+    source: 'squad-local' | 'project' | 'global';
+}
 interface SquadProviders {
     /** Default provider for all agents (default: anthropic) */
     default?: string;
@@ -81,7 +92,7 @@ interface Routine {
     /** Agents to run in this batch */
     agents: string[];
     /** Model to use (defaults to squad default or sonnet) */
-    model?: 'opus' | 'sonnet' | 'haiku';
+    model?: string;
     /** Whether the routine is enabled */
     enabled?: boolean;
     /** Priority for execution ordering (lower = higher priority) */
@@ -91,6 +102,8 @@ interface Routine {
 }
 interface Squad {
     name: string;
+    /** Directory name for file path resolution (e.g., "engineering") */
+    dir: string;
     mission: string;
     agents: Agent[];
     pipelines: Pipeline[];
@@ -117,18 +130,113 @@ interface Squad {
     /** Raw frontmatter for accessing KPIs and other custom fields */
     frontmatter?: Record<string, unknown>;
 }
+/**
+ * Resolved execution context with paths and metadata.
+ * Extends SquadContext with resolved paths for MCP, skills, and memory.
+ */
+interface ExecutionContext extends SquadContext {
+    /** Squad name this context belongs to */
+    squadName: string;
+    /** Resolved paths and metadata */
+    resolved: {
+        /** Path to MCP config file to use */
+        mcpConfigPath: string;
+        /** Source of MCP config resolution */
+        mcpSource: 'user-override' | 'generated' | 'fallback' | 'squad-local';
+        /** List of MCP servers in the config */
+        mcpServers: string[];
+        /** Resolved skill directory paths (deprecated, use skills instead) */
+        skillPaths: string[];
+        /** Resolved skills with source information */
+        skills: ResolvedSkill[];
+        /** Resolved memory file paths */
+        memoryPaths: string[];
+    };
+}
+/**
+ * Find the .agents/squads directory by searching current directory and parents.
+ * Searches up to 5 parent directories.
+ * @returns Path to squads directory or null if not found
+ */
 declare function findSquadsDir(): string | null;
+/**
+ * Find the root directory of the squads project (where .agents/ lives).
+ * @returns Path to project root or null if not in a squads project
+ */
 declare function findProjectRoot(): string | null;
+/**
+ * List all squad names in the given squads directory.
+ * Only includes directories containing a SQUAD.md file.
+ * @param squadsDir - Path to the .agents/squads directory
+ * @returns Array of squad directory names
+ */
 declare function listSquads(squadsDir: string): string[];
+/**
+ * List all agents in the squads directory or a specific squad.
+ * Agents are markdown files (excluding SQUAD.md) in squad directories.
+ * @param squadsDir - Path to the .agents/squads directory
+ * @param squadName - Optional squad name to filter agents
+ * @returns Array of Agent objects with basic metadata
+ */
 declare function listAgents(squadsDir: string, squadName?: string): Agent[];
+/**
+ * Parse a SQUAD.md file into a Squad object.
+ * Extracts frontmatter metadata, agents, pipelines, goals, and routines.
+ * @param filePath - Path to the SQUAD.md file
+ * @returns Parsed Squad object with all extracted data
+ */
 declare function parseSquadFile(filePath: string): Squad;
+/**
+ * Load and parse a squad by name.
+ * Convenience function that finds the squads directory and parses the squad file.
+ * @param squadName - Name of the squad directory (e.g., "engineering")
+ * @returns Parsed Squad object or null if not found
+ */
 declare function loadSquad(squadName: string): Squad | null;
+/**
+ * Load raw content of an agent definition file.
+ * @param agentPath - Path to the agent markdown file
+ * @returns Raw file content or empty string if file doesn't exist
+ */
 declare function loadAgentDefinition(agentPath: string): string;
+/**
+ * Add a new goal to a squad's SQUAD.md file.
+ * Creates the Goals section if it doesn't exist.
+ * @param squadName - Name of the squad directory
+ * @param goal - Goal description text
+ * @returns True if goal was added successfully
+ */
 declare function addGoalToSquad(squadName: string, goal: string): boolean;
+/**
+ * Update an existing goal in a squad's SQUAD.md file.
+ * Can mark goal as completed or update progress text.
+ * @param squadName - Name of the squad directory
+ * @param goalIndex - Zero-based index of the goal to update
+ * @param updates - Object with optional completed and progress fields
+ * @returns True if goal was updated successfully
+ */
 declare function updateGoalInSquad(squadName: string, goalIndex: number, updates: {
     completed?: boolean;
     progress?: string;
 }): boolean;
+/**
+ * Get all available squad-local skills for a squad.
+ * Scans .agents/squads/<squad>/skills/ directory.
+ */
+declare function getSquadLocalSkills(squadDir: string): ResolvedSkill[];
+/**
+ * Resolve execution context for a squad.
+ *
+ * Takes a Squad object and resolves all context references to actual paths:
+ * - MCP config path (four-tier resolution: squad-local, user-override, generated, fallback)
+ * - Skill directory paths (three-tier: squad-local, project, global)
+ * - Memory file paths
+ *
+ * @param squad - The squad to resolve context for
+ * @param forceRegenerate - Force MCP config regeneration
+ * @returns Resolved execution context with all paths
+ */
+declare function resolveExecutionContext(squad: Squad, forceRegenerate?: boolean): ExecutionContext;
 
 /**
  * Token estimation and tracking for context compression.
@@ -630,4 +738,4 @@ declare function createCondenser(squadConfig?: {
     };
 }): ContextCondenser;
 
-export { type Agent, type CompressionLevel, type CondenserConfig, type CondenserMessage, type CondenserResult, ContextCondenser, ConversationSummarizer, type EffortLevel, FileDeduplicator, type Goal, type Pipeline, type Squad, type SquadContext, type SquadFrontmatter, type ThresholdConfig, TokenPruner, type TokenTracker, addGoalToSquad, createCondenser, createTracker, estimateMessageTokens, estimateTokens, findProjectRoot, findSquadsDir, formatTrackerStatus, getCompressionLevel, listAgents, listSquads, loadAgentDefinition, loadSquad, parseSquadFile, updateGoalInSquad, updateTracker, version };
+export { type Agent, type CompressionLevel, type CondenserConfig, type CondenserMessage, type CondenserResult, ContextCondenser, ConversationSummarizer, type EffortLevel, type ExecutionContext, FileDeduplicator, type Goal, type Pipeline, type ResolvedSkill, type Squad, type SquadContext, type SquadFrontmatter, type ThresholdConfig, TokenPruner, type TokenTracker, addGoalToSquad, createCondenser, createTracker, estimateMessageTokens, estimateTokens, findProjectRoot, findSquadsDir, formatTrackerStatus, getCompressionLevel, getSquadLocalSkills, listAgents, listSquads, loadAgentDefinition, loadSquad, parseSquadFile, resolveExecutionContext, updateGoalInSquad, updateTracker, version };

package/dist/index.js

@@ -5,17 +5,96 @@ var pkg = require2("../package.json");
 var version = pkg.version;
 
 // src/lib/squad-parser.ts
-import { readFileSync, existsSync, readdirSync, writeFileSync } from "fs";
-import { join, basename, dirname } from "path";
+import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2, basename, dirname as dirname2 } from "path";
 import matter from "gray-matter";
+
+// src/lib/mcp-config.ts
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+var SERVER_REGISTRY = {};
+function getHome() {
+  return process.env.HOME || process.env.USERPROFILE || "";
+}
+function getContextsDir() {
+  return join(getHome(), ".claude", "contexts");
+}
+function getMcpConfigsDir() {
+  return join(getHome(), ".claude", "mcp-configs");
+}
+function generateMcpConfig(mcpServers) {
+  const config = { mcpServers: {} };
+  for (const server of mcpServers) {
+    const def = SERVER_REGISTRY[server];
+    if (def) {
+      config.mcpServers[server] = def;
+    }
+  }
+  return config;
+}
+function writeMcpConfig(config, path) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(config, null, 2));
+}
+function readMcpConfig(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const content = readFileSync(path, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function resolveMcpConfig(squadName, mcpServers, forceRegenerate = false) {
+  const home = getHome();
+  const userOverride = join(getMcpConfigsDir(), `${squadName}.json`);
+  if (existsSync(userOverride)) {
+    const config = readMcpConfig(userOverride);
+    return {
+      path: userOverride,
+      source: "user-override",
+      servers: config ? Object.keys(config.mcpServers) : void 0
+    };
+  }
+  if (mcpServers && mcpServers.length > 0) {
+    const generatedPath = join(getContextsDir(), `${squadName}.mcp.json`);
+    const shouldGenerate = forceRegenerate || !existsSync(generatedPath);
+    if (shouldGenerate) {
+      const config2 = generateMcpConfig(mcpServers);
+      writeMcpConfig(config2, generatedPath);
+      return {
+        path: generatedPath,
+        source: "generated",
+        servers: Object.keys(config2.mcpServers),
+        generated: true
+      };
+    }
+    const config = readMcpConfig(generatedPath);
+    return {
+      path: generatedPath,
+      source: "generated",
+      servers: config ? Object.keys(config.mcpServers) : mcpServers,
+      generated: false
+    };
+  }
+  return {
+    path: join(home, ".claude.json"),
+    source: "fallback"
+  };
+}
+
+// src/lib/squad-parser.ts
 function findSquadsDir() {
   let dir = process.cwd();
   for (let i = 0; i < 5; i++) {
-    const squadsPath = join(dir, ".agents", "squads");
-    if (existsSync(squadsPath)) {
+    const squadsPath = join2(dir, ".agents", "squads");
+    if (existsSync2(squadsPath)) {
       return squadsPath;
     }
-    const parent = join(dir, "..");
+    const parent = join2(dir, "..");
     if (parent === dir) break;
     dir = parent;
   }
@@ -24,15 +103,15 @@ function findSquadsDir() {
 function findProjectRoot() {
   const squadsDir = findSquadsDir();
   if (!squadsDir) return null;
-  return join(squadsDir, "..", "..");
+  return join2(squadsDir, "..", "..");
 }
 function listSquads(squadsDir) {
   const squads = [];
   const entries = readdirSync(squadsDir, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isDirectory() && !entry.name.startsWith("_")) {
-      const squadFile = join(squadsDir, entry.name, "SQUAD.md");
-      if (existsSync(squadFile)) {
+      const squadFile = join2(squadsDir, entry.name, "SQUAD.md");
+      if (existsSync2(squadFile)) {
         squads.push(entry.name);
       }
     }
@@ -43,8 +122,8 @@ function listAgents(squadsDir, squadName) {
   const agents = [];
   const dirs = squadName ? [squadName] : readdirSync(squadsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("_")).map((e) => e.name);
   for (const dir of dirs) {
-    const squadPath = join(squadsDir, dir);
-    if (!existsSync(squadPath)) continue;
+    const squadPath = join2(squadsDir, dir);
+    if (!existsSync2(squadPath)) continue;
     const files = readdirSync(squadPath);
     for (const file of files) {
       if (file.endsWith(".md") && file !== "SQUAD.md") {
@@ -53,7 +132,7 @@ function listAgents(squadsDir, squadName) {
           name: agentName,
           role: `Agent in ${dir}`,
           trigger: "manual",
-          filePath: join(squadPath, file)
+          filePath: join2(squadPath, file)
         });
       }
     }
@@ -61,13 +140,16 @@ function listAgents(squadsDir, squadName) {
   return agents;
 }
 function parseSquadFile(filePath) {
-  const rawContent = readFileSync(filePath, "utf-8");
+  const rawContent = readFileSync2(filePath, "utf-8");
   const { data: frontmatter, content: bodyContent } = matter(rawContent);
   const fm = frontmatter;
   const lines = bodyContent.split("\n");
+  const dirName = basename(dirname2(filePath));
   const squad = {
-    // Use directory name (e.g., "demo" from ".agents/squads/demo/SQUAD.md")
-    name: fm.name || basename(dirname(filePath)),
+    // Display name can be different from dir (e.g., "Engineering Squad")
+    name: fm.name || dirName,
+    // Directory name for file path resolution
+    dir: dirName,
     mission: fm.mission || "",
     agents: [],
     pipelines: [],
@@ -187,20 +269,20 @@ function parseSquadFile(filePath) {
 function loadSquad(squadName) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) return null;
-  const squadFile = join(squadsDir, squadName, "SQUAD.md");
-  if (!existsSync(squadFile)) return null;
+  const squadFile = join2(squadsDir, squadName, "SQUAD.md");
+  if (!existsSync2(squadFile)) return null;
   return parseSquadFile(squadFile);
 }
 function loadAgentDefinition(agentPath) {
-  if (!existsSync(agentPath)) return "";
-  return readFileSync(agentPath, "utf-8");
+  if (!existsSync2(agentPath)) return "";
+  return readFileSync2(agentPath, "utf-8");
 }
 function addGoalToSquad(squadName, goal) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) return false;
-  const squadFile = join(squadsDir, squadName, "SQUAD.md");
-  if (!existsSync(squadFile)) return false;
-  let content = readFileSync(squadFile, "utf-8");
+  const squadFile = join2(squadsDir, squadName, "SQUAD.md");
+  if (!existsSync2(squadFile)) return false;
+  let content = readFileSync2(squadFile, "utf-8");
   if (!content.includes("## Goals")) {
     const insertPoint = content.indexOf("## Dependencies");
     if (insertPoint > 0) {
@@ -235,15 +317,15 @@ function addGoalToSquad(squadName, goal) {
 - [ ] ${goal}` + content.slice(headerEnd);
     }
   }
-  writeFileSync(squadFile, content);
+  writeFileSync2(squadFile, content);
   return true;
 }
 function updateGoalInSquad(squadName, goalIndex, updates) {
   const squadsDir = findSquadsDir();
   if (!squadsDir) return false;
-  const squadFile = join(squadsDir, squadName, "SQUAD.md");
-  if (!existsSync(squadFile)) return false;
-  const content = readFileSync(squadFile, "utf-8");
+  const squadFile = join2(squadsDir, squadName, "SQUAD.md");
+  if (!existsSync2(squadFile)) return false;
+  const content = readFileSync2(squadFile, "utf-8");
   const lines = content.split("\n");
   let currentSection = "";
   let goalCount = 0;
@@ -265,7 +347,7 @@ function updateGoalInSquad(squadName, goalIndex, updates) {
             }
           }
           lines[i] = newLine;
-          writeFileSync(squadFile, lines.join("\n"));
+          writeFileSync2(squadFile, lines.join("\n"));
           return true;
         }
         goalCount++;
@@ -274,6 +356,198 @@ function updateGoalInSquad(squadName, goalIndex, updates) {
   }
   return false;
 }
+function findProjectSkillsDir() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) return null;
+  const skillsDir = join2(projectRoot, ".claude", "skills");
+  return existsSync2(skillsDir) ? skillsDir : null;
+}
+function findGlobalSkillsDir() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  if (!home) return null;
+  const skillsDir = join2(home, ".claude", "skills");
+  return existsSync2(skillsDir) ? skillsDir : null;
+}
+function findSquadLocalSkillsDir(squadDir) {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return null;
+  const skillsDir = join2(squadsDir, squadDir, "skills");
+  return existsSync2(skillsDir) ? skillsDir : null;
+}
+function listSkillsInDir(skillsDir) {
+  if (!existsSync2(skillsDir)) return [];
+  try {
+    const entries = readdirSync(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const skillMdPath = join2(skillsDir, entry.name, "SKILL.md");
+        if (existsSync2(skillMdPath)) {
+          skills.push(entry.name);
+        }
+      } else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+        skills.push(entry.name.replace(".md", ""));
+      }
+    }
+    return skills;
+  } catch {
+    return [];
+  }
+}
+function findMemoryDir() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) return null;
+  const memoryDir = join2(projectRoot, ".agents", "memory");
+  return existsSync2(memoryDir) ? memoryDir : null;
+}
+function resolveSkill(skillName, squadDir) {
+  if (squadDir) {
+    const squadSkillsDir = findSquadLocalSkillsDir(squadDir);
+    if (squadSkillsDir) {
+      const dirPath = join2(squadSkillsDir, skillName);
+      if (existsSync2(dirPath) && existsSync2(join2(dirPath, "SKILL.md"))) {
+        return { name: skillName, path: dirPath, source: "squad-local" };
+      }
+      const filePath = join2(squadSkillsDir, `${skillName}.md`);
+      if (existsSync2(filePath)) {
+        return { name: skillName, path: filePath, source: "squad-local" };
+      }
+    }
+  }
+  const projectSkillsDir = findProjectSkillsDir();
+  if (projectSkillsDir) {
+    const dirPath = join2(projectSkillsDir, skillName);
+    if (existsSync2(dirPath) && existsSync2(join2(dirPath, "SKILL.md"))) {
+      return { name: skillName, path: dirPath, source: "project" };
+    }
+    const filePath = join2(projectSkillsDir, `${skillName}.md`);
+    if (existsSync2(filePath)) {
+      return { name: skillName, path: filePath, source: "project" };
+    }
+  }
+  const globalSkillsDir = findGlobalSkillsDir();
+  if (globalSkillsDir) {
+    const dirPath = join2(globalSkillsDir, skillName);
+    if (existsSync2(dirPath) && existsSync2(join2(dirPath, "SKILL.md"))) {
+      return { name: skillName, path: dirPath, source: "global" };
+    }
+    const filePath = join2(globalSkillsDir, `${skillName}.md`);
+    if (existsSync2(filePath)) {
+      return { name: skillName, path: filePath, source: "global" };
+    }
+  }
+  return null;
+}
+function getSquadLocalSkills(squadDir) {
+  const squadSkillsDir = findSquadLocalSkillsDir(squadDir);
+  if (!squadSkillsDir) return [];
+  const skillNames = listSkillsInDir(squadSkillsDir);
+  const skills = [];
+  for (const name of skillNames) {
+    const resolved = resolveSkill(name, squadDir);
+    if (resolved && resolved.source === "squad-local") {
+      skills.push(resolved);
+    }
+  }
+  return skills;
+}
+function resolveMemoryPaths(patterns) {
+  const memoryDir = findMemoryDir();
+  if (!memoryDir) return [];
+  const resolved = [];
+  for (const pattern of patterns) {
+    if (pattern.endsWith("/*")) {
+      const subdir = pattern.slice(0, -2);
+      const subdirPath = join2(memoryDir, subdir);
+      if (existsSync2(subdirPath)) {
+        try {
+          const files = readdirSync(subdirPath);
+          for (const file of files) {
+            if (file.endsWith(".md")) {
+              resolved.push(join2(subdirPath, file));
+            }
+          }
+        } catch {
+        }
+      }
+    } else {
+      const fullPath = join2(memoryDir, pattern);
+      if (existsSync2(fullPath)) {
+        resolved.push(fullPath);
+      }
+    }
+  }
+  return resolved;
+}
+function findSquadLocalMcpConfig(squadDir) {
+  const squadsDir = findSquadsDir();
+  if (!squadsDir) return null;
+  const mcpConfigPath = join2(squadsDir, squadDir, "mcp.json");
+  return existsSync2(mcpConfigPath) ? mcpConfigPath : null;
+}
+function resolveExecutionContext(squad, forceRegenerate = false) {
+  const ctx = squad.context || {};
+  const squadLocalMcpConfig = findSquadLocalMcpConfig(squad.dir);
+  let mcpConfigPath;
+  let mcpSource;
+  let mcpServers = [];
+  if (squadLocalMcpConfig) {
+    mcpConfigPath = squadLocalMcpConfig;
+    mcpSource = "squad-local";
+    try {
+      const content = readFileSync2(squadLocalMcpConfig, "utf-8");
+      const config = JSON.parse(content);
+      mcpServers = Object.keys(config.mcpServers || {});
+    } catch {
+    }
+  } else {
+    const mcpResolution = resolveMcpConfig(
+      squad.name,
+      ctx.mcp,
+      forceRegenerate
+    );
+    mcpConfigPath = mcpResolution.path;
+    mcpSource = mcpResolution.source;
+    mcpServers = mcpResolution.servers || [];
+  }
+  const resolvedSkills = [];
+  const skillPaths = [];
+  const squadLocalSkills = getSquadLocalSkills(squad.dir);
+  for (const skill of squadLocalSkills) {
+    resolvedSkills.push(skill);
+    skillPaths.push(skill.path);
+  }
+  if (ctx.skills) {
+    for (const skillName of ctx.skills) {
+      if (resolvedSkills.some((s) => s.name === skillName)) {
+        continue;
+      }
+      const resolved = resolveSkill(skillName, squad.dir);
+      if (resolved) {
+        resolvedSkills.push(resolved);
+        skillPaths.push(resolved.path);
+      }
+    }
+  }
+  const memoryPaths = ctx.memory?.load ? resolveMemoryPaths(ctx.memory.load) : [];
+  return {
+    // Copy all SquadContext fields
+    ...ctx,
+    // Add squad name
+    squadName: squad.name,
+    // Add resolved paths
+    resolved: {
+      mcpConfigPath,
+      mcpSource,
+      mcpServers,
+      skillPaths,
+      // Backward compatible
+      skills: resolvedSkills,
+      // New detailed skill info
+      memoryPaths
+    }
+  };
+}
 
 // src/lib/condenser/tokens.ts
 var RATIOS = {
@@ -1032,11 +1306,13 @@ export {
   findSquadsDir,
   formatTrackerStatus,
   getCompressionLevel,
+  getSquadLocalSkills,
   listAgents,
   listSquads,
   loadAgentDefinition,
   loadSquad,
   parseSquadFile,
+  resolveExecutionContext,
   updateGoalInSquad,
   updateTracker,
   version