devloom 1.0.0 → 1.1.0

package/README.md

@@ -1,50 +1,102 @@
 # DevLoom
 
-**Autonomous Development Weaver for OpenCode**
+**Autonomous Software Delivery System for OpenCode**
 
 DevLoom combines *Developer* + *Loom* — the loom being the ancient machine that
-weaves individual threads into finished fabric. DevLoom does the same for software:
-it takes a single natural-language prompt and weaves together requirements,
-architecture, code, tests, and documentation into a complete, working feature.
+weaves individual threads into finished fabric. It transforms a single prompt
+into verified, documented, production-ready software — not just generated code.
+
+> Generating code is not success. Passing verification is not success.
+> Success is achieved only when all acceptance gates have passed.
 
 ---
 
+## Highlights
+
+- **17 agents, hard-delegation enforced** — Orchestrator routes; Planner, Developer, QA, Verifier, Security, Documenter, Vision, plus the read-only Visual Director (design direction) and Visual Critic (independent visual review) execute. Orchestrator has `edit/write/patch: deny` at the OpenCode permission level — code production is IMPOSSIBLE without `task()` delegation. Sub-agents have `task: deny` to prevent delegation chains.
+- **Complexity-based tiering** — Classifies prompts as senior/standard, calls variant agents by name. No global state.
+- **Protocol compliance** — Inline RULES + guard injection per turn. Never skippable.
+- **Pipeline continuity** — Sessions tracked via `state.sessions`, task_id reused across turns.
+- **Loop detection** — Tracks retry counts per agent per ticket. Warns at 2+ retries, blocks at 3+. Detects delegation chains and phase stalls.
+- **Peer review gate** — Multi-model consensus for high-risk changes.
+- **Architecture atlas** — Auto-generated codebase map on plugin init.
+- **Queue-over-preempt** — New prompts queue behind active work.
+- **Tier degradation** — Auto-fallback on model failure: senior→standard→skip.
+- **Agent listing** — `/devloom-agents` shows all agents and their current model assignments.
+- **Background dispatch** — Independent lanes run via `task(..., background: true)` for parallel work.
+
 ## How It Works
 
