opencode-onboard 0.2.3 → 0.2.7

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

@@ -2,14 +2,29 @@ import fs from "node:fs"
 import path from "node:path"
 
 const LOG_FILE = ".agents/session-log.json"
+const SPAWN_MATCH_WINDOW_MS = 15000
+const DEBUG = process.env.SESSION_LOG_DEBUG === "true"
 
-// Per-session state: editCount and loaded skills
+// Per-session state
 const sessionState = new Map()
 
+// Lead session -> current team name
+const leadTeamBySession = new Map()
+
+// Pending spawn records waiting for a session.created match
+const pendingSpawns = []
+
+// Team -> completed session snapshots
+const completedByTeam = new Map()
+
 function ts() {
   return new Date().toISOString()
 }
 
+function nowMs() {
+  return Date.now()
+}
+
 function appendEntry(directory, entry) {
   const logPath = path.join(directory, LOG_FILE)
   const dir = path.dirname(logPath)
@@ -40,35 +55,148 @@ function addSkillToState(state, skillName) {
   return true
 }
 
-function buildTeamSkillsSummary() {
+function toNum(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v
+  if (typeof v === "string" && v.trim() !== "" && !Number.isNaN(Number(v))) return Number(v)
+  return null
+}
+
+function extractReportedTokens(obj) {
+  const out = { input: 0, output: 0, total: 0, found: false }
+  const visited = new Set()
+
+  function walk(node) {
+    if (!node || typeof node !== "object") return
+    if (visited.has(node)) return
+    visited.add(node)
+
+    for (const [k, v] of Object.entries(node)) {
+      const key = String(k).toLowerCase()
+      const n = toNum(v)
+
+      if (n !== null) {
+        if ((key.includes("input") || key.includes("prompt")) && key.includes("token")) {
+          out.input += n
+          out.found = true
+        } else if ((key.includes("output") || key.includes("completion")) && key.includes("token")) {
+          out.output += n
+          out.found = true
+        } else if (key.includes("total") && key.includes("token")) {
+          out.total += n
+          out.found = true
+        }
+      }
+
+      if (v && typeof v === "object") walk(v)
+    }
+  }
+
+  walk(obj)
+  return out
+}
+
+function estimateTokens(state) {
+  const inTokens = Math.ceil((state.charIn || 0) / 4)
+  const outTokens = Math.ceil((state.charOut || 0) / 4)
+  const base = inTokens + outTokens + Math.max(0, (state.toolCalls || 0) * 20)
+  const low = Math.max(0, Math.floor(base * 0.7))
+  const high = Math.max(low, Math.ceil(base * 1.4))
+  return { low, high }
+}
+
+function usagePayload(state) {
+  const est = estimateTokens(state)
+  const reportedIn = state.reportedInputTokens || 0
+  const reportedOut = state.reportedOutputTokens || 0
+  const reportedTotalDirect = state.reportedTotalTokens || 0
+  const reportedTotalDerived = reportedIn + reportedOut
+  const reportedTotal = reportedTotalDirect || reportedTotalDerived || 0
+
+  let method = "heuristic"
+  if (reportedTotal > 0 && (est.low > 0 || est.high > 0)) method = "mixed"
+  else if (reportedTotal > 0) method = "reported"
+
+  return {
+    inputTokensReported: reportedIn || null,
+    outputTokensReported: reportedOut || null,
+    totalTokensReported: reportedTotal || null,
+    tokenEstimateLow: est.low,
+    tokenEstimateHigh: est.high,
+    method,
+  }
+}
+
+function buildCompletedSnapshot(state, sessionId) {
+  return {
+    sessionId,
+    agent: state.agentName,
+    member: state.member || null,
+    agentType: state.agentType || null,
+    team: state.teamName || null,
+    skills: Array.from(state.skills || []).sort(),
+    usage: usagePayload(state),
+    filesEdited: state.editCount || 0,
+  }
+}
+
+function buildTeamSkillsSummary(teamName) {
+  const rows = completedByTeam.get(teamName) || []
   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)
+  for (const row of rows) {
+    const key = row.member || row.agent || "unknown"
+    if (!byAgent[key]) byAgent[key] = { agentType: row.agentType || null, skills: new Set() }
+    for (const s of row.skills || []) byAgent[key].skills.add(s)
   }
+  const out = {}
+  for (const [k, v] of Object.entries(byAgent)) {
+    out[k] = {
+      agentType: v.agentType,
+      skills: Array.from(v.skills).sort(),
+    }
+  }
+  return out
+}
 
-  const summary = {}
-  for (const [agent, skills] of Object.entries(byAgent)) {
-    summary[agent] = Array.from(skills).sort()
+function trackCompletedByTeam(snapshot) {
+  if (!snapshot.team) return
+  if (!completedByTeam.has(snapshot.team)) completedByTeam.set(snapshot.team, [])
+  completedByTeam.get(snapshot.team).push(snapshot)
+}
+
+function enqueuePendingSpawn(leadSessionId, args) {
+  pendingSpawns.push({
+    leadSessionId,
+    at: nowMs(),
+    member: args?.name || null,
+    agentType: args?.agent || null,
+    teamName: leadTeamBySession.get(leadSessionId) || null,
+  })
+}
+
+function matchPendingSpawn() {
+  const now = nowMs()
+  // Drop expired pending spawns first
+  for (let i = pendingSpawns.length - 1; i >= 0; i--) {
+    if (now - pendingSpawns[i].at > SPAWN_MATCH_WINDOW_MS) pendingSpawns.splice(i, 1)
   }
-  return summary
+  if (pendingSpawns.length === 0) return null
+  return pendingSpawns.shift()
 }
 
-// Maps ensemble tool name → function that extracts the log entry fields from args
+// Maps ensemble tool name -> function that extracts log entry fields from args
 const ENSEMBLE_TOOL_HANDLERS = {
-  team_create:         (args) => ({ action: "team-created",        team: args.name }),
-  team_spawn:          (args) => ({ action: "teammate-spawned",    name: args.name, agentType: args.agent }),
-  team_shutdown:       (args) => ({ action: "teammate-shutdown",   name: args.name }),
-  team_merge:          (args) => ({ action: "teammate-merged",     name: args.name }),
-  team_cleanup:        ()     => ({ action: "team-cleanup" }),
-  team_status:         ()     => ({ action: "team-status-checked" }),
-  team_results:        (args) => ({ action: "team-results-read",   from: args.from }),
-  team_message:        (args) => ({ action: "team-message",        to: args.to ?? "lead", preview: String(args.text ?? "").slice(0, 120) }),
-  team_broadcast:      (args) => ({ action: "team-broadcast",      preview: String(args.text ?? "").slice(0, 120) }),
-  team_tasks_add:      (args) => ({ action: "tasks-added",         count: Array.isArray(args.tasks) ? args.tasks.length : "?" }),
-  team_tasks_complete: (args) => ({ action: "task-completed",      taskId: args.task_id }),
-  team_claim:          (args) => ({ action: "task-claimed",        taskId: args.task_id }),
+  team_create:         (args) => ({ action: "team-created", team: args.name }),
+  team_spawn:          (args) => ({ action: "teammate-spawned", name: args.name, agentType: args.agent }),
+  team_shutdown:       (args) => ({ action: "teammate-shutdown", name: args.name }),
+  team_merge:          (args) => ({ action: "teammate-merged", name: args.name }),
+  team_cleanup:        () => ({ action: "team-cleanup" }),
+  team_status:         () => ({ action: "team-status-checked" }),
+  team_results:        (args) => ({ action: "team-results-read", from: args.from }),
+  team_message:        (args) => ({ action: "team-message", to: args.to ?? "lead", preview: String(args.text ?? "").slice(0, 120) }),
+  team_broadcast:      (args) => ({ action: "team-broadcast", preview: String(args.text ?? "").slice(0, 120) }),
+  team_tasks_add:      (args) => ({ action: "tasks-added", count: Array.isArray(args.tasks) ? args.tasks.length : "?" }),
+  team_tasks_complete: (args) => ({ action: "task-completed", taskId: args.task_id }),
+  team_claim:          (args) => ({ action: "task-claimed", taskId: args.task_id }),
 }
 
 export const SessionLogPlugin = async ({ client, directory }) => {
@@ -81,10 +209,35 @@ export const SessionLogPlugin = async ({ client, directory }) => {
 
           const res = await client.session.get({ path: { id: sessionId } })
           const session = res?.data
-          const agentName = resolveAgentName(session)
+          const fallbackAgent = resolveAgentName(session)
+          const spawnMatch = matchPendingSpawn()
+
+          const state = {
+            agentName: spawnMatch?.member || fallbackAgent,
+            member: spawnMatch?.member || null,
+            agentType: spawnMatch?.agentType || null,
+            teamName: spawnMatch?.teamName || null,
+            editCount: 0,
+            skills: new Set(),
+            startedAtMs: nowMs(),
+            toolCalls: 0,
+            charIn: 0,
+            charOut: 0,
+            reportedInputTokens: 0,
+            reportedOutputTokens: 0,
+            reportedTotalTokens: 0,
+          }
 
-          sessionState.set(sessionId, { agentName, editCount: 0, skills: new Set() })
-          appendEntry(directory, { ts: ts(), agent: agentName, action: "started", sessionId })
+          sessionState.set(sessionId, state)
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            member: state.member,
+            agentType: state.agentType,
+            team: state.teamName,
+            action: "started",
+            sessionId,
+          })
         }
 
         if (event?.type === "file.edited") {
@@ -100,9 +253,21 @@ export const SessionLogPlugin = async ({ client, directory }) => {
           const state = sessionState.get(sessionId)
           if (!state) return
 
-          const { agentName, editCount } = state
-          const skills = Array.from(state.skills ?? []).sort()
-          appendEntry(directory, { ts: ts(), agent: agentName, action: "completed", filesEdited: editCount, skills })
+          const skills = Array.from(state.skills || []).sort()
+          const usage = usagePayload(state)
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            member: state.member,
+            agentType: state.agentType,
+            team: state.teamName,
+            action: "completed",
+            filesEdited: state.editCount,
+            skills,
+            usage,
+          })
+
+          trackCompletedByTeam(buildCompletedSnapshot(state, sessionId))
           sessionState.delete(sessionId)
         }
       } catch (_) {}
