@plainconceptsplatform/agent-harness 3.1.1 → 3.2.0

package/cli/steps/metadata/index.js

@@ -1,115 +1,115 @@
-import { execa } from 'execa'
-import fse from 'fs-extra'
-import path from 'path'
-import { createRequire } from 'node:module'
-import { header, success, warn } from '../../utils/exec.js'
-import { configPath } from '../../utils/paths.js'
-
-const require = createRequire(import.meta.url)
-const { version: harnessVersion } = require('../../../package.json')
-
-function clampConcurrency(n) {
-  const v = Number(n)
-  if (!Number.isFinite(v)) return 3
-  return Math.min(5, Math.max(1, Math.round(v)))
-}
-
-async function detectOpencodeVersion() {
-  try {
-    const result = await execa('opencode', ['--version'], { reject: false })
-    if (result.exitCode !== 0) return null
-    // `opencode --version` prints "opencode v2.0.22" on some builds and "2.0.22" on others;
-    // record the bare version so the field does not churn between machines.
-    const output = (result.stdout || result.stderr || '').trim()
-    return output.match(/\d+\.\d+\.\d+[\w.-]*/)?.[0] ?? (output || null)
-  } catch {
-    return null
-  }
-}
-
-export async function writeHarnessConfig(data) {
-  header('Step 10, Writing onboarding metadata')
-
-  const opencodeVersion = await detectOpencodeVersion()
-  const cwd = data.cwd ?? process.cwd()
-  const target = configPath(cwd)
-
-  // Read the existing file so load-bearing config (models, maxConcurrent)
-  // is preserved across metadata refreshes when not explicitly provided.
-  const existing = await fse.readJson(target).catch(() => null)
-
-  const selectedModels = Object.fromEntries(
-    Object.entries({
-      plan: data.planModel,
-      build: data.buildModel,
-      fast: data.fastModel,
-    }).filter(([, value]) => value)
-  )
-  const models = Object.keys(selectedModels).length > 0
-    ? { ...existing?.models, ...selectedModels }
-    : existing?.models ?? null
-  const maxConcurrent = clampConcurrency(data.maxConcurrentAgents ?? existing?.agents?.maxConcurrent ?? 3)
-
-  const optionalTools = data.optionalTools ?? existing?.tools ?? {}
-  const { caveman: _caveman, ...existingTools } = existing?.tools ?? {}
-  const tools = {
-    rtk: !!(optionalTools.rtk?.optedIn ?? optionalTools.rtk),
-    quota: !!(optionalTools.quota?.optedIn ?? optionalTools.quota),
-    simpleEnglish: !!(
-      optionalTools.simpleEnglish?.optedIn ?? optionalTools.simpleEnglish ??
-      optionalTools.caveman?.optedIn ?? optionalTools.caveman
-    ),
-    codegraph: !!(optionalTools.codegraph?.optedIn ?? optionalTools.codegraph),
-    memory: !!(optionalTools.memory?.optedIn ?? optionalTools.memory),
-    // humanizer was missing here, so a selection never survived a metadata
-    // write and patchGuardrails always saw it as off, leaving its marker
-    // section empty however the project was actually set up.
-    humanizer: !!(optionalTools.humanizer?.optedIn ?? optionalTools.humanizer),
-  }
-
-  const payload = {
-    ...existing,
-    // Never lower a schema version a repository already records.
-    version: Math.max(2, Number(existing?.version) || 0),
-    generatedAt: new Date().toISOString(),
-    harnessVersion,
-    opencodeVersion,
-
-    platform: {
-      ...existing?.platform,
-      backlog: data.backlogPlatform ?? 'none',
-      repo: data.repoPlatform ?? 'none',
-    },
-
-    ...(models ? { models } : {}),
-
-    agents: {
-      ...existing?.agents,
-      maxConcurrent,
-    },
-
-    source: {
-      ...existing?.source,
-      mode: data.sourceMode ?? 'current',
-      roots: data.sourceRoots ?? [],
-    },
-
-    tools: { ...existingTools, ...tools },
-
-    preexisting: {
-      ...existing?.preexisting,
-      design: !!data.hasDesign,
-      architecture: !!data.hasArchitecture,
-      openspec: !!data.hasOpenspec,
-    },
-  }
-
-  try {
-    await fse.ensureDir(path.dirname(target))
-    await fse.writeJson(target, payload, { spaces: 2 })
-    success('Wrote .opencode/harness.json')
-    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
-  } catch (err) {
-    warn(`Could not write onboarding metadata: ${err.message}`)
-  }
-}
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { createRequire } from 'node:module'
+import { header, success, warn } from '../../utils/exec.js'
+import { configPath } from '../../utils/paths.js'
+
+const require = createRequire(import.meta.url)
+const { version: harnessVersion } = require('../../../package.json')
+
+function clampConcurrency(n) {
+  const v = Number(n)
+  if (!Number.isFinite(v)) return 3
+  return Math.min(5, Math.max(1, Math.round(v)))
+}
+
+async function detectOpencodeVersion() {
+  try {
+    const result = await execa('opencode', ['--version'], { reject: false })
+    if (result.exitCode !== 0) return null
+    // `opencode --version` prints "opencode v2.0.22" on some builds and "2.0.22" on others;
+    // record the bare version so the field does not churn between machines.
+    const output = (result.stdout || result.stderr || '').trim()
+    return output.match(/\d+\.\d+\.\d+[\w.-]*/)?.[0] ?? (output || null)
+  } catch {
+    return null
+  }
+}
+
+export async function writeHarnessConfig(data) {
+  header('Step 10, Writing onboarding metadata')
+
+  const opencodeVersion = await detectOpencodeVersion()
+  const cwd = data.cwd ?? process.cwd()
+  const target = configPath(cwd)
+
+  // Read the existing file so load-bearing config (models, maxConcurrent)
+  // is preserved across metadata refreshes when not explicitly provided.
+  const existing = await fse.readJson(target).catch(() => null)
+
+  const selectedModels = Object.fromEntries(
+    Object.entries({
+      plan: data.planModel,
+      build: data.buildModel,
+      fast: data.fastModel,
+    }).filter(([, value]) => value)
+  )
+  const models = Object.keys(selectedModels).length > 0
+    ? { ...existing?.models, ...selectedModels }
+    : existing?.models ?? null
+  const maxConcurrent = clampConcurrency(data.maxConcurrentAgents ?? existing?.agents?.maxConcurrent ?? 3)
+
+  const optionalTools = data.optionalTools ?? existing?.tools ?? {}
+  const { caveman: _caveman, ...existingTools } = existing?.tools ?? {}
+  const tools = {
+    rtk: !!(optionalTools.rtk?.optedIn ?? optionalTools.rtk),
+    quota: !!(optionalTools.quota?.optedIn ?? optionalTools.quota),
+    simpleEnglish: !!(
+      optionalTools.simpleEnglish?.optedIn ?? optionalTools.simpleEnglish ??
+      optionalTools.caveman?.optedIn ?? optionalTools.caveman
+    ),
+    codegraph: !!(optionalTools.codegraph?.optedIn ?? optionalTools.codegraph),
+    memory: !!(optionalTools.memory?.optedIn ?? optionalTools.memory),
+    // humanizer was missing here, so a selection never survived a metadata
+    // write and patchGuardrails always saw it as off, leaving its marker
+    // section empty however the project was actually set up.
+    humanizer: !!(optionalTools.humanizer?.optedIn ?? optionalTools.humanizer),
+  }
+
+  const payload = {
+    ...existing,
+    // Never lower a schema version a repository already records.
+    version: Math.max(2, Number(existing?.version) || 0),
+    generatedAt: new Date().toISOString(),
+    harnessVersion,
+    opencodeVersion,
+
+    platform: {
+      ...existing?.platform,
+      backlog: data.backlogPlatform ?? 'none',
+      repo: data.repoPlatform ?? 'none',
+    },
+
+    ...(models ? { models } : {}),
+
+    agents: {
+      ...existing?.agents,
+      maxConcurrent,
+    },
+
+    source: {
+      ...existing?.source,
+      mode: data.sourceMode ?? 'current',
+      roots: data.sourceRoots ?? [],
+    },
+
+    tools: { ...existingTools, ...tools },
+
+    preexisting: {
+      ...existing?.preexisting,
+      design: !!data.hasDesign,
+      architecture: !!data.hasArchitecture,
+      openspec: !!data.hasOpenspec,
+    },
+  }
+
+  try {
+    await fse.ensureDir(path.dirname(target))
+    await fse.writeJson(target, payload, { spaces: 2 })
+    success('Wrote .opencode/harness.json')
+    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
+  } catch (err) {
+    warn(`Could not write onboarding metadata: ${err.message}`)
+  }
+}

