opencode-onboard 0.4.4 → 0.4.7

package/src/steps/models/write.test.js

@@ -59,59 +59,60 @@ custom_field: custom_value
   })
 })
 
-describe('writeModelsToConfigs()', () => {
-  let tmpDir, agentsDir, opencodeJsonPath, originalCwd
-
-  beforeEach(() => {
-    vi.clearAllMocks()
-    originalCwd = process.cwd()
-    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')
-    path.join(tmpDir, '.opencode', 'ensemble.json')
-    fs.mkdirSync(path.dirname(opencodeJsonPath), { recursive: true })
-    process.chdir(tmpDir)
-  })
-
-  afterEach(() => {
-    process.chdir(originalCwd)
-    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 () => {
-    const agentFile = path.join(agentsDir, 'back-engineer.md')
-    fs.writeFileSync(agentFile, '---\nname: Back\n---', 'utf-8')
-
-    await writeModelsToConfigs({
-      planModel: 'plan-model',
-      buildModel: 'build-model',
-      fastModel: 'fast-model',
-      agentsDir,
-      preset: { roles: { build: { agents: ['back-engineer'] }, fast: { agents: [] } } },
-    })
-
-    expect(success).toHaveBeenCalled()
-  })
-})
+describe('writeModelsToConfigs()', () => {
+  let tmpDir, agentsDir, opencodeJsonPath
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    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')
+    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, 'basic-engineer.md'), '---\nname: Basic\n---', 'utf-8')
+    fs.writeFileSync(path.join(agentsDir, 'frontend-engineer.md'), '---\nname: Front\n---', 'utf-8')
+    fs.writeFileSync(path.join(agentsDir, 'devops-manager.md'), '---\nname: Devops\n---', 'utf-8')
+
+    await writeModelsToConfigs({
+      planModel: 'plan-model',
+      buildModel: 'build-model',
+      fastModel: 'fast-model',
+      agentsDir,
+      cwd: tmpDir,
+      preset: {
+        roles: {
+          build: { agents: ['basic-engineer'] },
+          fast: { agents: ['devops-manager'] },
+        },
+      },
+    })
+
+    expect(success).toHaveBeenCalledWith('basic-engineer → build-model')
+    expect(success).toHaveBeenCalledWith('frontend-engineer → build-model')
+    expect(success).toHaveBeenCalledWith('devops-manager → fast-model')
+  })
+
+  it('reports success when writing configs', async () => {
+    const agentFile = path.join(agentsDir, 'basic-engineer.md')
+    fs.writeFileSync(agentFile, '---\nname: Basic\n---', 'utf-8')
+
+    await writeModelsToConfigs({
+      planModel: 'plan-model',
+      buildModel: 'build-model',
+      fastModel: 'fast-model',
+      agentsDir,
+      cwd: tmpDir,
+      preset: { roles: { build: { agents: ['basic-engineer'] }, fast: { agents: [] } } },
+    })
+
+    expect(success).toHaveBeenCalled()
+  })
+})

package/src/steps/openspec/ensemble.js

