@plainconceptsplatform/agent-harness 3.8.3 → 3.9.0

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"
-  }
-}
+{
+  "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,
+  };
+}

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

@@ -1,367 +1,56 @@
-// pc-subagent-tiers: on startup, reads *-engineer.md templates and creates
-// tier variant agent 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 can neither edit
-//                                           nor spawn.
-//   planner.md              mode: all       fullstack-engineer on the plan tier
-//                                           that may write but not spawn. The
-//                                           thinking commands run on it, and a
-//                                           CI lead spawns it for propose and
-//                                           archive, so those steps take the
-//                                           plan model whatever the session's is.
-//   fullstack-engineer.md   mode: subagent  the shared body of build and plan,
-//                                           and the fallback worker.
-//   *-engineer.md           mode: subagent  specialists, spawned by subagent().
-//   *-engineer.<tier>.md    mode: subagent  the same specialist pinned to a tier.
-//
-// OpenCode 2 discovers agents from .opencode/agents/*.md and overrides a built-in
-// by ID, so the generated files replace the built-in build/plan. The plugin API's
-// agent editor can update or remove an existing agent but cannot add one, so file
-// generation is the mechanism: writing the files in setup, before agents resolve,
-// is what makes them visible.
-
-import { Plugin, Model } from "@opencode/plugin"
-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
-// and subagent: a planning session cannot mutate the tree itself, and it cannot
-// spawn a worker that would do it on its behalf. shell stays allowed because the
-// planning skills shell out to git and openspec to read state, and
-// pc-system-reminders holds it to inspection commands.
-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" }],
-  },
-}
-
-// opencode's theme keywords. Treated as unset so a name-derived hex wins: the
-// old /make-engineer template asked whoever ran it to pick one of these and
-// avoid collisions by hand, which does not survive more than a few agents.
-const THEME_COLORS = new Set(["primary", "secondary", "accent", "success", "warning", "error", "info"])
-
-// Fields V1 agent frontmatter used that V2 forbids. Stripped on sight so a repo
-// upgraded in place does not carry a definition V2 refuses to load.
-const LEGACY_FIELDS = [
-  "model",
-  "permission",
-  "prompt",
-  "disable",
-  "disabled",
-  "temperature",
-  "top_p",
-  "maxSteps",
-  "tools",
-]
-
-// Mirrors cli/utils/agent-color.js in the CLI, duplicated because a plugin has
-// to stand alone in the consumer repo. agent-color.test.js asserts the two stay
-// in step; change one and change the other.
-//
-// Only the hue is hashed. Fixed saturation and lightness are what keep every
-// result usable: hashing those too would eventually produce a near-grey,
-// near-black or near-white agent, invisible against one theme or the other.
-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()
-}
-
-/** A theme keyword or a missing value yields to the derived hex; a hex stays. */
-function shouldDeriveColor(current) {
-  if (!current) return true
-  return THEME_COLORS.has(current.trim().toLowerCase())
-}
-
-/**
- * Render a colour for YAML frontmatter.
- *
- * A hex has to be quoted. `#` opens a comment in YAML, so `color: #D83155`
- * parses as null and opencode refuses the agent with "Invalid input color".
- * Theme keywords need no quoting and stay bare.
- */
-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)) {
-      // Drop the key and any indented continuation lines that belong to it.
-      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}`
-  // String operations rather than a built RegExp: `key` is one of this module's
-  // own constants, so the pattern would be safe, but a dynamic regexp here is a
-  // ReDoS-shaped pattern that static analysis rightly refuses to clear.
-  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")
-}
-
-/** The colour line an agent should have, or null when the current one is right. */
-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}`
-}
-
-const FULLSTACK_NAME = "fullstack-engineer"
-const FULLSTACK_TEMPLATE = `${FULLSTACK_NAME}.md`
-
-/** Rewrite a template's frontmatter to a clean V2 subagent definition. */
-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}`
-}
-
-/** A tier-pinned copy of a specialist: same body, resolved model. */
-function buildVariant(templateContent, model) {
-  const { frontmatter, body } = splitFrontmatter(templateContent)
-  let fm = stripLegacyFields(frontmatter ?? "")
-  fm = setScalar(fm, "mode", "subagent")
-  fm = setScalar(fm, "model", model)
-  // Hidden by default: a tier is chosen by whoever writes the task, not picked
-  // from the @ menu. Without this the menu lists every specialist once per tier.
-  fm = setScalar(fm, "hidden", "true")
-  if (!/^color:/m.test(fm)) {
-    const name = ""
-    fm = setScalar(fm, "color", name ? yamlColor(agentColor(name)) : yamlColor(agentColor("engineer")))
-  }
-  return `---\n${fm}\n---\n${body}`
-}
-
-/**
- * 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(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`
-}
-
-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
-  } catch {
-    // file missing, write it
-  }
-  const tmpPath = `${filePath}.tmp`
-  await fs.writeFile(tmpPath, content, "utf-8")
-  await fs.rename(tmpPath, filePath)
-}
-
-export default Plugin.define({
-  id: "pc.subagent-tiers",
-  async setup(ctx) {
-    const root = ctx.location.directory
-    const agentsDir = path.join(root, ".opencode", "agents")
-
-    try {
-      const [user, team] = await Promise.all([
-        readJson(path.join(root, ".opencode", "harness.user.json")),
-        readJson(path.join(root, ".opencode", "harness.json")),
-      ])
-      const models = {}
-      for (const tier of TIERS) {
-        models[tier] = user?.models?.[tier] ?? team?.models?.[tier] ?? null
-      }
-      const available = TIERS.filter(t => models[t])
-
-      const { templates, variantFiles, hasFullstack } = await scanEngineers(agentsDir)
-
-      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)
-          console.error("[pc-subagent-tiers] Normalized fullstack-engineer.md (V2 subagent)")
-        }
-
-        for (const [name, spec] of Object.entries(PRIMARIES)) {
-          await writeIfChanged(
-            path.join(agentsDir, `${name}.md`),
-            buildPrimary(spec, fullstack, models[spec.tier]),
-          )
-        }
-        console.error(`[pc-subagent-tiers] Wrote primaries: build (${models.build ?? "session model"}), plan and planner (${models.plan ?? "session model"})`)
-      } else {
-        console.error(`[pc-subagent-tiers] ${FULLSTACK_TEMPLATE} missing: build and plan not generated`)
-      }
-
-      const keepSet = new Set()
-      const variantsToWrite = []
-      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)
-          console.error(`[pc-subagent-tiers] Normalized ${name}.md (V2 subagent)`)
-        }
-        for (const tier of available) {
-          const file = `${name}.${tier}.md`
-          variantsToWrite.push({ file, path: path.join(agentsDir, file), content: buildVariant(content, models[tier]) })
-          keepSet.add(file)
-        }
-      }
-
-      await Promise.all(variantsToWrite.map(v => writeIfChanged(v.path, v.content)))
-      await Promise.all(
-        variantFiles.filter(f => !keepSet.has(f)).map(f => fs.unlink(path.join(agentsDir, f)).catch(() => {})),
-      )
-
-      if (variantsToWrite.length > 0) {
-        console.error(`[pc-subagent-tiers] Created ${variantsToWrite.length} variant files (${templates.length} engineers x ${available.length} tiers)`)
-      } else if (templates.length > 0) {
-        console.error(`[pc-subagent-tiers] No variants created. Models: ${JSON.stringify(models)}`)
-      }
-
-      // Best effort: if V2 already discovered these agents (same startup), pin
-      // the primaries' model and plan's read-only permissions in memory too.
-      if (typeof ctx.agent?.transform === "function") {
-        await ctx.agent.transform(editor => {
-          for (const [id, spec] of Object.entries(PRIMARIES)) {
-            const existing = editor.get(id)
-            if (!existing) continue
-            const model = models[spec.tier]
-            if (model) {
-              try {
-                existing.model = Model.Ref.parse(model)
-              } catch {
-                // invalid model ref; leave undefined so session model applies
-              }
-            }
-            existing.mode = spec.mode ?? "primary"
-            existing.description = spec.description
-            if (spec.permissions) existing.permissions = spec.permissions
-          }
-        })
-        await ctx.agent.reload?.()
-      }
-    } catch (error) {
-      console.error(`[pc-subagent-tiers] Error: ${error?.message}`)
-    }
-  },
-})
+// pc-subagent-tiers: on startup, generates the primary agents, the spawnable
+// planner alias and the tier variants from *-engineer.md templates, then pins
+// the primaries in memory. The generation itself lives in
+// pc-subagent-tiers-core.js so a CI pre-start step can write the same files
+// before OpenCode builds its task enum.
+
+import { Plugin, Model } from "@opencode/plugin";
+import { PRIMARIES, generateAgents } from "./pc-subagent-tiers-core.js";
+
+export default Plugin.define({
+  id: "pc.subagent-tiers",
+  async setup(ctx) {
+    const root = ctx.location.directory;
+
+    try {
+      const result = await generateAgents({ root });
+
+      console.error(
+        `[pc-subagent-tiers] Wrote primaries: build (${result.models.build ?? "session model"}), plan and planner (${result.models.plan ?? "session model"})`,
+      );
+      if (result.variants.length > 0) {
+        console.error(
+          `[pc-subagent-tiers] Created ${result.variants.length} variant files (${result.templates.length} engineers x ${Object.values(result.models).filter(Boolean).length} tiers)`,
+        );
+      } else if (result.templates.length > 0) {
+        console.error(`[pc-subagent-tiers] No variants created. Models: ${JSON.stringify(result.models)}`);
+      }
+      for (const warning of result.warnings) {
+        console.error(`[pc-subagent-tiers] Warning: ${warning}`);
+      }
+
+      if (typeof ctx.agent?.transform === "function") {
+        await ctx.agent.transform((editor) => {
+          for (const [id, spec] of Object.entries(PRIMARIES)) {
+            const existing = editor.get(id);
+            if (!existing) continue;
+            const model = result.models[spec.tier];
+            if (model) {
+              try {
+                existing.model = Model.Ref.parse(model);
+              } catch {
+                // invalid model ref; leave undefined so the session model applies
+              }
+            }
+            existing.mode = spec.mode ?? "primary";
+            existing.description = spec.description;
+            if (spec.permissions) existing.permissions = spec.permissions;
+          }
+        });
+        await ctx.agent.reload?.();
+      }
+    } catch (error) {
+      console.error(`[pc-subagent-tiers] Error: ${error?.message}`);
+    }
+  },
+});

