@plainconceptsplatform/agent-harness 2.0.0

package/src/steps/optimization/codegraph.js

@@ -0,0 +1,127 @@
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser'
+import { header, success, warn, error, loading } from '../../utils/exec.js'
+
+/**
+ * Normalizes codegraph's MCP entry in the project-level OpenCode config.
+ * Older codegraph versions write `mcpServers`; OpenCode expects `mcp`.
+ * Returns true if the config was successfully normalized (or no config exists).
+ */
+export async function fixCodegraphConfig() {
+  const cwd = process.cwd()
+  const configFile = path.join(cwd, 'opencode.jsonc')
+
+  if (!await fse.pathExists(configFile)) return true
+
+  let configText
+  let config
+  try {
+    configText = await fse.readFile(configFile, 'utf-8')
+    const errors = []
+    config = parseJsonc(configText, errors)
+    if (errors.length > 0) throw new Error(`parse errors: ${errors.length}`)
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+      throw new Error('unexpected structure')
+    }
+  } catch {
+    warn('Could not parse opencode.jsonc, leaving it untouched')
+    return false
+  }
+
+  const legacyMcp = config.mcpServers
+  const mcp = config.mcp || {}
+  const entries = { ...legacyMcp, ...mcp }
+  let changed = false
+
+  if (Object.keys(entries).length > 0) {
+    for (const entry of Object.values(entries)) {
+      if (Array.isArray(entry.command) && entry.command[0] === 'codegraph') {
+        entry.command = ['npx', '@colbymchenry/codegraph', ...entry.command.slice(1)]
+        // codegraph defaults to a 30s MCP timeout, which fails under parallel
+        // subagent load. Raise it unless the user has set one explicitly.
+        if (entry.timeout == null) entry.timeout = 120000
+      }
+    }
+    for (const [name, entry] of Object.entries(entries)) {
+      const edits = modify(configText, ['mcp', name], entry, {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+      })
+      configText = applyEdits(configText, edits)
+      changed = true
+    }
+  }
+
+  if (legacyMcp) {
+    configText = applyEdits(configText, modify(configText, ['mcpServers'], undefined, {
+      formattingOptions: { insertSpaces: true, tabSize: 2 },
+    }))
+    changed = true
+  }
+
+  if (changed) {
+    await fse.writeFile(configFile, configText, 'utf-8')
+    warn('Normalized codegraph MCP config in opencode.jsonc')
+  }
+
+  return true
+}
+
+export async function installCodegraph(options = {}) {
+  if (!options.skipHeader) header('Installing codegraph')
+
+  const location = options.installScope === 'global' ? 'global' : 'local'
+
+  loading(`configuring codegraph for opencode (${location})...`)
+
+  try {
+    const installResult = await execa(
+      'npx',
+      ['--yes', '@colbymchenry/codegraph', 'install', '--target=opencode', `--location=${location}`, '--yes'],
+      {
+        cwd: process.cwd(),
+        reject: false,
+        stdio: 'pipe',
+      }
+    )
+
+    if (installResult.exitCode !== 0) {
+      warn('codegraph install exited with non-zero code')
+      return { optedIn: true, installed: false }
+    }
+
+    const configFixed = await fixCodegraphConfig()
+
+    if (!configFixed) {
+      warn('codegraph config could not be merged: skipping init')
+      return { optedIn: true, installed: false }
+    }
+
+    success(`codegraph configured for opencode (${location})`)
+  } catch (err) {
+    error(`Failed to install codegraph: ${err.message}`)
+    return { optedIn: true, installed: false }
+  }
+
+  loading('initializing codegraph project index...')
+
+  try {
+    const initResult = await execa('npx', ['@colbymchenry/codegraph', 'init', '-i'], {
+      cwd: process.cwd(),
+      reject: false,
+      stdio: 'pipe',
+    })
+
+    if (initResult.exitCode !== 0) {
+      warn('codegraph init exited with non-zero code')
+      return { optedIn: true, installed: false }
+    }
+    success('codegraph project index initialized')
+  } catch (err) {
+    error(`Failed to initialize codegraph: ${err.message}`)
+    return { optedIn: true, installed: false }
+  }
+
+  return { optedIn: true, installed: true }
+}

