opencode-onboard 0.2.0 → 0.2.6

package/content/.opencode/plugins/session-log.js

@@ -3,7 +3,7 @@ import path from "node:path"
 
 const LOG_FILE = ".agents/session-log.json"
 
-// Per-session state: editCount and skills loaded
+// Per-session state: editCount and loaded skills
 const sessionState = new Map()
 
 function ts() {
@@ -32,6 +32,29 @@ function resolveAgentName(session) {
   return "lead"
 }
 
+function addSkillToState(state, skillName) {
+  if (!skillName || !state) return false
+  if (!state.skills) state.skills = new Set()
+  if (state.skills.has(skillName)) return false
+  state.skills.add(skillName)
+  return true
+}
+
+function buildTeamSkillsSummary() {
+  const byAgent = {}
+  for (const state of sessionState.values()) {
+    if (!state?.agentName) continue
+    if (!byAgent[state.agentName]) byAgent[state.agentName] = new Set()
+    for (const skill of state.skills ?? []) byAgent[state.agentName].add(skill)
+  }
+
+  const summary = {}
+  for (const [agent, skills] of Object.entries(byAgent)) {
+    summary[agent] = Array.from(skills).sort()
+  }
+  return summary
+}
+
 // Maps ensemble tool name → function that extracts the log entry fields from args
 const ENSEMBLE_TOOL_HANDLERS = {
   team_create:         (args) => ({ action: "team-created",        team: args.name }),
@@ -60,7 +83,7 @@ export const SessionLogPlugin = async ({ client, directory }) => {
           const session = res?.data
           const agentName = resolveAgentName(session)
 
-          sessionState.set(sessionId, { agentName, editCount: 0, skills: [] })
+          sessionState.set(sessionId, { agentName, editCount: 0, skills: new Set() })
           appendEntry(directory, { ts: ts(), agent: agentName, action: "started", sessionId })
         }
 
@@ -77,7 +100,8 @@ export const SessionLogPlugin = async ({ client, directory }) => {
           const state = sessionState.get(sessionId)
           if (!state) return
 
-          const { agentName, editCount, skills } = state
+          const { agentName, editCount } = state
+          const skills = Array.from(state.skills ?? []).sort()
           appendEntry(directory, { ts: ts(), agent: agentName, action: "completed", filesEdited: editCount, skills })
           sessionState.delete(sessionId)
         }
@@ -94,14 +118,26 @@ export const SessionLogPlugin = async ({ client, directory }) => {
 
         const tool = input?.tool
 
-        // Track skill loads
+        // Track skill loads via skill tool (primary)
+        if (tool === "skill") {
+          const skillName = input?.args?.name
+          const added = addSkillToState(state, skillName)
+          if (added) {
+            appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName, source: "skill-tool" })
+          }
+          return
+        }
+
+        // Track skill loads via reading SKILL.md (fallback)
         if (tool === "read") {
           const filePath = input?.args?.filePath ?? ""
           const match = filePath.match(/[/\\]skills[/\\]([^/\\]+)[/\\]SKILL\.md$/i)
           if (match) {
             const skillName = match[1]
-            if (!state.skills.includes(skillName)) state.skills.push(skillName)
-            appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName })
+            const added = addSkillToState(state, skillName)
+            if (added) {
+              appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName, source: "read-skill-file" })
+            }
           }
           return
         }
@@ -112,7 +148,12 @@ export const SessionLogPlugin = async ({ client, directory }) => {
         const ensembleHandler = ENSEMBLE_TOOL_HANDLERS[tool]
         if (!ensembleHandler) return
 
-        appendEntry(directory, { ts: ts(), agent: state.agentName, ...ensembleHandler(args) })
+        const entry = { ts: ts(), agent: state.agentName, ...ensembleHandler(args) }
+        appendEntry(directory, entry)
+
+        if (tool === "team_cleanup") {
+          appendEntry(directory, { ts: ts(), agent: state.agentName, action: "team-skills-summary", byAgent: buildTeamSkillsSummary() })
+        }
       } catch (_) {}
     },
   }

package/content/AGENTS.md

