devloom 1.0.0 → 1.2.0

package/GUIDE.md

@@ -29,7 +29,7 @@ and skill files to your OpenCode global config directory:
 | OS | Config directory |
 |---|---|
 | Linux | `~/.config/opencode/` |
-| macOS | `~/Library/Application Support/opencode/` |
+| macOS | `~/.config/opencode/` |
 | Windows | `%APPDATA%\opencode\` |
 
 Expected output:
@@ -40,20 +40,39 @@ DevLoom — post-install
   Config dir  : /home/you/.config/opencode
   Agents dir  : /home/you/.config/opencode/agents
   Commands dir: /home/you/.config/opencode/commands
+  AI dir      : /home/you/.config/opencode/devloom-ai
 
 Installing agents:
   - Agent: devloom-orchestrator
-  - Agent: devloom-analyst
-  - Agent: devloom-architect
-  - Agent: devloom-developer
-  - Agent: devloom-qa
-  - Agent: devloom-documenter
-
-Installing commands:
-  - Command: /devloom
-  - Command: /devloom-status
-  - Command: /devloom-resume
-  - Command: /devloom-init
+  - Agent: devloom-planner (+ -senior, -flash)
+  - Agent: devloom-developer (+ -senior, -flash)
+  - Agent: devloom-qa (+ -flash)
+  - Agent: devloom-verifier
+  - Agent: devloom-security (+ -senior)
+  - Agent: devloom-documenter (+ -flash)
+  - Agent: devloom-vision
+  - Agent: devloom-visual-director
+  - Agent: devloom-visual-critic
+
+Installing commands (17 total):
+  - /devloom, /devloom-init, /devloom-status, /devloom-resume
+  - /devloom-save, /devloom-agents
+  - /devloom-go, /devloom-go-economy, /devloom-go-flash, /devloom-deepseek
+  - /devloom-mimo, /devloom-deepseek-mimo, /devloom-free, /devloom-auto
+  - /devloom-plan, /devloom-context, /devloom-loop, /devloom-loop-status
+
+Installing skills (21 total):
+  - 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)
+
+Installing theme:
+  - DevLoom Night Owl (auto-activated)
 
 DevLoom installed successfully!
 ```
@@ -89,6 +108,8 @@ project without a global install:
 ```
 
 OpenCode loads it automatically when you open a session in that directory.
+On load, the plugin bootstraps `.opencode/devloom/project/` and normalizes any
+legacy DevLoom workspace files into the compact canonical format.
 
 ---
 
@@ -97,10 +118,20 @@ OpenCode loads it automatically when you open a session in that directory.
 Start OpenCode and open the command palette by typing `/`:
 
 ```
