@plainconceptsplatform/agent-harness 2.0.0

package/src/commands/join.js

@@ -0,0 +1,244 @@
+import chalk from 'chalk'
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { parse as parseJsonc } from 'jsonc-parser'
+import { installBrowser } from '../steps/browser/index.js'
+import { checkRtk } from '../steps/optimization/index.js'
+import { checkPlatform } from '../steps/platform/index.js'
+import { commandExists, header, info, loading, success, warn } from '../utils/exec.js'
+import { IGNORED_ENTRIES, USER_CONFIG_FILE } from '../utils/paths.js'
+import { readHarnessConfig } from './shared.js'
+
+export async function runJoin() {
+  const logo = chalk.hex('#fe3d57')
+  console.log()
+  console.log(logo('  🤝 agent-harness join'))
+  console.log(chalk.dim('  New team member setup: checks & local installs only.'))
+  console.log(chalk.dim('  Does not modify committed project files.'))
+  console.log()
+
+  const saved = await readHarnessConfig()
+
+  if (!saved) {
+    warn('No .opencode/harness.json found.')
+    warn('This project may not have been onboarded yet. Run `npx @plainconceptsplatform/agent-harness` first.')
+    return
+  }
+
+  const backlogPlatform = saved?.platform?.backlog
+  const repoPlatform = saved?.platform?.repo
+  const installScope = 'local'
+  const teamModels = saved?.models ?? {}
+
+  const opencodeDir = path.join(process.cwd(), '.opencode')
+  const opencodeJsonPath = path.join(process.cwd(), 'opencode.jsonc')
+
+  // Step 1: Platform CLI check
+  header('Step 1, Platform CLI check')
+  const platformsToCheck = [...new Set([backlogPlatform, repoPlatform])].filter(p => p && p !== 'none')
+  if (platformsToCheck.length === 0) {
+    info('No platform integration selected, skipping CLI checks.')
+  } else {
+    for (const p of platformsToCheck) {
+      const display = p === 'github' ? 'GitHub' : p === 'azure' ? 'Azure DevOps' : p
+      info(`Checking platform: ${display}`)
+      await checkPlatform(p)
+    }
+  }
+
+  // Step 2: Install OpenCode plugins
+  header('Step 2, Installing OpenCode plugins')
+  const pkgPath = path.join(opencodeDir, 'package.json')
+  if (await fse.pathExists(pkgPath)) {
+    try {
+      await execa('npm', ['install'], { cwd: opencodeDir, reject: false, stdio: 'pipe' })
+      success('OpenCode plugins installed')
+    } catch {
+      warn('npm install failed in .opencode/: plugins may not load correctly')
+    }
+  } else {
+    warn('No .opencode/package.json found: skipping plugin install')
+  }
+
+  // Step 3: Install/update skills
+  header('Step 3, Installing skills')
+  try {
+    await execa('npx', ['skills'], { cwd: process.cwd(), reject: false, stdio: 'pipe' })
+    success('Skills installed/updated')
+  } catch {
+    warn('npx skills failed: skills may be missing')
+  }
+
+  // Step 4: OpenSpec CLI check
+  header('Step 4, Checking OpenSpec')
+  const openspecAvailable = await commandExists('openspec')
+  if (openspecAvailable) {
+    success('OpenSpec CLI is available')
+  } else {
+    info('OpenSpec not found on PATH: installing...')
+    try {
+      const result = await execa('npm', ['install', '@fission-ai/openspec', '--global'], {
+        cwd: process.cwd(),
+        reject: false,
+        stdio: 'pipe',
+      })
+      if (result.exitCode === 0) {
+        success('OpenSpec installed')
+      } else {
+        warn('OpenSpec install failed: run `npm install -g @fission-ai/openspec` manually')
+      }
+    } catch {
+      warn('OpenSpec install failed: run `npm install -g @fission-ai/openspec` manually')
+    }
+  }
+
+  // Step 5: agentmemory (if project uses it)
+  header('Step 5, Checking agentmemory')
+  let cfg = {}
+  if (await fse.pathExists(opencodeJsonPath)) {
+    try {
+      const errors = []
+      cfg = parseJsonc(await fse.readFile(opencodeJsonPath, 'utf-8'), errors)
+      if (errors.length > 0) cfg = {}
+    } catch {
+      // ignore config read errors
+    }
+  }
+
+  if (cfg?.mcp?.['agentmemory']) {
+    info('Project uses agentmemory MCP')
+    loading('checking agentmemory server...')
+
+    // Check if agentmemory is installed
+    const agentmemoryAvailable = await commandExists('agentmemory')
+    if (agentmemoryAvailable) {
+      success('agentmemory CLI is available')
+    } else {
+      info('agentmemory not found on PATH, installing...')
+      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 failed, run `npm install -g @agentmemory/agentmemory` manually')
+        }
+      } catch (err) {
+        warn(`agentmemory install failed: ${err.message}`)
+      }
+    }
+
+    // Health-check the server
+    try {
+      const healthResult = await execa('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', 'http://localhost:3111/agentmemory/health'], {
+        reject: false,
+        timeout: 5000,
+      })
+      if (healthResult.stdout.trim() === '200') {
+        success('agentmemory server is running')
+      } else {
+        info('agentmemory server not running, start it with `agentmemory` in a separate terminal')
+      }
+    } catch {
+      info('agentmemory server not running, start it with `agentmemory` in a separate terminal')
+    }
+  } else {
+    info('agentmemory not configured for this project, skipping')
+  }
+
+  // Step 6: Codegraph (if project uses it)
+  header('Step 6, Checking codegraph')
+  if (cfg?.mcp?.['codegraph']) {
+    info('Project uses codegraph MCP: building index...')
+    try {
+      const result = await execa('npx', ['--yes', '@colbymchenry/codegraph', 'init', '-i'], {
+        cwd: process.cwd(),
+        reject: false,
+        stdio: 'pipe',
+        timeout: 120000,
+      })
+      if (result.exitCode === 0) {
+        success('codegraph index initialized')
+      } else {
+        warn('codegraph init failed: codegraph_search may be slow or unavailable')
+      }
+    } catch {
+      warn('codegraph init failed: codegraph_search may be slow or unavailable')
+    }
+  } else {
+    info('codegraph not configured for this project: skipping')
+  }
+
+  // Step 7: RTK check
+  header('Step 7, Checking rtk')
+  await checkRtk({ skipHeader: true, skipPrompt: true })
+
+  // Step 8: Browser extension
+  header('Step 8, Installing opencode-browser')
+  await installBrowser({ installScope })
+
+  // Step 9: Model tier guidance
+  header('Step 9, Model tiers')
+  const userConfigPath = path.join(opencodeDir, USER_CONFIG_FILE)
+  const hasUserOverride = await fse.pathExists(userConfigPath)
+
+  if (teamModels && Object.keys(teamModels).length > 0) {
+    info('Team model configuration:')
+    for (const [tier, model] of Object.entries(teamModels)) {
+      info(`  ${tier}: ${model}`)
+    }
+    console.log()
+
+    if (hasUserOverride) {
+      info('You have a local model override (harness.user.json).')
+      info('To change: /make-user-model user <tier> <model>')
+    } else {
+      info('No local override: using team defaults.')
+      info('To override a tier for your machine: /make-user-model user <tier> <model>')
+      info('  e.g. /make-user-model user build current')
+    }
+    console.log()
+    info('The pc-subagent-tiers plugin will generate *-engineer.<tier>.md variants')
+    info('on opencode startup from these model configs.')
+  } else {
+    warn('No model tiers configured in harness.json.')
+    warn('Run /make-user-model <tier> <model> for plan, build, and fast.')
+  }
+
+  // Step 10: Ensure .opencode/.gitignore exists
+  header('Step 10, Checking .opencode/.gitignore')
+  const gitignorePath = path.join(opencodeDir, '.gitignore')
+  const requiredEntries = IGNORED_ENTRIES
+
+  if (await fse.pathExists(gitignorePath)) {
+    const content = await fse.readFile(gitignorePath, 'utf-8')
+    const existing = content.split('\n').map(l => l.trim()).filter(Boolean)
+    const missing = requiredEntries.filter(e => !existing.includes(e))
+    if (missing.length > 0) {
+      const merged = `${[...existing, ...missing].join('\n')}\n`
+      await fse.writeFile(gitignorePath, merged, 'utf-8')
+      success(`Merged ${missing.length} missing .gitignore entries`)
+    } else {
+      success('.gitignore is up to date')
+    }
+  } else {
+    await fse.writeFile(gitignorePath, `${requiredEntries.join('\n')}\n`, 'utf-8')
+    success('Created .opencode/.gitignore')
+  }
+
+  console.log()
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log(chalk.bold.green('  Join setup complete!'))
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log()
+  console.log('  Your local environment is ready.')
+  if (teamModels && Object.keys(teamModels).length > 0 && !hasUserOverride) {
+    console.log(chalk.dim('  Tip: Run /make-user-model user <tier> current to override team models locally.'))
+  }
+  console.log(chalk.dim('  Restart opencode to pick up tier agent variants.'))
+  console.log()
+}

