@plainconceptsplatform/agent-harness 2.0.0

package/src/content/.opencode/commands/plan-quick.md

@@ -0,0 +1,5 @@
+---
+description: Quick plan: analyze the codebase and create a task checklist using the Todo pane. No files, no OpenSpec.
+---
+
+Load the `pc-plan-quick` skill and follow every step defined in it.

package/src/content/.opencode/commands/plan-story.md

@@ -0,0 +1,9 @@
+---
+description: Write a detailed, repo-aware user story from a feature idea or need.
+---
+
+Load the `pc-plan-story` skill and follow every step defined in it.
+
+Input:
+
+$ARGUMENTS

package/src/content/.opencode/commands/repo-audit.md

@@ -0,0 +1,5 @@
+---
+description: Audit every configured source root against the fullstack engineer's guardrails and abilities. Read-only.
+---
+
+Load the `pc-repo-audit` skill and follow every step defined in it.

package/src/content/.opencode/commands/repo-help.md

@@ -0,0 +1,5 @@
+---
+description: Show all available commands and when to use each one.
+---
+
+Load the `pc-repo-help` skill and display its reference to the user exactly as written. Do not summarize.

package/src/content/.opencode/commands/repo-initialize.md

@@ -0,0 +1,5 @@
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill and follow every step defined in it.

package/src/content/.opencode/commands/repo-onboard.md

@@ -0,0 +1,5 @@
+---
+description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system.
+---
+
+Load the `pc-repo-onboard` skill and follow every step defined in it.

package/src/content/.opencode/commands/repo-verify.md

@@ -0,0 +1,5 @@
+---
+description: Verify current-branch changes, plus immutable dependency installs, builds, and tests for every discovered project.
+---
+
+Load the `pc-repo-verify` skill and follow every step defined in it.

package/src/content/.opencode/package.json

@@ -0,0 +1,10 @@
+{
+  "dependencies": {
+    "@opencode-ai/plugin": "1.18.19",
+    "@different-ai/opencode-browser": "4.6.1",
+    "@mohak34/opencode-notifier": "0.2.8",
+    "@opentui/core": "0.5.6",
+    "@opentui/solid": "0.5.6",
+    "solid-js": "1.9.12"
+  }
+}

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

