opencode-onboard 0.2.14 → 0.3.3

package/content/AGENTS.md

@@ -299,6 +299,8 @@ 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.
+
 ---
 
 ## Project Structure
@@ -349,6 +351,8 @@ Agents CANNOT:
 - ❌ 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.

package/package.json

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

package/src/index.js

@@ -1,26 +1,25 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import chalk from 'chalk'
+import fse from 'fs-extra'
 import { createRequire } from 'node:module'
 import path from 'node:path'
-import fse from 'fs-extra'
 import { checkEnv } from './steps/check-env.js'
 import { checkPlatform } from './steps/check-platform.js'
 import { checkRtk } from './steps/check-rtk.js'
-import { chooseModels } from './steps/choose-models.js'
+import { chooseModels } from './steps/choose-models.js'
 import { choosePlatform } from './steps/choose-platform.js'
-import { chooseSourceScope } from './steps/choose-source-scope.js'
 import { chooseSkillsProvider } from './steps/choose-skills-provider.js'
-import { cleanAiFiles } from './steps/clean-ai-files.js'
-import { copyContentStep } from './steps/copy-content.js'
-import { initOpenspec } from './steps/init-openspec.js'
-import { patchAgentsMd } from './steps/patch-agents-md.js'
-import { installQuota } from './steps/install-quota.js'
-import { installCaveman } from './steps/install-caveman.js'
+import { chooseSourceScope } from './steps/choose-source-scope.js'
+import { cleanAiFiles } from './steps/clean-ai-files.js'
+import { copyContentStep } from './steps/copy-content.js'
 import { enableCavemanGuidance } from './steps/enable-caveman-guidance.js'
+import { initOpenspec } from './steps/init-openspec.js'
 import { installBrowser } from './steps/install-browser.js'
-import { writeOnboardConfig } from './steps/write-onboard-config.js'
-import { loading } from './utils/exec.js'
+import { installCaveman } from './steps/install-caveman.js'
+import { installQuota } from './steps/install-quota.js'
+import { patchAgentsMd } from './steps/patch-agents-md.js'
 import { tokenOptimizationStep } from './steps/token-optimization.js'