-/devloom          → Weave a full feature from a single prompt
-/devloom-status   → Show current weaving progress
-/devloom-resume   → Resume an interrupted execution
-/devloom-init     → Initialize a project for DevLoom
+/devloom             → Weave a full feature from a single prompt
+/devloom-status      → Show current weaving progress
+/devloom-resume      → Resume an interrupted execution
+/devloom-init        → Initialize a project for DevLoom
+/devloom-save        → Persist current state and pause for the next command
+/devloom-agents      → List all agents and their current model assignments
+/devloom-go          → Switch to Go premium profile
+/devloom-go-economy  → Switch to Go economy profile
+/devloom-go-flash    → Switch to Go flash profile (cheapest paid)
+/devloom-mimo        → Switch to the MiMo V2.6 Flash profile (multimodal all-role stack)
+/devloom-deepseek-mimo → Switch to the hybrid profile (DeepSeek V4.1 general, MiMo V2.6 visual)
+/devloom-free        → Switch to free-tier profile
+/devloom-auto        → Auto-detect best profile for your environment
+/devloom-loop        → Start/stop loop engineering patterns
 ```
 
 Or check installed files directly:
@@ -109,14 +140,23 @@ Or check installed files directly:
 # Linux / macOS
 ls ~/.config/opencode/agents/ | grep devloom
 
-# Expected:
-devloom-analyst.md
-devloom-architect.md
-devloom-developer.md
-devloom-documenter.md
+# Expected (17 agents):
 devloom-orchestrator.md
-devloom-qa.md
-```
+devloom-planner.md          devloom-planner-senior.md      devloom-planner-flash.md
+devloom-developer.md        devloom-developer-senior.md    devloom-developer-flash.md
+devloom-qa.md               devloom-qa-flash.md
+devloom-verifier.md
+devloom-security.md         devloom-security-senior.md
+devloom-documenter.md       devloom-documenter-flash.md
+devloom-vision.md
+devloom-visual-director.md  devloom-visual-critic.md
+```
+
+All installed `devloom-*` subagents are callable by `devloom-orchestrator`
+during normal autonomous runs. You may invoke them manually, but they are not
+restricted to manual-only use.
+The expected behavior is delegation by default: the orchestrator routes and
+persists state, while the matching subagent executes each specialist phase.
 
 ---
 
@@ -124,45 +164,159 @@ devloom-qa.md
 
 ### Default (no config)
 
-All agents default to `opencode/deepseek-v4-flash-free` — the fastest free model.
+All agents default to the best available free model via per-role candidate chains — currently led by `opencode/big-pickle` (orchestrator), `opencode/nemotron-3-ultra-free` (planner), `opencode/big-pickle` (developer/QA/verifier/security) and `opencode/muse-spark-1.2-contributor-free` (documenter).
+
+### Model Routing — Profiles
 
-### Per-project override (recommended)
+DevLoom provides model profiles that trade off quality vs cost:
 
-Create `.opencode/devloom/config.json` in your project root:
+| Profile | Use case | Tier |
+|---|---|---|
+| `go` | Production-grade builds, maximum quality | Go (paid) |
+| `go-economy` | Good quality at lower cost | Go (paid) |
+| `deepseek` | DeepSeek-only stack | Go (paid) |
+| `glm` | GLM-only stack | Go (paid) |
+| `go-flash` | Maximum throughput, minimum cost | Go (paid) |
+| `deepseek-mimo` | Fast general work (DeepSeek V4.1), MiMo V2.6 for graphical/complex roles | Go (paid) |
+| `mimo` | Multimodal all-role stack incl. vision | Go/MiMo |
+| `free` | Zero-cost experimentation | Free |
+
+The profile determines which model is assigned to each of the 10 agent roles.
+Premium roles (planner, QA, verifier, security) get stronger models; the
+`vision` and `visual-critic` roles always get a multimodal model regardless of
+profile.
+
+#### go (max quality)
+
+```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
+
+```json
+{
+  "models": {
+    "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"
+  }
+}
+```
+
+#### go-flash
+
+```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"
+  }
+}
+```
+
+#### deepseek
+
+```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"
+  }
+}
+```
+
+#### free
 
 ```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"
+    "planner": "opencode/nemotron-3-ultra-free",
+    "developer": "opencode/big-pickle",
+    "qa": "opencode/big-pickle",
+    "verifier": "opencode/big-pickle",
+    "security": "opencode/big-pickle",
+    "documenter": "opencode/muse-spark-1.2-contributor-free",
+    "vision": "opencode/mimo-v2.5-free",
+    "visual-director": "opencode/mimo-v2.5-free",
+    "visual-critic": "opencode/mimo-v2.5-free"
   }
 }
 ```
 
-Every DevLoom command (`/devloom`, `/devloom-init`, `/devloom-resume`) reads
-this file before invoking the orchestrator and applies the models to the
-global agent files. **Local config always wins.**
+### Complexity tiers (name-based agent selection)
+
+The orchestrator classifies every prompt by complexity and calls the correct
+variant sub-agent by name — no global state switching. Each variant has a fixed
+model, so worktrees never conflict.
 
