@tudeorangbiasa/sdd-multiagent-opencode 0.1.3 → 0.2.0

package/GUIDE.md

@@ -0,0 +1,128 @@
+# SDD Multi-Agent OpenCode Guide
+
+This kit exposes one small workflow for OpenCode:
+
+```text
+/sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
+```
+
+It is inspired by spec-driven development, but it is not a port of another tool. The goal is to make OpenCode safer on real projects by separating investigation, planning, implementation, and final verification.
+
+## Commands
+
+| Command | Purpose | Writes Code? |
+|---------|---------|--------------|
+| `/sdd-explore` | Investigate unclear ideas, bugs, or code areas | No |
+| `/sdd-propose` | Create one focused change plan | No |
+| `/sdd-apply` | Implement an approved change | Yes |
+| `/sdd-ship` | Verify readiness before merge/release | No, unless explicitly asked |
+
+## Default Flow
+
+```text
+/sdd-propose change-id "what should change"
+    -> review specs/active/change-id/
+/sdd-apply change-id
+/sdd-ship change-id
+```
+
+Use `/sdd-explore` first only when the problem is unclear.
+
+## When To Use Each Command
+
+### `/sdd-explore`
+
+Use this when you need understanding before deciding what to build.
+
+```text
+/sdd-explore "admin UI feels messy, find reusable component opportunities"
+/sdd-explore invoice-delete "why invoice delete sometimes fails"
+```
+
+This command should return findings, options, and a recommended next `/sdd-propose` command. It must not implement code.
+
+### `/sdd-propose`
+
+Use this when you know the change you want.
+
+```text
+/sdd-propose ui-admin-components "modularize admin UI into reusable components"
+/sdd-propose "add password reset flow"
+```
+
+It creates:
+
+```text
+specs/active/<change-id>/
+├── proposal.md
+├── spec.md
+├── design.md
+├── tasks.md
+└── progress.md        optional for large changes
+```
+
+Review these files before applying. This is the agreement point.
+
+### `/sdd-apply`
+
+Use this after the proposal is accepted.
+
+```text
+/sdd-apply ui-admin-components
+```
+
+It reads the artifacts, implements `tasks.md`, updates checkboxes, and runs targeted verification when possible.
+
+For large changes, it uses `progress.md` as a checkpoint so work can resume without relying on chat history. If tasks touch disjoint files, it can run safe batches in parallel through subagents; otherwise it runs sequentially.
+
+### `/sdd-ship`
+
+Use this before calling the change done.
+
+```text
+/sdd-ship ui-admin-components
+```
+
+It audits the implementation against the artifacts and writes:
+
+```text
+specs/active/<change-id>/verification.md
+```
+
+## Example: New Feature
+
+```text
+/sdd-propose auth-reset "add secure password reset by email"
+/sdd-apply auth-reset
+/sdd-ship auth-reset
+```
+
+## Example: Bug Fix
+
+```text
+/sdd-explore invoice-delete "deleting invoices sometimes fails in production"
+/sdd-propose invoice-delete "fix invoice delete failure with regression coverage"
+/sdd-apply invoice-delete
+/sdd-ship invoice-delete
+```
+
+## Example: Refactor
+
+```text
+/sdd-explore admin-ui "check whether admin UI is modular and reusable"
+/sdd-propose admin-ui-components "extract reusable admin layout and form components"
+/sdd-apply admin-ui-components
+/sdd-ship admin-ui-components
+```
+
+## Design Principles
+
+- Four commands only by default.
+- No fake flags like `--deep` or `--until-finish`.
+- No source code changes during explore/propose.
+- One change folder per unit of work.
+- Planning artifacts are compact and reviewable.
+- Proposals must cite real project files or clearly say what was not found.
+- Long-running apply work must checkpoint to `progress.md`.
+- Parallel execution is a capability inside `/sdd-apply`, not a separate command.
+- Verification is a first-class step, not a vague final message.

package/README.md

@@ -1,6 +1,6 @@
 # SDD Multi-Agent OpenCode
 