@@ -21,22 +21,27 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       \`\`\`
       Announce: "Team running. Monitor at http://localhost:4747/"
 
-   **Step 6c.** Add ALL tasks to the shared board BEFORE spawning anyone.
+   **Step 6c.** Add ALL tasks to the shared board BEFORE spawning anyone, using as many \`team_tasks_add\` calls as needed to wire dependencies correctly.
       Schema: { content: string, priority: "high"|"medium"|"low", depends_on?: string[] }
-      Use depends_on to block tasks that require other tasks first, pass the IDs returned by team_tasks_add.
+      You cannot reference returned task IDs until an earlier \`team_tasks_add\` call finishes, so add tasks in dependency order.
       \`\`\`
       team_tasks_add tasks:[
         { content: "1.1 <exact task text from tasks.md>", priority: "high" },
-        { content: "1.2 <exact task text>", priority: "high" },
-        { content: "3.1 <task that needs 1.x done first>", priority: "medium", depends_on: ["<id-of-1.1>"] },
-        ...every task, one entry each...
+        { content: "1.2 <exact task text>", priority: "high" }
       ]
       \`\`\`
-      Save the task IDs returned. Pass them to agents in step 6d.
+      Save the returned IDs for root tasks.
+      \`\`\`
+      team_tasks_add tasks:[
+        { content: "2.1 <task that depends on 1.1>", priority: "high", depends_on: ["<real-id-of-1.1>"] },
+        { content: "3.1 <task that depends on 1.2>", priority: "medium", depends_on: ["<real-id-of-1.2>"] }
+      ]
+      \`\`\`
+      Repeat until every OpenSpec task is on the board, then pass the literal IDs returned by those calls to agents in step 6d.
       DO NOT call team_claim yourself, only agents claim tasks.
       DO NOT proceed to 6d until team_tasks_add succeeds.
 
-   **Step 6d.** Discover relevant skills, then spawn specialists with an INITIAL BATCH of tasks.
+   **Step 6d.** Discover available engineers, then spawn specialists with an INITIAL BATCH of tasks.
 
       **ROLLING BATCH MODEL:**
       Agents do NOT receive all their tasks upfront. Instead:
@@ -45,44 +50,60 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       - Repeat until no pending tasks remain on the board.
       - Only shut down an agent when the board has no more tasks for its domain.
 
-      Before spawning, scan \`.agents/skills/\` and read each \`SKILL.md\` description line.
-      Match skills to agents by domain:
-      - 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. Their initial batch of tasks (up to 3): include the LITERAL task IDs (e.g. "task-abc123") AND the task content. Copy them verbatim from the IDs returned by team_tasks_add. Do NOT paraphrase or omit IDs.
-      3. Key context they need (summarized from context files, do NOT tell them to read files themselves)
-      4. The 6 OpenCode tools they have available (these are OpenCode tools, NOT shell commands, call them directly as tools, never via bash):
-         team_claim, team_tasks_complete, team_tasks_list, team_tasks_add, team_message, team_broadcast
-      5. How to proceed: for EACH task ID listed, call team_claim tool with that exact task_id before starting it, call team_tasks_complete tool with that task_id after finishing it, then move to the next task. When all listed tasks are done, message lead with results. Lead may assign more tasks, do NOT shut down until lead confirms no more tasks.
-      6. Which skills to load: list the skill names and paths they MUST read before implementing. Example: "Before starting, read \`.agents/skills/next-best-practices/SKILL.md\` and follow its rules for all Next.js code."
-
-      Keep spawn prompts under 600 tokens. Do not describe team internals or how ensemble works.
+      Before spawning:
+      - scan \`.agents/agents/\` and list the engineers that actually exist in this project
+      - exclude \`devops-manager\` from implementation selection
+      - read each engineer's description and abilities
+      - prefer the most specialized custom engineer whose description and abilities match the task
+      - use \`basic-engineer\` only when no custom engineer is a clear fit or as a recovery fallback
+      - never spawn an engineer name that is not present in \`.agents/agents/\`
+
+      Each \`team_spawn\` MUST include the agent field (required, causes NOT NULL error if omitted).
+
+      The spawn prompt must be short and operational. It must contain:
+      1. Their name and engineer file on this team
+      2. Their initial batch of tasks (up to 3): include the LITERAL task IDs AND the task content. Copy them verbatim from the IDs returned by \`team_tasks_add\`. Do NOT paraphrase or omit IDs.
+      3. Key context they need, summarized from context files
+      4. Exact verification commands or acceptance checks
+      5. Only the mandatory skill names or repo-specific rules they still need after claim
+
+      Keep spawn prompts short and concrete. Prefer 120-220 tokens. Do NOT paste a generic tool list or long workflow boilerplate the plugin and agent file already provide.
+      ALWAYS set \`claim_task\` to the first unblocked task in that agent's initial batch.
       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):
+      Prompt shape:
       \`\`\`
-      team_spawn name:"back" agent:"back-engineer" prompt:"..."
-      (wait for result)
-      team_spawn name:"front" agent:"front-engineer" prompt:"..."
+      You are <worker-name>, <engineer-file>.
+      Claim this task immediately as your first action:
+      - [task-<id1>] <task text>
+      <optional more tasks in the batch>
+
+      Key context:
+      - <short bullets>
+
+      After claiming:
+      1. Load @ob-global
+      2. Load only the relevant abilities/skills for this task
+      3. Implement the task
+      4. Call team_tasks_complete for the same task ID
+      5. Send a short team_message with files changed and checks run
+      \`\`\`
+
+      Spawn sequentially, waiting for each result:
+      \`\`\`
+      team_spawn name:"ui1" agent:"frontend-engineer" prompt:"..."
       (wait for result)
-      team_spawn name:"infra" agent:"infra-engineer" prompt:"..."
+      team_spawn name:"api1" agent:"backend-engineer" prompt:"..."
       (wait for result)
       \`\`\`
+      Replace example agent names with REAL engineers that exist in this project.
 
-      Then immediately send each spawned agent a start message that repeats their task IDs:
+      Then send each spawned agent a short start message that repeats their exact task IDs if needed:
       \`\`\`
-      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."
+      team_message to:"ui1" text:"Claim now: [task-<id1>] <task text>."
       \`\`\`
-      Replace placeholders with REAL task IDs and content. Never send a generic "claim your first task" message without the actual IDs.
+      Never send a generic "claim your first task" message without the actual IDs.
+      If \`claim_task\` already covers the first task, keep the start message minimal. Use follow-up messages mainly for additional tasks in the batch or recovery.
 
    **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.
@@ -96,26 +117,31 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
    **Step 6f.** When a teammate messages back (rolling re-assignment loop):
       1. Call \`team_results from:"<name>"\` to read full message.
       2. Call \`team_tasks_list\` to check remaining pending/unassigned tasks on the board.
-      3. **If there are more unassigned tasks matching this agent's domain:**
-         - Pick up to 3 unassigned, unblocked tasks for this agent's domain.
-         - Send them via \`team_message to:"<name>" text:"Next tasks: [task-<id1>] <desc>, [task-<id2>] <desc>. Claim each with team_claim before starting."\`
-         - Do NOT shut down the agent. Go back to waiting (step 6e).
-      4. **If no more tasks for this agent:**
-         - \`team_shutdown member:"<name>"\`
-         - \`team_merge member:"<name>"\`
-         - If team_merge blocks on local changes: \`git stash\`, retry merge, \`git stash pop\`.
-      5. **If ALL agents are shut down and tasks remain unassigned** (new domain, dependencies unblocked):
-         - Spawn new agents for the remaining tasks (back to step 6d).
-      6. **If ALL tasks are done:** proceed to step 7.
+      3. If the teammate is idle and has not claimed any assigned task:
+         - resend one short claim-only message with the same literal task IDs
+         - if they still do not claim, \`team_shutdown member:"<name>" force:true\`
+         - respawn once with a shorter prompt and the same first \`claim_task\`
+         - if the second spawn also stays idle, stop forcing ensemble for this change and continue in the main session or ask the user whether to retry later
+      4. **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:"Claim next: [task-<id1>] <desc>, [task-<id2>] <desc>."\`
+          - Do NOT shut down the agent. Go back to waiting (step 6e).
+      5. **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\`.
+      6. **If ALL agents are shut down and tasks remain unassigned** (new domain, dependencies unblocked):
+          - Discover the remaining matching engineers from \`.agents/agents/\` and spawn a new wave (back to step 6d).
+      7. **If ALL tasks are done:** proceed to step 7.
       If a teammate reports rate-limit/quota/token exhaustion, immediately shutdown that teammate and respawn with an available model.
 
       **ZERO PENDING TASKS GUARANTEE:** Before proceeding to step 7, call \`team_tasks_list\` and verify EVERY task is either \`done\` or \`blocked\`. If any task is \`pending\` and unassigned, assign it to an agent or spawn a new one. Never leave pending tasks orphaned.
 
 7. **Quality check**
 
-   Spawn quality engineer with worktree:false (read-only, no file edits):
+   Spawn the best available verification-capable engineer with \`worktree:false\` (for example, a testing-focused custom engineer or \`basic-engineer\` if no better verifier exists):
    \`\`\`
-   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>"
+   team_spawn name:"verify" agent:"<real-verifier-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)
 
@@ -139,21 +165,22 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 - NEVER implement tasks directly. Always use team_create + team_spawn, no exceptions
 - NEVER touch source files before team_create is called, not even one edit
 - NEVER call team_spawn without the agent field, it is required and will fail without it
-- NEVER call team_spawn before team_tasks_add, tasks must exist before agents are spawned
+- NEVER call team_spawn before all tasks are on the board; use multiple \`team_tasks_add\` calls when dependencies require real IDs from earlier calls
 - NEVER poll team_results or team_status in a loop, wait for teammates to message you
 - NEVER call team_claim or team_tasks_complete as lead, only agents call these tools
 - NEVER leave pending tasks orphaned, always verify board is empty before proceeding to step 7
 - ALWAYS pass the LITERAL task IDs returned by team_tasks_add into each agent's spawn prompt, copy the exact IDs, never paraphrase
 - ALWAYS assign initial batch of up to 3 tasks per agent; re-assign next batch (up to 3) via team_message when agent reports done
 - ALWAYS call team_tasks_list after each agent reports done to check for remaining unassigned tasks
-- ALWAYS repeat the same literal task IDs in the team_message start trigger, never send a generic "claim your first task" without the actual IDs
+- ALWAYS repeat the same literal task IDs in any task assignment message, 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 add every task to the board before spawning, using multiple \`team_tasks_add\` calls when dependency wiring requires it
+- ALWAYS discover engineers from \`.agents/agents/\` and prefer matching custom engineers over \`basic-engineer\`
 - ALWAYS spawn agents sequentially (wait for each team_spawn result before the next), then send start messages to all of them together
-- ALWAYS instruct agents to call team_claim before each task and team_tasks_complete after
+- ALWAYS set \`claim_task\` for the first unblocked task in each initial batch and instruct agents to claim before any other work
 - 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
+- If teammates are stuck, use one short claim-only message, then one respawn with a shorter prompt. If repeated idle/stall continues, stop forcing ensemble and continue outside it.
 - 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

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

@@ -2,7 +2,7 @@ import { describe, it, expect, 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'
+import { patchApplyFile, APPLY_TARGETS, ENSEMBLE_SECTION } from './ensemble.js'
 
 describe('patchApplyFile()', () => {
   let tmpDir
@@ -70,10 +70,42 @@ describe('patchApplyFile()', () => {
   })
 })
 
-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'))
-  })
-})
+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'))
+  })
+})
+
+describe('ENSEMBLE_SECTION dependency guidance', () => {
+  it('instructs multi-call task creation for dependent tasks', () => {
+    expect(ENSEMBLE_SECTION).toContain('using as many `team_tasks_add` calls as needed')
+    expect(ENSEMBLE_SECTION).toContain('Save the returned IDs for root tasks.')
+    expect(ENSEMBLE_SECTION).toContain('Repeat until every OpenSpec task is on the board')
+  })
+
+  it('requires claim_task and idle-teammate recovery guidance', () => {
+    expect(ENSEMBLE_SECTION).toContain('ALWAYS set \`claim_task\` to the first unblocked task')
+    expect(ENSEMBLE_SECTION).toContain('If the teammate is idle and has not claimed any assigned task')
+    expect(ENSEMBLE_SECTION).toContain('stop forcing ensemble for this change and continue in the main session')
+  })
+
+  it('prefers discovered custom engineers over hardcoded role inventory', () => {
+    expect(ENSEMBLE_SECTION).toContain('scan `.agents/agents/` and list the engineers that actually exist in this project')
+    expect(ENSEMBLE_SECTION).toContain('prefer the most specialized custom engineer')
+    expect(ENSEMBLE_SECTION).not.toContain('front-engineer: UI, components, framework skills')
+    expect(ENSEMBLE_SECTION).not.toContain('team_spawn name:"front" agent:"front-engineer"')
+  })
+
+  it('keeps the prompt claim-first and minimal', () => {
+    expect(ENSEMBLE_SECTION).toContain('Claim this task immediately as your first action:')
+    expect(ENSEMBLE_SECTION).toContain('After claiming:')
+    expect(ENSEMBLE_SECTION).not.toContain('Available OpenCode tools:')
+  })
+
+  it('does not include the impossible same-call dependency example', () => {
+    expect(ENSEMBLE_SECTION).not.toContain('{ content: "3.1 <task that needs 1.x done first>", priority: "medium", depends_on: ["<id-of-1.1>"] }')
+    expect(ENSEMBLE_SECTION).not.toContain('Use depends_on to block tasks that require other tasks first, pass the IDs returned by team_tasks_add.')
+  })
+})

package/src/steps/optimization/codegraph.js

@@ -1,6 +1,55 @@
 import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'node:path'
 import { header, success, warn, error, loading } from '../../utils/exec.js'
 
+/**
+ * After codegraph install, it may create an `opencode.jsonc` at the project root.
+ * This project uses `.opencode/opencode.json` instead. Merge any MCP config from
+ * the rogue file into the correct location and remove it.
+ */
+export async function fixCodegraphConfig() {
+  const cwd = process.cwd()
+  const rogueFile = path.join(cwd, 'opencode.jsonc')
+  const correctFile = path.join(cwd, '.opencode', 'opencode.json')
+
+  if (!await fse.pathExists(rogueFile)) return
+
+  let rogueContent
+  try {
+    const raw = await fse.readFile(rogueFile, 'utf-8')
+    // Strip JSONC comments (single-line // and block /* */) before parsing
+    const stripped = raw
+      .replace(/\/\/.*$/gm, '')
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+    rogueContent = JSON.parse(stripped)
+  } catch {
+    warn('Could not parse opencode.jsonc, removing it')
+    await fse.remove(rogueFile)
+    return
+  }
+
+  let correctContent = {}
+  if (await fse.pathExists(correctFile)) {
+    try {
+      correctContent = await fse.readJson(correctFile)
+    } catch {
+      correctContent = {}
+    }
+  }
+
+  // Merge mcpServers from rogue into correct config
+  if (rogueContent.mcpServers || rogueContent.mcp) {
+    const mcpServers = rogueContent.mcpServers || rogueContent.mcp
+    correctContent.mcpServers = { ...(correctContent.mcpServers || {}), ...mcpServers }
+  }
+
+  await fse.ensureDir(path.dirname(correctFile))
+  await fse.writeJson(correctFile, correctContent, { spaces: 2 })
+  await fse.remove(rogueFile)
+  warn('Migrated codegraph config from opencode.jsonc → .opencode/opencode.json (removed opencode.jsonc)')
+}
+
 export async function installCodegraph(options = {}) {
   if (!options.skipHeader) header('Installing codegraph')
 
@@ -23,6 +72,8 @@ export async function installCodegraph(options = {}) {
       warn('codegraph install exited with non-zero code')
       return { optedIn: true, installed: false }
     }
+
+    await fixCodegraphConfig()
     success(`codegraph configured for opencode (${location})`)
   } catch (err) {
     error(`Failed to install codegraph: ${err.message}`)

package/src/steps/optimization/codegraph.test.js

@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import fse from 'fs-extra'
+
+vi.mock('execa', () => ({ execa: vi.fn() }))
+vi.mock('../../utils/exec.js', () => ({
+  header: vi.fn(),
+  success: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  loading: vi.fn(),
+}))
+
+import { warn } from '../../utils/exec.js'
+import { fixCodegraphConfig } from './codegraph.js'
+
+describe('fixCodegraphConfig()', () => {
+  let tmpDir
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-test-'))
+    vi.spyOn(process, 'cwd').mockReturnValue(tmpDir)
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+    vi.restoreAllMocks()
+  })
+
+  it('does nothing when opencode.jsonc does not exist', async () => {
+    await fixCodegraphConfig()
+    // No error, no file created
+    expect(fs.existsSync(path.join(tmpDir, '.opencode', 'opencode.json'))).toBe(false)
+  })
+
+  it('merges mcpServers from opencode.jsonc into .opencode/opencode.json', async () => {
+    const rogueContent = {
+      mcpServers: {
+        codegraph: { command: 'codegraph', args: ['mcp'] }
+      }
+    }
+    fs.writeFileSync(path.join(tmpDir, 'opencode.jsonc'), JSON.stringify(rogueContent))
+
+    const opencodeDir = path.join(tmpDir, '.opencode')
+    fs.mkdirSync(opencodeDir, { recursive: true })
+    fs.writeFileSync(path.join(opencodeDir, 'opencode.json'), JSON.stringify({
+      "$schema": "https://opencode.ai/config.json",
+      "plugin": ["opencode-plugin-openspec@latest"]
+    }))
+
+    await fixCodegraphConfig()
+
+    expect(fs.existsSync(path.join(tmpDir, 'opencode.jsonc'))).toBe(false)
+    const result = await fse.readJson(path.join(opencodeDir, 'opencode.json'))
+    expect(result.mcpServers.codegraph).toEqual({ command: 'codegraph', args: ['mcp'] })
+    expect(result.plugin).toEqual(["opencode-plugin-openspec@latest"])
+  })
+
+  it('handles JSONC with comments', async () => {
+    const rogueRaw = `{
+  // This is a comment
+  "mcpServers": {
+    "codegraph": { "command": "codegraph", "args": ["mcp"] }
+  }
+}`
+    fs.writeFileSync(path.join(tmpDir, 'opencode.jsonc'), rogueRaw)
+
+    const opencodeDir = path.join(tmpDir, '.opencode')
+    fs.mkdirSync(opencodeDir, { recursive: true })
+    fs.writeFileSync(path.join(opencodeDir, 'opencode.json'), '{}')
+
+    await fixCodegraphConfig()
+
+    expect(fs.existsSync(path.join(tmpDir, 'opencode.jsonc'))).toBe(false)
+    const result = await fse.readJson(path.join(opencodeDir, 'opencode.json'))
+    expect(result.mcpServers.codegraph.command).toBe('codegraph')
+  })
+
+  it('removes unparseable opencode.jsonc and warns', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'opencode.jsonc'), 'not valid json {{{')
+
+    await fixCodegraphConfig()
+
+    expect(fs.existsSync(path.join(tmpDir, 'opencode.jsonc'))).toBe(false)
+    expect(warn).toHaveBeenCalledWith('Could not parse opencode.jsonc, removing it')
+  })
+
+  it('creates .opencode/opencode.json if it does not exist', async () => {
+    const rogueContent = {
+      mcpServers: {
+        codegraph: { command: 'codegraph', args: ['mcp'] }
+      }
+    }
+    fs.writeFileSync(path.join(tmpDir, 'opencode.jsonc'), JSON.stringify(rogueContent))
+
+    await fixCodegraphConfig()
+
+    const result = await fse.readJson(path.join(tmpDir, '.opencode', 'opencode.json'))
+    expect(result.mcpServers.codegraph.command).toBe('codegraph')
+    expect(fs.existsSync(path.join(tmpDir, 'opencode.jsonc'))).toBe(false)
+  })
+})

package/src/steps/optimization/global.js

@@ -29,7 +29,27 @@ function buildSourceRootsSection(sourceRoots, cwd) {
 
 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.`
