@plainconceptsplatform/agent-harness 2.0.1 → 2.2.0

package/README.md

@@ -164,12 +164,14 @@ Agents define _how to work_. They are universal personas (same behavior across p
 Current baseline uses a generic execution model:
 
 ```
-lead                   lead/orchestrator, planning, pull request lifecycle
-fullstack-engineer     primary planning agent, accumulates all skills (user-facing, not spawned)
-*-engineer             user-created specialists, spawned by the lead for parallel implementation
+build                  primary. Implements. Full write access. The default.
+plan                   primary. Same body as build, but cannot edit files.
+fullstack-engineer     subagent. The body build and plan share, and the fallback worker.
+*-engineer             subagent. User-created specialists, spawned for parallel implementation.
+*-engineer.<tier>      subagent. The same specialist pinned to a plan/build/fast model.
 ```
 
-`fullstack-engineer` is `mode: primary`, so it is the user's planning session agent rather than a spawned worker. Project-specific specialization comes from user-created custom engineers via `/make-engineer`. During `/plan-apply`, the lead inspects the engineers that actually exist in `.opencode/agents/` and spawns matching specialists. `fullstack-engineer` is never assigned to tasks. If no specialist matches, the user should create one.
+`build` and `plan` are the only agents a human selects, and they are overrides of opencode's own two primaries rather than new names. The `pc-subagent-tiers` plugin regenerates both from `fullstack-engineer.md` on every startup, so they always carry the current abilities, each on its own tier model. `plan` differs from `build` in one frontmatter line: `edit: deny`. It can still read the tree, shell out to git and openspec, and spawn engineers, so planning works and cannot write. Everything else is `mode: subagent` and reached through `task()`, never picked from the agent list. Project-specific specialization comes from user-created engineers via `/make-engineer`. During `/plan-apply` the lead inspects the engineers that actually exist in `.opencode/agents/` and spawns matching specialists. Prefer a specialist over `fullstack-engineer`; if none matches, create one.
 
 ### Skills, platform knowledge
 
@@ -289,7 +291,8 @@ your-project/
 │   ├── opencode.json                ← default model + plugin config
 │   ├── harness.json                 ← harness config: platform, models, maxConcurrentAgents
 │   ├── harness-managed.json         ← hashes of every managed file, so "update" spares your edits
-│   ├── agents/                      ← fullstack-engineer (primary, planning) + user-created *-engineer files
+│   ├── agents/                      ← build.md + plan.md (generated primaries), fullstack-engineer,
+│   │                                   and user-created *-engineer files (all subagents)
 │   ├── tui.json                     ← registers the Subagents sidebar panel
 │   ├── tui/
 │   │   └── pc-subagents.tsx         ← TUI plugin: live Subagents panel in the sidebar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",

package/src/commands/migrate.js

@@ -0,0 +1,294 @@
+import chalk from 'chalk'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { execa } from 'execa'
+import { fileURLToPath } from 'node:url'
+import { GENERATABLE_SKILLS, SKILL_RENAME } from '../steps/copy/skills.js'
+import { header, info, success, warn } from '../utils/exec.js'
+import { CONFIG_FILE, MANIFEST_FILE, OPENCODE_DIR, USER_CONFIG_FILE } from '../utils/paths.js'
+import { exit } from '../utils/process.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const CONTENT_SKILLS_DIR = path.resolve(__dirname, '../content/.agents/skills')
+
+// State files, old name to new. The run-state file is deleted rather than moved:
+// it is live wave state owned by the monitor plugin and is rebuilt on demand.
+const STATE_MOVES = [
+  ['opencode-onboard.json', CONFIG_FILE],
+  ['opencode-onboard.user.json', USER_CONFIG_FILE],
+  ['opencode-onboard-managed.json', MANIFEST_FILE],
+]
+const STATE_DELETES = ['.ob-run.json']
+
+const TEXT_EXTENSIONS = new Set(['.md', '.mdx', '.json', '.jsonc', '.js', '.ts', '.tsx', '.yaml', '.yml', '.txt'])
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', 'coverage'])
+
+// Archived OpenSpec changes are an audit trail: those proposals really did
+// reference ob-* skills when they were written. Rewriting them would make the
+// record say something that was never true, so the archive is left verbatim.
+const ARCHIVE_SEGMENTS = ['openspec', 'changes', 'archive']
+
+/**
+ * The skills this package ships, expressed under the old `ob-` prefix.
+ *
+ * A shipped skill is safe to delete because `update` reinstalls it as `pc-*`
+ * with current content, and that is strictly better than renaming a v1 copy we
+ * would then have to convince the manifest to overwrite. Anything NOT in this
+ * set is project-owned and must be renamed with its content intact.
+ */
+async function shippedLegacyNames() {
+  const entries = await fse.readdir(CONTENT_SKILLS_DIR, { withFileTypes: true }).catch(() => [])
+  const names = new Set()
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    // Platform variants install under a generic name, so both spellings ship.
+    for (const name of [entry.name, SKILL_RENAME[entry.name]].filter(Boolean)) {
+      if (name.startsWith('pc-')) names.add(`ob-${name.slice(3)}`)
+    }
+  }
+  return names
+}
+
+/** Generated skills carry project content even though the placeholder ships. */
+function isGeneratable(legacyName) {
+  return GENERATABLE_SKILLS.has(`pc-${legacyName.slice(3)}`)
+}
+
+function isArchived(filePath) {
+  // Split on both separators: path.join yields backslashes on Windows, and a
+  // separator-blind check here would let the archive be rewritten there only.
+  const parts = filePath.split(/[\\/]/)
+  const at = parts.indexOf(ARCHIVE_SEGMENTS[0])
+  if (at === -1) return false
+  return ARCHIVE_SEGMENTS.every((segment, i) => parts[at + i] === segment)
+}
+
+async function collectTextFiles(dir, acc = []) {
+  const entries = await fse.readdir(dir, { withFileTypes: true }).catch(() => [])
+  for (const entry of entries) {
+    if (SKIP_DIRS.has(entry.name)) continue
+    const full = path.join(dir, entry.name)
+    if (isArchived(full)) continue
+    if (entry.isDirectory()) {
+      await collectTextFiles(full, acc)
+    } else if (TEXT_EXTENSIONS.has(path.extname(entry.name)) || entry.name === '.gitignore') {
+      acc.push(full)
+    }
+  }
+  return acc
+}
+
+/**
+ * Rewrite the identifiers v2 renamed.
+ *
+ * `\b` matters: a bare `ob-` also appears inside words such as `{blob-url}` in
+ * the shipped GitHub ship fragment, and rewriting that silently corrupts the
+ * command it belongs to.
+ */
+function rewriteIdentifiers(text) {
+  return text
+    .replace(/\bob-/g, 'pc-')
+    .replace(/\bOB-/g, 'PC-')
+    .replace(/opencode-onboard-managed\.json/g, MANIFEST_FILE)
+    .replace(/opencode-onboard\.user\.json/g, USER_CONFIG_FILE)
+    .replace(/opencode-onboard\.json/g, CONFIG_FILE)
+    .replace(/@plainconceptsplatform\/opencode-onboard/g, '@plainconceptsplatform/agent-harness')
+}
+
+/** Base engineer templates and fullstack are subagents in v2. */
+function demoteToSubagent(text) {
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!fm) return text
+  if (!/^mode:\s*primary/m.test(fm[1])) return text
+  const patched = fm[1].replace(/^mode:.*$/m, 'mode: subagent')
+  return `---\n${patched}\n---${text.slice(fm[0].length)}`
+}
+
+async function isDirty(cwd) {
+  const result = await execa('git', ['status', '--porcelain'], { cwd, reject: false })
+  if (result.exitCode !== 0) return false
+  return result.stdout.trim().length > 0
+}
+
+export async function planMigration(cwd = process.cwd()) {
+  const opencodeDir = path.join(cwd, OPENCODE_DIR)
+  const skillsDir = path.join(cwd, '.agents', 'skills')
+
+  const moves = []
+  for (const [from, to] of STATE_MOVES) {
+    if (await fse.pathExists(path.join(opencodeDir, from))) moves.push([from, to])
+  }
+  const deletes = []
+  for (const name of STATE_DELETES) {
+    if (await fse.pathExists(path.join(opencodeDir, name))) deletes.push(name)
+  }
+
+  const shipped = await shippedLegacyNames()
+  const entries = (await fse.readdir(skillsDir).catch(() => [])).filter(e => e.startsWith('ob-'))
+
+  const skillsToRename = []
+  const skillsToDrop = []
+  for (const name of entries) {
+    const stat = await fse.stat(path.join(skillsDir, name)).catch(() => null)
+    if (!stat?.isDirectory()) continue
+    // Generated content wins over "it ships": the placeholder shipped, the
+    // 150-line project guardrails that replaced it did not.
+    if (isGeneratable(name) || !shipped.has(name)) skillsToRename.push([name, `pc-${name.slice(3)}`])
+    else skillsToDrop.push(name)
+  }
+
+  const agentsDir = path.join(cwd, OPENCODE_DIR, 'agents')
+  const agentFiles = await fse.readdir(agentsDir).catch(() => [])
+  const staleVariants = agentFiles.filter(f => /^[\w-]+-engineer\.(build|fast|plan)\.md$/.test(f))
+
+  // Plugins and the TUI panel are shipped code, and update installs the pc-*
+  // copies alongside rather than over the ob-* ones. Left in place, both
+  // generations load: two tier plugins writing the same variant files and two
+  // monitors writing the same run state.
+  const stalePlugins = []
+  for (const dir of ['plugins', 'tui']) {
+    const full = path.join(cwd, OPENCODE_DIR, dir)
+    for (const file of await fse.readdir(full).catch(() => [])) {
+      if (file.startsWith('ob-')) stalePlugins.push(path.join(dir, file))
+    }
+  }
+
+  return { moves, deletes, skillsToRename, skillsToDrop, staleVariants, stalePlugins }
+}
+
+export async function runMigrate({ cwd = process.cwd(), force = false, dryRun = false } = {}) {
+  header('Migrating from opencode-onboard v1')
+
+  const opencodeDir = path.join(cwd, OPENCODE_DIR)
+  if (await fse.pathExists(path.join(opencodeDir, CONFIG_FILE))) {
+    success(`${OPENCODE_DIR}/${CONFIG_FILE} already exists: this project is already on v2.`)
+    return { migrated: false, alreadyV2: true }
+  }
+  if (!await fse.pathExists(path.join(opencodeDir, 'opencode-onboard.json'))) {
+    warn(`No ${OPENCODE_DIR}/opencode-onboard.json found: nothing to migrate.`)
+    return { migrated: false }
+  }
+
+  // The migration rewrites files in place across the repo. A clean tree means
+  // `git checkout .` is always a complete undo.
+  if (!force && !dryRun && await isDirty(cwd)) {
+    warn('Working tree has uncommitted changes.')
+    warn('Commit or stash them first so this migration can be reverted with `git checkout .`, or pass --force.')
+    return { migrated: false, dirty: true }
+  }
+
+  const plan = await planMigration(cwd)
+
+  for (const [from, to] of plan.moves) info(`${from} -> ${to}`)
+  for (const name of plan.deletes) info(`${name} -> removed (rebuilt on demand)`)
+  for (const [from, to] of plan.skillsToRename) info(`${from}/ -> ${to}/ (content kept)`)
+  if (plan.skillsToDrop.length > 0) {
+    info(`${plan.skillsToDrop.length} shipped skill(s) removed, reinstalled as pc-* by update`)
+  }
+  if (plan.staleVariants.length > 0) {
+    info(`${plan.staleVariants.length} tier variant(s) removed, regenerated at startup`)
+  }
+  if (plan.stalePlugins.length > 0) {
+    info(`${plan.stalePlugins.length} ob- plugin/tui file(s) removed, replaced by pc-* on update`)
+  }
+
+  if (dryRun) {
+    console.log()
+    info('Dry run: nothing written.')
+    return { migrated: false, dryRun: true, plan }
+  }
+
+  // 1. State files. The manifest keeps its hashes; only its keys are renamed,
+  //    so update still recognizes untouched files and refreshes them.
+  for (const [from, to] of plan.moves) {
+    const fromPath = path.join(opencodeDir, from)
+    const toPath = path.join(opencodeDir, to)
+    if (to === MANIFEST_FILE) {
+      const manifest = await fse.readJson(fromPath).catch(() => null)
+      if (manifest?.files && typeof manifest.files === 'object') {
+        manifest.files = Object.fromEntries(
+          Object.entries(manifest.files).map(([key, value]) => [rewriteIdentifiers(key), value]),
+        )
+      }
+      await fse.writeJson(toPath, manifest ?? { version: 1, files: {} }, { spaces: 2 })
+      await fse.remove(fromPath)
+    } else {
+      await fse.move(fromPath, toPath, { overwrite: true })
+    }
+  }
+  for (const name of plan.deletes) await fse.remove(path.join(opencodeDir, name))
+
+  // 2. Skills: rename what holds project content, drop what update reinstalls.
+  const skillsDir = path.join(cwd, '.agents', 'skills')
+  for (const [from, to] of plan.skillsToRename) {
+    await fse.move(path.join(skillsDir, from), path.join(skillsDir, to), { overwrite: true })
+  }
+  for (const name of plan.skillsToDrop) await fse.remove(path.join(skillsDir, name))
+
+  // 3. Stale tier variants: the plugin rebuilds these from the base templates.
+  const agentsDir = path.join(opencodeDir, 'agents')
+  for (const file of plan.staleVariants) await fse.remove(path.join(agentsDir, file))
+
+  // 3b. Stale plugins and TUI panel, so only one generation loads.
+  for (const relative of plan.stalePlugins) await fse.remove(path.join(opencodeDir, relative))
+
+  // 4. Rewrite identifiers everywhere that survives, so preserved skills and
+  //    custom agents stop pointing at names that no longer exist.
+  let rewritten = 0
+  for (const dir of [skillsDir, opencodeDir, path.join(cwd, 'openspec')]) {
+    if (!await fse.pathExists(dir)) continue
+    for (const file of await collectTextFiles(dir)) {
+      const before = await fse.readFile(file, 'utf-8')
+      const after = rewriteIdentifiers(before)
+      if (after !== before) {
+        await fse.writeFile(file, after, 'utf-8')
+        rewritten++
+      }
+    }
+  }
+  for (const name of ['AGENTS.md', 'ARCHITECTURE.md', 'DESIGN.md', 'opencode.jsonc', 'opencode.json']) {
+    const file = path.join(cwd, name)
+    if (!await fse.pathExists(file)) continue
+    const before = await fse.readFile(file, 'utf-8')
+    const after = rewriteIdentifiers(before)
+    if (after !== before) {
+      await fse.writeFile(file, after, 'utf-8')
+      rewritten++
+    }
+  }
+
+  // 5. Engineers become subagents; build and plan are the only primaries now.
+  //    The plugin also does this at startup, but doing it here keeps the
+  //    migration commit self-consistent.
+  let demoted = 0
+  for (const file of await fse.readdir(agentsDir).catch(() => [])) {
+    if (!file.endsWith('.md')) continue
+    const full = path.join(agentsDir, file)
+    const before = await fse.readFile(full, 'utf-8')
+    const after = demoteToSubagent(before)
+    if (after !== before) {
+      await fse.writeFile(full, after, 'utf-8')
+      demoted++
+    }
+  }
+
+  success(`Renamed ${plan.moves.length} state file(s), kept ${plan.skillsToRename.length} project-owned skill(s)`)
+  success(`Rewrote identifiers in ${rewritten} file(s), demoted ${demoted} agent(s) to subagent`)
+  if (plan.stalePlugins.length > 0) {
+    success(`Removed ${plan.stalePlugins.length} superseded plugin/tui file(s)`)
+  }
+  console.log()
+  console.log(chalk.bold('Next: run update to install the current harness.'))
+  console.log(chalk.dim('  npx @plainconceptsplatform/agent-harness@latest update'))
+
+  return { migrated: true, plan, rewritten, demoted }
+}
+
+export async function runMigrateCommand(args = []) {
+  const result = await runMigrate({
+    force: args.includes('--force'),
+    dryRun: args.includes('--dry-run'),
+  })
+  if (result.dirty) exit(1)
+  return result
+}

