opencode-onboard 0.1.13 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-onboard",
-  "version": "0.1.13",
+  "version": "0.2.3",
   "description": "Prepare any brownfield codebase for AI agent workflows using OpenCode, OpenSpec, and ensemble orchestration.",
   "keywords": [
     "opencode",

package/src/index.js

@@ -5,11 +5,14 @@ import { checkEnv } from './steps/check-env.js'
 import { checkPlatform } from './steps/check-platform.js'
 import { checkRtk } from './steps/check-rtk.js'
 import { chooseModels } from './steps/choose-models.js'
-import { choosePlatform } from './steps/choose-platform.js'
-import { chooseSkillsProvider } from './steps/choose-skills-provider.js'
+import { choosePlatform } from './steps/choose-platform.js'
+import { chooseSourceScope } from './steps/choose-source-scope.js'
+import { chooseSkillsProvider } from './steps/choose-skills-provider.js'
 import { cleanAiFiles } from './steps/clean-ai-files.js'
 import { copyContentStep } from './steps/copy-content.js'
 import { initOpenspec } from './steps/init-openspec.js'
+import { patchAgentsMd } from './steps/patch-agents-md.js'
+import { installBrowser } from './steps/install-browser.js'
 
 if (process.stdout.isTTY) console.clear()
 console.log()
@@ -57,45 +60,62 @@ try {
   // 1. Check Node + pnpm
   await checkEnv()
 
-  // 2. Clean existing AI config files
-  await cleanAiFiles()
-
-  // 3. Choose platform
-  const platform = await choosePlatform()
-
-  // 4. Check platform CLI (az or gh)
-  await checkPlatform(platform)
-
-  // 5. Copy content
-  await copyContentStep(platform)
-
-  // 6. Init OpenSpec
-  await initOpenspec()
-
-  // 7. Install skills
-  await chooseSkillsProvider()
-
-  // 8. Choose models
-  await chooseModels()
-
-  // 9. Check RTK
-  await checkRtk()
-
-  // 10. Install opencode-browser
-  await installBrowser()
+  // 2. Choose source code scope for init analysis
+  const scope = await chooseSourceScope()
+
+  // 3. Clean existing AI config files, detect preserved state
+  const preserve = await cleanAiFiles()
+  const ctx = { ...preserve, ...scope }
+
+  // 4. Choose platform
+  const platform = await choosePlatform()
+
+  // 5. Check platform CLI (az or gh)
+  await checkPlatform(platform)
+
+  // 6. Copy content
+  await copyContentStep(platform, ctx)
+
+  // 6b. Patch AGENTS.md to skip steps for already-existing files
+  await patchAgentsMd(ctx)
+
+  // 7. Init OpenSpec
+  await initOpenspec()
+
+  // 8. Install skills
+  await chooseSkillsProvider()
+
+  // 9. Choose models
+  await chooseModels()
+
+  // 10. Check RTK
+  await checkRtk()
+
+  // 11. Install opencode-browser
+  await installBrowser()
 
   // Done
+  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('  Next step:')
-  console.log(chalk.hex('#fe3d57')('  Open OpenCode in this project and type: ') + chalk.bold('"init"'))
-  console.log()
-  console.log('  OpenCode will generate ARCHITECTURE.md and DESIGN.md')
-  console.log('  from your actual codebase, then activate the agent team.')
+  console.log('  Open this project in OpenCode and type:')
+  console.log(chalk.bold('  "init"'))
   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()
 } catch (err) {
   if (err.name === 'ExitPromptError') {
     console.log()

package/src/steps/check-platform.js

@@ -10,7 +10,7 @@ export async function checkPlatform(platform) {
 }
 
 async function checkAzure() {
-  header('Step 4, Checking Azure DevOps CLI')
+  header('Step 5, Checking Azure DevOps CLI')
 
   // Check az is installed
   const hasAz = await commandExists('az')
@@ -51,7 +51,7 @@ async function checkAzure() {
 }
 
 async function checkGithub() {
-  header('Step 4, Checking GitHub CLI')
+  header('Step 5, Checking GitHub CLI')
 
   const hasGh = await commandExists('gh')
 

package/src/steps/check-rtk.js

@@ -1,7 +1,7 @@
 import { code, commandExists, header, info, success, warn } from '../utils/exec.js'
 
 export async function checkRtk() {
-  header('Step 9, Checking rtk')
+  header('Step 10, Checking rtk')
 
   const available = await commandExists('rtk')
 

package/src/steps/choose-models.js

@@ -66,7 +66,7 @@ async function writeModelToAgent(agentFile, modelId) {
 }
 
 export async function chooseModels() {
-  header('Step 8, Choose models')
+  header('Step 9, Choose models')
 
   info('Fetching available models from models.dev...')
   const { models: rawModels, source } = await fetchModels()
@@ -91,20 +91,21 @@ export async function chooseModels() {
   console.log()
 
   // Plan model
-  info('PLAN model, used by the main agent for proposals, specs, architecture decisions.')
-  info('Pick something capable with strong reasoning.')
+  info('PLAN model: used by the main agent to read issues, write proposals, coordinate the team.')
+  info('This model needs to be strong. Use Claude Sonnet/Opus, GPT-4o, o3, or equivalent.')
+  info('A weak model here will silently skip steps and break the workflow.')
   const planModel = await pickModel('Plan model:', models)
   console.log()
 
   // Build model
-  info('BUILD model, used by front-engineer, back-engineer, infra-engineer, quality-engineer, security-auditor.')
-  info('Pick something capable for implementation work.')
+  info('BUILD model: used by front-engineer, back-engineer, infra-engineer, quality-engineer, security-auditor.')
+  info('Needs to be capable for implementation work. Claude Sonnet, GPT-4o, or equivalent.')
   const buildModel = await pickModel('Build model:', models)
   console.log()
 
   // Fast model
-  info('FAST model, used by devops-manager for reading issues, classifying PR comments.')
-  info('Pick something fast and cheap, no heavy reasoning needed.')
+  info('FAST model: used by devops-manager for reading issues and classifying PR comments.')
+  info('Something fast and cheap is fine here, no heavy reasoning needed.')
   const fastModel = await pickModel('Fast model:', models)
   console.log()
 

package/src/steps/choose-platform.js

@@ -10,7 +10,7 @@ const PLATFORMS_PRESET_PATH = path.resolve(__dirname, '../presets/platforms.json
 const platformsPreset = await fse.readJson(PLATFORMS_PRESET_PATH)
 
 export async function choosePlatform() {
-  header('Step 3, Version control platform')
+  header('Step 4, Version control platform')
 
   const platform = await select({
     message: 'Which platform are you using?',

package/src/steps/choose-skills-provider.js

@@ -28,7 +28,7 @@ async function installObSkills() {
 }
 
 export async function chooseSkillsProvider() {
-  header('Step 7, Installing skills')
+  header('Step 8, Installing skills')
 
   // ob-skills are always installed, mandatory
   info('Installing built-in ob-skills...')

package/src/steps/choose-source-scope.js

@@ -0,0 +1,81 @@
+import { checkbox, select } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'path'
+import { header, info, success, warn } from '../utils/exec.js'
+
+async function listParentFolders(cwd) {
+  const parent = path.resolve(cwd, '..')
+  const entries = await fse.readdir(parent)
+  const dirs = []
+
+  for (const name of entries) {
+    if (name.startsWith('.')) continue
+    const abs = path.join(parent, name)
+    try {
+      const stat = await fse.stat(abs)
+      if (!stat.isDirectory()) continue
+      if (path.resolve(abs) === path.resolve(cwd)) continue
+      dirs.push({ name, abs })
+    } catch {
+      // ignore invalid entries
+    }
+  }
+
+  dirs.sort((a, b) => a.name.localeCompare(b.name))
+  return dirs
+}
+
+export async function chooseSourceScope() {
+  header('Step 2, Source code scope')
+
+  const cwd = process.cwd()
+  info('Choose where agents should read source code from during init analysis.')
+
+  const mode = await select({
+    message: 'Source code location:',
+    default: 'current',
+    choices: [
+      {
+        name: 'Current folder (default)',
+        value: 'current',
+        description: 'Use this repository only',
+      },
+      {
+        name: 'Select folders in parent (../)',
+        value: 'parent',
+        description: 'Use when this repo only contains agent config',
+      },
+    ],
+  })
+
+  if (mode === 'current') {
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  const parentFolders = await listParentFolders(cwd)
+  if (parentFolders.length === 0) {
+    warn('No sibling folders found in parent directory. Falling back to current folder.')
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  const selected = await checkbox({
+    message: 'Select source folders from parent directory:',
+    choices: parentFolders.map(d => ({
+      name: `../${d.name}`,
+      value: d.abs,
+      checked: false,
+    })),
+    required: true,
+  })
+
+  if (!selected || selected.length === 0) {
+    warn('No folders selected. Falling back to current folder.')
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  success(`Source scope: ${selected.map(p => path.basename(p)).join(', ')}`)
+  return { sourceMode: 'parent-selected', sourceRoots: selected }
+}

package/src/steps/clean-ai-files.js

@@ -1,11 +1,14 @@
 import fse from 'fs-extra'
 import path from 'path'
 import { findAiFiles } from '../utils/copy.js'
-import { header, info, prompt, success, warn } from '../utils/exec.js'
+import { header, info, success, warn } from '../utils/exec.js'
+
+// Files/dirs that are valuable pre-existing work, never removed
+const PRESERVE = ['DESIGN.md', 'ARCHITECTURE.md', 'openspec']
 
 /**
- * Enumerate immediate children of a directory, returning their absolute paths.
- * Skips any entry named 'skills' at any level to preserve user-installed skills.
+ * Enumerate immediate children of a directory.
+ * Skips 'skills' to preserve user-installed skills.
  */
 async function childrenExcludingSkills(dir) {
   const results = []
@@ -18,15 +21,55 @@ async function childrenExcludingSkills(dir) {
   return results
 }
 
+/**
+ * Returns true if the file exists and has real content (not empty, not a prompt template).
+ * Prompt templates contain a specific marker written by the onboard CLI.
+ */
+async function isPopulated(filePath) {
+  if (!await fse.pathExists(filePath)) return false
+  const content = await fse.readFile(filePath, 'utf-8')
+  const trimmed = content.trim()
+  if (!trimmed) return false
+  // DESIGN.md and ARCHITECTURE.md shipped as prompt templates contain this marker
+  if (trimmed.startsWith('<!-- onboard-prompt')) return false
+  return true
+}
+
+/**
+ * Returns true if openspec/ exists and has at least one change or archive entry.
+ */
+async function hasOpenspecHistory(cwd) {
+  const changesDir = path.join(cwd, 'openspec', 'changes')
+  const archiveDir = path.join(cwd, 'openspec', 'archive')
+  if (await fse.pathExists(changesDir)) {
+    const entries = await fse.readdir(changesDir)
+    if (entries.length > 0) return true
+  }
+  if (await fse.pathExists(archiveDir)) {
+    const entries = await fse.readdir(archiveDir)
+    if (entries.length > 0) return true
+  }
+  return false
+}
+
 export async function cleanAiFiles() {
-  header('Step 2, Existing AI config files')
+  header('Step 3, Existing AI config files')
 
   const cwd = process.cwd()
 
-  // Flat AI config files (not directories)
-  const flatFiles = await findAiFiles(cwd)
+  // Detect what should be preserved before touching anything
+  const ctx = {
+    hasDesign: await isPopulated(path.join(cwd, 'DESIGN.md')),
+    hasArchitecture: await isPopulated(path.join(cwd, 'ARCHITECTURE.md')),
+    hasOpenspec: await hasOpenspecHistory(cwd),
+  }
 
-  // For directory targets (.opencode, .agents), enumerate children and skip skills/
+  if (ctx.hasDesign) info('DESIGN.md exists and is populated, keeping it')
+  if (ctx.hasArchitecture) info('ARCHITECTURE.md exists and is populated, keeping it')
+  if (ctx.hasOpenspec) info('openspec/ history exists, keeping it')
+
+  // Build the list of files to remove
+  const flatFiles = await findAiFiles(cwd)
   const dirTargets = ['.opencode', '.agents']
   const dirEntries = []
   for (const dirName of dirTargets) {
@@ -35,37 +78,28 @@ export async function cleanAiFiles() {
     dirEntries.push(...children)
   }
 
-  // Remove the directory targets themselves from flat list (we handle them via children)
+  // Remove directory targets themselves from flat list (handled via children)
+  // Also remove any preserved entries
   const filteredFlat = flatFiles.filter(f => {
     const rel = path.relative(cwd, f)
-    return !dirTargets.includes(rel)
+    if (dirTargets.includes(rel)) return false
+    if (PRESERVE.some(p => rel === p || rel.startsWith(p + path.sep))) return false
+    return true
   })
 
-  const allFiles = [...filteredFlat, ...dirEntries]
+  const allToRemove = [...filteredFlat, ...dirEntries]
 
-  if (allFiles.length === 0) {
-    success('No existing AI config files found')
-    return
+  if (allToRemove.length === 0) {
+    success('No existing AI config files to remove')
+    return ctx
   }
 
-  warn('Found the following AI config files:')
-  for (const f of allFiles) {
-    info(f.replace(cwd, '.'))
-  }
-  console.log()
-  prompt('Press Enter to remove them all (skills/ folders will be kept)')
-  console.log()
-
-  await new Promise(resolve => {
-    process.stdin.resume()
-    process.stdin.once('data', () => {
-      process.stdin.pause()
-      resolve()
-    })
-  })
-
-  for (const f of allFiles) {
+  warn('Removing existing AI config files:')
+  for (const f of allToRemove) {
+    info('  ' + f.replace(cwd + path.sep, ''))
     await fse.remove(f)
   }
   success('Removed existing AI config files')
+
+  return ctx
 }

package/src/steps/copy-content.js

@@ -1,18 +1,25 @@
 import path from 'path'
 import { fileURLToPath } from 'url'
+import fse from 'fs-extra'
 import { copyContent } from '../utils/copy.js'
 import { error, header, success } from '../utils/exec.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const CONTENT_DIR = path.resolve(__dirname, '../../content')
 
-export async function copyContentStep(platform) {
-  header('Step 5, Copying opencode-onboard files')
+export async function copyContentStep(platform, ctx = {}) {
+  header('Step 6, Copying opencode-onboard files')
 
   const dest = process.cwd()
 
   try {
-    await copyContent(CONTENT_DIR, dest, platform)
+    await copyContent(CONTENT_DIR, dest, platform, ctx)
+    const rootsFile = path.join(dest, '.agents', 'source-roots.json')
+    await fse.ensureDir(path.dirname(rootsFile))
+    await fse.writeJson(rootsFile, {
+      mode: ctx.sourceMode || 'current',
+      roots: ctx.sourceRoots || [dest],
+    }, { spaces: 2 })
     success('Files copied to project root')
   } catch (err) {
     error(`Failed to copy content: ${err.message}`)