opencode-onboard 0.3.3 → 0.4.2

package/content/AGENTS.md

@@ -97,7 +97,7 @@ After restarting you are ready to work.
 - Do NOT implement any features
 - Do NOT create branches or PRs
 - Do NOT modify any project source files
-- Do NOT create RTK files, scripts, or wrappers, RTK is already defined in AGENTS.md and agent 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/
 
 <!-- AGENTS-TEMPLATE-START -->
@@ -112,17 +112,20 @@ This file provides guidance to AI agents when working in this repository.
 This is the agent orchestration layer for your project. It provides:
 - Universal agent team for development workflow
 - OpenSpec change management
-- Skills for platform-specific knowledge
+- Mandatory global baseline skill (`ob-global`) for all agents
+- Additional skills for platform/task-specific knowledge
 
 ## Source Scope
 
-- Read source scope from `.agents/source-roots.json`.
-- Use those roots for codebase analysis tasks (design, architecture, project-history, exploration).
-- If missing, default to current folder.
+Source scope is defined by mandatory `ob-global` skill.
+
+- Load `ob-global` first.
+- Follow the generated `## Source Roots` section from that skill.
+- Do not duplicate source-scope rules here.
 
 ## I Am the Lead, Full Workflow Ownership
 
-When the user provides a work item URL or says "implement the plan" or "I've added comments to the PR", **I own the full lifecycle**. I load the appropriate skill and use ensemble tools to coordinate the agent team.
+When the user provides a work item URL or says "implement the plan" or "I've added comments to the PR", **I own the full lifecycle**. I load `ob-global` skill first, then the appropriate userstory skill, and use ensemble tools to coordinate the agent team.
 
 Trigger patterns, I recognize ALL of these, exact wording does not matter:
 - User pastes or mentions a GitHub Issue URL → load `ob-userstory-gh` skill → parse issue → run `/opsx-propose` → confirm with user → run `/opsx-apply` → ship
@@ -135,26 +138,15 @@ 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.
-
-| Tool | What it does |
-|------|-------------|
-| `team_create` | Create a team (caller becomes lead) |
-| `team_spawn` | Start a teammate asynchronously |
-| `team_shutdown` | Stop a teammate, preserve their branch |
-| `team_merge` | Merge a teammate's branch into working dir |
-| `team_cleanup` | Tear down the team |
-| `team_results` | Retrieve full message content (delivery is a ping only) |
-| `team_message` | Send a direct message to a teammate or lead |
-| `team_broadcast` | Message all teammates |
-| `team_status` | View all members and task summary |
-| `team_tasks_list` | View the shared task board |
-| `team_tasks_add` | Add tasks to shared board |
-| `team_tasks_complete` | Mark task done, auto-unblocks dependents |
-| `team_claim` | Atomically claim a pending task (teammates use this) |
+## 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/**
 
@@ -171,30 +163,25 @@ If a teammate stalls due to model quota/rate-limit exhaustion:
 
 ---
 
-## Pipeline
+## Pipeline
 
 ```
-devops-manager (read mode)
-  → parse work item via skill → structured summary
+devops-manager (lead mode)
+  → load ob-global + parse work item via skill
         ↓
   openspec-propose
   → proposal.md + specs + tasks
         ↓
   [confirm with user]
         ↓
-back-engineer → front-engineer → infra-engineer  ← sequential, one at a time, only spawn what the task needs
-        ↓
-quality-engineer (worktree:false)
-  → tests, build, lint, acceptance criteria
-        ↓
-security-auditor (worktree:false)
-  → vulnerability audit, secrets, auth gaps
+basic-engineer + custom-engineer-* (parallel as needed)
+  → claim tasks + load abilities + implement
         ↓
 devops-manager (ship mode)
-  → screenshots → commit → push → PR → post comment
+  → 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)
@@ -204,60 +191,44 @@ 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, handles context reading, ensemble orchestration, and task marking.
-   - Lead adds all tasks to board, then spawns specialists ONE AT A TIME (not parallel)
-   - Each specialist claims tasks, implements, completes tasks, messages lead when done
-   - Lead merges each branch after shutdown, then marks tasks done in tasks.md
-2. After /opsx-apply completes, proceed to quality check.
-```
-
-### Phase 3, Quality
-
-```
-3. team_spawn name:quality agent:quality-engineer worktree:false → tests, build, lint
-4. Wait → team_results → fix any blockers → team_shutdown (no merge, worktree:false)
-```
+### 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 4, Security
+### Phase 3, Ship
 
 ```
-5. team_spawn name:security agent:security-auditor worktree:false → audit full change
-6. Wait → team_results → fix Critical findings → team_shutdown (no merge, worktree:false)
+3. team_spawn name:devops agent:devops-manager (ship mode)
+   → commit & push → create PR → post comment
+4. Wait → team_results → report PR URL to user
+5. team_cleanup
 ```
 
