opencode-onboard 0.1.13 → 0.2.3

package/src/steps/init-openspec.js

@@ -1,9 +1,14 @@
 import { execa } from 'execa'
-import fs from 'node:fs'
 import path from 'node:path'
+import fse from 'fs-extra'
 import { error, header, success, warn } from '../utils/exec.js'
 
-const ENSEMBLE_PATCH = `6. **Implement via ensemble team**
+const APPLY_TARGETS = [
+  path.join('.opencode', 'commands', 'opsx-apply.md'),
+  path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
+]
+
+const ENSEMBLE_SECTION = `6. **Implement via ensemble team**
 
    NEVER implement tasks directly. Always delegate to specialists via ensemble.
    Do NOT touch any source files before the team is running, not even a single edit.
@@ -12,31 +17,43 @@ const ENSEMBLE_PATCH = `6. **Implement via ensemble team**
 
    **Step 6a.** Create feature branch if not already on one: \`feature/{id}-{slug}\`
 
-   **Step 6b.** Clean up stale state, then create the team:
+   **Step 6b.** Create the team:
       \`\`\`
-      team_cleanup force:true acknowledge_uncommitted:true
-      team_create "<change-name>"
+      team_create "<change-name>-<random 4 digit number>"
       \`\`\`
-      "not in a team" error from team_cleanup is expected, ignore it.
       Announce: "Team running. Monitor at http://localhost:4747/"
 
    **Step 6c.** Add ALL tasks to the shared board BEFORE spawning anyone.
-      Schema: { content: string, priority: "high"|"medium"|"low" }. No other fields.
+      Schema: { content: string, priority: "high"|"medium"|"low", depends_on?: string[] }
+      Use depends_on to block tasks that require other tasks first, pass the IDs returned by team_tasks_add.
       \`\`\`
       team_tasks_add tasks:[
         { content: "1.1 <exact task text from tasks.md>", priority: "high" },
         { content: "1.2 <exact task text>", priority: "high" },
-        ...every task from tasks.md, one entry each...
+        { content: "3.1 <task that needs 1.x done first>", priority: "medium", depends_on: ["<id-of-1.1>"] },
+        ...every task, one entry each...
       ]
       \`\`\`
+      Save the task IDs returned. Pass them to agents in step 6d.
+      DO NOT call team_claim yourself, only agents claim tasks.
       DO NOT proceed to 6d until team_tasks_add succeeds.
-      Do NOT call team_claim or interact with tasks further — the board is for visibility only.
 
-   **Step 6d.** Spawn specialists ONE AT A TIME. Wait for each team_spawn result before calling the next.
-      Each team_spawn MUST include agent field (required, causes NOT NULL error if omitted).
-      Include: full task list and all context file paths. Tell each agent to:
-      - implement their tasks in order
-      - send results to lead via team_message when all done or blocked
+   **Step 6d.** Spawn all needed specialists, then kick them off in parallel.
+
+      Each team_spawn MUST include the agent field (required, causes NOT NULL error if omitted).
+
+      The spawn prompt must contain exactly:
+      1. Their name and role on this team
+      2. Which tasks are theirs, list the task IDs and content from the board
+      3. Key context they need (summarized from context files, do NOT tell them to read files themselves)
+      4. The 6 OpenCode tools they have available (these are OpenCode tools, NOT shell commands, call them directly as tools, never via bash):
+         team_claim, team_tasks_complete, team_tasks_list, team_tasks_add, team_message, team_broadcast
+      5. How to proceed: call team_claim tool with the task_id to claim a task before starting it, call team_tasks_complete tool after finishing it, repeat until all their tasks are done, then call team_message tool to notify lead with results or blockers
+
+      Keep spawn prompts under 500 tokens. Do not describe team internals or how ensemble works.
+      Only spawn agents whose tasks are actually needed by this change. Skip agents with no tasks.
+
+      First spawn all agents (wait for each team_spawn to confirm before the next):
       \`\`\`
       team_spawn name:"back" agent:"back-engineer" prompt:"..."
       (wait for result)
@@ -46,26 +63,33 @@ const ENSEMBLE_PATCH = `6. **Implement via ensemble team**
       (wait for result)
       \`\`\`
 
-   **Step 6e.** After all spawns, tell the user what is running, then STOP and wait.
+      Then immediately send each spawned agent a start message to kick them off:
+      \`\`\`
+      team_message to:"back" text:"Start now. Claim your first task with team_claim and begin implementing."
+      team_message to:"front" text:"Start now. Claim your first task with team_claim and begin implementing."
+      team_message to:"infra" text:"Start now. Claim your first task with team_claim and begin implementing."
+      \`\`\`
+
+   **Step 6e.** After sending start messages, tell the user what is running, then STOP and wait.
       Do NOT call team_results, team_status, or team_broadcast in a loop.
       Teammates will message you when done or blocked. Wait for those messages.
 
-   **Step 6f.** When teammates message back: call team_results to get full output
-      (team_message delivery is truncated — always use team_results for the full content).
-      Then for each teammate: team_shutdown → team_merge. Fix any blockers reported.
-      Do NOT edit any files between spawns and merges — team_merge blocks on overlapping local changes.
+   **Step 6f.** When a teammate messages back, you receive a ping only, the full content is NOT in the notification.
+      Call team_results to read the full message and mark it read. Then for each teammate: team_shutdown -> team_merge.
+      If team_merge blocks ("overlapping local changes"), commit or stash your local changes first, then retry.
+      Fix any other blockers reported.
 
 7. **Quality check**
 
    Spawn quality engineer with worktree:false (read-only, no file edits):
    \`\`\`
-   team_spawn name:"quality" agent:"quality-engineer" worktree:false prompt:"<task list, context files, run tests + build + lint + verify acceptance criteria, send results to lead when done>"
+   team_spawn name:"quality" agent:"quality-engineer" worktree:false prompt:"<task list, context summary, run tests + build + lint + verify acceptance criteria, send results to lead when done>"
    \`\`\`
-   Wait for message → team_results → fix blockers → team_shutdown (no team_merge needed, worktree:false)
+   Wait for message -> team_results -> fix blockers -> team_shutdown (no team_merge needed, worktree:false)
 
 8. **Mark tasks complete in openspec**
 
-   Update tasks.md: \`- [ ]\` → \`- [x]\` for each completed task.
+   Update tasks.md: \`- [ ]\` -> \`- [x]\` for each completed task.
    Run \`rtk openspec status --change "<name>" --json\` to confirm.
 
 9. **Show status, then cleanup**
@@ -82,53 +106,47 @@ const ENSEMBLE_PATCH = `6. **Implement via ensemble team**
 - NEVER skip or reorder steps 6a-6f
 - NEVER implement tasks directly. Always use team_create + team_spawn, no exceptions
 - NEVER touch source files before team_create is called, not even one edit
