opencode-onboard 0.4.2 → 0.4.4

package/src/steps/copy/agents.js

@@ -61,6 +61,34 @@ function replaceBetween(content, start, end, replacement) {
   return content.replace(pattern, `${start}\n${replacement.trim()}\n${end}`)
 }
 
+const CONCURRENCY_PLACEHOLDER = '{{MAX_CONCURRENT_AGENTS}}'
+const DEFAULT_MAX_CONCURRENT_AGENTS = 4
+
+export async function patchConcurrency(ctx) {
+  const maxAgents = String(ctx.maxConcurrentAgents ?? DEFAULT_MAX_CONCURRENT_AGENTS)
+  const cwd = process.cwd()
+
+  const filesToPatch = [
+    'AGENTS.md',
+    path.join('.opencode', 'commands', 'opsx-apply.md'),
+    path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
+  ]
+
+  let patched = 0
+  for (const rel of filesToPatch) {
+    const abs = path.join(cwd, rel)
+    if (!await fse.pathExists(abs)) continue
+    const content = await fse.readFile(abs, 'utf-8')
+    if (!content.includes(CONCURRENCY_PLACEHOLDER)) continue
+    await fse.writeFile(abs, content.replaceAll(CONCURRENCY_PLACEHOLDER, maxAgents), 'utf-8')
+    patched++
+  }
+
+  if (patched > 0) {
+    success(`Concurrency limit set to ${maxAgents} agents in ${patched} file(s)`)
+  }
+}
+
 export async function patchAgentsMd(ctx) {
   const agentsMdPath = path.join(process.cwd(), 'AGENTS.md')
   if (!await fse.pathExists(agentsMdPath)) return

package/src/steps/copy/copy.test.js

@@ -12,6 +12,7 @@ vi.mock('../../utils/copy.js', () => ({
 
 vi.mock('./agents.js', () => ({
   patchAgentsMd: vi.fn(),
+  patchConcurrency: vi.fn(),
   patchDevopsManagerMd: vi.fn(),
 }))
 

package/src/steps/copy/index.js

@@ -3,7 +3,7 @@ import path from 'path'
 import { fileURLToPath } from 'url'
 import { copyContent } from '../../utils/copy.js'
 import { error, header, success } from '../../utils/exec.js'
-import { patchAgentsMd, patchDevopsManagerMd } from './agents.js'
+import { patchAgentsMd, patchConcurrency, patchDevopsManagerMd } from './agents.js'
 import { installSkills } from './skills.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -24,6 +24,7 @@ export async function copyContentStep(platform, ctx = {}) {
     }, { spaces: 2 })
     await patchDevopsManagerMd(platform)
     await patchAgentsMd(ctx)
+    await patchConcurrency(ctx)
     await installSkills()
     success('Files copied to project root')
   } catch (err) {

package/src/steps/metadata/index.js

@@ -1,61 +1,63 @@
-import { execa } from 'execa'
-import fse from 'fs-extra'
-import path from 'path'
-import { createRequire } from 'node:module'
-import { header, success, warn } from '../../utils/exec.js'
-
-const require = createRequire(import.meta.url)
-const { version: onboardVersion } = require('../../../package.json')
-
-async function detectOpencodeVersion() {
-  try {
-    const result = await execa('opencode', ['--version'], { reject: false })
-    if (result.exitCode !== 0) return null
-    const output = (result.stdout || result.stderr || '').trim()
-    return output || null
-  } catch {
-    return null
-  }
-}
-
-export async function writeOnboardConfig(data) {
-  header('Step 10, Writing onboarding metadata')
-
-  const opencodeVersion = await detectOpencodeVersion()
-  const target = path.join(process.cwd(), '.opencode', 'opencode-onboard.json')
-
-  const payload = {
-    schema: 1,
-    generatedAt: new Date().toISOString(),
-    onboardVersion,
-    opencodeVersion,
-    wizard: {
-      platform: data.platform,
-      sourceMode: data.sourceMode,
-      sourceRoots: data.sourceRoots,
-      preserved: {
-        design: !!data.hasDesign,
-        architecture: !!data.hasArchitecture,
-        openspec: !!data.hasOpenspec,
-      },
-      additionalSkillsProvider: data.additionalSkillsProvider,
-      models: {
-        plan: data.planModel,
-        build: data.buildModel,
-        fast: data.fastModel,
-      },
-      optionalTools: data.optionalTools ?? null,
-      cavemanGuidance: data.cavemanGuidance ?? null,
-    },
-    note: 'Informational file only. Editing this file does not change runtime behavior.',
-  }
-
-  try {
-    await fse.ensureDir(path.dirname(target))
-    await fse.writeJson(target, payload, { spaces: 2 })
-    success('Wrote .opencode/opencode-onboard.json')
-    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
-  } catch (err) {
-    warn(`Could not write onboarding metadata: ${err.message}`)
-  }
-}
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { createRequire } from 'node:module'
+import { header, success, warn } from '../../utils/exec.js'
+
+const require = createRequire(import.meta.url)
+const { version: onboardVersion } = require('../../../package.json')
+
+async function detectOpencodeVersion() {
+  try {
+    const result = await execa('opencode', ['--version'], { reject: false })
+    if (result.exitCode !== 0) return null
+    const output = (result.stdout || result.stderr || '').trim()
+    return output || null
+  } catch {
+    return null
+  }
+}
+
+export async function writeOnboardConfig(data) {
+  header('Step 10, Writing onboarding metadata')
+
+  const opencodeVersion = await detectOpencodeVersion()
+  const target = path.join(process.cwd(), '.opencode', 'opencode-onboard.json')
+
+  const payload = {
+    schema: 1,
+    generatedAt: new Date().toISOString(),
+    onboardVersion,
+    opencodeVersion,
+    wizard: {
+      platform: data.platform,
+      sourceMode: data.sourceMode,
+      sourceRoots: data.sourceRoots,
+      maxConcurrentAgents: data.maxConcurrentAgents ?? 4,
+      preserved: {
+        design: !!data.hasDesign,
+        architecture: !!data.hasArchitecture,
+        openspec: !!data.hasOpenspec,
+      },
+      openspec: data.openspec,
+      additionalSkillsProvider: data.additionalSkillsProvider,
+      models: {
+        plan: data.planModel,
+        build: data.buildModel,
+        fast: data.fastModel,
+      },
+      optionalTools: data.optionalTools ?? null,
+      cavemanGuidance: data.cavemanGuidance ?? null,
+    },
+    note: 'Informational file only. Editing this file does not change runtime behavior.',
+  }
+
+  try {
+    await fse.ensureDir(path.dirname(target))
+    await fse.writeJson(target, payload, { spaces: 2 })
+    success('Wrote .opencode/opencode-onboard.json')
+    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
+  } catch (err) {
+    warn(`Could not write onboarding metadata: ${err.message}`)
+  }
+}

package/src/steps/models/format.js

@@ -1,60 +1,61 @@
-import { search } from '@inquirer/prompts'
-import fse from 'fs-extra'
-import path from 'path'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const MODELS_PRESET_PATH = path.resolve(__dirname, '../../presets/models.json');
-const modelsPreset = await fse.readJson(MODELS_PRESET_PATH);
-
-function costTier(input) {
-  if (input === undefined || input === null) return '';
-  const tier = modelsPreset.costTiers.find(t => t.max === undefined || input <= t.max);
-  return tier ? ` ${tier.label}` : '';
-}
-
-function costTierDisplay(cost, canonicalCost) {
-  return costTier(canonicalCost !== undefined ? canonicalCost : cost);
-}
-
-function formatPrice(price) {
-  if (price === undefined || price === null) return '?';
-  if (price === 0) return '$0 (subscription)';
-  return `$${price}/M`;
-}
-
-export function buildDisplayModels(rawModels) {
-  return rawModels.map(m => {
-    const priceStr = formatPrice(m.cost);
-    const canonicalNote = m.canonicalCost !== undefined
-      ? ` · official price: ${formatPrice(m.canonicalCost)}/M`
-      : '';
-    return {
-      ...m,
-      label: `${m.name}${costTierDisplay(m.cost, m.canonicalCost)}, ${m.id}`,
-      description: `${priceStr}${canonicalNote} · context: ${m.context ? (m.context / 1000) + 'k' : '?'}`,
-    };
-  });
-}
-
-export async function pickModel(message, models) {
-  return await search({
-    message,
-    source: (input) => {
-      const q = (input || '').toLowerCase();
-      const filtered = q
-        ? models.filter(m =>
-            m.label.toLowerCase().includes(q) ||
-            m.id.toLowerCase().includes(q)
-          )
-        : models;
-      return filtered.slice(0, 50).map(m => ({
-        name: m.label,
-        value: m.id,
-        description: m.description,
-      }));
-    },
-  });
-}
-
-export { modelsPreset };
+import { search } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MODELS_PRESET_PATH = path.resolve(__dirname, '../../presets/models.json');
+const modelsPreset = await fse.readJson(MODELS_PRESET_PATH);
+
+function costTier(input) {
+  if (input === undefined || input === null) return '';
+  const tier = modelsPreset.costTiers.find(t => t.max === undefined || input <= t.max);
+  return tier ? ` ${tier.label}` : '';
+}
+
+function costTierDisplay(cost, canonicalCost) {
+  return costTier(canonicalCost !== undefined ? canonicalCost : cost);
+}
+
+function formatPrice(price) {
+  if (price === undefined || price === null) return '?';
+  if (price === 0) return '$0 (subscription)';
+  return `$${price}/M`;
+}
+
+export function buildDisplayModels(rawModels) {
+  return rawModels.map(m => {
+    const priceStr = formatPrice(m.cost);
+    const canonicalNote = m.canonicalCost !== undefined
+      ? ` · official price: ${formatPrice(m.canonicalCost)}/M`
+      : '';
+    const context = m.context ? `${m.context / 1000}k` : '?';
+    return {
+      ...m,
+      label: `${m.name}${costTierDisplay(m.cost, m.canonicalCost)}, ${m.id}`,
+      description: `${priceStr}${canonicalNote} · context: ${context}`,
+    };
+  });
+}
+
+export function pickModel(message, models) {
+  return search({
+    message,
+    source: (input) => {
+      const q = (input || '').toLowerCase();
+      const filtered = q
+        ? models.filter(m =>
+            m.label.toLowerCase().includes(q) ||
+            m.id.toLowerCase().includes(q)
+          )
+        : models;
+      return filtered.slice(0, 50).map(m => ({
+        name: m.label,
+        value: m.id,
+        description: m.description,
+      }));
+    },
+  });
+}
+
+export { modelsPreset };

package/src/steps/models/write.test.js

@@ -1,117 +1,117 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import fs from 'node:fs'
-import path from 'node:path'
-import os from 'node:os'
-
-vi.mock('../../utils/exec.js', () => ({
-  success: vi.fn(),
-}))
-
-import { success } from '../../utils/exec.js'
-import { writeModelToAgent, writeModelsToConfigs } from './write.js'
-
-describe('writeModelToAgent()', () => {
-  let tmpDir
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'models-write-test-'))
-  })
-
-  afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true })
-  })
-
-  it('adds model field to agent file frontmatter', async () => {
-    const filePath = path.join(tmpDir, 'test-agent.md')
-    const original = `---
-name: Test Agent
-description: A test agent
----
-
-# Test Agent`
-    fs.writeFileSync(filePath, original, 'utf-8')
-
-    await writeModelToAgent(filePath, 'anthropic/claude-3-sonnet')
-
-    const updated = fs.readFileSync(filePath, 'utf-8')
-    expect(updated).toContain('model: anthropic/claude-3-sonnet')
-  })
-
-  it('preserves existing frontmatter fields', async () => {
-    const filePath = path.join(tmpDir, 'test-agent.md')
-    const original = `---
-name: Test Agent
-description: A test agent
-custom_field: custom_value
----
-
-# Test Agent`
-    fs.writeFileSync(filePath, original, 'utf-8')
-
-    await writeModelToAgent(filePath, 'test/model')
-
-    const updated = fs.readFileSync(filePath, 'utf-8')
-    expect(updated).toContain('name: Test Agent')
-    expect(updated).toContain('description: A test agent')
-    expect(updated).toContain('custom_field: custom_value')
-    expect(updated).toContain('model: test/model')
-  })
-})
-
-describe('writeModelsToConfigs()', () => {
-  let tmpDir, agentsDir, opencodeJsonPath, ensembleJsonPath, originalCwd
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-    originalCwd = process.cwd()
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'models-config-test-'))
-    agentsDir = path.join(tmpDir, '.agents', 'agents')
-    fs.mkdirSync(agentsDir, { recursive: true })
-    opencodeJsonPath = path.join(tmpDir, '.opencode', 'opencode.json')
-    ensembleJsonPath = path.join(tmpDir, '.opencode', 'ensemble.json')
-    fs.mkdirSync(path.dirname(opencodeJsonPath), { recursive: true })
-    process.chdir(tmpDir)
-  })
-
-  afterEach(() => {
-    process.chdir(originalCwd)
-    fs.rmSync(tmpDir, { recursive: true, force: true })
-  })
-
-  it('writes build model to agent files', async () => {
-    fs.writeFileSync(path.join(agentsDir, 'back-engineer.md'), '---\nname: Back\n---', 'utf-8')
-    fs.writeFileSync(path.join(agentsDir, 'front-engineer.md'), '---\nname: Front\n---', 'utf-8')
-
-    await writeModelsToConfigs({
-      planModel: 'plan-model',
-      buildModel: 'build-model',
-      fastModel: 'fast-model',
-      agentsDir,
-      preset: {
-        roles: {
-          build: { agents: ['back-engineer'] },
-          fast: { agents: ['front-engineer'] },
-        },
-      },
-    })
-
-    expect(success).toHaveBeenCalledWith('back-engineer → build-model')
-    expect(success).toHaveBeenCalledWith('front-engineer → fast-model')
-  })
-
-  it('reports success when writing configs', async () => {
-    const agentFile = path.join(agentsDir, 'back-engineer.md')
-    fs.writeFileSync(agentFile, '---\nname: Back\n---', 'utf-8')
-
-    await writeModelsToConfigs({
-      planModel: 'plan-model',
-      buildModel: 'build-model',
-      fastModel: 'fast-model',
-      agentsDir,
-      preset: { roles: { build: { agents: ['back-engineer'] }, fast: { agents: [] } } },
-    })
-
-    expect(success).toHaveBeenCalled()
-  })
-})
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+vi.mock('../../utils/exec.js', () => ({
+  success: vi.fn(),
+}))
+
+import { success } from '../../utils/exec.js'
+import { writeModelToAgent, writeModelsToConfigs } from './write.js'
+
+describe('writeModelToAgent()', () => {
+  let tmpDir
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'models-write-test-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('adds model field to agent file frontmatter', async () => {
+    const filePath = path.join(tmpDir, 'test-agent.md')
+    const original = `---
+name: Test Agent
+description: A test agent
+---
+
+# Test Agent`
+    fs.writeFileSync(filePath, original, 'utf-8')
+
+    await writeModelToAgent(filePath, 'anthropic/claude-3-sonnet')
+
+    const updated = fs.readFileSync(filePath, 'utf-8')
+    expect(updated).toContain('model: anthropic/claude-3-sonnet')
+  })
+
+  it('preserves existing frontmatter fields', async () => {
+    const filePath = path.join(tmpDir, 'test-agent.md')
+    const original = `---
+name: Test Agent
+description: A test agent
+custom_field: custom_value
+---
+
+# Test Agent`
+    fs.writeFileSync(filePath, original, 'utf-8')
+
+    await writeModelToAgent(filePath, 'test/model')
+
+    const updated = fs.readFileSync(filePath, 'utf-8')
+    expect(updated).toContain('name: Test Agent')
+    expect(updated).toContain('description: A test agent')
+    expect(updated).toContain('custom_field: custom_value')
+    expect(updated).toContain('model: test/model')
+  })
+})
+
+describe('writeModelsToConfigs()', () => {
+  let tmpDir, agentsDir, opencodeJsonPath, originalCwd
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    originalCwd = process.cwd()
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'models-config-test-'))
+    agentsDir = path.join(tmpDir, '.agents', 'agents')
+    fs.mkdirSync(agentsDir, { recursive: true })
+    opencodeJsonPath = path.join(tmpDir, '.opencode', 'opencode.json')
+    path.join(tmpDir, '.opencode', 'ensemble.json')
+    fs.mkdirSync(path.dirname(opencodeJsonPath), { recursive: true })
+    process.chdir(tmpDir)
+  })
+
+  afterEach(() => {
+    process.chdir(originalCwd)
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('writes build model to agent files', async () => {
+    fs.writeFileSync(path.join(agentsDir, 'back-engineer.md'), '---\nname: Back\n---', 'utf-8')
+    fs.writeFileSync(path.join(agentsDir, 'front-engineer.md'), '---\nname: Front\n---', 'utf-8')
+
+    await writeModelsToConfigs({
+      planModel: 'plan-model',
+      buildModel: 'build-model',
+      fastModel: 'fast-model',
+      agentsDir,
+      preset: {
+        roles: {
+          build: { agents: ['back-engineer'] },
+          fast: { agents: ['front-engineer'] },
+        },
+      },
+    })
+
+    expect(success).toHaveBeenCalledWith('back-engineer → build-model')
+    expect(success).toHaveBeenCalledWith('front-engineer → fast-model')
+  })
+
+  it('reports success when writing configs', async () => {
+    const agentFile = path.join(agentsDir, 'back-engineer.md')
+    fs.writeFileSync(agentFile, '---\nname: Back\n---', 'utf-8')
+
+    await writeModelsToConfigs({
+      planModel: 'plan-model',
+      buildModel: 'build-model',
+      fastModel: 'fast-model',
+      agentsDir,
+      preset: { roles: { build: { agents: ['back-engineer'] }, fast: { agents: [] } } },
+    })
+
+    expect(success).toHaveBeenCalled()
+  })
+})