package/src/steps/optimization/humanizer.js

@@ -0,0 +1,17 @@
+import { addSkillToLock } from './skills-lock.js'
+import { header, success, info } from '../../utils/exec.js'
+
+const SKILL_ENTRY = {
+  source: 'blader/humanizer',
+  sourceType: 'github',
+  skillPath: 'SKILL.md',
+}
+
+export async function installHumanizer(options = {}) {
+  if (!options.skipHeader) header('Installing humanizer')
+
+  info('Adding humanizer to skills-lock.json for batch install')
+  await addSkillToLock('humanizer', SKILL_ENTRY)
+  success('humanizer queued for installation')
+  return { optedIn: true, installed: true }
+}

package/src/steps/optimization/index.js

@@ -0,0 +1,163 @@
+import { checkbox, confirm } from '@inquirer/prompts'
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { code, commandExists, header, info, loading, success, warn } from '../../utils/exec.js'
+import { installQuota } from './quota.js'
+import { installSimpleEnglish } from './simple-english.js'
+import { installCodegraph } from './codegraph.js'
+import { installMemory } from './memory.js'
+import { installHumanizer } from './humanizer.js'
+import { patchGuardrails } from './patch-guardrails.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const OPTIMIZATION_PRESET_PATH = path.resolve(__dirname, '../../presets/optimization.json')
+const optimizationPreset = await fse.readJson(OPTIMIZATION_PRESET_PATH)
+
+export async function checkRtk(options = {}) {
+  if (!options.skipHeader) header('Checking rtk')
+
+  let shouldCheck = true
+  if (!options.skipPrompt) {
+    info('Recommended: install and verify rtk for safer agent CLI command execution.')
+    shouldCheck = await confirm({
+      message: 'Check rtk now?',
+      default: true,
+    })
+  }
+
+  if (!shouldCheck) {
+    warn('Skipped rtk check (you can install it later)')
+    return { optedIn: false, checked: false, available: false }
+  }
+
+  loading('checking rtk...')
+
+  const available = await commandExists('rtk')
+
+  if (available) {
+    success('rtk is available')
+    return { optedIn: true, checked: true, available: true }
+  }
+
+  warn('rtk not found on PATH.')
+  console.log()
+  info('rtk is required for agents to run CLI commands safely.')
+  info('Install it from: https://github.com/rtk-ai/rtk#pre-built-binaries')
+  console.log()
+  info('After installing, verify with:')
+  code(['rtk --version'])
+  return { optedIn: true, checked: true, available: false }
+}
+
+export async function tokenOptimizationStep(options = {}) {
+  header('Step 8, Token optimization tools')
+
+  const defaultSelected = optimizationPreset.choices
+    .filter(choice => choice.checked)
+    .map(choice => choice.value)
+  let selected = defaultSelected
+
+  if (!options.skipPrompt && process.stdin.isTTY) {
+    info(optimizationPreset.info)
+    // Abort the prompt via signal instead of racing it: a raced prompt keeps
+    // stdin in raw mode after "losing" and rejects unhandled on a later Ctrl+C.
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), optimizationPreset.timeoutMs)
+    try {
+      selected = await checkbox(
+        {
+          message: optimizationPreset.message,
+          choices: optimizationPreset.choices,
+        },
+        { signal: controller.signal },
+      )
+    } catch (err) {
+      if (err.name !== 'AbortPromptError') throw err
+      selected = defaultSelected
+      info('No response: continuing with the recommended defaults.')
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  loading('applying token optimization selections...')
+
+  const installScope = options.ctx?.installScope || 'local'
+
+  const has = value => selected.includes(value)
+
+  const rtk = has('rtk')
+    ? await checkRtk({ skipHeader: true, skipPrompt: true })
+    : { optedIn: false, checked: false, available: false }
+
+  const quota = has('quota')
+    ? await installQuota({ skipHeader: true, skipPrompt: true })
+    : { optedIn: false, installed: false }
+
+  const simpleEnglish = has('simpleEnglish')
+    ? await installSimpleEnglish({
+      skipHeader: true,
+      skipPrompt: true,
+      installScope,
+    })
+    : { optedIn: false, installed: false }
+
+  const codegraph = has('codegraph')
+    ? await installCodegraph({ skipHeader: true, installScope })
+    : { optedIn: false, installed: false }
+
+  const memory = has('memory')
+    ? await installMemory({ skipHeader: true })
+    : { optedIn: false, installed: false }
+
+  const humanizer = has('humanizer')
+    ? await installHumanizer({ skipHeader: true, installScope })
+    : { optedIn: false, installed: false }
+
+  // Run a single npx skills experimental_install to pick up all skills
+  // that were added to skills-lock.json by the individual installers above.
+  await syncSkillsLock()
+
+  // Patch guardrails skill with selected tool guidance sections
+  await patchGuardrails({
+    rtk: rtk.available,
+    codegraph: codegraph.optedIn,
+    memory: memory.optedIn,
+    simpleEnglish: simpleEnglish.installed,
+    humanizer: humanizer.optedIn,
+  })
+
+  if (selected.length === 0) warn('No token optimization tools selected')
+  else success('Token optimization step completed')
+
+  return { rtk, quota, simpleEnglish, codegraph, memory, humanizer }
+}
+
+async function syncSkillsLock() {
+  const destLock = path.join(process.cwd(), 'skills-lock.json')
+  if (!await fse.pathExists(destLock)) {
+    info('No skills-lock.json found, skipping skills sync')
+    return
+  }
+
+  loading('syncing skills via npx skills experimental_install...')
+  try {
+    const result = await execa('npx', ['skills', 'experimental_install', '--yes'], {
+      cwd: process.cwd(),
+      reject: false,
+      stdio: 'pipe',
+      timeout: 600000,
+    })
+
+    if (result.exitCode === 0) {
+      success('Skills synced from skills-lock.json')
+    } else {
+      const errLine = result.stderr?.trim().split('\n').slice(-3).join('\n')
+      warn(`npx skills experimental_install exited with non-zero code${errLine ? `: ${errLine}` : ''}`)
+    }
+  } catch (err) {
+    warn(`npx skills experimental_install failed: ${err.message}`)
+  }
+}