-- NEVER call team_spawn without the agent field — it is required and will fail without it
-- NEVER call team_spawn before team_tasks_add — tasks must exist before agents are spawned
-- NEVER poll team_results or team_status in a loop — wait for teammates to message you
-- NEVER call team_claim or team_tasks_complete — the task board is visual only, tasks.md is the source of truth
-- NEVER edit files between team_spawn and team_merge — team_merge blocks on overlapping local changes
-- ALWAYS run team_cleanup force:true before team_create to clear stale state
-- ALWAYS add every task from tasks.md to the board with team_tasks_add before spawning
-- ALWAYS spawn one at a time, waiting for each result before the next (avoids worktree contention)
-- Do NOT instruct agents to call team_claim, team_tasks_complete, or any task board tool — agents only implement and report back via team_message
-- If teammates are stuck, use team_message to resend tasks, then wait — never implement directly
+- NEVER call team_spawn without the agent field, it is required and will fail without it
+- NEVER call team_spawn before team_tasks_add, tasks must exist before agents are spawned
+- NEVER poll team_results or team_status in a loop, wait for teammates to message you
+- NEVER call team_claim or team_tasks_complete as lead, only agents call these tools
+- ALWAYS pass the task IDs returned by team_tasks_add to each agent's spawn prompt
+- NEVER edit files between team_spawn and team_merge, team_merge blocks on overlapping local changes
+- ALWAYS add every task to the board with team_tasks_add before spawning
+- ALWAYS spawn agents sequentially (wait for each team_spawn result before the next), then send start messages to all of them together
+- ALWAYS instruct agents to call team_claim before each task and team_tasks_complete after
+- If teammates are stuck, use team_message to resend tasks, then wait, never implement directly
 - Mark tasks complete in openspec AFTER specialists finish, not before
 - Pause on errors, blockers, or unclear requirements. Do not guess
 - Use contextFiles from CLI output, do not assume specific file paths
+- Use \`rtk\` wrapper for ALL CLI commands. Never run openspec, git, gh, or az directly
 `
 
-// Patterns that identify the solo implementation step in openspec-generated files
-const SOLO_IMPL_PATTERNS = [
-  /^#{1,3}\s+\d+\..*(implement|loop until|make the code changes|for each (pending )?task)/im,
-  /\*\*Implement tasks.*loop until/im,
-  /^6\.\s+\*\*Implement tasks/im,
-]
+const STEP_6_START = /^6\.\s+\*\*Implement\b/im
+const FLUID_SECTION = /^\*\*Fluid Workflow Integration\*\*/im
 
