opencode-onboard 0.1.12 → 0.2.0

package/content/.agents/agents/back-engineer.md

@@ -63,8 +63,18 @@ Rules:
 - Do not force push
 - Report blockers immediately rather than working around them
 
+## Workflow
+
+When spawned by the lead:
+1. For each assigned task: call `team_claim task_id:<id>` before starting
+2. Implement the task
+3. Call `team_tasks_complete task_id:<id>` after finishing
+4. When all tasks are done or blocked, send results to lead via `team_message`
+
 ## Output Format
 
+Send via `team_message` to lead when done:
+
 ```
 ## Back Engineer, Done
 

package/content/.agents/agents/front-engineer.md

@@ -62,8 +62,18 @@ Rules:
 - Do not force push
 - Report blockers immediately rather than working around them
 
+## Workflow
+
+When spawned by the lead:
+1. For each assigned task: call `team_claim task_id:<id>` before starting
+2. Implement the task
+3. Call `team_tasks_complete task_id:<id>` after finishing
+4. When all tasks are done or blocked, send results to lead via `team_message`
+
 ## Output Format
 
+Send via `team_message` to lead when done:
+
 ```
 ## Front Engineer, Done
 

package/content/.agents/agents/quality-engineer.md

@@ -60,8 +60,17 @@ Rules:
 - Do not force push
 - Report all failures, do not silently skip failing tests
 
+## Workflow
+
+When spawned by the lead:
+1. Read the task list and context files provided in the spawn prompt
+2. Run tests, build, lint, and verify acceptance criteria
+3. When done, send results to lead via `team_message`
+
 ## Output Format
 