-The **Orchestrator** interprets your prompt, delegates to five specialist
-sub-agents, and loops until every task passes QA and the final build succeeds —
-no human intervention required after the initial prompt.
-
-```
-/devloom "Build a REST API for user management with JWT auth"
-         │
-         ▼
-  DEVLOOM ORCHESTRATOR
-         │
-         ├── @devloom-analyst     → .opencode/devloom/requirements.md
-         ├── @devloom-architect   → .opencode/devloom/plan.md
-         │
-         └── For each task in plan.md:
-                 ├── @devloom-developer   (weaves the code)
-                 ├── @devloom-qa          (inspects the weave)
-                 │       └── QA_FAIL → developer re-weaves → QA re-inspects
-                 └── marks task [x] on QA_PASS
-         │
-         ├── @devloom-documenter  (updates README + API docs)
-         └── Final quality gate  (build + full test suite)
-                 └── All green → DEVLOOM_DONE
-```
-
-### Agent Roster
-
-| Agent | Mode | Role |
-|---|---|---|
-| `devloom-orchestrator` | `primary` | Loop controller, phase manager, quality gate |
-| `devloom-analyst` | `subagent` | Prompt → `.opencode/devloom/requirements.md` |
-| `devloom-architect` | `subagent` | Requirements → `.opencode/devloom/plan.md` |
-| `devloom-developer` | `subagent` | Task implementation |
-| `devloom-qa` | `subagent` | Tests, lint, regression checks, verdict |
-| `devloom-documenter` | `subagent` | README + API doc updates |
+```
+/devloom "<prompt>"
+         |
+         v
+   ORCHESTRATOR (never implements — routes only)
+         |
+          +-- CLASSIFY: complex? senior tier. Standard? Base agent.
+          |              Then call the right variant by name.
+         |
+         +-- TRIAGE: pick minimal chain for intent
+         |     feature → planner > developer > qa > documenter
+         |     bug     → developer (root-cause) > qa (regression)
+         |     small   → developer > qa
+         |
+         +-- CONDITIONAL ADD-ONS (only when touched)
+         |     image        → vision first
+         |     UI/API/CRUD  → verifier / security
+         |
+         +-- DEFECT LOOP: max 3 cycles, then BLOCKED
+         +-- DEVLOOM_DONE: all chain gates pass
+```
+
+### Agents
+
+| Agent | Role | Skill |
+|-------|------|-------|
+| Orchestrator | Triage, route, state, gate (hard-denied write/edit/patch) | — |
+| Planner | Requirements + CleanArch plan + evidence path | `plan/planning` + `plan/verification-planning` |
+| Developer | Implement / fix + simplify | `build/development` + `build/simplify` |
+| QA | Tests, lint, review, regression + simplify | `verify/quality-assurance` + `build/simplify` |
+| Verifier | Runtime checks by scope + peer review | `verify/app-verification` |
+| Security | CRUD/exposure forensic review | `review/security-review` |
+| Documenter | Docs + state updates | `ship/documentation` |
+| Vision | Image/screenshot analysis | `build/vision-analysis` |
+| Visual Director | Read-only visual design direction + project design memory (never implements frontend code) | `design/visual-direction` + domain design skill |
+| Visual Critic | Independent read-only visual review of rendered output (never edits code) | `verify/visual-critique` |
+
+Each agent has variant files: `-senior` (strongest models) or `-flash` (cheapest), plus base (standard tier). Protocol rules are inlined in every agent — no external LOAD needed beyond the skill files.
+
+---
+
+## Visual Intelligence Pipeline
+
+For substantial graphical work, DevLoom routes through an extra visual loop:
+
+```
+planner (marks VISUAL_REQUIRED=true)
+  → visual-director   (classifies visual domain + defines direction;
+                       persists .opencode/devloom/context/design.md)
+  → developer         (implements against design.md as the visual contract;
+                       functionality overrides aesthetics)
+  → visual-critic     (independent screenshot review — fresh context, no
+                       implementation rationale)
+  → developer correction (max 3 visual cycles, integrated with DevLoom's
+                       existing defect-loop circuit breakers)
+  → qa → verifier (visual, responsive, motion, a11y + functional scopes)
+  → documenter
+```
+
+- **Small UI bug**: developer → qa → verifier — no visual agents. Backend work never routes through visual agents.
+- **Design memory**: `.opencode/devloom/context/design.md` with sections Visual Concept, Personality, UX Goal, Color Roles, Typography, Spacing, Grid/Layout, Surface, Shape Language, Components, Iconography, Motion, Interaction, Responsive, Accessibility, DO/DON'T (games add HUD Information Priority + Gameplay Attention Rules). Read before subsequent visual work; updated only when direction intentionally changes.
+- **Visual complexity** is orchestration metadata: `none` / `standard` / `high` — separate from the engineering tier (senior/standard).
+- **New skills**: `design/visual-direction`, `design/design-grounding`, `design/web-design`, `design/app-design`, `design/game-design`, `design/motion-design`, `design/design-system`; `verify/visual-critique`, `verify/visual-quality-gate`, `verify/visual-regression`.
+- **Verifier scopes gained**: `visual` (render + screenshot + critique integration + design-direction alignment), `responsive` (1440×1000, 1024×900, 390×844 or project targets: overflow, clipping, nav, readability, reflow, control usability), `motion` (key transitions, feedback, prefers-reduced-motion, no motion breakage).
+- **Completion gates**: FUNCTIONAL + QA + VISUAL + RESPONSIVE + ACCESSIBILITY for graphical work. `visual_validation_verified` requires actual rendered evidence when tooling supports it; if images cannot be inspected, DevLoom reports `VISUAL_VERIFICATION_LIMITED` instead of a false pass. Backend-only changes do not require visual gates.
+- **Chrome MCP (optional)**: browser-renderable work uses the Chrome MCP when configured (screenshots, DOM/a11y snapshot, viewport resize, device emulation, console/network, JS eval, Lighthouse). It is discovered, never assumed; Playwright MCP is not a substitute. Without it, DevLoom falls back to structural/runtime verification and says so — it never fabricates visual checks.
+- **One-time multimodal path check**: Chrome screenshot → actual image → vision-capable model. If real images cannot reach the model (e.g. a given MiMo endpoint), screenshot validation is not marked passed.
+- **OpenDesign MCP (optional)**: if an `opendesign` MCP is configured, visual-director may use it for design grounding (typography/spacing/density/palette/motion/interaction relationships + explicit DON'T rules). Never a hard dependency; DevLoom works normally without it, and never clones another product.
+- **Optional max-quality visual mode (documented, NOT default)**: 3 concepts → select 1 → 2 isolated implementations → blind visual-critic comparison → winner → max 2–3 refinement cycles → verifier gates. Only for high-value deliverables.
+- **Anti-generic-aesthetic rules**: avoid card soup, pill soup, default purple gradients, meaningless glassmorphism, arbitrary glow, decorative blobs, giant text without compositional purpose, generic cyan sci-fi HUDs/hexagons/scanlines, and dark SaaS dashboards disguised as game UI. Quality = hierarchy, composition, typography, spacing, proportion, coherence, domain fit, interaction quality.
 
 ---
 
@@ -70,9 +122,6 @@ cd devloom
 npm install && npm run build && node postinstall.mjs
 ```
 
-All methods run the post-install script that copies agents, commands, and skills
-to your OpenCode global config directory.
-
 **Per-project via `opencode.json`:**
 
 ```json
@@ -82,6 +131,49 @@ to your OpenCode global config directory.
 }
 ```
 
+The plugin auto-bootstraps `.opencode/devloom/project/`, generates the
+Architecture Atlas (`context/atlas.md`), and creates `.opencode/devloom/.tmp/`
+for temporary files — all on OpenCode startup.
+
+### Theme
+
+DevLoom ships a custom **Night Owl** theme for OpenCode's TUI. Deep indigo
+background with vibrant cyan, purple, and orange accents — designed for long
+coding sessions and low eye strain.
+
+```json
+# ~/.config/opencode/tui.json or .opencode/tui.json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "theme": "devloom-night-owl"
+}
+```
+
+The theme file is at `.opencode/themes/devloom-night-owl.json` in the project
+root. OpenCode loads it automatically when you open the devloom directory.
+
+### Drift protection (always-on)
+
+Long sessions make models "forget" prompt-only rules. DevLoom enforces the
+flow deterministically at three levels — no reminders needed:
+
+- **Level 1: OpenCode permissions (hardest)** — The orchestrator's `edit`/`write`/`patch` are denied at the OpenCode permission level. Calls fail with permission errors — the model has no way to bypass this. Sub-agents have `task: deny` so they cannot create delegation chains.
+- **Level 2: Plugin guard** (`tool.execute.before`): if the orchestrator somehow attempts a write outside `.opencode/devloom/`, the plugin blocks it with an error telling it to delegate via `task()`. State persistence stays allowed.
+- **Level 3: Per-turn injection** (`chat.message` + system transform): compliance requirements + protocol rules + live pipeline state injected into ALL devloom agents every turn.
+- **Compaction guard** (`experimental.session.compacting`): the compaction summary is forced to preserve the routing rule and current pipeline state, so the flow survives context compression.
+- **Session persistence**: session→agent mapping is written to `.opencode/devloom/.sessions.json` so the guard survives plugin reloads (e.g. after `opencode --continue`).
+
+### Anti-loop protection
+
+Agents that get stuck waste tokens. DevLoom tracks retry counts and stops runaway chains:
+
+- **Per-agent retry counter** — `state.loopCounts[agentName]` tracks how many times the orchestrator re-delegated to the same agent for the current ticket.
+- **WARN at 2 retries** — injected into the orchestrator's state summary as `loop_risk=[WARN:devloom-developer=2x]`.
+- **HARD STOP at 3 retries** — orchestrator prompt enforces: mark ticket blocked, report BLOCKED, never attempt a 4th retry.
+- **Phase stall detection** — if the same phase is re-entered 3+ times with no state advancement, report BLOCKED and ask for task decomposition.
+- **Delegation chain detection** — if a sub-agent responds by calling `task()` instead of completing its work, STOP. Sub-agents have `task: deny` at the permission level as a hard guarantee.
+- **Cost circuit breaker** — if a single ticket exceeds 2M tokens, pause and report.
+
 ---
 
 ## Usage
@@ -96,6 +188,18 @@ Check progress mid-run:
 /devloom-status
 ```
 