-### Phase 5, Ship
-
-```
-11. team_spawn name:devops agent:devops-manager (ship mode)
-    → screenshots → commit & push → create PR → post comment
-12. Wait → team_results → report PR URL to user
-13. team_cleanup
-```
-
-### Phase 6, PR Feedback Loop
+### Phase 4, PR Feedback Loop
 
 ```
 When user says "I've added comments to the PR" or asks to fix PR comments from PR URLs:
 1. team_create "pr-feedback-<id>-<random>"
 2. team_tasks_add with at least these lead-managed tasks:
    - Parse and classify PR feedback (devops-manager)
-   - Implement Api feedback items (back-engineer, if needed)
-   - Implement App feedback items (front-engineer, if needed)
-   - Infra feedback items (infra-engineer, if needed)
-   - Verify with tests/build (quality-engineer)
+   - Implement feedback items (basic-engineer and/or custom engineers)
+   - Verify with tests/build/lint (implementation worker or dedicated verifier if available)
    - Push updates and post PR replies (devops-manager)
 3. team_spawn devops-manager (feedback mode) with explicit task IDs, then team_message "Start now"
 4. Wait for message → team_results
-5. Add/update implementation tasks on board from parsed checklist (Api/App/Infra), then spawn needed specialists in parallel with explicit task IDs + team_message "Start now"
-6. Wait for specialist results → team_shutdown + team_merge per specialist
-7. team_spawn quality-engineer worktree:false with verification task ID + team_message "Start now"
-8. Wait → team_results → fix blockers if any
-9. team_spawn devops-manager (ship mode) with "push + update PR threads" task ID + team_message "Start now"
-10. Wait → team_results → report what was updated
-11. team_cleanup
+5. Add/update implementation tasks on board, then spawn needed engineers in parallel with explicit task IDs + team_message "Start now"
+6. Wait for engineer results → team_shutdown + team_merge per engineer
+7. Run verification tasks (tests/build/lint) and fix blockers if any
+8. team_spawn devops-manager (ship mode) with "push + update PR threads" task ID + team_message "Start now"
+9. Wait → team_results → report what was updated
+10. team_cleanup
 ```
 
 ---
@@ -269,28 +240,43 @@ All agents are universal, no project-specific knowledge. Platform and tech knowl
 | Agent | File | Role |
 |-------|------|------|
 | `devops-manager` | .agents/agents/devops-manager.md | Reads work items, creates PRs, handles review feedback |
-| `front-engineer` | .agents/agents/front-engineer.md | Web, mobile, UI implementation |
-| `back-engineer` | .agents/agents/back-engineer.md | APIs, services, data, AI implementation |
-| `infra-engineer` | .agents/agents/infra-engineer.md | Terraform, pipelines, cloud infrastructure |
-| `quality-engineer` | .agents/agents/quality-engineer.md | Unit, integration, e2e tests across all layers |
-| `security-auditor` | .agents/agents/security-auditor.md | Vulnerability audit, secrets, auth gaps |
+| `basic-engineer` | .agents/agents/basic-engineer.md | Generic implementation worker using ability-loaded skills |
+
+User can add more custom engineer agents and run them in parallel. Keep behavior ability-driven via skill mappings.
+
+Default `basic-engineer` abilities:
+
+```
+## Abilities
+- Guardrails: @ob-generic-guardrails, @ob-default
+- Development: @ob-default
+- Testing: @ob-default
+- Infrastructure: @ob-default
+```
 
-## Skills
+## Skills
 
-Skills provide platform and tech-specific knowledge. Agents detect and load them automatically, the user never specifies which skill to use.
+Skills provide platform and tech-specific knowledge. Agents detect and load them automatically, **you never tell an agent which skill to use**.
+
+`ob-global` is always loaded first, it provides baseline rules for all agents.
 
 Skills are located in `.agents/skills/`. Each skill has a `SKILL.md` with a description the agent reads to determine relevance.
 
 | Skill | Purpose |
 |-------|---------|
+| `ob-global` | Generic skill, baseline rules loaded by all agents. Context, source roots, git/secrets guardrails, token opt rules |
+| `ob-default` | Fallback skill, when no other skill matches |
+| `ob-generic-guardrails` | Minimal foundation for user guardrails skills |
 | `ob-userstory-az` | Parse Azure DevOps work item URL |
 | `ob-userstory-gh` | Parse GitHub Issue URL |
 | `ob-pullrequest-az` | Create PR on Azure DevOps |
 | `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 |
+| `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.
 
 ---
 
@@ -299,7 +285,7 @@ Skills are located in `.agents/skills/`. Each skill has a `SKILL.md` with a desc
 Format: `feature/{issue-id}-{slug}`
 Example: `feature/42-add-user-auth`
 
