agent-pool-mcp 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-pool-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "MCP Server for multi-agent task delegation and orchestration via Gemini CLI",
   "main": "index.js",

package/skills/group-lead.md

@@ -0,0 +1,30 @@
+---
+name: group-lead
+description: Fractal group leader — breaks down tasks and delegates to group members via delegate_to_group.
+---
+
+# Group Lead
+
+You are a group leader in a fractal agent orchestration system. Your role is to:
+
+1. **Analyze** the incoming task and break it into independent subtasks
+2. **Create groups** if they don't exist yet, with appropriate skills and policies
+3. **Delegate** subtasks to group members using `delegate_to_group`
+4. **Collect** results from all agents using `get_task_result`
+5. **Synthesize** a final report combining all results
+
+## Rules
+
+- Break tasks into pieces that can run in parallel
+- Each subtask should be self-contained (agent can complete it without external context)
+- Set appropriate policies: use `read-only` for analysis, `safe-edit` for code changes
+- Always set `max_agents` to prevent runaway spawning
+- Collect ALL results before synthesizing — don't skip slow agents
+- Report both successes and failures
+
+## Output Format
+
+After collecting all results, produce a structured summary:
+1. Task overview (what was asked)
+2. Subtask results (one per agent)
+3. Synthesized conclusion

package/src/scheduler/daemon.js

@@ -11,10 +11,14 @@
  * @module agent-pool/scheduler/daemon
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { matchesCron } from './cron.js';
+import { getGroup } from '../tools/groups.js';
+import { getRunner } from '../runner/config.js';
+import { buildSshSpawn } from '../runner/ssh.js';
+import { killGroup } from '../runner/process-manager.js';
 
 const POLL_INTERVAL_MS = 30_000; // Check schedules every 30 seconds
 const PID_FILE = '.agents/scheduler.pid';