-### Prefix requirement
+| Tier | Classification | Agent Variants | Model |
+|------|---------------|---------------|-------|
+| **senior** | Complex feature, architecture, debugging, security audit | `-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 |
+| **senior developer** | (when senior tier is selected) | devloom-developer-senior | `kimi-k3` |
 
-All models MUST use the `opencode/` or `opencode-go/` prefix:
+### Per-project override
+
+Create `.opencode/devloom/config.json` in your project root with your chosen profile above. Every DevLoom command (`/devloom`, `/devloom-init`, `/devloom-resume`) reads this file before invoking the orchestrator and applies the models to the global agent files. Local config always wins.
+
+You can also override individual agents by providing a partial `models` map — only specified roles are changed, others keep their existing assignment.
+
+### 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 |
 |---|---|
-| `opencode/deepseek-v4-flash-free` | `deepseek-v4-flash-free` |
+| `mimo/mimo-v2.6-flash` | `mimo-v2.6-flash` |
 | `opencode-go/deepseek-v4-pro` | `deepseek-v4-pro` |
 
-If you forget the prefix, DevLoom adds it automatically and logs a warning.
+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 whether to use **Free** (`opencode/`) or **Go** (`opencode-go/`) tier,
-then assigns the best available model per agent role.
+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 models per agent role matching the selected profile.
 
 ### Available models
 
@@ -170,39 +324,83 @@ then assigns the best available model per agent role.
 
 | Model string |
 |---|
-| `opencode/deepseek-v4-flash-free` |
-| `opencode/minimax-m2.5-free` |
-| `opencode/nemotron-3-super-free` |
 | `opencode/big-pickle` |
+| `opencode/ling-3.0-flash-fin-free` |
+| `opencode/mimo-v2.5-free` |
+| `opencode/muse-spark-1.2-contributor-free` |
+| `opencode/muse-spark-1.3-contributor-free` |
+| `opencode/nemotron-3-ultra-free` |
+| `opencode/nemotron-3.5-lightning-free` |
 
-**Go tier** (`opencode-go/` — higher quality):
+**Go tier** (`opencode-go/` — higher quality, paid):
 
 | Model string |
 |---|
-| `opencode-go/deepseek-v4-pro` |
-| `opencode-go/deepseek-v4-flash` |
-| `opencode-go/kimi-k2.5` |
-| `opencode-go/kimi-k2.6` |
 | `opencode-go/glm-5` |
 | `opencode-go/glm-5.1` |
+| `opencode-go/kimi-k2.5` |
+| `opencode-go/kimi-k2.6` |
+| `opencode-go/deepseek-v4-pro` |
+| `opencode-go/deepseek-v4-flash` |
 | `opencode-go/minimax-m2.5` |
 | `opencode-go/minimax-m2.7` |
+| `opencode-go/minimax-m3` |
 | `opencode-go/mimo-v2.5` |
 | `opencode-go/mimo-v2.5-pro` |
-| `opencode-go/qwen3.5-plus` |
 | `opencode-go/qwen3.6-plus` |
+| `opencode-go/qwen3.7-plus` |
+| `opencode-go/qwen3.7-max` |
+
+### Checking available models
 
-Run `opencode models` to see what's currently available in your environment.
+Run `opencode models` in your terminal to see which models are currently available in your environment. Available models vary by region and subscription tier.
 
 ### Global override (advanced)
 
 Edit the agent files at `~/.config/opencode/agents/` directly:
 
 ```bash