package/src/content/.agents/skills/pc-make-engineer/SKILL.md

@@ -4,9 +4,9 @@ description: Create a custom engineer agent via persona-driven interactive desig
 license: MIT
 ---
 
-Create one file only: `.opencode/agents/{persona}-engineer.md`. The `pc-subagent-tiers` plugin creates tier variants (`.build.md`, `.fast.md`, `.plan.md`) at startup, so you never write those.
+Create one file only: `.opencode/agents/{persona}-engineer.md`. The `pc-subagent-tiers` plugin creates tier variants (`.build.md`, `.fast.md`, `.plan.md`) at startup, so you never write those. It also generates `build.md` and `plan.md`, the only two primary agents: never create or edit those either.
 
-Fidelity to the [template](template.md) is the whole job. The file contains frontmatter plus one identity paragraph plus the `## Abilities` section. No other `##` headings. No expertise notes, architecture details, conventions, file maps, or workflow steps. Those belong in skills. Always set `mode: primary`. Never write `model:`. Only reference skills installed in the project's `.agents/skills/` directory.
+Fidelity to the [template](template.md) is the whole job. The file contains frontmatter plus one identity paragraph plus the `## Abilities` section. No other `##` headings. No expertise notes, architecture details, conventions, file maps, or workflow steps. Those belong in skills. Always set `mode: subagent`. Engineers are reached through `task()`, never picked by a human, so a primary engineer would only clutter the agent picker. Never write `model:`. Only reference skills installed in the project's `.agents/skills/` directory.
 
 Skills first: you must complete Step 4 (present the form, discover skills for every detected signal and architecture, let the user confirm the set, then install 5-10 skills) before writing any file.
 
