opencode-onboard 0.4.2 → 0.4.4

package/content/.opencode/skills/openspec-apply-change/SKILL.md

@@ -92,71 +92,90 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
       DO NOT call team_claim yourself, only agents claim tasks.
       DO NOT proceed to 6d until team_tasks_add succeeds.
 
-   **Step 6d.** Discover available agents, assign tasks by best fit, then spawn workers.
-
-      Agent discovery and assignment rule:
-      - Read `.agents/agents/*.md` and use each agent's `description` and `## Abilities` to understand specialization.
-      - For each task ID, choose the best-fit agent based on task domain (backend, frontend, infra, testing, etc.).
-      - Prefer specialized agents when available; use `basic-engineer` as fallback only.
-      - Only spawn agents that have assigned task IDs.
-
-      REQUIRED assignment algorithm (do not skip):
-      1. Build candidate list from `.agents/agents/*.md` excluding `devops-manager`.
-      2. Classify each task by domain using task text (api/backend, ui/frontend, infra/devops, testing/qa).
-      3. For each task, score every candidate agent:
-         - +3 if agent description explicitly matches domain
-         - +2 if agent `## Abilities` include domain-relevant skills
-         - +1 if prior tasks of same domain already assigned to that agent (cohesion)
-      4. Assign task to highest-score agent.
-      5. Use `basic-engineer` ONLY when no specialized agent has positive score.
-      6. If all tasks go to `basic-engineer`, you MUST explain why no specialist matched.
-
-      HARD RULES:
-      - NEVER assign a task to `basic-engineer` if a specialized agent has higher score.
-      - NEVER skip agent discovery from `.agents/agents/*.md`.
-      - ALWAYS include assignment rationale in spawn prompt: "Selected because <domain match>".
-
-      Skill loading is worker-driven:
-      - The spawned agent MUST load `@ob-global` first.
-      - Then it MUST load skills from its own `## Abilities` for the claimed task domain.
-
-      Each team_spawn MUST include the agent field (required, causes NOT NULL error if omitted).
-
-      The spawn prompt must contain exactly:
-      1. Their name and role on this team
-      2. Which tasks are theirs, list the task IDs and content from the board
-      2.1 Why they were selected for those tasks (domain/abilities match)
-      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: call team_claim tool with the task_id to claim a task before starting it, call team_tasks_complete tool after finishing it, repeat until all their tasks are done, then call team_message tool to notify lead with results or blockers
-      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.
-      Only spawn agents whose tasks are actually needed by this change. Skip agents with no tasks.
-
-      Spawn one or more best-fit workers (parallel when dependencies allow):
-      ```
-      team_spawn name:"eng-1" agent:"backend-engineer" prompt:"..."
-      team_spawn name:"eng-2" agent:"frontend-engineer" prompt:"..."
-      team_spawn name:"eng-3" agent:"basic-engineer" prompt:"..."
-      ```
-
-      Then immediately send each spawned worker a start message with exact task IDs:
-      ```
-      team_message to:"eng-1" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id1>] ... Claim each task ID before starting."
-      team_message to:"eng-2" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id2>] ... Claim each task ID before starting."
-      team_message to:"eng-3" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id3>] ... Claim each task ID before starting."
-      ```
+   **Step 6d.** Discover available agents, assign an INITIAL BATCH of tasks, then spawn workers.
+
+       **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.
+
+       Agent discovery and assignment rule:
+       - Read `.agents/agents/*.md` and use each agent's `description` and `## Abilities` to understand specialization.
+       - For each task ID, choose the best-fit agent based on task domain (backend, frontend, infra, testing, etc.).
+       - Prefer specialized agents when available; use `basic-engineer` as fallback only.
+       - Only spawn agents that have assigned task IDs.
+
+       REQUIRED assignment algorithm (do not skip):
+       1. Build candidate list from `.agents/agents/*.md` excluding `devops-manager`.
+       2. Classify each task by domain using task text (api/backend, ui/frontend, infra/devops, testing/qa).
+       3. For each task, score every candidate agent:
+          - +3 if agent description explicitly matches domain
+          - +2 if agent `## Abilities` include domain-relevant skills
+          - +1 if prior tasks of same domain already assigned to that agent (cohesion)
+       4. Assign task to highest-score agent.
+       5. Use `basic-engineer` ONLY when no specialized agent has positive score.
+       6. If all tasks go to `basic-engineer`, you MUST explain why no specialist matched.
+
+       HARD RULES:
+       - NEVER assign a task to `basic-engineer` if a specialized agent has higher score.
+       - NEVER skip agent discovery from `.agents/agents/*.md`.
+       - ALWAYS include assignment rationale in spawn prompt: "Selected because <domain match>".
+
+       Skill loading is worker-driven:
+       - The spawned agent MUST load `@ob-global` first.
+       - Then it MUST load skills from its own `## Abilities` for the claimed task domain.
+
+       Each team_spawn MUST include the agent field (required, causes NOT NULL error if omitted).
+
+       The spawn prompt must contain exactly:
+       1. Their name and role on this team
+       1.1 Why they were selected for those tasks (domain/abilities match)
+       2. Their initial batch of tasks (up to 3): list the LITERAL task IDs and content from the board.
+       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: call team_claim tool with the task_id to claim a task before starting it, call team_tasks_complete tool after finishing it, repeat until all listed tasks are done, then call team_message tool to notify 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.
+       Only spawn agents whose tasks are actually needed by this change. Skip agents with no tasks.
+
+       Spawn one or more best-fit workers (parallel when dependencies allow):
+       ```
+       team_spawn name:"eng-1" agent:"backend-engineer" prompt:"..."
+       team_spawn name:"eng-2" agent:"frontend-engineer" prompt:"..."
+       team_spawn name:"eng-3" agent:"basic-engineer" prompt:"..."
+       ```
+
+       Then immediately send each spawned worker a start message with exact task IDs:
+       ```
+       team_message to:"eng-1" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id1>] ... Claim each task ID before starting."
+       team_message to:"eng-2" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id2>] ... Claim each task ID before starting."
+       team_message to:"eng-3" text:"Start now. Load @ob-global first, then use your agent `## Abilities` for these tasks: [task-<id3>] ... Claim each task ID before starting."
+       ```
 
    **Step 6e.** After sending start messages, tell the user what is running, then STOP and wait.
-      Do NOT call team_results, team_status, or team_broadcast in a loop.
-      Teammates will message you when done or blocked. Wait for those messages.
-
-   **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.
+       Do NOT call team_results, team_status, or team_broadcast in a loop.
+       Teammates will message you when done or blocked. Wait for those messages.
+
+   **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:**
+          - Spawn new agents for the remaining tasks (back to step 6d).
+       6. **If ALL tasks are done:** proceed to step 7.
+
+       **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. **Verification check**
 
@@ -189,11 +208,14 @@ Implement tasks from an OpenSpec change using the ensemble agent 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
-- ALWAYS pass the task IDs returned by team_tasks_add to each agent's spawn prompt
+- NEVER leave pending tasks orphaned, always verify board is empty before proceeding to step 7
+- 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
 - 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 workers based on dependencies: parallel when safe, sequential when required
 - 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 worker implementation and verification finish, not before
 - Pause on errors, blockers, or unclear requirements. Do not guess

package/content/AGENTS.md

@@ -63,13 +63,32 @@ 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
+
+Write `openspec/config.yaml` with the real project information discovered during steps 1-3. Overwrite whatever is currently in the file. The output must contain `schema: spec-driven` and a populated `context:` block. Do not leave placeholder text.
+
+```yaml
+schema: spec-driven
+
+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>
+```
+
+Replace every `<…>` with real values from the codebase. Add a `rules:` section 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 +99,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 +118,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 +158,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
@@ -163,7 +190,7 @@ If a teammate stalls due to model quota/rate-limit exhaustion:
 
 ---
 
-## Pipeline
+## Pipeline
 
 ```
 devops-manager (lead mode)