+Send via `team_message` to lead when done:
+
 ```
 ## Quality Engineer, Done
 

package/content/.opencode/commands/opsx-apply.md

@@ -0,0 +1,170 @@
+---
+description: Implement tasks from an OpenSpec change via ensemble agent team
+---
+
+Implement tasks from an OpenSpec change using the ensemble agent team.
+
+**Input**: Optionally specify a change name (e.g., `/opsx-apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `rtk openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
+
+2. **Check status to understand the schema**
+
+   ```bash
+   rtk openspec status --change "<name>" --json
+   ```
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   rtk openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx-continue`
+   - If `state: "all_done"`: congratulate, suggest archive with `/opsx-archive`
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   Do NOT tell agents to read files themselves, summarize the content here and pass it in spawn prompts.
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+
+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.
+
+   Steps MUST be followed in order. Do not skip any step.
+
+   **Step 6a.** Create feature branch if not already on one: `feature/{id}-{slug}`
+
+   **Step 6b.** Create the team:
+      ```
+      team_create "<change-name>-<random 4 digit number>"
+      ```
+      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", 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" },
+        { 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.
+
+   **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)
+      team_spawn name:"front" agent:"front-engineer" prompt:"..."
+      (wait for result)
+      team_spawn name:"infra" agent:"infra-engineer" prompt:"..."
+      (wait for result)
+      ```
+
+      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 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 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)
+
+8. **Mark tasks complete in openspec**
+
+   Update tasks.md: `- [ ]` → `- [x]` for each completed task.
+   Run `rtk openspec status --change "<name>" --json` to confirm.
+
+9. **Show status, then cleanup**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive with `/opsx-archive`
+   - If paused: explain why and wait for guidance
+
+   Then run `team_cleanup`.
+
+**Guardrails**
+- 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 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

package/content/.opencode/plugins/session-log.js

@@ -32,6 +32,22 @@ function resolveAgentName(session) {
   return "lead"
 }
 
+// Maps ensemble tool name → function that extracts the log entry fields from args
+const ENSEMBLE_TOOL_HANDLERS = {
+  team_create:         (args) => ({ action: "team-created",        team: args.name }),
+  team_spawn:          (args) => ({ action: "teammate-spawned",    name: args.name, agentType: args.agent }),
+  team_shutdown:       (args) => ({ action: "teammate-shutdown",   name: args.name }),
+  team_merge:          (args) => ({ action: "teammate-merged",     name: args.name }),
+  team_cleanup:        ()     => ({ action: "team-cleanup" }),
+  team_status:         ()     => ({ action: "team-status-checked" }),
+  team_results:        (args) => ({ action: "team-results-read",   from: args.from }),
+  team_message:        (args) => ({ action: "team-message",        to: args.to ?? "lead", preview: String(args.text ?? "").slice(0, 120) }),
+  team_broadcast:      (args) => ({ action: "team-broadcast",      preview: String(args.text ?? "").slice(0, 120) }),
+  team_tasks_add:      (args) => ({ action: "tasks-added",         count: Array.isArray(args.tasks) ? args.tasks.length : "?" }),
+  team_tasks_complete: (args) => ({ action: "task-completed",      taskId: args.task_id }),
+  team_claim:          (args) => ({ action: "task-claimed",        taskId: args.task_id }),
+}
+
 export const SessionLogPlugin = async ({ client, directory }) => {
   return {
     event: async ({ event }) => {
@@ -76,7 +92,10 @@ export const SessionLogPlugin = async ({ client, directory }) => {
         const state = sessionState.get(sessionId)
         if (!state) return
 
-        if (input?.tool === "read") {
+        const tool = input?.tool
+
+        // Track skill loads
+        if (tool === "read") {
           const filePath = input?.args?.filePath ?? ""
           const match = filePath.match(/[/\\]skills[/\\]([^/\\]+)[/\\]SKILL\.md$/i)
           if (match) {
@@ -84,7 +103,16 @@ export const SessionLogPlugin = async ({ client, directory }) => {
             if (!state.skills.includes(skillName)) state.skills.push(skillName)
             appendEntry(directory, { ts: ts(), agent: state.agentName, action: "skill-loaded", skill: skillName })
           }
+          return
         }
+
+        const args = input?.args ?? {}
+
+        // Track ensemble tool calls
+        const ensembleHandler = ENSEMBLE_TOOL_HANDLERS[tool]
+        if (!ensembleHandler) return
+
+        appendEntry(directory, { ts: ts(), agent: state.agentName, ...ensembleHandler(args) })
       } catch (_) {}
     },
   }

package/content/.opencode/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change via ensemble agent team. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI and opencode-ensemble plugin.
+metadata:
+  author: openspec-onboard
+  version: "2.0"
+---
+
+Implement tasks from an OpenSpec change using the ensemble agent team.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `rtk openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
+
+2. **Check status to understand the schema**
+
+   ```bash
+   rtk openspec status --change "<name>" --json
+   ```
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   rtk openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive with `/opsx-archive`
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   Do NOT tell agents to read files themselves, summarize the content here and pass it in spawn prompts.
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+
+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.
+
+   Steps MUST be followed in order. Do not skip any step.
+
+   **Step 6a.** Create feature branch if not already on one: `feature/{id}-{slug}`
+
+   **Step 6b.** Create the team:
+      ```
+      team_create "<change-name>-<random 4 digit number>"
+      ```
+      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", 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" },
+        { 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.
+
+   **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)
+      team_spawn name:"front" agent:"front-engineer" prompt:"..."
+      (wait for result)
+      team_spawn name:"infra" agent:"infra-engineer" prompt:"..."
+      (wait for result)
+      ```
+
+      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 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 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)
+
+8. **Mark tasks complete in openspec**
+
+   Update tasks.md: `- [ ]` → `- [x]` for each completed task.
+   Run `rtk openspec status --change "<name>" --json` to confirm.
+
+9. **Show status, then cleanup**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive with `/opsx-archive`
+   - If paused: explain why and wait for guidance
+
+   Then run `team_cleanup`.
+
+**Guardrails**
+- 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 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

package/content/AGENTS.md

@@ -72,14 +72,20 @@ Replace the entire contents of this file (`AGENTS.md`) with everything below the
 Tell the user:
 
 ```
-Initialization complete.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Initialization complete.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - ARCHITECTURE.md generated
 - DESIGN.md generated
 - Project history archived in openspec
 - AGENTS.md updated with real guidance
 