+import { writeOnboardConfig } from './steps/write-onboard-config.js'
 
 function printHelp(version) {
   console.log(`opencode-onboard v${version}`)
@@ -70,78 +69,60 @@ async function runSingleCommand(command) {
   const platform = savedWizard?.platform
   const resolvedPlatform = platform === 'azure' || platform === 'github' ? platform : 'github'
 
-  if (command === 'clean') {
-    await cleanAiFiles()
-    return true
-  }
-
-  if (command === 'platform') {
-    await choosePlatform()
-    return true
-  }
-
-  if (command === 'copy') {
-    await copyContentStep(resolvedPlatform, ctx)
-    await patchAgentsMd(ctx)
-    return true
-  }
-
-  if (command === 'openspec') {
-    await initOpenspec()
-    return true
-  }
-
-  if (command === 'skills') {
-    await chooseSkillsProvider()
-    return true
-  }
-
-  if (command === 'models') {
-    await chooseModels()
-    return true
-  }
-
-  if (command === 'optimization') {
-    await tokenOptimizationStep({ skillsProvider: savedWizard?.additionalSkillsProvider })
-    return true
-  }
-
-  if (command === 'quota') {
-    await installQuota()
-    return true
-  }
-
-  if (command === 'rtk') {
-    await checkRtk()
-    return true
-  }
-
-  if (command === 'caveman') {
-    const caveman = await installCaveman({ skillsProvider: savedWizard?.additionalSkillsProvider })
-    await enableCavemanGuidance(caveman)
-    return true
-  }
-
-  if (command === 'browser') {
-    await installBrowser()
-    return true
-  }
-
-  if (command === 'metadata') {
-    await writeOnboardConfig({
-      ...ctx,
-      platform: resolvedPlatform,
-      additionalSkillsProvider: savedWizard?.additionalSkillsProvider ?? 'none',
-      planModel: savedWizard?.models?.plan ?? null,
-      buildModel: savedWizard?.models?.build ?? null,
-      fastModel: savedWizard?.models?.fast ?? null,
-      optionalTools: savedWizard?.optionalTools ?? null,
-      cavemanGuidance: savedWizard?.cavemanGuidance ?? null,
-    })
-    return true
-  }
-
-  return false
+  const handlers = {
+    clean: async () => {
+      await cleanAiFiles()
+    },
+    platform: async () => {
+      await choosePlatform()
+    },
+    copy: async () => {
+      await copyContentStep(resolvedPlatform, ctx)
+      await patchAgentsMd(ctx)
+    },
+    openspec: async () => {
+      await initOpenspec()
+    },
+    skills: async () => {
+      await chooseSkillsProvider()
+    },
+    models: async () => {
+      await chooseModels()
+    },
+    optimization: async () => {
+      await tokenOptimizationStep({ skillsProvider: savedWizard?.additionalSkillsProvider })
+    },
+    quota: async () => {
+      await installQuota()
+    },
+    rtk: async () => {
+      await checkRtk()
+    },
+    caveman: async () => {
+      const caveman = await installCaveman({ skillsProvider: savedWizard?.additionalSkillsProvider })
+      await enableCavemanGuidance(caveman)
+    },
+    browser: async () => {
+      await installBrowser()
+    },
+    metadata: async () => {
+      await writeOnboardConfig({
+        ...ctx,
+        platform: resolvedPlatform,
+        additionalSkillsProvider: savedWizard?.additionalSkillsProvider ?? 'none',
+        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
 }
 
 if (process.stdout.isTTY) console.clear()
@@ -168,94 +149,69 @@ if (args.length > 0) {
 
 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()
-    })
-  })
-}
-
-try {
-  // 1. Check Node + pnpm
+  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()
+    })
+  })
+}
+
+try {
   await checkEnv()
-  loading('preparing next step...')
 
-  // 2. Choose source code scope for init analysis
   const scope = await chooseSourceScope()
-  loading('preparing next step...')
 
-  // 3. Clean existing AI config files, detect preserved state
   const preserve = await cleanAiFiles()
   const ctx = { ...preserve, ...scope }
-  loading('preparing next step...')
 
-  // 4. Choose platform
   const platform = await choosePlatform()
-  loading('preparing next step...')
-
-  // 5. Check platform CLI (az or gh)
+  
   await checkPlatform(platform)
-  loading('preparing next step...')
 
-  // 6. Copy content
   await copyContentStep(platform, ctx)
-  loading('preparing next step...')
 
-  // 6b. Patch AGENTS.md to skip steps for already-existing files
   await patchAgentsMd(ctx)
-  loading('preparing next step...')
 
-  // 7. Init OpenSpec
   await initOpenspec()
-  loading('preparing next step...')
 
-  // 8. Install skills
   const skillsSelection = await chooseSkillsProvider()
-  loading('preparing next step...')
-
-  // 9. Choose models
+  
   const selectedModels = await chooseModels()
-  loading('preparing next step...')
 
-  // 10. Token optimization tools
   const tokenOpt = await tokenOptimizationStep({ skillsProvider: skillsSelection.additionalSkillsProvider })
   const { rtk, quota, caveman, cavemanGuidance } = tokenOpt
-  loading('preparing next step...')
 
-  // 11. Install opencode-browser
   await installBrowser()
-  loading('preparing next step...')
 
-  // 12. Write onboarding metadata
   await writeOnboardConfig({
     ...ctx,
     platform,
@@ -264,21 +220,20 @@ try {
     optionalTools: { rtk, quota, caveman },
     cavemanGuidance,
   })
-
-  // Done
-  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()
+
+  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.')
@@ -287,12 +242,12 @@ try {
   }
   console.log(`  Source scope: ${ctx.sourceMode === 'parent-selected' ? ctx.sourceRoots.map(p => `../${p.split(/[/\\]/).pop()}`).join(', ') : 'current folder'}`)
   console.log()
-} catch (err) {
-  if (err.name === 'ExitPromptError') {
-    console.log()
-    console.log(chalk.yellow('Cancelled.'))
-  } else {
-    console.error(chalk.red('\nUnexpected error:'), err.message)
-    process.exit(1)
-  }
-}
+} catch (err) {
+  if (err.name === 'ExitPromptError') {
+    console.log()
+    console.log(chalk.yellow('Cancelled.'))
+  } else {
+    console.error(chalk.red('\nUnexpected error:'), err.message)
+    process.exit(1)
+  }
+}