@@ -181,7 +208,7 @@ devops-manager (ship mode)
   → verify completion → commit → push → PR → post comment
 ```
 
-### Phase 1, Parse & Propose
+### Phase 1, Parse & Propose
 
 ```
 1. Detect URL type → load matching skill (ob-userstory-gh or ob-userstory-az)
@@ -191,16 +218,17 @@ 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
 
@@ -254,7 +282,7 @@ Default `basic-engineer` abilities:
 - Infrastructure: @ob-default
 ```
 
-## Skills
+## Skills
 
 Skills provide platform and tech-specific knowledge. Agents detect and load them automatically, **you never tell an agent which skill to use**.
 
@@ -273,10 +301,10 @@ Skills are located in `.agents/skills/`. Each skill has a `SKILL.md` with a desc
 | `ob-pullrequest-gh` | Create PR on GitHub |
 | `openspec-propose` | Propose change artifacts (proposal, specs, tasks) |
 | `openspec-apply-change` | Implement change with agent team |
-| `openspec-archive-change` | Archive completed change |
-| `browser-automation` | Browser automation for localhost UI, screenshots, clicks, queries |
-
-Execution rules live in skills. Keep AGENTS.md focused on orchestration and routing.
+| `openspec-archive-change` | Archive completed change |
+| `browser-automation` | Browser automation for localhost UI, screenshots, clicks, queries |
+
+Execution rules live in skills. Keep AGENTS.md focused on orchestration and routing.
 
 ---
 
@@ -317,16 +345,16 @@ When `## Source Roots` lists multiple roots, each root is an independent git rep
 
 ---
 
