SDD Multi-Agent OpenCode

Spec-Driven Development workflow kit for OpenCode with five core commands, CLI wrappers, multi-agent orchestration, and configurable model routing.

Inspired by spec-kit-command-cursor and mattpocock/skills, rebuilt from scratch for OpenCode's multi-agent architecture.

Layering

This repo is the SDD workflow layer. For base agent behavior, CLI-first scaffolding, status verification, and context-window management, use opencode-agent-rules first.

opencode-agent-rules        # base behavior + context/compaction policy
        ↓
sdd-multiagent-opencode     # SDD commands, agents, skills, templates, CLI wrappers
        ↓
external UI skills          # impeccable, taste, nothing-design, etc.

What's Different from the Original

Multi-Agent Architecture

All models are configurable via ~/.config/opencode/sdd-multiagent-opencode.json. Edit this file to change which model each agent uses. See Model Settings below.

Quick Start

Plugin Install (Recommended)

Add to your opencode.json (global or project-level):

{
  "plugin": [
    "@tudeorangbiasa/sdd-multiagent-opencode@latest"
  ]
}

Restart OpenCode. The plugin auto-registers skills, agents, commands, and internal plugins (model router, auto reasoning).

To pin a specific version:

{
  "plugin": [
    "@tudeorangbiasa/sdd-multiagent-opencode@0.5.0"
  ]
}

Verify by asking: "What SDD commands do you have?"

Why npm instead of GitHub? GitHub installs pull the latest commit which may include beta/unstable changes. npm packages are versioned and tested before publish, so you get a stable, mature release.

npx Install (Fallback)

For projects that prefer local files instead of a plugin:

cd your-project
npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init

Flags:

npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init              # Install everything
npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init --sdd-only   # SDD workflow only
npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init --rules-only # Base rules only
npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init --force      # Overwrite existing
npx -y -p @tudeorangbiasa/sdd-multiagent-opencode sdd-opencode init --dry-run    # Preview only

Updating

Plugin installs from npm update when you bump the version in your opencode.json and restart OpenCode. Check npm for the latest version.

For npx installs, run the installer again with --force to overwrite existing files.

Command Flow Guide

See GUIDE.md for the practical command flow.

Default workflow:

/sdd-construct  # initialize SDD workflow for a new or existing project (one-time)
/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
/sdd-quick      # lightweight cosmetic/config fix (~200 tokens via CLI wrapper)

Most work starts with /sdd-propose, then /sdd-apply, then /sdd-ship. Use /sdd-explore first only when the problem is unclear. Use /sdd-construct once per project to set up the spine.

Model Settings

SDD model and reasoning routing are configured in one global plugin config:

~/.config/opencode/sdd-multiagent-opencode.json

Edit this file to change which model each SDD agent uses. This package does not read per-project model or reasoning profile files at runtime.

⚠️ 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.

Provider Prefix Format

OpenCode supports 75+ providers. Model IDs use the format provider_id/model_id. Run opencode provider list for the full list on your system.

OpenAI (Frontier Models)

Best for orchestration and complex planning. Access via OpenAI API key.

Anthropic (Claude)

Access via Anthropic API key or OpenCode Zen.

OpenCode Zen (Curated Paid Models)

Models tested and verified by the OpenCode team. Access via OpenCode API key.

OpenCode Go (Budget Subscription — $10/month)

Curated open-source models with generous limits. Best value for planner/orchestrator on a budget.

DeepSeek V4 Pro vs MiniMax M2.7: Based on Artificial Analysis benchmarks, DeepSeek V4 Pro scores higher on intelligence index, has 1M context (vs 205K), MIT license (vs non-commercial), and is more recent. Recommended for orchestrator/planner over MiniMax M2.7.

Free-Tier Models

Models available at no cost via OpenCode Zen. Run opencode models opencode | grep "free" to check current availability — free models change frequently.

Current free models (verified):

⚠️ Free models are limited-time offers and may be removed or rotated without notice. Not recommended for production SDD workflows. Use opencode models opencode | grep "free" to verify what's currently available.

Alternative free options via other providers:

• groq/qwen-qwq — Qwen QwQ 32B via Groq (free tier available)
• groq/llama-3.3-70b-versatile — Llama 3.3 70B via Groq
• openrouter/deepseek-r1-free — DeepSeek R1 via OpenRouter (free)