-sed -i 's|^model:.*|model: opencode/deepseek-v4-flash-free|' \
+sed -i 's|^model:.*|model: opencode-go/deepseek-v4-pro|' \
   ~/.config/opencode/agents/devloom-*.md
 ```
 
+### Updating global agents after config change
+
+After modifying `.opencode/devloom/config.json` (e.g., switching profiles or overriding individual models), run `/devloom-init` or start a new weave with `/devloom`. DevLoom re-reads the config and updates the global agent files at `~/.config/opencode/agents/devloom-*.md` automatically.
+
+If you prefer a manual refresh:
+
+```bash
+node $(npm root -g)/devloom/postinstall.mjs
+```
+
+This re-installs agent files from the installed package. Then start a weave to apply your config models.
+
+### Profile and agents in the sidebar
+
+OpenCode installs npm plugins into `~/.cache/opencode/packages/` with
+`ignoreScripts`, so the DevLoom plugin code there can go stale. When it does,
+the plugin's `config` hook never runs and the sidebar does not reflect the
+profile or the injected agent configs. DevLoom keeps that cache in sync:
+
+- The package `postinstall` and the `/devloom-refresh` command re-copy the
+  current plugin code (the hook that injects all 17 agents + the active
+  profile) into the OpenCode plugin cache. The refresh rebuilds `dist/` from
+  source first, so the cache never receives stale compiled code.
+- The sidebar header shows the active profile (`DevLoom - free`, `DevLoom - go`,
+  ...) and every agent row shows its resolved model (e.g.
+  `orchestrator: opencode/big-pickle`). The active profile is also
+  visible on the orchestrator agent description:
+  `DevLoom Orchestrator: autonomous multi-agent delivery (profile: go-flash)`.
+  With a senior tier override the label is extended to
+  `(profile: go, tier: senior)`.
+- The sidebar shows only the 10 base agents — all `-flash` and `-senior`
+  variants are hidden for every profile. All 17 agents stay registered, so the
+  orchestrator can still delegate to hidden variants via `task()`.
+- After installing/updating DevLoom or switching profiles, **restart opencode**
+  (or continue with `opencode --continue`) to see the updated profile and
+  agents in the sidebar.
+
 ---
 
 ## Usage
@@ -216,6 +414,10 @@ cd /path/to/your/project
 opencode
 ```
 
+If this is the first time DevLoom is used in the project, or the project has an
+older DevLoom workspace, plugin startup normalizes `.opencode/devloom/project/`
+before command execution.
+
 #### Option 1 — Slash command (recommended)
 
 ```
@@ -238,7 +440,12 @@ opencode run "/devloom Add OpenTelemetry tracing to all HTTP handlers"
 
 ### What happens after you submit the prompt
 
-DevLoom works through phases automatically:
+The orchestrator first **triages** the prompt and picks the minimal agent chain
+for the intent (bug → developer-fix>qa-regression; docs → planner>documenter;
+small change → developer>qa; etc. — see `workflow.dsl` CHAINS). Verifier
+agents are added only when the work touches their surface (UI, API, CRUD/data
+exposure, user flows). The full sequence below runs only for a feature that
+touches all surfaces:
 
 **Phase 0 — Model Setup**
 
@@ -248,29 +455,77 @@ preference (Free or Go tier), and assigns models per agent role.
 
 **Phase 1 — Understand & Plan**
 
-The Analyst explores your codebase and writes `.opencode/devloom/requirements.md`.
-The Architect reads the requirements and writes `.opencode/devloom/plan.md`
-with an ordered, dependency-resolved task list.
+The Planner explores your codebase, writes `.opencode/devloom/requirements.md`,
+then a CleanArch `.opencode/devloom/plan.md` with an ordered, dependency-resolved
+task list (it can run REQ-only, PLAN-only, or both).
+Before phase routing, the orchestrator appends the current user prompt as the
+last item in `.opencode/devloom/project/tasks/TODO.md`, loads relevant memory
+and skills, and keeps ticket/todo/plan artifacts synchronized.
 
-**Phase 2 — Weave**
+**Phase 2 — Implementation & QA Loop**
 
 For each task in the plan:
-1. The Developer implements the code.
-2. QA writes tests, runs the linter, runs the full test suite, and reports
-   `QA_PASS` or `QA_FAIL`.
-3. On failure: the Orchestrator passes the exact failure details back to the
-   Developer for targeted fixes, then QA re-runs. This repeats until the
-   task passes (max 3 attempts, then skipped).
+1. The Developer implements the code (TDD, SOLID, clean architecture).
+2. QA writes tests, runs the linter, runs the full test suite, reviews the code,
+   runs targeted regression, and reports `QA_PASS` or `QA_FAIL`.
+3. On failure: the Orchestrator routes the defect back to the Developer for a
+   root-cause fix (no workarounds), then QA regression. Up to 3 fix cycles per
+   defect, then the ticket is marked blocked.
 4. The Orchestrator marks the task `[x]` in `.opencode/devloom/plan.md`.
 
-**Phase 3 — Finish & Deliver**
+**Runtime verification (only when the change touches a surface)**
+
+A single Verifier agent runs the requested scope(s) against the running app —
+the running app is the source of truth, not specs. Scopes:
+- `explore` — discover routes, pages, buttons, forms, modals, tables.
+- `route` + `dom` — HTTP status, content, console errors, DOM integrity.
+- `form` — valid/invalid/boundary submissions, validation, loading/error/success.
+- `a11y` — ARIA, labels, keyboard nav, focus, contrast, semantic HTML.
+- `api` + `contract` — auth, validation, schema, status codes; runtime vs OpenAPI.
+- `journey` + `state` — generated user flows and state-transition coverage.
+
+The orchestrator adds only the scopes the change requires (UI → route/form/a11y,
+API → api/contract, user flow → journey/state).
+
+**Security (mandatory on exposure)**
+
+The `devloom-security` subagent is mandatory whenever a CRUD endpoint changes or
+when a component/module starts exposing internal data through input or output
+boundaries. It performs a forensic, evidence-based review.
+
+**Acceptance Gate (Final)**
+
+The Documenter updates README.md and any API docs.
+The Orchestrator runs the final acceptance gate against the criteria relevant to
+the chosen chain:
 
-The Documenter updates `README.md` and any API docs.
-The Orchestrator runs the final build + test gate.
-When everything is green, you see:
+```
+build: pass
+lint: pass
+unit_tests: pass
+integration_tests: pass
+e2e_tests: pass
+all_routes_visited: pass
+all_buttons_tested: pass
+all_forms_tested: pass
+all_links_verified: pass
+all_user_journeys_passed: pass
+all_api_endpoints_verified: pass
+accessibility_verified: pass
+responsive_layout_verified: pass
+visual_validation_verified: pass
+performance_validation_verified: pass
+security_validation_verified: pass
+no_open_defects: pass
+```
 
+If any gate fails, the Orchestrator routes back to the Developer for a
+root-cause fix and re-verification. `DEVLOOM_DONE` is output only when all gates
+for the chosen chain pass.
+
+Completed output example:
 ```
