opencode-onboard 0.5.1 → 0.5.3

package/content/.opencode/commands/opsx-apply.md

@@ -122,9 +122,16 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
        - 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 `.opencode/agents/`
-
-       REQUIRED assignment algorithm (do not skip):
+        - never spawn an engineer name that is not present in `.opencode/agents/`
+
+        **Model resolution for spawned agents (do not skip):**
+        Before each `team_spawn`, resolve the model for that agent using this priority:
+        1. **Agent file frontmatter** — Read `.opencode/agents/<engineer-file>` and check for a `model:` field in the YAML frontmatter. This is the user's explicit choice for this specific agent.
+        2. **`ensemble.json` `modelsByAgent`** — Read `.opencode/ensemble.json`. If `modelsByAgent` contains a key matching this agent's role (build agents → `build`, devops-manager → `explore`), use that value.
+        3. **Active chat model** — Fall back to the model currently running this conversation (your own model).
+        Never hardcode a model ID. Never skip this resolution. Log the result: `[model: <id> ← <source: agent frontmatter / ensemble.json modelsByAgent / active chat>]`
+
+        REQUIRED assignment algorithm (do not skip):
        1. Build candidate list from `.opencode/agents/*.md` excluding `devops-manager`.
        2. Classify each task by domain using task text (api/backend, ui/frontend, infra/devops, testing/qa).
        3. For each task, score every candidate agent:
@@ -174,13 +181,13 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
        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.
 
-       Spawn sequentially, waiting for each result:
-       ```
-       team_spawn name:"ui1" agent:"frontend-engineer" prompt:"..."
-       (wait for result)
-       team_spawn name:"api1" agent:"backend-engineer" prompt:"..."
-       (wait for result)
-       ```
+        Spawn sequentially, waiting for each result:
+        ```
+        team_spawn name:"ui1" agent:"frontend-engineer" model:"<resolved-model>" prompt:"..."
+        (wait for result)
+        team_spawn name:"api1" agent:"backend-engineer" model:"<resolved-model>" prompt:"..."
+        (wait for result)
+        ```
        Replace example agent names with REAL engineers that exist in this project.
 
        Then send each spawned worker a short start message that repeats their exact task IDs if needed:
@@ -226,7 +233,7 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
 
    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:"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>"
+   team_spawn name:"verify" agent:"<real-verifier-engineer>" worktree:false model:"<resolved-model>" 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)
 
@@ -253,9 +260,10 @@ Implement tasks from an OpenSpec change using the ensemble agent 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 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 call team_spawn without a resolved `model:` field; always pass the model resolved from the priority chain
+- 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 edit files between team_spawn and team_merge, team_merge blocks on overlapping local changes
 - 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

package/content/.opencode/skills/openspec-apply-change/SKILL.md

@@ -128,9 +128,16 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
        - 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 `.opencode/agents/`
+        - never spawn an engineer name that is not present in `.opencode/agents/`
 
-       REQUIRED assignment algorithm (do not skip):
+        **Model resolution for spawned agents (do not skip):**
+        Before each `team_spawn`, resolve the model for that agent using this priority:
+        1. **Agent file frontmatter** — Read `.opencode/agents/<engineer-file>` and check for a `model:` field in the YAML frontmatter. This is the user's explicit choice for this specific agent.
+        2. **`ensemble.json` `modelsByAgent`** — Read `.opencode/ensemble.json`. If `modelsByAgent` contains a key matching this agent's role (build agents → `build`, devops-manager → `explore`), use that value.
+        3. **Active chat model** — Fall back to the model currently running this conversation (your own model).
+        Never hardcode a model ID. Never skip this resolution. Log the result: `[model: <id> ← <source: agent frontmatter / ensemble.json modelsByAgent / active chat>]`
+
+        REQUIRED assignment algorithm (do not skip):
        1. Build candidate list from `.opencode/agents/*.md` excluding `devops-manager`.
        2. Classify each task by domain using task text (api/backend, ui/frontend, infra/devops, testing/qa).
        3. For each task, score every candidate agent:
@@ -181,13 +188,13 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
        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:"api1" agent:"backend-engineer" prompt:"..."