@@ -185,7 +185,7 @@ If either check fails, fix the file and re-validate.
 
 ## Step 7: Update fullstack-engineer.md abilities
 
-The `fullstack-engineer.md` is `mode: primary`, the planning session agent, not a spawned worker. Having all skills here is fine since it does planning, not parallel implementation.
+`fullstack-engineer.md` is `mode: subagent`, but it is also the body that `pc-subagent-tiers` copies into `build.md` and `plan.md` on every startup. So every skill listed here reaches both primary agents, which is why it accumulates all of them: it plans and delegates rather than doing parallel implementation itself.
 
 After creating the persona engineer and validating its references, additively merge new skills into fullstack:
 
@@ -216,4 +216,4 @@ Report:
 - Skills that failed validation or install (list each with reason)
 - `fullstack-engineer.md` updated (additive, list new skills added)
 - How to use: "This agent will be spawned by the lead during `/plan-apply` for tasks matching its specialty."
-- "Restart opencode for the `pc-subagent-tiers` plugin to pick up the new engineer."
+- "Restart opencode for the `pc-subagent-tiers` plugin to pick up the new engineer and rebuild `build.md` and `plan.md` from the updated fullstack abilities."

package/src/content/.agents/skills/pc-make-engineer/template.md

@@ -5,8 +5,8 @@ The agent file is exactly this structure: frontmatter plus one identity paragrap
 ```markdown
 ---
 description: <one sentence naming the persona + top 3-5 detected technologies>
-mode: primary
-color: <pick: primary|secondary|accent|error|info: avoid colors used by existing agents; warning is reserved for the lead engineer>
+mode: subagent
+color: <pick: primary|secondary|accent|error|info: avoid colors used by existing agents; warning is reserved for the build and plan primaries>
 permission:
   edit: allow
   bash: allow
@@ -62,7 +62,7 @@ Rules:
 
 After writing the agent file, verify:
 
-1. Frontmatter exists: starts with `---`, has `description`, `mode: primary`, `color`, `permission` block.
+1. Frontmatter exists: starts with `---`, has `description`, `mode: subagent`, `color`, `permission` block.
 2. No `model:` field in the frontmatter. The `pc-subagent-tiers` plugin injects it.
 3. `## Abilities` is the only `##` heading. No other `##` sections exist in the file.
 4. One identity paragraph before `## Abilities`: 2-3 sentences max, not multiple paragraphs.