-DEVLOOM_DONE
+DEVLOOM_DONE — ALL GATES PASSED
 
 Completed 8 tasks:
   - Task 1: Database schema and migration
@@ -351,17 +606,102 @@ without starting a weave:
 
 ---
 
+## Incremental Briefing (token savings)
+
+Sub-agents must not re-read the same files on every dispatch. DevLoom solves
+this with a per-ticket briefing plus change-based invalidation:
+
+- **Ticket start:** the orchestrator runs `briefing.mjs init <ticket>` and
+  writes `.opencode/devloom/context/briefing.md` ONCE (goal, constraints,
+  file map with `file:line` refs, decisions).
+- **Every `task()` prompt** starts with `Read .opencode/devloom/context/briefing.md
+  first — do not re-discover` — sub-agents start from the map instead of
+  scanning the repo. A stable prompt prefix also gets provider prompt-caching.
+- **Before each later dispatch:** `briefing.mjs changed` prints only the paths
+  whose content fingerprints differ from the last anchor (sha256, recorded at
+  `init`/`touch` — works inside or outside git and never re-flags a file that
+  was already re-read). The orchestrator re-reads ONLY those, patches the
+  briefing, runs `briefing.mjs touch`, and dispatches. Unchanged files are
+  never re-read.
+
+Script discovery uses the same fallback chain as `profile.mjs`:
+`~/.config/opencode/commands/briefing.mjs` → `~/.config/opencode/devloom-scripts/briefing.mjs`
+→ `scripts/briefing.mjs`.
+
+## Visual 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.
+
+---
+
+## Loop Engineering
+
+DevLoom ships a cadence-driven execution system for recurring agent tasks. Seven
+loop patterns are available out of the box: `daily-triage`, `pr-babysitter`,
+`ci-sweeper`, `dependency-sweeper`, `changelog-drafter`, `post-merge-cleanup`,
+and `issue-triage`.
+
+Each pattern has a matching skill under `skills/loop/` and a safety level:
+
+- **L1 (report-only)** — observe and report, no modifications
+- **L2 (assisted)** — fix in an isolated worktree with verifier approval
+- **L3 (unattended)** — full autonomous fix-and-close cycle
+
+Start a loop from within OpenCode:
+
+```
+/devloom-loop start daily-triage --cadence "0 8 * * 1-5" --level L2
+```
+
+Run a single tick manually from the terminal:
+
+```bash
+node scripts/loop-run.mjs --pattern daily-triage
+```
+
+The loop system includes a token budget circuit breaker: if a run exceeds its
+allocated budget, the loop auto-pauses and logs the overage. Run
+`/devloom-loop status` to inspect current loop state, last run, and budget
+consumption.
+
+---
+
 ## Skills System
 