package/cli/steps/models/write.js

@@ -1,38 +1,38 @@
-import fse from 'fs-extra'
-import { applyEdits, modify, parse } from 'jsonc-parser'
-import path from 'path'
-import { success, warn } from '../../utils/exec.js'
-
-/**
- * Writes the selected build model as the default model in opencode.jsonc.
- * Per-tier models (plan/build/fast) are recorded in harness.json (models)
- * by the metadata step, then consumed by the agent-variant generator and /plan-apply.
- *
- * opencode tolerates JSONC (comments, trailing commas) in its config, so this
- * must not use readJson/writeJson: a strict parse crashes on valid configs and
- * a strict rewrite deletes user comments. jsonc-parser edits only the `model`
- * key and preserves the rest of the file byte-for-byte.
- */
-export async function writeModelsToConfigs({ buildModel, keepExisting = false, cwd = process.cwd() }) {
-  const opencodeJsonPath = path.join(cwd, 'opencode.jsonc')
-  if (!await fse.pathExists(opencodeJsonPath)) return
-
-  const text = await fse.readFile(opencodeJsonPath, 'utf-8')
-  const errors = []
-  parse(text, errors)
-  if (errors.length > 0) {
-    warn('opencode.jsonc could not be parsed: leaving it untouched. Set "model" manually.')
-    return
-  }
-
-  // A model the repository already chose is its decision, not the wizard's: `update` used to
-  // reset a deliberately pinned default to the build tier in every consumer it ran in.
-  if (keepExisting && typeof parse(text)?.model === 'string') return
-
-  // `undefined` removes the key; a string value sets it.
-  const edits = modify(text, ['model'], buildModel || undefined, {
-    formattingOptions: { insertSpaces: true, tabSize: 2 },
-  })
-  await fse.writeFile(opencodeJsonPath, applyEdits(text, edits), 'utf-8')
-  if (buildModel) success(`default model -> ${buildModel} (written to opencode.jsonc)`)
-}
+import fse from 'fs-extra'
+import { applyEdits, modify, parse } from 'jsonc-parser'
+import path from 'path'
+import { success, warn } from '../../utils/exec.js'
+
+/**
+ * Writes the selected build model as the default model in opencode.jsonc.
+ * Per-tier models (plan/build/fast) are recorded in harness.json (models)
+ * by the metadata step, then consumed by the agent-variant generator and /plan-apply.
+ *
+ * opencode tolerates JSONC (comments, trailing commas) in its config, so this
+ * must not use readJson/writeJson: a strict parse crashes on valid configs and
+ * a strict rewrite deletes user comments. jsonc-parser edits only the `model`
+ * key and preserves the rest of the file byte-for-byte.
+ */
+export async function writeModelsToConfigs({ buildModel, keepExisting = false, cwd = process.cwd() }) {
+  const opencodeJsonPath = path.join(cwd, 'opencode.jsonc')
+  if (!await fse.pathExists(opencodeJsonPath)) return
+
+  const text = await fse.readFile(opencodeJsonPath, 'utf-8')
+  const errors = []
+  parse(text, errors)
+  if (errors.length > 0) {
+    warn('opencode.jsonc could not be parsed: leaving it untouched. Set "model" manually.')
+    return
+  }
+
+  // A model the repository already chose is its decision, not the wizard's: `update` used to
+  // reset a deliberately pinned default to the build tier in every consumer it ran in.
+  if (keepExisting && typeof parse(text)?.model === 'string') return
+
+  // `undefined` removes the key; a string value sets it.
+  const edits = modify(text, ['model'], buildModel || undefined, {
+    formattingOptions: { insertSpaces: true, tabSize: 2 },
+  })
+  await fse.writeFile(opencodeJsonPath, applyEdits(text, edits), 'utf-8')
+  if (buildModel) success(`default model -> ${buildModel} (written to opencode.jsonc)`)
+}