@@ -161,60 +165,119 @@ function executeSchedule(schedule) {
 
 // ─── Pipeline tick ──────────────────────────────────────────
 
-import { readdirSync } from 'node:fs';
-
 const PIPELINES_DIR = '.agents/pipelines';
 const RUNS_DIR = '.agents/runs';
 
 /**
- * Spawn a Gemini CLI agent for a pipeline step.
+ * Spawn Gemini CLI agent(s) for a pipeline step.
  * @param {object} stepDef - Step definition from pipeline
  * @param {object} run - Current run state
  * @param {string} runId
  * @param {string} [bounceReason] - If bouncing back, the reason
- * @returns {number} child PID
+ * @returns {number[]} Array of child PIDs
  */
 function spawnStep(stepDef, run, runId, bounceReason) {
-  let prompt = stepDef.prompt;
-  if (bounceReason) {
-    prompt = `${stepDef.prompt}\n\n⚠️ BOUNCE BACK: предыдущая попытка была отклонена следующим шагом.\nПричина: ${bounceReason}\nДополни и улучши результат.`;
+  const count = stepDef.count || 1;
+  const pids = [];
+
+  // Resolve group
+  let groupConfig = {};
+  if (stepDef.group) {
+    groupConfig = getGroup(run.cwd || cwd, stepDef.group) || {};
   }
 
-  // Inject pipeline context
-  prompt = `[Pipeline: ${run.pipelineName}, Step: ${stepDef.name}, Run: ${runId}]\n\nTask:\n${prompt}\n\nWhen finished, call signal_step_complete with step_name "${stepDef.name}" and run_id "${runId}".`;
+  const skill = stepDef.skill || groupConfig.skill;
+  const policy = groupConfig.policy; // currently policy only from group
+  const runnerId = groupConfig.runner;
+  const runner = runnerId ? getRunner(runnerId) : { type: 'local' };
+  const isRemote = runner && runner.type === 'ssh';
 
-  const args = [
-    '-p', prompt,
-    '--output-format', 'stream-json',
-    '--approval-mode', stepDef.approvalMode || 'yolo',
-  ];
+  for (let i = 0; i < count; i++) {
+    let prompt = stepDef.prompt;
+    if (bounceReason) {
+      prompt = `${stepDef.prompt}\n\n⚠️ BOUNCE BACK: предыдущая попытка была отклонена следующим шагом.\nПричина: ${bounceReason}\nДополни и улучши результат.`;
+    }
 
-  const child = spawn('gemini', args, {
-    cwd: run.cwd || cwd,
-    env: { ...process.env, TERM: 'dumb', CI: '1' },
-    stdio: ['pipe', 'pipe', 'pipe'],
-    detached: true,
-  });
+    if (count > 1) {
+      prompt = `[Agent ${i + 1}/${count}]\n\n${prompt}`;
+    }
 
-  child.on('close', (code) => {
-    // Update step exit code in run state
-    try {
-      const currentRun = JSON.parse(readFileSync(join(cwd, RUNS_DIR, `${runId}.json`), 'utf-8'));
-      if (currentRun.steps[stepDef.name]) {
-        currentRun.steps[stepDef.name].exitCode = code;
+    // Inject pipeline context
+    prompt = `[Pipeline: ${run.pipelineName}, Step: ${stepDef.name}, Run: ${runId}]\n\nTask:\n${prompt}\n\nWhen finished, call signal_step_complete with step_name "${stepDef.name}" and run_id "${runId}".`;
+
+    const args = [
+      '-p', prompt,
+      '--output-format', 'stream-json',
+      '--approval-mode', stepDef.approvalMode || 'yolo',
+    ];
+
+    if (skill) {
+      // Skills can be active via prompt injection, as we do for scheduled tasks
+      args[1] = `Activate skill "${skill}" first.\n\n${args[1]}`;
+    }
+    if (policy) {
+      args.push('--policy', policy);
+    }
+    if (groupConfig.include_dirs?.length > 0) {
+      for (const dir of groupConfig.include_dirs) {
+        args.push('--include-directories', dir);
       }
-      writeFileSync(join(cwd, RUNS_DIR, `${runId}.json`), JSON.stringify(currentRun, null, 2));
-    } catch { /* ignore */ }
-    console.error(`[pipeline] Step "${stepDef.name}" exited (code: ${code}, run: ${runId})`);
-  });
+    }
 
-  child.stdin.end();
-  child.unref();
+    let spawnCmd, spawnArgs, spawnOpts;
+    if (isRemote) {
+      const ssh = buildSshSpawn(runner, args, run.cwd || cwd);
+      spawnCmd = ssh.command;
+      spawnArgs = ssh.args;
+      spawnOpts = { stdio: ['pipe', 'pipe', 'pipe'], detached: true };
+    } else {
+      spawnCmd = 'gemini';
+      spawnArgs = args;
+      const currentDepth = parseInt(process.env.AGENT_POOL_DEPTH ?? '0');
+      spawnOpts = {
+        cwd: run.cwd || cwd,
+        env: {
+          ...process.env,
+          TERM: 'dumb',
+          CI: '1',
+          AGENT_POOL_DEPTH: String(currentDepth + 1)
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: true,
+      };
+      if (count > 1) spawnOpts.env.AGENT_INDEX = String(i);
+    }
+
+    const child = spawn(spawnCmd, spawnArgs, spawnOpts);
+
+    child.on('close', (code) => {
+      // Update step exit code in run state
+      try {
+        const currentRun = JSON.parse(readFileSync(join(cwd, RUNS_DIR, `${runId}.json`), 'utf-8'));
+        if (currentRun.steps[stepDef.name]) {
+          // If any child fails, set exit code to non-zero
+          if (code !== 0) {
+             currentRun.steps[stepDef.name].exitCode = code;
+          } else if (currentRun.steps[stepDef.name].exitCode === null) {
+             currentRun.steps[stepDef.name].exitCode = 0;
+          }
+        }
+        writeFileSync(join(cwd, RUNS_DIR, `${runId}.json`), JSON.stringify(currentRun, null, 2));
+      } catch { /* ignore */ }
+      console.error(`[pipeline] Step "${stepDef.name}" [pid ${child.pid}] exited (code: ${code}, run: ${runId})`);
+    });
+
+    child.stdin.end();
+    child.unref();
 
-  console.error(`[pipeline] Started step "${stepDef.name}" → pid ${child.pid} (run: ${runId})`);
-  return child.pid;
+    console.error(`[pipeline] Started step "${stepDef.name}" → pid ${child.pid} (run: ${runId})`);
+    pids.push(child.pid);
+  }
+
+  return pids;
 }
 
+
 /**
  * Check if a process is alive.
  * @param {number} pid
@@ -261,33 +324,67 @@ function tickPipelines() {
       if (step.status === 'bounce_pending') {
         step.status = 'running';
         step.startedAt = new Date().toISOString();
-        step.pid = spawnStep(stepDef, run, runId, step.lastBounceReason);
+        const pids = spawnStep(stepDef, run, runId, step.lastBounceReason);
+        step.pids = pids;
+        if (pids.length > 0) step.pid = pids[0];
         modified = true;
         continue;
       }
 
       // ── Handle running steps: check if process died ──
-      if (step.status === 'running' && step.pid) {
-        if (!isAlive(step.pid)) {
-          // Process is dead — did agent signal?
-          if (!step.signaled) {
-            // Auto-fallback: check exit code
-            if (step.exitCode === 0 || step.exitCode === null) {
-              // Treat as success (agent forgot to signal)
-              step.status = 'success';
-              step.completedAt = new Date().toISOString();
-              console.error(`[pipeline] Step "${stepDef.name}" auto-completed (pid dead, exit: ${step.exitCode})`);
-            } else {
-              // Failed
-              step.status = 'failed';
-              step.completedAt = new Date().toISOString();
-              console.error(`[pipeline] Step "${stepDef.name}" failed (exit: ${step.exitCode})`);
-              if (pipeline.onError === 'stop') {
-                run.status = 'failed';
-                run.completedAt = new Date().toISOString();
-              }
+      if (step.status === 'running') {
+        const pids = step.pids?.length > 0 ? step.pids : (step.pid ? [step.pid] : []);
+        if (pids.length === 0) continue;
+
+        let livingPids = 0;
+        for (const pid of pids) if (isAlive(pid)) livingPids++;
+
+        const isParallel = pids.length > 1;
+
+        if (isParallel) {
+          // Parallel semantics: rely entirely on exit codes
+          if (step.exitCode !== null && step.exitCode !== 0) {
+            // Fail fast: kill siblings
+            for (const pid of pids) if (isAlive(pid)) killGroup(pid);
+            step.status = 'failed';
+            step.completedAt = new Date().toISOString();
+            console.error(`[pipeline] Step "${stepDef.name}" parallel failed (exit: ${step.exitCode})`);
+            if (pipeline.onError === 'stop') {
+              run.status = 'failed';
+              run.completedAt = new Date().toISOString();
             }
             modified = true;
+          } else if (livingPids === 0) {
+            // All dead and no errors
+            step.status = 'success';
+            step.completedAt = new Date().toISOString();
+            console.error(`[pipeline] Step "${stepDef.name}" parallel completed successfully`);
+            modified = true;
+          }
+        } else {
+          // Sequential semantics (count 1)
+          const pid = pids[0];
+          if (!isAlive(pid)) {
+            // Process is dead — did agent signal?
+            if (!step.signaled) {
+              // Auto-fallback: check exit code
+              if (step.exitCode === 0 || step.exitCode === null) {
+                // Treat as success (agent forgot to signal)
+                step.status = 'success';
+                step.completedAt = new Date().toISOString();
+                console.error(`[pipeline] Step "${stepDef.name}" auto-completed (pid dead, exit: ${step.exitCode})`);
+              } else {
+                // Failed
+                step.status = 'failed';
+                step.completedAt = new Date().toISOString();
+                console.error(`[pipeline] Step "${stepDef.name}" failed (exit: ${step.exitCode})`);
+                if (pipeline.onError === 'stop') {
+                  run.status = 'failed';
+                  run.completedAt = new Date().toISOString();
+                }
+              }
+              modified = true;
+            }
           }
         }
         continue;
@@ -324,7 +421,9 @@ function tickPipelines() {
         if (shouldStart && run.status === 'running') {
           step.status = 'running';
           step.startedAt = new Date().toISOString();
-          step.pid = spawnStep(stepDef, run, runId);
+          const pids = spawnStep(stepDef, run, runId);
+          step.pids = pids;
+          if (pids.length > 0) step.pid = pids[0];
           modified = true;
         }
       }
@@ -335,7 +434,9 @@ function tickPipelines() {
         if (depStepName && run.steps[depStepName]?.status === 'success') {
           step.status = 'running';
           step.startedAt = new Date().toISOString();
-          step.pid = spawnStep(stepDef, run, runId);
+          const pids = spawnStep(stepDef, run, runId);
+          step.pids = pids;
+          if (pids.length > 0) step.pid = pids[0];
           modified = true;
         }
       }

package/src/scheduler/pipeline.js

@@ -11,6 +11,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlink
 import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { ensureDaemon } from './scheduler.js';
+import { killGroup } from '../runner/process-manager.js';
 
 const PIPELINES_DIR = '.agents/pipelines';
 const RUNS_DIR = '.agents/runs';
@@ -69,6 +70,8 @@ export function createPipeline(cwd, { name, steps, onError }) {
       name: s.name,
       prompt: s.prompt,
       skill: s.skill || null,
+      group: s.group || null,
+      count: s.count ? parseInt(s.count, 10) : 1,
       approvalMode: s.approval_mode || 'yolo',
       timeout: s.timeout || 600,
       maxBounces: s.maxBounces ?? s.max_bounces ?? 2,
@@ -134,7 +137,8 @@ export function runPipeline(cwd, pipelineId) {
   for (const step of pipeline.steps) {
     steps[step.name] = {
       status: 'pending',
-      pid: null,
+      pid: null,     // Legacy / single pid
+      pids: [],      // Array for parallel execution
       exitCode: null,
       signaled: false,
       bounces: 0,
@@ -219,8 +223,13 @@ export function cancelRun(cwd, runId) {
 
   // Kill any running step
   for (const [name, step] of Object.entries(run.steps)) {
-    if (step.status === 'running' && step.pid) {
-      try { process.kill(step.pid, 'SIGTERM'); } catch { /* already dead */ }
+    if (step.status === 'running') {
+      const pidsToKill = [...(step.pids || [])];
+      if (step.pid && !pidsToKill.includes(step.pid)) pidsToKill.push(step.pid);
+
+      for (const pid of pidsToKill) {
+        killGroup(pid);
+      }
       step.status = 'cancelled';
     }
     if (step.status === 'pending') {
@@ -332,7 +341,16 @@ export function bounceBack(cwd, targetStepName, reason, runId) {
       targetStep.status = 'bounce_pending';
       targetStep.bounces += 1;
       targetStep.lastBounceReason = reason;
+
+      // Fail-fast: kill any remaining running agents for this step
+      const pidsToKill = [...(targetStep.pids || [])];
+      if (targetStep.pid && !pidsToKill.includes(targetStep.pid)) pidsToKill.push(targetStep.pid);
+      for (const pid of pidsToKill) {
+        killGroup(pid);
+      }
+
       targetStep.pid = null;
+      targetStep.pids = [];
       targetStep.exitCode = null;
       targetStep.signaled = false;
 

package/src/server.js

@@ -22,6 +22,7 @@ import { listSkills, createSkill, deleteSkill, installSkill, provisionSkill } fr
 import { consultPeer } from './tools/consult.js';
 import { addSchedule, listSchedules, removeSchedule, getScheduledResults, getDaemonStatus } from './scheduler/scheduler.js';
 import { createPipeline, listPipelines, runPipeline, getRun, listRuns, cancelRun, signalStepComplete, bounceBack } from './scheduler/pipeline.js';
+import { createGroup, listGroups, getGroup } from './tools/groups.js';
 
 import { TOOL_DEFINITIONS } from './tool-definitions.js';
 
@@ -68,6 +69,7 @@ Docs: https://github.com/google-gemini/gemini-cli`
 /** Tools that require Gemini CLI to be installed */
 const GEMINI_TOOLS = new Set([
   'delegate_task', 'delegate_task_readonly', 'consult_peer', 'list_sessions',
+  'delegate_to_group',
 ]);
 
 // ─── Depth tracking (for nested orchestration) ──────────────
@@ -110,7 +112,7 @@ export function createServer() {
   }
 
   const server = new Server(
-    { name: 'agent-pool', version: '1.2.1' },
+    { name: 'agent-pool', version: '1.6.0' },
     { capabilities: { tools: {}, resources: {} } },
   );
 
@@ -200,6 +202,12 @@ export function createServer() {
           response = handleBounceBack(args); break;
         case 'get_usage_guide':
           response = handleGetUsageGuide(args); break;
+        case 'create_group':
+          response = handleCreateGroup(args); break;
+        case 'list_groups':
+          response = handleListGroups(args); break;
+        case 'delegate_to_group':
+          response = handleDelegateToGroup(args); break;
         default:
           response = { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
       }
@@ -688,3 +696,110 @@ function handleGetUsageGuide(args) {
   return { content: [{ type: 'text', text: topicContent.join('\n').trim() }] };
 }
 
+// ─── Group Handlers ─────────────────────────────────────────────
+
+/** @param {object} args */
+function handleCreateGroup(args) {
+  const cwd = args.cwd ?? defaultCwd;
+  const result = createGroup(cwd, {
+    name: args.name,
+    runner: args.runner,
+    skill: args.skill,
+    policy: args.policy,
+    max_agents: args.max_agents,
+    include_dirs: args.include_dirs,
+  });
+
+  const configParts = [];
+  if (args.runner) configParts.push(`runner: ${args.runner}`);
+  if (args.skill) configParts.push(`skill: ${args.skill}`);
+  if (args.policy) configParts.push(`policy: ${args.policy}`);
+  if (args.max_agents) configParts.push(`max: ${args.max_agents}`);
+
+  return {
+    content: [{
+      type: 'text',
+      text: `✅ Group ${result.created ? 'created' : 'updated'}: \`${args.name}\`${configParts.length > 0 ? `\n- ${configParts.join('\n- ')}` : ''}\n\nUse \`delegate_to_group\` to send tasks to this group.`,
+    }],
+  };
+}
+
+/** @param {object} args */
+function handleListGroups(args) {
+  const cwd = args.cwd ?? defaultCwd;
+  const groups = listGroups(cwd);
+
+  if (groups.length === 0) {
+    return { content: [{ type: 'text', text: 'No groups defined. Use `create_group` to create one.' }] };
+  }
+
+  const lines = groups.map((g) => {
+    const parts = [];
+    if (g.runner) parts.push(`runner: ${g.runner}`);
+    if (g.skill) parts.push(`skill: ${g.skill}`);
+    if (g.policy) parts.push(`policy: ${g.policy}`);
+    if (g.max_agents) parts.push(`max: ${g.max_agents}`);
+    return `- **${g.name}** — ${parts.join(', ') || 'no config'}`;
+  });
+
+  return {
+    content: [{ type: 'text', text: `## Agent Groups (${groups.length})\n\n${lines.join('\n')}` }],
+  };
+}
+
+/** @param {object} args */
+function handleDelegateToGroup(args) {
+  const cwd = args.cwd ?? defaultCwd;
+  const group = getGroup(cwd, args.group);
+
+  if (!group) {
+    return {
+      content: [{ type: 'text', text: `❌ Group \`${args.group}\` not found. Use \`list_groups\` to see available groups.` }],
+      isError: true,
+    };
+  }
+
+  const count = args.count ?? 1;
+
+  // Check max_agents limit
+  if (group.max_agents && count > group.max_agents) {
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ Requested ${count} agents but group \`${args.group}\` allows max ${group.max_agents}.`,
+      }],
+      isError: true,
+    };
+  }
+
+  const taskIds = [];
+
+  for (let i = 0; i < count; i++) {
+    const delegateArgs = {
+      prompt: count > 1 ? `[Agent ${i + 1}/${count} in group "${args.group}"]\n\n${args.prompt}` : args.prompt,
+      cwd,
+      runner: group.runner || undefined,
+      skill: group.skill || undefined,
+      policy: group.policy || undefined,
+      include_dirs: group.include_dirs || undefined,
+      timeout: args.timeout,
+    };
+
+    const result = handleDelegate(delegateArgs, {
+      approvalMode: DEFAULT_APPROVAL_MODE,
+      emoji: '👥',
+      label: `Group task (${args.group} #${i + 1})`,
+    });
+
+    // Extract task_id from response text
+    const match = result.content[0].text.match(/`([0-9a-f-]{36})`/);
+    if (match) taskIds.push(match[1]);
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: `👥 Delegated to group \`${args.group}\` — ${count} agent(s) spawned.\n\n${taskIds.map((id, i) => `- Agent ${i + 1}: \`${id}\``).join('\n')}\n\nUse \`get_task_result\` to check each agent's status.`,
+    }],
+  };
+}

