opencode-onboard 0.3.1 → 0.4.1

package/src/steps/models/index.js

@@ -0,0 +1,52 @@
+import path from 'path'
+import { header, info, success, warn } from '../../utils/exec.js'
+import { fetchModels } from '../../utils/models-cache.js'
+import { buildDisplayModels, modelsPreset, pickModel } from './format.js'
+import { writeModelsToConfigs } from './write.js'
+
+export async function chooseModels() {
+  header('Step 7, Choose models');
+
+  info('Fetching available models from models.dev...');
+  const { models: rawModels, source } = await fetchModels();
+
+  if (!rawModels) {
+    warn('Could not fetch models (offline and no cache). Skipping model selection.');
+    warn('Set models later in .agents/agents/<name>.md and .opencode/opencode.json');
+    return;
+  }
+
+  if (source === 'stale-cache') {
+    warn('Network unavailable, using cached model list (may be outdated).');
+  } else if (source === 'cache') {
+    info('Using cached model list (refreshes weekly).');
+  }
+
+  const models = buildDisplayModels(rawModels);
+  success(`${models.length} models available`);
+  console.log();
+  info('Cost indicators: [$] cheap  [$$] mid  [$$$] expensive');
+  info('Type to search. Change selections later in .agents/agents/ and .opencode/opencode.json');
+  console.log();
+
+  for (const line of modelsPreset.roles.plan.info) info(line);
+  const planModel = await pickModel(modelsPreset.roles.plan.prompt, models);
+  console.log();
+
+  for (const line of modelsPreset.roles.build.info) info(line);
+  const buildModel = await pickModel(modelsPreset.roles.build.prompt, models);
+  console.log();
+
+  for (const line of modelsPreset.roles.fast.info) info(line);
+  const fastModel = await pickModel(modelsPreset.roles.fast.prompt, models);
+  console.log();
+
+  const agentsDir = path.join(process.cwd(), '.agents', 'agents');
+  await writeModelsToConfigs({ planModel, buildModel, fastModel, agentsDir, preset: modelsPreset });
+
+  console.log();
+  warn('Make sure you have API access to the selected models.');
+  warn('Change them anytime in .agents/agents/<name>.md and .opencode/opencode.json');
+
+  return { planModel, buildModel, fastModel };
+}

package/src/steps/models/write.js