package/harness/.opencode/scripts/harness-doctor.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Print the effective model routing and the generated agents. --strict exits 1
+// on any warning, a missing planner-sub, or a manifest older than its configs.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const rootIndex = args.indexOf("--root");
+const root = rootIndex !== -1 ? path.resolve(args[rootIndex + 1]) : process.cwd();
+const strict = args.includes("--strict");
+const manifestPath = path.join(root, ".opencode", "harness-models.json");
+
+function fail(message, code = 1) {
+  console.error(message);
+  process.exit(code);
+}
+
+if (!fs.existsSync(manifestPath)) {
+  fail(`harness-doctor: ${manifestPath} is missing; run node .opencode/scripts/sync-agents.mjs`, 2);
+}
+
+let manifest;
+try {
+  manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+} catch (error) {
+  fail(`harness-doctor: ${manifestPath} is not valid JSON: ${error.message}`, 2);
+}
+
+const models = manifest.models ?? {};
+const sources = manifest.source ?? {};
+const warnings = Array.isArray(manifest.warnings) ? manifest.warnings : [];
+const agents = manifest.agents ?? {};
+const planner = agents["planner-sub"] ?? agents.planner;
+const plannerFile = planner?.file ? path.join(root, ".opencode", "agents", planner.file) : null;
+const plannerExists = plannerFile ? fs.existsSync(plannerFile) : false;
+
+console.log("Model routing");
+console.log(`  ${"tier".padEnd(6)} ${"effective".padEnd(40)} source`);
+for (const tier of ["plan", "build", "fast"]) {
+  console.log(`  ${tier.padEnd(6)} ${String(models[tier] ?? "(session)").padEnd(40)} ${sources[tier] ?? "missing"}`);
+}
+console.log(`  ${"lead".padEnd(6)} ${"session model (ci-workflow-agent)".padEnd(40)} session`);
+console.log(`  ${"planner".padEnd(6)} ${String(planner?.model ?? "(session)").padEnd(40)} ${planner?.mode ?? "missing"}`);
+console.log(`  planner file: ${plannerFile ? `${planner.file}${plannerExists ? "" : " (missing)"}` : "missing"}`);
+console.log(`  agents: ${Object.keys(agents).length} entries, ${warnings.length} warning(s)`);
+
+for (const warning of warnings) console.error(`warning: ${warning}`);
+
+if (strict && (!planner || !plannerExists || warnings.length > 0)) {
+  process.exit(1);
+}