-       (wait for result)
-       ```
+        Spawn sequentially, waiting for each result:
+        ```
+        team_spawn name:"ui1" agent:"frontend-engineer" model:"<resolved-model>" prompt:"..."
+        (wait for result)
+        team_spawn name:"api1" agent:"backend-engineer" model:"<resolved-model>" prompt:"..."
+        (wait for result)
+        ```
        Replace example agent names with REAL engineers that exist in this project.
 
        Then send each spawned worker a short start message that repeats their exact task IDs if needed:
@@ -232,7 +239,7 @@ Implement tasks from an OpenSpec change using the ensemble agent team.
 
    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:"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>"
+   team_spawn name:"verify" agent:"<real-verifier-engineer>" worktree:false model:"<resolved-model>" 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)
 
@@ -259,6 +266,7 @@ Implement tasks from an OpenSpec change using the ensemble agent 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 without a resolved `model:` field; always pass the model resolved from the priority chain
 - 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

package/content/AGENTS.md

@@ -248,8 +248,9 @@ Core tools used in this workflow:
 
 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
+2. Resolve a new model using the model resolution priority (agent file frontmatter → `ensemble.json` `modelsByAgent` → active chat model). Avoid the model that hit the rate limit.
+3. `team_spawn` same member/task with the resolved model
+4. `team_message` start instruction with the exact next task ID
 
 ---
 

package/package.json

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

package/src/commands/shared.js

@@ -1,3 +1,4 @@
+import { execa } from 'execa'
 import fse from 'fs-extra'
 import path from 'node:path'
 
@@ -10,3 +11,15 @@ export async function readOnboardConfig() {
     return null
   }
 }
+
+export async function ensureGitLongpaths(cwd = process.cwd()) {
+  try {
+    const repoCheck = await execa('git', ['rev-parse', '--is-inside-work-tree'], { cwd, reject: false })
+    if (repoCheck.exitCode !== 0 || repoCheck.stdout.trim() !== 'true') return false
+
+    const configResult = await execa('git', ['config', 'core.longpaths', 'true'], { cwd, reject: false })
+    return configResult.exitCode === 0
+  } catch {
+    return false
+  }
+}

package/src/commands/shared.test.js

@@ -1,13 +1,20 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+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 { readOnboardConfig } from './shared.js'
+
+vi.mock('execa', () => ({
+  execa: vi.fn(),
+}))
+
+import { execa } from 'execa'
+import { ensureGitLongpaths, readOnboardConfig } from './shared.js'
 
 describe('readOnboardConfig()', () => {
   let tmpDir, originalCwd
 
   beforeEach(() => {
+    vi.clearAllMocks()
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'shared-test-'))
     originalCwd = process.cwd()
     process.chdir(tmpDir)
@@ -54,3 +61,36 @@ describe('readOnboardConfig()', () => {
     expect(result).toBeNull()
   })
 })
+
+describe('ensureGitLongpaths()', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('configures core.longpaths in a git repository', async () => {
+    execa
+      .mockResolvedValueOnce({ exitCode: 0, stdout: 'true' })
+      .mockResolvedValueOnce({ exitCode: 0, stdout: '', stderr: '' })
+
+    const result = await ensureGitLongpaths('C:/repo')
+
+    expect(result).toBe(true)
+    expect(execa).toHaveBeenNthCalledWith(1, 'git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: 'C:/repo',
+      reject: false,
+    })
+    expect(execa).toHaveBeenNthCalledWith(2, 'git', ['config', 'core.longpaths', 'true'], {
+      cwd: 'C:/repo',
+      reject: false,
+    })
+  })
+
+  it('skips configuration outside a git repository', async () => {
+    execa.mockResolvedValueOnce({ exitCode: 1, stdout: '', stderr: '' })
+
+    const result = await ensureGitLongpaths('C:/not-a-repo')
+
+    expect(result).toBe(false)
+    expect(execa).toHaveBeenCalledTimes(1)
+  })
+})

package/src/commands/wizard.js

@@ -1,7 +1,8 @@
 import { select as wizardSelect } from '@inquirer/prompts'
-import chalk from 'chalk'
-import { chooseSourceScope } from '../steps/source/index.js'
-import { cleanAiFiles } from '../steps/clean/index.js'
+import chalk from 'chalk'
+import { ensureGitLongpaths } from './shared.js'
+import { chooseSourceScope } from '../steps/source/index.js'
+import { cleanAiFiles } from '../steps/clean/index.js'
 import { choosePlatform } from '../steps/platform/index.js'
 import { copyContentStep } from '../steps/copy/index.js'
 import { initOpenspec } from '../steps/openspec/index.js'
@@ -37,7 +38,7 @@ export async function runWizard(version) {
   console.log()
 
   // Only wait for Enter in a real interactive TTY
-  if (process.stdin.isTTY) {
+  if (process.stdin.isTTY) {
     console.log(chalk.bold('  Press Enter to begin...'))
     console.log()
     await new Promise(resolve => {
@@ -46,10 +47,13 @@ export async function runWizard(version) {
         process.stdin.pause()
         resolve()
       })
-    })
-  }
-
-  const scope = await chooseSourceScope()
+    })
+  }
+
+  const longpathsConfigured = await ensureGitLongpaths()
+  if (longpathsConfigured) console.log(chalk.dim('  Git long paths enabled for this repository.'))
+
+  const scope = await chooseSourceScope()
 
   const maxConcurrentAgents = await wizardSelect({
     message: 'Max concurrent agents:',

package/src/steps/metadata/index.js

@@ -24,8 +24,15 @@ export async function writeOnboardConfig(data) {
   const opencodeVersion = await detectOpencodeVersion()
   const cwd = data.cwd ?? process.cwd()
   const target = path.join(cwd, '.opencode', 'opencode-onboard.json')
-
-  const payload = {
+  const selectedModels = Object.fromEntries(
+    Object.entries({
+      plan: data.planModel,
+      build: data.buildModel,
+      fast: data.fastModel,
+    }).filter(([, value]) => value)
+  )
+
+  const payload = {
     schema: 1,
     generatedAt: new Date().toISOString(),
     onboardVersion,
@@ -39,17 +46,13 @@ export async function writeOnboardConfig(data) {
         design: !!data.hasDesign,
         architecture: !!data.hasArchitecture,
         openspec: !!data.hasOpenspec,
-      },
-      openspec: data.openspec,
-      additionalSkillsProvider: data.additionalSkillsProvider,
-      models: {
-        plan: data.planModel,
-        build: data.buildModel,
-        fast: data.fastModel,
-      },
-      optionalTools: data.optionalTools ?? null,
-      cavemanGuidance: data.cavemanGuidance ?? null,
-    },
+      },
+      openspec: data.openspec,
+      additionalSkillsProvider: data.additionalSkillsProvider,
+      ...(Object.keys(selectedModels).length > 0 ? { models: selectedModels } : {}),
+      optionalTools: data.optionalTools ?? null,
+      cavemanGuidance: data.cavemanGuidance ?? null,
+    },
     note: 'Informational file only. Editing this file does not change runtime behavior.',
   }
 

package/src/steps/metadata/metadata.test.js

@@ -104,4 +104,14 @@ describe('writeOnboardConfig()', () => {
     const payload = call[1]
     expect(payload.wizard.platform).toBe('none')
   })
+
+  it('omits model metadata when no model is selected', async () => {
+    execa.mockResolvedValue({ exitCode: 0, stdout: '1', stderr: '' })
+
+    await writeOnboardConfig({ platform: 'github', sourceMode: 'current', sourceRoots: [], cwd: tmpDir })
+
+    const call = fse.writeJson.mock.calls[0]
+    const payload = call[1]
+    expect(payload.wizard.models).toBeUndefined()
+  })
 })

package/src/steps/models/format.js

@@ -23,8 +23,8 @@ function formatPrice(price) {
   return `$${price}/M`;
 }
 
-export function buildDisplayModels(rawModels) {
-  return rawModels.map(m => {
+export function buildDisplayModels(rawModels) {
+  return rawModels.map(m => {
     const priceStr = formatPrice(m.cost);
     const canonicalNote = m.canonicalCost !== undefined
       ? ` · official price: ${formatPrice(m.canonicalCost)}/M`
@@ -35,27 +35,37 @@ export function buildDisplayModels(rawModels) {
       label: `${m.name}${costTierDisplay(m.cost, m.canonicalCost)}, ${m.id}`,
       description: `${priceStr}${canonicalNote} · context: ${context}`,
     };
-  });
-}
-
-export function pickModel(message, models) {
-  return search({
-    message,
-    source: (input) => {
-      const q = (input || '').toLowerCase();
-      const filtered = q
-        ? models.filter(m =>
-            m.label.toLowerCase().includes(q) ||
-            m.id.toLowerCase().includes(q)
-          )
-        : models;
-      return filtered.slice(0, 50).map(m => ({
-        name: m.label,
-        value: m.id,
-        description: m.description,
-      }));
-    },
-  });
-}
+  });
+}
+
+export function buildModelChoices(input, models) {
+  const q = (input || '').toLowerCase();
+  const filtered = q
+    ? models.filter(m =>
+        m.label.toLowerCase().includes(q) ||
+        m.id.toLowerCase().includes(q)
+      )
+    : models;
+
+  return [
+    {
+      name: 'None',
+      value: null,
+      description: 'Leave this model unset',
+    },
+    ...filtered.slice(0, 50).map(m => ({
+      name: m.label,
+      value: m.id,
+      description: m.description,
+    })),
+  ];
+}
+
+export function pickModel(message, models) {
+  return search({
+    message,
+    source: input => buildModelChoices(input, models),
+  });
+}
 
 export { modelsPreset };

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { buildDisplayModels } from './format.js'
+import { buildDisplayModels, buildModelChoices } from './format.js'
 
 describe('buildDisplayModels()', () => {
   it('adds cost tier label for cheap models', () => {
@@ -72,4 +72,30 @@ describe('buildDisplayModels()', () => {
     expect(result[1].id).toBe('cheap/model')
     expect(result[2].id).toBe('mid/model')
   })
-})
+
+  it('keeps None as the first choice with no search', () => {
+    const models = buildDisplayModels([
+      { id: 'openai/gpt-4.1', name: 'GPT-4.1', cost: 2, context: 128000 },
+    ])
+
+    const result = buildModelChoices('', models)
+
+    expect(result[0]).toEqual({
+      name: 'None',
+      value: null,
+      description: 'Leave this model unset',
+    })
+  })
+
+  it('keeps None as the first choice during search', () => {
+    const models = buildDisplayModels([
+      { id: 'openai/gpt-4.1', name: 'GPT-4.1', cost: 2, context: 128000 },
+      { id: 'anthropic/claude-3-5-sonnet', name: 'Claude 3.5 Sonnet', cost: 3, context: 200000 },
+    ])
+
+    const result = buildModelChoices('claude', models)
+
+    expect(result[0].name).toBe('None')
+    expect(result[1].value).toBe('anthropic/claude-3-5-sonnet')
+  })
+})

package/src/steps/models/write.js

@@ -2,12 +2,20 @@ import fse from 'fs-extra'
 import path from 'path'
 import { success } from '../../utils/exec.js'
 
+function updateFrontmatterModel(content, modelId) {
+  return content.replace(
+    /^(---\n)([\s\S]*?)(\n---)/m,
+    (_, start, body, end) => {
+      const withoutModel = body.replace(/^model:\s.*\n?/m, '').replace(/\n+$/, '')
+      const nextBody = modelId ? `${withoutModel}\nmodel: ${modelId}` : withoutModel
+      return `${start}${nextBody}${end}`
+    }
+  )
+}
+
 export async function writeModelToAgent(agentFile, modelId) {
   const content = await fse.readFile(agentFile, 'utf-8');
-  const updated = content.replace(
-    /^(---\n[\s\S]*?)\n---/m,
-    `$1\nmodel: ${modelId}\n---`
-  );
+  const updated = updateFrontmatterModel(content, modelId)
   await fse.writeFile(agentFile, updated, 'utf-8');
 }
 
@@ -29,7 +37,7 @@ export async function writeModelsToConfigs({ planModel, buildModel, fastModel, a
     const file = path.join(agentsDir, `${name}.md`);
     if (await fse.pathExists(file)) {
       await writeModelToAgent(file, buildModel);
-      success(`${name} → ${buildModel}`);
+      if (buildModel) success(`${name} → ${buildModel}`);
     }
   }
 
@@ -37,31 +45,37 @@ export async function writeModelsToConfigs({ planModel, buildModel, fastModel, a
     const file = path.join(agentsDir, `${name}.md`);
     if (await fse.pathExists(file)) {
       await writeModelToAgent(file, fastModel);
-      success(`${name} → ${fastModel}`);
+      if (fastModel) success(`${name} → ${fastModel}`);
     }
   }
 
   const opencodeJsonPath = path.join(cwd, '.opencode', 'opencode.json');
   if (await fse.pathExists(opencodeJsonPath)) {
     const config = await fse.readJson(opencodeJsonPath);
-    config.model = buildModel;
+    if (buildModel) config.model = buildModel;
+    else delete config.model;
     await fse.writeJson(opencodeJsonPath, config, { spaces: 2 });
-    success(`default model -> ${buildModel} (written to .opencode/opencode.json)`);
+    if (buildModel) success(`default model -> ${buildModel} (written to .opencode/opencode.json)`);
   }
 
   const ensembleJsonPath = path.join(cwd, '.opencode', 'ensemble.json');
   if (await fse.pathExists(ensembleJsonPath)) {
     const ensemble = await fse.readJson(ensembleJsonPath);
     delete ensemble.defaultModel;
-    ensemble.modelsByAgent = {
-      ...ensemble.modelsByAgent,
-      plan: planModel,
-      build: buildModel,
-      explore: fastModel,
-    };
+    const modelsByAgent = { ...ensemble.modelsByAgent }
+    if (planModel) modelsByAgent.plan = planModel
+    else delete modelsByAgent.plan
+    if (buildModel) modelsByAgent.build = buildModel
+    else delete modelsByAgent.build
+    if (fastModel) modelsByAgent.explore = fastModel
+    else delete modelsByAgent.explore
+
+    if (Object.keys(modelsByAgent).length > 0) ensemble.modelsByAgent = modelsByAgent
+    else delete ensemble.modelsByAgent
+
     await fse.writeJson(ensembleJsonPath, ensemble, { spaces: 2 });
-    success(`plan model -> ${planModel} (written to .opencode/ensemble.json)`);
-    success(`build model -> ${buildModel} (written to .opencode/ensemble.json)`);
-    success(`fast model -> ${fastModel} (written to .opencode/ensemble.json)`);
+    if (planModel) success(`plan model -> ${planModel} (written to .opencode/ensemble.json)`);
+    if (buildModel) success(`build model -> ${buildModel} (written to .opencode/ensemble.json)`);
+    if (fastModel) success(`fast model -> ${fastModel} (written to .opencode/ensemble.json)`);
   }
 }

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

@@ -38,7 +38,7 @@ description: A test agent
     expect(updated).toContain('model: anthropic/claude-3-sonnet')
   })
 
-  it('preserves existing frontmatter fields', async () => {
+  it('preserves existing frontmatter fields', async () => {
     const filePath = path.join(tmpDir, 'test-agent.md')
     const original = `---
 name: Test Agent