package/src/steps/optimization/memory.js

@@ -0,0 +1,88 @@
+import { execa } from 'execa'
+import { addSkillToLock } from './skills-lock.js'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser'
+import { error, info, loading, success, warn } from '../../utils/exec.js'
+
+/**
+ * Configures the agentmemory MCP server in opencode.jsonc
+ * and installs the agentmemory skills.
+ *
+ * agentmemory runs as a persistent local server on localhost:3111.
+ * Requires Node.js 18+ (npm install -g @agentmemory/agentmemory).
+ * MCP bridge: npx -y @agentmemory/mcp (proxies to the running server).
+ * Skill source: https://github.com/rohitg00/agentmemory
+ */
+export async function installMemory(options = {}) {
+  if (!options.skipHeader) info('Configuring agentmemory local memory server...')
+
+  // Install agentmemory globally so the `agentmemory` command is on PATH
+  loading('installing agentmemory (this may take a minute)...')
+  try {
+    const installResult = await execa('npm', ['install', '-g', '@agentmemory/agentmemory'], {
+      reject: false,
+      timeout: 300000,
+      stdio: 'pipe',
+    })
+    if (installResult.exitCode === 0) {
+      success('agentmemory installed')
+    } else {
+      warn('agentmemory install exited with non-zero code, MCP may fall back to npx resolution')
+    }
+  } catch (err) {
+    warn(`agentmemory install failed: ${err.message}`)
+  }
+
+  // Configure MCP server in opencode.jsonc
+  try {
+    const opencodePath = path.join(process.cwd(), 'opencode.jsonc')
+
+    let opencodeText = JSON.stringify({ $schema: 'https://opencode.ai/config.json' }, null, 2)
+    let opencode
+    if (await fse.pathExists(opencodePath)) {
+      const errors = []
+      opencodeText = await fse.readFile(opencodePath, 'utf-8')
+      opencode = parseJsonc(opencodeText, errors)
+      if (errors.length > 0 || !opencode || typeof opencode !== 'object' || Array.isArray(opencode)) {
+        throw new Error('opencode.jsonc could not be parsed')
+      }
+    } else {
+      opencode = { $schema: 'https://opencode.ai/config.json' }
+    }
+
+    if (!opencode.mcp?.['agentmemory']) {
+      const agentmemory = {
+        type: 'local',
+        command: ['npx', '-y', '@agentmemory/mcp'],
+        env: {
+          AGENTMEMORY_URL: 'http://localhost:3111',
+        },
+        enabled: true,
+        timeout: 120000,
+      }
+      opencodeText = applyEdits(opencodeText, modify(opencodeText, ['mcp', 'agentmemory'], agentmemory, {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+      }))
+    }
+
+    await fse.writeFile(opencodePath, opencodeText, 'utf-8')
+    success('agentmemory MCP server configured in opencode.jsonc')
+  } catch (err) {
+    error(`Failed to configure agentmemory MCP: ${err.message}`)
+    return { optedIn: true, installed: false }
+  }
+
+  // Add agentmemory skills to skills-lock.json for batch install
+  await addSkillToLock('agentmemory-agents', {
+    source: 'rohitg00/agentmemory',
+    sourceType: 'github',
+    skillPath: 'plugin/skills/agentmemory-agents/SKILL.md',
+  })
+
+  info('Memory server: run `agentmemory` to start on localhost:3111')
+  info('Real-time viewer: http://localhost:3113')
+  info('Health check: curl http://localhost:3111/agentmemory/health')
+
+  return { optedIn: true, installed: true }
+}

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

