@plainconceptsplatform/agent-harness 3.8.2 → 3.9.0-alpha.1

package/README.md

@@ -89,7 +89,7 @@ Reach for individual steps when you want something narrower:
 
 > **Upgrading from `opencode-onboard` v1?** v2 renamed the config files and the skill prefix (`ob-` became `pc-`), and it does not migrate v1 projects. The CLI detects one and refuses to run rather than half-patching it. Re-onboard on a clean branch: remove `.opencode/` and `.agents/skills/ob-*`, then run the wizard again.
 
-> **Browser tooling changed in v2.4.** The `@different-ai/opencode-browser` plugin (and its Chrome extension) was replaced by [`agent-browser`](https://github.com/vercel-labs/agent-browser), wired in as an MCP server in `opencode.jsonc`. Running `update` strips the old plugin entry, adds the MCP block, and installs the new binary — no manual unloading of the extension is needed, though you can remove it from `chrome://extensions` yourself. Skills you wrote that call `browser_*` tools directly must switch to the `agent-browser` CLI or the `agent_browser_*` MCP tools. Backlog-browser users: agent-browser runs its own Chrome, so log in once per project using the `--session backlog --restore` flow described in `pc-userstory-browser`.
+> **Browser tooling changed in v2.5.** `agent-browser` (which launched its own isolated Chrome for Testing) was replaced by [`browse`](https://opencode.ai/product/browse), the OpenCode MCP server that drives the user's real Chrome-family browser with their logins, tabs, cookies, and extensions. Agent tabs open in the background in collapsed groups; when only a person can proceed (login, 2FA, captcha, payment), browse hands the tab back and continues once the user clicks Continue. Running `update` replaces the `agent-browser` MCP server entry with `browse`, installs the new CLI, and runs `browse install` which opens the Chrome Web Store for the extension and pairs it. Skills you wrote that call `agent-browser` CLI commands or `agent_browser_*` MCP tools must switch to the `browse` CLI or the `browse.execute` / `browse.session_*` MCP tools. Backlog-browser users: browse uses your real browser, so work-item pages behind your own login are already authenticated — no separate login session is needed.
 
 ---
 
@@ -107,7 +107,7 @@ The first run is a 10-step wizard. It keeps the current step visible, plus the l
 | **6. Initialize OpenSpec** | Runs `npx @fission-ai/openspec init` silently for structured change management |
 | **7. Choose models** | Fetches live model list from [models.dev](https://models.dev), lets you pick plan, build, and fast models with cost indicators and canonical pricing |
 | **8. Token optimization tools** | Optional and recommended. One checklist step for RTK check, opencode-quota setup, Simple English install, codegraph install, agentmemory install, humanizer install, and token-optimization rule injection into guardrails |
-| **9. Install browser tooling** | Installs `agent-browser` globally and downloads its Chrome for Testing binary |
+| **9. Install browser tooling** | Installs `@opencode/browse` globally and pairs it with the user's real browser via the browse extension |
 | **10. Write onboarding metadata** | Writes `.opencode/harness.json` with selected setup details |
 
 When it finishes, open OpenCode in your project and type:
@@ -179,7 +179,9 @@ If you choose backlog platform `None`, no userstory skills are injected into the
 Current loading model:
 
 - `pc-guardrails-generic` is mandatory baseline for every agent (git, secrets, quality rules, plus the engineer workflow)
+- `AGENTS.md` states the file paths to read before any edit, shell command or subagent spawn, so agents that do not discover `.agents/skills` natively (Claude Code reads `.claude/skills`) still load the guardrails
 - Baseline context rules and token-optimization guidance live in `AGENTS.md` (always in context), not in a skill
+- Humanizer and Simple English are read on demand before writing prose; they are not transitive requirements of the guardrails
 
 Default `fullstack-engineer` abilities:
 
@@ -200,7 +202,7 @@ Built-in skills (`pc-` prefix) shipped with agent-harness:
 | `pc-userstory-az` | Parse an Azure DevOps work item URL |
 | `pc-userstory-jira` | Parse a Jira issue URL via `acli` CLI |
 | `pc-userstory-browser` | Parse work item from any URL via browser automation (Linear, Trello, and so on) |
-| `browser-automation` | Browser control via `agent-browser` (localhost and browser backlog exception) |
+| `browser-automation` | Browser control via `browse` (user's real browser, localhost + external sites with handoffs) |
 | `pc-plan-explore` | Read-only exploration procedure behind `/plan-explore`; autonomous mode used by `/plan-goal` |
 | `pc-plan-propose` | Proposal + task-enrichment procedure behind `/plan-propose`; autonomous mode used by `/plan-goal` |
 | `pc-plan-apply` | Wave-implementation procedure behind `/plan-apply`; autonomous mode used by `/plan-goal` |
@@ -307,7 +309,7 @@ your-project/
 
 On OpenCode 2 the terminal client is configured globally (`~/.config/opencode/cli.json`), so the harness ships no project-local `tui.json`; the native session sidebar shows subagents without a sidecar panel.
 
-Platform skills ship as suffixed variants (`pc-userstory-gh`, `pc-userstory-az`, `pc-userstory-jira`, `pc-userstory-browser`) and the installer copies only the matching one, renamed to its generic name. Platform operations (ship, review, backlog) are injected directly into the `/ops-*` command files from `cli/fragments/ops-*/` during onboarding. Source-roots metadata lands in `.opencode/source-roots.json`. The always-shipped reminder plugin holds editing, shell and spawning until every ability under the agent's `## Abilities` is loaded, guardrails first, and re-arms after compaction. Token-optimization guidance is injected into `pc-guardrails-generic` marker blocks during onboarding.
+Platform skills ship as suffixed variants (`pc-userstory-gh`, `pc-userstory-az`, `pc-userstory-jira`, `pc-userstory-browser`) and the installer copies only the matching one, renamed to its generic name. Platform operations (ship, review, backlog) are injected directly into the `/ops-*` command files from `cli/fragments/ops-*/` during onboarding. Source-roots metadata lands in `.opencode/source-roots.json`. The always-shipped reminder plugin holds editing, shell and spawning until every ability under the agent's `## Abilities` is loaded, guardrails first, and re-arms after compaction. `AGENTS.md` names the guardrails files by path so the same contract survives in agents that only have a read tool. Token-optimization guidance is injected into `pc-guardrails-generic` marker blocks during onboarding; Humanizer and Simple English are named by path and loaded when prose is written, not held as transitive requirements.
 
 ---
 
@@ -505,7 +507,7 @@ Data the CLI reads lives in two places, split by kind:
 - `models.json` controls model role prompts and agent assignments
 - `optimization.json` controls RTK, quota, Simple English, codegraph, agentmemory, and humanizer checklist defaults
 - `quota.json` controls opencode-quota defaults
-- `browser.json` controls the agent-browser installer (npm package + Chrome setup)
+- `browser.json` controls the browse installer (npm package + browser extension pairing)
 
 **`cli/fragments/`** holds Markdown injected into the installed harness, one directory per marker family: `archive/`, `guardrails/`, `ops-backlog/`, `ops-review/`, `ops-ship/`. Each file is the platform-specific body that replaces a `<!-- PC-PLATFORM-*-START -->` block.
 

package/cli/commands/join.js

@@ -193,7 +193,7 @@ export async function runJoin() {
   await checkRtk({ skipHeader: true, skipPrompt: true })
 
   // Step 8: Browser automation
-  header('Step 8, Installing agent-browser')
+  header('Step 8, Installing browse')
   await installBrowser()
 
   // Step 9: Model tier guidance

package/cli/fragments/guardrails/humanizer.md

@@ -1,4 +1,4 @@
-## Humanizer (optimization skill)
+## Humanizer (before writing prose)
 
-- Load `skill("humanizer")` before writing prose (commit messages, PR descriptions, docs, proposals); unhumanized prose reads as machine-written. Editing, shell and spawning stay blocked until it is loaded (pc-system-reminders).
+- Before writing prose (commit messages, PR descriptions, docs, proposals), read `.agents/skills/humanizer/SKILL.md` and apply it; unhumanized prose reads as machine-written.
 - Never apply it to code, config files, or terminal output: prose only.

package/cli/fragments/guardrails/simple-english.md

@@ -1,4 +1,4 @@
-## Simple English (optimization skill)
+## Simple English (before writing prose)
 
-- Apply Simplified Technical English to all prose: `skill("simple-english")`. Editing, shell and spawning stay blocked until it is loaded (pc-system-reminders).
+- Before writing prose, read `.agents/skills/simple-english/SKILL.md` and apply Simplified Technical English.
 - Keep code blocks, identifiers, CLI commands, file paths, quoted errors, and product names exact.

package/cli/index.js

@@ -26,7 +26,7 @@ function printHelp(version) {
   console.log('  openspec        Run OpenSpec initialization step')
   console.log('  models          Run models selection step')
   console.log('  optimization    Run token optimization tools step')
-  console.log('  browser         Run agent-browser installer step')
+  console.log('  browser         Run browse installer step')
   console.log('  metadata        Write onboarding metadata step')
   console.log()
   console.log('Options:')

package/cli/presets/agents-content.json

@@ -28,7 +28,7 @@
     },
     "browser": {
       "workflow": "Any work item URL means run the pipeline, whichever tool it points at, unless the user asked for analysis or context only.\n\n- The URL: `pc-userstory` to open and read the page, `pc-plan-propose` for the plan, confirm, `pc-plan-apply` to build, then ship.\n- An existing OpenSpec change, plus any of `implement` / `start` / `go`: `pc-plan-apply`, then ship.\n\nBrowser is backlog-only: PR work runs on the repo platform in `platform.repo`.",
-      "skillsGuide": "### Backlog Platform: Others (Browser)\n- `pc-userstory` -> opens work item URLs via agent-browser, reads page content, creates OpenSpec changes. Load when a URL the user provides does not match GitHub/Azure/Jira CLI platforms.\n\n### Repo Platform\n- PR skills are loaded based on `platform.repo` (GitHub / Azure DevOps / GitLab)."
+      "skillsGuide": "### Backlog Platform: Others (Browser)\n- `pc-userstory` -> opens work item URLs via browse, reads page content, creates OpenSpec changes. Load when a URL the user provides does not match GitHub/Azure/Jira CLI platforms.\n\n### Repo Platform\n- PR skills are loaded based on `platform.repo` (GitHub / Azure DevOps / GitLab)."
     }
   }
 }

package/cli/presets/browser.json

@@ -1,10 +1,10 @@
 {
   "installer": {
     "command": "npm",
-    "args": ["install", "-g", "agent-browser@0.36.0"]
+    "args": ["install", "-g", "@opencode/browse@0.0.14"]
   },
-  "chromeSetup": {
-    "command": "agent-browser",
-    "args": ["install"]
+  "setup": {
+    "command": "browse",
+    "args": ["install", "--yes"]
   }
 }

package/cli/steps/browser/index.js

@@ -10,7 +10,7 @@ const BROWSER_PRESET_PATH = path.resolve(__dirname, '../../presets/browser.json'
 const browserPreset = await fse.readJson(BROWSER_PRESET_PATH)
 
 export async function installBrowser() {
-  header('Step 9, Installing agent-browser')
+  header('Step 9, Installing browse')
 
   try {
     const install = await execa(browserPreset.installer.command, browserPreset.installer.args, {
@@ -19,30 +19,34 @@ export async function installBrowser() {
     })
 
     if (install.exitCode !== 0) {
-      warn('agent-browser npm install exited with non-zero code')
+      warn('browse npm install exited with non-zero code')
       if (install.stderr) info(install.stderr)
       return
     }
-    success('agent-browser installed')
+    success('browse installed')
   } catch (err) {
-    error(`Failed to install agent-browser: ${err.message}`)
+    error(`Failed to install browse: ${err.message}`)
     return
   }
 
   try {
-    const chrome = await execa(browserPreset.chromeSetup.command, browserPreset.chromeSetup.args, {
+    const setup = await execa(browserPreset.setup.command, browserPreset.setup.args, {
       cwd: os.homedir(),
       reject: false,
+      timeout: 180000,
     })
 
-    if (chrome.exitCode === 0) {
-      success('agent-browser Chrome ready')
-      if (chrome.stdout) info(chrome.stdout.trim())
+    if (setup.exitCode === 0) {
+      success('browse paired with your browser')
+      if (setup.stdout) info(setup.stdout.trim())
     } else {
-      warn('agent-browser install (Chrome setup) exited with non-zero code')
-      if (chrome.stderr) info(chrome.stderr)
+      // browse install opens the Chrome Web Store and waits for the extension to connect.
+      // A non-zero exit often just means the user didn't finish pairing in time; browse is
+      // still installed and usable once they add the extension and run `browse pair`.
+      warn('browse setup did not complete — install the extension and run `browse pair`')
+      if (setup.stderr) info(setup.stderr)
     }
   } catch (err) {
-    error(`Failed to set up Chrome for agent-browser: ${err.message}`)
+    error(`Failed to set up browse: ${err.message}`)
   }
 }

package/cli/steps/copy/agents.js

@@ -47,9 +47,13 @@ const PLATFORM_WORKFLOW_START = '<!-- PC-PLATFORM-WORKFLOW-START -->'
 const PLATFORM_WORKFLOW_END = '<!-- PC-PLATFORM-WORKFLOW-END -->'
 const PLATFORM_SKILLS_GUIDE_START = '<!-- PC-PLATFORM-SKILLS-GUIDE-START -->'
 const PLATFORM_SKILLS_GUIDE_END = '<!-- PC-PLATFORM-SKILLS-GUIDE-END -->'
+const PLATFORM_SKILLS_START = '<!-- PC-PLATFORM-SKILLS-START -->'
+const PLATFORM_SKILLS_END = '<!-- PC-PLATFORM-SKILLS-END -->'
 const PLATFORM_CONTRACT_START = '<!-- PC-PLATFORM-CONTRACT-START -->'
 const PLATFORM_CONTRACT_END = '<!-- PC-PLATFORM-CONTRACT-END -->'
 
+const MANDATORY_SKILLS_BODY = 'Mandatory, before any edit, shell command or subagent spawn: read `.agents/skills/pc-guardrails-generic/SKILL.md`, then `.agents/skills/pc-guardrails-project/SKILL.md` if present. They are instructions, not references: a loaded skill may name further skills, and those load too before the work they cover.'
+
 function platformContent(platform, key) {
   const p = agentsContent.platform[platform] ?? agentsContent.platform.github
   return p[key] ?? ''
@@ -74,6 +78,17 @@ function replaceBetween(content, start, end, replacement) {
   return content.replace(pattern, () => (body ? `${start}\n${body}\n${end}` : `${start}\n${end}`))
 }
 
+// Reading the file works in every agent, not only the ones that discover
+// `.agents/skills` natively (Claude Code reads `.claude/skills`). Installs from
+// before this block have no marker pair and update never rewrites AGENTS.md, so
+// append a section then; the marker pair keeps later updates idempotent.
+function patchMandatorySkillsBlock(content) {
+  if (content.includes(PLATFORM_SKILLS_START)) {
+    return replaceBetween(content, PLATFORM_SKILLS_START, PLATFORM_SKILLS_END, MANDATORY_SKILLS_BODY)
+  }
+  return `${content.replace(/\s*$/, '')}\n\n## Mandatory skills\n\n${PLATFORM_SKILLS_START}\n${MANDATORY_SKILLS_BODY}\n${PLATFORM_SKILLS_END}\n`
+}
+
 export function reuseBlock(contract, templateSource = false) {
   const { docs = [], packages = [], names = [] } = contract?.reuse ?? {}
   if (!docs.length && !packages.length && !names.length) return ''
@@ -150,6 +165,7 @@ export async function patchAgentGuidance(backlogPlatform, repoPlatform, cwd = pr
     let content = await fse.readFile(agentsMdPath, 'utf-8')
     content = replaceBetween(content, PLATFORM_WORKFLOW_START, PLATFORM_WORKFLOW_END, mixedPlatformContent(backlogPlatform, repo, 'workflow'))
     content = replaceBetween(content, PLATFORM_SKILLS_GUIDE_START, PLATFORM_SKILLS_GUIDE_END, mixedPlatformContent(backlogPlatform, repo, 'skillsGuide'))
+    content = patchMandatorySkillsBlock(content)
     content = patchContractBlock(content, cwd)
     await fse.writeFile(agentsMdPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
     const label = backlogPlatform === repo ? repo : `${backlogPlatform}→${repo}`

package/cli/steps/copy/fullstack-engineer.js

@@ -64,14 +64,6 @@ export async function generateFullstackEngineer({ cwd = process.cwd(), updateMod
     // like every other subagent.
     // Quoted: a bare #hex is a YAML comment, which opencode rejects.
     `color: ${yamlColor(agentColor('fullstack-engineer'))}`,
-    'permission:',
-    '  edit: allow',
-    '  bash: allow',
-    '  read: allow',
-    '  glob: allow',
-    '  grep: allow',
-    '  question: allow',
-    '  todowrite: allow',
     '---',
   ]
 

package/harness/.opencode/_gitignore

@@ -2,9 +2,11 @@ node_modules
 harness-run.json
 harness.user.json
 harness-managed.json
+harness-models.json
 source-roots.json
 tmp/
 *-engineer.*.md
 agents/build.md
 agents/plan.md
 agents/planner.md
+agents/planner-sub.md

package/harness/.opencode/package.json

@@ -1,5 +1,6 @@
 {
   "dependencies": {
     "@opencode/plugin": "2.0.22"
-  }
+  },
+  "type": "module"
 }

package/harness/.opencode/plugins/pc-subagent-tiers-core.js

@@ -0,0 +1,337 @@
+// pc-subagent-tiers-core: pure Node agent generation. The plugin and the
+// standalone sync script both call this, so a CI pre-start step can write the
+// agents before OpenCode builds its task enum. No @opencode/plugin import here.
+//
+// Agent topology:
+//   build.md / plan.md      mode: primary   the only agents a human selects.
+//   planner.md              mode: all       fullstack body on the plan tier;
+//                                            commands run on it, it cannot spawn.
+//   planner-sub.md          mode: subagent  spawnable plan-tier alias for the
+//                                            task tool, same body, cannot spawn.
+//   fullstack-engineer.md   mode: subagent  shared body and fallback worker.
+//   *-engineer.md           mode: subagent  specialists.
+//   *-engineer.<tier>.md    mode: subagent  the same specialist pinned to a tier.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const TIERS = ["build", "fast", "plan"];
+export const MANIFEST_FILE = "harness-models.json";
+export const FULLSTACK_NAME = "fullstack-engineer";
+export const FULLSTACK_TEMPLATE = `${FULLSTACK_NAME}.md`;
+
+export const PRIMARIES = {
+  build: {
+    tier: "build",
+    color: "primary",
+    description:
+      "Implement changes in this repository. Full write access, spawns specialist engineers for parallel work.",
+    permissions: null,
+  },
+  plan: {
+    tier: "plan",
+    color: "warning",
+    description:
+      "Explore and plan without touching the tree. Read-only: proposes work for build to carry out.",
+    permissions: [
+      { action: "edit", resource: "*", effect: "deny" },
+      { action: "subagent", resource: "*", effect: "deny" },
+    ],
+  },
+  planner: {
+    tier: "plan",
+    mode: "all",
+    color: "info",
+    description:
+      "Write plans, proposals, stories, reviews and archives on the plan model. Edits the tree, never spawns workers.",
+    permissions: [{ action: "subagent", resource: "*", effect: "deny" }],
+  },
+};
+
+const THEME_COLORS = new Set(["primary", "secondary", "accent", "success", "warning", "error", "info"]);
+
+const LEGACY_FIELDS = [
+  "model",
+  "permission",
+  "prompt",
+  "disable",
+  "disabled",
+  "temperature",
+  "top_p",
+  "maxSteps",
+  "tools",
+];
+
+function agentColor(name) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < name.length; i++) {
+    h ^= name.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  const hue = (h >>> 0) % 360;
+  const sat = 0.68;
+  const light = 0.52;
+  const c = (1 - Math.abs(2 * light - 1)) * sat;
+  const x = c * (1 - Math.abs(((hue / 60) % 2) - 1));
+  const m = light - c / 2;
+  const [r, g, b] =
+    hue < 60
+      ? [c, x, 0]
+      : hue < 120
+        ? [x, c, 0]
+        : hue < 180
+          ? [0, c, x]
+          : hue < 240
+            ? [0, x, c]
+            : hue < 300
+              ? [x, 0, c]
+              : [c, 0, x];
+  const toHex = (v) => Math.round((v + m) * 255).toString(16).padStart(2, "0");
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase();
+}
+
+function shouldDeriveColor(current) {
+  if (!current) return true;
+  return THEME_COLORS.has(current.trim().toLowerCase());
+}
+
+function yamlColor(value) {
+  return value.startsWith("#") ? `"${value}"` : value;
+}
+
+function unquoteColor(raw) {
+  return (raw ?? "").trim().replace(/^["']/, "").replace(/["']$/, "");
+}
+
+function splitFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { frontmatter: null, body: content };
+  return { frontmatter: match[1], body: content.slice(match[0].length) };
+}
+
+function stripLegacyFields(frontmatter) {
+  const lines = frontmatter.split(/\r?\n/);
+  const kept = [];
+  for (let i = 0; i < lines.length; i++) {
+    const key = lines[i].match(/^([A-Za-z0-9_-]+):/)?.[1];
+    if (key && LEGACY_FIELDS.includes(key)) {
+      i++;
+      while (i < lines.length && /^\s+\S/.test(lines[i])) i++;
+      i--;
+      continue;
+    }
+    kept.push(lines[i]);
+  }
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function setScalar(frontmatter, key, value) {
+  const line = `${key}: ${value}`;
+  const lines = frontmatter.split(/\r?\n/);
+  const index = lines.findIndex((current) => current.startsWith(`${key}:`));
+  if (index === -1) return frontmatter ? `${line}\n${frontmatter}` : line;
+  lines[index] = line;
+  return lines.join("\n");
+}
+
+function permissionsYaml(permissions) {
+  return [
+    "permissions:",
+    ...permissions.flatMap((p) => [
+      `  - action: ${p.action}`,
+      `    resource: ${p.resource}`,
+      `    effect: ${p.effect}`,
+    ]),
+  ].join("\n");
+}
+
+function colorLineFor(name, rawCurrent) {
+  const current = unquoteColor(rawCurrent);
+  const target = shouldDeriveColor(current) ? agentColor(name) : current;
+  const rendered = yamlColor(target);
+  return (rawCurrent ?? "").trim() === rendered ? null : `color: ${rendered}`;
+}
+
+function normalizeTemplate(content, name) {
+  const { frontmatter, body } = splitFrontmatter(content);
+  if (frontmatter === null) {
+    return `---\nmode: subagent\ncolor: ${yamlColor(agentColor(name))}\n---\n\n${content}`;
+  }
+  let fm = stripLegacyFields(frontmatter);
+  fm = setScalar(fm, "mode", "subagent");
+  const colorLine = colorLineFor(name, fm.match(/^color:\s*(.+)$/m)?.[1]);
+  if (colorLine) fm = setScalar(fm, "color", colorLine.slice("color: ".length));
+  return `---\n${fm}\n---\n${body}`;
+}
+
+function buildVariant(templateContent, model) {
+  const { frontmatter, body } = splitFrontmatter(templateContent);
+  let fm = stripLegacyFields(frontmatter ?? "");
+  fm = setScalar(fm, "mode", "subagent");
+  fm = setScalar(fm, "model", model);
+  fm = setScalar(fm, "hidden", "true");
+  if (!/^color:/m.test(fm)) {
+    fm = setScalar(fm, "color", yamlColor(agentColor("engineer")));
+  }
+  return `---\n${fm}\n---\n${body}`;
+}
+
+function buildPrimary(spec, fullstackContent, model) {
+  const { body } = splitFrontmatter(fullstackContent);
+  const lines = ["---", `description: ${spec.description}`, `mode: ${spec.mode ?? "primary"}`];
+  if (model) lines.push(`model: ${model}`);
+  lines.push(`color: ${yamlColor(spec.color)}`);
+  if (spec.permissions) lines.push(permissionsYaml(spec.permissions));
+  lines.push("---");
+  return `${lines.join("\n")}\n\n${body.trim()}\n`;
+}
+
+function buildPlannerSub(fullstackContent, model) {
+  const { body } = splitFrontmatter(fullstackContent);
+  const lines = [
+    "---",
+    "description: Spawnable planner alias for the task tool. Uses the plan model and cannot spawn workers.",
+    "mode: subagent",
+  ];
+  if (model) lines.push(`model: ${model}`);
+  lines.push(`color: ${yamlColor(agentColor("planner-sub"))}`);
+  lines.push("hidden: true");
+  lines.push(permissionsYaml([{ action: "subagent", resource: "*", effect: "deny" }]));
+  lines.push("---");
+  return `${lines.join("\n")}\n\n${body.trim()}\n`;
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+async function scanEngineers(agentsDir) {
+  try {
+    const entries = await fs.readdir(agentsDir);
+    return {
+      templates: entries
+        .filter((f) => /^[\w-]+-engineer\.md$/.test(f) && f !== FULLSTACK_TEMPLATE)
+        .map((f) => f.replace(/\.md$/, "")),
+      variantFiles: entries.filter((f) => /^[\w-]+-engineer\.(build|fast|plan)\.md$/.test(f)),
+      hasFullstack: entries.includes(FULLSTACK_TEMPLATE),
+    };
+  } catch {
+    return { templates: [], variantFiles: [], hasFullstack: false };
+  }
+}
+
+async function writeIfChanged(filePath, content) {
+  try {
+    if ((await fs.readFile(filePath, "utf-8")) === content) return false;
+  } catch {
+    // file missing, write it
+  }
+  const tmpPath = `${filePath}.tmp`;
+  await fs.writeFile(tmpPath, content, "utf-8");
+  await fs.rename(tmpPath, filePath);
+  return true;
+}
+
+function isModelId(value) {
+  return typeof value === "string" && /^[^/\s]+\/[^/\s]+$/.test(value);
+}
+
+export async function generateAgents({ root, writeManifest = true } = {}) {
+  if (!root) throw new Error("generateAgents requires a root directory");
+  const agentsDir = path.join(root, ".opencode", "agents");
+  const [user, team] = await Promise.all([
+    readJson(path.join(root, ".opencode", "harness.user.json")),
+    readJson(path.join(root, ".opencode", "harness.json")),
+  ]);
+
+  const models = {};
+  const sources = {};
+  const warnings = [];
+  for (const tier of TIERS) {
+    const fromUser = user?.models?.[tier];
+    const fromTeam = team?.models?.[tier];
+    models[tier] = fromUser ?? fromTeam ?? null;
+    sources[tier] = fromUser ? "user" : fromTeam ? "team" : "missing";
+    if (!models[tier]) {
+      warnings.push(`tier ${tier} has no model; its agents inherit the session model`);
+    } else if (!isModelId(models[tier])) {
+      warnings.push(`tier ${tier} model "${models[tier]}" is not provider/model`);
+    }
+  }
+
+  const available = TIERS.filter((tier) => models[tier]);
+  const { templates, variantFiles, hasFullstack } = await scanEngineers(agentsDir);
+  const manifest = {
+    generatedAt: new Date().toISOString(),
+    models,
+    source: sources,
+    agents: {},
+    warnings,
+  };
+
+  if (hasFullstack) {
+    const fullstackPath = path.join(agentsDir, FULLSTACK_TEMPLATE);
+    const rawFullstack = await fs.readFile(fullstackPath, "utf-8");
+    const fullstack = normalizeTemplate(rawFullstack, FULLSTACK_NAME);
+    if (fullstack !== rawFullstack) await writeIfChanged(fullstackPath, fullstack);
+
+    for (const [name, spec] of Object.entries(PRIMARIES)) {
+      await writeIfChanged(path.join(agentsDir, `${name}.md`), buildPrimary(spec, fullstack, models[spec.tier]));
+      manifest.agents[name] = {
+        file: `${name}.md`,
+        mode: spec.mode ?? "primary",
+        model: models[spec.tier] ?? null,
+      };
+    }
+    await writeIfChanged(path.join(agentsDir, "planner-sub.md"), buildPlannerSub(fullstack, models.plan));
+    manifest.agents["planner-sub"] = {
+      file: "planner-sub.md",
+      mode: "subagent",
+      model: models.plan ?? null,
+      hidden: true,
+    };
+  } else {
+    warnings.push(`${FULLSTACK_TEMPLATE} missing: build, plan, planner and planner-sub not generated`);
+  }
+
+  const keepSet = new Set();
+  const variants = [];
+  for (const name of templates) {
+    const rawContent = await fs.readFile(path.join(agentsDir, `${name}.md`), "utf-8");
+    const content = normalizeTemplate(rawContent, name);
+    if (content !== rawContent) await writeIfChanged(path.join(agentsDir, `${name}.md`), content);
+    for (const tier of available) {
+      const file = `${name}.${tier}.md`;
+      variants.push({ file, path: path.join(agentsDir, file), content: buildVariant(content, models[tier]) });
+      keepSet.add(file);
+      manifest.agents[name] ??= {};
+      manifest.agents[name][tier] = { file, model: models[tier], hidden: true };
+    }
+  }
+
+  await Promise.all(variants.map((variant) => writeIfChanged(variant.path, variant.content)));
+  await Promise.all(
+    variantFiles.filter((file) => !keepSet.has(file)).map((file) => fs.unlink(path.join(agentsDir, file)).catch(() => {})),
+  );
+
+  if (templates.length === 0) warnings.push("no *-engineer.md templates found; no tier variants generated");
+
+  if (writeManifest) {
+    await fs.mkdir(path.join(root, ".opencode"), { recursive: true });
+    await writeIfChanged(path.join(root, ".opencode", MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+
+  return {
+    models,
+    sources,
+    warnings,
+    manifest,
+    templates,
+    variants: variants.map((variant) => variant.file),
+    hasFullstack,
+  };
+}