-## Guardrails
-
-Guardrails are mandatory via `ob-global` and ability-loaded skills.
-
-Minimal non-negotiables:
-- Never commit or push to `main`.
-- Never force push.
-- Never expose or commit secrets.
-- Use `gh`/`az` CLI for platform operations.
-- In multi-repo source scope, run git operations per repository.
+## Guardrails
+
+Guardrails are mandatory via `ob-global` and ability-loaded skills.
+
+Minimal non-negotiables:
+- Never commit or push to `main`.
+- Never force push.
+- Never expose or commit secrets.
+- Use `gh`/`az` CLI for platform operations.
+- In multi-repo source scope, run git operations per repository.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-onboard",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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,99 +1,124 @@
-import chalk from 'chalk'
-import { chooseSourceScope } from '../steps/source/index.js'
-import { cleanAiFiles } from '../steps/clean/index.js'
-import { choosePlatform } from '../steps/platform/index.js'
-import { copyContentStep } from '../steps/copy/index.js'
-import { initOpenspec } from '../steps/openspec/index.js'
-import { chooseModels } from '../steps/models/index.js'
-import { tokenOptimizationStep } from '../steps/optimization/index.js'
-import { installBrowser } from '../steps/browser/index.js'
-import { writeOnboardConfig } from '../steps/metadata/index.js'
-
-export async function runWizard(version) {
-  const logo = chalk.hex('#fe3d57')
-  const bannerLines = [
-    logo('                             '),
-    logo('        ▒▒▒▒▒▒▒▒▒▒▒▒▒        '),
-    logo('        ▒▒▓       ▓▒▓        '),
-    logo('   ▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒   '),
-    logo('  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓  '),
-    logo(' ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓ '),
-    logo(' ▓▒▒▒▒░░░▒▒▒▒▒▒▒▒▒▒▒░░░▒▒▒▓▓ '),
-    logo('  ▓▓▓▓▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▓▓▓▓  '),
-    logo('  ▓▓▒▒▒▒▒▒░▒▒▒▒▒▒▒░▒▒▒▒▒▒▓▓  '),
-    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
-    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
-    logo('   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    '),
-    '',
-    chalk.bold('        🧰 opencode-onboard') + chalk.dim(` v${version}`),
-    chalk.dim('        Prepare your codebase for AI agents'),
-  ]
-
-  for (const line of bannerLines) console.log(line)
-  console.log()
-  console.log('  This tool will set up your project with a team of AI agents,')
-  console.log('  install skills, select models, and configure OpenCode.')
-  console.log()
-
-  // Only wait for Enter in a real interactive TTY
-  if (process.stdin.isTTY) {
-    console.log(chalk.bold('  Press Enter to begin...'))
-    console.log()
-    await new Promise(resolve => {
-      process.stdin.resume()
-      process.stdin.once('data', () => {
-        process.stdin.pause()
-        resolve()
-      })
-    })
-  }
-
-  const scope = await chooseSourceScope()
-
-  const preserve = await cleanAiFiles()
-  const ctx = { ...preserve, ...scope }
-
-  const platform = await choosePlatform()
-
-  await copyContentStep(platform, ctx)
-
-  await initOpenspec()
-
-  const selectedModels = await chooseModels()
-
-  const tokenOpt = await tokenOptimizationStep({ ctx })
-  const { rtk, quota, caveman, cavemanGuidance } = tokenOpt
-
-  await installBrowser()
-
-  await writeOnboardConfig({
-    ...ctx,
-    platform,
-    additionalSkillsProvider: 'npx-skills',
-    ...selectedModels,
-    optionalTools: { rtk, quota, caveman },
-    cavemanGuidance,
-  })
-
-  const toGenerate = [
-    !ctx.hasDesign && 'DESIGN.md',
-    !ctx.hasArchitecture && 'ARCHITECTURE.md',
-  ].filter(Boolean)
-
-  console.log()
-  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
-  console.log(chalk.bold.green('  Onboarding complete!'))
-  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
-  console.log()
-  console.log('  Open this project in OpenCode and type:')
-  console.log(chalk.bold('  "init"'))
-  console.log()
-  if (toGenerate.length > 0) {
-    console.log(`  OpenCode will generate ${toGenerate.join(' and ')}`)
-    console.log('  from your actual codebase, then activate the agent team.')
-  } else {
-    console.log('  OpenCode will activate the agent team.')
-  }
-  console.log(`  Source scope: ${ctx.sourceMode === 'parent-selected' ? ctx.sourceRoots.map(p => `../${p.split(/[/\\]/).pop()}`).join(', ') : 'current folder'}`)
-  console.log()
-}
+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'
+import { choosePlatform } from '../steps/platform/index.js'
+import { copyContentStep } from '../steps/copy/index.js'
+import { initOpenspec } from '../steps/openspec/index.js'
+import { chooseModels } from '../steps/models/index.js'
+import { tokenOptimizationStep } from '../steps/optimization/index.js'
+import { installBrowser } from '../steps/browser/index.js'
+import { writeOnboardConfig } from '../steps/metadata/index.js'
+
+export async function runWizard(version) {
+  const logo = chalk.hex('#fe3d57')
+  const bannerLines = [
+    logo('                             '),
+    logo('        ▒▒▒▒▒▒▒▒▒▒▒▒▒        '),
+    logo('        ▒▒▓       ▓▒▓        '),
+    logo('   ▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒   '),
+    logo('  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓  '),
+    logo(' ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓ '),
+    logo(' ▓▒▒▒▒░░░▒▒▒▒▒▒▒▒▒▒▒░░░▒▒▒▓▓ '),
+    logo('  ▓▓▓▓▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▓▓▓▓  '),
+    logo('  ▓▓▒▒▒▒▒▒░▒▒▒▒▒▒▒░▒▒▒▒▒▒▓▓  '),
+    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
+    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
+    logo('   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    '),
+    '',
+    chalk.bold('        🧰 opencode-onboard') + chalk.dim(` v${version}`),
+    chalk.dim('        Prepare your codebase for AI agents'),
+  ]
+
+  for (const line of bannerLines) console.log(line)
+  console.log()
+  console.log('  This tool will set up your project with a team of AI agents,')
+  console.log('  install skills, select models, and configure OpenCode.')
+  console.log()
+
+  // Only wait for Enter in a real interactive TTY
+  if (process.stdin.isTTY) {
+    console.log(chalk.bold('  Press Enter to begin...'))
+    console.log()
+    await new Promise(resolve => {
+      process.stdin.resume()
+      process.stdin.once('data', () => {
+        process.stdin.pause()
+        resolve()
+      })
+    })
+  }
+
+  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 installScope = await wizardSelect({
+    message: 'Install dependencies:',
+    default: 'local',
+    choices: [
+      { name: 'Locally (default)', value: 'local', description: 'Install tools project-locally where possible' },
+      { name: 'Globally', value: 'global', description: 'Install tools globally (affects all projects on this machine)' },
+    ],
+  })
+
+  const preserve = await cleanAiFiles()
+  const ctx = { ...preserve, ...scope, maxConcurrentAgents, installScope }
+
+  const platform = await choosePlatform()
+
+  await copyContentStep(platform, ctx)
+
+  const openspec = await initOpenspec()
+
+  const selectedModels = await chooseModels()
+
+  const tokenOpt = await tokenOptimizationStep({ ctx })
+  const { rtk, quota, caveman, cavemanGuidance } = tokenOpt
+
+  await installBrowser(ctx)
+
+  await writeOnboardConfig({
+    ...ctx,
+    platform,
+    openspec,
+    maxConcurrentAgents,
+    installScope,
+    additionalSkillsProvider: 'npx-skills',
+    ...selectedModels,
+    optionalTools: { rtk, quota, caveman },
+    cavemanGuidance,
+  })
+
+  const toGenerate = [
+    !ctx.hasDesign && 'DESIGN.md',
+    !ctx.hasArchitecture && 'ARCHITECTURE.md',
+  ].filter(Boolean)
+
+  console.log()
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log(chalk.bold.green('  Onboarding complete!'))
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log()
+  console.log('  Open this project in OpenCode and type:')
+  console.log(chalk.bold('  "init"'))
+  console.log()
+  if (toGenerate.length > 0) {
+    console.log(`  OpenCode will generate ${toGenerate.join(' and ')}`)
+    console.log('  from your actual codebase, then activate the agent team.')
+  } else {
+    console.log('  OpenCode will activate the agent team.')
+  }
+  console.log(`  Source scope: ${ctx.sourceMode === 'parent-selected' ? ctx.sourceRoots.map(p => `../${p.split(/[/\\]/).pop()}`).join(', ') : 'current folder'}`)
+  console.log()
+}