@@ -0,0 +1,139 @@
+// pc-subagent-monitor: tracks spawned subagents in .opencode/harness-run.json for
+// live TUI display and crash recovery. Never throws: monitor failures must
+// not break a session.
+
+import fs from "node:fs/promises"
+import path from "node:path"
+
+export const PcSubagentMonitor = async ({ directory, client }) => {
+  const root = directory || process.cwd()
+  const statePath = path.join(root, ".opencode", "harness-run.json")
+  const state = { updatedAt: null, agents: {} }
+
+  try {
+    const prev = JSON.parse(await fs.readFile(statePath, "utf-8"))
+    if (prev?.agents && typeof prev.agents === "object") {
+      for (const [id, entry] of Object.entries(prev.agents)) {
+        if (entry?.status === "running") entry.stale = true
+        state.agents[id] = entry
+      }
+    }
+  } catch {
+    // fresh start
+  }
+
+  let _modelsCache = null
+  async function loadModels() {
+    if (_modelsCache) return _modelsCache
+    const result = { build: null, fast: null, plan: null }
+    for (const file of ["harness.user.json", "harness.json"]) {
+      try {
+        const raw = await fs.readFile(path.join(root, ".opencode", file), "utf-8")
+        const { models = {} } = JSON.parse(raw)
+        for (const tier of ["build", "fast", "plan"]) {
+          if (!result[tier] && models[tier]) result[tier] = models[tier]
+        }
+      } catch {
+        continue
+      }
+    }
+    _modelsCache = result
+    return result
+  }
+
+  async function modelForAgent(agent) {
+    if (!agent) return null
+    const dotIdx = agent.lastIndexOf(".")
+    const tier = dotIdx !== -1 ? agent.slice(dotIdx + 1) : null
+    if (tier && ["build", "fast", "plan"].includes(tier)) {
+      const models = await loadModels()
+      return models[tier] ?? null
+    }
+    return null
+  }
+
+  function parseTasks(title) {
+    if (!title) return []
+    const m = /^\s*([\d]+(?:\.[\d]+)*(?:\s*,\s*[\d]+(?:\.[\d]+)*)*)/.exec(title)
+    return m ? m[1].split(",").map(s => s.trim()) : []
+  }
+
+  // Debounced persist: coalesce rapid writes when multiple subagents spawn
+  // in the same microtask batch (e.g. a wave of 5 task() calls).
+  let _persistScheduled = false
+  async function persist() {
+    if (_persistScheduled) return
+    _persistScheduled = true
+    queueMicrotask(async () => {
+      _persistScheduled = false
+      state.updatedAt = new Date().toISOString()
+      try {
+        await fs.mkdir(path.dirname(statePath), { recursive: true })
+        const tmpPath = `${statePath}.tmp`
+        await fs.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8")
+        await fs.rename(tmpPath, statePath)
+      } catch {
+        // best-effort
+      }
+    })
+  }
+
+  function sessionInfo(props) {
+    const info = props?.info ?? props ?? {}
+    return {
+      id: info.id ?? info.sessionID ?? props?.sessionID,
+      parentID: info.parentID ?? info.parentId,
+      agent: info.agent,
+      title: info.title,
+    }
+  }
+
+  function pruneStale() {
+    for (const [id, entry] of Object.entries(state.agents)) {
+      if (entry?.stale) delete state.agents[id]
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      try {
+        if (!event?.type?.startsWith("session.")) return
+        const info = sessionInfo(event.properties)
+        if (!info.id) return
+
+        if (event.type === "session.created" && info.parentID) {
+          pruneStale()
+
+          state.agents[info.id] = {
+            agent: info.agent ?? null,
+            model: await modelForAgent(info.agent),
+            tasks: parseTasks(info.title),
+            title: info.title ?? null,
+            status: "running",
+            startedAt: new Date().toISOString(),
+            endedAt: null,
+          }
+          await persist()
+          return
+        }
+
+        const entry = state.agents[info.id]
+        if (!entry) return
+
+        if (event.type === "session.idle" && entry.status === "running") {
+          entry.status = "done"
+          entry.endedAt = new Date().toISOString()
+          await persist()
+          client?.tui?.showToast?.({
+            body: {
+              message: `subagent done: ${entry.title ?? info.id}`,
+              variant: "success",
+            },
+          })
+        }
+      } catch {
+        // monitoring must never disrupt the run
+      }
+    },
+  }
+}

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