-When `## Source Roots` lists multiple roots, each root is an independent git repository. The same branch name must be created in every repo that will have changes. Git operations (`branch`, `commit`, `push`) run once per repository — there is no shared git history.
+When `## Source Roots` lists multiple roots, each root is an independent git repository. The same branch name must be created in every repo that will have changes. Git operations (`branch`, `commit`, `push`) run once per repository, there is no shared git history.
 
 ---
 
@@ -309,7 +295,16 @@ When `## Source Roots` lists multiple roots, each root is an independent git rep
 [project-root]/
 ├── .agents/
 │   ├── agents/        # Agent definitions (universal, no project knowledge)
-│   └── skills/        # Skills (platform/tech specific knowledge)
+│   │   ├── devops-manager.md
+│   │   ├── basic-engineer.md
+│   │   └── custom-engineer-*.md   # optional, user-defined workers
+│   └── skills/      # Skills (platform/tech specific knowledge)
+│       ├── ob-global/              ← baseline skill, load first
+│       ├── ob-default/            ← fallback skill
+│       ├── ob-generic-guardrails/ ← foundation for user guardrails
+│       ├── ob-userstory-gh/
+│       ├── ob-userstory-az/
+│       └── browser-automation/
 ├── openspec/
 │   ├── specs/
 │   └── changes/
@@ -322,61 +317,16 @@ When `## Source Roots` lists multiple roots, each root is an independent git rep
 
 ---
 
-## RTK
-
-Use `rtk` wrapper for ALL CLI commands. Never run git, az, gh, or openspec commands directly.
-
-- `rtk git add` NOT `git add`
-- `rtk git commit` NOT `git commit`
-- `rtk git push` NOT `git push`
-- `rtk az boards work-item show` NOT `az boards work-item show`
-- `rtk az repos pr create` NOT `az repos pr create`
-- `rtk gh issue view` NOT `gh issue view`
-- `rtk gh pr create` NOT `gh pr create`
-- `rtk openspec new change` NOT `openspec new change`
-
----
-
-## Guardrails
-
-### Git Operations
-
-Agents CAN:
-- ✅ Commit to feature branches
-- ✅ Push to feature branches
-
-Agents CANNOT:
-- ❌ Commit or push to `main`, FORBIDDEN
-- ❌ Force push, FORBIDDEN
-- ❌ Merge PRs, human-only
-- ❌ Create or delete branches other than `feature/*`
-
-**Multi-repo**: When `## Source Roots` lists multiple roots, each is an independent git repository with its own history. All `rtk git` commands must be issued per repository. Never assume one `git` context covers all repos. Create the feature branch in each repo, commit per repo, push per repo, open one PR per repo.
-
-### Platform CLI
-
-ALL platform interactions via CLI only. Browser MCP and webfetch FORBIDDEN for any DevOps or GitHub operation, use `gh` or `az` CLI exclusively, never fall back to HTTP requests.
-
-| Operation | Azure DevOps | GitHub |
-|-----------|-------------|--------|
-| Read issue | `az boards work-item show --id <id>` | `gh issue view <number>` |
-| Read PR threads | `az devops invoke ...` | `gh pr view <number> --comments` |
-| Create PR | `az repos pr create ...` | `gh pr create ...` |
-
-Browser MCP tools permitted only for screenshots of **local running app** on `localhost` URLs.
-
-### Security
-
-Agents CANNOT:
-- ❌ Access `.env` or config files with secrets
-- ❌ Log or output credentials, API keys, or tokens
-- ❌ Commit secrets to git
-
-### Scope
-
-- Max 10 files per change
-- No architecture changes without human approval
-- No pipeline modifications without human approval
+## 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/content/skills-lock.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "skills": {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-onboard",
-  "version": "0.3.3",
+  "version": "0.4.2",
   "description": "Prepare any brownfield codebase for AI agent workflows using OpenCode, OpenSpec, and ensemble orchestration.",
   "keywords": [
     "opencode",
@@ -33,12 +33,17 @@
     "ora": "^8.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
     "vitest": "^4.1.5"
   },
   "vitest": {
     "environment": "node"
   },
   "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/src/commands/join.js

@@ -0,0 +1,43 @@
+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 { 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('  This will NOT modify any project files.'))
+  console.log()
+
+  // Step 1: Platform CLI check
+  header('Step 1, Platform CLI check')
+  const saved = await readOnboardConfig()
+  const savedPlatform = saved?.wizard?.platform
+  if (savedPlatform) {
+    info(`Detected project platform: ${savedPlatform === 'github' ? 'GitHub' : 'Azure DevOps'}`)
+    await checkPlatform(savedPlatform)
+  } else {
+    const platform = await choosePlatform()
+    void platform // result not persisted in join mode
+  }
+
+  // Step 2: rtk check
+  header('Step 2, Checking rtk')
+  await checkRtk({ skipHeader: true })
+
+  // Step 3: Browser extension
+  await installBrowser()
+
+  console.log()
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log(chalk.bold.green('  Join setup complete!'))
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log()
+  console.log('  Your local environment is ready.')
+  console.log('  Open the project in OpenCode and start coding!')
+  console.log()
+}