@@ -0,0 +1,108 @@
+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 }
+}

package/src/steps/optimization/quota.js

@@ -0,0 +1,119 @@
+import { confirm } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { fileURLToPath } from 'url'
+import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser'
+import { error, header, info, loading, success, warn } from '../../utils/exec.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const QUOTA_PRESET_PATH = path.resolve(__dirname, '../../presets/quota.json')
+const quotaPreset = await fse.readJson(QUOTA_PRESET_PATH)
+const PLUGIN = quotaPreset.plugin
+
+export function splitPackageSpec(spec) {
+  const separator = spec.startsWith('@') ? spec.indexOf('@', 1) : spec.lastIndexOf('@')
+  if (separator === -1) return { name: spec, version: 'latest' }
+  return { name: spec.slice(0, separator), version: spec.slice(separator + 1) }
+}
+
+function ensurePlugin(config) {
+  if (!Array.isArray(config.plugin)) config.plugin = []
+  if (!config.plugin.includes(PLUGIN)) config.plugin.push(PLUGIN)
+}
+
+export async function installQuota(options = {}) {
+  if (!options.skipHeader) header('Installing opencode-quota')
+
+  let shouldInstall = true
+  if (!options.skipPrompt && process.stdin.isTTY) {
+    // Same abort-on-timeout pattern as tokenOptimizationStep: never race a
+    // live inquirer prompt, it leaks raw-mode stdin and unhandled rejections.
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), quotaPreset.prompt.timeoutMs)
+    try {
+      shouldInstall = await confirm(
+        {
+          message: quotaPreset.prompt.message,
+          default: quotaPreset.prompt.default,
+        },
+        { signal: controller.signal },
+      )
+    } catch (err) {
+      if (err.name !== 'AbortPromptError') throw err
+      shouldInstall = true
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  if (!shouldInstall) {
+    warn('Skipped opencode-quota installation')
+    return { optedIn: false, installed: false }
+  }
+
+  loading('configuring opencode-quota...')
+
+  try {
+    const opencodeDir = path.join(process.cwd(), '.opencode')
+    const opencodePath = path.join(process.cwd(), 'opencode.jsonc')
+    const pkgPath = path.join(opencodeDir, 'package.json')
+    const tuiPath = path.join(opencodeDir, 'tui.json')
+    const quotaDir = path.join(opencodeDir, 'opencode-quota')
+    const quotaPath = path.join(quotaDir, 'quota-toast.json')
+
+    let opencodeText = JSON.stringify({ $schema: 'https://opencode.ai/config.json' }, null, 2)
+    let opencode
+    if (await fse.pathExists(opencodePath)) {
+      const errors = []
+      opencodeText = await fse.readFile(opencodePath, 'utf-8')
+      opencode = parseJsonc(opencodeText, errors)
+      if (errors.length > 0 || !opencode || typeof opencode !== 'object' || Array.isArray(opencode)) {
+        throw new Error('opencode.jsonc could not be parsed')
+      }
+    } else {
+      opencode = { $schema: 'https://opencode.ai/config.json' }
+    }
+
+    const pkg = await fse.pathExists(pkgPath)
+      ? await fse.readJson(pkgPath)
+      : {}
+
+    const tui = await fse.pathExists(tuiPath)
+      ? await fse.readJson(tuiPath)
+      : { $schema: 'https://opencode.ai/tui.json' }
+
+    const plugins = Array.isArray(opencode.plugin) ? opencode.plugin : []
+    if (!plugins.includes(PLUGIN)) {
+      plugins.push(PLUGIN)
+      opencodeText = applyEdits(opencodeText, modify(opencodeText, ['plugin'], plugins, {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+      }))
+    }
+    ensurePlugin(tui)
+
+    if (!pkg.dependencies) pkg.dependencies = {}
+    const { name: pkgName, version: pkgVersion } = splitPackageSpec(PLUGIN)
+    if (pkg.dependencies[pkgName] !== pkgVersion) pkg.dependencies[pkgName] = pkgVersion
+
+    await fse.ensureDir(opencodeDir)
+    await fse.writeFile(opencodePath, opencodeText, 'utf-8')
+    await fse.writeJson(pkgPath, pkg, { spaces: 2 })
+    await fse.writeJson(tuiPath, tui, { spaces: 2 })
+
+    const quotaConfig = await fse.pathExists(quotaPath)
+      ? await fse.readJson(quotaPath)
+      : {}
+
+    Object.assign(quotaConfig, quotaPreset.defaults)
+
+    await fse.ensureDir(quotaDir)
+    await fse.writeJson(quotaPath, quotaConfig, { spaces: 2 })
+
+    success('opencode-quota configured (manual setup)')
+    info('Restart OpenCode and run /quota to verify')
+    return { optedIn: true, installed: true }
+  } catch (err) {
+    error(`Failed to configure opencode-quota: ${err.message}`)
+    return { optedIn: true, installed: false }
+  }
+}