package/src/commands/shared.js

@@ -0,0 +1,27 @@
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import { configPath } from '../utils/paths.js'
+
+export async function readHarnessConfig() {
+  const cfgPath = configPath()
+  if (!await fse.pathExists(cfgPath)) return null
+  try {
+    return await fse.readJson(cfgPath)
+  } catch {
+    return null
+  }
+}
+
+export async function ensureGitLongpaths(cwd = process.cwd()) {
+  // core.longpaths only matters on Windows; don't touch repo config elsewhere.
+  if (process.platform !== 'win32') return false
+  try {
+    const repoCheck = await execa('git', ['rev-parse', '--is-inside-work-tree'], { cwd, reject: false })
+    if (repoCheck.exitCode !== 0 || repoCheck.stdout.trim() !== 'true') return false
+
+    const configResult = await execa('git', ['config', 'core.longpaths', 'true'], { cwd, reject: false })
+    return configResult.exitCode === 0
+  } catch {
+    return false
+  }
+}

package/src/commands/single.js

@@ -0,0 +1,79 @@
+import fse from 'fs-extra'
+import path from 'node:path'
+import { fileURLToPath } from 'url'
+import { cleanAiFiles } from '../steps/clean/index.js'
+import { copyContentStep } from '../steps/copy/index.js'
+import { chooseModels } from '../steps/models/index.js'
+import { initOpenspec } from '../steps/openspec/index.js'
+import { tokenOptimizationStep } from '../steps/optimization/index.js'
+import { choosePlatform } from '../steps/platform/index.js'
+import { installBrowser } from '../steps/browser/index.js'
+import { writeHarnessConfig } from '../steps/metadata/index.js'
+import { readHarnessConfig } from './shared.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const platformsPreset = await fse.readJson(path.resolve(__dirname, '../presets/platforms.json'))
+// platforms.json is the single source of truth for valid platform values.
+// Hardcoding a subset here silently rewrote jira/gitlab/browser projects to github.
+const VALID_PLATFORMS = new Set(platformsPreset.map(p => p.value))
+
+export function resolvePlatform(value, fallback = 'github') {
+  return VALID_PLATFORMS.has(value) ? value : fallback
+}
+
+export async function runSingleCommand(command) {
+  const saved = await readHarnessConfig()
+  const ctx = {
+    hasDesign: !!saved?.preexisting?.design,
+    hasArchitecture: !!saved?.preexisting?.architecture,
+    hasOpenspec: !!saved?.preexisting?.openspec,
+    sourceMode: saved?.source?.mode ?? 'current',
+    sourceRoots: Array.isArray(saved?.source?.roots) ? saved.source.roots : [],
+    maxConcurrentAgents: saved?.agents?.maxConcurrent ?? 3,
+  }
+  const backlogPlatform = saved?.platform?.backlog
+  const repoPlatform = saved?.platform?.repo
+  const resolvedBacklog = resolvePlatform(backlogPlatform)
+  const resolvedRepo = resolvePlatform(repoPlatform)
+
+  const handlers = {
+    clean: async () => {
+      await cleanAiFiles()
+    },
+    platform: async () => {
+      await choosePlatform()
+    },
+    copy: async () => {
+      await copyContentStep({ backlogPlatform: resolvedBacklog, repoPlatform: resolvedRepo }, ctx)
+    },
+    openspec: async () => {
+      await initOpenspec()
+    },
+    models: async () => {
+      await chooseModels()
+    },
+    optimization: async () => {
+      await tokenOptimizationStep({ ctx })
+    },
+    browser: async () => {
+      await installBrowser()
+    },
+    metadata: async () => {
+      await writeHarnessConfig({
+        ...ctx,
+        backlogPlatform: resolvedBacklog,
+        repoPlatform: resolvedRepo,
+        maxConcurrentAgents: saved?.agents?.maxConcurrent ?? 3,
+        planModel: saved?.models?.plan ?? null,
+        buildModel: saved?.models?.build ?? null,
+        fastModel: saved?.models?.fast ?? null,
+        optionalTools: saved?.tools ?? null,
+      })
+    },
+  }
+
+  const handler = handlers[command]
+  if (!handler) return false
+  await handler()
+  return true
+}