Default Config

Recommended starting configuration (orchestrator/planner use OpenAI GPT 5.5, others use free):

{
  "model": "openai/gpt-5.5",
  "small_model": "opencode/deepseek-v4-flash-free",
  "agent": {
    "sdd-orchestrator": { "model": "openai/gpt-5.5" },
    "sdd-planner": { "model": "openai/gpt-5.5" },
    "sdd-explorer": { "model": "opencode/deepseek-v4-flash-free" },
    "sdd-implementer": { "model": "opencode/deepseek-v4-flash-free" },
    "sdd-verifier": { "model": "opencode/qwen3.6-plus-free" },
    "sdd-reviewer": { "model": "opencode/qwen3.6-plus-free" },
    "sdd-quick": { "model": "opencode/qwen3.6-plus-free" }
  },
  "reasoning": {
    "default": "low",
    "applyProviderOptions": true,
    "resetToolOverrideAfterNextRequest": true,
    "agents": {
      "sdd-orchestrator": "high",
      "sdd-planner": "high",
      "sdd-explorer": "low",
      "sdd-implementer": "medium",
      "sdd-verifier": "medium",
      "sdd-reviewer": "medium",
      "sdd-quick": "low"
    },
    "commands": {
      "sdd-explore": "medium",
      "sdd-propose": "high",
      "sdd-apply": "medium",
      "sdd-ship": "medium",
      "sdd-quick": "low"
    }
  }
}

Budget alternative (OpenCode Go $10/month):

{
  "model": "opencode-go/deepseek-v4-pro",
  "small_model": "opencode/deepseek-v4-flash-free",
  "agent": {
    "sdd-orchestrator": { "model": "opencode-go/deepseek-v4-pro" },
    "sdd-planner": { "model": "opencode-go/deepseek-v4-pro" },
    "sdd-explorer": { "model": "opencode/deepseek-v4-flash-free" },
    "sdd-implementer": { "model": "opencode/deepseek-v4-flash-free" },
    "sdd-verifier": { "model": "opencode-go/kimi-k2.6" },
    "sdd-reviewer": { "model": "opencode/qwen3.6-plus-free" },
    "sdd-quick": { "model": "opencode-go/qwen3.6-plus" }
  }
}

Model routing rationale:

• Orchestrator → GPT 5.5 (OpenAI) or DeepSeek V4 Pro (Go): needs strongest reasoning for DAG coordination, deadlock detection
• Planner → GPT 5.5 (OpenAI) or DeepSeek V4 Pro (Go): 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 → Qwen3.6 Plus free: multimodal for Chrome DevTools screenshots
• Reviewer → Qwen3.6 Plus free: available free-tier review model
• Quick → Qwen3.6 Plus free: minimal prompt for small cosmetic/config edits (~200 tokens)

.opencode/plugins/sdd-model-router.js reads ~/.config/opencode/sdd-multiagent-opencode.json at OpenCode startup and applies the model settings. Restart OpenCode after editing it.

Important: Do NOT set SDD agent models in opencode.json. All SDD model routing goes through ~/.config/opencode/sdd-multiagent-opencode.json.

Auto Reasoning

The plugin installs .opencode/plugins/sdd-auto-reasoning.js and reads the reasoning section from ~/.config/opencode/sdd-multiagent-opencode.json.

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:

{
  "default": "low",
  "agents": {
    "sdd-orchestrator": "high",
    "sdd-planner": "high",
    "sdd-implementer": "medium",
    "sdd-reviewer": "medium",
    "sdd-quick": "low"
  }
}

Restart OpenCode after editing ~/.config/opencode/sdd-multiagent-opencode.json.

Manual Install

If you prefer local files over a plugin:

git clone https://github.com/TudeOrangBiasa/opencode-agent-rules.git
git clone https://github.com/TudeOrangBiasa/sdd-multiagent-opencode.git

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/
cp -r sdd-multiagent-opencode/.opencode /your-project/
cp -r sdd-multiagent-opencode/.sdd /your-project/
cp sdd-multiagent-opencode/opencode.json /your-project/

Merge the agent and permission sections from opencode.json into your project's opencode.json.

Usage

See GUIDE.md for the practical flow.

/sdd-construct                              # one-time project initialization
/sdd-propose auth-reset "add secure password reset by email"
/sdd-apply auth-reset
/sdd-ship auth-reset