+List all agents and their current models:
+
+```
+/devloom-agents
+```
+
+Persist current state and pause for the next user command:
+
+```
+/devloom-save
+```
+
 Resume an interrupted execution:
 
 ```
@@ -116,117 +220,461 @@ opencode run "/devloom Add OpenTelemetry tracing to all HTTP handlers"
 
 ---
 
+## The Completion Gate
+
+DevLoom considers a task complete only when **all** of these pass:
+
+| Gate | What It Checks |
+|------|----------------|
+| `build` | Compilation succeeds |
+| `lint` | No lint errors |
+| `unit_tests` | All unit tests pass |
+| `integration_tests` | All integration tests pass |
+| `e2e_tests` | All end-to-end tests pass |
+| `all_routes_visited` | Every discovered route was visited |
+| `all_buttons_tested` | Every button was clicked |
+| `all_forms_tested` | Every form was verified |
+| `all_links_verified` | Every link was navigated |
+| `all_user_journeys_passed` | All user journeys executed successfully |
+| `all_api_endpoints_verified` | Every endpoint validated |
+| `accessibility_verified` | ARIA, keyboard, contrast all pass |
+| `responsive_layout_verified` | No layout defects |
+| `visual_validation_verified` | Rendering correct |
+| `performance_validation_verified` | Performance baseline met |
+| `security_validation_verified` | No security issues |
+| `no_open_defects` | Defect registry is clean |
+
+If any gate fails, DevLoom automatically returns to the repair phase.
+
+---
+
+## Autonomous Operation
+
+DevLoom never stops after code generation. It continues through:
+
+1. **Verification** -- Every route, form, button, link, and API endpoint is tested
+2. **Defect Discovery** -- All defects logged to persistent registry
+3. **Root Cause Analysis** -- Symptoms are traced to their source
+4. **Repair** -- Minimal fixes applied to root causes only
+5. **Re-Verification** -- Full regression suite after every fix
+6. **Recovery** -- Self-healing from build/test/network failures
+
+Human intervention is always the last resort.
+
+---
+
+## Loop Engineering
+
+**Stop prompting the agent. Design the loop that prompts the agent.**
+
+DevLoom's loop engineering system moves beyond one-shot prompts to recurring,
+cadence-driven agent execution. A configured loop runs a pattern on a schedule,
+with automatic circuit-breaking via token budget limits.
+
+### Loop patterns (7 built-in)
+
+| Pattern | Purpose |
+|---------|---------|
+| `daily-triage` | Review new issues, classify, route to planner |
+| `pr-babysitter` | Check open PRs for CI status, staleness, conflicts |
+| `ci-sweeper` | Retry or investigate failed CI jobs |
+| `dependency-sweeper` | Scan for outdated/vulnerable dependencies |
+| `changelog-drafter` | Generate changelog from recent commits |
+| `post-merge-cleanup` | Clean up merged branches, update tickets |
+| `issue-triage` | Triage issue queue with classification and routing |
+
+### Safety levels
+
+| Level | Behavior |
+|-------|----------|
+| L1 (report-only) | Observe and report — no file modifications |
+| L2 (assisted) | Fix with worktree isolation + verifier approval |
+| L3 (unattended) | Full autonomous fix-and-close cycle |
+
+### Usage
+
+Start a loop tick manually:
+
+```bash
+node .opencode/devloom/scripts/loop-run.mjs --pattern daily-triage
+```
+
+In OpenCode, start a background loop:
+
+```
+/devloom-loop start daily-triage --cadence "0 8 * * 1-5" --level L2
+```
+
+Each tick respects the token budget circuit breaker — if a run exceeds its
+budget, the loop pauses and logs the overage before the next scheduled tick.
+
+---
+
+## Defect Registry
+
+All discovered defects are tracked in `.opencode/devloom/defects.json`:
+
+```json
+{
+  "defects": [
+    {
+      "id": "BUG-001",
+      "severity": "high",
+      "location": "/customers",
+      "type": "route",
+      "status": "open"
+    }
+  ]
+}
+```
+
+Defects flow through: `open -> analyzed -> fixed -> verified -> closed`.
+The same defect is never rediscovered -- the registry prevents duplication.
+
+---
+
 ## Model Configuration
 
-By default all agents use **deepseek-v4-flash-free** (the fastest free model).
+DevLoom provides seven selectable model profiles plus auto-detection. Each
+maps every agent to a specific model optimized for its role.
+
+### Profile comparison
+
+| Profile | Quality | Cost | Best for |
+|---------|---------|------|----------|
+| **go** | Highest | Premium | Production delivery, complex features |
+| **go-economy** | High | Lower | Daily development, budget-conscious |
+| **deepseek** | High | Lower | DeepSeek-only stack |
+| **go-flash** | Good | Cheapest paid | High-volume, simple tasks |
+| **free** | Good | Zero | Evaluation, learning, hobby projects |
+| **glm** | High | Lower | GLM-only stack |
+| **mimo** | High | Low/Fast | MiMo V2.6 multimodal all-role stack |
+
+### go profile (max quality)
 
-### Per-project override
+Uses the strongest OpenCode Go models per role.
 
-Create `.opencode/devloom/config.json` in your project root. Every time you run
-a DevLoom command, it reads this file and overrides the global defaults:
+```json
+{
+  "models": {
+    "orchestrator": "opencode-go/deepseek-v4-flash",
+    "planner": "opencode-go/qwen3.7-max",
+    "developer": "opencode-go/kimi-k2.7-code",
+    "qa": "opencode-go/deepseek-v4-pro",
+    "verifier": "opencode-go/deepseek-v4-pro",
+    "security": "opencode-go/glm-5.2",
+    "documenter": "opencode-go/qwen3.7-plus",
+    "vision": "opencode-go/qwen3.6-plus",
+    "visual-director": "opencode-go/glm-5.2",
+    "visual-critic": "opencode-go/glm-5.3-flash"
+  }
+}
+```
+
+### go-economy profile
 
 ```json
 {
   "models": {
-    "orchestrator": "opencode/big-pickle",
-    "analyst": "opencode/deepseek-v4-flash-free",
-    "architect": "opencode/deepseek-v4-flash-free",
-    "developer": "opencode/deepseek-v4-flash-free",
-    "qa": "opencode/deepseek-v4-flash-free",
-    "documenter": "opencode/deepseek-v4-flash-free"
+    "orchestrator": "opencode-go/deepseek-v4-flash",
+    "planner": "opencode-go/deepseek-v4-pro",
+    "developer": "opencode-go/deepseek-v4-pro",
+    "qa": "opencode-go/deepseek-v4-flash",
+    "verifier": "opencode-go/deepseek-v4-flash",
+    "security": "opencode-go/deepseek-v4-pro",
+    "documenter": "opencode-go/qwen3.7-plus",
+    "vision": "opencode-go/qwen3.6-plus",
+    "visual-director": "opencode-go/deepseek-v4-pro",
+    "visual-critic": "opencode-go/glm-5.3-flash"
   }
 }
 ```
 
-**All models MUST use the `opencode/` or `opencode-go/` prefix.** If you forget
-the prefix, DevLoom adds it automatically and warns you.
+### deepseek profile
 
-### Interactive setup (first run)
+Uses only DeepSeek models for consistent provider affinity (vision uses cheapest vision-capable DeepSeek model):
 
-If no `config.json` exists, Phase 0 detects available models and asks whether
-to use **Free** (`opencode/`) or **Go** (`opencode-go/`) tier, then assigns
-the best available model per agent role.
+```json
+{
+  "models": {
+    "orchestrator": "opencode-go/deepseek-v4-pro",
+    "planner": "opencode-go/deepseek-v4-pro",
+    "developer": "opencode-go/deepseek-v4-pro",
+    "qa": "opencode-go/deepseek-v4-pro",
+    "verifier": "opencode-go/deepseek-v4-flash",
+    "security": "opencode-go/deepseek-v4-pro",
+    "documenter": "opencode-go/deepseek-v4-flash",
+    "vision": "opencode-go/deepseek-v4-flash-vision-exp",
+    "visual-director": "opencode-go/deepseek-v4-pro",
+    "visual-critic": "opencode-go/deepseek-v4-flash-vision-exp"
+  }
+}
+```
 
-### Global override
+### go-flash profile
 
-Edit the agent files directly at `~/.config/opencode/agents/`:
+All agents on DeepSeek V4 Flash for maximum throughput at minimum cost:
 
-```bash
-sed -i 's|^model:.*|model: opencode/deepseek-v4-flash-free|' \
-  ~/.config/opencode/agents/devloom-*.md
+```json
+{
+  "models": {
+    "orchestrator": "opencode-go/deepseek-v4-flash",
+    "planner": "opencode-go/deepseek-v4-flash",
+    "developer": "opencode-go/deepseek-v4-flash",
+    "qa": "opencode-go/deepseek-v4-flash",
+    "verifier": "opencode-go/deepseek-v4-flash",
+    "security": "opencode-go/deepseek-v4-flash",
+    "documenter": "opencode-go/deepseek-v4-flash",
+    "vision": "opencode-go/qwen3.6-plus",
+    "visual-director": "opencode-go/deepseek-v4-flash",
+    "visual-critic": "opencode-go/glm-5.3-flash"
+  }
+}
 ```
 
