@plainconceptsplatform/agent-harness 3.9.0 → 3.10.0

package/cli/steps/clean/index.js

@@ -1,120 +1,120 @@
-import { checkbox } from '@inquirer/prompts'
-import fse from 'fs-extra'
-import path from 'path'
-import { fileURLToPath } from 'url'
-import { findAiFiles } from '../../utils/copy.js'
-import { header, info, success, warn } from '../../utils/exec.js'
-import { MARKERS } from '../../utils/terminal.js'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const CLEAN_PRESET_PATH = path.resolve(__dirname, '../../presets/clean.json')
-const cleanPreset = await fse.readJson(CLEAN_PRESET_PATH)
-
-async function childrenExcludingPreserved(dir) {
-  const results = []
-  if (!await fse.pathExists(dir)) return results
-  const entries = await fse.readdir(dir)
-  for (const entry of entries) {
-    if (cleanPreset.preserveSubfolders.includes(entry)) continue
-    results.push(path.join(dir, entry))
-  }
-  return results
-}
-
-async function isPopulated(filePath) {
-  if (!await fse.pathExists(filePath)) return false
-  const content = await fse.readFile(filePath, 'utf-8')
-  const trimmed = content.trim()
-  if (!trimmed) return false
-  if (trimmed.startsWith('<!-- onboard-prompt')) return false
-  return true
-}
-
-async function hasOpenspecHistory(cwd) {
-  const changesDir = path.join(cwd, 'openspec', 'changes')
-  const archiveDir = path.join(cwd, 'openspec', 'archive')
-  if (await fse.pathExists(changesDir)) {
-    const entries = await fse.readdir(changesDir)
-    if (entries.length > 0) return true
-  }
-  if (await fse.pathExists(archiveDir)) {
-    const entries = await fse.readdir(archiveDir)
-    if (entries.length > 0) return true
-  }
-  return false
-}
-
-export async function cleanAiFiles({ removeLegacyConfig = false } = {}) {
-  header('Step 2, Existing AI config files')
-
-  const cwd = process.cwd()
-  const ctx = {
-    hasDesign: await isPopulated(path.join(cwd, 'DESIGN.md')),
-    hasArchitecture: await isPopulated(path.join(cwd, 'ARCHITECTURE.md')),
-    hasOpenspec: await hasOpenspecHistory(cwd),
-  }
-
-  if (ctx.hasDesign) info('DESIGN.md exists and is populated, keeping it')
-  if (ctx.hasArchitecture) info('ARCHITECTURE.md exists and is populated, keeping it')
-  if (ctx.hasOpenspec) info('openspec/ history exists, keeping it')
-
-  const legacyConfig = path.join(cwd, '.opencode', 'opencode.json')
-  if (removeLegacyConfig && await fse.pathExists(legacyConfig)) {
-    await fse.remove(legacyConfig)
-    info('Removed legacy .opencode/opencode.json')
-  }
-
-  const flatFiles = await findAiFiles(cwd, cleanPreset.detectFiles)
-  const dirTargets = cleanPreset.directoryTargets
-  const dirEntries = []
-  for (const dirName of dirTargets) {
-    const dirPath = path.join(cwd, dirName)
-    const children = await childrenExcludingPreserved(dirPath)
-    if (children.length > 0) {
-      dirEntries.push(...children)
-    } else if (await fse.pathExists(dirPath)) {
-      // Directory exists but all children are preserved (e.g. only skills/):
-      // still offer the directory itself as a removable option.
-      dirEntries.push(dirPath)
-    }
-  }
-
-  const filteredFlat = flatFiles.filter(f => {
-    const rel = path.relative(cwd, f)
-    if (dirTargets.includes(rel)) return false
-    if (cleanPreset.preserve.some(p => rel === p || rel.startsWith(p + path.sep))) return false
-    return true
-  })
-
-  const allToRemove = [...filteredFlat, ...dirEntries]
-
-  if (allToRemove.length === 0) {
-    success('No existing AI config files to remove')
-    return ctx
-  }
-
-  const choices = allToRemove.map(f => ({
-    name: path.relative(cwd, f).replace(/\\/g, '/'),
-    value: f,
-    checked: true,
-  }))
-
-  const selected = await checkbox({
-    message: cleanPreset.selectionMessage,
-    choices,
-  })
-
-  if (!selected || selected.length === 0) {
-    success('No AI config files selected for removal')
-    return ctx
-  }
-
-  warn('Removing selected AI config files:')
-  for (const f of selected) {
-    info(`${MARKERS.EMPTY}${f.replace(cwd + path.sep, '')}`)
-    await fse.remove(f)
-  }
-  success('Removed existing AI config files')
-
-  return ctx
-}
+import { checkbox } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { findAiFiles } from '../../utils/copy.js'
+import { header, info, success, warn } from '../../utils/exec.js'
+import { MARKERS } from '../../utils/terminal.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const CLEAN_PRESET_PATH = path.resolve(__dirname, '../../presets/clean.json')
+const cleanPreset = await fse.readJson(CLEAN_PRESET_PATH)
+
+async function childrenExcludingPreserved(dir) {
+  const results = []
+  if (!await fse.pathExists(dir)) return results
+  const entries = await fse.readdir(dir)
+  for (const entry of entries) {
+    if (cleanPreset.preserveSubfolders.includes(entry)) continue
+    results.push(path.join(dir, entry))
+  }
+  return results
+}
+
+async function isPopulated(filePath) {
+  if (!await fse.pathExists(filePath)) return false
+  const content = await fse.readFile(filePath, 'utf-8')
+  const trimmed = content.trim()
+  if (!trimmed) return false
+  if (trimmed.startsWith('<!-- onboard-prompt')) return false
+  return true
+}
+
+async function hasOpenspecHistory(cwd) {
+  const changesDir = path.join(cwd, 'openspec', 'changes')
+  const archiveDir = path.join(cwd, 'openspec', 'archive')
+  if (await fse.pathExists(changesDir)) {
+    const entries = await fse.readdir(changesDir)
+    if (entries.length > 0) return true
+  }
+  if (await fse.pathExists(archiveDir)) {
+    const entries = await fse.readdir(archiveDir)
+    if (entries.length > 0) return true
+  }
+  return false
+}
+
+export async function cleanAiFiles({ removeLegacyConfig = false } = {}) {
+  header('Step 2, Existing AI config files')
+
+  const cwd = process.cwd()
+  const ctx = {
+    hasDesign: await isPopulated(path.join(cwd, 'DESIGN.md')),
+    hasArchitecture: await isPopulated(path.join(cwd, 'ARCHITECTURE.md')),
+    hasOpenspec: await hasOpenspecHistory(cwd),
+  }
+
+  if (ctx.hasDesign) info('DESIGN.md exists and is populated, keeping it')
+  if (ctx.hasArchitecture) info('ARCHITECTURE.md exists and is populated, keeping it')
+  if (ctx.hasOpenspec) info('openspec/ history exists, keeping it')
+
+  const legacyConfig = path.join(cwd, '.opencode', 'opencode.json')
+  if (removeLegacyConfig && await fse.pathExists(legacyConfig)) {
+    await fse.remove(legacyConfig)
+    info('Removed legacy .opencode/opencode.json')
+  }
+
+  const flatFiles = await findAiFiles(cwd, cleanPreset.detectFiles)
+  const dirTargets = cleanPreset.directoryTargets
+  const dirEntries = []
+  for (const dirName of dirTargets) {
+    const dirPath = path.join(cwd, dirName)
+    const children = await childrenExcludingPreserved(dirPath)
+    if (children.length > 0) {
+      dirEntries.push(...children)
+    } else if (await fse.pathExists(dirPath)) {
+      // Directory exists but all children are preserved (e.g. only skills/):
+      // still offer the directory itself as a removable option.
+      dirEntries.push(dirPath)
+    }
+  }
+
+  const filteredFlat = flatFiles.filter(f => {
+    const rel = path.relative(cwd, f)
+    if (dirTargets.includes(rel)) return false
+    if (cleanPreset.preserve.some(p => rel === p || rel.startsWith(p + path.sep))) return false
+    return true
+  })
+
+  const allToRemove = [...filteredFlat, ...dirEntries]
+
+  if (allToRemove.length === 0) {
+    success('No existing AI config files to remove')
+    return ctx
+  }
+
+  const choices = allToRemove.map(f => ({
+    name: path.relative(cwd, f).replace(/\\/g, '/'),
+    value: f,
+    checked: true,
+  }))
+
+  const selected = await checkbox({
+    message: cleanPreset.selectionMessage,
+    choices,
+  })
+
+  if (!selected || selected.length === 0) {
+    success('No AI config files selected for removal')
+    return ctx
+  }
+
+  warn('Removing selected AI config files:')
+  for (const f of selected) {
+    info(`${MARKERS.EMPTY}${f.replace(cwd + path.sep, '')}`)
+    await fse.remove(f)
+  }
+  success('Removed existing AI config files')
+
+  return ctx
+}

