@plainconceptsplatform/agent-harness 2.0.0

package/src/steps/copy/skills.js

@@ -0,0 +1,196 @@
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { info, success } from '../../utils/exec.js'
+import { canUpdateManagedFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from '../../utils/update-manifest.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const CONTENT_SKILLS_DIR = path.resolve(__dirname, '../../content/.agents/skills')
+const CONTENT_SKILLS_LOCK = path.resolve(__dirname, '../../content/skills-lock.json')
+
+// Userstory skills parse backlog work items: selected by backlogPlatform only.
+// Mixing the two axes here installs the wrong variant on mixed setups, because
+// all variants rename to the same generic dir and the first copy wins.
+const BACKLOG_PLATFORM_SKILLS = {
+  'pc-userstory-gh': 'github',
+  'pc-userstory-az': 'azure',
+  'pc-userstory-jira': 'jira',
+  'pc-userstory-browser': 'browser',
+}
+
+// Platform-specific skills are renamed to their generic form on install.
+// The -gh / -az / -jira / -gl suffix is only needed here to keep all variants in source.
+// After install only one platform is present so no suffix is needed.
+const SKILL_RENAME = {
+  'pc-userstory-gh':      'pc-userstory',
+  'pc-userstory-az':      'pc-userstory',
+  'pc-userstory-jira':    'pc-userstory',
+  'pc-userstory-browser': 'pc-userstory',
+}
+
+function shouldInstallSkill(skill, backlogPlatform, _repoPlatform) {
+  if (skill in BACKLOG_PLATFORM_SKILLS) return BACKLOG_PLATFORM_SKILLS[skill] === backlogPlatform
+  return true
+}
+
+// Shipped skills whose content is a PLACEHOLDER — a /make-* command
+// overwrites them with project-specific content. During forceOverwrite,
+// these must be preserved when they have already been generated (detected
+// by the <!-- Last updated: marker). Without this check, the update would
+// wipe project-specific guardrails, risk assessments, etc.
+const GENERATABLE_SKILLS = new Set([
+  'pc-guardrails-project',
+  'pc-merge-risk-assess',
+])
+
+const MARKER_SKILLS = new Set([
+  'pc-guardrails-generic',
+  'pc-plan-archive',
+  'pc-ops-ship',
+  'pc-ops-evidence',
+  'pc-repo-initialize',
+])
+
+async function isGeneratedSkill(dest) {
+  const skillMd = path.join(dest, 'SKILL.md')
+  if (!await fse.pathExists(skillMd)) return false
+  const content = await fse.readFile(skillMd, 'utf-8')
+  return content.includes('<!-- Last updated:')
+}
+
+async function syncSkillFiles(src, dest, relativeRoot, cwd, manifest) {
+  for (const entry of await fse.readdir(src, { withFileTypes: true })) {
+    const sourcePath = path.join(src, entry.name)
+    const destinationPath = path.join(dest, entry.name)
+    const relativePath = path.join(relativeRoot, entry.name)
+    if (entry.isDirectory()) {
+      await syncSkillFiles(sourcePath, destinationPath, relativePath, cwd, manifest)
+      continue
+    }
+    if (!await fse.pathExists(destinationPath) || await canUpdateManagedFile(relativePath, cwd, manifest)) {
+      await fse.ensureDir(path.dirname(destinationPath))
+      await fse.copyFile(sourcePath, destinationPath)
+      await recordManagedFile(manifest, relativePath, sourcePath)
+      success(`Updated skill: ${relativePath}`)
+    } else {
+      info(`Preserving modified skill file: ${relativePath}`)
+    }
+  }
+}
+
+async function recordSkillSourceFiles(src, relativeRoot, manifest) {
+  for (const entry of await fse.readdir(src, { withFileTypes: true })) {
+    const sourcePath = path.join(src, entry.name)
+    const relativePath = path.join(relativeRoot, entry.name)
+    if (entry.isDirectory()) {
+      await recordSkillSourceFiles(sourcePath, relativePath, manifest)
+    } else {
+      await recordManagedFile(manifest, relativePath, sourcePath)
+    }
+  }
+}
+
+async function installObSkills(backlogPlatform = 'github', repoPlatform, { forceOverwrite = false, updateMode = false } = {}) {
+  const repo = repoPlatform ?? backlogPlatform
+  const destSkillsDir = path.join(process.cwd(), '.agents', 'skills')
+  await fse.ensureDir(destSkillsDir)
+  const manifest = await readUpdateManifest()
+
+  // Build the set of skill names we ship (source dirs, after rename).
+  // Only these may be removed during forceOverwrite — project-generated
+  // skills (pc-merge-risk-assess, custom loops, etc.) must survive.
+  const contentSkills = await fse.readdir(CONTENT_SKILLS_DIR)
+  const shippedNames = new Set()
+  for (const skill of contentSkills) {
+    const stat = await fse.stat(path.join(CONTENT_SKILLS_DIR, skill)).catch(() => null)
+    if (stat?.isDirectory()) shippedNames.add(SKILL_RENAME[skill] ?? skill)
+  }
+  // Also account for stale platform-variant names (e.g. pc-userstory-gh
+  // when the current platform is azure).
+  Object.keys(SKILL_RENAME).forEach(k => shippedNames.add(k))
+
+  if (forceOverwrite && !updateMode) {
+    for (const entry of await fse.readdir(destSkillsDir)) {
+      if (!entry.startsWith('pc-')) continue
+      if (!shippedNames.has(entry)) {
+        info(`Preserving project-generated skill: ${entry}`)
+        continue
+      }
+      // Generatable skills: preserve if already populated by /make-*
+      if (GENERATABLE_SKILLS.has(entry) && await isGeneratedSkill(path.join(destSkillsDir, entry))) {
+        info(`Preserving generated skill: ${entry}`)
+        continue
+      }
+      await fse.remove(path.join(destSkillsDir, entry))
+      info(`Removing shipped skill: ${entry}`)
+    }
+  }
+
+  const skills = contentSkills
+  for (const skill of skills) {
+    const src = path.join(CONTENT_SKILLS_DIR, skill)
+    const destName = SKILL_RENAME[skill] ?? skill
+    const dest = path.join(destSkillsDir, destName)
+    const stat = await fse.stat(src)
+    if (!stat.isDirectory()) continue
+    if (!shouldInstallSkill(skill, backlogPlatform, repo)) {
+      if (forceOverwrite) {
+        const staleDest = path.join(destSkillsDir, skill)
+        if (skill !== destName && await fse.pathExists(staleDest)) {
+          await fse.remove(staleDest)
+          info(`Removing stale skill: ${skill}`)
+        }
+      }
+      info(`Skipping skill: ${skill} (not needed for platforms: ${backlogPlatform}/${repo})`)
+      continue
+    }
+    if (updateMode) {
+      if (!await fse.pathExists(dest)) {
+        await syncSkillFiles(src, dest, path.join('.agents', 'skills', destName), process.cwd(), manifest)
+      } else if (MARKER_SKILLS.has(destName) || GENERATABLE_SKILLS.has(destName)) {
+        info(`Preserving project-owned skill: ${destName}`)
+      } else {
+        await syncSkillFiles(src, dest, path.join('.agents', 'skills', destName), process.cwd(), manifest)
+      }
+      continue
+    }
+    if (await fse.pathExists(dest) && !forceOverwrite) {
+      info(`${destName} already exists, skipping`)
+      continue
+    }
+    // Even with forceOverwrite, never overwrite an already-generated
+    // generatable skill — its content was produced by /make-guardrails or
+    // similar, not by the shipped placeholder.
+    if (forceOverwrite && GENERATABLE_SKILLS.has(destName) && await isGeneratedSkill(dest)) {
+      info(`Preserving generated skill: ${destName}`)
+      continue
+    }
+    await fse.copy(src, dest, { overwrite: true })
+    if (!MARKER_SKILLS.has(destName) && !GENERATABLE_SKILLS.has(destName)) {
+      await recordSkillSourceFiles(src, path.join('.agents', 'skills', destName), manifest)
+    }
+    success(`${forceOverwrite ? 'Updated' : 'Installed'} skill: ${destName}`)
+  }
+
+  await writeUpdateManifest(manifest)
+}
+
+export async function installSkills(backlogPlatform = 'github', repoPlatform, opts = {}) {
+  info('Installing built-in pc-skills...')
+  await installObSkills(backlogPlatform, repoPlatform, opts)
+  console.log()
+
+  if (await fse.pathExists(CONTENT_SKILLS_LOCK)) {
+    const destLock = path.join(process.cwd(), 'skills-lock.json')
+    if (await fse.pathExists(destLock) && (opts.updateMode || !opts.forceOverwrite)) {
+      info('skills-lock.json already exists, skipping')
+    } else {
+      await fse.copy(CONTENT_SKILLS_LOCK, destLock, { overwrite: true })
+      success(`${opts.forceOverwrite ? 'Updated' : 'Installed'} skills-lock.json`)
+    }
+  }
+
+  // npx skills experimental_install is now called once at the end of the
+  // optimization step, after the user has selected which tools to enable.
+  // This avoids multiple npx skills add calls during onboarding.
+}

package/src/steps/metadata/index.js

@@ -0,0 +1,108 @@
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { createRequire } from 'node:module'
+import { header, success, warn } from '../../utils/exec.js'
+import { configPath } from '../../utils/paths.js'
+
+const require = createRequire(import.meta.url)
+const { version: harnessVersion } = require('../../../package.json')
+
+function clampConcurrency(n) {
+  const v = Number(n)
+  if (!Number.isFinite(v)) return 3
+  return Math.min(5, Math.max(1, Math.round(v)))
+}
+
+async function detectOpencodeVersion() {
+  try {
+    const result = await execa('opencode', ['--version'], { reject: false })
+    if (result.exitCode !== 0) return null
+    const output = (result.stdout || result.stderr || '').trim()
+    return output || null
+  } catch {
+    return null
+  }
+}
+
+export async function writeHarnessConfig(data) {
+  header('Step 10, Writing onboarding metadata')
+
+  const opencodeVersion = await detectOpencodeVersion()
+  const cwd = data.cwd ?? process.cwd()
+  const target = configPath(cwd)
+
+  // Read the existing file so load-bearing config (models, maxConcurrent)
+  // is preserved across metadata refreshes when not explicitly provided.
+  const existing = await fse.readJson(target).catch(() => null)
+
+  const selectedModels = Object.fromEntries(
+    Object.entries({
+      plan: data.planModel,
+      build: data.buildModel,
+      fast: data.fastModel,
+    }).filter(([, value]) => value)
+  )
+  const models = Object.keys(selectedModels).length > 0
+    ? { ...existing?.models, ...selectedModels }
+    : existing?.models ?? null
+  const maxConcurrent = clampConcurrency(data.maxConcurrentAgents ?? existing?.agents?.maxConcurrent ?? 3)
+
+  const optionalTools = data.optionalTools ?? existing?.tools ?? {}
+  const { caveman: _caveman, ...existingTools } = existing?.tools ?? {}
+  const tools = {
+    rtk: !!(optionalTools.rtk?.optedIn ?? optionalTools.rtk),
+    quota: !!(optionalTools.quota?.optedIn ?? optionalTools.quota),
+    simpleEnglish: !!(
+      optionalTools.simpleEnglish?.optedIn ?? optionalTools.simpleEnglish ??
+      optionalTools.caveman?.optedIn ?? optionalTools.caveman
+    ),
+    codegraph: !!(optionalTools.codegraph?.optedIn ?? optionalTools.codegraph),
+    memory: !!(optionalTools.memory?.optedIn ?? optionalTools.memory),
+  }
+
+  const payload = {
+    ...existing,
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    harnessVersion,
+    opencodeVersion,
+
+    platform: {
+      ...existing?.platform,
+      backlog: data.backlogPlatform ?? 'none',
+      repo: data.repoPlatform ?? 'none',
+    },
+
+    ...(models ? { models } : {}),
+
+    agents: {
+      ...existing?.agents,
+      maxConcurrent,
+    },
+
+    source: {
+      ...existing?.source,
+      mode: data.sourceMode ?? 'current',
+      roots: data.sourceRoots ?? [],
+    },
+
+    tools: { ...existingTools, ...tools },
+
+    preexisting: {
+      ...existing?.preexisting,
+      design: !!data.hasDesign,
+      architecture: !!data.hasArchitecture,
+      openspec: !!data.hasOpenspec,
+    },
+  }
+
+  try {
+    await fse.ensureDir(path.dirname(target))
+    await fse.writeJson(target, payload, { spaces: 2 })
+    success('Wrote .opencode/harness.json')
+    if (!opencodeVersion) warn('Could not detect opencode version, saved as null')
+  } catch (err) {
+    warn(`Could not write onboarding metadata: ${err.message}`)
+  }
+}

package/src/steps/models/format.js

@@ -0,0 +1,88 @@
+import { search, select } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MODELS_PRESET_PATH = path.resolve(__dirname, '../../presets/models.json');
+const modelsPreset = await fse.readJson(MODELS_PRESET_PATH);
+
+function costTier(input) {
+  if (input === undefined || input === null) return '';
+  const tier = modelsPreset.costTiers.find(t => t.max === undefined || input <= t.max);
+  return tier ? ` ${tier.label}` : '';
+}
+
+function costTierDisplay(cost, canonicalCost) {
+  return costTier(canonicalCost !== undefined ? canonicalCost : cost);
+}
+
+function formatPrice(price) {
+  if (price === undefined || price === null) return '?';
+  if (price === 0) return '$0 (subscription)';
+  return `$${price}/M`;
+}
+
+export function buildDisplayModels(rawModels) {
+  return rawModels.map(m => {
+    const priceStr = formatPrice(m.cost);
+    const canonicalNote = m.canonicalCost !== undefined
+      ? ` · official price: ${formatPrice(m.canonicalCost)}/M`
+      : '';
+    const context = m.context ? `${m.context / 1000}k` : '?';
+    return {
+      ...m,
+      label: `${m.name}${costTierDisplay(m.cost, m.canonicalCost)}, ${m.id}`,
+      description: `${priceStr}${canonicalNote} · context: ${context}`,
+    };
+  });
+}
+
+export function buildModelChoices(input, models) {
+  const q = (input || '').toLowerCase();
+  const filtered = q
+    ? models.filter(m =>
+        m.label.toLowerCase().includes(q) ||
+        m.id.toLowerCase().includes(q)
+      )
+    : models;
+
+  return [
+    {
+      name: 'None',
+      value: null,
+      description: 'Leave this model unset',
+    },
+    {
+      name: '← Change provider',
+      value: '__back__',
+      description: 'Go back to provider selection',
+    },
+    ...filtered.slice(0, 50).map(m => ({
+      name: m.label,
+      value: m.id,
+      description: m.description,
+    })),
+  ];
+}
+
+export function pickModel(message, models) {
+  return search({
+    message,
+    source: input => buildModelChoices(input, models),
+  });
+}
+
+export function filterModelsByProvider(models, provider) {
+  if (!provider) return models
+  return models.filter(m => m.id.startsWith(`${provider}/`))
+}
+
+export function pickProvider(message) {
+  return select({
+    message,
+    choices: modelsPreset.providers.map(p => ({ value: p.value, name: p.name })),
+  })
+}
+
+export { modelsPreset };

package/src/steps/models/index.js

@@ -0,0 +1,64 @@
+import { header, info, prompt, success, warn } from '../../utils/exec.js'
+import { fetchModels } from '../../utils/models-cache.js'
+import { buildDisplayModels, filterModelsByProvider, modelsPreset, pickModel, pickProvider } from './format.js'
+import { writeModelsToConfigs } from './write.js'
+
+async function pickRoleModel(role, allModels) {
+  const rolePreset = modelsPreset.roles[role]
+  const [first, ...rest] = rolePreset.info
+  prompt(first)
+  for (const line of rest) info(line)
+  console.log()
+
+  while (true) {
+    const provider = await pickProvider('Provider:')
+    const filtered = filterModelsByProvider(allModels, provider)
+    const available = filtered.length > 0 ? filtered : allModels
+
+    const suggestion = rolePreset.suggestions?.[provider]
+    if (suggestion) info(`  Suggested: ${suggestion}`)
+    if (filtered.length === 0 && provider) warn(`  No ${provider} models found: showing all`)
+
+    const model = await pickModel(rolePreset.prompt, available)
+    if (model !== '__back__') return model
+  }
+}
+
+export async function chooseModels() {
+  header('Step 7, Choose models');
+
+  info('Fetching available models from models.dev...');
+  const { models: rawModels, source } = await fetchModels();
+
+  if (!rawModels) {
+    warn('Could not fetch models (offline and no cache). Skipping model selection.');
+    warn('Set models later in opencode.jsonc');
+    return;
+  }
+
+  if (source === 'stale-cache') {
+    warn('Network unavailable, using cached model list (may be outdated).');
+  } else if (source === 'cache') {
+    info('Using cached model list (refreshes weekly).');
+  }
+
+  const models = buildDisplayModels(rawModels);
+  success(`${models.length} models available`);
+  console.log();
+  info('Three models: main session, engineers, and light commands.');
+  info('Cost indicators: [$] cheap  [$$] mid  [$$$] expensive');
+  info('Pick provider first, then search by name. Change later in opencode.jsonc');
+  console.log();
+
+  const planModel  = await pickRoleModel('plan',  models); console.log();
+  const buildModel = await pickRoleModel('build', models); console.log();
+  const fastModel  = await pickRoleModel('fast',  models); console.log();
+
+  await writeModelsToConfigs({ planModel, buildModel, fastModel });
+
+  console.log();
+  warn('Make sure you have API access to the selected models.');
+  warn('Change them anytime in opencode.jsonc');
+
+  return { planModel, buildModel, fastModel };
+}

package/src/steps/models/write.js

@@ -0,0 +1,34 @@
+import fse from 'fs-extra'
+import { applyEdits, modify, parse } from 'jsonc-parser'
+import path from 'path'
+import { success, warn } from '../../utils/exec.js'
+
+/**
+ * Writes the selected build model as the default model in opencode.jsonc.
+ * Per-tier models (plan/build/fast) are recorded in harness.json (models)
+ * by the metadata step, then consumed by the agent-variant generator and /plan-apply.
+ *
+ * opencode tolerates JSONC (comments, trailing commas) in its config, so this
+ * must not use readJson/writeJson: a strict parse crashes on valid configs and
+ * a strict rewrite deletes user comments. jsonc-parser edits only the `model`
+ * key and preserves the rest of the file byte-for-byte.
+ */
+export async function writeModelsToConfigs({ buildModel, cwd = process.cwd() }) {
+  const opencodeJsonPath = path.join(cwd, 'opencode.jsonc')
+  if (!await fse.pathExists(opencodeJsonPath)) return
+
+  const text = await fse.readFile(opencodeJsonPath, 'utf-8')
+  const errors = []
+  parse(text, errors)
+  if (errors.length > 0) {
+    warn('opencode.jsonc could not be parsed: leaving it untouched. Set "model" manually.')
+    return
+  }
+
+  // `undefined` removes the key; a string value sets it.
+  const edits = modify(text, ['model'], buildModel || undefined, {
+    formattingOptions: { insertSpaces: true, tabSize: 2 },
+  })
+  await fse.writeFile(opencodeJsonPath, applyEdits(text, edits), 'utf-8')
+  if (buildModel) success(`default model -> ${buildModel} (written to opencode.jsonc)`)
+}

package/src/steps/openspec/index.js

@@ -0,0 +1,136 @@
+import { execa } from "execa"
+import fse from "fs-extra"
+import path from "node:path"
+import { commandExists, error, header, info, loading, success, warn } from "../../utils/exec.js"
+
+
+async function cleanOpenspecFiles() {
+  const cwd = process.cwd()
+  const commandsDir = path.join(cwd, '.opencode', 'commands')
+  const opencodeSkillsDir = path.join(cwd, '.opencode', 'skills')
+  const agentsSkillsDir = path.join(cwd, '.agents', 'skills')
+
+  // Delete opsx-* command files generated by OpenSpec: we use /plan-propose and /plan-apply instead
+  if (await fse.pathExists(commandsDir)) {
+    for (const f of await fse.readdir(commandsDir)) {
+      if (f.startsWith('opsx-') && f.endsWith('.md')) {
+        await fse.remove(path.join(commandsDir, f))
+        info(`Removed generated command: ${f}`)
+      }
+    }
+  }
+
+  // Move .opencode/skills/* to .agents/skills/: skills should be in the universal location
+  if (await fse.pathExists(opencodeSkillsDir)) {
+    await fse.ensureDir(agentsSkillsDir)
+    for (const dir of await fse.readdir(opencodeSkillsDir)) {
+      const src = path.join(opencodeSkillsDir, dir)
+      const dest = path.join(agentsSkillsDir, dir)
+      if (!(await fse.pathExists(dest))) {
+        await fse.move(src, dest)
+        info(`Moved skill: ${dir} → .agents/skills/`)
+      } else {
+        await fse.remove(src)
+      }
+    }
+    // Remove .opencode/skills if now empty
+    const remaining = await fse.readdir(opencodeSkillsDir)
+    if (remaining.length === 0) await fse.remove(opencodeSkillsDir)
+  }
+
+  success('OpenSpec generated files cleaned up')
+}
+
+export const openspecSteps = {
+  check,
+  install,
+  init,
+}
+
+export async function initOpenspec() {
+  header("Step 6, Initializing OpenSpec")
+
+  let openSpec = await openspecSteps.check()
+  if (!openSpec.available) {
+    await openspecSteps.install()
+  }
+
+  openSpec = await openspecSteps.check()
+  if (!openSpec.available) {
+    warn("OpenSpec has not been installed. It is required to create changes.")
+    return { ...openSpec, initialized: false }
+  }
+
+  const initResult = await openspecSteps.init()
+  if (!initResult.initialized) {
+    warn(
+      "OpenSpec has not been initialized. It is required to create changes.",
+    )
+    return { ...openSpec, initialized: false }
+  }
+
+  await cleanOpenspecFiles()
+  return { ...openSpec, initialized: true }
+}
+
+async function install() {
+  info("Installing OpenSpec...")
+  try {
+    const result = await execa(
+      "npm",
+      ["install", "@fission-ai/openspec", "--global"],
+      {
+        cwd: process.cwd(),
+        stdio: "pipe",
+        reject: false,
+      },
+    )
+    if (result.exitCode !== 0) {
+      warn("OpenSpec install failed, check output above")
+    }
+    success("OpenSpec installed")
+  } catch (err) {
+    error(`Failed to run openspec install: ${err.message}`)
+  }
+}
+
+async function check() {
+  loading("Checking OpenSpec...")
+
+  const available = await commandExists("openspec")
+
+  if (available) success("OpenSpec is available")
+  else warn("OpenSpec not found on PATH.")
+
+  return { available }
+}
+
+async function init() {
+  loading("Initializing OpenSpec...")
+  try {
+    const result = await execa(
+      "npx",
+      ["@fission-ai/openspec", "init", "--tools", "opencode", "--force"],
+      {
+        cwd: process.cwd(),
+        reject: false,
+      },
+    )
+
+    if (result.exitCode !== 0) {
+      const stderr = (result.stderr || "").trim()
+      const msg = stderr
+        ? `init failed: ${stderr}`
+        : `init failed with exit code ${result.exitCode}`
+      throw new Error(msg)
+    }
+  } catch (err) {
+    error(`Failed to run openspec init: ${err.message}`)
+    return { initialized: false }
+  }
+
+  success("OpenSpec initialized")
+  return { initialized: true }
+}
+
+