opencode-onboard 0.4.2 → 0.4.3

package/content/AGENTS.md

@@ -63,13 +63,30 @@ The output must be a real, populated `ARCHITECTURE.md` based on what you found i
 
 ---
 
-### Step 4, Rewrite this file
+### Step 4, Populate OpenSpec config
+
+Read `openspec/config.yaml`. It contains a template with commented-out examples. Fill in the `context:` field with real project information discovered during steps 1-3:
+
+```yaml
+context: |
+  Tech stack: <languages, frameworks, libraries found in the codebase>
+  Build system: <build tools, package managers>
+  Architecture: <monolith, microservices, monorepo, etc.>
+  Conventions: <coding style, commit conventions, branching strategy if found>
+  Domain: <what this project does, in one line>
+```
+
+Keep the `schema: spec-driven` line. Add `rules:` only if the codebase has clear conventions worth enforcing (e.g., max task size, proposal format). Do not invent rules that aren't evidenced by the codebase.
+
+---
+
+### Step 5, Rewrite this file
 
 Replace the entire contents of this file (`AGENTS.md`) with everything below the line `<!-- AGENTS-TEMPLATE-START -->` in this same file. Delete the bootstrap section and the template marker, the file should contain only the template content when done.
 
 ---
 
-### Step 5, Confirm
+### Step 6, Confirm
 
 Tell the user:
 
@@ -80,6 +97,7 @@ Tell the user:
 
 - ARCHITECTURE.md generated
 - DESIGN.md generated
+- openspec/config.yaml populated
 - Project history archived in openspec
 - AGENTS.md updated with real guidance
 
@@ -98,7 +116,7 @@ After restarting you are ready to work.
 - Do NOT create branches or PRs
 - Do NOT modify any project source files
 - Do NOT create CLI wrapper files or scripts
-- Only read source files for analysis, write only to ARCHITECTURE.md, DESIGN.md, AGENTS.md, and openspec/
+- Only read source files for analysis, write only to ARCHITECTURE.md, DESIGN.md, AGENTS.md, openspec/config.yaml, and openspec/
 
 <!-- AGENTS-TEMPLATE-START -->
 # AGENTS.md
@@ -138,18 +156,25 @@ Trigger patterns, I recognize ALL of these, exact wording does not matter:
 
 **Never delegate without a plan. Never write implementation code directly, always spawn specialists, no exceptions. "Small feature", "faster to do it directly", or "environment issues" are not valid reasons to skip ensemble.**
 
-## Multi-Agent Execution, opencode-ensemble
-
-Parallel execution uses the `opencode-ensemble` plugin (`team_create`, `team_spawn`, etc.).
-Works on **all platforms** (Windows, macOS, Linux) via OpenCode's built-in worktree support.
-
-Core tools used in this workflow:
-- `team_create`, `team_spawn`, `team_shutdown`, `team_merge`, `team_cleanup`
-- `team_tasks_add`, `team_tasks_list`, `team_claim`, `team_tasks_complete`
-- `team_message`, `team_results`, `team_status`
+## Multi-Agent Execution, opencode-ensemble
+
+Parallel execution uses the `opencode-ensemble` plugin (`team_create`, `team_spawn`, etc.).
+Works on **all platforms** (Windows, macOS, Linux) via OpenCode's built-in worktree support.
+
+Core tools used in this workflow:
+- `team_create`, `team_spawn`, `team_shutdown`, `team_merge`, `team_cleanup`
+- `team_tasks_add`, `team_tasks_list`, `team_claim`, `team_tasks_complete`
+- `team_message`, `team_results`, `team_status`
 
 **Dashboard**: Monitor running agents at **http://localhost:4747/**
 
+**Hard limits:**
+- **Max {{MAX_CONCURRENT_AGENTS}} truly concurrent agents.** All {{MAX_CONCURRENT_AGENTS}} must be spawned and running simultaneously, not sequentially. Spawn in waves if more than {{MAX_CONCURRENT_AGENTS}} are needed. Wait for wave N to finish before spawning wave N+1.
+- **Non-overlapping file domains.** Each agent owns exclusive directories. Two agents must NEVER touch the same file.
+- **Immediate shutdown on completion.** The moment an agent's domain has no more pending tasks → `team_shutdown` → `team_merge`. Keep agents alive if more tasks in their domain are pending (rolling batch).
+- **Rolling batch assignment.** Agents receive up to 3 tasks initially. When they complete a batch, lead assigns the next batch of up to 3 from the board. Never leave pending tasks orphaned.
+- **Stall detection at 5 minutes.** No commits after 5 min → nudge message → 2 min grace → force shutdown + respawn.
+
 **Progress inspection commands (tell user explicitly after spawning):**
 - `team_status` for live team snapshot
 - `team_tasks_list` for task board state
@@ -159,7 +184,7 @@ Core tools used in this workflow:
 If a teammate stalls due to model quota/rate-limit exhaustion:
 1. `team_shutdown name:"<stuck-member>" force:true`
 2. `team_spawn` same member/task with an available model