package/cli/utils/copy.js

@@ -33,13 +33,16 @@ async function documentedElsewhere(destDir, fileName) {
   return false
 }
 
+const MANAGED_DIRS = ['.opencode/plugins/', '.opencode/scripts/']
+
 function isTemplateTest(relativePath) {
-  return relativePath.split(path.sep).join('/').startsWith('.opencode/plugins/') && relativePath.endsWith('.test.js')
+  const normalized = relativePath.split(path.sep).join('/')
+  return MANAGED_DIRS.some(dir => normalized.startsWith(dir)) && normalized.endsWith('.test.js')
 }
 
 export function isManagedContentPath(relativePath) {
   const normalized = relativePath.split(path.sep).join('/')
-  if (normalized.startsWith('.opencode/plugins/')) return true
+  if (MANAGED_DIRS.some(dir => normalized.startsWith(dir))) return true
   if (normalized.startsWith('.opencode/commands/') && !MARKER_COMMANDS.has(normalized)) return true
   return normalized === 'openspec/specs/.gitkeep' || normalized === 'openspec/changes/archive/.gitkeep'
 }

package/cli/utils/paths.js

@@ -1,80 +1,80 @@
-import os from 'node:os'
-import path from 'node:path'
-
-/**
- * Every harness path that lands in a consumer repo, in one place.
- *
- * These filenames are a contract with every repo the harness has been
- * installed into: the CLI writes them, and the opencode plugins shipped in
- * harness/.opencode/plugins/ read them back at runtime. Changing a name
- * here means changing it in that payload too, or the plugins go blind.
- *
- * They are deliberately named for the harness rather than for the CLI, so a
- * future rename of the package does not become a rename of the on-disk state.
- */
-export const OPENCODE_DIR = '.opencode'
-
-/** Project config written by the metadata step. */
-export const CONFIG_FILE = 'harness.json'
-
-/** Per-developer model override, gitignored, never committed. */
-export const USER_CONFIG_FILE = 'harness.user.json'
-
-/** Hashes of every managed file, so `update` can detect local edits. */
-export const MANIFEST_FILE = 'harness-managed.json'
-
-/** Live subagent wave state, owned by the pc-subagent-monitor plugin. */
-export const RUN_STATE_FILE = 'harness-run.json'
-
-/** Names `.opencode/.gitignore` must cover. Mirrored in content/.opencode/_gitignore. */
-export const IGNORED_ENTRIES = [
-  'node_modules',
-  RUN_STATE_FILE,
-  USER_CONFIG_FILE,
-  MANIFEST_FILE,
-  'source-roots.json',
-  '*-engineer.*.md',
-  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
-  'agents/build.md',
-  'agents/plan.md',
-]
-
-/**
- * Files the harness shipped and has since retired. `update` deletes them, because a skill or
- * command left behind keeps being offered to agents long after the procedure it describes is
- * gone. pc-ops-evidence wrote a capturePlan for a CI workflow that no longer exists; the
- * verification plan from pc-repo-verify is what the evidence workflow replays now.
- */
-export const RETIRED_PATHS = [
-  '.agents/skills/pc-ops-evidence',
-  '.agents/skills/pc-make-evidence-scaffold',
-  '.opencode/commands/ops-evidence.md',
-  '.opencode/commands/make-evidence-scaffold.md',
-]
-
-export function configPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, CONFIG_FILE)
-}
-
-export function userConfigPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, USER_CONFIG_FILE)
-}
-
-export function manifestPath(cwd = process.cwd()) {
-  return path.join(cwd, OPENCODE_DIR, MANIFEST_FILE)
-}
-
-/** Cross-run models cache, keyed to the CLI rather than to any one repo. */
-export function modelsCacheDir() {
-  return path.join(os.homedir(), '.config', 'agent-harness')
-}
-
-/**
- * Filenames written by opencode-onboard v1.x. Only used to detect a v1 repo
- * and refuse to half-patch it: nothing reads their contents.
- */
-export const LEGACY_CONFIG_FILES = [
-  'opencode-onboard.json',
-  'opencode-onboard.user.json',
-  'opencode-onboard-managed.json',
-]
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * Every harness path that lands in a consumer repo, in one place.
+ *
+ * These filenames are a contract with every repo the harness has been
+ * installed into: the CLI writes them, and the opencode plugins shipped in
+ * harness/.opencode/plugins/ read them back at runtime. Changing a name
+ * here means changing it in that payload too, or the plugins go blind.
+ *
+ * They are deliberately named for the harness rather than for the CLI, so a
+ * future rename of the package does not become a rename of the on-disk state.
+ */
+export const OPENCODE_DIR = '.opencode'
+
+/** Project config written by the metadata step. */
+export const CONFIG_FILE = 'harness.json'
+
+/** Per-developer model override, gitignored, never committed. */
+export const USER_CONFIG_FILE = 'harness.user.json'
+
+/** Hashes of every managed file, so `update` can detect local edits. */
+export const MANIFEST_FILE = 'harness-managed.json'
+
+/** Live subagent wave state, owned by the pc-subagent-monitor plugin. */
+export const RUN_STATE_FILE = 'harness-run.json'
+
+/** Names `.opencode/.gitignore` must cover. Mirrored in content/.opencode/_gitignore. */
+export const IGNORED_ENTRIES = [
+  'node_modules',
+  RUN_STATE_FILE,
+  USER_CONFIG_FILE,
+  MANIFEST_FILE,
+  'source-roots.json',
+  '*-engineer.*.md',
+  // Regenerated from fullstack-engineer.md by pc-subagent-tiers every startup.
+  'agents/build.md',
+  'agents/plan.md',
+]
+
+/**
+ * Files the harness shipped and has since retired. `update` deletes them, because a skill or
+ * command left behind keeps being offered to agents long after the procedure it describes is
+ * gone. pc-ops-evidence wrote a capturePlan for a CI workflow that no longer exists; the
+ * verification plan from pc-repo-verify is what the evidence workflow replays now.
+ */
+export const RETIRED_PATHS = [
+  '.agents/skills/pc-ops-evidence',
+  '.agents/skills/pc-make-evidence-scaffold',
+  '.opencode/commands/ops-evidence.md',
+  '.opencode/commands/make-evidence-scaffold.md',
+]
+
+export function configPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, CONFIG_FILE)
+}
+
+export function userConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, USER_CONFIG_FILE)
+}
+
+export function manifestPath(cwd = process.cwd()) {
+  return path.join(cwd, OPENCODE_DIR, MANIFEST_FILE)
+}
+
+/** Cross-run models cache, keyed to the CLI rather than to any one repo. */
+export function modelsCacheDir() {
+  return path.join(os.homedir(), '.config', 'agent-harness')
+}
+
+/**
+ * Filenames written by opencode-onboard v1.x. Only used to detect a v1 repo
+ * and refuse to half-patch it: nothing reads their contents.
+ */
+export const LEGACY_CONFIG_FILES = [
+  'opencode-onboard.json',
+  'opencode-onboard.user.json',
+  'opencode-onboard-managed.json',
+]