-Each agent loads domain-specific skills at session start. The `skill-discovery`
-meta-skill scans the task prompt and auto-loads the right skill (FE, BE, QA,
-security, docs, etc.).
+Each agent loads exactly one skill via its `LOAD:` directive. The skill folds in
+the relevant engineering standards (SOLID, clean code, clean architecture, TDD,
+UI/UX, forensic root-cause discipline). The `skill-discovery` meta-skill maps
+task domains to the right agent skill.
 
-```yaml
-# Each agent declares its skills in YAML frontmatter:
-skill:
-  - skill-discovery
-  - frontend-development
+```
+# Each agent's body declares its skill via LOAD:
+LOAD: ...|~/.config/opencode/skills/build/development.md
 ```
 
 Skills are stored in `~/.config/opencode/skills/` following the
@@ -369,15 +709,39 @@ Skills are stored in `~/.config/opencode/skills/` following the
 
 ```
 skills/
-├── meta/       skill-discovery
-├── define/     requirements-analysis
-├── plan/       architecture-planning
-├── build/      frontend-development, backend-development, api-design,
-│               incremental-development, test-driven-development
-├── verify/     quality-assurance, debugging
-├── review/     code-review, security-review, performance-review
-└── ship/       documentation
-```
+├── meta/       skill-discovery           (orchestrator)
+├── plan/       planning                  (planner)
+│               verification-planning     (planner — evidence path)
+├── build/      development               (developer)
+│               simplify                  (developer, qa)
+│               vision-analysis           (vision)
+│               live-docs                 (developer)
+├── design/     visual-direction          (visual-director — always)
+│               design-grounding          (visual-director)
+│               web-design                (visual-director — WEB_CREATIVE)
+│               app-design                (visual-director — PRODUCT_APP)
+│               game-design               (visual-director — GAME_UI)
+│               motion-design             (visual-director)
+│               design-system             (visual-director — EXISTING_DESIGN_SYSTEM)
+├── verify/     quality-assurance         (qa)
+│               app-verification          (verifier)
+│               visual-critique           (visual-critic)
+│               visual-quality-gate       (verifier)
+│               visual-regression         (verifier)
+├── review/     security-review           (security)
+├── ship/       documentation             (documenter)
+└── loop/       10 loop engineering skills (daily-triage, pr-babysitter, ...)
+```
+
+Discovery mapping for the visual roles: `visual-director` →
+`design/visual-direction` plus its domain design skill
+(`web-design` / `app-design` / `game-design`); `visual-critic` →
+`verify/visual-critique`. Visual skills load only when the orchestrator routes
+to those roles.
+
+Agents may load multiple skills via pipe-separated `LOAD:` directives. For example,
+planner loads both `planning` and `verification-planning`; developer and qa both
+load `development`/or `quality-assurance` plus `simplify`.
 
 ---
 
@@ -398,9 +762,17 @@ node $(npm root -g)/devloom/postinstall.mjs
 
 ### ProviderModelNotFoundError
 