----
+### free profile
 
-## Skills
+Uses only OpenCode Free models (zero cost). The profile auto-picks the best
+available free model per agent role using a candidate chain.
 
-Each DevLoom agent loads domain-specific skills at startup that guide its workflow:
+The orchestrator leads with `big-pickle` (strong free-tier routing). Role fallback order:
+- **orchestration**: big-pickle → muse-spark-1.3-contributor-free →
+  mimo-v2.5-free → muse-spark-1.2-contributor-free → nemotron-3.5-lightning-free → nemotron-3-ultra-free → ling-3.0-flash-fin-free
+- **implementation / verification**: big-pickle → muse-spark-1.3-contributor-free →
+  nemotron-3.5-lightning-free → mimo-v2.5-free → nemotron-3-ultra-free → ling-3.0-flash-fin-free
+- **planning**: nemotron-3-ultra-free → muse-spark-1.3-contributor-free → muse-spark-1.2-contributor-free →
+  big-pickle → nemotron-3.5-lightning-free → ling-3.0-flash-fin-free
+- **documentation**: muse-spark-1.3-contributor-free → muse-spark-1.2-contributor-free → nemotron-3-ultra-free →
+  mimo-v2.5-free → ling-3.0-flash-fin-free
+- **vision** (vision-capable models only): mimo-v2.5-free → go multimodal fallbacks
+  (deepseek-v4-flash-vision-exp, minimax-m3, mimo-v2.5-pro — ordered by cost, cheapest first)
+- **visual-director / visual-critic**: resolve through the same vision candidate
+  chain (they are vision-capable roles)
 
