@plainconceptsplatform/agent-harness 2.0.1 → 2.1.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.1.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/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/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/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()) {