package/src/commands/update.js

@@ -0,0 +1,109 @@
+import chalk from 'chalk'
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { fileURLToPath } from 'url'
+import { readHarnessConfig } from './shared.js'
+import { copyContentStep } from '../steps/copy/index.js'
+import { writeModelsToConfigs } from '../steps/models/write.js'
+import { patchGuardrails } from '../steps/optimization/patch-guardrails.js'
+import { writeHarnessConfig } from '../steps/metadata/index.js'
+import { exit } from '../utils/process.js'
+
+const SIMPLE_ENGLISH_ENTRY = {
+  source: 'AminBlg/SimpleEnglish',
+  sourceType: 'github',
+  skillPath: 'skills/simple-english/SKILL.md',
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const platformsPreset = await fse.readJson(path.resolve(__dirname, '../presets/platforms.json'))
+const VALID_PLATFORMS = new Set(platformsPreset.map(p => p.value))
+
+function resolvePlatform(value, fallback = 'github') {
+  return VALID_PLATFORMS.has(value) ? value : fallback
+}
+
+export async function runUpdate() {
+  const saved = await readHarnessConfig()
+  if (!saved?.platform) {
+    console.log(chalk.red('No agent-harness config found. Run the wizard first.'))
+    exit(1)
+    return
+  }
+
+  const backlogPlatform = resolvePlatform(saved.platform.backlog)
+  const repoPlatform = resolvePlatform(saved.platform.repo)
+
+  const ctx = {
+    hasDesign: !!saved.preexisting?.design,
+    hasArchitecture: !!saved.preexisting?.architecture,
+    hasOpenspec: !!saved.preexisting?.openspec,
+    sourceMode: saved.source?.mode ?? 'current',
+    sourceRoots: Array.isArray(saved.source?.roots) ? saved.source.roots : [],
+    maxConcurrentAgents: saved.agents?.maxConcurrent ?? 3,
+    installScope: 'local',
+    skipSkills: false,
+    updateMode: true,
+  }
+
+  console.log()
+  console.log(chalk.bold('Updating project from saved config'))
+  console.log(chalk.dim(`  backlog: ${backlogPlatform}  repo: ${repoPlatform}  agents: ${ctx.maxConcurrentAgents}`))
+  console.log()
+
+  await copyContentStep({ backlogPlatform, repoPlatform }, ctx)
+
+  if (saved.models) {
+    await writeModelsToConfigs({ buildModel: saved.models.build })
+  }
+
+  const tools = saved.tools ?? {}
+  await migrateCavemanSkill(tools)
+  await patchGuardrails({
+    rtk: !!tools.rtk,
+    simpleEnglish: !!(tools.simpleEnglish || tools.caveman),
+    codegraph: !!tools.codegraph,
+    memory: !!tools.memory,
+    humanizer: !!tools.humanizer,
+  })
+
+  await writeHarnessConfig({
+    ...ctx,
+    backlogPlatform,
+    repoPlatform,
+    maxConcurrentAgents: ctx.maxConcurrentAgents,
+    planModel: saved.models?.plan ?? null,
+    buildModel: saved.models?.build ?? null,
+    fastModel: saved.models?.fast ?? null,
+    optionalTools: tools,
+  })
+
+  console.log()
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log(chalk.bold.green('  Update complete!'))
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log()
+}
+
+async function migrateCavemanSkill(tools) {
+  if (!tools.caveman || tools.simpleEnglish) return
+
+  const lockPath = path.join(process.cwd(), 'skills-lock.json')
+  const lock = await fse.readJson(lockPath).catch(() => ({ version: 1, skills: {} }))
+  lock.skills ??= {}
+  delete lock.skills.caveman
+  lock.skills['simple-english'] = SIMPLE_ENGLISH_ENTRY
+  await fse.writeJson(lockPath, lock, { spaces: 2 })
+  await fse.remove(path.join(process.cwd(), '.agents', 'skills', 'caveman'))
+
+  const result = await execa('npx', ['skills', 'experimental_install', '--yes'], {
+    cwd: process.cwd(),
+    reject: false,
+    stdio: 'pipe',
+    timeout: 600000,
+  })
+  if (result.exitCode !== 0) {
+    console.log(chalk.yellow('Simple English was added to skills-lock.json but could not be installed. Run npx skills experimental_install --yes.'))
+  }
+}

package/src/commands/wizard.js

@@ -0,0 +1,134 @@
+import { select as wizardSelect } from '@inquirer/prompts'
+import chalk from 'chalk'
+import { ensureGitLongpaths } from './shared.js'
+import { chooseSourceScope } from '../steps/source/index.js'
+import { cleanAiFiles } from '../steps/clean/index.js'
+import { choosePlatform } from '../steps/platform/index.js'
+import { copyContentStep } from '../steps/copy/index.js'
+import { initOpenspec } from '../steps/openspec/index.js'
+import { chooseModels } from '../steps/models/index.js'
+import { tokenOptimizationStep } from '../steps/optimization/index.js'
+import { installBrowser } from '../steps/browser/index.js'
+import { writeHarnessConfig } from '../steps/metadata/index.js'
+
+export async function runWizard(version) {
+  const logo = chalk.hex('#fe3d57')
+  const bannerLines = [
+    logo('                             '),
+    logo('        ▒▒▒▒▒▒▒▒▒▒▒▒▒        '),
+    logo('        ▒▒▓       ▓▒▓        '),
+    logo('   ▒▒▒▒▒▒▓▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒   '),
+    logo('  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓  '),
+    logo(' ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓ '),
+    logo(' ▓▒▒▒▒░░░▒▒▒▒▒▒▒▒▒▒▒░░░▒▒▒▓▓ '),
+    logo('  ▓▓▓▓▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▓▓▓▓  '),
+    logo('  ▓▓▒▒▒▒▒▒░▒▒▒▒▒▒▒░▒▒▒▒▒▒▓▓  '),
+    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
+    logo('  ▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓   '),
+    logo('   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓    '),
+    '',
+    chalk.bold('        🧰 agent-harness') + chalk.dim(` v${version}`),
+    chalk.dim('        Prepare your codebase for AI agents'),
+  ]
+
+  for (const line of bannerLines) console.log(line)
+  console.log()
+  console.log('  This tool will set up your project with a team of AI agents,')
+  console.log('  install skills, select models, and configure OpenCode.')
+  console.log()
+
+  // Only wait for Enter in a real interactive TTY
+  if (process.stdin.isTTY) {
+    console.log(chalk.bold('  Press Enter to begin...'))
+    console.log()
+    await new Promise(resolve => {
+      process.stdin.resume()
+      process.stdin.once('data', () => {
+        process.stdin.pause()
+        resolve()
+      })
+    })
+  }
+
+  const longpathsConfigured = await ensureGitLongpaths()
+  if (longpathsConfigured) console.log(chalk.dim('  Git long paths enabled for this repository.'))
+
+  const scope = await chooseSourceScope()
+
+  const maxConcurrentAgents = await wizardSelect({
+    message: 'Max concurrent agents:',
+    default: 3,
+    choices: [
+      { name: '1', value: 1, description: 'Serial: one agent at a time' },
+      { name: '2', value: 2, description: 'Conservative: lower resource usage' },
+      { name: '3 (default)', value: 3, description: 'Recommended: balances speed vs MCP load' },
+      { name: '4', value: 4, description: 'Higher parallelism' },
+      { name: '5', value: 5, description: 'Maximum: needs more resources' },
+    ],
+  })
+
+  const installScope = await wizardSelect({
+    message: 'Install dependencies:',
+    default: 'local',
+    choices: [
+      { name: 'Locally (default)', value: 'local', description: 'Install tools project-locally where possible' },
+      { name: 'Globally', value: 'global', description: 'Install tools globally (affects all projects on this machine)' },
+    ],
+  })
+
+  const preserve = await cleanAiFiles({ removeLegacyConfig: true })
+  const ctx = { ...preserve, ...scope, maxConcurrentAgents, installScope }
+
+  const { backlogPlatform, repoPlatform } = await choosePlatform()
+
+  await copyContentStep({ backlogPlatform, repoPlatform }, ctx)
+
+  const openspec = await initOpenspec()
+
+  const selectedModels = await chooseModels()
+
+  const tokenOpt = await tokenOptimizationStep({ ctx })
+  const { rtk, quota, simpleEnglish, codegraph, memory, humanizer } = tokenOpt
+
+  await installBrowser(ctx)
+
+  await writeHarnessConfig({
+    ...ctx,
+    backlogPlatform,
+    repoPlatform,
+    openspec,
+    maxConcurrentAgents,
+    installScope,
+    additionalSkillsProvider: 'npx-skills',
+    ...selectedModels,
+    optionalTools: { rtk, quota, simpleEnglish, codegraph, memory, humanizer },
+  })
+
+  const toGenerate = [
+    !ctx.hasDesign && 'DESIGN.md',
+    !ctx.hasArchitecture && 'ARCHITECTURE.md',
+  ].filter(Boolean)
+
+  console.log()
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log(chalk.bold.green('  Onboarding complete!'))
+  console.log(chalk.bold.green('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'))
+  console.log()
+  console.log('  Open this project in OpenCode and type:')
+  console.log(chalk.bold('  "/init"'))
+  console.log('  Or run the following command in your terminal:')
+  console.log(chalk.bold('  opencode --prompt "/init" --model "opencode/big-pickle"  '))
+  console.log()
+  console.log(chalk.dim('  Note: the first time you open OpenCode in this project,'))
+  console.log(chalk.dim('  it will install plugin dependencies. You may see a black'))
+  console.log(chalk.dim('  screen for a moment: this is normal. Wait for it to load.'))
+  console.log()
+  if (toGenerate.length > 0) {
+    console.log(`  OpenCode will generate ${toGenerate.join(' and ')}`)
+    console.log('  from your actual codebase, then activate the agent team.')
+  } else {
+    console.log('  OpenCode will activate the agent team.')
+  }
+  console.log(`  Source scope: ${ctx.sourceMode === 'parent-selected' ? ctx.sourceRoots.map(p => `../${p.split(/[/\\]/).pop()}`).join(', ') : 'current folder'}`)
+  console.log()
+}

package/src/content/.agents/skills/browser-automation/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: browser-automation
+description: Reliable, composable browser automation using OpenCode Browser primitives. Use when capturing screenshots of a locally running app, clicking UI elements, reading page content, or automating browser interactions on localhost.
+license: MIT
+compatibility: Requires opencode-browser extension installed and running.
+metadata:
+  author: copilots
+  version: "1.0"
+---
+
+This skill operates on `localhost` URLs only. Screenshots, clicks, typing, scrolling, and queries on locally running apps are in scope. External services (github.com, dev.azure.com, npmjs.com, etc.) are out of scope for browser tools.
+
+The only exception: when the user selects "Others (Browser)" as their backlog platform during onboarding, the `pc-userstory` skill may navigate to work item URLs the user explicitly provides. That is the sole case where external navigation is permitted, and only to URLs the user explicitly gives you.
+
+## Best-practice workflow
+
+1. Inspect tabs with `browser_get_tabs`
+2. Open new tabs with `browser_open_tab` when needed
+3. Navigate with `browser_navigate` if needed
+4. Wait for UI using `browser_query` with `timeoutMs`
+5. Discover candidates using `browser_query` with `mode=list`
+6. Click, type, or select using `index`
+7. Confirm using `browser_query` or `browser_snapshot`
+
+## CLI-first debugging
+
+- List all available tools: `npx @different-ai/opencode-browser@4.6.1 tools`
+- Run one tool directly: `npx @different-ai/opencode-browser@4.6.1 tool browser_status`
+- Pass JSON args: `npx @different-ai/opencode-browser@4.6.1 tool browser_query --args '{"mode":"page_text"}'`
+- Run smoke test: `npx @different-ai/opencode-browser@4.6.1 self-test`
+- After `update`, reload the unpacked extension in `chrome://extensions`
+
+## Selecting options
+
+- Use `browser_select` for native `<select>` elements
+- Prefer `value` or `label`; use `optionIndex` when needed
+- Example: `browser_select({ selector: "select", value: "plugin" })`
+
+## Query modes
+
+- `text`: read visible text from a matched element
+- `value`: read input values
+- `list`: list many matches with text/metadata
+- `exists`: check presence and count
+- `page_text`: extract visible page text
+
+## Opening tabs
+
+- Use `browser_open_tab` to create a new tab, optionally with `url` and `active`
+- Example: `browser_open_tab({ url: "https://example.com", active: false })`
+
+## Troubleshooting
+
+- If a selector fails, run `browser_query` with `mode=page_text` to confirm the content exists
+- Use `mode=list` on broad selectors (`button`, `a`, `*[role="button"]`, `*[role="listitem"]`) and choose by index
+- For inbox/chat panes, try text selectors first (`text:Subject line`) then verify selection with `browser_query`
+- For scrollable containers, pass both `selector` and `x`/`y` to `browser_scroll` and then verify `scrollTop`
+
+## Scope
+
+- Screenshots of locally running app on `localhost` URLs: in scope
+- Click, type, scroll, query on `localhost` pages: in scope
+- Navigate to work item URLs the user explicitly provides (when backlog platform is "Others (Browser)"): in scope
+- Navigate to external services for non-work-item purposes: out of scope
+- DevOps or GitHub CLI operations via browser tools: out of scope
+- Reading or modifying production systems via browser tools: out of scope