-function patchOpensxApply(filePath) {
-  if (!fs.existsSync(filePath)) return false
+async function patchApplyFile(filePath) {
+  if (!await fse.pathExists(filePath)) return { ok: false, reason: 'missing-file' }
 
-  const content = fs.readFileSync(filePath, 'utf8')
-  const lines = content.split('\n')
+  const original = await fse.readFile(filePath, 'utf-8')
+  const startMatch = original.match(STEP_6_START)
+  if (!startMatch || startMatch.index === undefined) return { ok: false, reason: 'missing-step-6' }
 
-  // Find the line index where the solo implementation step starts
-  let cutLine = -1
-  for (let i = 0; i < lines.length; i++) {
-    if (SOLO_IMPL_PATTERNS.some(p => p.test(lines[i]))) {
-      cutLine = i
-      break
-    }
-  }
+  const before = original.slice(0, startMatch.index).replace(/\s*$/, '')
+  const fromStep6 = original.slice(startMatch.index)
+  const fluidMatch = fromStep6.match(FLUID_SECTION)
 
-  if (cutLine === -1) return false // Pattern not found, skip
+  const after = fluidMatch && fluidMatch.index !== undefined
+    ? `\n\n${fromStep6.slice(fluidMatch.index).replace(/^\s*/, '')}`
+    : ''
 
-  const preamble = lines.slice(0, cutLine).join('\n').trimEnd()
-  const patched = preamble + '\n\n' + ENSEMBLE_PATCH
-  fs.writeFileSync(filePath, patched, 'utf8')
-  return true
+  const patched = `${before}\n\n${ENSEMBLE_SECTION}${after}`
+  await fse.writeFile(filePath, patched, 'utf-8')
+  return { ok: true }
 }
 
 export async function initOpenspec() {
-  header('Step 6, Initializing OpenSpec')
+  header('Step 7, Initializing OpenSpec')
 
   try {
     const result = await execa('npx', ['@fission-ai/openspec', 'init', '--tools', 'opencode', '--force'], {
@@ -146,19 +164,18 @@ export async function initOpenspec() {
     error(`Failed to run openspec init: ${err.message}`)
   }
 
-  // Patch opsx-apply.md to use ensemble orchestration instead of solo implementation
-  const targets = [
-    path.join(process.cwd(), '.opencode', 'commands', 'opsx-apply.md'),
-    path.join(process.cwd(), '.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
-  ]
-
-  for (const target of targets) {
+  // Keep openspec defaults for selection/status/context steps, replace only implementation + guardrails.
+  for (const rel of APPLY_TARGETS) {
+    const abs = path.join(process.cwd(), rel)
     try {
-      const patched = patchOpensxApply(target)
-      if (patched) success(`Patched ${path.relative(process.cwd(), target)} for ensemble`)
+      const res = await patchApplyFile(abs)
+      if (res.ok) {
+        success(`Patched ensemble implementation section in ${rel}`)
+      } else {
+        warn(`Could not patch ${rel} (${res.reason})`)
+      }
     } catch (err) {
-      warn(`Could not patch ${path.relative(process.cwd(), target)}: ${err.message}`)
+      warn(`Could not patch ${rel}: ${err.message}`)
     }
   }
 }
-

package/src/steps/install-browser.js

@@ -12,7 +12,7 @@ const AUTO_ANSWERS = [
 ]
 
 export async function installBrowser() {
-  header('Step 10, Installing opencode-browser')
+  header('Step 11, Installing opencode-browser')
 
   try {
     const child = execa('npx', ['@different-ai/opencode-browser', 'install'], {

package/src/steps/patch-agents-md.js

@@ -0,0 +1,85 @@
+import fse from 'fs-extra'
+import path from 'path'
+import { info, success } from '../utils/exec.js'
+
+// Each block is identified by its heading line. We remove from the heading up to (and including) the next `---` separator.
+const STEP1_HEADING = '### Step 1, Archive project history into OpenSpec'
+const STEP2_HEADING = '### Step 2, Generate DESIGN.md'
+const STEP3_HEADING = '### Step 3, Generate ARCHITECTURE.md'
+
+// Confirm message lines that reference each step, removed when the step is skipped
+const STEP1_CONFIRM_LINE = '- Project history archived in openspec'
+const STEP2_CONFIRM_LINE = '- DESIGN.md generated'
+const STEP3_CONFIRM_LINE = '- ARCHITECTURE.md generated'
+
+/**
+ * Remove a bootstrap step block from AGENTS.md content.
+ * Removes from the step heading line up to and including the next `---` separator line.
+ */
+function removeStepBlock(content, heading) {
+  const lines = content.split('\n')
+  const start = lines.findIndex(l => l.trim() === heading.trim())
+  if (start === -1) return content
+
+  // Find the next `---` separator after the heading
+  let end = -1
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break }
+  }
+
+  if (end === -1) return content
+
+  // Remove the block including any blank line before the heading
+  const removeFrom = start > 0 && lines[start - 1].trim() === '' ? start - 1 : start
+  lines.splice(removeFrom, end - removeFrom + 1)
+  return lines.join('\n')
+}
+
+/**
+ * Remove a specific line from the confirm message block in AGENTS.md.
+ */
+function removeConfirmLine(content, line) {
+  return content.split('\n').filter(l => l.trim() !== line.trim()).join('\n')
+}
+
+/**
+ * Renumber remaining bootstrap steps sequentially (Step 1, Step 2, ...).
+ */
+function renumberSteps(content) {
+  let counter = 0
+  return content.replace(/^### Step \d+,/gm, () => `### Step ${++counter},`)
+}
+
+export async function patchAgentsMd(ctx) {
+  const agentsMdPath = path.join(process.cwd(), 'AGENTS.md')
+  if (!await fse.pathExists(agentsMdPath)) return
+
+  let content = await fse.readFile(agentsMdPath, 'utf-8')
+  const patches = []
+
+  if (ctx.hasOpenspec) {
+    content = removeStepBlock(content, STEP1_HEADING)
+    content = removeConfirmLine(content, STEP1_CONFIRM_LINE)
+    patches.push('Step 1 (openspec history) removed, openspec/ already exists')
+  }
+
+  if (ctx.hasDesign) {
+    content = removeStepBlock(content, STEP2_HEADING)
+    content = removeConfirmLine(content, STEP2_CONFIRM_LINE)
+    patches.push('Step 2 (DESIGN.md) removed, DESIGN.md already exists')
+  }
+
+  if (ctx.hasArchitecture) {
+    content = removeStepBlock(content, STEP3_HEADING)
+    content = removeConfirmLine(content, STEP3_CONFIRM_LINE)
+    patches.push('Step 3 (ARCHITECTURE.md) removed, ARCHITECTURE.md already exists')
+  }
+
+  if (patches.length === 0) return
+
+  content = renumberSteps(content)
+  await fse.writeFile(agentsMdPath, content, 'utf-8')
+
+  for (const msg of patches) info(msg)
+  success('AGENTS.md patched for existing project state')
+}

package/src/utils/copy.js

@@ -2,24 +2,38 @@ import fse from 'fs-extra'
 import path from 'path'
 
 // Folders never copied (skills handled separately by chooseSkillsProvider, .bootstrap is internal tooling)
+// These are excluded from the general content copy, they are installed separately
+// by initOpenspec after openspec init runs, so our versions win over the generated ones.
 const ALWAYS_EXCLUDE = ['.bootstrap', 'skills', 'node_modules']
+const OPENSPEC_APPLY_FILES = [
+  path.join('.opencode', 'commands', 'opsx-apply.md'),
+  path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
+]
 
 /**
- * Copy content/ directory to destination, excluding skills (handled separately by chooseSkillsProvider)
- * and internal bootstrap tooling.
+ * Copy content/ directory to destination.
+ * Excludes:
+ *   - .agents/skills and .opencode/skills (handled separately)
+ *   - .bootstrap (internal tooling)
+ *   - node_modules
+ *   - opsx-apply.md and openspec-apply-change/SKILL.md (installed by initOpenspec)
+ *   - DESIGN.md and ARCHITECTURE.md if ctx says they already exist (preserve user's files)
  * @param {string} contentDir - absolute path to content/
  * @param {string} destDir - absolute path to destination (project root)
  * @param {'azure'|'github'} platform
+ * @param {{ hasDesign?: boolean, hasArchitecture?: boolean }} ctx
  */
-export async function copyContent(contentDir, destDir, platform) {
+export async function copyContent(contentDir, destDir, platform, ctx = {}) {
   await fse.copy(contentDir, destDir, {
     overwrite: false,
     filter: (src) => {
       const rel = path.relative(contentDir, src)
       const parts = rel.split(path.sep)
-      return !parts.some(part =>
-        ALWAYS_EXCLUDE.some(pattern => part.includes(pattern))
-      )
+      if (parts.some(part => ALWAYS_EXCLUDE.some(pattern => part.includes(pattern)))) return false
+      if (OPENSPEC_APPLY_FILES.some(f => rel === f)) return false
+      if (ctx.hasDesign && rel === 'DESIGN.md') return false
+      if (ctx.hasArchitecture && rel === 'ARCHITECTURE.md') return false
+      return true
     },
   })
 }