+  return [
+    '## RTK, MANDATORY',
+    '',
+    'RTK has NO automatic hook in OpenCode. You MUST explicitly prefix every CLI command with `rtk`. It does not happen automatically.',
+    '',
+    'Prefix ALL shell commands with `rtk`:',
+    '- `rtk git diff` NOT `git diff`',
+    '- `rtk git log` NOT `git log`',
+    '- `rtk gh` NOT `gh`',
+    '- `rtk az` NOT `az`',
+    '- `rtk openspec` NOT `openspec`',
+    '- `rtk npx tsc --noEmit` NOT `npx tsc --noEmit`',
+    '- `rtk pnpm build` NOT `pnpm build`',
+    '- `rtk pnpm test` NOT `pnpm test`',
+    '- `rtk pnpm lint` NOT `pnpm lint`',
+    '- `rtk dotnet build` NOT `dotnet build`',
+    '',
+    'Light read-only commands that produce minimal output (e.g. `cat`, `ls`, `Get-Content`, `Select-String`) do not need `rtk`.',
+    '',
+    'If `rtk` is not available, report blocker and stop CLI execution.',
+  ].join('\n')
 }
 
 function buildCavemanSection(cavemanEnabled) {

package/src/steps/optimization/global.test.js

@@ -64,6 +64,9 @@ describe('configureObGlobal()', () => {
     await configureObGlobal({}, { rtk: { optedIn: true } })
     const content = fs.readFileSync(skillPath, 'utf-8')
     expect(content).toContain('RTK, MANDATORY')
+    expect(content).toContain('NO automatic hook in OpenCode')
+    expect(content).toContain('rtk pnpm build')
+    expect(content).toContain('rtk npx tsc')
   })
 
   it('injects RTK not-selected note when rtk is not opted in', async () => {

package/src/steps/platform/index.js

@@ -12,6 +12,12 @@ const platformsPreset = await fse.readJson(PLATFORMS_PRESET_PATH)
 
 export async function checkPlatform(platform) {
   const preset = platformsPreset.find(p => p.value === platform) || platformsPreset[0]
+  if (!preset.cli) {
+    header(`Step 4, Checking ${preset.name} CLI`)
+    info('No platform integration selected, skipping CLI checks.')
+    success(`Platform: ${preset.name}`)
+    return
+  }
   await checkPlatformCli(preset)
 }
 
@@ -23,7 +29,8 @@ export async function choosePlatform() {
     choices: platformsPreset.map(p => ({ name: p.name, value: p.value })),
   })
 
-  success(`Platform: ${platform === 'github' ? 'GitHub' : 'Azure DevOps'}`)
+  const preset = platformsPreset.find(p => p.value === platform)
+  success(`Platform: ${preset?.name || platform}`)
   await checkPlatform(platform)
   return platform
 }