@plainconceptsplatform/agent-harness 2.1.0 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "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,310 @@
+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
+  // .github/workflows is included because GitHub Agentic Workflow definitions
+  // call the skills by name (skill("pc-repo-audit")), so a stale ob- name there
+  // fails at run time in CI rather than locally. Their compiled .lock.yml files
+  // embed the same prompt text, so recompile with `gh aw compile` afterwards.
+  for (const dir of [skillsDir, opencodeDir, path.join(cwd, 'openspec'), path.join(cwd, '.github', 'workflows')]) {
+    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'))
+
+  // The .md definitions were rewritten above, but the compiled .lock.yml files
+  // embed the same prompt text and are what CI actually runs.
+  if (await fse.pathExists(path.join(cwd, '.github', 'workflows'))) {
+    const locks = (await fse.readdir(path.join(cwd, '.github', 'workflows')).catch(() => []))
+      .filter(f => f.endsWith('.lock.yml'))
+    if (locks.length > 0) {
+      console.log()
+      console.log(chalk.bold(`Then recompile ${locks.length} agentic workflow(s), whose .lock.yml still holds the old skill names:`))
+      console.log(chalk.dim('  gh aw compile'))
+    }
+  }
+
+  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/agents.js

@@ -1,118 +1,119 @@
-import fse from 'fs-extra'
-import path from 'path'
-import { fileURLToPath } from 'url'
-import { info, success, warn } from '../../utils/exec.js'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const agentsContent = await fse.readJson(path.resolve(__dirname, '../../presets/agents-content.json'))
-
-// Steps are matched by their title text, not by exact heading string:
-// heading level (###/####) and step numbers have drifted before and silently
-// broke removal. Matching `^#{3,4} Step N, <title>` survives both.
-const HISTORY_STEP_TITLE = 'Archive project history'
-const CHAIN_STEP_TITLE = 'Chain make commands'
-
-const CHAIN_CONFIRM_LINE = '- ARCHITECTURE.md generated'
-
-function stepHeadingPattern(title) {
-  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  return new RegExp(`^#{2,4} Step \\d+, ${escaped}`)
-}
-
-// The step heading is kept and its body replaced with an explicit skip note.
-// Removing the block and renumbering the remaining steps (the old approach)
-// went stale against prose cross-references like "Skip steps 2, 3, and 4";
-// stable numbering plus a visible reason is unambiguous for the agent.
-export function skipStepBlock(content, title, note) {
-  const lines = content.split('\n')
-  const pattern = stepHeadingPattern(title)
-  const start = lines.findIndex(l => pattern.test(l.trim()))
-  if (start === -1) return { content, matched: false }
-
-  let end = lines.length
-  for (let i = start + 1; i < lines.length; i++) {
-    if (lines[i].trim() === '---') { end = i; break }
-  }
-
-  lines.splice(start + 1, end - start - 1, '', `> ${note}`, '')
-  return { content: lines.join('\n'), matched: true }
-}
-
-function removeConfirmLine(content, line) {
-  return content.split('\n').filter(l => l.trim() !== line.trim()).join('\n')
-}
-
-const PLATFORM_WORKFLOW_START = '<!-- PC-PLATFORM-WORKFLOW-START -->'
-const PLATFORM_WORKFLOW_END = '<!-- PC-PLATFORM-WORKFLOW-END -->'
-const PLATFORM_SKILLS_GUIDE_START = '<!-- PC-PLATFORM-SKILLS-GUIDE-START -->'
-const PLATFORM_SKILLS_GUIDE_END = '<!-- PC-PLATFORM-SKILLS-GUIDE-END -->'
-
-function platformContent(platform, key) {
-  const p = agentsContent.platform[platform] ?? agentsContent.platform.github
-  return p[key] ?? ''
-}
-
-function mixedPlatformContent(backlogPlatform, repoPlatform, key) {
-  if (backlogPlatform === repoPlatform) {
-    return platformContent(backlogPlatform, key)
-  }
-  const backlog = agentsContent.platform[backlogPlatform] ?? agentsContent.platform.github
-  const repo = agentsContent.platform[repoPlatform] ?? agentsContent.platform.github
-  const mixed = agentsContent.platform.mixed ?? {}
-  const mixedKey = `${backlogPlatform}-${repoPlatform}`
-  return mixed[mixedKey]?.[key] ?? mixed.default?.[key]?.replace('{backlog}', backlog[key] ?? '').replace('{repo}', repo[key] ?? '') ?? platformContent(repoPlatform, key)
-}
-
-function replaceBetween(content, start, end, replacement) {
-  if (!content.includes(start) || !content.includes(end)) return content
-  const pattern = new RegExp(`${start}[\\s\\S]*?${end}`)
-  return content.replace(pattern, `${start}\n${replacement.trim()}\n${end}`)
-}
-
-export async function patchAgentsMd(ctx) {
-  const obInitSkillPath = path.join(process.cwd(), '.agents', 'skills', 'pc-repo-initialize', 'SKILL.md')
-  if (!await fse.pathExists(obInitSkillPath)) return
-
-  let content = await fse.readFile(obInitSkillPath, 'utf-8')
-  const patches = []
-
-  const skips = [
-    [ctx.hasOpenspec, HISTORY_STEP_TITLE, null,
-      'Skipped during onboarding: this project already had an openspec/ history. Do not archive again; continue with the next step.'],
-    [ctx.hasDesign || ctx.hasArchitecture, CHAIN_STEP_TITLE, CHAIN_CONFIRM_LINE,
-      'Skipped during onboarding: project files already exist. Run /make-architecture or /make-design individually to regenerate.'],
-  ]
-
-  for (const [enabled, title, confirmLine, note] of skips) {
-    if (!enabled) continue
-    const result = skipStepBlock(content, title, note)
-    if (!result.matched) {
-      warn(`pc-repo-initialize SKILL.md step "${title}" not found: template drift? Skipping this patch.`)
-      continue
-    }
-    content = result.content
-    if (confirmLine) content = removeConfirmLine(content, confirmLine)
-    patches.push(`Step "${title}" marked as skipped, file already exists`)
-  }
-
-  if (patches.length > 0) {
-    await fse.writeFile(obInitSkillPath, content, 'utf-8')
-    for (const msg of patches) info(msg)
-    success('pc-repo-initialize SKILL.md patched for existing project state')
-  }
-}
-
-export async function patchAgentGuidance(backlogPlatform, repoPlatform, cwd = process.cwd()) {
-  const agentsMdPath = path.join(cwd, 'AGENTS.md')
-  if (await fse.pathExists(agentsMdPath)) {
-    const repo = repoPlatform ?? backlogPlatform ?? 'github'
-    let content = await fse.readFile(agentsMdPath, 'utf-8')
-    content = replaceBetween(content, PLATFORM_WORKFLOW_START, PLATFORM_WORKFLOW_END, mixedPlatformContent(backlogPlatform, repo, 'workflow'))
-    content = replaceBetween(content, PLATFORM_SKILLS_GUIDE_START, PLATFORM_SKILLS_GUIDE_END, mixedPlatformContent(backlogPlatform, repo, 'skillsGuide'))
-    await fse.writeFile(agentsMdPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
-    const label = backlogPlatform === repo ? repo : `${backlogPlatform}→${repo}`
-    success(`AGENTS.md patched for platform workflow: ${label}`)
-  }
-}
-
-
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { info, success, warn } from '../../utils/exec.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const agentsContent = await fse.readJson(path.resolve(__dirname, '../../presets/agents-content.json'))
+
+// Steps are matched by their title text, not by exact heading string:
+// heading level (###/####) and step numbers have drifted before and silently
+// broke removal. Matching `^#{3,4} Step N, <title>` survives both.
+const HISTORY_STEP_TITLE = 'Archive project history'
+const CHAIN_STEP_TITLE = 'Chain make commands'
+
+const CHAIN_CONFIRM_LINE = '- ARCHITECTURE.md generated'
+
+function stepHeadingPattern(title) {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^#{2,4} Step \\d+, ${escaped}`)
+}
+
+// The step heading is kept and its body replaced with an explicit skip note.
+// Removing the block and renumbering the remaining steps (the old approach)
+// went stale against prose cross-references like "Skip steps 2, 3, and 4";
+// stable numbering plus a visible reason is unambiguous for the agent.
+export function skipStepBlock(content, title, note) {
+  const lines = content.split('\n')
+  const pattern = stepHeadingPattern(title)
+  const start = lines.findIndex(l => pattern.test(l.trim()))
+  if (start === -1) return { content, matched: false }
+
+  let end = lines.length
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break }
+  }
+
+  lines.splice(start + 1, end - start - 1, '', `> ${note}`, '')
+  return { content: lines.join('\n'), matched: true }
+}
+
+function removeConfirmLine(content, line) {
+  return content.split('\n').filter(l => l.trim() !== line.trim()).join('\n')
+}
+
+const PLATFORM_WORKFLOW_START = '<!-- PC-PLATFORM-WORKFLOW-START -->'
+const PLATFORM_WORKFLOW_END = '<!-- PC-PLATFORM-WORKFLOW-END -->'
+const PLATFORM_SKILLS_GUIDE_START = '<!-- PC-PLATFORM-SKILLS-GUIDE-START -->'
+const PLATFORM_SKILLS_GUIDE_END = '<!-- PC-PLATFORM-SKILLS-GUIDE-END -->'
+
+function platformContent(platform, key) {
+  const p = agentsContent.platform[platform] ?? agentsContent.platform.github
+  return p[key] ?? ''
+}
+
+function mixedPlatformContent(backlogPlatform, repoPlatform, key) {
+  if (backlogPlatform === repoPlatform) {
+    return platformContent(backlogPlatform, key)
+  }
+  const backlog = agentsContent.platform[backlogPlatform] ?? agentsContent.platform.github
+  const repo = agentsContent.platform[repoPlatform] ?? agentsContent.platform.github
+  const mixed = agentsContent.platform.mixed ?? {}
+  const mixedKey = `${backlogPlatform}-${repoPlatform}`
+  return mixed[mixedKey]?.[key] ?? mixed.default?.[key]?.replace('{backlog}', backlog[key] ?? '').replace('{repo}', repo[key] ?? '') ?? platformContent(repoPlatform, key)
+}
+
+function replaceBetween(content, start, end, replacement) {
+  if (!content.includes(start) || !content.includes(end)) return content
+  const pattern = new RegExp(`${start}[\\s\\S]*?${end}`)
+  // Replacer function so $&, $' and $` in injected content stay literal.
+  return content.replace(pattern, () => `${start}\n${replacement.trim()}\n${end}`)
+}
+
+export async function patchAgentsMd(ctx) {
+  const obInitSkillPath = path.join(process.cwd(), '.agents', 'skills', 'pc-repo-initialize', 'SKILL.md')
+  if (!await fse.pathExists(obInitSkillPath)) return
+
+  let content = await fse.readFile(obInitSkillPath, 'utf-8')
+  const patches = []
+
+  const skips = [
+    [ctx.hasOpenspec, HISTORY_STEP_TITLE, null,
+      'Skipped during onboarding: this project already had an openspec/ history. Do not archive again; continue with the next step.'],
+    [ctx.hasDesign || ctx.hasArchitecture, CHAIN_STEP_TITLE, CHAIN_CONFIRM_LINE,
+      'Skipped during onboarding: project files already exist. Run /make-architecture or /make-design individually to regenerate.'],
+  ]
+
+  for (const [enabled, title, confirmLine, note] of skips) {
+    if (!enabled) continue
+    const result = skipStepBlock(content, title, note)
+    if (!result.matched) {
+      warn(`pc-repo-initialize SKILL.md step "${title}" not found: template drift? Skipping this patch.`)
+      continue
+    }
+    content = result.content
+    if (confirmLine) content = removeConfirmLine(content, confirmLine)
+    patches.push(`Step "${title}" marked as skipped, file already exists`)
+  }
+
+  if (patches.length > 0) {
+    await fse.writeFile(obInitSkillPath, content, 'utf-8')
+    for (const msg of patches) info(msg)
+    success('pc-repo-initialize SKILL.md patched for existing project state')
+  }
+}
+
+export async function patchAgentGuidance(backlogPlatform, repoPlatform, cwd = process.cwd()) {
+  const agentsMdPath = path.join(cwd, 'AGENTS.md')
+  if (await fse.pathExists(agentsMdPath)) {
+    const repo = repoPlatform ?? backlogPlatform ?? 'github'
+    let content = await fse.readFile(agentsMdPath, 'utf-8')
+    content = replaceBetween(content, PLATFORM_WORKFLOW_START, PLATFORM_WORKFLOW_END, mixedPlatformContent(backlogPlatform, repo, 'workflow'))
+    content = replaceBetween(content, PLATFORM_SKILLS_GUIDE_START, PLATFORM_SKILLS_GUIDE_END, mixedPlatformContent(backlogPlatform, repo, 'skillsGuide'))
+    await fse.writeFile(agentsMdPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
+    const label = backlogPlatform === repo ? repo : `${backlogPlatform}→${repo}`
+    success(`AGENTS.md patched for platform workflow: ${label}`)
+  }
+}
+
+

package/src/steps/copy/commands.js

@@ -1,91 +1,95 @@
-import fse from 'fs-extra'
-import path from 'path'
-import { fileURLToPath } from 'url'
-import { success } from '../../utils/exec.js'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const _archive = {
-  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/az.md'), 'utf-8'),
-  github: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/gh.md'), 'utf-8'),
-  gitlab: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/gl.md'), 'utf-8'),
-  none: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/none.md'), 'utf-8'),
-}
-
-const _ship = {
-  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-ship/gh.md'), 'utf-8'),
-  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-ship/az.md'), 'utf-8'),
-  gitlab: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-ship/gl.md'), 'utf-8'),
-}
-
-const _review = {
-  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-review/gh.md'), 'utf-8'),
-  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-review/az.md'), 'utf-8'),
-  gitlab: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-review/gl.md'), 'utf-8'),
-}
-
-const _backlog = {
-  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-backlog/gh.md'), 'utf-8'),
-  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-backlog/az.md'), 'utf-8'),
-  jira: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-backlog/jira.md'), 'utf-8'),
-}
-
-// Evidence comments target the backlog platform (where the issue/work-item lives).
-const _evidence = {
-  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-evidence/gh.md'), 'utf-8'),
-  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-evidence/az.md'), 'utf-8'),
-  jira: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-evidence/jira.md'), 'utf-8'),
-}
-
-// relativePath is POSIX-style relative to the project root; commands live in
-// .opencode/commands/, skill-backed procedures (plan-archive, ops-ship) in
-// .agents/skills/<name>/SKILL.md.
-function patchFile(relativePath, startMarker, endMarker, content, platform, cwd = process.cwd()) {
-  const targetPath = path.join(cwd, ...relativePath.split('/'))
-  if (!fse.pathExistsSync(targetPath)) return
-
-  let fileContent = fse.readFileSync(targetPath, 'utf-8')
-  if (!fileContent.includes(startMarker) || !fileContent.includes(endMarker)) return
-
-  const pattern = new RegExp(`${startMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${endMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`)
-  fileContent = fileContent.replace(pattern, `${startMarker}\n${content.trim()}\n${endMarker}`)
-  fse.writeFileSync(targetPath, `${fileContent.replace(/\s*$/, '')}\n`, 'utf-8')
-  success(`${relativePath} content injected for platform: ${platform}`)
-}
-
-export async function patchArchiveCommand(platform, cwd = process.cwd()) {
-  const repoPlatform = typeof platform === 'object' ? (platform.repoPlatform ?? platform.backlogPlatform ?? 'github') : platform
-  const replacement = _archive[repoPlatform]
-  if (!replacement) return
-  patchFile('.agents/skills/pc-plan-archive/SKILL.md', '<!-- PC-PLATFORM-ARCHIVE-START -->', '<!-- PC-PLATFORM-ARCHIVE-END -->', replacement, repoPlatform, cwd)
-}
-
-export async function patchOpsShip(platform, cwd = process.cwd()) {
-  const repoPlatform = typeof platform === 'object' ? (platform.repoPlatform ?? 'github') : platform
-  const replacement = _ship[repoPlatform]
-  if (!replacement) return
-  patchFile('.agents/skills/pc-ops-ship/SKILL.md', '<!-- PC-PLATFORM-SHIP-START -->', '<!-- PC-PLATFORM-SHIP-END -->', replacement, repoPlatform, cwd)
-}
-
-export async function patchOpsReview(platform, cwd = process.cwd()) {
-  const repoPlatform = typeof platform === 'object' ? (platform.repoPlatform ?? 'github') : platform
-  const replacement = _review[repoPlatform]
-  if (!replacement) return
-  patchFile('.opencode/commands/ops-review.md', '<!-- PC-PLATFORM-REVIEW-START -->', '<!-- PC-PLATFORM-REVIEW-END -->', replacement, repoPlatform, cwd)
-}
-
-export async function patchOpsBacklog(platform, cwd = process.cwd()) {
-  const backlogPlatform = typeof platform === 'object' ? (platform.backlogPlatform ?? 'github') : platform
-  const replacement = _backlog[backlogPlatform]
-  if (!replacement) return
-  patchFile('.opencode/commands/ops-backlog.md', '<!-- PC-PLATFORM-BACKLOG-START -->', '<!-- PC-PLATFORM-BACKLOG-END -->', replacement, backlogPlatform, cwd)
-}
-
-export async function patchOpsEvidence(platform, cwd = process.cwd()) {
-  const backlogPlatform = typeof platform === 'object' ? (platform.backlogPlatform ?? 'github') : platform
-  const replacement = _evidence[backlogPlatform]
-  // browser/none have no CLI to post with: leave the markers empty (the skill skips commenting).
-  if (!replacement) return
-  patchFile('.agents/skills/pc-ops-evidence/SKILL.md', '<!-- PC-PLATFORM-EVIDENCE-START -->', '<!-- PC-PLATFORM-EVIDENCE-END -->', replacement, backlogPlatform, cwd)
-}
-
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { success } from '../../utils/exec.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const _archive = {
+  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/az.md'), 'utf-8'),
+  github: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/gh.md'), 'utf-8'),
+  gitlab: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/gl.md'), 'utf-8'),
+  none: await fse.readFile(path.resolve(__dirname, '../../fragments/archive/none.md'), 'utf-8'),
+}
+
+const _ship = {
+  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-ship/gh.md'), 'utf-8'),
+  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-ship/az.md'), 'utf-8'),
+  gitlab: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-ship/gl.md'), 'utf-8'),
+}
+
+const _review = {
+  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-review/gh.md'), 'utf-8'),
+  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-review/az.md'), 'utf-8'),
+  gitlab: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-review/gl.md'), 'utf-8'),
+}
+
+const _backlog = {
+  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-backlog/gh.md'), 'utf-8'),
+  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-backlog/az.md'), 'utf-8'),
+  jira: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-backlog/jira.md'), 'utf-8'),
+}
+
+// Evidence comments target the backlog platform (where the issue/work-item lives).
+const _evidence = {
+  github: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-evidence/gh.md'), 'utf-8'),
+  azure: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-evidence/az.md'), 'utf-8'),
+  jira: await fse.readFile(path.resolve(__dirname, '../../fragments/ops-evidence/jira.md'), 'utf-8'),
+}
+
+// relativePath is POSIX-style relative to the project root; commands live in
+// .opencode/commands/, skill-backed procedures (plan-archive, ops-ship) in
+// .agents/skills/<name>/SKILL.md.
+function patchFile(relativePath, startMarker, endMarker, content, platform, cwd = process.cwd()) {
+  const targetPath = path.join(cwd, ...relativePath.split('/'))
+  if (!fse.pathExistsSync(targetPath)) return
+
+  let fileContent = fse.readFileSync(targetPath, 'utf-8')
+  if (!fileContent.includes(startMarker) || !fileContent.includes(endMarker)) return
+
+  const pattern = new RegExp(`${startMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${endMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`)
+  // Replacer function, not a replacement string: the injected fragments contain
+  // shell quoting like $'...' and a string replacement expands $' as "everything
+  // after the match", silently truncating the command. That is how the ops-ship
+  // screenshot comment lost its entire --body argument.
+  fileContent = fileContent.replace(pattern, () => `${startMarker}\n${content.trim()}\n${endMarker}`)
+  fse.writeFileSync(targetPath, `${fileContent.replace(/\s*$/, '')}\n`, 'utf-8')
+  success(`${relativePath} content injected for platform: ${platform}`)
+}
+
+export async function patchArchiveCommand(platform, cwd = process.cwd()) {
+  const repoPlatform = typeof platform === 'object' ? (platform.repoPlatform ?? platform.backlogPlatform ?? 'github') : platform
+  const replacement = _archive[repoPlatform]
+  if (!replacement) return
+  patchFile('.agents/skills/pc-plan-archive/SKILL.md', '<!-- PC-PLATFORM-ARCHIVE-START -->', '<!-- PC-PLATFORM-ARCHIVE-END -->', replacement, repoPlatform, cwd)
+}
+
+export async function patchOpsShip(platform, cwd = process.cwd()) {
+  const repoPlatform = typeof platform === 'object' ? (platform.repoPlatform ?? 'github') : platform
+  const replacement = _ship[repoPlatform]
+  if (!replacement) return
+  patchFile('.agents/skills/pc-ops-ship/SKILL.md', '<!-- PC-PLATFORM-SHIP-START -->', '<!-- PC-PLATFORM-SHIP-END -->', replacement, repoPlatform, cwd)
+}
+
+export async function patchOpsReview(platform, cwd = process.cwd()) {
+  const repoPlatform = typeof platform === 'object' ? (platform.repoPlatform ?? 'github') : platform
+  const replacement = _review[repoPlatform]
+  if (!replacement) return
+  patchFile('.opencode/commands/ops-review.md', '<!-- PC-PLATFORM-REVIEW-START -->', '<!-- PC-PLATFORM-REVIEW-END -->', replacement, repoPlatform, cwd)
+}
+
+export async function patchOpsBacklog(platform, cwd = process.cwd()) {
+  const backlogPlatform = typeof platform === 'object' ? (platform.backlogPlatform ?? 'github') : platform
+  const replacement = _backlog[backlogPlatform]
+  if (!replacement) return
+  patchFile('.opencode/commands/ops-backlog.md', '<!-- PC-PLATFORM-BACKLOG-START -->', '<!-- PC-PLATFORM-BACKLOG-END -->', replacement, backlogPlatform, cwd)
+}
+
+export async function patchOpsEvidence(platform, cwd = process.cwd()) {
+  const backlogPlatform = typeof platform === 'object' ? (platform.backlogPlatform ?? 'github') : platform
+  const replacement = _evidence[backlogPlatform]
+  // browser/none have no CLI to post with: leave the markers empty (the skill skips commenting).
+  if (!replacement) return
+  patchFile('.agents/skills/pc-ops-evidence/SKILL.md', '<!-- PC-PLATFORM-EVIDENCE-START -->', '<!-- PC-PLATFORM-EVIDENCE-END -->', replacement, backlogPlatform, cwd)
+}
+

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',
 ])