-3. `team_message` start instruction with the exact next task ID
+3. `team_message` start instruction with the exact next task ID
 
 ---
 
@@ -191,15 +216,16 @@ devops-manager (ship mode)
 5. STOP. Ask user: "Ready to implement? (yes/no)", DO NOT proceed until confirmed.
 ```
 
-### Phase 2, Implement
-
-```
-1. Run /opsx-apply.
-   - Lead adds all tasks to board.
-   - Lead spawns one or more engineers (`basic-engineer` and/or custom engineers) in parallel where safe.
-   - Each engineer must claim task IDs, load relevant abilities, implement, and complete tasks.
-   - Lead merges each engineer branch after shutdown, then marks tasks done in tasks.md.
-2. Verify with tests/build/lint according to task scope.
+### Phase 2, Implement
+
+```
+1. Run /opsx-apply.
+   - Lead adds all tasks to board.
+   - Lead spawns engineers with initial batch of up to 3 tasks each (rolling batch model).
+   - Each engineer claims tasks, implements, completes, messages lead.
+   - Lead assigns next batch (up to 3) to agents that report done. Repeat until board empty.
+   - Lead merges each engineer branch after shutdown, then marks tasks done in tasks.md.
+2. Verify with tests/build/lint according to task scope.
 ```
 
 ### Phase 3, Ship

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-onboard",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Prepare any brownfield codebase for AI agent workflows using OpenCode, OpenSpec, and ensemble orchestration.",
   "keywords": [
     "opencode",

package/src/commands/join.js

@@ -1,15 +1,15 @@
 import chalk from 'chalk'
-import { header, info } from '../utils/exec.js'
 import { installBrowser } from '../steps/browser/index.js'
 import { checkRtk } from '../steps/optimization/index.js'
-import { choosePlatform, checkPlatform } from '../steps/platform/index.js'
+import { checkPlatform, choosePlatform } from '../steps/platform/index.js'
+import { header, info } from '../utils/exec.js'
 import { readOnboardConfig } from './shared.js'
 
 export async function runJoin() {
   const logo = chalk.hex('#fe3d57')
   console.log()
   console.log(logo('  🤝 opencode-onboard join'))
-  console.log(chalk.dim('  New team member setup — checks & local installs only'))
+  console.log(chalk.dim('  New team member setup, checks & local installs only'))
   console.log(chalk.dim('  This will NOT modify any project files.'))
   console.log()
 

package/src/commands/single.js

@@ -17,6 +17,7 @@ export async function runSingleCommand(command) {
     hasOpenspec: !!savedWizard?.preserved?.openspec,
     sourceMode: savedWizard?.sourceMode ?? 'current',
     sourceRoots: Array.isArray(savedWizard?.sourceRoots) ? savedWizard.sourceRoots : [],
+    maxConcurrentAgents: savedWizard?.maxConcurrentAgents ?? 4,
   }
   const platform = savedWizard?.platform
   const resolvedPlatform = platform === 'azure' || platform === 'github' ? platform : 'github'
@@ -47,6 +48,7 @@ export async function runSingleCommand(command) {
       await writeOnboardConfig({
         ...ctx,
         platform: resolvedPlatform,
+        maxConcurrentAgents: savedWizard?.maxConcurrentAgents ?? 4,
         additionalSkillsProvider: 'npx-skills',
         planModel: savedWizard?.models?.plan ?? null,
         buildModel: savedWizard?.models?.build ?? null,

package/src/commands/wizard.js

@@ -1,3 +1,4 @@
+import { select as wizardSelect } from '@inquirer/prompts'
 import chalk from 'chalk'
 import { chooseSourceScope } from '../steps/source/index.js'
 import { cleanAiFiles } from '../steps/clean/index.js'
@@ -50,8 +51,20 @@ export async function runWizard(version) {
 
   const scope = await chooseSourceScope()
 
+  const maxConcurrentAgents = await wizardSelect({
+    message: 'Max concurrent agents:',
+    default: 4,
+    choices: [
+      { name: '2', value: 2, description: 'Conservative — lower resource usage' },
+      { name: '3', value: 3, description: 'Moderate parallelism' },
+      { name: '4 (default)', value: 4, description: 'Recommended for most projects' },
+      { name: '5', value: 5, description: 'High parallelism — requires more resources' },
+      { name: '6', value: 6, description: 'Maximum parallelism' },
+    ],
+  })
+
   const preserve = await cleanAiFiles()
-  const ctx = { ...preserve, ...scope }
+  const ctx = { ...preserve, ...scope, maxConcurrentAgents }
 
   const platform = await choosePlatform()
 
@@ -69,6 +82,7 @@ export async function runWizard(version) {
   await writeOnboardConfig({
     ...ctx,
     platform,
+    maxConcurrentAgents,
     additionalSkillsProvider: 'npx-skills',
     ...selectedModels,
     optionalTools: { rtk, quota, caveman },

package/src/presets/source.json

@@ -11,7 +11,13 @@
       "name": "Select folders in parent (../)",
       "value": "parent",
       "description": "Use when this repo only contains agent config"
+    },
+    {
+      "name": "Select child folders (./*/)",
+      "value": "children",
+      "description": "Use when source code lives in subdirectories of this repo"
     }
   ],
-  "parentSelectionMessage": "Select source folders from parent directory:"
+  "parentSelectionMessage": "Select source folders from parent directory:",
+  "childrenSelectionMessage": "Select child folders to include as source:"
 }

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

@@ -33,6 +33,7 @@ export async function writeOnboardConfig(data) {
       platform: data.platform,
       sourceMode: data.sourceMode,
       sourceRoots: data.sourceRoots,
+      maxConcurrentAgents: data.maxConcurrentAgents ?? 4,
       preserved: {
         design: !!data.hasDesign,
         architecture: !!data.hasArchitecture,

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

package/src/steps/source/index.js

@@ -8,6 +8,26 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const SOURCE_PRESET_PATH = path.resolve(__dirname, '../../presets/source.json')
 const sourcePreset = await fse.readJson(SOURCE_PRESET_PATH)
 
+async function listChildFolders(cwd) {
+  const entries = await fse.readdir(cwd)
+  const dirs = []
+
+  for (const name of entries) {
+    if (name.startsWith('.')) continue
+    const abs = path.join(cwd, name)
+    try {
+      const stat = await fse.stat(abs)
+      if (!stat.isDirectory()) continue
+      dirs.push({ name, abs })
+    } catch {
+      // ignore invalid entries
+    }
+  }
+
+  dirs.sort((a, b) => a.name.localeCompare(b.name))
+  return dirs
+}
+
 async function listParentFolders(cwd) {
   const parent = path.resolve(cwd, '..')
   const entries = await fse.readdir(parent)
@@ -47,6 +67,34 @@ export async function chooseSourceScope() {
     return { sourceMode: 'current', sourceRoots: [cwd] }
   }
 
+  if (mode === 'children') {
+    const childFolders = await listChildFolders(cwd)
+    if (childFolders.length === 0) {
+      warn('No child folders found in current directory. Falling back to current folder.')
+      success(`Source scope: ${cwd}`)
+      return { sourceMode: 'current', sourceRoots: [cwd] }
+    }
+
+    const selected = await checkbox({
+      message: sourcePreset.childrenSelectionMessage,
+      choices: childFolders.map(d => ({
+        name: `./${d.name}`,
+        value: d.abs,
+        checked: true,
+      })),
+      required: true,
+    })
+
+    if (!selected || selected.length === 0) {
+      warn('No folders selected. Falling back to current folder.')
+      success(`Source scope: ${cwd}`)
+      return { sourceMode: 'current', sourceRoots: [cwd] }
+    }
+
+    success(`Source scope: ${selected.map(p => path.basename(p)).join(', ')}`)
+    return { sourceMode: 'children-selected', sourceRoots: selected }
+  }
+
   const parentFolders = await listParentFolders(cwd)
   if (parentFolders.length === 0) {
     warn('No sibling folders found in parent directory. Falling back to current folder.')

package/src/steps/source/source.test.js

@@ -23,8 +23,10 @@ vi.mock('fs-extra', () => ({
       choices: [
         { name: 'Current folder', value: 'current' },
         { name: 'Parent folder', value: 'parent' },
+        { name: 'Child folders', value: 'children' },
       ],
       parentSelectionMessage: 'Select sibling folders',
+      childrenSelectionMessage: 'Select child folders',
     }),
     readdir: vi.fn(),
     stat: vi.fn().mockResolvedValue({ isDirectory: () => true }),
@@ -88,4 +90,35 @@ describe('chooseSourceScope()', () => {
 
     expect(result.sourceMode).toBe('current')
   })
+
+  it('lists child folders when user selects children mode', async () => {
+    select.mockResolvedValue('children')
+    fse.readdir.mockResolvedValue(['packages', 'apps'])
+    checkbox.mockResolvedValue([path.join(tmpDir, 'packages')])
+
+    const result = await chooseSourceScope()
+
+    expect(checkbox).toHaveBeenCalled()
+    expect(result.sourceMode).toBe('children-selected')
+    expect(result.sourceRoots).toContain(path.join(tmpDir, 'packages'))
+  })
+
+  it('falls back to current when no child folders found', async () => {
+    select.mockResolvedValue('children')
+    fse.readdir.mockResolvedValue([])
+
+    const result = await chooseSourceScope()
+
+    expect(result.sourceMode).toBe('current')
+  })
+
+  it('falls back to current when no child folders selected', async () => {
+    select.mockResolvedValue('children')
+    fse.readdir.mockResolvedValue(['packages'])
+    checkbox.mockResolvedValue([])
+
+    const result = await chooseSourceScope()
+
+    expect(result.sourceMode).toBe('current')
+  })
 })