package/src/commands/shared.js

@@ -0,0 +1,12 @@
+import fse from 'fs-extra'
+import path from 'node:path'
+
+export async function readOnboardConfig() {
+  const cfgPath = path.join(process.cwd(), '.opencode', 'opencode-onboard.json')
+  if (!await fse.pathExists(cfgPath)) return null
+  try {
+    return await fse.readJson(cfgPath)
+  } catch {
+    return null
+  }
+}

package/src/commands/shared.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { readOnboardConfig } from './shared.js'
+
+describe('readOnboardConfig()', () => {
+  let tmpDir, originalCwd
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'shared-test-'))
+    originalCwd = process.cwd()
+    process.chdir(tmpDir)
+  })
+
+  afterEach(() => {
+    process.chdir(originalCwd)
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('returns null when config file does not exist', async () => {
+    const result = await readOnboardConfig()
+
+    expect(result).toBeNull()
+  })
+
+  it('returns parsed config when file exists', async () => {
+    const configDir = path.join(tmpDir, '.opencode')
+    fs.mkdirSync(configDir)
+    fs.writeFileSync(
+      path.join(configDir, 'opencode-onboard.json'),
+      JSON.stringify({ schema: 1, wizard: { platform: 'github' } }),
+      'utf-8'
+    )
+
+    const result = await readOnboardConfig()
+
+    expect(result).not.toBeNull()
+    expect(result.schema).toBe(1)
+    expect(result.wizard.platform).toBe('github')
+  })
+
+  it('returns null when file contains invalid JSON', async () => {
+    const configDir = path.join(tmpDir, '.opencode')
+    fs.mkdirSync(configDir)
+    fs.writeFileSync(
+      path.join(configDir, 'opencode-onboard.json'),
+      'not valid json',
+      'utf-8'
+    )
+
+    const result = await readOnboardConfig()
+
+    expect(result).toBeNull()
+  })
+})

package/src/commands/single.js

@@ -0,0 +1,64 @@
+import { cleanAiFiles } from '../steps/clean/index.js'
+import { copyContentStep } from '../steps/copy/index.js'
+import { chooseModels } from '../steps/models/index.js'
+import { initOpenspec } from '../steps/openspec/index.js'
+import { tokenOptimizationStep } from '../steps/optimization/index.js'
+import { choosePlatform } from '../steps/platform/index.js'
+import { installBrowser } from '../steps/browser/index.js'
+import { writeOnboardConfig } from '../steps/metadata/index.js'
+import { readOnboardConfig } from './shared.js'
+
+export async function runSingleCommand(command) {
+  const saved = await readOnboardConfig()
+  const savedWizard = saved?.wizard ?? {}
+  const ctx = {
+    hasDesign: !!savedWizard?.preserved?.design,
+    hasArchitecture: !!savedWizard?.preserved?.architecture,
+    hasOpenspec: !!savedWizard?.preserved?.openspec,
+    sourceMode: savedWizard?.sourceMode ?? 'current',
+    sourceRoots: Array.isArray(savedWizard?.sourceRoots) ? savedWizard.sourceRoots : [],
+  }
+  const platform = savedWizard?.platform
+  const resolvedPlatform = platform === 'azure' || platform === 'github' ? platform : 'github'
+
+  const handlers = {
+    clean: async () => {
+      await cleanAiFiles()
+    },
+    platform: async () => {
+      await choosePlatform()
+    },
+    copy: async () => {
+      await copyContentStep(resolvedPlatform, ctx)
+    },
+    openspec: async () => {
+      await initOpenspec()
+    },
+    models: async () => {
+      await chooseModels()
+    },
+    optimization: async () => {
+      await tokenOptimizationStep({ ctx })
+    },
+    browser: async () => {
+      await installBrowser()
+    },
+    metadata: async () => {
+      await writeOnboardConfig({
+        ...ctx,
+        platform: resolvedPlatform,
+        additionalSkillsProvider: 'npx-skills',
+        planModel: savedWizard?.models?.plan ?? null,
+        buildModel: savedWizard?.models?.build ?? null,
+        fastModel: savedWizard?.models?.fast ?? null,
+        optionalTools: savedWizard?.optionalTools ?? null,
+        cavemanGuidance: savedWizard?.cavemanGuidance ?? null,
+      })
+    },
+  }
+
+  const handler = handlers[command]
+  if (!handler) return false
+  await handler()
+  return true
+}

package/src/commands/wizard.js

@@ -0,0 +1,99 @@
+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()
+}