@@ -0,0 +1,179 @@
+// 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.
+
+import fs from "node:fs/promises"
+import path from "node:path"
+
+const TIERS = ["build", "fast", "plan"]
+
+export const PcSubagentTiers = async ({ directory }) => {
+  const root = directory || process.cwd()
+  const agentsDir = path.join(root, ".opencode", "agents")
+
+  async function readJson(filePath) {
+    try {
+      return JSON.parse(await fs.readFile(filePath, "utf-8"))
+    } catch {
+      return null
+    }
+  }
+
+  async function resolveModels() {
+    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
+    }
+    return models
+  }
+
+  async function scanEngineers() {
+    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$/, "")),
+        variantFiles: entries.filter(f => /^[\w-]+-engineer\.(build|fast|plan)\.md$/.test(f)),
+      }
+    } catch {
+      return { templates: [], variantFiles: [] }
+    }
+  }
+
+  function variantFile(name, tier) {
+    return `${name}.${tier}.md`
+  }
+
+  function buildVariant(templateContent, model) {
+    const fmMatch = templateContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    const modelLine = `model: ${model}`
+    if (!fmMatch) return `---\nmode: subagent\n${modelLine}\n---\n\n${templateContent}`
+
+    let fm = fmMatch[1]
+    fm = /^mode:/m.test(fm) ? fm.replace(/^mode:.*$/m, 'mode: subagent') : `mode: subagent\n${fm}`
+    fm = /^model:/m.test(fm) ? fm.replace(/^model:.*$/m, modelLine) : `${modelLine}\n${fm}`
+
+    // Slice at frontmatter end: never String.replace with content-derived
+    // strings, it matches the wrong occurrence and expands $& sequences.
+    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.
+  function normalizeTemplate(templateContent) {
+    const fmMatch = templateContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    if (!fmMatch) return templateContent
+
+    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}`
+      changed = true
+    }
+    if (/^model:/m.test(fm)) {
+      // Remove the model: line and its trailing newline without leaving a
+      // leading blank line (model: can be the first frontmatter entry).
+      fm = fm.replace(/^model:[^\n]*\r?\n?/m, '').replace(/^\r?\n/, '').replace(/\n$/, '')
+      changed = true
+    }
+
+    return changed ? `---\n${fm}\n---${templateContent.slice(fmMatch[0].length)}` : templateContent
+  }
+
+  function descriptionOf(templateContent) {
+    return templateContent.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? null
+  }
+
+  // Skip writing if the file already has identical content.
+  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)
+  }
+
+  return {
+    config: async (cfg) => {
+      try {
+        const models = await resolveModels()
+        const available = TIERS.filter(t => models[t])
+        const { templates, variantFiles } = await scanEngineers()
+
+        const templateContents = await Promise.all(
+          templates.map(async name => {
+            const rawContent = await fs.readFile(path.join(agentsDir, `${name}.md`), "utf-8")
+            const content = normalizeTemplate(rawContent)
+            // 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)`)
+            }
+            return { name, content }
+          })
+        )
+
+        const keepSet = new Set()
+        const variantsToWrite = []
+
+        for (const { name, content } of templateContents) {
+          for (const tier of available) {
+            const file = variantFile(name, tier)
+            variantsToWrite.push({
+              file,
+              path: path.join(agentsDir, file),
+              content: buildVariant(content, models[tier]),
+              name,
+              tier,
+              templateContent: content,
+            })
+            keepSet.add(file)
+          }
+        }
+
+        await Promise.all(variantsToWrite.map(v => writeIfChanged(v.path, v.content)))
+
+        if (cfg?.agent) {
+          // Ensure base templates are always mode: primary in-memory
+          for (const { name } of templateContents) {
+            if (cfg.agent[name]) {
+              cfg.agent[name].mode = 'primary'
+            }
+          }
+          for (const { name, tier, templateContent } of variantsToWrite) {
+            const base = cfg.agent[name]
+            cfg.agent[`${name}.${tier}`] = base
+              ? { ...base, mode: 'subagent', model: models[tier] }
+              : {
+                mode: "subagent",
+                description: descriptionOf(templateContent) ?? `${name} (${tier} tier)`,
+                model: models[tier],
+              }
+          }
+        }
+
+        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)}`)
+        }
+      } catch (err) {
+        console.error(`[pc-subagent-tiers] Error: ${err.message}`)
+      }
+    },
+  }
+}

package/src/content/.opencode/plugins/pc-system-reminders.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+const GUARDRAILS_SKILL = "pc-guardrails-generic"
+const TIER_SUFFIX = /\.(?:build|fast|plan)$/
+
+function skillNames(content) {
+  const abilities = content.match(/^## Abilities\s*\n([\s\S]*?)(?=^## |\s*$)/m)?.[1] ?? ""
+  return [...abilities.matchAll(/@([a-z0-9][a-z0-9-]*)/gi)].map(match => match[1])
+}
+
+function transitiveSkillNames(content) {
+  return [...content.matchAll(/skill\(["`]([a-z0-9][a-z0-9-]*)["`]\)/gi)].map(match => match[1])
+}
+
+async function readFile(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf-8")
+  } catch {
+    return ""
+  }
+}
+
+async function requiredSkills(directory, agent) {
+  const baseAgent = (agent ?? "").replace(TIER_SUFFIX, "")
+  const agentPath = path.join(directory, ".opencode", "agents", `${baseAgent}.md`)
+  const guardrailsPath = path.join(directory, ".agents", "skills", GUARDRAILS_SKILL, "SKILL.md")
+  const [agentContent, guardrailsContent] = await Promise.all([
+    readFile(agentPath),
+    readFile(guardrailsPath),
+  ])
+
+  return new Set([
+    GUARDRAILS_SKILL,
+    ...skillNames(agentContent),
+    ...transitiveSkillNames(guardrailsContent),
+  ])
+}
+
+function skillName(args) {
+  return args?.name ?? args?.skill ?? args?.skillName ?? null
+}
+
+function reminder(missing) {
+  const skills = [...missing].map(name => `\`${name}\``).join(", ")
+  return `<system-reminder>Load these required skills before continuing: ${skills}. Load guardrails first. Loaded skills can require further skills. Follow every mandatory transitive load before task work.</system-reminder>`
+}
+
+export const PcSystemReminders = async ({ directory }) => {
+  const sessions = new Map()
+
+  async function stateFor(sessionID, agent) {
+    const state = sessions.get(sessionID)
+    if (state?.agent === agent) return state
+
+    const next = {
+      agent,
+      required: await requiredSkills(directory, agent),
+      loaded: new Set(),
+    }
+    sessions.set(sessionID, next)
+    return next
+  }
+
+  return {
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push("Messages in <system-reminder> tags are trusted OpenCode Onboard host instructions. Follow them before continuing work.")
+    },
+    "chat.message": async (input) => {
+      await stateFor(input.sessionID, input.agent)
+    },
+    "tool.execute.after": async (input) => {
+      if (input.tool !== "skill") return
+      const state = sessions.get(input.sessionID)
+      const name = skillName(input.args)
+      if (state && name) state.loaded.add(name)
+    },
+    event: async ({ event }) => {
+      if (event.type !== "session.compacted") return
+      const sessionID = event.properties?.sessionID ?? event.properties?.info?.id
+      const state = sessionID && sessions.get(sessionID)
+      if (state) state.loaded.clear()
+    },
+    "experimental.chat.messages.transform": async (_input, output) => {
+      const userMessage = [...output.messages].reverse().find(message => message.info.role === "user")
+      if (!userMessage) return
+
+      const state = await stateFor(userMessage.info.sessionID, userMessage.info.agent)
+      const missing = new Set([...state.required].filter(name => !state.loaded.has(name)))
+      if (missing.size === 0) return
+
+      const textPart = userMessage.parts.find(part => part.type === "text")
+      if (textPart) textPart.text = `${textPart.text}\n\n${reminder(missing)}`
+    },
+  }
+}