-Spec-Driven Development framework for OpenCode with multi-agent orchestration, DAG-based parallel execution, and free-tier model optimization.
+Spec-Driven Development workflow kit for OpenCode with four core commands, multi-agent support, and configurable model routing.
 
 Inspired by [spec-kit-command-cursor](https://github.com/madebyaris/spec-kit-command-cursor), rebuilt from scratch for OpenCode's multi-agent architecture.
 
@@ -20,38 +20,65 @@ external UI skills          # impeccable, taste, nothing-design, etc.
 
 | Aspect | Original (Cursor) | This (OpenCode) |
 |--------|-------------------|-----------------|
-| **Models** | Single `inherit` model | 4 models optimized per agent role |
-| **Parallel Execution** | Cursor `is_background: true` | OpenCode subagent spawning via Task tool |
+| **Models** | Single `inherit` model | Configurable per-agent routing |
+| **Parallel Execution** | Cursor `is_background: true` | Safe subagent spawning with file conflict detection |
 | **Codebase Search** | grep/glob | `codebase-memory-mcp` graph queries |
 | **Web Research** | Cursor web search | `exa_web_search_exa` |
 | **Visual Verification** | N/A | Chrome DevTools + Qwen (image-capable) |
 | **Hooks** | `hooks.json` | Plugin JS/TS with event system |
-| **Cost** | Per-token billing | All free-tier models |
+| **Commands** | 15+ slash commands | 4 core commands: explore, propose, apply, ship |
+| **Cost** | Per-token billing | Free-tier optimized with paid model routing |
 
 ## Multi-Agent Architecture
 
-| Agent | Model | Role |
-|-------|-------|------|
-| **sdd-orchestrator** | `opencode/minimax-m2.5-free` | DAG scheduling, conflict detection, deadlock handling |
-| **sdd-planner** | `opencode/qwen3.6-plus-free` | Architecture design, technical planning |
-| **sdd-explorer** | `opencode/deepseek-v4-flash-free` | Codebase discovery (readonly) |
-| **sdd-implementer** | `opencode/deepseek-v4-flash-free` | Code generation (high token usage) |
-| **sdd-verifier** | `opencode/qwen3.6-plus-free` | Completeness check + visual/UI verification (Chrome DevTools) |
-| **sdd-reviewer** | `opencode/minimax-m2.5-free` | Code review (security, performance, spec compliance) |
+| Agent | Default Model | Role |
+|-------|--------------|------|
+| **sdd-orchestrator** | configurable | DAG scheduling, conflict detection, deadlock handling |
+| **sdd-planner** | configurable | Architecture design, technical planning |
+| **sdd-explorer** | configurable | Codebase discovery (readonly) |
+| **sdd-implementer** | configurable | Code generation (high token usage) |
+| **sdd-verifier** | configurable | Completeness check + visual/UI verification (Chrome DevTools) |
+| **sdd-reviewer** | configurable | Code review (security, performance, spec compliance) |
+
+**All models are configurable** via `.sdd/model-profile.json`. Edit this file to change which model each agent uses. See [Model Settings](#model-settings) below.
 
 ## Quick Start
 
-### npx Install (Recommended)
+### Plugin Install (Recommended)
+
+Add to your `opencode.json` (global or project-level):
+
+```json
+{
+  "plugin": [
+    "@tudeorangbiasa/sdd-multiagent-opencode@git+https://github.com/TudeOrangBiasa/sdd-multiagent-opencode.git"
+  ]
+}
+```
+
+Restart OpenCode. The plugin auto-registers skills, agents, commands, and internal plugins (model router, auto reasoning).
+
+To pin a version:
+
+```json
+{
+  "plugin": [
+    "@tudeorangbiasa/sdd-multiagent-opencode@git+https://github.com/TudeOrangBiasa/sdd-multiagent-opencode.git#v0.2.0"
+  ]
+}
+```
+
+Verify by asking: "What SDD commands do you have?"
+
+### npx Install (Fallback)
+
+For projects that prefer local files instead of a plugin:
 
 ```bash
 cd your-project
 npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init
 ```
 
-This installs both:
-- Base OpenCode agent rules (verification, CLI-first, context budget)
-- SDD multi-agent workflow (commands, agents, skills, templates)
-
 **Flags:**
 ```bash
 npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init              # Install everything
@@ -61,19 +88,72 @@ npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init --force
 npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init --dry-run    # Preview only
 ```
 
+### Updating
+
+Plugin installs update automatically when OpenCode restarts and fetches the latest git commit. To pin a stable version, use a tag:
+
+```json
+"@tudeorangbiasa/sdd-multiagent-opencode@git+https://github.com/TudeOrangBiasa/sdd-multiagent-opencode.git#v0.2.0"
+```
+
+For npx installs, run the installer again with `--force` to overwrite existing files.
+
+## Command Flow Guide
+
+See [GUIDE.md](GUIDE.md) for the practical command flow.
+
+Default workflow:
+
+```text
+/sdd-explore   # investigate unclear ideas, bugs, or code areas; no code changes
+/sdd-propose   # create proposal.md, spec.md, design.md, tasks.md; no code changes
+/sdd-apply     # implement an approved change
+/sdd-ship      # final verification and readiness review
+```
+
+Most work starts with `/sdd-propose`, then `/sdd-apply`, then `/sdd-ship`. Use `/sdd-explore` first only when the problem is unclear.
+
 ### Model Settings
 
 The installer creates `.sdd/model-profile.json`. Edit this file to change which model each OpenCode agent uses.
 
-Default profile avoids paid GPT models:
+**⚠️ Requirement:** SDD works best with at least **ONE paid/subscription model** for orchestrator and planner. These roles need strong reasoning + multimodal capabilities that free models lack.
+
+**Subscription options:**
+- **OpenCode Go** ($10/month) — GLM 5.1, Kimi K2.5, MiniMax M2.5/M2.7
+- **Kimi Moderato** — Kimi K2.6 with vision support
+- **OpenAI Plus** — GPT 5.5 with reasoning and multimodal
+- **GLM Lite** — GLM 5.1 with strong reasoning
+- **OpenRouter** — Access to frontier reasoning models
+
+**Recommended paid models for SDD:**
+
+| Model | Best For | Notes |
+|-------|----------|-------|
+| `opencode/gpt-5.5` | Orchestrator, Planner | Strongest reasoning + multimodal |
+| `opencode/claude-sonnet-4-5` | Planner, Reviewer | Excellent code understanding |
+| `opencode/claude-opus-4-5` | Planner (complex) | Maximum capability for architecture |
+| `opencode/kimi-k2.6` | Verifier, Planner | Strong reasoning + vision support |
+| `opencode/glm-5.1` | Orchestrator, Planner | Strong reasoning alternative |
+
+**Free-tier fallback** (limited capability — not recommended for production):
+
+| Model | Best For | Limitations |
+|-------|----------|-------------|
+| `opencode/qwen3.6-plus-free` | General fallback | Limited multimodal |
+| `opencode/deepseek-v4-flash-free` | Explorer, Implementer | Code gen only, no reasoning |
+| `opencode/minimax-m2.5-free` | Reviewer, Orchestrator | Basic coordination |
+| `opencode/big-pickle` | Explorer | Limited-time free |
+
+**Default profile** (orchestrator/planner require paid, others use free):
 
 ```json
 {
-  "defaultPrimary": "opencode/minimax-m2.5-free",
+  "defaultPrimary": "opencode/gpt-5.5",
   "small": "opencode/deepseek-v4-flash-free",
   "agents": {
-    "sdd-orchestrator": "opencode/minimax-m2.5-free",
-    "sdd-planner": "opencode/qwen3.6-plus-free",
+    "sdd-orchestrator": "opencode/gpt-5.5",
+    "sdd-planner": "opencode/gpt-5.5",
     "sdd-explorer": "opencode/deepseek-v4-flash-free",
     "sdd-implementer": "opencode/deepseek-v4-flash-free",
     "sdd-verifier": "opencode/qwen3.6-plus-free",
@@ -82,29 +162,51 @@ Default profile avoids paid GPT models:
 }
 ```
 
-`.opencode/plugins/sdd-model-router.js` reads this file at OpenCode startup and applies the model settings. Restart OpenCode after editing it.
+**Model routing rationale:**
+- **Orchestrator** → GPT 5.5 (paid): needs strongest reasoning for DAG coordination, deadlock detection
+- **Planner** → GPT 5.5 (paid): needs maximum reasoning for architecture design, risk assessment
+- **Explorer** → DeepSeek free: fast readonly exploration, token-efficient
+- **Implementer** → DeepSeek free: code generation, handles high token usage
+- **Verifier** → Qwen free: multimodal for Chrome DevTools screenshots
+- **Reviewer** → MiniMax free: structured code review output
 
-### 1. Install (Manual)
+`.opencode/plugins/sdd-model-router.js` reads this file at OpenCode startup and applies the model settings. **Restart OpenCode after editing it.**
 
-#### Option A: Using Commands (Recommended)
+**Important:** Do NOT set models in `opencode.json` — they will be ignored. All model routing goes through `model-profile.json`.
 
-If you have OpenCode running, you can use the init commands:
+### Auto Reasoning
 
-```
-/init-rules   # Install base agent rules first
-/init-sdd    # Install SDD workflow layer
+The installer also creates `.sdd/reasoning-profile.json` and installs `.opencode/plugins/sdd-auto-reasoning.js`.
+
+The plugin reverse-engineers the behavior of `@howaboua/pi-auto-reasoning-tool` for OpenCode:
+- sets reasoning effort automatically per agent and command
+- exposes `change_reasoning` when `@opencode-ai/plugin` is available
+- resets tool overrides after the next model request by default
+
+Default routing:
+
+```json
+{
+  "default": "low",
+  "agents": {
+    "sdd-orchestrator": "high",
+    "sdd-planner": "high",
+    "sdd-implementer": "medium",
+    "sdd-reviewer": "medium"
+  }
+}
 ```
 
-#### Option B: Manual Copy
+Restart OpenCode after editing `.sdd/reasoning-profile.json`.
+
+### Manual Install
+
+If you prefer local files over a plugin:
 
 ```bash
-# Recommended: install base agent rules first
 git clone https://github.com/TudeOrangBiasa/opencode-agent-rules.git
-
-# Clone into your project
 git clone https://github.com/TudeOrangBiasa/sdd-multiagent-opencode.git
 
-# Or copy the .opencode/ and .sdd/ directories into your project
 cp opencode-agent-rules/AGENTS.md /your-project/
 cp -r opencode-agent-rules/.opencode/rules /your-project/.opencode/
 cp -r opencode-agent-rules/.opencode/plugins /your-project/.opencode/
@@ -113,158 +215,92 @@ cp -r sdd-multiagent-opencode/.sdd /your-project/
 cp sdd-multiagent-opencode/opencode.json /your-project/
 ```
 
-### 2. Configure
-
 Merge the `agent` and `permission` sections from `opencode.json` into your project's `opencode.json`.
 
-### 3. Update Project Profile
+## Usage
 
-Edit `.sdd/project-profile.json` with your stack:
-- framework (e.g., "next", "react", "express")
-- language (e.g., "typescript", "javascript")
-- packageManager (e.g., "pnpm", "npm", "yarn")
-- commands (dev, build, test, lint)
+See [GUIDE.md](GUIDE.md) for the practical flow.
 
-### 4. Use
+```text
+/sdd-propose auth-reset "add secure password reset by email"
+/sdd-apply auth-reset
+/sdd-ship auth-reset
+```
 
-```bash
-# Quick planning (80% of features)
-/brief user-auth JWT authentication with login/logout
-
-# Full planning (complex features)
-/research database-engine Best database for our use case --deep
-/specify user-auth User authentication with login, logout, password reset
-/plan user-auth
-/tasks user-auth
-/implement user-auth
-
-# TDD workflow (test-driven development)
-/tasks user-auth --tdd
-/implement user-auth --tdd
-
-# Full project roadmap
-/sdd-full-plan blog-platform Full-featured blog with CMS and analytics
-/execute-parallel blog-platform --until-finish
-
-# Audit
-/audit user-auth
+If the problem is unclear, start with exploration:
+
+```text
+/sdd-explore "admin UI feels messy, find reusable component opportunities"
 ```
 
 ## Commands
 
-| Command | Purpose | Output |
-|---------|---------|--------|
-| `/init-rules` | Install base agent rules | Base rules files |
-| `/init-sdd` | Install SDD workflow | SDD files + project profile |
-| `/brief` | Lightweight feature brief (~30 min) | `feature-brief.md` |
-| `/research` | Pattern investigation (supports `--deep`) | `research.md` |
-| `/specify` | Detailed requirements | `spec.md` |
-| `/plan` | Technical architecture | `plan.md` |
-| `/tasks` | Task breakdown | `tasks.md` |
-| `/implement` | Execute implementation with todo tracking | Code + `todo-list.md` |
-| `/sdd-full-plan` | Complete project roadmap | `roadmap.json` + tasks |
-| `/execute-parallel` | Parallel DAG execution | Updated roadmap |
-| `/execute-task` | Single task execution | Updated roadmap |
-| `/evolve` | Update specs with discoveries | Updated specs |
-| `/refine` | Iterate on specs through discussion | Updated docs |
-| `/upgrade` | Brief → Full SDD planning | Full SDD docs |
-| `/audit` | Compare implementation against specs | Audit report |
-| `/generate-prd` | PRD via Socratic questions | `full-prd.md` |
-| `/generate-rules` | Auto-generate coding rules | Rule files |
-| `/grill-me` | Clarify product requirements | Clarified brief |
+| Command | Purpose | Writes Code? |
+|---------|---------|--------------|
+| `/sdd-explore` | Investigate unclear ideas, bugs, or code areas | No |
+| `/sdd-propose` | Create one focused change plan | No |
+| `/sdd-apply` | Implement an approved change | Yes |
+| `/sdd-ship` | Final verification and readiness review | No, unless explicitly asked |
 
 ## Project Structure
 
 ```
 .opencode/
-├── opencode.json          # Agent configs, permissions, model assignments
 ├── agents/
-│   ├── sdd-orchestrator.md   # DAG coordinator (GPT 5.5)
-│   ├── sdd-planner.md        # Architecture designer (GPT 5.5)
-│   ├── sdd-explorer.md       # Codebase investigator (DeepSeek)
-│   ├── sdd-implementer.md    # Code generator (DeepSeek)
-│   ├── sdd-verifier.md       # Completeness checker (Qwen + Chrome)
-│   └── sdd-reviewer.md       # Code reviewer (MiniMax)
+│   ├── sdd-orchestrator.md   # Multi-agent coordination internals
+│   ├── sdd-planner.md        # Proposal/spec/design/tasks planning
+│   ├── sdd-explorer.md       # Readonly codebase investigation
+│   ├── sdd-implementer.md    # Approved implementation work
+│   ├── sdd-verifier.md       # Completeness and UI verification
+│   └── sdd-reviewer.md       # Final review and readiness checks
 ├── commands/
-│   ├── brief.md              # /brief
-│   ├── research.md           # /research
-│   ├── specify.md            # /specify
-│   ├── plan.md               # /plan
-│   ├── tasks.md              # /tasks
-│   ├── implement.md          # /implement
-│   ├── sdd-full-plan.md      # /sdd-full-plan
-│   ├── execute-parallel.md   # /execute-parallel
-│   ├── execute-task.md       # /execute-task
-│   ├── evolve.md             # /evolve
-│   ├── refine.md             # /refine
-│   ├── upgrade.md            # /upgrade
-│   ├── audit.md              # /audit
-│   ├── generate-prd.md       # /generate-prd
-│   └── generate-rules.md     # /generate-rules
+│   ├── sdd-explore.md        # /sdd-explore
+│   ├── sdd-propose.md        # /sdd-propose
+│   ├── sdd-apply.md          # /sdd-apply
+│   └── sdd-ship.md           # /sdd-ship
 └── skills/
     ├── sdd-research/SKILL.md
     ├── sdd-planning/SKILL.md
     ├── sdd-implementation/SKILL.md
-    ├── sdd-audit/SKILL.md
-    └── sdd-evolve/SKILL.md
+    └── sdd-audit/SKILL.md
 
 .sdd/
 ├── config.json               # Project configuration
 ├── project-profile.json      # Stack and skill routing config
 └── templates/                # Document templates
-    ├── feature-brief-v2.md
-    ├── spec-compact.md
-    ├── plan-compact.md
-    ├── tasks-compact.md
-    ├── research-compact.md
-    ├── todo-compact.md
-    ├── roadmap-template.json
-    └── roadmap-template.md
+    ├── proposal-template.md
+    ├── spec-template.md
+    ├── design-template.md
+    ├── tasks-template.md
+    ├── progress-template.md
+    └── verification-template.md
 
 specs/
-├── active/                   # Features in development
-├── backlog/                  # Future features
-├── completed/                # Delivered features
-└── todo-roadmap/             # Project roadmaps with DAG
+└── active/
+    └── <change-id>/
+        ├── proposal.md
+        ├── spec.md
+        ├── design.md
+        ├── tasks.md
+        ├── progress.md
+        └── verification.md
 ```
 
 ## Workflows
 
-### Quick Planning (80% of features)
-```
-/brief → /evolve → /refine → /implement
-```
-
-### Full Planning (complex features)
-```
-/research → /specify → /plan → /tasks → /implement
-```
-
-### Deep Research (unfamiliar domain)
-```
-/research --deep → /specify → /plan → /tasks → /implement
-```
+Most changes use:
 
-### Parallel Execution (project roadmap)
-```
-/sdd-full-plan → /execute-parallel --until-finish
+```text
+/sdd-propose -> /sdd-apply -> /sdd-ship
 ```
 
-### TDD Workflow (Test-Driven Development)
+Unclear changes use:
 
+```text
+/sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship
 ```
-/brief feature-x → /tasks feature-x --tdd → /implement feature-x --tdd
-```
-
-With `--tdd` flag:
-- `/tasks` generates TDD-specific tasks with test-first structure
-- `/implement` writes failing test → implements minimum code → verifies pass → refactors
 
-**Example:**
-```
-/tasks user-auth --tdd
-/implement user-auth --tdd
-```
+This kit intentionally avoids fake CLI flags such as `--deep` or `--until-finish`. If deeper research or parallel execution is needed, describe that in normal language and let the agent plan it explicitly.
 
 ## Tools Integration
 
@@ -277,11 +313,10 @@ Used by `sdd-explorer` and `sdd-implementer` for:
 - `get_architecture` — high-level project structure
 
 ### exa_web_search_exa
-Used by `sdd-explorer` and `sdd-research` skill for:
+Used by `sdd-explorer` when external research is relevant:
 - External pattern research
 - Documentation lookup
 - Technology comparison
-- Deep research mode (`--deep`)
 
 ### chrome-devtools
 Used by `sdd-verifier` for:

package/bin/sdd-opencode.js

@@ -260,6 +260,20 @@ function installSdd(ctx) {
     count++;
   }
 
+  const reasoningProfileDest = path.join(sddDir, "reasoning-profile.json");
+  const reasoningProfileTemplateSrc = path.join(
+    sddDir,
+    "templates",
+    "reasoning-profile-template.json"
+  );
+
+  if (fs.existsSync(reasoningProfileDest) && !ctx.force) {
+    ctx.skipped.push(".sdd/reasoning-profile.json (exists)");
+  } else if (fs.existsSync(reasoningProfileTemplateSrc)) {
+    copyFileSafe(reasoningProfileTemplateSrc, reasoningProfileDest, ctx);
+    count++;
+  }
+
   const specsDir = path.join(ctx.targetRoot, "specs");
   ensureDir(path.join(specsDir, "active"));
   ensureDir(path.join(specsDir, "backlog"));
@@ -303,16 +317,25 @@ function patchOpencodeJson(ctx) {
   if (fs.existsSync(pkgJsonPath)) {
     const pkgConfig = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
 
-    if (pkgConfig.model) {
-      targetConfig.model = pkgConfig.model;
-      ctx.installed.push("opencode.json (model patch)");
-    }
+    if (Array.isArray(pkgConfig.plugin)) {
+      if (!Array.isArray(targetConfig.plugin)) {
+        targetConfig.plugin = [];
+      }
 
-    if (pkgConfig.small_model) {
-      targetConfig.small_model = pkgConfig.small_model;
-      ctx.installed.push("opencode.json (small_model patch)");
+      for (const pluginEntry of pkgConfig.plugin) {
+        const key = JSON.stringify(pluginEntry);
+        const exists = targetConfig.plugin.some((existing) => JSON.stringify(existing) === key);
+        if (!exists) {
+          targetConfig.plugin.push(pluginEntry);
+          ctx.installed.push(`opencode.json (plugin: ${Array.isArray(pluginEntry) ? pluginEntry[0] : pluginEntry})`);
+        }
+      }
     }
 
+    // NOTE: model and small_model are NOT patched from opencode.json.
+    // Model routing is handled by .sdd/model-profile.json + sdd-model-router.js plugin.
+    // Users edit model-profile.json to change models — opencode.json models are ignored.
+
     if (pkgConfig.agents && !targetConfig.agents) {
       targetConfig.agents = pkgConfig.agents;
       ctx.installed.push("opencode.json (agents patch)");
@@ -331,6 +354,10 @@ function patchOpencodeJson(ctx) {
       targetConfig.permission = pkgConfig.permission;
       ctx.installed.push("opencode.json (permission patch)");
     }
+
+    // NOTE: model and small_model are NOT patched here.
+    // Model routing is handled by .sdd/model-profile.json + sdd-model-router.js plugin.
+    // Users should edit model-profile.json to change models, not opencode.json.
   }
 
   if (ctx.dryRun) {