-You're ready to work.
+!! RESTART OPENCODE NOW !!
+
+Quit and reopen OpenCode before doing anything else.
+Nothing will work correctly until you do.
+After restarting you are ready to work.
 ```
 
 ---
@@ -108,13 +114,15 @@ This is the agent orchestration layer for your project. It provides:
 
 ## I Am the Lead, Full Workflow Ownership
 
-When the user provides a work item URL, says "implement the plan", or "I've added comments to the PR", **I own the full lifecycle**. I load the appropriate skill and use ensemble tools (`team_create`, `team_spawn`, etc.) to coordinate the agent team.
+When the user provides a work item URL or says "implement the plan" or "I've added comments to the PR", **I own the full lifecycle**. I load the appropriate skill and use ensemble tools to coordinate the agent team.
+
+Trigger patterns, I recognize ALL of these, exact wording does not matter:
+- User pastes or mentions a GitHub Issue URL → load `ob-userstory-gh` skill → parse issue → run `/opsx-propose` → confirm with user → run `/opsx-apply` → ship
+- User pastes or mentions an Azure DevOps URL → load `ob-userstory-az` skill → parse work item → run `/opsx-propose` → confirm with user → run `/opsx-apply` → ship
+- `implement the plan` / `implement` / `start` / `go` → run `/opsx-apply` → ship
+- `I've added comments to the PR` → read PR comments → fix → update PR
 
-Trigger patterns:
-- `work on this <azure-devops-url>` → spawn `devops-manager` in read mode → propose OpenSpec → **confirm with user** → implement → ship
-- `work on this <github-url>` → spawn `devops-manager` in read mode → propose OpenSpec → **confirm with user** → implement → ship
-- `implement the plan` → run `/opsx-apply` (ensemble orchestration is built into the command) → ship
-- `I've added comments to the PR` → spawn `devops-manager` in feedback mode → fix → update PR
+**A GitHub or Azure DevOps URL anywhere in the user's message is always a trigger, regardless of surrounding words.**
 
 **Never delegate without a plan. Never write implementation code directly, always spawn specialists, no exceptions. "Small feature", "faster to do it directly", or "environment issues" are not valid reasons to skip ensemble.**
 
@@ -130,11 +138,14 @@ Works on **all platforms** (Windows, macOS, Linux) via OpenCode's built-in workt
 | `team_shutdown` | Stop a teammate, preserve their branch |
 | `team_merge` | Merge a teammate's branch into working dir |
 | `team_cleanup` | Tear down the team |
-| `team_results` | Retrieve full message from a teammate |
-| `team_message` | Send a direct message to a teammate |
+| `team_results` | Retrieve full message content (delivery is a ping only) |
+| `team_message` | Send a direct message to a teammate or lead |
 | `team_broadcast` | Message all teammates |
+| `team_status` | View all members and task summary |
+| `team_tasks_list` | View the shared task board |
 | `team_tasks_add` | Add tasks to shared board |
-| `team_tasks_complete` | Mark task done |
+| `team_tasks_complete` | Mark task done, auto-unblocks dependents |
+| `team_claim` | Atomically claim a pending task (teammates use this) |
 
 **Dashboard**: Monitor running agents at **http://localhost:4747/**
 
@@ -151,12 +162,12 @@ devops-manager (read mode)
         ↓
   [confirm with user]
         ↓
-front-engineer + back-engineer + infra-engineer  ← parallel, only spawn what the task needs
+back-engineer → front-engineer → infra-engineer  ← sequential, one at a time, only spawn what the task needs
         ↓
-quality-engineer
+quality-engineer (worktree:false)
   → tests, build, lint, acceptance criteria
         ↓
-security-auditor
+security-auditor (worktree:false)
   → vulnerability audit, secrets, auth gaps
         ↓
 devops-manager (ship mode)