-An agent file has a model string without the `opencode/` prefix. DevLoom
-auto-fixes this when loading `config.json`, but if you edit files manually
-always use the full prefix.
+This error means an agent file references a model that is not available in your environment. Common causes:
+
+1. **Missing provider** — model ids must be `provider/model`; bare ids (e.g. `deepseek-v4-flash`) are invalid and fail validation. DevLoom does not add a provider automatically.
+2. **Model not available** — some Go models may not be available in your region or subscription. Run `opencode models` to list available models.
+3. **Outdated agent files** — global agent files may reference a model that no longer exists. Re-run the installer and apply config:
+
+```bash
+node $(npm root -g)/devloom/postinstall.mjs
+```
+
+Then update your `.opencode/devloom/config.json` with models from the available list and start a new weave.
 
 ### The weave stops before DEVLOOM_DONE
 
@@ -424,14 +796,37 @@ Note: this project uses bun test for testing and bun run build for builds.
 
 ### A task keeps failing QA
 
-The Orchestrator retries a failed task up to 3 times. On the third failure it
-logs the task to `.opencode/devloom/errors.md` and moves on. To manually retry:
+The Orchestrator routes failures to:
+1. Root Cause Analysis — determines the root cause
+2. Repair Agent — applies minimal fix
+3. Regression Verification — re-runs all tests
+
+Up to 3 repair cycles per defect, then the defect is marked `escalated` in the
+registry and the task is skipped. To manually retry an escalated task:
 
 1. Open `.opencode/devloom/plan.md` and change `- [x]` back to `- [ ]`
-2. Remove its entry from `.opencode/devloom/errors.md`
+2. Open `.opencode/devloom/defects.json` and remove or reset the defect
 3. Run `/devloom-status` to confirm it is pending
 4. Resume: `/devloom-resume`
 
+### The acceptance gate is failing
+
+Check `.opencode/devloom/defects.json` for open defects. Common gate failures:
+
+| Gate | Common Cause |
+|------|-------------|
+| `all_routes_visited` | Explorer didn't discover all routes — check app starts correctly |
+| `all_forms_tested` | Form verifier found validation issues — check error/success handling |
+| `no_open_defects` | Defects in registry need repair — run RCA + Repair |
+| `accessibility_verified` | ARIA labels or keyboard nav missing — check semantic HTML |
+| `build` | Repair may have introduced build error — Recovery Agent auto-fixes most |
+
+### The Recovery Agent keeps retrying
+
+The Recovery Agent retries 3 times per failure type. If all 3 attempts fail,
+the defect is marked `escalated`. Check `.opencode/devloom/recovery-log.md`
+for the full recovery attempt history.
+
 ---
 
 ## Uninstalling
@@ -447,39 +842,101 @@ rm -rf ~/.config/opencode/skills/
 
 ---
 