package/src/steps/optimization/simple-english.js

@@ -0,0 +1,17 @@
+import { addSkillToLock } from './skills-lock.js'
+import { header, success, info } from '../../utils/exec.js'
+
+const SKILL_ENTRY = {
+  source: 'AminBlg/SimpleEnglish',
+  sourceType: 'github',
+  skillPath: 'skills/simple-english/SKILL.md',
+}
+
+export async function installSimpleEnglish(options = {}) {
+  if (!options.skipHeader) header('Installing Simple English')
+
+  info('Adding Simple English to skills-lock.json for batch install')
+  await addSkillToLock('simple-english', SKILL_ENTRY)
+  success('Simple English queued for installation')
+  return { optedIn: true, installed: true }
+}

package/src/steps/optimization/skills-lock.js

@@ -0,0 +1,30 @@
+import fse from 'fs-extra'
+import path from 'path'
+import { info, warn } from '../../utils/exec.js'
+
+export async function addSkillToLock(skillName, entry) {
+  if (!entry) {
+    warn(`No entry provided for skills-lock.json: ${skillName}`)
+    return false
+  }
+
+  const destLock = path.join(process.cwd(), 'skills-lock.json')
+
+  let lock = { version: 1, skills: {} }
+  if (await fse.pathExists(destLock)) {
+    try {
+      lock = await fse.readJson(destLock)
+      if (!lock.skills) lock.skills = {}
+    } catch {
+      warn('Could not parse existing skills-lock.json, creating fresh')
+    }
+  }
+
+  if (!lock.skills[skillName]) {
+    lock.skills[skillName] = entry
+    await fse.writeJson(destLock, lock, { spaces: 2 })
+    info(`Added ${skillName} to skills-lock.json`)
+  }
+
+  return true
+}