@@ -166,32 +177,35 @@ devops-manager (ship mode)
 ### Phase 1, Parse & Propose
 
 ```
-1. team_spawn devops-manager (read mode) → fetch work item via skill, output summary
-2. Load skill: openspec-propose → generate proposal.md, specs/, tasks.md
-   - team_create → spawn design + specs in parallel → merge → write tasks.md
-3. Show the plan: change name, schema, total tasks, task list summary
-4. STOP. Ask user: "Ready to implement? (yes/no)", DO NOT proceed until confirmed.
+1. Detect URL type → load matching skill (ob-userstory-gh or ob-userstory-az)
+2. Follow skill steps: fetch issue/work item via CLI, create OpenSpec change
+3. Run /opsx-propose → generates proposal.md, specs/, design.md, tasks.md
+4. Show the plan: change name, total tasks, task list summary
+5. STOP. Ask user: "Ready to implement? (yes/no)", DO NOT proceed until confirmed.
 ```
 
 ### Phase 2, Implement
 
 ```
 1. Run /opsx-apply, handles context reading, ensemble orchestration, and task marking.
+   - Lead adds all tasks to board, then spawns specialists ONE AT A TIME (not parallel)
+   - Each specialist claims tasks, implements, completes tasks, messages lead when done
+   - Lead merges each branch after shutdown, then marks tasks done in tasks.md
 2. After /opsx-apply completes, proceed to quality check.
 ```
 
 ### Phase 3, Quality
 
 ```
-7. team_spawn name:quality agent:quality-engineer → tests, build, lint
-8. Wait → team_results → fix any blockers → team_shutdown
+3. team_spawn name:quality agent:quality-engineer worktree:false → tests, build, lint
+4. Wait → team_results → fix any blockers → team_shutdown (no merge, worktree:false)
 ```
 
 ### Phase 4, Security
 
 ```
-9. team_spawn name:security agent:security-auditor → audit full change
-10. Wait → team_results → fix Critical findings → team_shutdown
+5. team_spawn name:security agent:security-auditor worktree:false → audit full change
+6. Wait → team_results → fix Critical findings → team_shutdown (no merge, worktree:false)
 ```
 
 ### Phase 5, Ship

package/package.json

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

package/src/index.js

