@plainconceptsplatform/agent-harness 2.2.0 → 2.3.0

package/src/steps/copy/fullstack-engineer.js

@@ -1,85 +1,88 @@
-import fse from 'fs-extra'
-import path from 'path'
-import { success } from '../../utils/exec.js'
-
-const FULLSTACK_FILE = 'fullstack-engineer.md'
-const FULLSTACK_DESCRIPTION = 'Default engineer that accumulates skills from all created persona engineers. Use as fallback when no specialist matches: but prefer spawning a specific engineer for deterministic results.'
-const FULLSTACK_IDENTITY = 'You are the default engineer, and your body is what the build and plan agents run. You are more complete but less accurate than specialized engineers, so prefer spawning a specialist when one matches the task domain.'
-
-// The reminder plugin owns ability bootstrap. Remove the old prompt-level
-// directive when regenerating so it cannot duplicate the plugin reminder.
-function stripStartupDirective(text) {
-  if (!text) return text
-  return text
-    .split(/\r?\n\r?\n+/)
-    .filter(paragraph => !paragraph.trim().startsWith('**Startup'))
-    .join('\n\n')
-    .trim()
-}
-
-export async function removeLegacyStartupDirectives({ cwd = process.cwd() } = {}) {
-  const agentsDir = path.join(cwd, '.opencode', 'agents')
-  if (!await fse.pathExists(agentsDir)) return 0
-
-  let updated = 0
-  for (const fileName of await fse.readdir(agentsDir)) {
-    if (!fileName.endsWith('.md')) continue
-    const filePath = path.join(agentsDir, fileName)
-    const content = await fse.readFile(filePath, 'utf-8')
-    const cleaned = stripStartupDirective(content)
-    if (cleaned === content.trim()) continue
-    await fse.writeFile(filePath, `${cleaned}\n`, 'utf-8')
-    updated++
-  }
-  return updated
-}
-
-export async function generateFullstackEngineer({ cwd = process.cwd(), updateMode = false } = {}) {
-  const agentsDir = path.join(cwd, '.opencode', 'agents')
-  await fse.ensureDir(agentsDir)
-  const filePath = path.join(agentsDir, FULLSTACK_FILE)
-
-  if (updateMode && await fse.pathExists(filePath)) {
-    return { generated: false, preserved: true }
-  }
-
-  let existingAbilities = null
-  let existingIdentity = null
-  if (await fse.pathExists(filePath)) {
-    const content = await fse.readFile(filePath, 'utf-8')
-    const abilitiesMatch = content.match(/## Abilities\n([\s\S]*?)$/)
-    if (abilitiesMatch) existingAbilities = abilitiesMatch[1].trim()
-    const identityMatch = content.match(/^---\n[\s\S]*?\n---\n\n(.*?)(?:\n\n## Abilities)/s)
-    if (identityMatch) existingIdentity = stripStartupDirective(identityMatch[1])
-  }
-
-  const frontmatter = [
-    '---',
-    `description: ${FULLSTACK_DESCRIPTION}`,
-    // subagent, not primary: build.md and plan.md are the primaries, and
-    // pc-subagent-tiers generates both from this file on every startup.
-    'mode: subagent',
-    'color: warning',
-    'permission:',
-    '  edit: allow',
-    '  bash: allow',
-    '  read: allow',
-    '  glob: allow',
-    '  grep: allow',
-    '  question: allow',
-    '  todowrite: allow',
-    '---',
-  ]
-
-  const identity = existingIdentity ?? FULLSTACK_IDENTITY
-
-  const abilities = existingAbilities ?? [
-    '- Guardrails: @pc-guardrails-generic, @pc-guardrails-project',
-  ].join('\n')
-
-  const content = `${frontmatter.join('\n')}\n\n${identity}\n\n## Abilities\n${abilities}\n`
-
-  await fse.writeFile(filePath, content, 'utf-8')
-  success(`Generated ${FULLSTACK_FILE}`)
-  return { generated: true }
-}
+import fse from 'fs-extra'
+import path from 'path'
+import { success } from '../../utils/exec.js'
+import { agentColor } from '../../utils/agent-color.js'
+
+const FULLSTACK_FILE = 'fullstack-engineer.md'
+const FULLSTACK_DESCRIPTION = 'Default engineer that accumulates skills from all created persona engineers. Use as fallback when no specialist matches: but prefer spawning a specific engineer for deterministic results.'
+const FULLSTACK_IDENTITY = 'You are the default engineer, and your body is what the build and plan agents run. You are more complete but less accurate than specialized engineers, so prefer spawning a specialist when one matches the task domain.'
+
+// The reminder plugin owns ability bootstrap. Remove the old prompt-level
+// directive when regenerating so it cannot duplicate the plugin reminder.
+function stripStartupDirective(text) {
+  if (!text) return text
+  return text
+    .split(/\r?\n\r?\n+/)
+    .filter(paragraph => !paragraph.trim().startsWith('**Startup'))
+    .join('\n\n')
+    .trim()
+}
+
+export async function removeLegacyStartupDirectives({ cwd = process.cwd() } = {}) {
+  const agentsDir = path.join(cwd, '.opencode', 'agents')
+  if (!await fse.pathExists(agentsDir)) return 0
+
+  let updated = 0
+  for (const fileName of await fse.readdir(agentsDir)) {
+    if (!fileName.endsWith('.md')) continue
+    const filePath = path.join(agentsDir, fileName)
+    const content = await fse.readFile(filePath, 'utf-8')
+    const cleaned = stripStartupDirective(content)
+    if (cleaned === content.trim()) continue
+    await fse.writeFile(filePath, `${cleaned}\n`, 'utf-8')
+    updated++
+  }
+  return updated
+}
+
+export async function generateFullstackEngineer({ cwd = process.cwd(), updateMode = false } = {}) {
+  const agentsDir = path.join(cwd, '.opencode', 'agents')
+  await fse.ensureDir(agentsDir)
+  const filePath = path.join(agentsDir, FULLSTACK_FILE)
+
+  if (updateMode && await fse.pathExists(filePath)) {
+    return { generated: false, preserved: true }
+  }
+
+  let existingAbilities = null
+  let existingIdentity = null
+  if (await fse.pathExists(filePath)) {
+    const content = await fse.readFile(filePath, 'utf-8')
+    const abilitiesMatch = content.match(/## Abilities\n([\s\S]*?)$/)
+    if (abilitiesMatch) existingAbilities = abilitiesMatch[1].trim()
+    const identityMatch = content.match(/^---\n[\s\S]*?\n---\n\n(.*?)(?:\n\n## Abilities)/s)
+    if (identityMatch) existingIdentity = stripStartupDirective(identityMatch[1])
+  }
+
+  const frontmatter = [
+    '---',
+    `description: ${FULLSTACK_DESCRIPTION}`,
+    // subagent, not primary: build.md and plan.md are the primaries, and
+    // pc-subagent-tiers generates both from this file on every startup.
+    'mode: subagent',
+    // warning is reserved for plan, so fullstack takes its name-derived hex
+    // like every other subagent.
+    `color: ${agentColor('fullstack-engineer')}`,
+    'permission:',
+    '  edit: allow',
+    '  bash: allow',
+    '  read: allow',
+    '  glob: allow',
+    '  grep: allow',
+    '  question: allow',
+    '  todowrite: allow',
+    '---',
+  ]
+
+  const identity = existingIdentity ?? FULLSTACK_IDENTITY
+
+  const abilities = existingAbilities ?? [
+    '- Guardrails: @pc-guardrails-generic, @pc-guardrails-project',
+  ].join('\n')
+
+  const content = `${frontmatter.join('\n')}\n\n${identity}\n\n## Abilities\n${abilities}\n`
+
+  await fse.writeFile(filePath, content, 'utf-8')
+  success(`Generated ${FULLSTACK_FILE}`)
+  return { generated: true }
+}

package/src/steps/copy/opencode-json.js

@@ -1,147 +1,161 @@
-import fse from 'fs-extra'
-import { applyEdits, modify, parse } from 'jsonc-parser'
-import path from 'node:path'
-import { success } from '../../utils/exec.js'
-
-// The reminder plugin loads every agent ability before work, including
-// user-installed skills outside the pc-* and openspec-* namespaces.
-const SHARED_PERMISSIONS = [
-  ['question', 'allow'],
-  ['todowrite', 'allow'],
-]
-
-function applyModify(text, jsonPath, value) {
-  const edits = modify(text, jsonPath, value, {
-    formattingOptions: { insertSpaces: true, tabSize: 2 },
-  })
-  return applyEdits(text, edits)
-}
-
-export async function patchOpencodeJson(cwd = process.cwd()) {
-  const opencodePath = path.join(cwd, 'opencode.jsonc')
-
-  let text
-  if (await fse.pathExists(opencodePath)) {
-    text = await fse.readFile(opencodePath, 'utf-8')
-  } else {
-    text = JSON.stringify({ $schema: 'https://opencode.ai/config.json' }, null, 2)
-  }
-
-  const errors = []
-  const parsed = parse(text, errors)
-  if (errors.length > 0 || typeof parsed !== 'object') {
-    return { patched: false, reason: 'parse error' }
-  }
-
-  // build and plan are overridden, not disabled. Earlier versions disabled them
-  // and pointed default_agent at fullstack-engineer; now they are the only two
-  // primaries and pc-subagent-tiers regenerates their agent files from
-  // fullstack-engineer.md. A repo patched by an earlier version still carries
-  // `disable: true`, which would hide both agents, so that flag is cleared here.
-  const hasStaleDisable = (
-    parsed?.agent?.build?.disable !== undefined ||
-    parsed?.agent?.plan?.disable !== undefined
-  )
-  const needsAgentOverride = hasStaleDisable || !(
-    parsed?.agent?.build?.mode === 'primary' &&
-    parsed?.agent?.plan?.mode === 'primary' &&
-    parsed?.agent?.plan?.permission?.edit === 'deny'
-  )
-  const needsSkillPermission = parsed?.permission?.skill !== 'allow'
-  const missingSharedPermissions = SHARED_PERMISSIONS.filter(
-    ([key, value]) => parsed?.permission?.[key] !== value,
-  )
-  // opencode only scans .opencode/skills/ by default, but we install to .agents/skills/
-  const needsSkillsPaths = !(
-    Array.isArray(parsed?.skills?.paths) &&
-    parsed.skills.paths.includes('.agents/skills')
-  )
-  const needsCompaction = !(
-    parsed?.compaction?.auto === true &&
-    parsed?.compaction?.prune === true
-  )
-
-  if (!needsAgentOverride && !needsSkillPermission && missingSharedPermissions.length === 0 && !needsSkillsPaths && !needsCompaction) {
-    return { patched: false }
-  }
-
-  // Apply edits sequentially so offsets stay correct
-  if (needsAgentOverride) {
-    // undefined removes the key, clearing the disable left by earlier versions.
-    if (parsed?.agent?.build?.disable !== undefined) {
-      text = applyModify(text, ['agent', 'build', 'disable'], undefined)
-    }
-    if (parsed?.agent?.plan?.disable !== undefined) {
-      text = applyModify(text, ['agent', 'plan', 'disable'], undefined)
-    }
-    text = applyModify(text, ['agent', 'build', 'mode'], 'primary')
-    text = applyModify(text, ['agent', 'plan', 'mode'], 'primary')
-    text = applyModify(text, ['agent', 'plan', 'permission', 'edit'], 'deny')
-  }
-  if (needsSkillPermission) text = applyModify(text, ['permission', 'skill'], 'allow')
-  for (const [key, value] of missingSharedPermissions) {
-    text = applyModify(text, ['permission', key], value)
-  }
-
-  // Ensure .agents/skills is in skills.paths so opencode discovers installed skills
-  if (needsSkillsPaths) {
-    const existingPaths = Array.isArray(parsed?.skills?.paths) ? parsed.skills.paths : []
-    if (!existingPaths.includes('.agents/skills')) {
-      const updatedPaths = [...existingPaths, '.agents/skills']
-      text = applyModify(text, ['skills', 'paths'], updatedPaths)
-    }
-  }
-
-  // Enable context pruning to reduce token costs in long agent sessions
-  if (needsCompaction) {
-    text = applyModify(text, ['compaction', 'auto'], true)
-    text = applyModify(text, ['compaction', 'prune'], true)
-    text = applyModify(text, ['compaction', 'reserved'], 10000)
-  }
-
-  await fse.writeFile(opencodePath, text, 'utf-8')
-  if (needsAgentOverride) {
-    success('Set build/plan as the primary agents in opencode.jsonc (plan is read-only)')
-  }
-  if (needsSkillPermission) {
-    success('Allowed skill loading in opencode.jsonc')
-  }
-  if (missingSharedPermissions.length > 0) {
-    success('Allowed question/todowrite tools in opencode.jsonc')
-  }
-  if (needsSkillsPaths) {
-    success('Added .agents/skills to skills.paths in opencode.jsonc')
-  }
-  if (needsCompaction) {
-    success('Enabled context pruning (compaction.prune) in opencode.jsonc')
-  }
-
-  return { patched: true }
-}
-
-const OPENCODE_PACKAGE_DEPENDENCIES = {
-  '@opencode-ai/plugin': '1.18.19',
-  '@opentui/core': '0.5.6',
-  '@opentui/solid': '0.5.6',
-  'solid-js': '1.9.12',
-}
-
-export async function patchOpencodePackage(cwd = process.cwd()) {
-  const packagePath = path.join(cwd, '.opencode', 'package.json')
-  if (!await fse.pathExists(packagePath)) return { patched: false }
-
-  const packageJson = await fse.readJson(packagePath).catch(() => null)
-  if (!packageJson?.dependencies) return { patched: false }
-
-  let patched = false
-  for (const [name, version] of Object.entries(OPENCODE_PACKAGE_DEPENDENCIES)) {
-    if (!(name in packageJson.dependencies) || packageJson.dependencies[name] === version) continue
-    packageJson.dependencies[name] = version
-    patched = true
-  }
-  if (!patched) return { patched: false }
-
-  await fse.writeJson(packagePath, packageJson, { spaces: 2 })
-  success('Updated OpenCode plugin dependencies in .opencode/package.json')
-  return { patched: true }
-}
+import fse from 'fs-extra'
+import { applyEdits, modify, parse } from 'jsonc-parser'
+import path from 'node:path'
+import { success } from '../../utils/exec.js'
+
+// The reminder plugin loads every agent ability before work, including
+// user-installed skills outside the pc-* and openspec-* namespaces.
+const SHARED_PERMISSIONS = [
+  ['question', 'allow'],
+  ['todowrite', 'allow'],
+]
+
+function applyModify(text, jsonPath, value) {
+  const edits = modify(text, jsonPath, value, {
+    formattingOptions: { insertSpaces: true, tabSize: 2 },
+  })
+  return applyEdits(text, edits)
+}
+
+export async function patchOpencodeJson(cwd = process.cwd()) {
+  const opencodePath = path.join(cwd, 'opencode.jsonc')
+
+  let text
+  if (await fse.pathExists(opencodePath)) {
+    text = await fse.readFile(opencodePath, 'utf-8')
+  } else {
+    text = JSON.stringify({ $schema: 'https://opencode.ai/config.json' }, null, 2)
+  }
+
+  const errors = []
+  const parsed = parse(text, errors)
+  if (errors.length > 0 || typeof parsed !== 'object') {
+    return { patched: false, reason: 'parse error' }
+  }
+
+  // build and plan are overridden, not disabled. Earlier versions disabled them
+  // and pointed default_agent at fullstack-engineer; now they are the only two
+  // primaries and pc-subagent-tiers regenerates their agent files from
+  // fullstack-engineer.md. A repo patched by an earlier version still carries
+  // `disable: true`, which would hide both agents, so that flag is cleared here.
+  const hasStaleDisable = (
+    parsed?.agent?.build?.disable !== undefined ||
+    parsed?.agent?.plan?.disable !== undefined
+  )
+  const needsAgentOverride = hasStaleDisable || !(
+    parsed?.agent?.build?.mode === 'primary' &&
+    parsed?.agent?.plan?.mode === 'primary' &&
+    parsed?.agent?.plan?.permission?.edit === 'deny'
+  )
+
+  // default_agent pointing at fullstack-engineer is now invalid: it became a
+  // subagent when build and plan took over as the only primaries, so opencode
+  // has no valid default to open a session with. A deliberate choice of build
+  // or plan is left alone; anything else is repointed at plan, so a session
+  // starts read-only.
+  const currentDefault = parsed?.default_agent
+  const needsDefaultAgent = currentDefault !== 'plan' && currentDefault !== 'build'
+  const needsSkillPermission = parsed?.permission?.skill !== 'allow'
+  const missingSharedPermissions = SHARED_PERMISSIONS.filter(
+    ([key, value]) => parsed?.permission?.[key] !== value,
+  )
+  // opencode only scans .opencode/skills/ by default, but we install to .agents/skills/
+  const needsSkillsPaths = !(
+    Array.isArray(parsed?.skills?.paths) &&
+    parsed.skills.paths.includes('.agents/skills')
+  )
+  const needsCompaction = !(
+    parsed?.compaction?.auto === true &&
+    parsed?.compaction?.prune === true
+  )
+
+  if (!needsAgentOverride && !needsDefaultAgent && !needsSkillPermission && missingSharedPermissions.length === 0 && !needsSkillsPaths && !needsCompaction) {
+    return { patched: false }
+  }
+
+  // Apply edits sequentially so offsets stay correct
+  if (needsAgentOverride) {
+    // undefined removes the key, clearing the disable left by earlier versions.
+    if (parsed?.agent?.build?.disable !== undefined) {
+      text = applyModify(text, ['agent', 'build', 'disable'], undefined)
+    }
+    if (parsed?.agent?.plan?.disable !== undefined) {
+      text = applyModify(text, ['agent', 'plan', 'disable'], undefined)
+    }
+    text = applyModify(text, ['agent', 'build', 'mode'], 'primary')
+    text = applyModify(text, ['agent', 'plan', 'mode'], 'primary')
+    text = applyModify(text, ['agent', 'plan', 'permission', 'edit'], 'deny')
+  }
+  if (needsDefaultAgent) {
+    text = applyModify(text, ['default_agent'], 'plan')
+  }
+  if (needsSkillPermission) text = applyModify(text, ['permission', 'skill'], 'allow')
+  for (const [key, value] of missingSharedPermissions) {
+    text = applyModify(text, ['permission', key], value)
+  }
+
+  // Ensure .agents/skills is in skills.paths so opencode discovers installed skills
+  if (needsSkillsPaths) {
+    const existingPaths = Array.isArray(parsed?.skills?.paths) ? parsed.skills.paths : []
+    if (!existingPaths.includes('.agents/skills')) {
+      const updatedPaths = [...existingPaths, '.agents/skills']
+      text = applyModify(text, ['skills', 'paths'], updatedPaths)
+    }
+  }
+
+  // Enable context pruning to reduce token costs in long agent sessions
+  if (needsCompaction) {
+    text = applyModify(text, ['compaction', 'auto'], true)
+    text = applyModify(text, ['compaction', 'prune'], true)
+    text = applyModify(text, ['compaction', 'reserved'], 10000)
+  }
+
+  await fse.writeFile(opencodePath, text, 'utf-8')
+  if (needsAgentOverride) {
+    success('Set build/plan as the primary agents in opencode.jsonc (plan is read-only)')
+  }
+  if (needsDefaultAgent) {
+    success(`default_agent -> plan${currentDefault ? ` (was ${currentDefault})` : ''}`)
+  }
+  if (needsSkillPermission) {
+    success('Allowed skill loading in opencode.jsonc')
+  }
+  if (missingSharedPermissions.length > 0) {
+    success('Allowed question/todowrite tools in opencode.jsonc')
+  }
+  if (needsSkillsPaths) {
+    success('Added .agents/skills to skills.paths in opencode.jsonc')
+  }
+  if (needsCompaction) {
+    success('Enabled context pruning (compaction.prune) in opencode.jsonc')
+  }
+
+  return { patched: true }
+}
+
+const OPENCODE_PACKAGE_DEPENDENCIES = {
+  '@opencode-ai/plugin': '1.18.19',
+  '@opentui/core': '0.5.6',
+  '@opentui/solid': '0.5.6',
+  'solid-js': '1.9.12',
+}
+
+export async function patchOpencodePackage(cwd = process.cwd()) {
+  const packagePath = path.join(cwd, '.opencode', 'package.json')
+  if (!await fse.pathExists(packagePath)) return { patched: false }
+
+  const packageJson = await fse.readJson(packagePath).catch(() => null)
+  if (!packageJson?.dependencies) return { patched: false }
+
+  let patched = false
+  for (const [name, version] of Object.entries(OPENCODE_PACKAGE_DEPENDENCIES)) {
+    if (!(name in packageJson.dependencies) || packageJson.dependencies[name] === version) continue
+    packageJson.dependencies[name] = version
+    patched = true
+  }
+  if (!patched) return { patched: false }
+
+  await fse.writeJson(packagePath, packageJson, { spaces: 2 })
+  success('Updated OpenCode plugin dependencies in .opencode/package.json')
+  return { patched: true }
+}

package/src/steps/metadata/index.js

@@ -59,6 +59,10 @@ export async function writeHarnessConfig(data) {
     ),
     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 = {

package/src/steps/optimization/detect.js

@@ -0,0 +1,66 @@
+import fse from 'fs-extra'
+import path from 'node:path'
+import { parse } from 'jsonc-parser'
+
+/**
+ * Work out which optional tools a project actually has, rather than trusting
+ * the flags in harness.json.
+ *
+ * Those flags drift. Numa and Odissey both had codegraph and agentmemory MCP
+ * servers enabled in opencode.jsonc and the humanizer and simple-english skills
+ * installed, while harness.json recorded `codegraph: false`, `memory: false` and
+ * no humanizer key at all. patchGuardrails believed the config and emptied those
+ * marker sections, so agents lost the guidance for tools the project was running.
+ *
+ * Detection only ever turns a tool ON. A flag that is already true is left
+ * alone, because some of these install globally and cannot be seen from inside
+ * the repository at all.
+ */
+
+function mcpServers(cwd) {
+  const configPath = path.join(cwd, 'opencode.jsonc')
+  if (!fse.pathExistsSync(configPath)) return {}
+  const errors = []
+  const parsed = parse(fse.readFileSync(configPath, 'utf-8'), errors)
+  if (errors.length > 0 || typeof parsed !== 'object' || parsed === null) return {}
+  return parsed.mcp ?? {}
+}
+
+function hasSkill(cwd, name) {
+  return fse.pathExistsSync(path.join(cwd, '.agents', 'skills', name))
+}
+
+/** An MCP server counts as present unless it is explicitly disabled. */
+function hasMcp(servers, name) {
+  const server = servers[name]
+  if (!server) return false
+  return server.enabled !== false
+}
+
+export function detectInstalledTools(cwd = process.cwd()) {
+  const servers = mcpServers(cwd)
+  return {
+    // rtk is a global CLI with nothing to find in the repo, so it is not
+    // detectable here and the saved flag stands on its own.
+    codegraph: hasMcp(servers, 'codegraph') || fse.pathExistsSync(path.join(cwd, '.codegraph')),
+    memory: hasMcp(servers, 'agentmemory'),
+    simpleEnglish: hasSkill(cwd, 'simple-english'),
+    humanizer: hasSkill(cwd, 'humanizer'),
+    quota: fse.pathExistsSync(path.join(cwd, '.opencode', 'opencode-quota')),
+  }
+}
+
+/**
+ * Saved flags merged with what is on disk. Detection can only add, so a tool
+ * recorded as enabled stays enabled even when nothing local proves it.
+ */
+export function reconcileTools(saved = {}, cwd = process.cwd()) {
+  const detected = detectInstalledTools(cwd)
+  const merged = { ...saved }
+  for (const [key, present] of Object.entries(detected)) {
+    if (present) merged[key] = true
+  }
+  // simpleEnglish replaced caveman; honour the old key one last time.
+  if (saved.caveman) merged.simpleEnglish = true
+  return merged
+}