-| Agent | Skills |
-|---|---|
-| **analyst** | `skill-discovery`, `requirements-analysis` |
-| **architect** | `skill-discovery`, `architecture-planning`, `api-design` |
-| **developer** | `skill-discovery`, `incremental-development`, `test-driven-development`, `frontend-development`, `backend-development`, `api-design` |
-| **qa** | `skill-discovery`, `quality-assurance`, `code-review`, `security-review`, `performance-review`, `debugging` |
-| **documenter** | `skill-discovery`, `documentation` |
-| **orchestrator** | `skill-discovery` |
+### mimo profile
+
+All 10 roles mapped to MiMo V2.6 Flash — a multimodal all-role stack, so the
+same model also covers vision and visual-critic (no separate vision provider):
+
+```json
+{
+  "models": {
+    "orchestrator": "opencode-go/mimo-v2.6-flash",
+    "planner": "opencode-go/mimo-v2.6-flash",
+    "developer": "opencode-go/mimo-v2.6-flash",
+    "qa": "opencode-go/mimo-v2.6-flash",
+    "verifier": "opencode-go/mimo-v2.6-flash",
+    "security": "opencode-go/mimo-v2.6-flash",
+    "documenter": "opencode-go/mimo-v2.6-flash",
+    "vision": "opencode-go/mimo-v2.6-flash",
+    "visual-director": "opencode-go/mimo-v2.6-flash",
+    "visual-critic": "opencode-go/mimo-v2.6-flash"
+  }
+}
+```
 