@@ -16,6 +16,8 @@ When the user says anything resembling initialization, "init", "initialize", "se
 
 Scan the codebase for any existing documentation, changelogs, ADRs, README files, or notable history that describes decisions already made in this project. Create an OpenSpec archive entry that captures this history so agents have context going forward.
 
+Before scanning, load source roots from `.agents/source-roots.json` when present. Only scan those roots plus this repo's docs/config files.
+
 ```bash
 openspec new change "project-history"
 ```
@@ -40,7 +42,7 @@ openspec archive "project-history"
 1. **Read `DESIGN.md` now** using a file read tool. The file contains a prompt with instructions and an output format.
 2. **Store the full prompt text** in your context.
 3. **Overwrite `DESIGN.md` with an empty string** (zero bytes). Do this before generating any content.
-4. **Analyze the actual codebase**: read CSS files, Tailwind config, component files, token definitions. Do not rely on prior knowledge, read the files.
+4. **Analyze the actual codebase**: use `.agents/source-roots.json` as source roots when present, then read CSS files, Tailwind config, component files, token definitions. Do not rely on prior knowledge, read the files.
 5. **Write the result into `DESIGN.md`** following exactly the format and sections described in the stored prompt.
 
 The output must be a real, populated `DESIGN.md` based on what you found in the codebase, not from memory or assumptions.
@@ -54,7 +56,7 @@ The output must be a real, populated `DESIGN.md` based on what you found in the
 1. **Read `ARCHITECTURE.md` now** using a file read tool. The file contains a prompt with instructions and an output format.
 2. **Store the full prompt text** in your context.
 3. **Overwrite `ARCHITECTURE.md` with an empty string** (zero bytes). Do this before generating any content.
-4. **Analyze the actual codebase**: read folder structure, config files, route definitions, data models, integration points. Do not rely on prior knowledge, read the files.
+4. **Analyze the actual codebase**: use `.agents/source-roots.json` as source roots when present, then read folder structure, config files, route definitions, data models, integration points. Do not rely on prior knowledge, read the files.
 5. **Write the result into `ARCHITECTURE.md`** following exactly the format and sections described in the stored prompt.
 
 The output must be a real, populated `ARCHITECTURE.md` based on what you found in the codebase, covering all sections the prompt describes.
@@ -112,6 +114,12 @@ This is the agent orchestration layer for your project. It provides:
 - OpenSpec change management
 - Skills for platform-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.
+
 ## 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.
@@ -121,6 +129,7 @@ Trigger patterns, I recognize ALL of these, exact wording does not matter:
 - User pastes or mentions an Azure DevOps URL → load `ob-userstory-az` skill → parse work item → run `/opsx-propose` → confirm with user → run `/opsx-apply` → ship
 - `implement the plan` / `implement` / `start` / `go` → run `/opsx-apply` → ship
 - `I've added comments to the PR` → read PR comments → fix → update PR
+- Any GitHub/Azure DevOps PR URL in a feedback/fix request (e.g. "check comments", "fix PR feedback") → run PR Feedback Loop
 
 **A GitHub or Azure DevOps URL anywhere in the user's message is always a trigger, regardless of surrounding words.**
 
@@ -149,6 +158,17 @@ Works on **all platforms** (Windows, macOS, Linux) via OpenCode's built-in workt
 
 **Dashboard**: Monitor running agents at **http://localhost:4747/**
 
+**Progress inspection commands (tell user explicitly after spawning):**
+- `team_status` for live team snapshot
+- `team_tasks_list` for task board state
+- `team_view member:"<name>"` to inspect a teammate live session
+- `team_results from:"<name>"` to fetch full teammate report text
+
+If a teammate stalls due to model quota/rate-limit exhaustion:
+1. `team_shutdown name:"<stuck-member>" force:true`
+2. `team_spawn` same member/task with an available model
+3. `team_message` start instruction with the exact next task ID
+
 ---
 
 ## Pipeline