package/harness/.opencode/_gitignore

@@ -1,9 +1,9 @@
-node_modules
-harness-run.json
-harness.user.json
-harness-managed.json
-source-roots.json
-tmp/
-*-engineer.*.md
-agents/build.md
-agents/plan.md
+node_modules
+harness-run.json
+harness.user.json
+harness-managed.json
+source-roots.json
+tmp/
+*-engineer.*.md
+agents/build.md
+agents/plan.md

package/harness/.opencode/commands/init.md

@@ -1,5 +1,5 @@
----
-description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
----
-
-Load the `pc-repo-initialize` skill.
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill.

package/harness/.opencode/commands/make-architecture.md

@@ -1,5 +1,5 @@
----
-description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
----
-
-Load the `pc-make-architecture` skill.
+---
+description: Generate or update ARCHITECTURE.md by analyzing the codebase structure. Safe to run at any time.
+---
+
+Load the `pc-make-architecture` skill.

package/harness/.opencode/commands/make-design.md

@@ -1,5 +1,5 @@
----
-description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
----
-
-Load the `pc-make-design` skill.
+---
+description: Generate or update DESIGN.md by analyzing the codebase design system. Safe to run at any time.
+---
+
+Load the `pc-make-design` skill.

package/harness/.opencode/commands/make-engineer.md