package/src/tool-definitions.js

@@ -360,5 +360,53 @@ export const TOOL_DEFINITIONS = [
       required: ['step_name', 'reason'],
     },
   },
+  // ─── Group Tools ────────────────────────────────────────
+  {
+    name: 'create_group',
+    description: 'Create a named agent group with shared config (runner, skill, policy). Groups are reusable presets for fractal orchestration.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Group name (e.g. "backend-team", "qa-group").' },
+        runner: { type: 'string', description: 'Default runner for agents in this group.' },
+        skill: { type: 'string', description: 'Default skill activated for all agents in this group.' },
+        policy: { type: 'string', description: 'Default policy restricting agent permissions.' },
+        max_agents: { type: 'number', description: 'Max concurrent agents allowed in this group.' },
+        include_dirs: { type: 'array', items: { type: 'string' }, description: 'Additional directories agents in this group can access.' },
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'list_groups',
+    description: 'List all registered agent groups with their config.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+    },
+  },
+  {
+    name: 'delegate_to_group',
+    description: [
+      'Delegate a task to a named agent group. Spawns agents with the group\'s shared config (runner, skill, policy).',
+      'Use `count` to launch multiple agents in parallel (fractal orchestration).',
+      '',
+      'Returns array of task_ids immediately (non-blocking). Use get_task_result to check each.',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        group: { type: 'string', description: 'Group name to delegate to.' },
+        prompt: { type: 'string', description: 'Task description for the agents.' },
+        count: { type: 'number', description: 'Number of agents to spawn. Default: 1.' },
+        cwd: { type: 'string', description: 'Working directory. Defaults to current working directory.' },
+        timeout: { type: 'number', description: 'Timeout in seconds. Overrides group default.' },
+      },
+      required: ['group', 'prompt'],
+    },
+  },
 ];
 