package/src/content/.agents/skills/pc-plan-propose/SKILL.md

@@ -58,7 +58,7 @@ Load `@openspec-propose` skill and follow its instructions to generate proposal.
    - `description:` from the YAML frontmatter: the engineer's specialization summary
    - `## Abilities` section: the skills listed under Development, Testing, Infrastructure (e.g. `@nodejs-backend`, `@secure-nextjs-api-routes`)
    Build a map of `agent-name -> { description, abilities }`.
-2. For each task, compare the task text and domain against every engineer's description AND abilities. Pick the engineer whose combined profile most closely matches. `fullstack-engineer` is `mode: primary` (the user's planning agent), not a spawned worker. If no specialist matches a task, leave the agent field blank and record the missing specialization in the proposal. An annotated OpenSpec task needs a real subagent; never substitute the lead or an obsolete generic agent name.
+2. For each task, compare the task text and domain against every engineer's description AND abilities. Pick the engineer whose combined profile most closely matches. `fullstack-engineer` is the fallback worker and the body behind `build` and `plan`; prefer a real specialist over it, and never annotate a task with `build` or `plan`, which are the user's own primaries. If no specialist matches a task, leave the agent field blank and record the missing specialization in the proposal. An annotated OpenSpec task needs a real subagent; never substitute the lead or an obsolete generic agent name.
 3. Pick a tier, derive `depends_on`, derive `touches`, and annotate each task line. Follow the [task annotation](task-annotation.md) reference for the full tier selection guide, dependency derivation, touches derivation, and annotation format with examples.
 
 ## Step 3: Show the plan and ask for confirmation (stop)