@@ -117,13 +282,49 @@ export const SessionLogPlugin = async ({ client, directory }) => {
         if (!state) return
 
         const tool = input?.tool
+        const args = input?.args ?? {}
+
+        state.toolCalls++
+        state.charIn += JSON.stringify(args).length
+        state.charOut += JSON.stringify(output ?? {}).length
+
+        const reportedIn = extractReportedTokens(input)
+        const reportedOut = extractReportedTokens(output)
+        if (reportedIn.found) {
+          state.reportedInputTokens += reportedIn.input
+          state.reportedOutputTokens += reportedIn.output
+          state.reportedTotalTokens += reportedIn.total
+        }
+        if (reportedOut.found) {
+          state.reportedInputTokens += reportedOut.input
+          state.reportedOutputTokens += reportedOut.output
+          state.reportedTotalTokens += reportedOut.total
+        }
+
+        if (DEBUG && !reportedIn.found && !reportedOut.found && tool !== "read") {
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            action: "debug-no-token-metrics",
+            tool,
+          })
+        }
 
         // 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" })
+            appendEntry(directory, {
+              ts: ts(),
+              agent: state.agentName,
+              member: state.member,
+              agentType: state.agentType,
+              team: state.teamName,
+              action: "skill-loaded",
+              skill: skillName,
+              source: "skill-tool",
+            })
           }
           return
         }