@@ -1,5 +1,5 @@
----
-description: Create a custom engineer agent via persona-driven interactive design
----
-
-Load the `pc-make-engineer` skill.
+---
+description: Create a custom engineer agent via persona-driven interactive design
+---
+
+Load the `pc-make-engineer` skill.

package/harness/.opencode/commands/make-guardrails.md

@@ -1,5 +1,5 @@
----
-description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
----
-
-Load the `pc-make-guardrails` skill.
+---
+description: Generate or update a pc-guardrails-project skill from ARCHITECTURE.md and relevant project files.
+---
+
+Load the `pc-make-guardrails` skill.

package/harness/.opencode/commands/make-user-model.md

@@ -1,5 +1,5 @@
----
-description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
----
-
-Load the `pc-make-user-model` skill.
+---
+description: Set the model for a tier (plan, build, or fast). Team-wide or user-local override.
+---
+
+Load the `pc-make-user-model` skill.

package/harness/.opencode/commands/plan-apply.md

@@ -1,9 +1,9 @@
----
-description: "Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans."
----
-
-Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch`.
-
-Input:
-
-$ARGUMENTS
+---
+description: "Implement tasks from a plan: works with OpenSpec proposals and in-conversation plans."
+---
+
+Load the `pc-plan-apply` skill and execute it in **interactive mode** with `start_from: branch`.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/plan-goal.md

@@ -1,5 +1,5 @@
----
-description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering."
----
-
-Load the `pc-plan-goal` skill.
+---
+description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering."
+---
+
+Load the `pc-plan-goal` skill.

package/harness/.opencode/commands/plan-quick.md

@@ -1,5 +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.
+---
+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.

package/harness/.opencode/commands/plan-story.md

@@ -1,9 +1,9 @@
----
-description: Write a detailed, repo-aware user story from a feature idea or need.
----
-
-Load the `pc-plan-story` skill.
-
-Input:
-
-$ARGUMENTS
+---
+description: Write a detailed, repo-aware user story from a feature idea or need.
+---
+
+Load the `pc-plan-story` skill.
+
+Input:
+
+$ARGUMENTS

package/harness/.opencode/commands/repo-audit.md

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