opencode-swarm 2.1.0 → 2.1.2

package/README.md

@@ -1,161 +1,78 @@
 # OpenCode Swarm
 
-Architect-centric agentic swarm plugin for OpenCode. Hub-and-spoke orchestration with SME consultation, code generation, and QA review.
+![License](https://img.shields.io/badge/license-MIT-blue)
+![OpenCode Plugin](https://img.shields.io/badge/opencode-plugin-green)
+![Agentic Architecture](https://img.shields.io/badge/architecture-architect--centric-purple)
 
-## Overview
+**Architect-driven, multi-agent development for OpenCode.**  
+Design-first orchestration with domain-aware SMEs, heterogeneous model perspectives, production-grade code generation, and layered QA.
 
-OpenCode Swarm implements a multi-agent development pipeline where:
+OpenCode Swarm is built for engineers who want **structured reasoning, controlled delegation, and predictable outcomes**—not parallel agent noise.
 
-1. **Architect** (central orchestrator) analyzes requests and coordinates all agents
-2. **SME Agents** provide domain-specific technical expertise (serial execution)
-3. **Coder** implements unified specifications
-4. **QA Agents** (Security Reviewer + Auditor) validate code quality
-5. **Test Engineer** generates test cases for approved code
+---
 
-```
-User → Architect (analyze) → [SME Pool - serial] → Architect (collate)
-     → Coder → [QA: Security + Auditor] → Architect (triage) → Test
-```
+## Why OpenCode Swarm
 
-## Installation
+Most agent frameworks parallelize everything and hope coherence emerges later.  
+OpenCode Swarm enforces discipline:
 
-```bash
-bunx opencode-swarm install
-```
+- A single Architect owns analysis and decisions
+- Experts are consulted only when technically relevant
+- Agents execute serially for traceability
+- Security and correctness are validated before delivery
+- Different models can be assigned per role, introducing genuinely distinct perspectives
 
-Then start OpenCode:
+This design improves **accuracy, efficiency, and failure detection**, especially on complex or high-stakes tasks.
 
-```bash
-opencode
-```
-
-## Configuration
+---
 
-Edit `~/.config/opencode/opencode-swarm.json`:
-
-```json
-{
-  "preset": "hybrid",
-  "presets": {
-    "remote": {
-      "architect": { "model": "anthropic/claude-sonnet-4.5" },
-      "coder": { "model": "openai/gpt-5.2-codex" },
-      "_sme": { "model": "google/gemini-3-flash" },
-      "_qa": { "model": "google/gemini-3-flash" },
-      "test_engineer": { "model": "google/gemini-3-flash" }
-    },
-    "hybrid": {
-      "architect": { "model": "anthropic/claude-sonnet-4.5" },
-      "coder": { "model": "ollama/qwen3:72b" },
-      "_sme": { "model": "npu/qwen3:14b" },
-      "_qa": { "model": "npu/qwen3:14b" },
-      "test_engineer": { "model": "npu/qwen3:14b" }
-    }
-  },
-  "swarm_mode": "hybrid",
-  "gpu_url": "http://192.168.1.100:1234/v1",
-  "npu_url": "http://localhost:11435/v1",
-  "max_iterations": 5
-}
-```
+## Key Advantage: Heterogeneous Model Perspectives
 
-### Category Defaults
+OpenCode Swarm allows **per-role model selection** so that each cognitive function is optimized independently:
 
-Use `_sme` and `_qa` to set models for all agents in a category:
+- Architect → deep reasoning and synthesis
+- SMEs → domain recall and speed
+- Coder → implementation fidelity
+- QA → adversarial review and audit rigor
 
-```json
-{
-  "agents": {
-    "_sme": { "model": "npu/qwen3:14b" },
-    "_qa": { "model": "npu/qwen3:14b" }
-  }
-}
-```
+Using different models per role reduces correlated failure modes, increases early error detection, and mirrors how real engineering teams benefit from diverse expertise.
 
-To override a specific agent within a category:
+See: [docs/design-rationale.md](docs/design-rationale.md)
 
-```json
-{
-  "agents": {
-    "_sme": { "model": "npu/qwen3:14b" },
-    "sme_oracle": { "model": "ollama/qwen3:72b" }
-  }
-}
-```
+---
 
-### Custom Prompts
+## Architecture Overview
 
-Place custom prompts in `~/.config/opencode/opencode-swarm/`:
+OpenCode Swarm implements a hub-and-spoke pipeline with a single controlling Architect.
 
-- `{agent}.md` - Replace the default prompt entirely
-- `{agent}_append.md` - Append to the default prompt
-
-Example: `architect_append.md` to add custom instructions to the Architect.
-
-## Agents
-
-### Orchestrator
-
-| Agent | Role |
-|-------|------|
-| `architect` | Central orchestrator, coordinates all phases |
-
-### SME Specialists (Domain Experts)
-
-| Agent | Domain |
-|-------|--------|
-| `sme_windows` | Windows OS internals, registry, services |
-| `sme_powershell` | PowerShell scripting, cmdlets, modules |
-| `sme_python` | Python ecosystem, libraries, best practices |
-| `sme_oracle` | Oracle Database, SQL/PLSQL, administration |
-| `sme_network` | Networking, firewalls, DNS, TLS/SSL |
-| `sme_security` | STIG compliance, hardening, encryption |
-| `sme_linux` | Linux administration, systemd, packages |
-| `sme_vmware` | VMware vSphere, ESXi, PowerCLI |
-| `sme_azure` | Azure cloud services, Entra ID, ARM/Bicep |
-| `sme_active_directory` | Active Directory, LDAP, Group Policy |
-| `sme_ui_ux` | UI/UX design, interaction patterns |
-
-### Pipeline Agents
-
-| Agent | Role |
-|-------|------|
-| `coder` | Implements specifications, writes production code |
-| `security_reviewer` | Security vulnerability assessment |
-| `auditor` | Code correctness and quality review |
-| `test_engineer` | Test case and validation script generation |
-
-## Workflow Phases
-
-1. **ANALYZE** - Parse request, identify domains, create initial spec
-2. **SME_CONSULTATION** - Consult domain experts serially
-3. **COLLATE** - Synthesize SME outputs into unified spec
-4. **CODE** - Generate implementation
-5. **QA_REVIEW** - Security and quality review (parallel)
-6. **TRIAGE** - Approve, request revision, or block
-7. **TEST** - Generate tests for approved code
-
-## Delegation Rules
+```
+User → Architect (analysis)
+     → Reader (optional)
+     → Relevant SMEs (serial)
+     → Architect (spec synthesis)
+     → Coder
+     → Security Review → Audit
+     → Architect (triage)
+     → Test Engineer
+```
 
-The Architect enforces resource-aware delegation:
+See: [docs/architecture.md](docs/architecture.md)
 
-- **SME agents**: Execute serially (one at a time) to avoid overwhelming local inference
-- **QA agents**: May execute in parallel (independent analysis)
-- **Cross-category**: One agent per category may run simultaneously
+---
 
-## Tools
+## Installation
 
-| Tool | Description |
-|------|-------------|
-| `detect_domains` | Auto-detect SME domains from text |
-| `extract_code_blocks` | Extract and save code blocks to files |
+```json
+{
+  "plugin": ["opencode-swarm"]
+}
+```
 
-## Environment Variables
+```bash
+bunx opencode-swarm install
+```
 
-| Variable | Description |
-|----------|-------------|
-| `OPENCODE_SWARM_PRESET` | Override preset selection |
-| `OPENCODE_SWARM_DEBUG` | Enable debug logging (`1` to enable) |
+---
 
 ## License
 

package/dist/index.js

@@ -13866,55 +13866,57 @@ var ARCHITECT_PROMPT = `You are Architect - an AI coding orchestrator that coord
 @auditor - Code quality review, correctness verification
 @test_engineer - Test case generation and validation scripts
 
+**CRITICAL: @reader MUST be your FIRST delegation for code reviews**
+When asked to review, analyze, or examine any codebase:
+1. IMMEDIATELY delegate to @reader - do not read the code yourself
+2. Wait for @reader's summary
+3. Use that summary to decide which SMEs to consult
+4. Never skip @reader for code review tasks
+
 **Workflow**:
 
-## 1. Analyze (you do this)
-Parse request: explicit requirements + implicit needs.
-Identify which domains are relevant (usually 1-3, not all).
-Create initial specification.
+## 1. Analyze Request (you do this briefly)
+Parse what user wants. If it involves reviewing code \u2192 go directly to step 2.
+
+## 2. Reader FIRST (for any code review/analysis)
+"Delegating to @reader for codebase analysis..."
+- Send the codebase/files to @reader
+- Wait for summary response
+- Use summary to identify domains and issues
 
-## 2. SME Consultation (delegate only relevant SMEs, serially)
-For each relevant domain, delegate to @sme_* agent one at a time.
-Only consult SMEs for domains that actually apply to the task.
-Wait for each response before calling the next.
+## 3. SME Consultation (based on @reader's findings)
+Consult only SMEs for domains identified from @reader's summary.
+Usually 1-3 SMEs, not all 11. Wait for each response.
 
-## 3. Collate (you do this)
-Synthesize SME inputs into unified specification.
-Ensure clarity and completeness.
+## 4. Collate (you do this)
+Combine @reader summary + SME inputs into final review or specification.
 
-## 4. Code (delegate to @coder)
-Send unified specification to @coder.
-Wait for implementation.
+## 5. Code (delegate to @coder) - only if writing new code
+Send specification to @coder. Wait for implementation.
 
-## 5. QA Review (delegate serially)
-Send code to @security_reviewer, wait for response.
-Then send code to @auditor, wait for response.
+## 6. QA Review (delegate serially) - only if code was written
+@security_reviewer first, then @auditor.
 
-## 6. Triage (you do this)
-Review QA feedback and decide:
-- APPROVED \u2192 proceed to @test_engineer
-- REVISION_NEEDED \u2192 send revision plan to @coder, then repeat QA
-- BLOCKED \u2192 explain why and end
+## 7. Triage (you do this)
+APPROVED \u2192 @test_engineer | REVISION_NEEDED \u2192 @coder | BLOCKED \u2192 explain
 
-## 7. Test (delegate to @test_engineer)
-Send approved code to @test_engineer for test generation.
+## 8. Test (delegate to @test_engineer) - if approved
 
-**Using @reader**:
-- Delegate to @reader when you need to process large amounts of data
-- Use for: analyzing gitingest output, reviewing large files, summarizing codebases
-- @reader returns condensed summaries you can use for decision-making
+**Order of Operations for Code Review**:
+1. @reader (ALWAYS FIRST - analyzes codebase)
+2. @sme_* (only relevant domains based on @reader findings)
+3. Collate findings into review
 
-**Delegation Rules**:
-- All agents run serially (one at a time)
-- Wait for each agent response before calling the next
-- Only consult SMEs for domains relevant to the task (1-3 typically)
-- Reference paths/lines, don't paste entire files
-- Brief delegation notices: "Consulting @sme_powershell..."
+**Order of Operations for New Code**:
+1. @reader (if analyzing existing code first)
+2. @sme_* (relevant domains)
+3. @coder (implementation)
+4. @security_reviewer \u2192 @auditor (QA)
+5. @test_engineer (tests)
 
 **Communication**:
-- Be direct, no preamble or flattery
-- Don't ask user for confirmation between phases - proceed automatically
-- If original request is vague, ask one targeted question before starting
+- Be direct, no preamble
+- Don't ask for confirmation between phases
 - You analyze, collate, and triage. You never write code yourself.`;
 function createArchitectAgent(model, customPrompt, customAppendPrompt) {
   let prompt = ARCHITECT_PROMPT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",