package/src/steps/openspec/ensemble.js

@@ -36,7 +36,14 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       DO NOT call team_claim yourself, only agents claim tasks.
       DO NOT proceed to 6d until team_tasks_add succeeds.
 
-   **Step 6d.** Discover relevant skills, then spawn specialists.
+   **Step 6d.** Discover relevant skills, then spawn specialists with an INITIAL BATCH of tasks.
+
+      **ROLLING BATCH MODEL:**
+      Agents do NOT receive all their tasks upfront. Instead:
+      - Assign each agent an initial batch of up to 3 unblocked tasks.
+      - When an agent completes its batch and messages back, the lead assigns the next batch of up to 3 unassigned tasks from the board that match the agent's domain.
+      - Repeat until no pending tasks remain on the board.
+      - Only shut down an agent when the board has no more tasks for its domain.
 
       Before spawning, scan \`.agents/skills/\` and read each \`SKILL.md\` description line.
       Match skills to agents by domain:
@@ -49,11 +56,11 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 
       The spawn prompt must contain exactly:
       1. Their name and role on this team
-      2. Which tasks are theirs, include the LITERAL task IDs (e.g. "task-abc123") AND the task content for each. Copy them verbatim from the IDs returned by team_tasks_add. Do NOT paraphrase or omit IDs.
+      2. Their initial batch of tasks (up to 3): include the LITERAL task IDs (e.g. "task-abc123") AND the task content. Copy them verbatim from the IDs returned by team_tasks_add. Do NOT paraphrase or omit IDs.
       3. Key context they need (summarized from context files, do NOT tell them to read files themselves)
       4. The 6 OpenCode tools they have available (these are OpenCode tools, NOT shell commands, call them directly as tools, never via bash):
          team_claim, team_tasks_complete, team_tasks_list, team_tasks_add, team_message, team_broadcast
-      5. How to proceed: for EACH task ID listed above, call team_claim tool with that exact task_id before starting it, call team_tasks_complete tool with that task_id after finishing it, then move to the next task. When all tasks are done or blocked, call team_message to notify lead with results or blockers.
+      5. How to proceed: for EACH task ID listed, call team_claim tool with that exact task_id before starting it, call team_tasks_complete tool with that task_id after finishing it, then move to the next task. When all listed tasks are done, message lead with results. Lead may assign more tasks, do NOT shut down until lead confirms no more tasks.
       6. Which skills to load: list the skill names and paths they MUST read before implementing. Example: "Before starting, read \`.agents/skills/next-best-practices/SKILL.md\` and follow its rules for all Next.js code."
 
       Keep spawn prompts under 600 tokens. Do not describe team internals or how ensemble works.
@@ -86,12 +93,24 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       - \`team_view member:"<name>"\` for a teammate live session
       - \`team_results from:"<name>"\` for full teammate report text
 
-   **Step 6f.** When a teammate messages back, you receive a ping only, the full content is NOT in the notification.
-      Call team_results to read the full message and mark it read. Then for each teammate: team_shutdown -> team_merge.
-      If team_merge blocks ("overlapping local changes"), commit or stash your local changes first, then retry.
-      Fix any other blockers reported.
+   **Step 6f.** When a teammate messages back (rolling re-assignment loop):
+      1. Call \`team_results from:"<name>"\` to read full message.
+      2. Call \`team_tasks_list\` to check remaining pending/unassigned tasks on the board.
+      3. **If there are more unassigned tasks matching this agent's domain:**
+         - Pick up to 3 unassigned, unblocked tasks for this agent's domain.
+         - Send them via \`team_message to:"<name>" text:"Next tasks: [task-<id1>] <desc>, [task-<id2>] <desc>. Claim each with team_claim before starting."\`
+         - Do NOT shut down the agent. Go back to waiting (step 6e).
+      4. **If no more tasks for this agent:**
+         - \`team_shutdown member:"<name>"\`
+         - \`team_merge member:"<name>"\`
+         - If team_merge blocks on local changes: \`git stash\`, retry merge, \`git stash pop\`.
+      5. **If ALL agents are shut down and tasks remain unassigned** (new domain, dependencies unblocked):
+         - Spawn new agents for the remaining tasks (back to step 6d).
+      6. **If ALL tasks are done:** proceed to step 7.
       If a teammate reports rate-limit/quota/token exhaustion, immediately shutdown that teammate and respawn with an available model.
 
+      **ZERO PENDING TASKS GUARANTEE:** Before proceeding to step 7, call \`team_tasks_list\` and verify EVERY task is either \`done\` or \`blocked\`. If any task is \`pending\` and unassigned, assign it to an agent or spawn a new one. Never leave pending tasks orphaned.
+
 7. **Quality check**
 
    Spawn quality engineer with worktree:false (read-only, no file edits):
@@ -123,13 +142,17 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 - NEVER call team_spawn before team_tasks_add, tasks must exist before agents are spawned
 - NEVER poll team_results or team_status in a loop, wait for teammates to message you
 - NEVER call team_claim or team_tasks_complete as lead, only agents call these tools
+- NEVER leave pending tasks orphaned, always verify board is empty before proceeding to step 7
 - ALWAYS pass the LITERAL task IDs returned by team_tasks_add into each agent's spawn prompt, copy the exact IDs, never paraphrase
+- ALWAYS assign initial batch of up to 3 tasks per agent; re-assign next batch (up to 3) via team_message when agent reports done
+- ALWAYS call team_tasks_list after each agent reports done to check for remaining unassigned tasks
 - ALWAYS repeat the same literal task IDs in the team_message start trigger, never send a generic "claim your first task" without the actual IDs
 - NEVER send a start message that omits task IDs; if a task ID is missing from the start message, the agent cannot claim
 - NEVER edit files between team_spawn and team_merge, team_merge blocks on overlapping local changes
 - ALWAYS add every task to the board with team_tasks_add before spawning
 - ALWAYS spawn agents sequentially (wait for each team_spawn result before the next), then send start messages to all of them together
 - ALWAYS instruct agents to call team_claim before each task and team_tasks_complete after
+- ALWAYS shut down + merge agents only when no more tasks remain for their domain
 - If teammates are stuck, use team_message to resend tasks, then wait, never implement directly
 - Mark tasks complete in openspec AFTER specialists finish, not before
 - Pause on errors, blockers, or unclear requirements. Do not guess