@@ -136,23 +337,53 @@ export const SessionLogPlugin = async ({ client, directory }) => {
             const skillName = match[1]
             const added = addSkillToState(state, skillName)
             if (added) {
-              appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName, source: "read-skill-file" })
+              appendEntry(directory, {
+                ts: ts(),
+                agent: state.agentName,
+                member: state.member,
+                agentType: state.agentType,
+                team: state.teamName,
+                action: "skill-loaded",
+                skill: skillName,
+                source: "read-skill-file",
+              })
             }
           }
           return
         }
 
-        const args = input?.args ?? {}
-
         // Track ensemble tool calls
         const ensembleHandler = ENSEMBLE_TOOL_HANDLERS[tool]
         if (!ensembleHandler) return
 
-        const entry = { ts: ts(), agent: state.agentName, ...ensembleHandler(args) }
+        const entry = {
+          ts: ts(),
+          agent: state.agentName,
+          member: state.member,
+          agentType: state.agentType,
+          team: state.teamName,
+          ...ensembleHandler(args),
+        }
         appendEntry(directory, entry)
 
+        if (tool === "team_create") {
+          leadTeamBySession.set(sessionId, args?.name || null)
+          state.teamName = args?.name || state.teamName
+        }
+
+        if (tool === "team_spawn") {
+          enqueuePendingSpawn(sessionId, args)
+        }
+
         if (tool === "team_cleanup") {
-          appendEntry(directory, { ts: ts(), agent: state.agentName, action: "team-skills-summary", byAgent: buildTeamSkillsSummary() })
+          const teamName = state.teamName || leadTeamBySession.get(sessionId)
+          appendEntry(directory, {
+            ts: ts(),
+            agent: state.agentName,
+            action: "team-skills-summary",
+            team: teamName || null,
+            byAgent: teamName ? buildTeamSkillsSummary(teamName) : {},
+          })
         }
       } 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"
 ```
@@ -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.3",
+  "version": "0.2.7",
   "description": "Prepare any brownfield codebase for AI agent workflows using OpenCode, OpenSpec, and ensemble orchestration.",
   "keywords": [
     "opencode",

package/src/index.js

@@ -11,8 +11,9 @@ 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()
@@ -83,16 +84,24 @@ try {
   await initOpenspec()
 
   // 8. Install skills
-  await chooseSkillsProvider()
+  const skillsSelection = await chooseSkillsProvider()
 
   // 9. Choose models
-  await chooseModels()
+  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 = [

package/src/steps/choose-models.js

@@ -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-skills-provider.js

@@ -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/copy-content.js

@@ -7,6 +7,66 @@ 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 6, Copying opencode-onboard files')
 
@@ -20,6 +80,7 @@ export async function copyContentStep(platform, ctx = {}) {
       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

@@ -73,11 +73,17 @@ const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
    **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**
 
@@ -120,6 +126,7 @@ const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 - 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

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}`)
+  }
+}