@@ -220,12 +240,24 @@ devops-manager (ship mode)
 ### Phase 6, PR Feedback Loop
 
 ```
-When user says "I've added comments to the PR":
-1. team_spawn devops-manager (feedback mode) → read & classify comments
-2. Wait → team_results → spawn front/back/infra for code-change items (parallel)
-3. Wait → team_results → spawn quality-engineer → verify fixes
-4. Wait → team_results → spawn devops-manager (ship mode) → push & update PR
-5. team_cleanup
+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)
+   - 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
 ```
 
 ---

package/package.json

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

package/src/index.js

@@ -5,13 +5,15 @@ 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 { choosePlatform } from './steps/choose-platform.js'
-import { chooseSkillsProvider } from './steps/choose-skills-provider.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 { installBrowser } from './steps/install-browser.js'
+import { patchAgentsMd } from './steps/patch-agents-md.js'
+import { installBrowser } from './steps/install-browser.js'
+import { writeOnboardConfig } from './steps/write-onboard-config.js'
 
 if (process.stdout.isTTY) console.clear()
 console.log()
@@ -59,35 +61,47 @@ try {
   // 1. Check Node + pnpm
   await checkEnv()
 
-  // 2. Clean existing AI config files, detect preserved state
-  const ctx = await cleanAiFiles()
-
-  // 3. Choose platform
-  const platform = await choosePlatform()
-
-  // 4. Check platform CLI (az or gh)
-  await checkPlatform(platform)
-
-  // 5. Copy content
-  await copyContentStep(platform, ctx)
-
-  // 5b. Patch AGENTS.md to skip steps for already-existing files
-  await patchAgentsMd(ctx)
-
-  // 6. Init OpenSpec
-  await initOpenspec()
-
-  // 7. Install skills
-  await chooseSkillsProvider()
-
-  // 8. Choose models
-  await chooseModels()
-
-  // 9. Check RTK
-  await checkRtk()
-
-  // 10. Install opencode-browser
-  await installBrowser()
+  // 2. Choose source code scope for init analysis
+  const scope = await chooseSourceScope()
+
+  // 3. Clean existing AI config files, detect preserved state
+  const preserve = await cleanAiFiles()
+  const ctx = { ...preserve, ...scope }
+
+  // 4. Choose platform
+  const platform = await choosePlatform()
+
+  // 5. Check platform CLI (az or gh)
+  await checkPlatform(platform)
+
+  // 6. Copy content
+  await copyContentStep(platform, ctx)
+
+  // 6b. Patch AGENTS.md to skip steps for already-existing files
+  await patchAgentsMd(ctx)
+
+  // 7. Init OpenSpec
+  await initOpenspec()
+
+  // 8. Install skills
+  const skillsSelection = await chooseSkillsProvider()
+
+  // 9. Choose models
+  const selectedModels = await chooseModels()
+
+  // 10. Check RTK
+  await checkRtk()
+
+  // 11. Install opencode-browser
+  await installBrowser()
+
+  // 12. Write onboarding metadata
+  await writeOnboardConfig({
+    ...ctx,
+    platform,
+    ...skillsSelection,
+    ...selectedModels,
+  })
 
   // Done
   const toGenerate = [
@@ -103,13 +117,14 @@ try {
   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()
+  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()
 } catch (err) {
   if (err.name === 'ExitPromptError') {
     console.log()

package/src/steps/check-platform.js

@@ -10,7 +10,7 @@ export async function checkPlatform(platform) {
 }
 
 async function checkAzure() {
-  header('Step 4, Checking Azure DevOps CLI')
+  header('Step 5, Checking Azure DevOps CLI')
 
   // Check az is installed
   const hasAz = await commandExists('az')
@@ -51,7 +51,7 @@ async function checkAzure() {
 }
 
 async function checkGithub() {
-  header('Step 4, Checking GitHub CLI')
+  header('Step 5, Checking GitHub CLI')
 
   const hasGh = await commandExists('gh')
 

package/src/steps/check-rtk.js

@@ -1,7 +1,7 @@
 import { code, commandExists, header, info, success, warn } from '../utils/exec.js'
 
 export async function checkRtk() {
-  header('Step 9, Checking rtk')
+  header('Step 10, Checking rtk')
 
   const available = await commandExists('rtk')
 

package/src/steps/choose-models.js

@@ -66,7 +66,7 @@ async function writeModelToAgent(agentFile, modelId) {
 }
 
 export async function chooseModels() {
-  header('Step 8, Choose models')
+  header('Step 9, Choose models')
 
   info('Fetching available models from models.dev...')
   const { models: rawModels, source } = await fetchModels()
@@ -154,4 +154,10 @@ export async function chooseModels() {
   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/choose-platform.js

@@ -10,7 +10,7 @@ const PLATFORMS_PRESET_PATH = path.resolve(__dirname, '../presets/platforms.json
 const platformsPreset = await fse.readJson(PLATFORMS_PRESET_PATH)
 
 export async function choosePlatform() {
-  header('Step 3, Version control platform')
+  header('Step 4, Version control platform')
 
   const platform = await select({
     message: 'Which platform are you using?',

package/src/steps/choose-skills-provider.js

@@ -28,7 +28,7 @@ async function installObSkills() {
 }
 
 export async function chooseSkillsProvider() {
-  header('Step 7, Installing skills')
+  header('Step 8, Installing skills')
 
   // ob-skills are always installed, mandatory
   info('Installing built-in ob-skills...')
@@ -56,7 +56,7 @@ export async function chooseSkillsProvider() {
   })
 
   if (selected === 'none') {
-    return
+    return { additionalSkillsProvider: 'none' }
   }
 
   if (selected === 'npx-skills') {
@@ -71,5 +71,9 @@ export async function chooseSkillsProvider() {
     } catch (err) {
       warn(`npx skills failed: ${err.message}`)
     }
+
+    return { additionalSkillsProvider: 'npx-skills' }
   }
+
+  return { additionalSkillsProvider: selected }
 }

package/src/steps/choose-source-scope.js

@@ -0,0 +1,81 @@
+import { checkbox, select } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'path'
+import { header, info, success, warn } from '../utils/exec.js'
+
+async function listParentFolders(cwd) {
+  const parent = path.resolve(cwd, '..')
+  const entries = await fse.readdir(parent)
+  const dirs = []
+
+  for (const name of entries) {
+    if (name.startsWith('.')) continue
+    const abs = path.join(parent, name)
+    try {
+      const stat = await fse.stat(abs)
+      if (!stat.isDirectory()) continue
+      if (path.resolve(abs) === path.resolve(cwd)) continue
+      dirs.push({ name, abs })
+    } catch {
+      // ignore invalid entries
+    }
+  }
+
+  dirs.sort((a, b) => a.name.localeCompare(b.name))
+  return dirs
+}
+
+export async function chooseSourceScope() {
+  header('Step 2, Source code scope')
+
+  const cwd = process.cwd()
+  info('Choose where agents should read source code from during init analysis.')
+
+  const mode = await select({
+    message: 'Source code location:',
+    default: 'current',
+    choices: [
+      {
+        name: 'Current folder (default)',
+        value: 'current',
+        description: 'Use this repository only',
+      },
+      {
+        name: 'Select folders in parent (../)',
+        value: 'parent',
+        description: 'Use when this repo only contains agent config',
+      },
+    ],
+  })
+
+  if (mode === 'current') {
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  const parentFolders = await listParentFolders(cwd)
+  if (parentFolders.length === 0) {
+    warn('No sibling folders found in parent directory. Falling back to current folder.')
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  const selected = await checkbox({
+    message: 'Select source folders from parent directory:',
+    choices: parentFolders.map(d => ({
+      name: `../${d.name}`,
+      value: d.abs,
+      checked: false,
+    })),
+    required: true,
+  })
+
+  if (!selected || selected.length === 0) {
+    warn('No folders selected. Falling back to current folder.')
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  success(`Source scope: ${selected.map(p => path.basename(p)).join(', ')}`)
+  return { sourceMode: 'parent-selected', sourceRoots: selected }
+}

package/src/steps/clean-ai-files.js

@@ -53,7 +53,7 @@ async function hasOpenspecHistory(cwd) {
 }
 
 export async function cleanAiFiles() {
-  header('Step 2, Existing AI config files')
+  header('Step 3, Existing AI config files')
 
   const cwd = process.cwd()
 

package/src/steps/copy-content.js

@@ -1,18 +1,86 @@
 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'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const CONTENT_DIR = path.resolve(__dirname, '../../content')
 
+function formatRootsForText(roots = [], cwd = process.cwd()) {
+  if (!roots.length) return ['current folder']
+  return roots.map(r => {
+    const rel = path.relative(cwd, r)
+    if (!rel || rel === '') return 'current folder'
+    if (!rel.startsWith('..')) return `./${rel.replace(/\\/g, '/')}`
+    return rel.replace(/\\/g, '/')
+  })
+}
+
+async function patchSourceScopeFiles(dest, ctx) {
+  const roots = formatRootsForText(ctx.sourceRoots || [dest], dest)
+  const rootsInline = roots.join(', ')
+  const rootsBullets = roots.map(r => `  - ${r}`).join('\n')
+
+  const agentsPath = path.join(dest, 'AGENTS.md')
+  if (await fse.pathExists(agentsPath)) {
+    let content = await fse.readFile(agentsPath, 'utf-8')
+    content = content.replace(
+      'Before scanning, load source roots from `.agents/source-roots.json` when present. Only scan those roots plus this repo\'s docs/config files.',
+      `Source roots selected during onboarding (scan these roots plus this repo docs/config): ${rootsInline}.`
+    )
+    content = content.replace(
+      '4. **Analyze the actual codebase**: use `.agents/source-roots.json` as source roots when present, then read CSS files, Tailwind config, component files, token definitions. Do not rely on prior knowledge, read the files.',
+      `4. **Analyze the actual codebase** using these source roots:\n${rootsBullets}\n\n   Then read CSS files, Tailwind config, component files, token definitions. Do not rely on prior knowledge, read the files.`
+    )
+    content = content.replace(
+      '4. **Analyze the actual codebase**: use `.agents/source-roots.json` as source roots when present, then read folder structure, config files, route definitions, data models, integration points. Do not rely on prior knowledge, read the files.',
+      `4. **Analyze the actual codebase** using these source roots:\n${rootsBullets}\n\n   Then read folder structure, config files, route definitions, data models, integration points. Do not rely on prior knowledge, read the files.`
+    )
+    content = content.replace(
+      '- Read source scope from `.agents/source-roots.json`.',
+      `- Source roots selected during onboarding: ${rootsInline}.`
+    )
+    await fse.writeFile(agentsPath, content, 'utf-8')
+  }
+
+  const designPath = path.join(dest, 'DESIGN.md')
+  if (await fse.pathExists(designPath)) {
+    let content = await fse.readFile(designPath, 'utf-8')
+    const injection = `\nSource roots selected during onboarding:\n${rootsBullets}\n\nWhen analyzing, read UI/design evidence only from these roots.\n\nIn the generated DESIGN.md, add this section near the top:\n\n## Source Roots Used\n${rootsBullets}\n`
+    content = content.replace(
+      'Analyze the design system of this codebase with the goal of creating a DESIGN.md file in the project root and giving the user a file for easy copy & pasting.',
+      'Analyze the design system of this codebase with the goal of creating a DESIGN.md file in the project root and giving the user a file for easy copy & pasting.' + injection
+    )
+    await fse.writeFile(designPath, content, 'utf-8')
+  }
+
+  const architecturePath = path.join(dest, 'ARCHITECTURE.md')
+  if (await fse.pathExists(architecturePath)) {
+    let content = await fse.readFile(architecturePath, 'utf-8')
+    const injection = `\nSource roots selected during onboarding:\n${rootsBullets}\n\nWhen analyzing, read architecture evidence only from these roots.\n\nIn the generated ARCHITECTURE.md, add this section near the top:\n\n## Source Roots Used\n${rootsBullets}\n`
+    content = content.replace(
+      'Analyze the architecture of this codebase with the goal of creating an ARCHITECTURE.md file in the project root and giving the user a file for easy copy & pasting.',
+      'Analyze the architecture of this codebase with the goal of creating an ARCHITECTURE.md file in the project root and giving the user a file for easy copy & pasting.' + injection
+    )
+    await fse.writeFile(architecturePath, content, 'utf-8')
+  }
+}
+
 export async function copyContentStep(platform, ctx = {}) {
-  header('Step 5, Copying opencode-onboard files')
+  header('Step 6, Copying opencode-onboard files')
 
   const dest = process.cwd()
 
   try {
     await copyContent(CONTENT_DIR, dest, platform, ctx)
+    const rootsFile = path.join(dest, '.agents', 'source-roots.json')
+    await fse.ensureDir(path.dirname(rootsFile))
+    await fse.writeJson(rootsFile, {
+      mode: ctx.sourceMode || 'current',
+      roots: ctx.sourceRoots || [dest],
+    }, { spaces: 2 })
+    await patchSourceScopeFiles(dest, ctx)
     success('Files copied to project root')
   } catch (err) {
     error(`Failed to copy content: ${err.message}`)

package/src/steps/init-openspec.js

@@ -1,28 +1,159 @@
 import { execa } from 'execa'
-import fse from 'fs-extra'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import fse from 'fs-extra'
 import { error, header, success, warn } from '../utils/exec.js'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-// Our owned apply command and skill, stored in the package content folder.
-// After openspec init generates its versions, we delete them and copy ours in.
-const OUR_CONTENT_DIR = path.resolve(__dirname, '../../content')
-
-const APPLY_OVERRIDES = [
-  {
-    src: path.join(OUR_CONTENT_DIR, '.opencode', 'commands', 'opsx-apply.md'),
-    dest: path.join('.opencode', 'commands', 'opsx-apply.md'),
-  },
-  {
-    src: path.join(OUR_CONTENT_DIR, '.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
-    dest: path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
-  },
+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**
+
+   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.
+
+   Steps MUST be followed in order. Do not skip any step.
+
+   **Step 6a.** Create feature branch if not already on one: \`feature/{id}-{slug}\`
+
+   **Step 6b.** Create the team:
+      \`\`\`
+      team_create "<change-name>-<random 4 digit number>"
+      \`\`\`
+      Announce: "Team running. Monitor at http://localhost:4747/"
+
+   **Step 6c.** Add ALL tasks to the shared board BEFORE spawning anyone.
+      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.
+      \`\`\`
+      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...
+      ]
+      \`\`\`
+      Save the task IDs returned. Pass them 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.** Spawn all needed specialists, then kick them off in parallel.
+
+      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
+      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
+
+      Keep spawn prompts under 500 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):
+      \`\`\`
+      team_spawn name:"back" agent:"back-engineer" prompt:"..."
+      (wait for result)
+      team_spawn name:"front" agent:"front-engineer" prompt:"..."
+      (wait for result)
+      team_spawn name:"infra" agent:"infra-engineer" prompt:"..."
+      (wait for result)
+      \`\`\`
+
+      Then immediately send each spawned agent a start message to kick them off:
+      \`\`\`
+      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."
+      \`\`\`
+
+   **Step 6e.** After sending start messages, tell the user what is running, then STOP and wait.
+      Do NOT call team_results, team_status, or team_broadcast in a loop.
+      Teammates will message you when done or blocked. Wait for those messages.
+      Tell the user exactly how to inspect progress:
+      - \`team_status\` for team snapshot
+      - \`team_tasks_list\` for board state
+      - \`team_view member:"<name>"\` for a teammate live session
+      - \`team_results from:"<name>"\` for full teammate report text
+
+   **Step 6f.** When a teammate messages back, you receive a ping only, the full content is NOT in the notification.
+      Call team_results to read the full message and mark it read. Then for each teammate: team_shutdown -> team_merge.
+      If team_merge blocks ("overlapping local changes"), commit or stash your local changes first, then retry.
+      Fix any other blockers reported.
+      If a teammate reports rate-limit/quota/token exhaustion, immediately shutdown that teammate and respawn with an available model.
+
+7. **Quality check**
+
+   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>"
+   \`\`\`
+   Wait for message -> team_results -> fix blockers -> team_shutdown (no team_merge needed, worktree:false)
+
+8. **Mark tasks complete in openspec**
+
+   Update tasks.md: \`- [ ]\` -> \`- [x]\` for each completed task.
+   Run \`rtk openspec status --change "<name>" --json\` to confirm.
+
+9. **Show status, then cleanup**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive with \`/opsx-archive\`
+   - If paused: explain why and wait for guidance
+
+   Then run \`team_cleanup\`.
+
+**Guardrails**
+- NEVER skip or reorder steps 6a-6f
+- 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 poll team_results or team_status in a loop, wait for teammates to message you
+- NEVER call team_claim or team_tasks_complete as lead, only agents call these tools
+- ALWAYS pass the task IDs returned by team_tasks_add to each agent's spawn prompt
+- NEVER 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
+- ALWAYS instruct agents to call team_claim before each task and team_tasks_complete after
+- If teammates are stuck, use team_message to resend tasks, then wait, never implement directly
+- 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
+- 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' }
+
+  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 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 6, Initializing OpenSpec')
+  header('Step 7, Initializing OpenSpec')
 
   try {
     const result = await execa('npx', ['@fission-ai/openspec', 'init', '--tools', 'opencode', '--force'], {
@@ -40,15 +171,18 @@ export async function initOpenspec() {
     error(`Failed to run openspec init: ${err.message}`)
   }
 
-  // Replace the openspec-generated apply command and skill with our ensemble-native versions.
-  // The generated files implement tasks directly (solo agent). Ours delegate to the ensemble team.
-  for (const { src, dest } of APPLY_OVERRIDES) {
-    const destAbs = path.join(process.cwd(), dest)
+  // 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 {
-      await fse.copy(src, destAbs, { overwrite: true })
-      success(`Installed ensemble apply → ${dest}`)
+      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 install ${dest}: ${err.message}`)
+      warn(`Could not patch ${rel}: ${err.message}`)
     }
   }
 }

package/src/steps/install-browser.js

@@ -12,7 +12,7 @@ const AUTO_ANSWERS = [
 ]
 
 export async function installBrowser() {
-  header('Step 10, Installing opencode-browser')
+  header('Step 11, Installing opencode-browser')
 
   try {
     const child = execa('npx', ['@different-ai/opencode-browser', 'install'], {

package/src/steps/write-onboard-config.js

@@ -0,0 +1,59 @@
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { createRequire } from 'node:module'
+import { header, success, warn } from '../utils/exec.js'
+
+const require = createRequire(import.meta.url)
+const { version: onboardVersion } = require('../../package.json')
+
+async function detectOpencodeVersion() {
+  try {
+    const result = await execa('opencode', ['--version'], { reject: false })
+    if (result.exitCode !== 0) return null
+    const output = (result.stdout || result.stderr || '').trim()
+    return output || null
+  } catch {
+    return null
+  }
+}
+
+export async function writeOnboardConfig(data) {
+  header('Step 12, Writing onboarding metadata')
+
+  const opencodeVersion = await detectOpencodeVersion()
+  const target = path.join(process.cwd(), '.opencode', 'opencode-onboard.json')
+
+  const payload = {
+    schema: 1,
+    generatedAt: new Date().toISOString(),
+    onboardVersion,
+    opencodeVersion,
+    wizard: {
+      platform: data.platform,
+      sourceMode: data.sourceMode,
+      sourceRoots: data.sourceRoots,
+      preserved: {
+        design: !!data.hasDesign,
+        architecture: !!data.hasArchitecture,
+        openspec: !!data.hasOpenspec,
+      },
+      additionalSkillsProvider: data.additionalSkillsProvider,
+      models: {
+        plan: data.planModel,
+        build: data.buildModel,
+        fast: data.fastModel,
+      },
+    },
+    note: 'Informational file only. Editing this file does not change runtime behavior.',
+  }
+
+  try {
+    await fse.ensureDir(path.dirname(target))
+    await fse.writeJson(target, payload, { spaces: 2 })
+    success('Wrote .opencode/opencode-onboard.json')
+    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
+  } catch (err) {
+    warn(`Could not write onboarding metadata: ${err.message}`)
+  }
+}