-Skills auto-detect the task type (FE, BE, security, docs, etc.) and load the
-right workflow. All skills are in `skills/` and are copied to
-`~/.config/opencode/skills/` during install.
+The actual id is the first available candidate from the chain
+`mimo/mimo-v2.6-flash` → `xiaomi/mimo-v2.6-flash` → `opencode-go/mimo-v2.6-flash`,
+checked against `opencode models`. If no MiMo V2.6 Flash candidate is available,
+profile activation FAILS with a diagnostic listing the attempted candidates and
+compatible models found — it never silently substitutes unrelated models (a
+same-family fallback such as `mimo-v2.6-pro` is allowed but always reported
+under "Fallbacks applied"). Tier overrides are locked for `mimo` (like
+`go-flash` and `free`). Switch with `/devloom-mimo` (`profile.mjs set mimo`).
+
+### Model-routing table (go)
+
+Each of the 10 agents is assigned a model optimized for its role:
+
+| Agent | Role | Standard Tier | Senior Tier |
+|---|---|---|---|
+| `orchestrator` | Triage, routing, state, gate | `deepseek-v4-flash` | `deepseek-v4-flash` |
+| `planner` | Requirements + CleanArch plan | `qwen3.7-max` | `glm-5.2` |
+| `developer` | Implementation + root-cause fixes | `glm-5.3-flash` | `kimi-k3` |
+| `qa` | Tests, lint, code review, regression | `v4-flash` | `v4-pro` |
+| `verifier` | Runtime app checks + peer review | `v4-flash` | `v4-pro` |
+| `security` | CRUD/exposure forensic review | `v4-flash` | `glm-5.2` |
+| `documenter` | Docs + state updates | `v4-flash` | `qwen3.7-plus` |
+| `vision` | Image analysis (multimodal) | `qwen3.6-plus` | `qwen3.6-plus` |
+| `visual-director` | Visual direction + design memory | `glm-5.3-flash` | `glm-5.2` |
+| `visual-critic` | Independent visual review (multimodal) | `glm-5.3-flash` | `glm-5.3-flash` |
+
+### Tier system (complexity-based agent selection)
+
+The orchestrator automatically classifies each prompt by complexity and calls the
+correct variant sub-agent by name — no global state switching. Each variant has
+a fixed model in its agent file, so parallel worktrees never conflict.
+
+| Tier | When | Agent Variant | Model |
+|------|------|--------------|-------|
+| **senior** | Complex feature, architecture, security audit, debugging | `-senior` suffix (planner, developer, security) | GLM-5.2, Kimi K3 |
+| **standard** | Everything else (default) | Base agents (no suffix) | deepseek-v4-flash, qwen3.7-max, kimi-k2.7-code |
+
+### Provider-agnostic model IDs
+
+Model IDs are validated as `provider/model` — any OpenCode provider works, and
+the model segment may itself contain slashes (e.g. `lmstudio/google/gemma-...`):
+
+| Correct | Wrong |
+|---|---|
+| `mimo/mimo-v2.6-flash` | `mimo-v2.6-flash` |
+| `opencode-go/deepseek-v4-pro` | `deepseek-v4-pro` |
+
+Availability is checked against `opencode models`: a well-formed but
+unavailable model still fails validation. Bare ids without a provider
+(`deepseek-v4-flash`, `invalid-no-provider`) are invalid. Unavailable models
+fail validation or fall back per profile policy.
+
+### First-run interactive setup
+
+If no `config.json` exists, Phase 0 detects available models (`opencode models`),
+asks which profile to use (**go**, **go-economy**, **mimo**, or **free**), then
+assigns the best model per agent role for the chosen profile.
+
+### Profile & sidebar visibility
+
+OpenCode installs npm plugins into a package cache (`~/.cache/opencode/packages`)
+with `ignoreScripts`, so the DevLoom plugin code there can go stale. The DevLoom
+`postinstall` and the `/devloom-refresh` command re-copy the current plugin code
+(including the `config` hook that injects all 17 DevLoom agents + the active
+profile into the OpenCode sidebar) into that cache, rebuilding `dist/` from
+source first so the cache never receives stale compiled code.
+
+- After installing or updating DevLoom, run `/devloom-refresh` once, then
+  **restart opencode** (or continue with `opencode --continue`) to pick up the
+  refreshed plugin.
+- The sidebar header shows the active profile (`DevLoom - free`,
+  `DevLoom - go`, ...) and every agent row shows its resolved model
+  (`orchestrator: opencode/big-pickle`, ...). The orchestrator
+  agent description also carries the profile label:
+  `DevLoom Orchestrator: autonomous multi-agent delivery (profile: go-flash)`,
+  extended to `(profile: go, tier: senior)` with a senior tier override.
+- The sidebar shows only the 10 base agents — all `-flash` and `-senior`
+  variants are hidden for every profile. The variants stay registered so
+  orchestrator `task()` routing keeps working; they are simply not listed.
+- Switching profiles (`/devloom-go`, `/devloom-go-flash`, `/devloom-mimo`,
+  `/devloom-free`, ...)
+  updates the installed agent files immediately; restart opencode to see the
+  updated profile and models in the sidebar.
 
 ---
 
