opencode-swarm 6.11.0 → 6.12.0

package/README.md

@@ -1,204 +1,200 @@
-<p align="center">
-   <img src="https://img.shields.io/badge/version-6.11.0-blue" alt="Version">
-   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-   <img src="https://img.shields.io/badge/opencode-plugin-purple" alt="OpenCode Plugin">
-   <img src="https://img.shields.io/badge/agents-9-orange" alt="Agents">
-   <img src="https://img.shields.io/badge/tests-6000+-brightgreen" alt="Tests">
-</p>
-
-<h1 align="center">🐝 OpenCode Swarm</h1>
-
-<p align="center">
-  <strong>A structured multi-agent coding framework for OpenCode.</strong><br>
-  Nine specialized agents. Persistent memory. A QA gate on every task. Code that ships.
-</p>
-
-<p align="center">
-  <a href="#the-problem">The Problem</a> •
-  <a href="#how-it-works">How It Works</a> •
-  <a href="#agents">Agents</a> •
-  <a href="#persistent-memory">Memory</a> •
-  <a href="#guardrails">Guardrails</a> •
-  <a href="#comparison">Comparison</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#roadmap">Roadmap</a>
-</p>
+# 🐝 OpenCode Swarm
+
+**Your AI writes the code. Swarm makes sure it actually works.**
+
+OpenCode Swarm is a plugin for [OpenCode](https://opencode.ai) that turns a single AI coding agent into a team of nine. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another catches security issues. Nothing ships until every check passes. Your project state is saved to disk, so you can close your laptop, come back tomorrow, and pick up exactly where you left off.
+
+```bash
+npm install -g opencode-swarm
+```
+
+That's it. Open your project with `opencode` and start building. Swarm activates automatically.
 
 ---
 
-## The Problem
+## What Actually Happens
 
-Every multi-agent AI coding tool on the market has the same failure mode: they are vibes-driven. You describe a feature. Agents spawn. They race each other to write conflicting code, lose context after 20 messages, hit token limits mid-task, and produce something that sort-of-works until it doesn't. There's no plan. There's no memory. There's no gatekeeper. There's no test that was actually run.
+You say: *"Build me a JWT auth system."*
 
-**oh-my-opencode** is a prompt collection. **get-shit-done** is a workflow macro. Neither is a framework with memory, QA enforcement, or the ability to resume a project a week later exactly where you left off.
+Here's what Swarm does behind the scenes:
 
-OpenCode Swarm is built differently.
+1. **Asks you clarifying questions** (only the ones it can't figure out itself)
+2. **Scans your codebase** to understand what already exists
+3. **Consults domain experts** (security, API design, whatever your project needs) and caches the guidance so it never re-asks
+4. **Writes a phased plan** with concrete tasks, acceptance criteria, and dependencies
+5. **A separate critic agent reviews the plan** before any code is written
+6. **Implements one task at a time.** For each task:
+   - A coder agent writes the code
+   - 7 automated checks run (syntax, imports, linting, secrets, security, build, quality)
+   - A reviewer agent (running on a *different* AI model) checks for correctness
+   - A test engineer agent writes tests, runs them, and checks coverage
+   - If anything fails, it goes back to the coder with specific feedback
+   - If it passes everything, the task is marked done and the next one starts
+7. **After each phase completes**, documentation updates automatically, and a retrospective captures what worked and what didn't. Those learnings carry into the next phase.
+
+All of this state lives in a `.swarm/` folder in your project:
 
 ```
-Every other framework:
-├── Agent 1 starts the auth module...
-├── Agent 2 starts the user model... (conflicts with Agent 1)
-├── Agent 3 writes tests... (for code that doesn't exist yet)
-├── Context window fills up and the whole thing drifts
-└── Result: chaos. Rework. Start over.
-
-OpenCode Swarm:
-├── Architect reads .swarm/plan.md → project already in progress, resumes Phase 2
-├── @explorer scans the codebase for current state
-├── @sme DOMAIN: security → consults on auth patterns, guidance cached
-├── Architect writes .swarm/plan.md: 3 phases, 9 tasks, acceptance criteria per task
-├── @critic reviews the plan → APPROVED
-├── @coder implements Task 2.2 (one task, full context, nothing else)
-├── diff tool → imports tool → lint fix → lint check → secretscan → @reviewer → @test_engineer
-├── All gates pass → plan.md updated → Task 2.2: [x]
-└── Result: working code, documented decisions, resumable project, evidence trail
+.swarm/
+├── plan.md       # Your project roadmap (tasks, status, what's done, what's next)
+├── context.md    # Decisions made, expert guidance, established patterns
+├── evidence/     # Review verdicts, test results, diffs for every completed task
+└── history/      # Phase retrospectives and metrics
 ```
 
+Close your terminal. Come back next week. Swarm reads these files and picks up exactly where it stopped.
+
 ---
 
-## How It Works
+## Why This Exists
 
-### The Execution Pipeline
+Most AI coding tools let one model write code and then ask *that same model* if the code is good. That's like asking someone to proofread their own essay. They'll miss the same things they missed while writing it.
 
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 0: Resume Check                                                   │
-│  .swarm/plan.md exists? Resume mid-task. New project? Continue.          │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 1: Clarify                                                        │
-│  Ask only what the Architect cannot infer. Then stop.                    │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 2: Discover                                                       │
-│  @explorer scans codebase → structure, languages, frameworks, key files  │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 3: SME Consult (serial, cached)                                   │
-│  @sme DOMAIN: security, @sme DOMAIN: api, ...                            │
-│  Guidance written to .swarm/context.md — never re-asked in future phases │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 4: Plan                                                           │
-│  Architect writes .swarm/plan.md                                         │
-│  Structured phases, tasks with SMALL/MEDIUM/LARGE sizing, acceptance     │
-│  criteria per task, explicit dependency graph                            │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 4.5: Critic Gate                                                  │
-│  @critic reviews plan → APPROVED / NEEDS_REVISION / REJECTED             │
-│  Max 2 revision cycles. Escalates to user if unresolved.                 │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 5: Execute (per task)                                             │
-│                                                                          │
-│  [UI task?] → @designer scaffold first                                   │
-│                                                                          │
-│  @coder (one task, full context)                                         │
-│       ↓                                                                  │
-│  diff → syntax_check → placeholder_scan → imports → lint fix            │
-│  (contract detection) (parse validation) (anti-slop) (AST-based)         │
-│       ↓                                                                  │
-│  build_check → pre_check_batch (4 parallel: lint:check, secretscan,      │
-│  (compile verify)        sast_scan, quality_budget)                      │
-│       ↓                                                                  │
-│  @reviewer (correctness pass)                                            │
-│       ↓ APPROVED                                                         │
-│  @reviewer (security-only pass, if file matches security globs)          │
-│       ↓ APPROVED                                                         │
-│  @test_engineer (verification tests + coverage gate ≥70%)               │
-│       ↓ PASS                                                             │
-│  @test_engineer (adversarial tests — boundary violations, injections)    │
-│       ↓ PASS                                                             │
-│  ⛔ HARD STOP: Pre-commit checklist (4 items required, no override)       │
-│       ↓ COMPLETE                                                         │
-│  plan.md → [x] Task complete                                             │
-│                                                                          │
-│  Any gate fails → retry with failure count + structured rejection        │
-│  Max 5 retries → escalate to user                                        │
-└──────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    ▼
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Phase 6: Phase Complete                                                 │
-│  @explorer rescans. @docs updates documentation. Retrospective written.  │
-│  Learnings injected as [SWARM RETROSPECTIVE] into next phase.            │
-│  "Phase 1 complete (4 tasks, 0 rejections). Ready for Phase 2?"          │
-└──────────────────────────────────────────────────────────────────────────┘
+Swarm fixes this by splitting the work across specialized agents and requiring that different models handle writing vs. reviewing. The coder writes. A different model reviews. Another model tests. Different training data, different blind spots, different failure modes.
+
+The other thing most tools get wrong: they try to do everything in parallel. That sounds fast, but in practice you get three agents writing conflicting code at the same time with no coordination. Swarm runs one task at a time through a fixed pipeline. Slower per-task, but you don't redo work.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g opencode-swarm
 ```
 
-### Why Serial Execution Matters
+### Verify
 
-Multi-agent parallelism sounds fast. In practice, it is a race to produce conflicting, unreviewed code that requires a human to untangle. OpenCode Swarm runs one task at a time through a deterministic pipeline. Every task is reviewed. Every test is run. Every failure is documented and fed back to the coder with structured context. The tradeoff in raw speed is paid back in not redoing work.
+Open a project with `opencode` and run:
 
----
+```
+/swarm diagnose
+```
+
+This checks that everything is wired up correctly.
 
-## Agents
+### Configure Models (Optional)
 
-### 🎯 Orchestrator
+By default, Swarm uses whatever model OpenCode is configured with. To route different agents to different models (recommended), create `.opencode/swarm.json` in your project:
+
+```json
+{
+  "agents": {
+    "architect": { "model": "anthropic/claude-opus-4-6" },
+    "coder":     { "model": "minimax-coding-plan/MiniMax-M2.5" },
+    "reviewer":  { "model": "zai-coding-plan/glm-5" }
+  }
+}
+```
 
-**`architect`** — The central coordinator. Owns the plan, delegates all work, enforces every QA gate, maintains project memory, and resumes projects across sessions. Every other agent works for the Architect.
+You only need to specify the agents you want to override. The rest use the default.
 
-### 🔍 Discovery
+### Start Building
 
-**`explorer`** — Fast codebase scanner. Identifies structure, languages, frameworks, key files, and import patterns. Runs before planning and after every phase completes.
+Just tell OpenCode what you want to build. Swarm handles the rest.
 
-### 🧠 Domain Expert
+```
+> Build a REST API with user registration, login, and JWT auth
+```
 
-**`sme`** — Open-domain expert. The Architect specifies any domain per call: `security`, `python`, `rust`, `kubernetes`, `ios`, `ml`, `blockchain` — any domain the underlying model has knowledge of. No hardcoded list. Guidance is cached in `.swarm/context.md` so the same question is never asked twice.
+Use `/swarm status` at any time to see where things stand.
 
-### 🎨 Design
+---
 
-**`designer`** — UI/UX specification agent. Opt-in via config. Generates component scaffolds and design tokens before the coder touches UI tasks, eliminating the most common source of front-end rework.
+## Useful Commands
 
-### 💻 Implementation
+| Command | What It Does |
+|---------|-------------|
+| `/swarm status` | Where am I? Current phase, task progress |
+| `/swarm plan` | Show the full project plan |
+| `/swarm diagnose` | Health check, is everything configured right? |
+| `/swarm evidence 2.1` | Show review/test results for a specific task |
+| `/swarm history` | What's been completed so far |
+| `/swarm reset --confirm` | Start over (clears all swarm state) |
 
-**`coder`** — Implements exactly one task with full context. No multitasking. No context bleed from prior tasks. The coder receives: the task spec, acceptance criteria, SME guidance, and relevant context from `.swarm/context.md`. Nothing else.
+---
 
-**`test_engineer`** — Generates tests, runs them, and returns structured `PASS/FAIL` verdicts with coverage percentages. Runs twice per task: once for verification, once for adversarial attack scenarios.
+## The Agents
 
-### ✅ Quality Assurance
+Swarm has nine agents. You don't interact with them directly. The architect orchestrates everything.
 
-**`reviewer`** — Dual-pass review. First pass: correctness, logic, maintainability. Second pass: security-only, scoped to OWASP Top 10 categories, triggered automatically when the modified files match security-sensitive path patterns. Both passes produce structured verdicts with specific rejection reasons.
+| Agent | Role | When It Runs |
+|-------|------|-------------|
+| **architect** | Plans the project, delegates tasks, enforces quality gates | Always (it's the coordinator) |
+| **explorer** | Scans your codebase to understand what exists | Before planning, after each phase |
+| **sme** | Domain expert (security, APIs, databases, whatever is needed) | During planning, guidance is cached |
+| **critic** | Reviews the plan before any code is written | After planning, before execution |
+| **coder** | Writes code, one task at a time | During execution |
+| **reviewer** | Reviews code for correctness and security issues | After every task |
+| **test_engineer** | Writes and runs tests, including adversarial edge cases | After every task |
+| **designer** | Generates UI scaffolds and design tokens (opt-in) | Before UI tasks |
+| **docs** | Updates documentation to match what was actually built | After each phase |
 
-**`critic`** — Plan review gate. Reviews the Architect's plan *before implementation begins*. Checks for completeness, feasibility, scope creep, missing dependencies, and AI-slop hallucinations. Plans do not proceed without Critic approval.
+---
 
-### 📝 Documentation
+## How It Compares
 
-**`docs`** — Documentation synthesizer. Runs in Phase 6 with a diff of changed files. Updates READMEs, API documentation, and guides to reflect what was actually built, not what was planned.
+| | OpenCode Swarm | oh-my-opencode | get-shit-done |
+|---|:-:|:-:|:-:|
+| Multiple specialized agents | ✅ 9 agents | ❌ Prompt config | ❌ Single-agent macros |
+| Plan reviewed before coding starts | ✅ | ❌ | ❌ |
+| Every task reviewed + tested | ✅ | ❌ | ❌ |
+| Different model for review vs. coding | ✅ | ❌ | ❌ |
+| Saves state to disk, resumable | ✅ | ❌ | ❌ |
+| Security scanning built in | ✅ | ❌ | ❌ |
+| Learns from its own mistakes | ✅ (retrospectives) | ❌ | ❌ |
 
 ---
 
-## Persistent Memory
+<details>
+<summary><strong>Full Execution Pipeline (Technical Detail)</strong></summary>
 
-Other frameworks lose everything when the session ends. Swarm stores project state on disk.
+### The Pipeline
+
+Every task goes through this sequence. No exceptions, no overrides.
 
 ```
-.swarm/
-├── plan.md          # Living roadmap: phases, tasks, status, rejections, blockers
-├── plan.json        # Machine-readable plan for tooling
-├── context.md       # Institutional knowledge: decisions, SME guidance, patterns
-├── evidence/        # Per-task execution evidence bundles
-│   ├── 1.1/         # review verdict, test results, diff summary for task 1.1
-│   └── 2.3/
-└── history/
-    ├── phase-1.md   # What was built, what was learned, retrospective metrics
-    └── phase-2.md
+MODE: EXECUTE (per task)
+│
+├── 5a. @coder implements (ONE task only)
+├── 5b. diff + imports (contract + dependency analysis)
+├── 5c. syntax_check (parse validation)
+├── 5d. placeholder_scan (catches TODOs, stubs, incomplete code)
+├── 5e. lint fix → lint check
+├── 5f. build_check (does it compile?)
+├── 5g. pre_check_batch (4 parallel: lint, secretscan, SAST, quality budget)
+├── 5h. @reviewer (correctness pass)
+├── 5i. @reviewer (security pass, if security-sensitive files changed)
+├── 5j. @test_engineer (verification tests + coverage ≥70%)
+├── 5k. @test_engineer (adversarial tests)
+├── 5l. ⛔ Pre-commit checklist (all 4 items required, no override)
+└── 5m. Task marked complete, evidence written
 ```
 
-### plan.md — Living Roadmap
+If any step fails, the coder gets structured feedback and retries. After 5 failures on the same task, it escalates to you.
+
+### Architect Workflow Modes
+
+The architect moves through these modes automatically:
+
+| Mode | What Happens |
+|------|-------------|
+| `RESUME` | Checks if `.swarm/plan.md` exists, picks up where it left off |
+| `CLARIFY` | Asks you questions (only what it can't infer) |
+| `DISCOVER` | Explorer scans the codebase |
+| `CONSULT` | SME agents provide domain guidance |
+| `PLAN` | Architect writes the phased plan |
+| `CRITIC-GATE` | Critic reviews the plan (max 2 revision cycles) |
+| `EXECUTE` | Tasks are implemented one at a time through the QA pipeline |
+| `PHASE-WRAP` | Phase completes, docs update, retrospective written |
+
+</details>
+
+<details>
+<summary><strong>Persistent Memory (What's in .swarm/)</strong></summary>
+
+### plan.md: Your Project Roadmap
 
 ```markdown
 # Project: Auth System
@@ -215,156 +211,108 @@ Current Phase: 2
   - Acceptance: Returns valid JWT with user claims, 15-minute expiry
   - Attempt 1: REJECTED — missing expiration claim
 - [ ] Task 2.3: Token validation middleware [MEDIUM]
-- [BLOCKED] Task 2.4: Refresh token rotation
-  - Reason: Awaiting decision on rotation strategy
 ```
 
-### context.md — Institutional Knowledge
+### context.md: What's Been Decided
 
 ```markdown
-# Project Context: Auth System
-
 ## Technical Decisions
 - bcrypt cost factor: 12
 - JWT TTL: 15 minutes; refresh TTL: 7 days
-- Refresh token store: Redis with key prefix auth:refresh:
 
-## SME Guidance Cache
+## SME Guidance (cached, never re-asked)
 ### security (Phase 1)
-- Never log tokens or passwords in any context
-- Use constant-time comparison for all token equality checks
-- Rate-limit login endpoint: 5 attempts / 15 minutes per IP
+- Never log tokens or passwords
+- Rate-limit login: 5 attempts / 15 min per IP
 
 ### api (Phase 1)
-- Return HTTP 401 for invalid credentials (not 404)
-- Include token expiry timestamp in response body
-
-## Patterns Established
-- Error handling: custom ApiError class with HTTP status and error code
-- Validation: Zod schemas in /validators/, applied at request boundary
+- Return 401 for invalid credentials (not 404)
 ```
 
-Start a new session tomorrow. The Architect reads these files and picks up exactly where you left off — no re-explaining, no rediscovery, no drift.
-
 ### Evidence Bundles
 
-Each completed task writes structured evidence to `.swarm/evidence/`:
+Every completed task writes structured evidence to `.swarm/evidence/`:
 
 | Type | What It Captures |
-|------|-----------------|
-| `review` | Verdict (APPROVED/REJECTED), risk level, specific issues |
-| `test` | Pass/fail counts, coverage percentage, failure messages |
-| `diff` | Files changed, additions/deletions, contract change flags |
-| `approval` | Stakeholder sign-off with notes |
-| `retrospective` | Phase metrics: total tool calls, coder revisions, reviewer rejections, test failures, security findings, lessons learned |
+|------|--------------------|
+| review | Verdict, risk level, specific issues |
+| test | Pass/fail counts, coverage %, failure messages |
+| diff | Files changed, additions/deletions |
+| retrospective | Phase metrics, lessons learned (injected into next phase) |
 
-Retrospectives from completed phases are injected as `[SWARM RETROSPECTIVE]` hints at the start of subsequent phases. The framework learns from its own history within a project.
+</details>
 
----
+<details>
+<summary><strong>Guardrails and Circuit Breakers</strong></summary>
 
-## Heterogeneous Models
+Every agent runs inside a circuit breaker that kills runaway behavior before it burns your credits.
 
-Single-model frameworks have correlated failure modes. The same model that writes the bug reviews it and misses it. Swarm lets you route each agent to the model it is best suited for:
+| Signal | Default Limit | What Happens |
+|--------|:---:|-------------|
+| Tool calls | 200 | Agent is stopped |
+| Duration | 30 min | Agent is stopped |
+| Same tool repeated | 10x | Agent is warned, then stopped |
+| Consecutive errors | 5 | Agent is stopped |
+
+Limits reset per task. A coder working on Task 2.3 is not penalized for tool calls made during Task 2.2.
+
+Per-agent overrides:
 
 ```json
 {
-  "agents": {
-    "architect": { "model": "anthropic/claude-opus-4-6" },
-    "coder": { "model": "minimax-coding-plan/MiniMax-M2.5" },
-    "explorer": { "model": "minimax-coding-plan/MiniMax-M2.1" },
-    "sme": { "model": "kimi-for-coding/k2p5" },
-    "critic": { "model": "zai-coding-plan/glm-5" },
-    "reviewer": { "model": "zai-coding-plan/glm-5" },
-    "test_engineer": { "model": "minimax-coding-plan/MiniMax-M2.5" },
-    "docs": { "model": "zai-coding-plan/glm-4.7-flash" },
-    "designer": { "model": "kimi-for-coding/k2p5" }
+  "guardrails": {
+    "profiles": {
+      "coder": { "max_tool_calls": 500, "max_duration_minutes": 60 },
+      "explorer": { "max_tool_calls": 50 }
+    }
   }
 }
 ```
 
-Reviewer uses a different model than Coder by design. Different training, different priors, different blind spots. This is the cheapest bug-catcher you will ever deploy.
-
----
+</details>
 
-## Guardrails
+<details>
+<summary><strong>Quality Gates (Technical Detail)</strong></summary>
 
-Every subagent runs inside a circuit breaker that kills runaway behavior before it burns credits on a stuck loop.
+### Built-in Tools
 
-| Layer | Trigger | Action |
-|-------|---------|--------|
-| ⚠️ Soft Warning | 50% of any limit reached | Warning injected into agent stream |
-| 🛑 Hard Block | 100% of any limit reached | All further tool calls blocked |
+| Tool | What It Does |
+|------|-------------|
+| syntax_check | Tree-sitter validation across 9+ languages |
+| placeholder_scan | Catches TODOs, FIXMEs, stubs, placeholder text |
+| sast_scan | Offline security analysis, 63+ rules, 9 languages |
+| sbom_generate | CycloneDX dependency tracking, 8 ecosystems |
+| build_check | Runs your project's native build/typecheck |
+| quality_budget | Enforces complexity, duplication, and test ratio limits |
+| pre_check_batch | Runs lint, secretscan, SAST, and quality budget in parallel (~15s vs ~60s sequential) |
 
-| Signal | Default | Description |
-|--------|---------|-------------|
-| Tool calls | 200 | Per-invocation, not per-session |
-| Duration | 30 min | Wall-clock time per delegation |
-| Repetition | 10 | Same tool + args consecutively |
-| Consecutive errors | 5 | Sequential null/undefined outputs |
+All tools run locally. No Docker, no network calls, no external APIs.
 
-Limits are enforced **per-invocation**. Each delegation to a subagent starts a fresh budget. A coder fixing a second task is not penalized for the first task's tool calls. The Architect is exempt from all limits by default.
+Optional enhancement: Semgrep (if on PATH).
 
-Per-agent profiles allow fine-grained overrides:
+### Gate Configuration
 
-```jsonc
+```json
 {
-  "guardrails": {
-    "max_tool_calls": 200,
-    "profiles": {
-      "coder":    { "max_tool_calls": 500, "max_duration_minutes": 60 },
-      "explorer": { "max_tool_calls": 50 }
+  "gates": {
+    "syntax_check": { "enabled": true },
+    "placeholder_scan": { "enabled": true },
+    "sast_scan": { "enabled": true },
+    "quality_budget": {
+      "enabled": true,
+      "max_complexity_delta": 5,
+      "min_test_to_code_ratio": 0.3
     }
   }
 }
 ```
 
----
-
-## Comparison
-
-| Feature | OpenCode Swarm | oh-my-opencode | get-shit-done | AutoGen | CrewAI |
-|---------|:-:|:-:|:-:|:-:|:-:|
-| Multi-agent orchestration | ✅ 9 specialized agents | ❌ Prompt config only | ❌ Single-agent macros | ✅ | ✅ |
-| Execution model | Serial (deterministic) | N/A | N/A | Parallel (chaotic) | Parallel |
-| Phased planning with acceptance criteria | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Critic gate before implementation | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Per-task dual-pass review (correctness + security) | ✅ | ❌ | ❌ | Optional | Optional |
-| Adversarial test pass per task | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Pre-reviewer pipeline (lint, secretscan, imports) | ✅ v6.3 | ❌ | ❌ | ❌ | ❌ |
-| Persistent session memory | ✅ `.swarm/` files | ❌ | ❌ | Session only | Session only |
-| Resume projects across sessions | ✅ Native | ❌ | ❌ | ❌ | ❌ |
-| Evidence trail per task | ✅ Structured bundles | ❌ | ❌ | ❌ | ❌ |
-| Heterogeneous model routing | ✅ Per-agent | ❌ | ❌ | Limited | Limited |
-| Circuit breaker / guardrails | ✅ Per-invocation | ❌ | ❌ | ❌ | ❌ |
-| Open-domain SME consultation | ✅ Any domain | ❌ | ❌ | ❌ | ❌ |
-| Retrospective learning across phases | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Slash commands + diagnostics | ✅ 12 commands | ❌ | Limited | ❌ | ❌ |
-
----
-
-## Slash Commands
-
-| Command | Description |
-|---------|-------------|
-| `/swarm status` | Current phase, task progress, agent count |
-| `/swarm plan [N]` | Full plan or filtered by phase |
-| `/swarm agents` | All registered agents with models and permissions |
-| `/swarm history` | Completed phases with status |
-| `/swarm config` | Current resolved configuration |
-| `/swarm diagnose` | Health check for `.swarm/` files and config |
-| `/swarm export` | Export plan and context as portable JSON |
-| `/swarm evidence [task]` | Evidence bundles for a task or all tasks |
-| `/swarm archive [--dry-run]` | Archive old evidence with retention policy |
-| `/swarm benchmark` | Performance benchmarks |
-| `/swarm retrieve [id]` | Retrieve auto-summarized tool outputs |
-| `/swarm reset --confirm` | Clear swarm state files |
-| `/swarm preflight` | Run phase preflight checks (v6.7) |
-| `/swarm config doctor [--fix] [--restore <id>]` | Config validation with optional auto-fix (v6.7) |
-| `/swarm sync-plan` | Force plan.md regeneration from plan.json (v6.7) |
+</details>
 
----
+<details>
+<summary><strong>Full Configuration Reference</strong></summary>
 
-## Configuration
+Config file location: `~/.config/opencode/opencode-swarm.json` (global) or `.opencode/swarm.json` (project). Project config merges over global.
 
 ```json
 {
@@ -388,7 +336,7 @@ Per-agent profiles allow fine-grained overrides:
   },
   "review_passes": {
     "always_security_review": false,
-    "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*", "**/*token*"]
+    "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*"]
   },
   "automation": {
     "mode": "manual",
@@ -396,7 +344,6 @@ Per-agent profiles allow fine-grained overrides:
       "plan_sync": false,
       "phase_preflight": false,
       "config_doctor_on_startup": false,
-      "config_doctor_autofix": false,
       "evidence_auto_summaries": false,
       "decision_drift_detection": false
     }
@@ -404,333 +351,93 @@ Per-agent profiles allow fine-grained overrides:
 }
 ```
 
-Save to `~/.config/opencode/opencode-swarm.json` or `.opencode/swarm.json` in your project root. Project config merges over global config via deep merge — partial overrides do not clobber unspecified fields.
+### Automation Modes
 
-### Automation (v6.7)
+| Mode | Behavior |
+|------|----------|
+| `manual` | No background automation (default) |
+| `hybrid` | Background automation for safe ops, manual for sensitive ones |
+| `auto` | Full background automation |
 
-**Default mode: `manual`** (no background automation). Enable automation features via `automation` config:
+### Disabling Agents
 
 ```json
 {
-  "automation": {
-    "mode": "hybrid",
-    "capabilities": {
-      "plan_sync": true,
-      "config_doctor_on_startup": true,
-      "evidence_auto_summaries": true
-    }
-  }
+  "sme": { "disabled": true },
+  "designer": { "disabled": true },
+  "test_engineer": { "disabled": true }
 }
 ```
 
-**Automation modes:**
-- `manual` - No background automation (default)
-- `hybrid` - Background automation for safe ops, manual for sensitive ones
-- `auto` - Full background automation (target state)
+</details>
 
-**Per-feature flags (all default `false`):**
-- `plan_sync` - Auto-regenerate plan.md from plan.json when out of sync
-- `phase_preflight` - Phase-boundary validation before agent execution
-- `config_doctor_on_startup` - Config validation on plugin initialization
-- `config_doctor_autofix` - Auto-fix mode for Config Doctor (requires explicit opt-in)
-- `evidence_auto_summaries` - Auto-generate evidence summaries
-- `decision_drift_detection` - Detect drift between planned and actual decisions
+<details>
+<summary><strong>All Slash Commands</strong></summary>
 
-### Disabling Agents
+| Command | Description |
+|---------|-------------|
+| `/swarm status` | Current phase, task progress, agent count |
+| `/swarm plan [N]` | Full plan or filtered by phase |
+| `/swarm agents` | Registered agents with models and permissions |
+| `/swarm history` | Completed phases with status |
+| `/swarm config` | Current resolved configuration |
+| `/swarm diagnose` | Health check for `.swarm/` files and config |
+| `/swarm export` | Export plan and context as portable JSON |
+| `/swarm evidence [task]` | Evidence bundles for a task or all tasks |
+| `/swarm archive [--dry-run]` | Archive old evidence with retention policy |
+| `/swarm benchmark` | Performance benchmarks |
+| `/swarm retrieve [id]` | Retrieve auto-summarized tool outputs |
+| `/swarm reset --confirm` | Clear swarm state files |
+| `/swarm preflight` | Run phase preflight checks |
+| `/swarm config doctor [--fix]` | Config validation with optional auto-fix |
+| `/swarm sync-plan` | Force plan.md regeneration from plan.json |
 
-```json
-{
-  "sme":          { "disabled": true },
-  "designer":     { "disabled": true },
-  "test_engineer": { "disabled": true }
-}
-```
+</details>
 
 ---
 
-## Installation
+## Recent Changes
 
-```bash
-# Install globally
-npm install -g opencode-swarm
-
-# Or use npx
-npx opencode-swarm install
+### v6.12.0 — Anti-Process-Violation Hardening
 
-# Verify
-opencode  # then: /swarm diagnose
-```
+This release adds runtime detection hooks to catch and warn about architect workflow violations:
 
-The installer auto-configures `opencode.json` to include the plugin. Manual configuration:
+- **Self-coding detection**: Warns when the architect writes code directly instead of delegating
+- **Partial gate tracking**: Detects when QA gates are skipped
+- **Self-fix detection**: Warns when an agent fixes its own gate failure (should delegate to fresh agent)
+- **Batch detection**: Catches "implement X and add Y" batching in task requests
+- **Zero-delegation detection**: Warns when tasks complete without any coder delegation
 
-```json
-{
-  "plugins": ["opencode-swarm"]
-}
-```
+These hooks are advisory (warnings only) and help maintain workflow discipline during long sessions.
 
 ---
 
 ## Testing
 
-4008 tests across 136 files. Unit, integration, adversarial, and smoke. Covers config schemas, all agent prompts, all hooks, all tools, all commands, guardrail circuit breaker, race conditions, invocation window isolation, multi-invocation state, security category classification, evidence validation, background workers, phase-monitor hooks, and evidence-summary automation.
+6,000+ tests. Unit, integration, adversarial, and smoke. Zero additional test dependencies.
 
 ```bash
 bun test
 ```
 
-Zero additional test dependencies. Uses Bun's built-in test runner.
-
 ---
 
-## Quality Gates (v6.9.0)
-
-### syntax_check - Tree-sitter Parse Validation
-Validates syntax across 9+ languages using Tree-sitter parsers. Catches syntax errors before review.
-
-### placeholder_scan - Anti-Slop Detection  
-Detects TODO/FIXME comments, placeholder text, and stub implementations. Prevents shipping incomplete code.
-
-### sast_scan - Static Security Analysis
-Offline SAST with 63+ security rules across 9 languages. Optional Semgrep Tier B enhancement if available on PATH.
-
-### sbom_generate - Dependency Tracking
-Generates CycloneDX SBOMs from manifests/lock files. Tracks dependencies for 8 ecosystems.
-
-### build_check - Build Verification
-Runs repo-native build/typecheck commands. Ensures code compiles before review.
-
-### quality_budget - Maintainability Enforcement
-Enforces complexity, API, duplication, and test-to-code ratio budgets. Configurable thresholds.
-
-## Parallel Pre-Check Batch (v6.10.0)
-
-### pre_check_batch - Parallel Verification
-
-Runs four verification tools in parallel for faster QA gate execution:
-- **lint:check** - Code quality verification (hard gate)
-- **secretscan** - Secret detection (hard gate)
-- **sast_scan** - Static security analysis (hard gate)
-- **quality_budget** - Maintainability metrics
-
-**Purpose**: Reduces total gate execution time from ~60s (sequential) to ~15s (parallel) by running independent checks concurrently.
-
-**When to use**: After `build_check` passes and before `@reviewer` — all 4 gates must pass for `gates_passed: true`.
-
-**Usage**:
-```typescript
-const result = await pre_check_batch({
-  directory: ".",
-  files: ["src/auth.ts", "src/session.ts"],
-  sast_threshold: "medium"
-});
-
-// Returns:
-// {
-//   gates_passed: boolean,  // All hard gates passed
-//   lint: { ran, result, error, duration_ms },
-//   secretscan: { ran, result, error, duration_ms },
-//   sast_scan: { ran, result, error, duration_ms },
-//   quality_budget: { ran, result, error, duration_ms },
-//   total_duration_ms: number
-// }
-```
-
-**Hard Gates** (must pass for gates_passed=true):
-- Lint errors → Fix and retry
-- Secrets found → Fix and retry
-- SAST vulnerabilities at/above threshold → Fix and retry
-- Quality budget violations → Refactor or adjust thresholds
-
-**Parallel Execution Safety**:
-- Max 4 concurrent operations via `p-limit`
-- 60-second timeout per tool
-- 500KB output size limit
-- Individual tool failures don't cascade to others
-
-### Configuration
-
-Enable/disable parallel pre-check via `.opencode/swarm.json`:
-
-```json
-{
-  "pipeline": {
-    "parallel_precheck": true  // default: true
-  }
-}
-```
-
-Set to `false` to run gates sequentially (useful for debugging or resource-constrained environments).
-
-### Updated Phase 5 QA Sequence (v6.11.0)
-
-Complete execution pipeline with MODE labels and observable outputs:
-
-```
-MODE: EXECUTE (per task)
-│
-├── 5a. @coder implements (ONE task only)
-│   └── → REQUIRED: Print task start confirmation
-│
-├── 5b. diff + imports tools (contract + dependency analysis)
-│   └── → REQUIRED: Print change summary
-│
-├── 5c. syntax_check (parse validation)
-│   └── → REQUIRED: Print syntax status
-│
-├── 5d. placeholder_scan (anti-slop detection)
-│   └── → REQUIRED: Print placeholder scan results
-│
-├── 5e. lint fix → 5f. lint:check (inside pre_check_batch)
-│   └── → REQUIRED: Print lint status
-│
-├── 5g. build_check (compilation verification)
-│   └── → REQUIRED: Print build status
-│
-├── 5h. pre_check_batch (4 parallel gates)
-│   ├── lint:check (hard gate)
-│   ├── secretscan (hard gate)
-│   ├── sast_scan (hard gate)
-│   └── quality_budget (maintainability metrics)
-│   └── → REQUIRED: Print gates_passed status
-│
-├── 5i. @reviewer (correctness pass)
-│   └── → REQUIRED: Print approval decision
-│
-├── 5j. @reviewer security-only pass (if security file)
-│   └── → REQUIRED: Print security approval
-│
-├── 5k. @test_engineer (verification tests + coverage)
-│   └── → REQUIRED: Print test results
-│
-├── 5l. @test_engineer (adversarial tests)
-│   └── → REQUIRED: Print adversarial test results
-│
-├── 5m. ⛔ HARD STOP: Pre-commit checklist
-│   ├── [ ] All QA gates passed (no overrides)
-│   ├── [ ] Reviewer approval documented
-│   ├── [ ] Tests pass with evidence
-│   └── [ ] No security findings
-│   └── → REQUIRED: Print checklist completion
-│
-└── 5n. TASK COMPLETION CHECKLIST (emit before marking complete)
-    ├── Evidence written to .swarm/evidence/{taskId}/
-    ├── plan.md updated with [x] task complete
-    └── → REQUIRED: Print completion confirmation
-```
-
-**MODE Labels** (v6.11): Architect workflow uses MODE labels internally:
-- `MODE: RESUME` — Resume detection
-- `MODE: CLARIFY` — Requirement clarification
-- `MODE: DISCOVER` — Codebase exploration
-- `MODE: CONSULT` — SME consultation
-- `MODE: PLAN` — Plan creation
-- `MODE: CRITIC-GATE` — Plan review checkpoint
-- `MODE: EXECUTE` — Task implementation
-- `MODE: PHASE-WRAP` — Phase completion
-
-**NAMESPACE RULE**: MODE labels refer to architect workflow phases. Project plan phases (in plan.md) remain as "Phase N".
-
-**Retry Protocol** (v6.11): On failure, emit structured rejection:
-```
-RETRY #{count}/5
-FAILED GATE: {gate_name}
-REASON: {specific failure}
-REQUIRED FIX: {actionable instruction}
-RESUME AT: {step_5x}
-```
-
-**Anti-Exemption Rules** (v6.11): The following rationalizations are explicitly blocked:
-- "It's a simple change"
-- "Just updating docs"
-- "Only a config tweak"
-- "Hotfix, no time for QA"
-- "The tests pass locally"
-- "I'll clean it up later"
-- "No logic changes"
-- "Already reviewed the pattern"
-
-**Pre-Commit Rule** (v6.11): All 4 checkboxes required before commit. No override. A commit without completed QA gate is a workflow violation.
-
-### Rollback
-
-If parallel execution causes issues, refer to `.swarm/ROLLBACK-pre-check-batch.md` for rollback instructions.
-
-### Local-Only Guarantee
-All v6.9.0 quality tools run locally without:
-- Docker containers
-- Network connections
-- External APIs
-- Cloud services
-
-Optional enhancement: Semgrep (if already on PATH)
-
-### Configuration
-Configure gates in `.opencode/swarm.json`:
+## Design Principles
 
-```json
-{
-  "gates": {
-    "syntax_check": { "enabled": true },
-    "placeholder_scan": { "enabled": true },
-    "sast_scan": { "enabled": true },
-    "sbom_generate": { "enabled": true },
-    "build_check": { "enabled": true },
-    "quality_budget": {
-      "enabled": true,
-      "max_complexity_delta": 5,
-      "max_public_api_delta": 10,
-      "max_duplication_ratio": 0.05,
-      "min_test_to_code_ratio": 0.3
-    }
-  }
-}
-```
+1. **Plan before code.** The critic approves the plan before a single line is written.
+2. **One task at a time.** The coder gets one task and full context. Nothing else.
+3. **Review everything immediately.** Correctness, security, tests, adversarial tests. Every task.
+4. **Different models catch different bugs.** The coder's blind spot is the reviewer's strength.
+5. **Save everything to disk.** Any session, any model, any day, pick up where you left off.
+6. **Document failures.** Rejections and retries are recorded. After 5 failures, it escalates to you.
 
 ---
 
 ## Roadmap
 
-### v6.3 — Pre-Reviewer Pipeline
-
-Three new tools complete the pre-reviewer gauntlet. Code reaching the Reviewer is already clean.
-
-- **`imports`** — AST-based import graph. For each file changed by the coder, returns every consumer file, which exports each consumer uses, and the line numbers. Replaces fragile grep-based integration analysis with deterministic graph traversal.
-- **`lint`** — Auto-detects project linter (Biome, ESLint, Ruff, Clippy, PSScriptAnalyzer). Runs in fix mode first, then check mode. Structured diagnostic output per file.
-- **`secretscan`** — Entropy-based credential scanner. Detects API keys, tokens, connection strings, and private key headers in the diff before they reach the reviewer. Zero external dependencies.
-
-Phase 5 execute loop becomes: `coder → diff → imports → lint fix → lint check → secretscan → reviewer → security reviewer → test_engineer → adversarial test_engineer`.
-
-### v6.4 — Execution and Planning Tools
-
-- **`test_runner`** — Unified test execution across Bun, Vitest, Jest, Mocha, pytest, cargo test, and Pester. Auto-detects framework, returns normalized JSON with pass/fail/skip counts and coverage. Three scope modes: `all`, `convention` (naming-based), `graph` (import-graph-based). Eliminates the test_engineer's most common failure mode.
-- **`symbols`** — Export inventory for a module: functions, classes, interfaces, types, enums. Gives the Architect instant visibility into a file's public API surface without reading the full source.
-- **`checkpoint`** — Git-backed save points. Before any multi-file refactor (≥3 files), Architect auto-creates a checkpoint commit. On critical integration failure, restores via soft reset instead of iterating into a hole.
-
-### v6.5 — Intelligence and Audit Tools
-
-Five tools that improve planning quality and post-phase validation:
-
-- **`pkg_audit`** — Wraps `npm audit`, `pip-audit`, `cargo audit`. Structured CVE output with severity, patched versions, and advisory URLs. Fed to the security reviewer for concrete vulnerability context.
-- **`complexity_hotspots`** — Git churn × cyclomatic complexity risk map. Run in Phase 0/2 to identify modules that need stricter QA gates before implementation begins.
-- **`schema_drift`** — Compares OpenAPI spec against actual route implementations. Surfaces undocumented routes and phantom spec paths. Run in Phase 6 when API routes were modified.
-- **`todo_extract`** — Structured extraction of `TODO`, `FIXME`, and `HACK` annotations across the codebase. High-priority items fed directly into plan task candidates.
-- **`evidence_check`** — Audits completed tasks against required evidence types. Run in Phase 6 to verify every task has review and test evidence before the phase is marked complete.
-
----
-
-## Design Principles
+See [CHANGELOG.md](CHANGELOG.md) for shipped features.
 
-1. **Plan before code** — Documented phases with acceptance criteria. The Critic approves the plan before a single line is written.
-2. **One task at a time** — The Coder gets one task and full context. Nothing else.
-3. **Review everything immediately** — Every task goes through correctness review, security review, verification tests, and adversarial tests. No task ships without passing all four.
-4. **Cache SME knowledge** — Guidance is written to `context.md`. The same domain question is never asked twice in a project.
-5. **Persistent memory** — `.swarm/` files are the ground truth. Any session, any model, any day.
-6. **Serial execution** — Predictable, debuggable, no race conditions, no conflicting writes.
-7. **Heterogeneous models** — Different models, different blind spots. The coder's bug is the reviewer's catch.
-8. **User checkpoints** — Phase transitions require user confirmation. No unsupervised multi-phase runs.
-9. **Document failures** — Rejections and retries are recorded in plan.md. After 5 failed attempts, the task escalates to the user.
-10. **Resumable by design** — A cold-start Architect can read `.swarm/` and continue any project as if it had been there from the beginning.
+Upcoming: v6.12 targets process violation hardening based on field testing with models that attempt to bypass QA gates.
 
 ---
 
@@ -739,8 +446,7 @@ Five tools that improve planning quality and post-phase validation:
 - [Architecture Deep Dive](docs/architecture.md)
 - [Design Rationale](docs/design-rationale.md)
 - [Installation Guide](docs/installation.md)
-- [Linux + Native Windows + Docker Desktop Install Guide](docs/installation-linux-docker.md)
-- [LLM Operator Install Guide](docs/installation-llm-operator.md)
+- [Linux + Docker Desktop Install Guide](docs/installation-linux-docker.md)
 
 ---
 
@@ -750,6 +456,4 @@ MIT
 
 ---
 
-<p align="center">
-  <strong>Stop hoping your agents figure it out. Start shipping code that actually works.</strong>
-</p>
+**Stop hoping your agents figure it out. Start shipping code that actually works.**