@@ -10,6 +10,8 @@ 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,8 +59,8 @@ try {
   // 1. Check Node + pnpm
   await checkEnv()
 
-  // 2. Clean existing AI config files
-  await cleanAiFiles()
+  // 2. Clean existing AI config files, detect preserved state
+  const ctx = await cleanAiFiles()
 
   // 3. Choose platform
   const platform = await choosePlatform()
@@ -67,7 +69,10 @@ try {
   await checkPlatform(platform)
 
   // 5. Copy content
-  await copyContentStep(platform)
+  await copyContentStep(platform, ctx)
+
+  // 5b. Patch AGENTS.md to skip steps for already-existing files
+  await patchAgentsMd(ctx)
 
   // 6. Init OpenSpec
   await initOpenspec()
@@ -85,16 +90,25 @@ try {
   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('  Open this project in OpenCode and type:')
+  console.log(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.')
+  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()
 } catch (err) {
   if (err.name === 'ExitPromptError') {

package/src/steps/choose-models.js

@@ -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/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')
 
   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

@@ -6,13 +6,13 @@ 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) {
+export async function copyContentStep(platform, ctx = {}) {
   header('Step 5, Copying opencode-onboard files')
 
   const dest = process.cwd()
 
   try {
-    await copyContent(CONTENT_DIR, dest, platform)
+    await copyContent(CONTENT_DIR, dest, platform, ctx)
     success('Files copied to project root')
   } catch (err) {
     error(`Failed to copy content: ${err.message}`)

package/src/steps/init-openspec.js

@@ -1,130 +1,26 @@
 import { execa } from 'execa'
-import fs from 'node:fs'
+import fse from 'fs-extra'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { error, header, success, warn } from '../utils/exec.js'
 
-const ENSEMBLE_PATCH = `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.
-
-   Steps MUST be followed in order. Do not skip any step.
-
-   **Step 6a.** Create feature branch if not already on one: \`feature/{id}-{slug}\`
-
-   **Step 6b.** Clean up stale state, then create the team:
-      \`\`\`
-      team_cleanup force:true acknowledge_uncommitted:true
-      team_create "<change-name>"
-      \`\`\`
-      "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.
-      \`\`\`
-      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...
-      ]
-      \`\`\`
-      Save the task IDs returned. You MUST pass them to agents in step 6d.
-      DO NOT proceed to 6d until team_tasks_add succeeds.
-
-   **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, all context file paths, the task IDs for their tasks, and these instructions:
-      - call team_claim with the task ID before starting each task
-      - call team_tasks_complete with the task ID after finishing each task
-      - send results to lead via team_message when all done or blocked
-      \`\`\`
-      team_spawn name:"back" agent:"back-engineer" prompt:"..."
-      (wait for result)
-      team_spawn name:"front" agent:"front-engineer" prompt:"..."
-      (wait for result)
-      team_spawn name:"infra" agent:"infra-engineer" prompt:"..."
-      (wait for result)
-      \`\`\`
-
-   **Step 6e.** After all spawns, 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,
-      then team_shutdown + team_merge for each. Fix any blockers reported.
-
-7. **Quality check**
-
-   Spawn quality engineer, wait for message back:
-   \`\`\`
-   team_spawn name:"quality" agent:"quality-engineer" prompt:"<task list, context files, run tests + build + lint + verify acceptance criteria, call team_claim/team_tasks_complete per task, send results to lead when done>"
-   \`\`\`
-   Wait for message → team_results → fix blockers → team_shutdown + team_merge
-
-8. **Mark tasks complete in openspec**
-
-   Update tasks.md: \`- [ ]\` → \`- [x]\` for each completed task.
-   Run \`rtk openspec status --change "<name>" --json\` to confirm.
-
-9. **Show status, then cleanup**
-
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive with \`/opsx-archive\`
-   - If paused: explain why and wait for guidance
-
-   Then run \`team_cleanup\`.
-
-**Guardrails**
-- 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 claim or complete tasks as lead — only subagents call team_claim and team_tasks_complete
-- 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 pass the task IDs returned by team_tasks_add to each agent's spawn prompt
-- ALWAYS spawn one at a time, waiting for each result before the next (avoids worktree contention)
-- 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
-`
-
-// 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 __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// Our owned apply command and skill, stored in the package content folder.
+// After openspec init generates its versions, we delete them and copy ours in.
+const OUR_CONTENT_DIR = path.resolve(__dirname, '../../content')
+
+const APPLY_OVERRIDES = [
+  {
+    src: path.join(OUR_CONTENT_DIR, '.opencode', 'commands', 'opsx-apply.md'),
+    dest: path.join('.opencode', 'commands', 'opsx-apply.md'),
+  },
+  {
+    src: path.join(OUR_CONTENT_DIR, '.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
+    dest: path.join('.opencode', 'skills', 'openspec-apply-change', 'SKILL.md'),
+  },
 ]
 
-function patchOpensxApply(filePath) {
-  if (!fs.existsSync(filePath)) return false
-
-  const content = fs.readFileSync(filePath, 'utf8')
-  const lines = content.split('\n')
-
-  // 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
-    }
-  }
-
-  if (cutLine === -1) return false // Pattern not found, skip
-
-  const preamble = lines.slice(0, cutLine).join('\n').trimEnd()
-  const patched = preamble + '\n\n' + ENSEMBLE_PATCH
-  fs.writeFileSync(filePath, patched, 'utf8')
-  return true
-}
-
 export async function initOpenspec() {
   header('Step 6, Initializing OpenSpec')
 
@@ -144,19 +40,15 @@ 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) {
+  // Replace the openspec-generated apply command and skill with our ensemble-native versions.
+  // The generated files implement tasks directly (solo agent). Ours delegate to the ensemble team.
+  for (const { src, dest } of APPLY_OVERRIDES) {
+    const destAbs = path.join(process.cwd(), dest)
     try {
-      const patched = patchOpensxApply(target)
-      if (patched) success(`Patched ${path.relative(process.cwd(), target)} for ensemble`)
+      await fse.copy(src, destAbs, { overwrite: true })
+      success(`Installed ensemble apply → ${dest}`)
     } catch (err) {
-      warn(`Could not patch ${path.relative(process.cwd(), target)}: ${err.message}`)
+      warn(`Could not install ${dest}: ${err.message}`)
     }
   }
 }
-

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
     },
   })
 }