-## Persistent State
+## OpenCode Go Optimization
 
-DevLoom uses `.opencode/devloom/` in your project root as shared state:
+DevLoom is **purpose-built for OpenCode Go** -- the premium model tier that
+delivers the highest-quality results from the OpenCode platform.
 
-| File | Purpose |
-|---|---|
-| `requirements.md` | User story, functional requirements, acceptance criteria |
-| `plan.md` | Ordered task checklist, updated as tasks complete |
-| `config.json` | Model assignments per agent role (local override) |
-| `state.json` | Execution state for resume support |
-| `errors.md` | Tasks skipped after repeated failures |
+### Why go?
 
-All files are plain Markdown/JSON — inspect and edit them directly.
+Each agent in the pipeline has different cognitive demands. DevLoom assigns
+role-optimized models via the tier system (senior/standard):
 
----
+| Agent | Standard | Senior (complex) |
+|-------|----------|-------------------|
+| Orchestrator | `deepseek-v4-flash` (fast, reliable routing) | `deepseek-v4-flash` |
+| Planner | `qwen3.7-max` (strong reasoning) | `glm-5.2` (deep analysis) |
+| Developer | `kimi-k2.7-code` (code-specialized) | `kimi-k3` (newest gen) |
+| QA | `v4-flash` (fast review) | `v4-pro` (thorough verification) |
+| Verifier | `v4-flash` (fast checks) | `v4-pro` (deep inspection) |
+| Security | `v4-flash` (light review) | `glm-5.2` (forensic depth) |
+| Documenter | `v4-flash` (fast docs) | `qwen3.7-plus` (quality docs) |
+| Vision | `qwen3.6-plus` (low-cost multimodal) | `qwen3.6-plus` |
 
-## Troubleshooting
+### Token architecture
 
-### Agents not found after install
-```bash
-ls ~/.config/opencode/agents/ | grep devloom
-```
-If empty, re-run: `node $(npm root -g)/devloom/postinstall.mjs`
+DevLoom eliminates redundant protocol loading at the architectural level:
+
+1. **Inline RULES** — Every agent has protocol rules embedded in its own file body. No external LOAD needed.
+2. **Single skill LOAD** — Agents load exactly one file: their skill. No protocol/DSL LOADs.
+3. **Guard injection** — Compliance + state summary injected per turn (already in context).
+4. **Tier degradation** — If a model fails twice, auto-fallback: senior→standard→skip agent.
+
+**Pipeline token cost (planner→dev→qa→verifier→doc, one turn):**
+- Before: ~24KB of LOADed protocol files
+- After: ~8KB of inline rules + skill LOAD
+- Savings: **~65%**
+
+Run `opencode models` to see what's currently available in your environment.
+
+---
 
