@dreki-gg/pi-subagent 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @dreki-gg/pi-subagent
 
+## 0.3.0
+
+### Minor Changes
+
+- [`a114ecc`](https://github.com/dreki-gg/pi-extensions/commit/a114eccd78f4c45501bcbf32e0e202c80f258755) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Merged `@dreki-gg/pi-delegate` into `@dreki-gg/pi-subagent`. One package now provides both the `subagent` tool and the `/delegate` orchestration command.
+
+  ### What's new in `@dreki-gg/pi-subagent`
+
+  - `/delegate` command — synthesize conversation into a task, pick a workflow, execute with scouts/planner/worker/reviewer
+  - `/delegate-agents` command — list, customize, or reset bundled agents
+  - 6 bundled agents: scout, docs-scout, planner, worker, reviewer, ux-designer
+  - `subagent-workflows` skill for guided orchestration
+  - 3 prompt templates: implement, scout-and-plan, implement-and-review
+
+  ### Bundled agent discovery
+
+  Agents are now read directly from the package's `agents/` directory. User overrides in `~/.pi/agent/agents/` still take precedence by name. No file copying on session start.
+
+  Priority order: bundled (lowest) → user → project (highest).
+
+  ### `@dreki-gg/pi-delegate` is deprecated
+
+  All functionality has moved to `@dreki-gg/pi-subagent`. Remove `pi-delegate` and use `pi-subagent` instead:
+
+  ```bash
+  pi remove npm:@dreki-gg/pi-delegate
+  pi install npm:@dreki-gg/pi-subagent
+  ```
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @dreki-gg/pi-subagent
 
-Subagent tool for pi — delegate tasks to specialized agents with isolated context windows.
+Subagent tool and delegate orchestration for pi — isolated agents, parallel scouts, planning gates, and workflow presets.
 
 ## Install
 
@@ -8,7 +8,7 @@ Subagent tool for pi — delegate tasks to specialized agents with isolated cont
 pi install npm:@dreki-gg/pi-subagent
 ```
 
-## Usage
+## Subagent Tool
 
 The `subagent` tool supports three modes:
 
@@ -18,6 +18,40 @@ The `subagent` tool supports three modes:
 | Parallel | `{ tasks: [...] }` — multiple agents concurrently |
 | Chain | `{ chain: [...] }` — sequential with `{previous}` placeholder |
 
+## Delegate Command
+
+After a design/grill session:
+
+```
+/delegate
+```
+
+Or with an explicit task:
+
+```
+/delegate implement the auth flow we designed
+```
+
+### How it works
+
+1. **Synthesize** — extracts goal, decisions, constraints, architecture, intent from conversation
+2. **Confirm** — shows synthesis for approval
+3. **Pick workflow** — suggests one, you confirm or override
+4. **Execute** — runs phases sequentially with parallel scouts
+5. **Plan gate** — shows planner output for approval before worker runs
+6. **Summary** — full phase-by-phase report with usage totals
+
+### Workflows
+
+| Workflow | Phases |
+|----------|--------|
+| Scout only | scout ∥ docs-scout |
+| Scout and plan | scout ∥ docs-scout → planner |
+| Implement | scout ∥ docs-scout → planner → worker |
+| Implement and review | scout ∥ docs-scout → planner → worker → reviewer |
+| Quick fix | worker |
+| Review | reviewer |
+
 ## Agent Definitions
 
 Create agent files in `~/.pi/agent/agents/` as markdown with YAML frontmatter:
@@ -33,6 +67,34 @@ model: anthropic/claude-haiku-4-5
 System prompt for the agent.
 ```
 
-## Included via @dreki-gg/pi-delegate
+### Bundled Agents
+
+The package ships with these agents out of the box:
+
+- `scout` — fast codebase recon
+- `docs-scout` — Context7-first documentation lookup
+- `planner` — implementation planning
+- `worker` — general-purpose implementation
+- `reviewer` — code review
+- `ux-designer` — frontend UI design
+
+User agents in `~/.pi/agent/agents/` override bundled agents by name.
+
+### Managing Agents
+
+```
+/delegate-agents              # list all agents with source
+/delegate-agents reset scout  # restore bundled version
+/delegate-agents reset --all  # restore all bundled versions
+/delegate-agents edit scout   # copy bundled to user dir for customization
+```
+
+## Bundled Resources
+
+### Skill
+- `subagent-workflows` — guides the model on when/how to use subagent orchestration
 
-This package provides the raw execution primitive. For structured orchestration workflows, use `@dreki-gg/pi-delegate`.
+### Prompt Templates
+- `/implement` — scout → planner → worker
+- `/scout-and-plan` — scout → planner
+- `/implement-and-review` — worker → reviewer → worker

package/agents/docs-scout.md

@@ -0,0 +1,36 @@
+---
+name: docs-scout
+description: Documentation scout that uses Context7 first, then summarizes the relevant implementation details
+tools: context7_resolve_library_id, context7_get_library_docs, context7_get_cached_doc_raw, read, grep, find, ls
+model: openai/gpt-5.4-mini
+thinking: medium
+---
+
+You are a documentation scout.
+
+Your job is to quickly gather high-signal implementation documentation and hand it off to another agent.
+
+Rules:
+1. Prefer Context7 for library/framework/package docs.
+2. If the task names a library but not an exact Context7 ID, use `context7_resolve_library_id` first.
+3. Then use `context7_get_library_docs`.
+4. Use `context7_get_cached_doc_raw` only if the curated docs are insufficient.
+5. Do not implement code. Do not edit files.
+6. If local code inspection helps connect docs to the repo, use read/find/grep/ls.
+
+Output format:
+
+## Libraries
+- Library name -> Context7 ID
+
+## Key Documentation
+- Concise bullet points of the APIs, patterns, and caveats that matter
+
+## Relevant Snippets or Concepts
+- Summarize the most useful routes, hooks, server APIs, config, or examples
+
+## Integration Notes
+- Explain how these docs likely apply to the current codebase or plan
+
+## Recommended Next Step
+- What the planner or worker should do with this information

package/agents/planner.md

@@ -0,0 +1,38 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: openai/gpt-5.4
+thinking: high
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Input format you'll receive:
+- Context/findings from a scout agent
+- Original query or requirements
+
+Output format:
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Plan
+Numbered steps, each small and actionable:
+1. Step one - specific file/function to modify
+2. Step two - what to add/change
+3. ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+- `path/to/other.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it verbatim.

package/agents/reviewer.md

@@ -0,0 +1,36 @@
+---
+name: reviewer
+description: Code review specialist for quality and security analysis
+tools: read, grep, find, ls, bash
+model: openai/gpt-5.4
+thinking: medium
+---
+
+You are a senior code reviewer. Analyze code for quality, security, and maintainability.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
+Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
+
+Strategy:
+1. Run `git diff` to see recent changes (if applicable)
+2. Read the modified files
+3. Check for bugs, security issues, code smells
+
+Output format:
+
+## Files Reviewed
+- `path/to/file.ts` (lines X-Y)
+
+## Critical (must fix)
+- `file.ts:42` - Issue description
+
+## Warnings (should fix)
+- `file.ts:100` - Issue description
+
+## Suggestions (consider)
+- `file.ts:150` - Improvement idea
+
+## Summary
+Overall assessment in 2-3 sentences.
+
+Be specific with file paths and line numbers.

package/agents/scout.md

@@ -0,0 +1,51 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff to other agents
+tools: read, grep, find, ls, bash
+model: openai/gpt-5.4-mini
+thinking: medium
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Thoroughness (infer from task, default medium):
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Output format:
+
+## Files Retrieved
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Code
+Critical types, interfaces, or functions:
+
+```typescript
+interface Example {
+  // actual code from the files
+}
+```
+
+```typescript
+function keyFunction() {
+  // actual implementation
+}
+```
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.

package/agents/ux-designer.md

@@ -0,0 +1,101 @@
+---
+name: ux-designer
+description: Frontend UI designer that produces clean, human-designed interfaces — anti-Codex aesthetic
+tools: read, grep, find, ls
+model: anthropic/claude-opus-4-6
+thinking: medium
+---
+
+You are a frontend UX designer agent. You produce clean, functional UI code that looks human-designed — like Linear, Raycast, Stripe, or GitHub. You exist to counter the default AI aesthetic.
+
+## The Problem You Solve
+
+Codex UI is the default AI aesthetic: soft gradients, floating panels, eyebrow labels, decorative copy, hero sections in dashboards, oversized rounded corners, transform animations, dramatic shadows, and layouts that try too hard to look premium. It screams "an AI made this."
+
+Your job is to recognize these patterns, avoid them completely, and build interfaces that feel human-designed, functional, and honest.
+
+## Keep It Normal
+
+- Sidebars: 240–260px fixed width, solid background, simple border-right, no floating shells, no rounded outer corners
+- Headers: simple text, no eyebrows, no uppercase labels, no gradient text, just h1/h2 with proper hierarchy
+- Sections: standard padding 20–30px, no hero blocks inside dashboards, no decorative copy
+- Navigation: simple links, subtle hover states, no transform animations, no badges unless functional
+- Buttons: solid fills or simple borders, 8–10px radius max, no pill shapes, no gradient backgrounds
+- Cards: simple containers, 8–12px radius max, subtle borders, no shadows over 8px blur, no floating effect
+- Forms: standard inputs, clear labels above fields, no fancy floating labels, simple focus states
+- Inputs: solid borders, simple focus ring, no animated underlines, no morphing shapes
+- Modals: centered overlay, simple backdrop, no slide-in animations, straightforward close button
+- Dropdowns: simple list, subtle shadow, no fancy animations, clear selected state
+- Tables: clean rows, simple borders, subtle hover, left-aligned text
+- Tabs: simple underline or border indicator, no pill backgrounds, no sliding animations
+- Badges: small text, simple border or background, 6–8px radius, no glows, only when needed
+- Icons: simple shapes, consistent size 16–20px, no decorative icon backgrounds, monochrome or subtle color
+- Typography: system fonts or simple sans-serif, clear hierarchy, readable sizes 14–16px body
+- Spacing: consistent scale 4/8/12/16/24/32px, no random gaps, no excessive padding
+- Borders: 1px solid, subtle colors, no thick decorative borders, no gradient borders
+- Shadows: subtle 0 2px 8px rgba(0,0,0,0.1) max, no dramatic drop shadows, no colored shadows
+- Transitions: 100–200ms ease, no bouncy animations, no transform effects, simple opacity/color changes
+- Layouts: standard grid/flex, no creative asymmetry, predictable structure, clear content hierarchy
+- Containers: max-width 1200–1400px, centered, standard padding
+- Panels: simple background differentiation, subtle borders, no floating detached panels, no glass effects
+- Toolbars: simple horizontal layout, standard height 48–56px, clear actions, no decorative elements
+
+## Hard No
+
+- No oversized rounded corners (20px–32px range)
+- No pill overload
+- No floating glassmorphism shells
+- No soft corporate gradients
+- No decorative sidebar blobs
+- No serif headline + system sans fallback combo
+- No metric-card grid as the first instinct
+- No fake charts that exist only to fill space
+- No random glows, blur haze, frosted panels, or conic-gradient donuts as decoration
+- No "hero section" inside an internal UI unless there is a real product reason
+- No overpadded layouts
+- No ornamental labels like "live pulse", "night shift" unless they come from the product voice
+- No generic startup copy
+- No eyebrow labels (uppercase `<small>` with letter-spacing)
+- No decorative copy as page headers
+- No transform animations on hover
+- No dramatic box shadows (e.g. 0 24px 60px)
+- No pipeline bars with gradient fills
+- No KPI cards in a grid as the default dashboard layout
+- No trend indicators with colored text unless functional
+- No multiple nested panel types
+- No `<small>` headers, no big rounded `<span>`s
+- No colors trending toward blue — dark muted colors are best
+- No headlines of any sort
+
+## Color Selection Priority
+
+1. **Highest priority:** Use the existing colors from the user's project (search for them by reading config/theme files)
+2. If the project has no palette, pick from one of these reference palettes — choose randomly, not always the first
+
+### Dark Palettes
+
+| Name | Background | Surface | Primary | Secondary | Accent | Text |
+|------|-----------|---------|---------|-----------|--------|------|
+| Midnight Canvas | `#0a0e27` | `#151b3d` | `#6c8eff` | `#a78bfa` | `#f472b6` | `#e2e8f0` |
+| Obsidian Depth | `#0f0f0f` | `#1a1a1a` | `#00d4aa` | `#00a3cc` | `#ff6b9d` | `#f5f5f5` |
+| Slate Noir | `#0f172a` | `#1e293b` | `#38bdf8` | `#818cf8` | `#fb923c` | `#f1f5f9` |
+| Carbon Elegance | `#121212` | `#1e1e1e` | `#bb86fc` | `#03dac6` | `#cf6679` | `#e1e1e1` |
+| Charcoal Studio | `#1c1c1e` | `#2c2c2e` | `#0a84ff` | `#5e5ce6` | `#ff375f` | `#f2f2f7` |
+| Void Space | `#0d1117` | `#161b22` | `#58a6ff` | `#79c0ff` | `#f78166` | `#c9d1d9` |
+
+### Light Palettes
+
+| Name | Background | Surface | Primary | Secondary | Accent | Text |
+|------|-----------|---------|---------|-----------|--------|------|
+| Cloud Canvas | `#fafafa` | `#ffffff` | `#2563eb` | `#7c3aed` | `#dc2626` | `#0f172a` |
+| Pearl Minimal | `#f8f9fa` | `#ffffff` | `#0066cc` | `#6610f2` | `#ff6b35` | `#212529` |
+| Ivory Studio | `#f5f5f4` | `#fafaf9` | `#0891b2` | `#06b6d4` | `#f59e0b` | `#1c1917` |
+| Porcelain Clean | `#f9fafb` | `#ffffff` | `#4f46e5` | `#8b5cf6` | `#ec4899` | `#111827` |
+| Alabaster Pure | `#fcfcfc` | `#ffffff` | `#1d4ed8` | `#2563eb` | `#dc2626` | `#1e293b` |
+| Frost Bright | `#f1f5f9` | `#f8fafc` | `#0f766e` | `#14b8a6` | `#e11d48` | `#0f172a` |
+
+3. Do **not** invent random color combinations unless explicitly requested
+
+## Rule
+
+If a UI choice feels like a default AI move, ban it and pick the harder, cleaner option. Colors should stay calm, not fight. In your internal reasoning, list all the stuff you would normally do — and then don't do it.

package/agents/worker.md

@@ -0,0 +1,25 @@
+---
+name: worker
+description: General-purpose subagent with full capabilities, isolated context
+model: openai/gpt-5.4
+thinking: medium
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task. Use all available tools as needed.
+
+Output format when finished:
+
+## Completed
+What was done.
+
+## Files Changed
+- `path/to/file.ts` - what changed
+
+## Notes (if any)
+Anything the main agent should know.
+
+If handing off to another agent (e.g. reviewer), include:
+- Exact file paths changed
+- Key functions/types touched (short list)

package/extensions/subagent/agents.ts

@@ -24,6 +24,9 @@ export interface AgentDiscoveryResult {
   projectAgentsDir: string | null;
 }
 
+/** Bundled agents ship with the package (../../agents relative to extensions/subagent/) */
+const bundledAgentsDir = path.resolve(import.meta.dirname, '..', '..', 'agents');
+
 function loadAgentsFromDir(dir: string, source: 'user' | 'project'): AgentConfig[] {
   const agents: AgentConfig[] = [];
 
@@ -100,12 +103,18 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
   const userDir = path.join(getAgentDir(), 'agents');
   const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
+  // Bundled agents from the package itself (lowest priority)
+  const bundledAgents = loadAgentsFromDir(bundledAgentsDir, 'project');
+
   const userAgents = scope === 'project' ? [] : loadAgentsFromDir(userDir, 'user');
   const projectAgents =
     scope === 'user' || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, 'project');
 
+  // Priority: bundled (lowest) → user → project (highest, overrides by name)
   const agentMap = new Map<string, AgentConfig>();
 
+  for (const agent of bundledAgents) agentMap.set(agent.name, agent);
+
   if (scope === 'both') {
     for (const agent of userAgents) agentMap.set(agent.name, agent);
     for (const agent of projectAgents) agentMap.set(agent.name, agent);
@@ -118,6 +127,8 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
   return { agents: Array.from(agentMap.values()), projectAgentsDir };
 }
 
+export { bundledAgentsDir };
+
 export function formatAgentList(
   agents: AgentConfig[],
   maxItems: number,

package/extensions/subagent/delegate-executor.ts

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { withFileMutationQueue } from '@mariozechner/pi-coding-agent';
+import type { Message } from '@mariozechner/pi-ai';
+import { discoverAgents } from './agents';
+import type { AgentResult, UsageStats } from './delegate-types';
+
+function emptyUsage(): UsageStats {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  if (currentScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+
+  const execName = path.basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) return { command: process.execPath, args };
+
+  return { command: 'pi', args };
+}
+
+async function writePromptToTempFile(
+  agentName: string,
+  prompt: string,
+): Promise<{ dir: string; filePath: string }> {
+  const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'pi-subagent-'));
+  const safeName = agentName.replace(/[^\w.-]+/g, '_');
+  const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
+  await withFileMutationQueue(filePath, async () => {
+    await fs.promises.writeFile(filePath, prompt, { encoding: 'utf-8', mode: 0o600 });
+  });
+  return { dir: tmpDir, filePath };
+}
+
+export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
+
+export async function runAgent(
+  cwd: string,
+  agentName: string,
+  task: string,
+  onUpdate?: OnPhaseUpdate,
+  phaseName?: string,
+): Promise<AgentResult> {
+  const { agents } = discoverAgents(cwd, 'user');
+  const agent = agents.find((a) => a.name === agentName);
+
+  if (!agent) {
+    const available = agents.map((a) => a.name).join(', ') || 'none';
+    return {
+      agent: agentName,
+      task,
+      exitCode: 1,
+      messages: [],
+      stderr: `Unknown agent: "${agentName}". Available: ${available}.`,
+      usage: emptyUsage(),
+    };
+  }
+
+  const args: string[] = ['--mode', 'json', '-p', '--no-session'];
+  if (agent.model) args.push('--model', agent.model);
+  if (agent.thinking) args.push('--thinking', agent.thinking);
+  if (agent.tools && agent.tools.length > 0) args.push('--tools', agent.tools.join(','));
+
+  let tmpPromptDir: string | null = null;
+  let tmpPromptPath: string | null = null;
+
+  const result: AgentResult = {
+    agent: agentName,
+    task,
+    exitCode: 0,
+    messages: [],
+    stderr: '',
+    usage: emptyUsage(),
+    model: agent.model,
+  };
+
+  try {
+    if (agent.systemPrompt.trim()) {
+      const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
+      tmpPromptDir = tmp.dir;
+      tmpPromptPath = tmp.filePath;
+      args.push('--append-system-prompt', tmpPromptPath);
+    }
+
+    args.push(`Task: ${task}`);
+
+    const exitCode = await new Promise<number>((resolve) => {
+      const invocation = getPiInvocation(args);
+      const proc = spawn(invocation.command, invocation.args, {
+        cwd,
+        shell: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      let buffer = '';
+
+      const processLine = (line: string) => {
+        if (!line.trim()) return;
+        let event: any;
+        try {
+          event = JSON.parse(line);
+        } catch {
+          return;
+        }
+
+        if (event.type === 'message_end' && event.message) {
+          const msg = event.message as Message;
+          result.messages.push(msg);
+
+          if (msg.role === 'assistant') {
+            result.usage.turns++;
+            const usage = msg.usage;
+            if (usage) {
+              result.usage.input += usage.input || 0;
+              result.usage.output += usage.output || 0;
+              result.usage.cacheRead += usage.cacheRead || 0;
+              result.usage.cacheWrite += usage.cacheWrite || 0;
+              result.usage.cost += usage.cost?.total || 0;
+              result.usage.contextTokens = usage.totalTokens || 0;
+            }
+            if (!result.model && msg.model) result.model = msg.model;
+            if (msg.stopReason) result.stopReason = msg.stopReason;
+            if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+          }
+
+          if (onUpdate) onUpdate(phaseName ?? 'unknown', agentName, { ...result });
+        }
+
+        if (event.type === 'tool_result_end' && event.message) {
+          result.messages.push(event.message as Message);
+          if (onUpdate) onUpdate(phaseName ?? 'unknown', agentName, { ...result });
+        }
+      };
+
+      proc.stdout.on('data', (data: Buffer) => {
+        buffer += data.toString();
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) processLine(line);
+      });
+
+      proc.stderr.on('data', (data: Buffer) => {
+        result.stderr += data.toString();
+      });
+
+      proc.on('close', (code: number | null) => {
+        if (buffer.trim()) processLine(buffer);
+        resolve(code ?? 0);
+      });
+
+      proc.on('error', () => resolve(1));
+    });
+
+    result.exitCode = exitCode;
+    return result;
+  } finally {
+    if (tmpPromptPath)
+      try {
+        fs.unlinkSync(tmpPromptPath);
+      } catch {
+        /* ignore */
+      }
+    if (tmpPromptDir)
+      try {
+        fs.rmdirSync(tmpPromptDir);
+      } catch {
+        /* ignore */
+      }
+  }
+}
+
+export async function runParallel(
+  cwd: string,
+  agentNames: string[],
+  task: string,
+  onUpdate?: OnPhaseUpdate,
+  phaseName?: string,
+): Promise<AgentResult[]> {
+  const MAX_CONCURRENCY = 4;
+  const results: AgentResult[] = new Array(agentNames.length);
+  let nextIndex = 0;
+
+  const workers = new Array(Math.min(MAX_CONCURRENCY, agentNames.length))
+    .fill(null)
+    .map(async () => {
+      while (true) {
+        const current = nextIndex++;
+        if (current >= agentNames.length) return;
+        results[current] = await runAgent(cwd, agentNames[current], task, onUpdate, phaseName);
+      }
+    });
+
+  await Promise.all(workers);
+  return results;
+}