package/harness/.opencode/scripts/harness-doctor.test.mjs

@@ -0,0 +1,58 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPT = path.join(HERE, "harness-doctor.mjs");
+let root;
+
+function fixture(manifest) {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), "harness-doctor-"));
+  const opencode = path.join(root, ".opencode");
+  fs.mkdirSync(path.join(opencode, "agents"), { recursive: true });
+  fs.writeFileSync(path.join(opencode, "harness-models.json"), JSON.stringify(manifest, null, 2));
+  return opencode;
+}
+
+afterEach(() => {
+  if (root) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe("harness doctor", () => {
+  it("prints the effective routing and the planner alias", () => {
+    fixture({
+      models: {
+        plan: "plainconcepts/glm-5-3",
+        build: "plainconcepts/glm-5-2",
+        fast: "plainconcepts/glm-5-2",
+      },
+      source: { plan: "team", build: "team", fast: "team" },
+      agents: {
+        "planner-sub": { file: "planner-sub.md", mode: "subagent", model: "plainconcepts/glm-5-3" },
+      },
+      warnings: [],
+    });
+    fs.writeFileSync(path.join(root, ".opencode", "agents", "planner-sub.md"), "---\nmode: subagent\n---\n");
+
+    const output = execFileSync(process.execPath, [SCRIPT, "--root", root, "--strict"], { encoding: "utf8" });
+    expect(output).toContain("Model routing");
+    expect(output).toContain("plainconcepts/glm-5-3");
+    expect(output).toContain("planner-sub.md");
+  });
+
+  it("fails strict when the planner alias is missing", () => {
+    fixture({
+      models: { plan: "p/plan", build: "p/build", fast: "p/fast" },
+      source: { plan: "team", build: "team", fast: "team" },
+      agents: {},
+      warnings: [],
+    });
+
+    const result = spawnSync(process.execPath, [SCRIPT, "--root", root, "--strict"], { encoding: "utf8" });
+    expect(result.status).toBe(1);
+    expect(result.stdout).toContain("planner file: missing");
+  });
+});

package/harness/.opencode/scripts/sync-agents.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Generate the build/plan/planner/planner-sub agents and the tier variants
+// before OpenCode starts. CI runs this in a pre-agent step so the task tool's
+// enum includes them from the first turn. Local users can run it too.
+
+import path from "node:path";
+import { generateAgents } from "../plugins/pc-subagent-tiers-core.js";
+
+const args = process.argv.slice(2);
+const rootIndex = args.indexOf("--root");
+const root = rootIndex !== -1 ? path.resolve(args[rootIndex + 1]) : process.cwd();
+const strict = args.includes("--strict");
+
+try {
+  const result = await generateAgents({ root });
+  console.log(`Model routing (${path.join(root, ".opencode", "harness-models.json")})`);
+  for (const tier of ["plan", "build", "fast"]) {
+    console.log(`  ${tier.padEnd(6)} ${String(result.models[tier] ?? "(session)").padEnd(40)} ${result.sources[tier]}`);
+  }
+  console.log(
+    `  agents ${result.templates.length} engineer template(s), ${result.variants.length} variant(s), ` +
+      `${result.hasFullstack ? "planner + planner-sub" : "planner missing (no fullstack)"}`,
+  );
+  for (const warning of result.warnings) console.error(`warning: ${warning}`);
+  if (strict && result.warnings.length > 0) process.exit(1);
+} catch (error) {
+  console.error(`sync-agents: ${error?.message ?? error}`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.8.3",
+  "version": "3.9.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/skills/pc-make-user-model/SKILL.md

@@ -51,6 +51,6 @@ An id with no `/` in it is malformed; confirm before writing it:
   file: <path written>
 ```
 
-The change lands on the next opencode start, when `pc-subagent-tiers` reads the configs and rebuilds the tier variants.
+The change lands on the next opencode start, when `pc-subagent-tiers` reads the configs and rebuilds the tier variants. For CI or a non-interactive run, `node .opencode/scripts/sync-agents.mjs` rebuilds the agents and `.opencode/harness-models.json`; `node .opencode/scripts/harness-doctor.mjs --strict` prints and validates the effective routing.
 
 Arguments: `$ARGUMENTS`

package/skills/pc-plan-apply/SKILL.md

@@ -37,13 +37,13 @@ Core rule: push, don't pull. A worker is born with its work: every `task()` spaw
 
 **1. Branch.** Create `feature/{change-slug}` if not already on one. (Skip this step when the caller passed `start_from: load-plan`.)
 
-**2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Inspect `.opencode/agents/` for each base engineer and its generated `.<tier>.md` variants. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn: `pc-subagent-tiers` resolves its model at startup and registers it as `mode: subagent`. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5, enforced by `pc-subagent-monitor`).
+**2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Read `.opencode/harness-models.json` (written by `pc-subagent-tiers` and `node .opencode/scripts/sync-agents.mjs`) for the effective model of every tier and the generated agent files. If the manifest is missing, run `node .opencode/scripts/sync-agents.mjs` once; if it still fails, stop. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn; its model is the manifest's, not `harness.json`'s. `harness.user.json` overrides `harness.json`, so never report a model from `harness.json` alone. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5, enforced by `pc-subagent-monitor`).
 
 When `.platform/contract.yml` declares `reuse` and the change's `proposal.md` has no `## What is reused` section, stop the APPLY stage and report it: the plan never checked what the template already ships. Otherwise every spawn prompt in step 7 carries that section.
 
-Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, or its tier variant is unavailable, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
+Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, its tier variant is unavailable, or the manifest has no effective model for its tier, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
 
-**3. Hydrate the Todo board.** `todowrite` one item per task: `pending`. The Todo pane is the visible subagent board (opencode plugins cannot draw a custom pane, so the native Todo widget is the live UI). While a task is in flight, its label must carry the worker: `<agent> · <model>`: so the pane shows which agent on which model is doing what. The Todo list is a projection only: never read it for recovery; rebuild it from `tasks.md` and git and `.opencode/harness-run.json`.
+**3. Hydrate the Todo board.** `todowrite` one item per task: `pending`. The Todo pane is the visible subagent board (opencode plugins cannot draw a custom pane, so the native Todo widget is the live UI). While a task is in flight, its label must carry the worker: `<agent> · <model>`, with the model read from `.opencode/harness-models.json`, so the pane shows which agent on which model is doing what. The Todo list is a projection only: never read it for recovery; rebuild it from `tasks.md` and git and `.opencode/harness-run.json`.
 
 **4. Worker context.** Before each wave, derive file-disjointness from `touches:` globs and `git diff`.
 

package/skills/pc-plan-propose/task-annotation.md

@@ -7,7 +7,7 @@ Pick a tier for each task based on complexity:
 - `fast`: light work: i18n keys, config changes, env variables, navigation links, simple markup, verification runs
 - `plan`: reserved for orchestration, do not use for implementation tasks
 
-The tier suffix is appended to the agent name with a dot (e.g. `backend-engineer.build`). This is the agent name you write in the annotation. The `pc-subagent-tiers` plugin resolves the model at startup from `models[<tier>]`.
+The tier suffix is appended to the agent name with a dot (e.g. `backend-engineer.build`). This is the agent name you write in the annotation. The `pc-subagent-tiers` plugin resolves the model at startup from `models[<tier>]`, with `.opencode/harness.user.json` overriding `.opencode/harness.json`, and writes the effective value to `.opencode/harness-models.json`. `tasks.md` names the tier, never a model id.
 
 ## depends_on