-### ProviderModelNotFoundError
-An agent file is missing the `opencode/` prefix. DevLoom auto-fixes this when
-loading config.json, but if you edit agent files manually, always use the full
-prefix (e.g. `opencode/deepseek-v4-flash-free`, not `deepseek-v4-flash-free`).
+## Skills
 
-### The weave stops before DEVLOOM_DONE
-Increase `max_steps` in `~/.config/opencode/agents/devloom-orchestrator.md` (default 200).
+DevLoom ships focused skills per agent. Each skill folds in the relevant engineering standards — SOLID, clean code, clean architecture, TDD, UI/UX (WCAG-AA), and forensic root-cause discipline (no workarounds):
+
+| Category | Skill | Agent |
+|----------|-------|-------|
+| `plan/` | planning | planner |
+| `plan/` | verification-planning | planner (evidence path before non-trivial changes) |
+| `build/` | development | developer |
+| `build/` | simplify | developer, qa (behavior-preserving simplification) |
+| `build/` | vision-analysis | vision |
+| `verify/` | quality-assurance | qa |
+| `verify/` | app-verification | verifier |
+| `verify/` | visual-critique, visual-quality-gate, visual-regression | visual-critic, verifier |
+| `design/` | visual-direction | visual-director (always) |
+| `design/` | design-grounding, web-design, app-design, game-design, motion-design, design-system | visual-director (domain-dependent; loads only when routed) |
+| `review/` | security-review | security (CRUD/exposure/auth audit) |
+| `ship/` | documentation | documenter |
+| `meta/` | skill-discovery | orchestrator |
 
 ---
 
-## Demo
+## Project Workspace
+
+Every initialized project gets a persistent workspace at `.opencode/devloom/project/`.
+
+- English-only artifacts for cross-agent consistency
+- Minified JSON for AI-only state files
+- Jira-style local board with stories, tasks, bugs, decisions, and reports
+- Single active ticket by default; unfinished work is always persisted
+- Optional GitHub Project mirror only when the user explicitly enables it
+- Existing legacy project files are normalized in place on `init`, `run`, and `resume`
+- Opening OpenCode in a DevLoom project also normalizes the workspace automatically
+
+---
 
-A working example of what DevLoom produces is available in the [`demo/`](demo/) folder. It was generated from the prompt:
+## Architecture Reference
 
 ```
-/devloom Build a very simple full-stack Task List web app.
+devloom/
++-- src/                          # Plugin source (TypeScript)
++-- agents/                       # 17 agents: 10 base + 7 tier variants
+|   +-- devloom-orchestrator.md
+|   +-- devloom-planner.md / -senior / -flash
+|   +-- devloom-developer.md / -senior / -flash
+|   +-- devloom-qa.md / -flash
+|   +-- devloom-verifier.md
+|   +-- devloom-security.md / -senior
+|   +-- devloom-documenter.md / -flash
+|   +-- devloom-vision.md
+|   +-- devloom-visual-director.md
+|   +-- devloom-visual-critic.md
++-- commands/                     # 17 command files + profile.mjs
++-- skills/                       # 21 skill files + 10 loop skills
+|   +-- plan/         planning, verification-planning
+|   +-- build/        development, simplify, vision-analysis, live-docs
+|   +-- verify/       quality-assurance, app-verification,
+|   |                 visual-critique, visual-quality-gate, visual-regression
+|   +-- design/       visual-direction, design-grounding, web-design,
+|   |                 app-design, game-design, motion-design, design-system
+|   +-- review/       security-review
+|   +-- ship/         documentation
+|   +-- meta/         skill-discovery
+|   +-- loop/         10 loop engineering skills
++-- protocol/                     # Shared protocols + rules.md
++-- .opencode/themes/             # DevLoom Night Owl theme
++-- __tests__/                    # 228 Jest tests
++-- postinstall.mjs               # Auto-installs 17 agents, 16 commands, 21 skills, theme
 ```
+---
 
-The app is a full-stack Task List with an Express + SQLite backend and vanilla JS frontend, including integration tests.
+## Acknowledgements
 
-```bash
-cd demo
-npm install
-npm start
-# Open http://localhost:3000
-```
+DevLoom's skill structure and lifecycle-driven workflow drew inspiration from
+[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) and the
+broader pattern of packaging senior-engineering workflows as agent-readable
+skills.
 
 ---