@@ -54,10 +54,28 @@ custom_field: custom_value
     const updated = fs.readFileSync(filePath, 'utf-8')
     expect(updated).toContain('name: Test Agent')
     expect(updated).toContain('description: A test agent')
-    expect(updated).toContain('custom_field: custom_value')
-    expect(updated).toContain('model: test/model')
-  })
-})
+    expect(updated).toContain('custom_field: custom_value')
+    expect(updated).toContain('model: test/model')
+  })
+
+  it('removes model field when no model is selected', async () => {
+    const filePath = path.join(tmpDir, 'test-agent.md')
+    const original = `---
+name: Test Agent
+model: existing/model
+description: A test agent
+---
+
+# Test Agent`
+    fs.writeFileSync(filePath, original, 'utf-8')
+
+    await writeModelToAgent(filePath, null)
+
+    const updated = fs.readFileSync(filePath, 'utf-8')
+    expect(updated).not.toContain('model:')
+    expect(updated).toContain('description: A test agent')
+  })
+})
 
 describe('writeModelsToConfigs()', () => {
   let tmpDir, agentsDir, opencodeJsonPath
@@ -115,4 +133,27 @@ describe('writeModelsToConfigs()', () => {
 
     expect(success).toHaveBeenCalled()
   })
+
+  it('removes model config entries when None is selected', async () => {
+    const agentFile = path.join(agentsDir, 'basic-engineer.md')
+    const ensembleJsonPath = path.join(tmpDir, '.opencode', 'ensemble.json')
+
+    fs.writeFileSync(agentFile, '---\nname: Basic\nmodel: existing/model\n---', 'utf-8')
+    fs.writeFileSync(opencodeJsonPath, JSON.stringify({ model: 'existing/model', theme: 'dark' }, null, 2), 'utf-8')
+    fs.writeFileSync(ensembleJsonPath, JSON.stringify({ modelsByAgent: { plan: 'a', build: 'b', explore: 'c', keep: 'yes' } }, null, 2), 'utf-8')
+
+    await writeModelsToConfigs({
+      planModel: null,
+      buildModel: null,
+      fastModel: null,
+      agentsDir,
+      cwd: tmpDir,
+      preset: { roles: { build: { agents: ['basic-engineer'] }, fast: { agents: [] } } },
+    })
+
+    expect(fs.readFileSync(agentFile, 'utf-8')).not.toContain('model:')
+    expect(JSON.parse(fs.readFileSync(opencodeJsonPath, 'utf-8'))).toEqual({ theme: 'dark' })
+    expect(JSON.parse(fs.readFileSync(ensembleJsonPath, 'utf-8'))).toEqual({ modelsByAgent: { keep: 'yes' } })
+    expect(success).not.toHaveBeenCalled()
+  })
 })