package/cli/steps/copy/agents.js

@@ -1,176 +1,176 @@
-import fse from 'fs-extra'
-import path from 'path'
-import { fileURLToPath } from 'url'
-import { info, success, warn } from '../../utils/exec.js'
-import { ContractError, isTemplateSource, loadContract } from '../../../harness/.opencode/scripts/platform-contract.mjs'
-
-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 (##/###/####), the `Step N,` prefix and any ` (if Yes)` suffix have all
-// drifted before, and every drift silently turned the patch into a no-op that
-// only showed up as a warning nobody read.
-const HISTORY_STEP_TITLE = 'Archive project history'
-const ARCHITECTURE_STEP_TITLE = 'Generate ARCHITECTURE.md'
-const DESIGN_STEP_TITLE = 'Generate DESIGN.md'
-
-function stepHeadingPattern(title) {
-  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  return new RegExp(`^#{2,4}\\s+(?:Step\\s+\\d+[a-z]?[,:]\\s+)?${escaped}\\b`, 'i')
-}
-
-// 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 }
-
-  // The block ends at the next heading or rule, NOT at end of file. Scanning
-  // only for `---` meant a document without one lost everything below the
-  // matched step.
-  let end = lines.length
-  for (let i = start + 1; i < lines.length; i++) {
-    const line = lines[i].trim()
-    if (line === '---' || /^#{1,4}\s/.test(line)) { end = i; break }
-  }
-
-  lines.splice(start + 1, end - start - 1, '', `> ${note}`, '')
-  return { content: lines.join('\n'), matched: true }
-}
-
-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 -->'
-const PLATFORM_SKILLS_START = '<!-- PC-PLATFORM-SKILLS-START -->'
-const PLATFORM_SKILLS_END = '<!-- PC-PLATFORM-SKILLS-END -->'
-const PLATFORM_CONTRACT_START = '<!-- PC-PLATFORM-CONTRACT-START -->'
-const PLATFORM_CONTRACT_END = '<!-- PC-PLATFORM-CONTRACT-END -->'
-
-const MANDATORY_SKILLS_BODY = 'Mandatory, before any edit, shell command or subagent spawn: read `.agents/skills/pc-guardrails-generic/SKILL.md`, then `.agents/skills/pc-guardrails-project/SKILL.md` if present. They are instructions, not references: a loaded skill may name further skills, and those load too before the work they cover.'
-
-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.
-  const body = replacement.trim()
-  return content.replace(pattern, () => (body ? `${start}\n${body}\n${end}` : `${start}\n${end}`))
-}
-
-// Reading the file works in every agent, not only the ones that discover
-// `.agents/skills` natively (Claude Code reads `.claude/skills`). Installs from
-// before this block have no marker pair and update never rewrites AGENTS.md, so
-// append a section then; the marker pair keeps later updates idempotent.
-function patchMandatorySkillsBlock(content) {
-  if (content.includes(PLATFORM_SKILLS_START)) {
-    return replaceBetween(content, PLATFORM_SKILLS_START, PLATFORM_SKILLS_END, MANDATORY_SKILLS_BODY)
-  }
-  return `${content.replace(/\s*$/, '')}\n\n## Mandatory skills\n\n${PLATFORM_SKILLS_START}\n${MANDATORY_SKILLS_BODY}\n${PLATFORM_SKILLS_END}\n`
-}
-
-export function reuseBlock(contract, templateSource = false) {
-  const { docs = [], packages = [], names = [] } = contract?.reuse ?? {}
-  if (!docs.length && !packages.length && !names.length) return ''
-  const code = list => list.map(item => `\`${item}\``).join(', ')
-  return [
-    '## Reuse before you build',
-    '',
-    `This repository receives shared code from ${contract.source.name} (${contract.source.url}), declared in \`.platform/contract.yml\`.`,
-    '',
-    ...(docs.length ? [`- Never design something new before reading ${code(docs)}.`] : []),
-    ...(packages.length ? [`- Never re-implement an export of ${code(packages)}; import it.`] : []),
-    ...(names.length ? [`- Never write your own ${code(names)}; reuse the existing one.`] : []),
-    ...(templateSource ? [] : [`- Never edit a path listed under \`owned\`. Ask for the change at ${contract.source.changes}, or add a dated exception to \`${contract.exceptions}\`.`]),
-  ].join('\n')
-}
-
-function contractBlock(cwd) {
-  try {
-    const contract = loadContract(cwd)
-    return reuseBlock(contract, isTemplateSource(cwd, contract))
-  } catch (err) {
-    if (!(err instanceof ContractError)) throw err
-    warn(`${err.message} The "Reuse before you build" block in AGENTS.md was left as it was.`)
-    return null
-  }
-}
-
-// Installs from before the contract have no marker pair, and update never rewrites AGENTS.md: append it then.
-function patchContractBlock(content, cwd) {
-  const block = contractBlock(cwd)
-  if (block == null) return content
-  if (content.includes(PLATFORM_CONTRACT_START)) return replaceBetween(content, PLATFORM_CONTRACT_START, PLATFORM_CONTRACT_END, block)
-  return block ? `${content.replace(/\s*$/, '')}\n\n${PLATFORM_CONTRACT_START}\n${block}\n${PLATFORM_CONTRACT_END}\n` : content
-}
-
-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,
-      'Skipped during onboarding: this project already had an openspec/ history. Do not archive again; continue with the next step.'],
-    [ctx.hasArchitecture, ARCHITECTURE_STEP_TITLE,
-      'Skipped during onboarding: ARCHITECTURE.md already exists. Run /make-architecture to regenerate it, which keeps its update mode.'],
-    [ctx.hasDesign, DESIGN_STEP_TITLE,
-      'Skipped during onboarding: DESIGN.md already exists. Run /make-design to regenerate it, which keeps its update mode.'],
-  ]
-
-  for (const [enabled, title, 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
-    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'))
-    content = patchMandatorySkillsBlock(content)
-    content = patchContractBlock(content, cwd)
-    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'
+import { ContractError, isTemplateSource, loadContract } from '../../../harness/.opencode/scripts/platform-contract.mjs'
+
+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 (##/###/####), the `Step N,` prefix and any ` (if Yes)` suffix have all
+// drifted before, and every drift silently turned the patch into a no-op that
+// only showed up as a warning nobody read.
+const HISTORY_STEP_TITLE = 'Archive project history'
+const ARCHITECTURE_STEP_TITLE = 'Generate ARCHITECTURE.md'
+const DESIGN_STEP_TITLE = 'Generate DESIGN.md'
+
+function stepHeadingPattern(title) {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`^#{2,4}\\s+(?:Step\\s+\\d+[a-z]?[,:]\\s+)?${escaped}\\b`, 'i')
+}
+
+// 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 }
+
+  // The block ends at the next heading or rule, NOT at end of file. Scanning
+  // only for `---` meant a document without one lost everything below the
+  // matched step.
+  let end = lines.length
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i].trim()
+    if (line === '---' || /^#{1,4}\s/.test(line)) { end = i; break }
+  }
+
+  lines.splice(start + 1, end - start - 1, '', `> ${note}`, '')
+  return { content: lines.join('\n'), matched: true }
+}
+
+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 -->'
+const PLATFORM_SKILLS_START = '<!-- PC-PLATFORM-SKILLS-START -->'
+const PLATFORM_SKILLS_END = '<!-- PC-PLATFORM-SKILLS-END -->'
+const PLATFORM_CONTRACT_START = '<!-- PC-PLATFORM-CONTRACT-START -->'
+const PLATFORM_CONTRACT_END = '<!-- PC-PLATFORM-CONTRACT-END -->'
+
+const MANDATORY_SKILLS_BODY = 'Mandatory, before any edit, shell command or subagent spawn: read `.agents/skills/pc-guardrails-generic/SKILL.md`, then `.agents/skills/pc-guardrails-project/SKILL.md` if present. They are instructions, not references: a loaded skill may name further skills, and those load too before the work they cover.'
+
+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.
+  const body = replacement.trim()
+  return content.replace(pattern, () => (body ? `${start}\n${body}\n${end}` : `${start}\n${end}`))
+}
+
+// Reading the file works in every agent, not only the ones that discover
+// `.agents/skills` natively (Claude Code reads `.claude/skills`). Installs from
+// before this block have no marker pair and update never rewrites AGENTS.md, so
+// append a section then; the marker pair keeps later updates idempotent.
+function patchMandatorySkillsBlock(content) {
+  if (content.includes(PLATFORM_SKILLS_START)) {
+    return replaceBetween(content, PLATFORM_SKILLS_START, PLATFORM_SKILLS_END, MANDATORY_SKILLS_BODY)
+  }
+  return `${content.replace(/\s*$/, '')}\n\n## Mandatory skills\n\n${PLATFORM_SKILLS_START}\n${MANDATORY_SKILLS_BODY}\n${PLATFORM_SKILLS_END}\n`
+}
+
+export function reuseBlock(contract, templateSource = false) {
+  const { docs = [], packages = [], names = [] } = contract?.reuse ?? {}
+  if (!docs.length && !packages.length && !names.length) return ''
+  const code = list => list.map(item => `\`${item}\``).join(', ')
+  return [
+    '## Reuse before you build',
+    '',
+    `This repository receives shared code from ${contract.source.name} (${contract.source.url}), declared in \`.platform/contract.yml\`.`,
+    '',
+    ...(docs.length ? [`- Never design something new before reading ${code(docs)}.`] : []),
+    ...(packages.length ? [`- Never re-implement an export of ${code(packages)}; import it.`] : []),
+    ...(names.length ? [`- Never write your own ${code(names)}; reuse the existing one.`] : []),
+    ...(templateSource ? [] : [`- Never edit a path listed under \`owned\`. Ask for the change at ${contract.source.changes}, or add a dated exception to \`${contract.exceptions}\`.`]),
+  ].join('\n')
+}
+
+function contractBlock(cwd) {
+  try {
+    const contract = loadContract(cwd)
+    return reuseBlock(contract, isTemplateSource(cwd, contract))
+  } catch (err) {
+    if (!(err instanceof ContractError)) throw err
+    warn(`${err.message} The "Reuse before you build" block in AGENTS.md was left as it was.`)
+    return null
+  }
+}
+
+// Installs from before the contract have no marker pair, and update never rewrites AGENTS.md: append it then.
+function patchContractBlock(content, cwd) {
+  const block = contractBlock(cwd)
+  if (block == null) return content
+  if (content.includes(PLATFORM_CONTRACT_START)) return replaceBetween(content, PLATFORM_CONTRACT_START, PLATFORM_CONTRACT_END, block)
+  return block ? `${content.replace(/\s*$/, '')}\n\n${PLATFORM_CONTRACT_START}\n${block}\n${PLATFORM_CONTRACT_END}\n` : content
+}
+
+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,
+      'Skipped during onboarding: this project already had an openspec/ history. Do not archive again; continue with the next step.'],
+    [ctx.hasArchitecture, ARCHITECTURE_STEP_TITLE,
+      'Skipped during onboarding: ARCHITECTURE.md already exists. Run /make-architecture to regenerate it, which keeps its update mode.'],
+    [ctx.hasDesign, DESIGN_STEP_TITLE,
+      'Skipped during onboarding: DESIGN.md already exists. Run /make-design to regenerate it, which keeps its update mode.'],
+  ]
+
+  for (const [enabled, title, 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
+    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'))
+    content = patchMandatorySkillsBlock(content)
+    content = patchContractBlock(content, cwd)
+    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}`)
+  }
+}
+
+