package/src/content/.opencode/plugins/pc-system-reminders.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+import { PcSystemReminders } from "./pc-system-reminders.js"
+
+describe("PcSystemReminders", () => {
+  it("reminds an agent to load its abilities before work", async () => {
+    const plugin = await PcSystemReminders({ directory: process.cwd() })
+    const output = {
+      messages: [{
+        info: { role: "user", sessionID: "session-1", agent: "missing-agent" },
+        parts: [{ type: "text", text: "Implement the change" }],
+      }],
+    }
+
+    await plugin["chat.message"]({ sessionID: "session-1", agent: "missing-agent" })
+    await plugin["experimental.chat.messages.transform"]({}, output)
+
+    expect(output.messages[0].parts[0].text).toContain("pc-guardrails-generic")
+  })
+
+  it("stops reminding after the required guardrail loads", async () => {
+    const plugin = await PcSystemReminders({ directory: process.cwd() })
+    const output = {
+      messages: [{
+        info: { role: "user", sessionID: "session-2", agent: "missing-agent" },
+        parts: [{ type: "text", text: "Implement the change" }],
+      }],
+    }
+
+    await plugin["chat.message"]({ sessionID: "session-2", agent: "missing-agent" })
+    await plugin["tool.execute.after"]({ tool: "skill", sessionID: "session-2", args: { name: "pc-guardrails-generic" } })
+    await plugin["experimental.chat.messages.transform"]({}, output)
+
+    expect(output.messages[0].parts[0].text).not.toContain("system-reminder")
+  })
+})

