@plainconceptsplatform/agent-harness 2.1.0 → 2.2.0

package/package.json

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

package/src/commands/migrate.js

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

package/src/index.js

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

package/src/steps/copy/skills.js

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