If the problem is unclear, start with exploration:

/sdd-explore "admin UI feels messy, find reusable component opportunities"

For small cosmetic fixes:

/sdd-quick "fix typo: succesful -> successful"
/sdd-quick "rename isLoading to isFetching in auth.ts"

Commands

Project Structure

.opencode/
├── agents/
│   ├── 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/
│   ├── sdd-construct.md      # /sdd-construct
│   ├── sdd-explore.md        # /sdd-explore
│   ├── sdd-propose.md        # /sdd-propose
│   ├── sdd-apply.md          # /sdd-apply
│   ├── sdd-ship.md           # /sdd-ship
│   └── sdd-quick.md          # /sdd-quick
└── skills/
    ├── sdd-research/SKILL.md
    ├── sdd-planning/SKILL.md
    ├── sdd-implementation/SKILL.md
    └── sdd-audit/SKILL.md

.sdd/
├── config.json               # Project configuration
├── project-profile.json      # Stack and skill routing config
└── templates/                # Document templates
    ├── proposal-template.md
    ├── spec-template.md
    ├── design-template.md
    ├── tasks-template.md
    ├── progress-template.md
    └── verification-template.md

bin/
├── sdd-opencode.js           # Main installer CLI
└── sdd-quick.js              # Quick fix CLI wrapper (deterministic checks)

specs/
├── active/
│   └── <change-id>/
│       ├── proposal.md
│       ├── spec.md
│       ├── design.md
│       ├── tasks.md
│       ├── progress.md
│       └── verification.md
├── QUICKFIX_LOG.md           # Ledger for /sdd-quick changes
└── QUICKFIX_LOG_ARCHIVE.md   # Archived ledger entries

Global runtime config lives at ~/.config/opencode/sdd-multiagent-opencode.json.

Workflows

New Project Setup

/sdd-construct  # one-time: detect stack, grill vision, scaffold config, create CONTEXT.md

Feature Development

/sdd-propose -> /sdd-apply -> /sdd-ship

Unclear Changes

/sdd-explore -> /sdd-propose -> /sdd-apply -> /sdd-ship

Quick Fixes

/sdd-quick "fix typo in error message"  # ~200 tokens, CLI-verified

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.

CLI Wrapper: /sdd-quick Architecture

The /sdd-quick command uses a hybrid CLI + LLM architecture to minimize token cost (~200 tokens vs ~1000 for all-LLM):

CLI (0 tokens) → Phase 1a: Keyword scan → PASS/FAIL
  ↓ (if ambiguous)
LLM (~50 tokens) → Phase 1b: Context-aware classification
  ↓
CLI (0 tokens) → Phase 2: Pre-flight (lock, grep, string delta)
  ↓
LLM (~150 tokens) → Phase 3: Edit (full file return for < 500 lines)
  ↓
CLI (0 tokens) → Phase 4: Post-flight (actual diff, lint, typecheck, auto-revert)
  ↓
CLI (0 tokens) → Phase 5: Atomic ledger append

The CLI wrapper (bin/sdd-quick.js) handles deterministic checks:

• Phase 1a: Regex-based keyword scan (operators, control flow, contract paths)
• Phase 2: Lock file management, cross-file grep scan, string length delta
• Phase 4: Post-flight verification — actual diff check, lint/typecheck, auto-revert
• Phase 5: Atomic ledger append via temp file + rename, automatic archiving

The LLM is only invoked for:

• Phase 1b: Context-aware classification (if keywords found in comments/strings)
• Phase 3: The actual edit (full file return or search-replace blocks)

Tools Integration

codebase-memory-mcp

Used by sdd-explorer and sdd-implementer for:

• search_graph — find functions, classes, routes by natural language
• trace_path — trace call chains and dependencies
• get_code_snippet — read specific function/class source code
• query_graph — run Cypher queries for complex patterns
• get_architecture — high-level project structure

exa_web_search_exa

Used by sdd-explorer when external research is relevant:

• External pattern research
• Documentation lookup
• Technology comparison

chrome-devtools

Used by sdd-verifier for:

• chrome-devtools_navigate_page — navigate to feature pages
• chrome-devtools_take_screenshot — capture visual state
• chrome-devtools_take_snapshot — analyze DOM structure
• chrome-devtools_list_console_messages — check for errors

License

MIT