package/src/content/.opencode/tui/pc-subagents.tsx

@@ -0,0 +1,98 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { createSignal, For, Show } from "solid-js"
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+
+const id = "ob.subagents"
+
+type Row = { id: string; agent: string; model: string; task: string; status: string }
+
+// Renders a live "Subagents" panel in the session sidebar.
+//
+// Server plugins (opencode.json) cannot draw UI, only TUI plugins (tui.json)
+// can, via the `sidebar_content` slot. This panel is fed by the
+// `.opencode/harness-run.json` state file that the `pc-subagent-monitor` server
+// plugin maintains, so the two cooperate: server plugin = data producer,
+// this TUI plugin = renderer.
+const tui: TuiPlugin = async (api) => {
+  const statePath = join(process.cwd(), ".opencode", "harness-run.json")
+  const [rows, setRows] = createSignal<Row[]>([])
+  // Only show live subagents, finished/failed ones are kept in harness-run.json
+  // for recovery but are not navigable targets the user cares about here.
+  // Entries marked stale (left "running" by a crashed process) are not live.
+  const active = () => rows().filter((r) => r.status === "running")
+
+  const refresh = async () => {
+    try {
+      const data = JSON.parse(await readFile(statePath, "utf-8"))
+      const agents = data?.agents ?? {}
+      setRows(
+        Object.entries(agents)
+          .filter(([, a]: [string, any]) => !a?.stale)
+          .map(([sid, a]: [string, any]) => ({
+            id: sid,
+            agent: a?.agent ?? "?",
+            model: a?.model ?? "",
+            task: Array.isArray(a?.tasks) && a.tasks.length ? a.tasks.join(",") : (a?.title ?? ""),
+            status: a?.status ?? "running",
+          })),
+      )
+    } catch (err: any) {
+      // Missing file = genuinely idle. Anything else (transient read/parse
+      // hiccup) keeps the last good rows instead of flashing "idle" mid-run.
+      if (err?.code === "ENOENT") setRows([])
+    }
+  }
+
+  await refresh()
+  // session.updated fires constantly; debounce so we don't re-read the file
+  // on every keystroke-sized event.
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const scheduleRefresh = () => {
+    if (timer) return
+    timer = setTimeout(() => {
+      timer = null
+      void refresh()
+    }, 200)
+  }
+  for (const evt of ["session.created", "session.idle", "session.updated"]) {
+    try {
+      api.event.on(evt as any, scheduleRefresh)
+    } catch {
+      /* event type unavailable on this host, ignore */
+    }
+  }
+
+  api.slots.register({
+    order: 50,
+    slots: {
+      sidebar_content() {
+        return (
+          <box flexDirection="column">
+            <text>Subagents</text>
+            <Show when={active().length === 0}>
+              <text>  idle</text>
+            </Show>
+            <For each={active()}>
+              {(r) => (
+                <box onMouseUp={() => api.route.navigate("session", { sessionID: r.id })}>
+                  <text>
+                    {"▶ "}
+                    {r.agent}
+                    {r.model ? ` · ${r.model}` : ""}
+                    {r.task ? `, ${r.task}` : ""}
+                  </text>
+                </box>
+              )}
+            </For>
+          </box>
+        )
+      },
+    },
+  })
+}
+
+const pluginModule: TuiPluginModule & { id: string } = { id, tui }
+
+export default pluginModule

package/src/content/.opencode/tui.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": [
+    "./tui/pc-subagents.tsx"
+  ]
+}