package/src/content/.agents/skills/pc-repo-onboard/SKILL.md

@@ -33,7 +33,7 @@ Present as a table:
 Then explain the agent selection model:
 - Primary agents appear in Tab and handle direct user interaction
 - Subagent engineers are spawned by the lead for parallel implementation waves
-- Specialist engineers are preferred when their domain matches the task; `fullstack-engineer` is the user's planning agent (`mode: primary`), not a spawned worker. If no specialist matches, create one with `/make-engineer`.
+- Specialist engineers are preferred when their domain matches the task. `build` and `plan` are the only agents the user selects, and both run the `fullstack-engineer` body; `plan` cannot edit files. Everything else is `mode: subagent` and spawned. If no specialist matches, create one with `/make-engineer`.
 
 ## Step 3: Command reference
 

package/src/content/.opencode/_gitignore

@@ -5,3 +5,5 @@ harness-managed.json
 source-roots.json
 tmp/
 *-engineer.*.md
+agents/build.md
+agents/plan.md

package/src/content/.opencode/plugins/pc-subagent-tiers.js

@@ -1,12 +1,45 @@
 // pc-subagent-tiers: on startup, reads *-engineer.md templates and creates
-// tier variant files with the resolved model. Variants are gitignored and
-// regenerated every startup. Model resolution: user override > team config.
+// tier variant files with the resolved model, plus the two primary agents the
+// user actually talks to. Everything generated here is gitignored and rebuilt
+// every startup. Model resolution: user override > team config.
+//
+// Agent topology:
+//   build.md / plan.md      mode: primary   the only agents a human selects.
+//                                           Both are fullstack-engineer with a
+//                                           tier model; plan cannot edit.
+//   fullstack-engineer.md   mode: subagent  the shared body of build and plan,
+//                                           and the fallback worker.
+//   *-engineer.md           mode: subagent  specialists, spawned by task().
+//   *-engineer.<tier>.md    mode: subagent  the same specialist pinned to a tier.
+//
+// Overriding opencode's built-in build and plan (rather than disabling them, as
+// earlier versions did) means the agent picker offers exactly two entries and
+// both carry our prompt and abilities.
 
 import fs from "node:fs/promises"
 import path from "node:path"
 
 const TIERS = ["build", "fast", "plan"]
 