@@ -0,0 +1,54 @@
+import fse from 'fs-extra'
+import path from 'path'
+import { success } from '../../utils/exec.js'
+
+export async function writeModelToAgent(agentFile, modelId) {
+  const content = await fse.readFile(agentFile, 'utf-8');
+  const updated = content.replace(
+    /^(---\n[\s\S]*?)\n---/m,
+    `$1\nmodel: ${modelId}\n---`
+  );
+  await fse.writeFile(agentFile, updated, 'utf-8');
+}
+
+export async function writeModelsToConfigs({ planModel, buildModel, fastModel, agentsDir, preset }) {
+  for (const name of preset.roles.build.agents) {
+    const file = path.join(agentsDir, `${name}.md`);
+    if (await fse.pathExists(file)) {
+      await writeModelToAgent(file, buildModel);
+      success(`${name} → ${buildModel}`);
+    }
+  }
+
+  for (const name of preset.roles.fast.agents) {
+    const file = path.join(agentsDir, `${name}.md`);
+    if (await fse.pathExists(file)) {
+      await writeModelToAgent(file, fastModel);
+      success(`${name} → ${fastModel}`);
+    }
+  }
+
+  const opencodeJsonPath = path.join(process.cwd(), '.opencode', 'opencode.json');
+  if (await fse.pathExists(opencodeJsonPath)) {
+    const config = await fse.readJson(opencodeJsonPath);
+    config.model = buildModel;
+    await fse.writeJson(opencodeJsonPath, config, { spaces: 2 });
+    success(`default model -> ${buildModel} (written to .opencode/opencode.json)`);
+  }
+
+  const ensembleJsonPath = path.join(process.cwd(), '.opencode', 'ensemble.json');
+  if (await fse.pathExists(ensembleJsonPath)) {
+    const ensemble = await fse.readJson(ensembleJsonPath);
+    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/models/write.test.js

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

package/src/steps/{init-openspec.js → openspec/ensemble.js}

@@ -1,14 +1,12 @@
-import { execa } from 'execa'
-import path from 'node:path'
 import fse from 'fs-extra'
-import { error, header, success, warn } from '../utils/exec.js'
+import path from 'node:path'
 
-const APPLY_TARGETS = [
+export const APPLY_TARGETS = [
   path.join('.opencode', 'commands', 'opsx-apply.md'),
   path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
 ]
 
-const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
+export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 
    NEVER implement tasks directly. Always delegate to specialists via ensemble.
    Do NOT touch any source files before the team is running, not even a single edit.
@@ -51,11 +49,11 @@ 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, 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 600 tokens. Do not describe team internals or how ensemble works.
@@ -71,12 +69,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. Read all skills listed in your prompt first, confirm loaded skills, then claim your first task with team_claim."
-      team_message to:"front" text:"Start now. Read all skills listed in your prompt first, confirm loaded skills, then claim your first task with team_claim."
-      team_message to:"infra" text:"Start now. Read all skills listed in your prompt first, confirm loaded skills, then claim your first task with team_claim."
+      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.
@@ -104,7 +103,7 @@ const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 8. **Mark tasks complete in openspec**
 
    Update tasks.md: \`- [ ]\` -> \`- [x]\` for each completed task.
-   Run \`rtk openspec status --change "<name>" --json\` to confirm.
+   Run \`openspec status --change "<name>" --json\` to confirm.
 
 9. **Show status, then cleanup**
 
@@ -124,7 +123,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
@@ -133,64 +134,29 @@ const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 - Mark tasks complete in openspec AFTER specialists finish, not before
 - Pause on errors, blockers, or unclear requirements. Do not guess
 - Use contextFiles from CLI output, do not assume specific file paths
-- Use \`rtk\` wrapper for ALL CLI commands. Never run openspec, git, gh, or az directly
+- Follow CLI rules from \`@ob-global\` when present
 - If model quota/rate-limit is exhausted, tell lead immediately via team_message and stop claiming new tasks until respawned
 `
 
 const STEP_6_START = /^6\.\s+\*\*Implement\b/im
 const FLUID_SECTION = /^\*\*Fluid Workflow Integration\*\*/im
 
-async function patchApplyFile(filePath) {
-  if (!await fse.pathExists(filePath)) return { ok: false, reason: 'missing-file' }
+export async function patchApplyFile(filePath) {
+  if (!await fse.pathExists(filePath)) return { ok: false, reason: 'missing-file' };
 
-  const original = await fse.readFile(filePath, 'utf-8')
-  const startMatch = original.match(STEP_6_START)
-  if (!startMatch || startMatch.index === undefined) return { ok: false, reason: 'missing-step-6' }
+  const original = await fse.readFile(filePath, 'utf-8');
+  const startMatch = original.match(STEP_6_START);
+  if (!startMatch || startMatch.index === undefined) return { ok: false, reason: 'missing-step-6' };
 
-  const before = original.slice(0, startMatch.index).replace(/\s*$/, '')
-  const fromStep6 = original.slice(startMatch.index)
-  const fluidMatch = fromStep6.match(FLUID_SECTION)
+  const before = original.slice(0, startMatch.index).replace(/\s*$/, '');
+  const fromStep6 = original.slice(startMatch.index);
+  const fluidMatch = fromStep6.match(FLUID_SECTION);
 
   const after = fluidMatch && fluidMatch.index !== undefined
     ? `\n\n${fromStep6.slice(fluidMatch.index).replace(/^\s*/, '')}`
-    : ''
-
-  const patched = `${before}\n\n${ENSEMBLE_SECTION}${after}`
-  await fse.writeFile(filePath, patched, 'utf-8')
-  return { ok: true }
-}
+    : '';
 
-export async function initOpenspec() {
-  header('Step 7, Initializing OpenSpec')
-
-  try {
-    const result = await execa('npx', ['@fission-ai/openspec', 'init', '--tools', 'opencode', '--force'], {
-      cwd: process.cwd(),
-      stdio: 'pipe',
-      reject: false,
-    })
-
-    if (result.exitCode === 0) {
-      success('OpenSpec initialized')
-    } else {
-      warn('OpenSpec init exited with non-zero code, check output above')
-    }
-  } catch (err) {
-    error(`Failed to run openspec init: ${err.message}`)
-  }
-
-  // Keep openspec defaults for selection/status/context steps, replace only implementation + guardrails.
-  for (const rel of APPLY_TARGETS) {
-    const abs = path.join(process.cwd(), rel)
-    try {
-      const res = await patchApplyFile(abs)
-      if (res.ok) {
-        success(`Patched ensemble implementation section in ${rel}`)
-      } else {
-        warn(`Could not patch ${rel} (${res.reason})`)
-      }
-    } catch (err) {
-      warn(`Could not patch ${rel}: ${err.message}`)
-    }
-  }
+  const patched = `${before}\n\n${ENSEMBLE_SECTION}${after}`;
+  await fse.writeFile(filePath, patched, 'utf-8');
+  return { ok: true };
 }

package/src/steps/openspec/ensemble.test.js

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { patchApplyFile, APPLY_TARGETS } from './ensemble.js'
+
+describe('patchApplyFile()', () => {
+  let tmpDir
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-test-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('returns ok:false when file does not exist', async () => {
+    const result = await patchApplyFile(path.join(tmpDir, 'missing.md'))
+
+    expect(result).toEqual({ ok: false, reason: 'missing-file' })
+  })
+
+  it('returns ok:false when Step 6 is not found', async () => {
+    const filePath = path.join(tmpDir, 'opsx-apply.md')
+    fs.writeFileSync(filePath, 'Some other content without Step 6', 'utf-8')
+
+    const result = await patchApplyFile(filePath)
+
+    expect(result).toEqual({ ok: false, reason: 'missing-step-6' })
+  })
+
+  it('patches file with ENSEMBLE_SECTION when Step 6 found', async () => {
+    const filePath = path.join(tmpDir, 'opsx-apply.md')
+    const original = `Some header
+
+6. **Implement**
+   Old implementation here.
+
+**Fluid Workflow Integration**
+   Fluid section content.
+`
+    fs.writeFileSync(filePath, original, 'utf-8')
+
+    const result = await patchApplyFile(filePath)
+
+    expect(result.ok).toBe(true)
+    const patched = fs.readFileSync(filePath, 'utf-8')
+    expect(patched).toContain('**Implement via ensemble team**')
+    expect(patched).toContain('6. **Implement via ensemble team**')
+    expect(patched).toContain('**Fluid Workflow Integration**')
+  })
+
+  it('removes original Step 6 content before patching', async () => {
+    const filePath = path.join(tmpDir, 'SKILL.md')
+    const original = `Steps:
+
+6. **Implement**
+   Do things directly.
+
+7. **Quality check**
+`
+    fs.writeFileSync(filePath, original, 'utf-8')
+
+    await patchApplyFile(filePath)
+
+    const patched = fs.readFileSync(filePath, 'utf-8')
+    expect(patched).not.toContain('Do things directly.')
+    expect(patched).toContain('NEVER implement tasks directly')
+  })
+})
+
+describe('APPLY_TARGETS', () => {
+  it('contains expected OpenSpec apply file paths', () => {
+    expect(APPLY_TARGETS).toHaveLength(2)
+    expect(APPLY_TARGETS).toContain(path.join('.opencode', 'commands', 'opsx-apply.md'))
+    expect(APPLY_TARGETS).toContain(path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'))
+  })
+})

package/src/steps/openspec/index.js

@@ -0,0 +1,32 @@
+import { execa } from 'execa'
+import path from 'node:path'
+import { error, header, success, warn } from '../../utils/exec.js'
+import { APPLY_TARGETS, patchApplyFile } from './ensemble.js'
+
+export async function initOpenspec() {
+  header('Step 6, Initializing OpenSpec');
+
+  try {
+    const result = await execa('npx', ['@fission-ai/openspec', 'init', '--tools', 'opencode', '--force'], {
+      cwd: process.cwd(),
+      stdio: 'pipe',
+      reject: false,
+    });
+
+    if (result.exitCode === 0) success('OpenSpec initialized');
+    else warn('OpenSpec init exited with non-zero code, check output above');
+  } catch (err) {
+    error(`Failed to run openspec init: ${err.message}`);
+  }
+
+  for (const rel of APPLY_TARGETS) {
+    const abs = path.join(process.cwd(), rel);
+    try {
+      const res = await patchApplyFile(abs);
+      if (res.ok) success(`Patched ensemble implementation section in ${rel}`);
+      else warn(`Could not patch ${rel} (${res.reason})`);
+    } catch (err) {
+      warn(`Could not patch ${rel}: ${err.message}`);
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+import { info } from '../../utils/exec.js'
+
+export async function enableCavemanGuidance(cavemanResult) {
+  if (!cavemanResult?.installed) {
+    info('Caveman guidance skipped (caveman not installed)')
+    return { enabled: false }
+  }
+
+  info('Caveman guidance is configured only via @ob-global skill')
+  return { enabled: true, patchedFiles: 0 }
+}

package/src/steps/{install-caveman.js → optimization/caveman.js}

@@ -1,13 +1,5 @@
 import { execa } from 'execa'
-import fse from 'fs-extra'
-import path from 'node:path'
-import { header, success, warn, error, loading, info } from '../utils/exec.js'
-
-const SKILLS_LOCK_CANDIDATES = [
-  'skills-lock.json',
-  '.skills-lock.json',
-  '.skills/skills-lock.json',
-]
+import { header, success, warn, error, loading, info } from '../../utils/exec.js'
 
 export async function installCaveman(options = {}) {
   if (!options.skipHeader) header('Installing caveman')
@@ -23,19 +15,13 @@ export async function installCaveman(options = {}) {
     })
 
     if (result.exitCode === 0) {
-      if (options.skillsProvider !== 'npx-skills') {
-        for (const rel of SKILLS_LOCK_CANDIDATES) {
-          const abs = path.join(process.cwd(), rel)
-          if (await fse.pathExists(abs)) await fse.remove(abs)
-        }
-      }
       success('caveman installed')
       return { optedIn: true, installed: true }
-    } else {
-      if (result.stderr?.trim()) warn(result.stderr.trim().split('\n').slice(-3).join('\n'))
-      warn('caveman install exited with non-zero code')
-      return { optedIn: true, installed: false }
     }
+
+    if (result.stderr?.trim()) warn(result.stderr.trim().split('\n').slice(-3).join('\n'))
+    warn('caveman install exited with non-zero code')
+    return { optedIn: true, installed: false }
   } catch (err) {
     error(`Failed to install caveman: ${err.message}`)
     return { optedIn: true, installed: false }

package/src/steps/optimization/global.js

@@ -0,0 +1,64 @@
+import fse from 'fs-extra'
+import path from 'node:path'
+import { info, success, warn } from '../../utils/exec.js'
+
+const SOURCE_START = '<!-- OB-SOURCE-ROOTS-START -->'
+const SOURCE_END = '<!-- OB-SOURCE-ROOTS-END -->'
+const RTK_START = '<!-- OB-RTK-START -->'
+const RTK_END = '<!-- OB-RTK-END -->'
+const CAVEMAN_START = '<!-- OB-CAVEMAN-START -->'
+const CAVEMAN_END = '<!-- OB-CAVEMAN-END -->'
+
+function relRoot(cwd, abs) {
+  const rel = path.relative(cwd, abs).replace(/\\/g, '/')
+  return rel || '.'
+}
+
+function buildSourceRootsSection(sourceRoots, cwd) {
+  const roots = Array.isArray(sourceRoots) && sourceRoots.length > 0 ? sourceRoots : [cwd]
+  const bullets = roots.map(r => `- \`${relRoot(cwd, r)}\``).join('\n')
+  const multiRepo = roots.length > 1
+    ? '\nEach root is an independent git repository. For branch/commit/push workflows, run git operations per repository. There is no single shared git history across all roots.\n'
+    : ''
+
+  return `Read and analyze code ONLY from these roots:\n\n${bullets}\n${multiRepo}`
+}
+
+function buildRtkSection(rtkEnabled) {
+  if (!rtkEnabled) return 'RTK was not selected during onboarding. Do not assume `rtk` exists.'
+  return `## RTK, MANDATORY\n\nUse \`rtk\` for ALL CLI commands. Never run commands directly.\n\n- \`rtk git\` NOT \`git\`\n- \`rtk gh\` NOT \`gh\`\n- \`rtk az\` NOT \`az\`\n- \`rtk openspec\` NOT \`openspec\`\n\nIf \`rtk\` is not available, report blocker and stop CLI execution.`
+}
+
+function buildCavemanSection(cavemanEnabled) {
+  if (!cavemanEnabled) return 'Caveman was not selected during onboarding. Use normal concise style.'
+  return `## Caveman\n\ncaveman mode. Active now. Every response. No revert unless user asks \"stop caveman\" or \"normal mode\".`
+}
+
+function replaceBetween(content, start, end, replacement) {
+  if (!content.includes(start) || !content.includes(end)) return content
+  const pattern = new RegExp(`${start}[\\s\\S]*?${end}`)
+  return content.replace(pattern, `${start}\n${replacement.trim()}\n${end}`)
+}
+
+export async function configureObGlobal(ctx = {}, tokenOpt = {}) {
+  const cwd = process.cwd()
+  const skillPath = path.join(cwd, '.agents', 'skills', 'ob-global', 'SKILL.md')
+
+  if (!await fse.pathExists(skillPath)) {
+    warn('ob-global skill not found, skipping dynamic configuration')
+    return { configured: false }
+  }
+
+  const sourceRootsSection = buildSourceRootsSection(ctx.sourceRoots, cwd)
+  const rtkSection = buildRtkSection(!!tokenOpt?.rtk?.optedIn)
+  const cavemanSection = buildCavemanSection(!!tokenOpt?.caveman?.optedIn)
+
+  let content = await fse.readFile(skillPath, 'utf-8')
+  content = replaceBetween(content, SOURCE_START, SOURCE_END, sourceRootsSection)
+  content = replaceBetween(content, RTK_START, RTK_END, rtkSection)
+  content = replaceBetween(content, CAVEMAN_START, CAVEMAN_END, cavemanSection)
+  await fse.writeFile(skillPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
+  info('Configured ob-global from onboarding selections')
+  success('ob-global skill updated')
+  return { configured: true, path: skillPath }
+}