package/src/steps/optimization/patch-guardrails.js

@@ -1,108 +1,109 @@
-import fse from 'fs-extra'
-import path from 'path'
-import { fileURLToPath } from 'url'
-import { info, success } from '../../utils/exec.js'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const GUARDRAILS_FRAGMENT_DIR = path.resolve(__dirname, '../../fragments/guardrails')
-
-const MARKER_SECTIONS = {
-  rtk: 'RTK',
-  codegraph: 'CODEGRAPH',
-  memory: 'MEMORY',
-  simpleEnglish: 'SIMPLE-ENGLISH',
-  humanizer: 'HUMANIZER',
-}
-
-const OPTIONAL_TOOL_GUIDANCE = {
-  codegraph: 'Use `codegraph_explore` to refine relevant symbols and file-disjointness for the current wave.',
-  memory: 'Use Agentmemory MCP tools for cross-session context and task-result notes.',
-}
-
-function replaceMarkerSection(content, startMarker, endMarker, replacement) {
-  if (!content.includes(startMarker) || !content.includes(endMarker)) return content
-  const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  const pattern = new RegExp(`${escape(startMarker)}[\\s\\S]*?${escape(endMarker)}`)
-  return content.replace(pattern, `${startMarker}\n${replacement}\n${endMarker}`)
-}
-
-async function patchOptionalToolGuidance(destSkillsDir, selections) {
-  const files = []
-
-  async function collect(dir) {
-    for (const entry of await fse.readdir(dir, { withFileTypes: true })) {
-      const entryPath = path.join(dir, entry.name)
-      if (entry.isDirectory()) await collect(entryPath)
-      else if (entry.name.endsWith('.md')) files.push(entryPath)
-    }
-  }
-
-  if (!await fse.pathExists(destSkillsDir)) return 0
-  await collect(destSkillsDir)
-
-  let patched = 0
-  for (const filePath of files) {
-    let content = await fse.readFile(filePath, 'utf-8')
-    const original = content
-    for (const [key, guidance] of Object.entries(OPTIONAL_TOOL_GUIDANCE)) {
-      const suffix = key.toUpperCase()
-      content = replaceMarkerSection(
-        content,
-        `<!-- PC-OPTIMIZATION-${suffix}-START -->`,
-        `<!-- PC-OPTIMIZATION-${suffix}-END -->`,
-        selections[key] ? guidance : '',
-      )
-    }
-    if (content !== original) {
-      await fse.writeFile(filePath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
-      patched++
-    }
-  }
-  return patched
-}
-
-export async function patchGuardrails(selections = {}, { cwd = process.cwd() } = {}) {
-  const destSkillsDir = path.join(cwd, '.agents', 'skills')
-  const guardrailsPath = path.join(destSkillsDir, 'pc-guardrails-generic', 'SKILL.md')
-  let patchedCount = 0
-
-  if (await fse.pathExists(guardrailsPath)) {
-    let content = await fse.readFile(guardrailsPath, 'utf-8')
-    content = replaceMarkerSection(
-      content,
-      '<!-- PC-GUARDRAILS-CAVEMAN-START -->',
-      '<!-- PC-GUARDRAILS-CAVEMAN-END -->',
-      '',
-    ).replace(
-      '<!-- PC-GUARDRAILS-CAVEMAN-START -->\n\n<!-- PC-GUARDRAILS-CAVEMAN-END -->',
-      '<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->\n<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->',
-    ).replace(
-      '1. Load ALL skills listed under your own `## Abilities` now (Guardrails first, then the rest), by calling the `skill` tool once per `@skill-name`.',
-      '1. The `pc-system-reminders` plugin has already loaded the skills listed under your `## Abilities`, guardrails first.',
-    )
-    for (const [key, markerSuffix] of Object.entries(MARKER_SECTIONS)) {
-      let sectionContent = ''
-      if (selections[key]) {
-        const presetName = key === 'simpleEnglish' ? 'simple-english' : key
-        const presetPath = path.join(GUARDRAILS_FRAGMENT_DIR, `${presetName}.md`)
-        if (await fse.pathExists(presetPath)) {
-          sectionContent = (await fse.readFile(presetPath, 'utf-8')).trim()
-        }
-      }
-      content = replaceMarkerSection(
-        content,
-        `<!-- PC-GUARDRAILS-${markerSuffix}-START -->`,
-        `<!-- PC-GUARDRAILS-${markerSuffix}-END -->`,
-        sectionContent,
-      )
-      if (selections[key]) patchedCount++
-    }
-    await fse.writeFile(guardrailsPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
-  } else {
-    info('pc-guardrails-generic not found, skipping guardrails patching')
-  }
-
-  const optionalPatched = await patchOptionalToolGuidance(destSkillsDir, selections)
-  success(`Guardrails patched: ${patchedCount} sections injected; ${optionalPatched} optional tool file(s) updated`)
-  return { patched: true, count: patchedCount, optionalPatched }
-}
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { info, success } from '../../utils/exec.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const GUARDRAILS_FRAGMENT_DIR = path.resolve(__dirname, '../../fragments/guardrails')
+
+const MARKER_SECTIONS = {
+  rtk: 'RTK',
+  codegraph: 'CODEGRAPH',
+  memory: 'MEMORY',
+  simpleEnglish: 'SIMPLE-ENGLISH',
+  humanizer: 'HUMANIZER',
+}
+
+const OPTIONAL_TOOL_GUIDANCE = {
+  codegraph: 'Use `codegraph_explore` to refine relevant symbols and file-disjointness for the current wave.',
+  memory: 'Use Agentmemory MCP tools for cross-session context and task-result notes.',
+}
+
+function replaceMarkerSection(content, startMarker, endMarker, replacement) {
+  if (!content.includes(startMarker) || !content.includes(endMarker)) return content
+  const escape = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(`${escape(startMarker)}[\\s\\S]*?${escape(endMarker)}`)
+  // Replacer function so $&, $' and $` in injected content stay literal.
+  return content.replace(pattern, () => `${startMarker}\n${replacement}\n${endMarker}`)
+}
+
+async function patchOptionalToolGuidance(destSkillsDir, selections) {
+  const files = []
+
+  async function collect(dir) {
+    for (const entry of await fse.readdir(dir, { withFileTypes: true })) {
+      const entryPath = path.join(dir, entry.name)
+      if (entry.isDirectory()) await collect(entryPath)
+      else if (entry.name.endsWith('.md')) files.push(entryPath)
+    }
+  }
+
+  if (!await fse.pathExists(destSkillsDir)) return 0
+  await collect(destSkillsDir)
+
+  let patched = 0
+  for (const filePath of files) {
+    let content = await fse.readFile(filePath, 'utf-8')
+    const original = content
+    for (const [key, guidance] of Object.entries(OPTIONAL_TOOL_GUIDANCE)) {
+      const suffix = key.toUpperCase()
+      content = replaceMarkerSection(
+        content,
+        `<!-- PC-OPTIMIZATION-${suffix}-START -->`,
+        `<!-- PC-OPTIMIZATION-${suffix}-END -->`,
+        selections[key] ? guidance : '',
+      )
+    }
+    if (content !== original) {
+      await fse.writeFile(filePath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
+      patched++
+    }
+  }
+  return patched
+}
+
+export async function patchGuardrails(selections = {}, { cwd = process.cwd() } = {}) {
+  const destSkillsDir = path.join(cwd, '.agents', 'skills')
+  const guardrailsPath = path.join(destSkillsDir, 'pc-guardrails-generic', 'SKILL.md')
+  let patchedCount = 0
+
+  if (await fse.pathExists(guardrailsPath)) {
+    let content = await fse.readFile(guardrailsPath, 'utf-8')
+    content = replaceMarkerSection(
+      content,
+      '<!-- PC-GUARDRAILS-CAVEMAN-START -->',
+      '<!-- PC-GUARDRAILS-CAVEMAN-END -->',
+      '',
+    ).replace(
+      '<!-- PC-GUARDRAILS-CAVEMAN-START -->\n\n<!-- PC-GUARDRAILS-CAVEMAN-END -->',
+      '<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->\n<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->',
+    ).replace(
+      '1. Load ALL skills listed under your own `## Abilities` now (Guardrails first, then the rest), by calling the `skill` tool once per `@skill-name`.',
+      '1. The `pc-system-reminders` plugin has already loaded the skills listed under your `## Abilities`, guardrails first.',
+    )
+    for (const [key, markerSuffix] of Object.entries(MARKER_SECTIONS)) {
+      let sectionContent = ''
+      if (selections[key]) {
+        const presetName = key === 'simpleEnglish' ? 'simple-english' : key
+        const presetPath = path.join(GUARDRAILS_FRAGMENT_DIR, `${presetName}.md`)
+        if (await fse.pathExists(presetPath)) {
+          sectionContent = (await fse.readFile(presetPath, 'utf-8')).trim()
+        }
+      }
+      content = replaceMarkerSection(
+        content,
+        `<!-- PC-GUARDRAILS-${markerSuffix}-START -->`,
+        `<!-- PC-GUARDRAILS-${markerSuffix}-END -->`,
+        sectionContent,
+      )
+      if (selections[key]) patchedCount++
+    }
+    await fse.writeFile(guardrailsPath, `${content.replace(/\s*$/, '')}\n`, 'utf-8')
+  } else {
+    info('pc-guardrails-generic not found, skipping guardrails patching')
+  }
+
+  const optionalPatched = await patchOptionalToolGuidance(destSkillsDir, selections)
+  success(`Guardrails patched: ${patchedCount} sections injected; ${optionalPatched} optional tool file(s) updated`)
+  return { patched: true, count: patchedCount, optionalPatched }
+}