+## Security Considerations
+
+### Permissions
+
+DevLoom operates with your user permissions. It does not escalate privileges.
+The agent `permission` blocks in `~/.config/opencode/agents/devloom-*.md` define
+what each agent can do (edit files, run shell commands, fetch URLs, etc.).
+Review these permissions and restrict them if needed.
+
+**Hard delegation guarantees** — the orchestrator agent's `permission` block
+sets `edit: deny`, `write: deny`, `patch: deny` at the OpenCode level. The model
+cannot bypass this; the only way to produce code is via `task()` delegation to
+sub-agents. Sub-agents have `task: deny`, preventing delegation chains. This is
+enforced by OpenCode itself, not by the plugin — it survives plugin reloads.
+
+### Prompt Sanitization
+
+User prompts are truncated to 4000 characters and control characters are stripped
+before they reach the orchestrator. This provides basic injection prevention.
+However, AI agents may still follow instructions embedded in prompts — always
+review generated output critically.
+
+### Path Traversal Protection
+
+The `postinstall.mjs` script validates all destination paths to ensure they stay
+within the OpenCode config directory (`~/.config/opencode/`). Paths containing
+`..` or absolute paths outside the config directory are rejected.
+
+### Reporting Vulnerabilities
+
+See [SECURITY.md](SECURITY.md) for our responsible disclosure policy.
+
+### Best Practices
+
+- Pin exact versions in `package.json` instead of using ranges.
+- Review all generated code before committing or deploying.
+- Run `npm audit` regularly to check dependency vulnerabilities.
+- Keep DevLoom state in `.opencode/devloom/` and add it to `.gitignore` if you
+  do not want execution state tracked in version control.
+
+---
+
 ## Architecture Reference
 
 ```
 devloom/
 ├── src/
-│   ├── index.ts              # Plugin entry point (exports DevLoomPlugin)
-│   └── plugin.ts             # Lifecycle hooks: event, tool.execute.before/after
-├── agents/
-│   ├── devloom-orchestrator.md   # primary — loop controller
-│   ├── devloom-analyst.md        # subagent — requirements
-│   ├── devloom-architect.md      # subagent — design & task list
-│   ├── devloom-developer.md      # subagent — code implementation
-│   ├── devloom-qa.md             # subagent — tests, lint, verdict
-│   └── devloom-documenter.md     # subagent — docs update
-├── commands/
-│   ├── devloom.md            # /devloom <prompt>
-│   ├── devloom-status.md     # /devloom-status
-│   ├── devloom-resume.md     # /devloom-resume
-│   └── devloom-init.md       # /devloom-init
-├── skills/
+│   ├── index.ts                   # Plugin entry point (exports DevLoomPlugin)
+│   ├── plugin.ts                  # Lifecycle hooks: event, chat.message, tool.execute.before/after
+│   ├── guard.ts                   # Compliance guard, loop detection, state summary
+│   ├── bootstrap.ts               # Project workspace bootstrap
+│   ├── context.ts                 # Architecture atlas generation
+│   ├── loop.ts                    # Loop engineering state
+│   ├── worktree.ts                # Worktree management
+│   └── constraints.ts             # Loop constraints
+├── agents/                         # 17 agents — 10 base + 7 tier variants
+│   ├── devloom-orchestrator.md    # primary — triage, route, state, gate (edit/write/patch: deny)
+│   ├── 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
+│   ├── devloom.md, devloom-init.md, devloom-resume.md, devloom-status.md
+│   ├── devloom-save.md, devloom-agents.md
+│   ├── devloom-go.md, devloom-go-economy.md, devloom-go-flash.md
+│   ├── devloom-deepseek.md, devloom-mimo.md, devloom-free.md, devloom-auto.md
+│   ├── devloom-plan.md, devloom-context.md
+│   └── devloom-loop.md, devloom-loop-status.md
+├── skills/                        # 21 skill files + 10 loop skills
 │   ├── meta/       skill-discovery
-│   ├── define/     requirements-analysis
-│   ├── plan/       architecture-planning
-│   ├── build/      frontend-development, backend-development, api-design,
-│   │               incremental-development, test-driven-development
-│   ├── verify/     quality-assurance, debugging
-│   ├── review/     code-review, security-review, performance-review
-│   └── ship/       documentation
-├── postinstall.mjs           # Copies agents + commands + skills to config dir
+│   ├── plan/       planning, verification-planning
+│   ├── build/      development, simplify, vision-analysis, live-docs
+│   ├── design/     visual-direction, design-grounding, web-design, app-design,
+│   │               game-design, motion-design, design-system
+│   ├── verify/     quality-assurance, app-verification,
+│   │               visual-critique, visual-quality-gate, visual-regression
+│   ├── review/     security-review (full audit playbook)
+│   ├── ship/       documentation
+│   └── loop/       10 loop engineering skills
+├── protocol/                       # Shared protocols (orchestrator-core, agent-contracts, ...)
+├── .opencode/themes/               # DevLoom Night Owl theme
+├── __tests__/                      # 228 unit tests (Jest)
+├── postinstall.mjs                 # Installs 17 agents, 16 commands, 21 skills, theme
+├── SECURITY.md                     # Security policy and disclosure
+├── jest.config.mjs                 # Jest test configuration
 ├── package.json
 ├── tsconfig.json
 ├── README.md
-└── GUIDE.md                  # This file
+├── GUIDE.md                        # This file
+└── .github/workflows/ci.yml        # CI pipeline (Node 18, 20, 22)
 ```
 
 ---