+// The two primaries, and the tier each takes its model from. plan denies edit
+// so a planning session cannot mutate the tree; bash stays allowed because the
+// planning skills shell out to git and openspec to read state.
+const PRIMARIES = {
+  build: {
+    tier: "build",
+    description: "Implement changes in this repository. Full write access, spawns specialist engineers for parallel work.",
+    permission: null,
+  },
+  plan: {
+    tier: "plan",
+    description: "Explore and plan without touching the tree. Read-only: proposes work for build to carry out.",
+    permission: { edit: "deny" },
+  },
+}
+
+const FULLSTACK_NAME = "fullstack-engineer"
+const FULLSTACK_TEMPLATE = `${FULLSTACK_NAME}.md`
+
 export const PcSubagentTiers = async ({ directory }) => {
   const root = directory || process.cwd()
   const agentsDir = path.join(root, ".opencode", "agents")
@@ -35,11 +68,12 @@ export const PcSubagentTiers = async ({ directory }) => {
     try {
       const entries = await fs.readdir(agentsDir)
       return {
-        templates: entries.filter(f => /^[\w-]+-engineer\.md$/.test(f) && f !== 'fullstack-engineer.md').map(f => f.replace(/\.md$/, "")),
+        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: [] }
+      return { templates: [], variantFiles: [], hasFullstack: false }
     }
   }
 
@@ -61,11 +95,13 @@ export const PcSubagentTiers = async ({ directory }) => {
     return `---\n${fm}\n---${templateContent.slice(fmMatch[0].length)}`
   }
 
-  // Ensure template files have mode: primary and no stale model: line. Base
-  // engineer templates must never declare a model: models are resolved at
-  // startup per-tier and injected into variant files only. A stale model:
-  // (e.g. from a prior `stampAgentModels` run) is stripped here so the base
-  // agent falls back to the session-level model in opencode.jsonc.
+  // Ensure template files are mode: subagent with no stale model: line. Only
+  // build and plan are primary; every engineer is reached through task(), never
+  // picked by a human, so a primary engineer would just clutter the picker.
+  // Templates must never declare a model either: models resolve per tier at
+  // startup and are injected into generated files only, so a stale model: (from
+  // a prior `stampAgentModels` run, or from when these were primary) is
+  // stripped and the agent falls back to the session model in opencode.jsonc.
   function normalizeTemplate(templateContent) {
     const fmMatch = templateContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
     if (!fmMatch) return templateContent
@@ -73,8 +109,8 @@ export const PcSubagentTiers = async ({ directory }) => {
     let fm = fmMatch[1]
     let changed = false
 
-    if (!/^mode:\s*primary/m.test(fm)) {
-      fm = /^mode:/m.test(fm) ? fm.replace(/^mode:.*$/m, 'mode: primary') : `mode: primary\n${fm}`
+    if (!/^mode:\s*subagent/m.test(fm)) {
+      fm = /^mode:/m.test(fm) ? fm.replace(/^mode:.*$/m, 'mode: subagent') : `mode: subagent\n${fm}`
       changed = true
     }
     if (/^model:/m.test(fm)) {
@@ -91,6 +127,32 @@ export const PcSubagentTiers = async ({ directory }) => {
     return templateContent.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? null
   }
 
+  // Build a primary from the fullstack body: same identity and the same
+  // ## Abilities block, with our own frontmatter on top. The body is taken
+  // verbatim so /make-engineer only has to maintain fullstack-engineer.md and
+  // both primaries inherit whatever it lists.
+  function buildPrimary(name, spec, fullstackContent, model) {
+    const body = fullstackContent.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
+
+    const lines = [
+      '---',
+      `description: ${spec.description}`,
+      'mode: primary',
+    ]
+    if (model) lines.push(`model: ${model}`)
+    lines.push('color: warning')
+    lines.push('permission:')
+    // plan denies edit; everything else stays allowed so the planning skills can
+    // still read the tree, shell out to git and openspec, and spawn engineers.
+    lines.push(`  edit: ${spec.permission?.edit ?? 'allow'}`)
+    for (const key of ['bash', 'read', 'glob', 'grep', 'question', 'todowrite', 'task', 'skill']) {
+      lines.push(`  ${key}: ${spec.permission?.[key] ?? 'allow'}`)
+    }
+    lines.push('---')
+
+    return `${lines.join('\n')}\n\n${body}\n`
+  }
+
   // Skip writing if the file already has identical content.
   async function writeIfChanged(filePath, content) {
     try {
@@ -108,7 +170,43 @@ export const PcSubagentTiers = async ({ directory }) => {
       try {
         const models = await resolveModels()
         const available = TIERS.filter(t => models[t])
-        const { templates, variantFiles } = await scanEngineers()
+        const { templates, variantFiles, hasFullstack } = await scanEngineers()
+
+        // build.md and plan.md are regenerated from fullstack-engineer.md every
+        // startup, which is also how an edit to fullstack propagates to both.
+        // normalizeTemplate runs on it too, so a repo carrying the old
+        // mode: primary fullstack is migrated in place on first launch.
+        if (hasFullstack) {
+          const fullstackPath = path.join(agentsDir, FULLSTACK_TEMPLATE)
+          const rawFullstack = await fs.readFile(fullstackPath, "utf-8")
+          const fullstack = normalizeTemplate(rawFullstack)
+          if (fullstack !== rawFullstack) {
+            await writeIfChanged(fullstackPath, fullstack)
+            console.error(`[pc-subagent-tiers] Normalized ${FULLSTACK_TEMPLATE} (mode: subagent)`)
+          }
+
+          for (const [name, spec] of Object.entries(PRIMARIES)) {
+            const model = models[spec.tier]
+            await writeIfChanged(
+              path.join(agentsDir, `${name}.md`),
+              buildPrimary(name, spec, fullstack, model),
+            )
+            if (cfg?.agent) {
+              // Override opencode's built-in agent of the same name rather than
+              // disabling it, so the picker shows ours with our model.
+              cfg.agent[name] = {
+                ...cfg.agent[name],
+                mode: 'primary',
+                description: spec.description,
+                ...(model ? { model } : {}),
+                ...(spec.permission ? { permission: { ...cfg.agent[name]?.permission, ...spec.permission } } : {}),
+              }
+            }
+          }
+          console.error(`[pc-subagent-tiers] Wrote primaries: build (${models.build ?? 'session model'}), plan (${models.plan ?? 'session model'})`)
+        } else {
+          console.error(`[pc-subagent-tiers] ${FULLSTACK_TEMPLATE} missing: build and plan not generated`)
+        }
 
         const templateContents = await Promise.all(
           templates.map(async name => {
@@ -117,7 +215,7 @@ export const PcSubagentTiers = async ({ directory }) => {
             // If the template had the wrong mode or a stale model:, persist the fix to disk
             if (content !== rawContent) {
               await writeIfChanged(path.join(agentsDir, `${name}.md`), content)
-              console.error(`[pc-subagent-tiers] Normalized ${name}.md (mode: primary, model: removed)`)
+              console.error(`[pc-subagent-tiers] Normalized ${name}.md (mode: subagent, model: removed)`)
             }
             return { name, content }
           })
@@ -144,12 +242,16 @@ export const PcSubagentTiers = async ({ directory }) => {
         await Promise.all(variantsToWrite.map(v => writeIfChanged(v.path, v.content)))
 
         if (cfg?.agent) {
-          // Ensure base templates are always mode: primary in-memory
+          // Ensure base templates are always mode: subagent in-memory. A repo
+          // upgraded from an earlier version may still have primary in config.
           for (const { name } of templateContents) {
             if (cfg.agent[name]) {
-              cfg.agent[name].mode = 'primary'
+              cfg.agent[name].mode = 'subagent'
             }
           }
+          if (cfg.agent[FULLSTACK_NAME]) {
+            cfg.agent[FULLSTACK_NAME].mode = 'subagent'
+          }
           for (const { name, tier, templateContent } of variantsToWrite) {
             const base = cfg.agent[name]
             cfg.agent[`${name}.${tier}`] = base

package/src/content/AGENTS.md

@@ -38,7 +38,7 @@ Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `
 
 ## Engineer selection
 
-Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `fullstack-engineer` is `mode: primary`, the planning agent, and is not a spawned worker. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
+Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
 
 The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. Read `agents.maxConcurrent` from `.opencode/harness.json` before spawning workers.
 

package/src/content/opencode.jsonc

@@ -1,31 +1,39 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "instructions": [
-    "AGENTS.md"
-  ],
-  "plugin": [
-    "@different-ai/opencode-browser@4.6.1",
-    "@mohak34/opencode-notifier@0.2.8"
-  ],
-  "experimental": {
-    "mcp_timeout": 300000
-  },
-  "compaction": {
-    "auto": true,
-    "prune": true,
-    "reserved": 10000
-  },
-  "permission": {
-    "question": "allow",
-    "todowrite": "allow",
-    "skill": "allow"
-  },
-  "skills": {
-    "paths": [".agents/skills"]
-  },
-  "default_agent": "fullstack-engineer",
-  "agent": {
-    "build": { "disable": true },
-    "plan": { "disable": true }
-  }
-}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "AGENTS.md"
+  ],
+  "plugin": [
+    "@different-ai/opencode-browser@4.6.1",
+    "@mohak34/opencode-notifier@0.2.8"
+  ],
+  "experimental": {
+    "mcp_timeout": 300000
+  },
+  "compaction": {
+    "auto": true,
+    "prune": true,
+    "reserved": 10000
+  },
+  "permission": {
+    "question": "allow",
+    "todowrite": "allow",
+    "skill": "allow"
+  },
+  "skills": {
+    "paths": [".agents/skills"]
+  },
+  // build and plan are the only primaries. The pc-subagent-tiers plugin
+  // regenerates .opencode/agents/{build,plan}.md from fullstack-engineer.md on
+  // every startup and overrides these two entries with the resolved tier model,
+  // so what is here is only the floor if the plugin cannot run. Every engineer
+  // is mode: subagent and reached through task(), never picked by a human.
+  "default_agent": "build",
+  "agent": {
+    "build": { "mode": "primary" },
+    "plan": {
+      "mode": "primary",
+      "permission": { "edit": "deny" }
+    }
+  }
+}

package/src/index.js

@@ -6,6 +6,7 @@ import { runUpdate } from './commands/update.js'
 import { runSingleCommand } from './commands/single.js'
 import { runWizard } from './commands/wizard.js'
 import { exit } from './utils/process.js'
+import { runMigrateCommand } from './commands/migrate.js'
 import { findLegacyInstall } from './utils/legacy-check.js'
 
 function printHelp(version) {
@@ -17,6 +18,7 @@ function printHelp(version) {
   console.log()
   console.log('Commands:')
   console.log('  update          Bring the harness up to date from saved config (no prompts)')
+  console.log('  migrate         Move a v1 (opencode-onboard) project to v2, keeping your content')
   console.log('  join            Set up a teammate\'s machine (checks & local installs only)')
   console.log('  clean           Run AI files cleanup step')
   console.log('  platform        Run platform selection step')
@@ -59,16 +61,23 @@ async function refuseLegacyInstall() {
   console.log('and it does not migrate v1 projects. Continuing would leave the harness')
   console.log('half-patched without reporting an error.')
   console.log()
-  console.log('Re-onboard on a clean branch instead:')
-  console.log(chalk.dim('  git switch -c chore/agent-harness'))
-  console.log(chalk.dim('  rm -rf .opencode .agents/skills/ob-*'))
-  console.log(chalk.dim('  npx @plainconceptsplatform/agent-harness'))
+  console.log('Migrate it, keeping your generated skills and custom engineers:')
+  console.log(chalk.dim('  npx @plainconceptsplatform/agent-harness migrate'))
+  console.log(chalk.dim('  npx @plainconceptsplatform/agent-harness update'))
+  console.log()
+  console.log(chalk.dim('Add --dry-run to see what migrate would change first.'))
   return true
 }
 
 // Ctrl-C out of an @inquirer prompt throws ExitPromptError; that is a normal
 // cancellation, not a crash, so it must not exit non-zero.
 async function main() {
+  // migrate is the way out of a v1 project, so it must run before the guard
+  // that refuses v1 projects.
+  if (args[0] === 'migrate') {
+    await runMigrateCommand(args.slice(1))
+    return
+  }
   if (await refuseLegacyInstall()) {
     exit(1)
     return

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

@@ -4,7 +4,7 @@ import { success } from '../../utils/exec.js'
 
 const FULLSTACK_FILE = 'fullstack-engineer.md'
 const FULLSTACK_DESCRIPTION = 'Default engineer that accumulates skills from all created persona engineers. Use as fallback when no specialist matches: but prefer spawning a specific engineer for deterministic results.'
-const FULLSTACK_IDENTITY = 'You are the default engineer, mostly used by the user for architecture and planning. You are more complete but less accurate than specialized engineers, prefer spawning a specialist when one matches the task domain.'
+const FULLSTACK_IDENTITY = 'You are the default engineer, and your body is what the build and plan agents run. You are more complete but less accurate than specialized engineers, so prefer spawning a specialist when one matches the task domain.'
 
 // The reminder plugin owns ability bootstrap. Remove the old prompt-level
 // directive when regenerating so it cannot duplicate the plugin reminder.
@@ -56,7 +56,9 @@ export async function generateFullstackEngineer({ cwd = process.cwd(), updateMod
   const frontmatter = [
     '---',
     `description: ${FULLSTACK_DESCRIPTION}`,
-    'mode: primary',
+    // subagent, not primary: build.md and plan.md are the primaries, and
+    // pc-subagent-tiers generates both from this file on every startup.
+    'mode: subagent',
     'color: warning',
     'permission:',
     '  edit: allow',

package/src/steps/copy/opencode-json.js

@@ -33,9 +33,19 @@ export async function patchOpencodeJson(cwd = process.cwd()) {
     return { patched: false, reason: 'parse error' }
   }
 
-  const needsAgentDisable = !(
-    parsed?.agent?.build?.disable === true &&
-    parsed?.agent?.plan?.disable === true
+  // build and plan are overridden, not disabled. Earlier versions disabled them
+  // and pointed default_agent at fullstack-engineer; now they are the only two
+  // primaries and pc-subagent-tiers regenerates their agent files from
+  // fullstack-engineer.md. A repo patched by an earlier version still carries
+  // `disable: true`, which would hide both agents, so that flag is cleared here.
+  const hasStaleDisable = (
+    parsed?.agent?.build?.disable !== undefined ||
+    parsed?.agent?.plan?.disable !== undefined
+  )
+  const needsAgentOverride = hasStaleDisable || !(
+    parsed?.agent?.build?.mode === 'primary' &&
+    parsed?.agent?.plan?.mode === 'primary' &&
+    parsed?.agent?.plan?.permission?.edit === 'deny'
   )
   const needsSkillPermission = parsed?.permission?.skill !== 'allow'
   const missingSharedPermissions = SHARED_PERMISSIONS.filter(
@@ -51,14 +61,22 @@ export async function patchOpencodeJson(cwd = process.cwd()) {
     parsed?.compaction?.prune === true
   )
 
-  if (!needsAgentDisable && !needsSkillPermission && missingSharedPermissions.length === 0 && !needsSkillsPaths && !needsCompaction) {
+  if (!needsAgentOverride && !needsSkillPermission && missingSharedPermissions.length === 0 && !needsSkillsPaths && !needsCompaction) {
     return { patched: false }
   }
 
   // Apply edits sequentially so offsets stay correct
-  if (needsAgentDisable) {
-    text = applyModify(text, ['agent', 'build', 'disable'], true)
-    text = applyModify(text, ['agent', 'plan', 'disable'], true)
+  if (needsAgentOverride) {
+    // undefined removes the key, clearing the disable left by earlier versions.
+    if (parsed?.agent?.build?.disable !== undefined) {
+      text = applyModify(text, ['agent', 'build', 'disable'], undefined)
+    }
+    if (parsed?.agent?.plan?.disable !== undefined) {
+      text = applyModify(text, ['agent', 'plan', 'disable'], undefined)
+    }
+    text = applyModify(text, ['agent', 'build', 'mode'], 'primary')
+    text = applyModify(text, ['agent', 'plan', 'mode'], 'primary')
+    text = applyModify(text, ['agent', 'plan', 'permission', 'edit'], 'deny')
   }
   if (needsSkillPermission) text = applyModify(text, ['permission', 'skill'], 'allow')
   for (const [key, value] of missingSharedPermissions) {
@@ -82,8 +100,8 @@ export async function patchOpencodeJson(cwd = process.cwd()) {
   }
 
   await fse.writeFile(opencodePath, text, 'utf-8')
-  if (needsAgentDisable) {
-    success('Disabled built-in build/plan agents in opencode.jsonc')
+  if (needsAgentOverride) {
+    success('Set build/plan as the primary agents in opencode.jsonc (plan is read-only)')
   }
   if (needsSkillPermission) {
     success('Allowed skill loading in opencode.jsonc')

package/src/steps/copy/skills.js

@@ -21,7 +21,7 @@ const BACKLOG_PLATFORM_SKILLS = {
 // Platform-specific skills are renamed to their generic form on install.
 // The -gh / -az / -jira / -gl suffix is only needed here to keep all variants in source.
 // After install only one platform is present so no suffix is needed.
-const SKILL_RENAME = {
+export const SKILL_RENAME = {
   'pc-userstory-gh':      'pc-userstory',
   'pc-userstory-az':      'pc-userstory',
   'pc-userstory-jira':    'pc-userstory',
@@ -38,7 +38,7 @@ function shouldInstallSkill(skill, backlogPlatform, _repoPlatform) {
 // these must be preserved when they have already been generated (detected
 // by the <!-- Last updated: marker). Without this check, the update would
 // wipe project-specific guardrails, risk assessments, etc.
-const GENERATABLE_SKILLS = new Set([
+export const GENERATABLE_SKILLS = new Set([
   'pc-guardrails-project',
   'pc-merge-risk-assess',
 ])

package/src/utils/paths.js

@@ -34,6 +34,9 @@ export const IGNORED_ENTRIES = [
   MANIFEST_FILE,
   'source-roots.json',
   '*-engineer.*.md',
+  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
+  'agents/build.md',
+  'agents/plan.md',
 ]
 
 export function configPath(cwd = process.cwd()) {