package/src/steps/choose-models.js

@@ -131,9 +131,9 @@ export async function chooseModels() {
   const opencodeJsonPath = path.join(process.cwd(), '.opencode', 'opencode.json')
   if (await fse.pathExists(opencodeJsonPath)) {
     const config = await fse.readJson(opencodeJsonPath)
-    config.model = planModel
+    config.model = buildModel
     await fse.writeJson(opencodeJsonPath, config, { spaces: 2 })
-    success(`plan model -> ${planModel} (written to .opencode/opencode.json)`)
+    success(`default model -> ${buildModel} (written to .opencode/opencode.json)`)
   }
 
   // Write build and fast models to ensemble.json
@@ -143,10 +143,12 @@ export async function chooseModels() {
     delete ensemble.defaultModel
     ensemble.modelsByAgent = {
       ...ensemble.modelsByAgent,
+      plan: planModel,
       build: buildModel,
       explore: fastModel,
     }
     await fse.writeJson(ensembleJsonPath, ensemble, { spaces: 2 })
+    success(`plan model -> ${planModel} (written to .opencode/ensemble.json)`)
     success(`build model -> ${buildModel} (written to .opencode/ensemble.json)`)
     success(`fast model -> ${fastModel} (written to .opencode/ensemble.json)`)
   }

package/src/steps/copy-content.js

@@ -1,6 +1,6 @@
+import fse from 'fs-extra'
 import path from 'path'
 import { fileURLToPath } from 'url'
-import fse from 'fs-extra'
 import { copyContent } from '../utils/copy.js'
 import { error, header, success } from '../utils/exec.js'
 
@@ -12,7 +12,7 @@ function formatRootsForText(roots = [], cwd = process.cwd()) {
   return roots.map(r => {
     const rel = path.relative(cwd, r)
     if (!rel || rel === '') return 'current folder'
-    if (!rel.startsWith('..')) return `./${rel.replace(/\\/g, '/')}`
+    if (!rel.startsWith('..')) return rel
     return rel.replace(/\\/g, '/')
   })
 }

package/src/steps/enable-caveman-guidance.js

@@ -6,30 +6,15 @@ const MARKER_START = '<!-- CAVEMAN-GUIDANCE-START -->'
 const MARKER_END = '<!-- CAVEMAN-GUIDANCE-END -->'
 
 const AGENTS_BLOCK = `${MARKER_START}
-## Caveman Mode (Optional)
+## Caveman Mode
 
-If caveman is installed, prefer concise responses by default to reduce token usage while keeping full technical accuracy.
-
-Treat any of these as a direct trigger to enable concise style:
-- "talk like caveman"
-- "caveman mode"
-- "less tokens please"
-
-When enabled:
-- Keep explanations short and direct
-- Prioritize exact commands, paths, and outcomes
-- Avoid filler, greetings, and repeated context
-
-The user can disable it with phrases like: "normal mode" or "stop caveman".
+caveman mode. Active now. Every response. No revert.
 ${MARKER_END}`
 
 const OPSX_BLOCK = `${MARKER_START}
-## Caveman Output Style
+## Caveman Mode
 
-If the user requests "talk like caveman", "caveman mode", or "less tokens please", keep all status updates concise:
-- Report only key actions, blockers, and next commands
-- Keep completion updates brief and factual
-- Preserve technical precision; compress wording only
+caveman mode. Active now. Every response. No revert.
 ${MARKER_END}`
 
 async function appendBlockIfMissing(filePath, block) {

package/src/steps/init-openspec.js

@@ -38,19 +38,27 @@ 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.** Spawn all needed specialists, then kick them off in parallel.
+   **Step 6d.** Discover relevant skills, then spawn specialists.
+
+      Before spawning, scan \`.agents/skills/\` and read each \`SKILL.md\` description line.
+      Match skills to agents by domain:
+      - front-engineer: UI, components, framework skills (e.g. next-best-practices, browser-automation)
+      - back-engineer: API, data, service skills
+      - infra-engineer: cloud, pipeline, deployment skills
+      - quality-engineer: testing, coverage skills
 
       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. 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.
       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
+      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.
+      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 500 tokens. Do not describe team internals or how ensemble works.
+      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.
 
       First spawn all agents (wait for each team_spawn to confirm before the next):
@@ -63,12 +71,13 @@ const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       (wait for result)
       \`\`\`
 
-      Then immediately send each spawned agent a start message to kick them off:
+      Then immediately send each spawned agent a start message that repeats their task IDs:
       \`\`\`
-      team_message to:"back" text:"Start now. Claim your first task with team_claim and begin implementing."
-      team_message to:"front" text:"Start now. Claim your first task with team_claim and begin implementing."
-      team_message to:"infra" text:"Start now. Claim your first task with team_claim and begin implementing."
+      team_message to:"back" text:"Start now. Load skills first. Your tasks: [task-<id1>] <task1 text>, [task-<id2>] <task2 text>. Call team_claim task_id:<id> for each before starting it."
+      team_message to:"front" text:"Start now. Load skills first. Your tasks: [task-<id3>] <task3 text>. Call team_claim task_id:<id> before starting it."
+      team_message to:"infra" text:"Start now. Load skills first. Your tasks: [task-<id4>] <task4 text>. Call team_claim task_id:<id> before starting it."
       \`\`\`
+      Replace placeholders with REAL task IDs and content. Never send a generic "claim your first task" message without the actual IDs.
 
    **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.
@@ -89,7 +98,7 @@ const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 
    Spawn quality engineer with worktree:false (read-only, no file edits):
    \`\`\`
-   team_spawn name:"quality" agent:"quality-engineer" worktree:false prompt:"<task list, context summary, run tests + build + lint + verify acceptance criteria, send results to lead when done>"
+   team_spawn name:"quality" agent:"quality-engineer" worktree:false prompt:"<verification scope, context summary, run tests + build + lint + verify acceptance criteria, no task claiming required in this phase, send results to lead when done>"
    \`\`\`
    Wait for message -> team_results -> fix blockers -> team_shutdown (no team_merge needed, worktree:false)
 
@@ -116,7 +125,9 @@ 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
-- ALWAYS pass the task IDs returned by team_tasks_add to each agent's spawn prompt
+- ALWAYS pass the LITERAL task IDs returned by team_tasks_add into each agent's spawn prompt — copy the exact IDs, never paraphrase
+- 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

package/src/steps/install-quota.js

@@ -1,9 +1,9 @@
 import { confirm } from '@inquirer/prompts'
 import fse from 'fs-extra'
 import path from 'node:path'
-import { header, success, warn, error, loading, info } from '../utils/exec.js'
+import { error, header, info, loading, success, warn } from '../utils/exec.js'
 
-const PLUGIN = '@slkiser/opencode-quota'
+const PLUGIN = '@slkiser/opencode-quota@latest'
 
 function ensurePlugin(config) {
   if (!Array.isArray(config.plugin)) config.plugin = []

package/src/steps/patch-agents-md.js

@@ -2,6 +2,70 @@ import fse from 'fs-extra'
 import path from 'path'
 import { info, success } from '../utils/exec.js'
 
+// Agent files that receive a Source Roots injection when parent folders are selected
+const AGENT_FILES = [
+  '.agents/agents/front-engineer.md',
+  '.agents/agents/back-engineer.md',
+  '.agents/agents/infra-engineer.md',
+  '.agents/agents/quality-engineer.md',
+  '.agents/agents/security-auditor.md',
+  '.agents/agents/devops-manager.md',
+]
+
+/**
+ * Build a markdown Source Roots block from an array of absolute paths.
+ */
+function buildSourceRootsBlock(sourceRoots, cwd) {
+  const bullets = sourceRoots.map(r => {
+    const rel = path.relative(cwd, r).replace(/\\/g, '/')
+    return `- \`${rel}\``
+  }).join('\n')
+  const multiRepoNote = sourceRoots.length > 1
+    ? `\nEach root is an independent git repository. When branching, committing, or pushing, ALL repositories must be operated separately — create the feature branch in each repo, commit changes per repo, and push each repo independently. There is no single repo; \`rtk git\` commands must be run once per repository root.\n`
+    : ''
+  return `## Source Roots\n\nThe user selected these source repositories during onboarding.\nSearch and read code ONLY from these roots — do not assume code lives in the current folder.\n${multiRepoNote}\n${bullets}\n`
+}
+
+/**
+ * Inject source roots into AGENTS.md (replaces the generic Source Scope section)
+ * and into every agent file (inserts after the ## Domain section).
+ */
+async function patchSourceRootsIntoAgents(cwd, sourceRoots) {
+  const block = buildSourceRootsBlock(sourceRoots, cwd)
+
+  // --- AGENTS.md: replace the ## Source Scope section ---
+  const agentsMdPath = path.join(cwd, 'AGENTS.md')
+  if (await fse.pathExists(agentsMdPath)) {
+    let content = await fse.readFile(agentsMdPath, 'utf-8')
+    // Replace the generic section between ## Source Scope and the next ## heading
+    content = content.replace(
+      /## Source Scope\n[\s\S]*?(?=\n## )/,
+      `## Source Roots\n\n${block.replace('## Source Roots\n\n', '')}\n`
+    )
+    await fse.writeFile(agentsMdPath, content, 'utf-8')
+    info('AGENTS.md: Source Roots section injected')
+  }
+
+  // --- Agent files: insert ## Source Roots after ## Domain section ---
+  for (const relFile of AGENT_FILES) {
+    const agentPath = path.join(cwd, relFile)
+    if (!await fse.pathExists(agentPath)) continue
+
+    let content = await fse.readFile(agentPath, 'utf-8')
+
+    // Skip if already patched
+    if (content.includes('## Source Roots')) continue
+
+    // Insert after the ## Domain section (after its paragraph block, before next ##)
+    content = content.replace(
+      /(## Domain\n[\s\S]*?)(\n## )/,
+      `$1\n${block}\n## `
+    )
+    await fse.writeFile(agentPath, content, 'utf-8')
+    info(`${path.basename(agentPath)}: Source Roots section injected`)
+  }
+}
+
 // Each block is identified by its heading line. We remove from the heading up to (and including) the next `---` separator.
 const STEP1_HEADING = '### Step 1, Archive project history into OpenSpec'
 const STEP2_HEADING = '### Step 2, Generate DESIGN.md'
@@ -75,11 +139,15 @@ export async function patchAgentsMd(ctx) {
     patches.push('Step 3 (ARCHITECTURE.md) removed, ARCHITECTURE.md already exists')
   }
 
-  if (patches.length === 0) return
-
-  content = renumberSteps(content)
-  await fse.writeFile(agentsMdPath, content, 'utf-8')
+  if (patches.length > 0) {
+    content = renumberSteps(content)
+    await fse.writeFile(agentsMdPath, content, 'utf-8')
+    for (const msg of patches) info(msg)
+    success('AGENTS.md patched for existing project state')
+  }
 
-  for (const msg of patches) info(msg)
-  success('AGENTS.md patched for existing project state')
+  if (ctx.sourceMode === 'parent-selected' && Array.isArray(ctx.sourceRoots) && ctx.sourceRoots.length > 0) {
+    await patchSourceRootsIntoAgents(process.cwd(), ctx.sourceRoots)
+    success('Source roots injected into AGENTS.md and agent files')
+  }
 }