package/src/tools/groups.js

@@ -0,0 +1,124 @@
+/**
+ * Agent Groups — named config presets for fractal orchestration.
+ * Groups bundle runner, skill, policy, and max_agents into a reusable team config.
+ *
+ * @module agent-pool/tools/groups
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const GROUPS_DIR = '.agents';
+const GROUPS_FILE = 'groups.json';
+
+/**
+ * Get path to groups.json for a project.
+ *
+ * @param {string} cwd - Project directory
+ * @returns {string}
+ */
+function getGroupsPath(cwd) {
+  return path.join(cwd, GROUPS_DIR, GROUPS_FILE);
+}
+
+/**
+ * Load all groups from disk.
+ *
+ * @param {string} cwd - Project directory
+ * @returns {Object<string, object>}
+ */
+function loadGroups(cwd) {
+  const filePath = getGroupsPath(cwd);
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save groups to disk.
+ *
+ * @param {string} cwd - Project directory
+ * @param {Object<string, object>} groups
+ */
+function saveGroups(cwd, groups) {
+  const dirPath = path.join(cwd, GROUPS_DIR);
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+  fs.writeFileSync(getGroupsPath(cwd), JSON.stringify(groups, null, 2));
+}
+
+/**
+ * Create or update a group.
+ *
+ * @param {string} cwd - Project directory
+ * @param {object} config - Group configuration
+ * @param {string} config.name - Group name (e.g. "backend-team")
+ * @param {string} [config.runner] - Default runner for agents in this group
+ * @param {string} [config.skill] - Default skill for agents in this group
+ * @param {string} [config.policy] - Default policy for agents in this group
+ * @param {number} [config.max_agents] - Max concurrent agents in this group
+ * @param {string[]} [config.include_dirs] - Additional directories agents can access
+ * @returns {{ name: string, created: boolean }}
+ */
+export function createGroup(cwd, config) {
+  const groups = loadGroups(cwd);
+  const existed = !!groups[config.name];
+
+  groups[config.name] = {
+    runner: config.runner || null,
+    skill: config.skill || null,
+    policy: config.policy || null,
+    max_agents: config.max_agents || null,
+    include_dirs: config.include_dirs || null,
+    created_at: existed ? groups[config.name].created_at : new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+
+  saveGroups(cwd, groups);
+  return { name: config.name, created: !existed };
+}
+
+/**
+ * List all groups.
+ *
+ * @param {string} cwd - Project directory
+ * @returns {Array<{ name: string, runner: string|null, skill: string|null, policy: string|null, max_agents: number|null }>}
+ */
+export function listGroups(cwd) {
+  const groups = loadGroups(cwd);
+  return Object.entries(groups).map(([name, config]) => ({
+    name,
+    ...config,
+  }));
+}
+
+/**
+ * Get a single group by name.
+ *
+ * @param {string} cwd - Project directory
+ * @param {string} name - Group name
+ * @returns {object|null}
+ */
+export function getGroup(cwd, name) {
+  const groups = loadGroups(cwd);
+  return groups[name] || null;
+}
+
+/**
+ * Delete a group.
+ *
+ * @param {string} cwd - Project directory
+ * @param {string} name - Group name
+ * @returns {boolean}
+ */
+export function deleteGroup(cwd, name) {
+  const groups = loadGroups(cwd);
+  if (!groups[name]) return false;
+  delete groups[name];
+  saveGroups(cwd, groups);
+  return true;
+}