package/src/steps/openspec/ensemble.js

@@ -58,6 +58,13 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       - 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 \`.opencode/agents/\`
 
+      **Model resolution for spawned agents (do not skip):**
+      Before each \`team_spawn\`, resolve the model for that agent using this priority:
+      1. **Agent file frontmatter** — Read \`.opencode/agents/<engineer-file>\` and check for a \`model:\` field in the YAML frontmatter. This is the user's explicit choice for this specific agent.
+      2. **\`ensemble.json\` \`modelsByAgent\`** — Read \`.opencode/ensemble.json\`. If \`modelsByAgent\` contains a key matching this agent's role (build agents → \`build\`, devops-manager → \`explore\`), use that value.
+      3. **Active chat model** — Fall back to the model currently running this conversation (your own model).
+      Never hardcode a model ID. Never skip this resolution. Log the result: \`[model: <id> ← <source: agent frontmatter / ensemble.json modelsByAgent / active chat>]\`
+
       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:
@@ -91,9 +98,9 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 
       Spawn sequentially, waiting for each result:
       \`\`\`
-      team_spawn name:"ui1" agent:"frontend-engineer" prompt:"..."
+      team_spawn name:"ui1" agent:"frontend-engineer" model:"<resolved-model>" prompt:"..."
       (wait for result)
-      team_spawn name:"api1" agent:"backend-engineer" prompt:"..."
+      team_spawn name:"api1" agent:"backend-engineer" model:"<resolved-model>" prompt:"..."
       (wait for result)
       \`\`\`
       Replace example agent names with REAL engineers that exist in this project.
@@ -133,7 +140,7 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
       6. **If ALL agents are shut down and tasks remain unassigned** (new domain, dependencies unblocked):
           - Discover the remaining matching engineers from \`.opencode/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.
+      If a teammate reports rate-limit/quota/token exhaustion, immediately shutdown that teammate and respawn with a different model using the model resolution priority above.
 
       **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.
 
@@ -141,7 +148,7 @@ export const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 
    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:"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>"
+   team_spawn name:"verify" agent:"<real-verifier-engineer>" worktree:false model:"<resolved-model>" 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)
 
@@ -165,6 +172,7 @@ 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 without a resolved \`model:\` field; always pass the model resolved from the priority chain
 - 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