opencode-vision 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# vision — Visual Judgment Skill for opencode
+
+A typed visual-judgment contract for text-only orchestrators (GLM 5.2).
+The orchestrator captures a screenshot via a browser/computer-use MCP,
+extracts the visual-judgment intent, assembles a versioned request JSON,
+delegates to a vision subagent, and parses a typed report.
+
+## What it gives you
+
+- **10 vision subagents** registered programmatically at init — one per
+  top-tier vision model across OpenAI, Kimi for Coding, Ollama Cloud, and
+  opencode-go.
+- **A stable typed contract** — two versioned JSON Schemas
+  (`visual-judgment-request.v1` / `visual-judgment-report.v1`) replace the
+  old "design your own schema" free-for-all.
+- **Per-session model selection** — the skill asks the user once which
+  vision model to use, then reuses it for the rest of the session.
+- **10 judgment types** — `presence`, `absence`, `alignment`, `ordering`,
+  `equality`, `layout`, `readability`, `state`, `diff`, `describe`.
+- **MCP integration** — works with chrome-devtools, Playwright, and
+  cua-driver screenshots. Uses the a11y/AX tree when it answers the
+  question; delegates to a vision subagent only when pixels matter.
+
+## Install
+
+Add the plugin to your `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "opencode-vision"
+  ],
+  "skills": {
+    "paths": [
+      "~/.cache/opencode/node_modules/opencode-vision"
+    ]
+  }
+}
+```
+
+opencode auto-installs the npm package via Bun on next launch — no separate
+`npm install` step needed. The skill ships inside the package (in `SKILL.md`),
+so point `skills.paths` at the installed package location so opencode's skill
+loader can find it.
+
+The old `~/.config/opencode/agents/visual-judge.md` subagent is removed —
+this plugin replaces it with 10 typed `vision-*` subagents. Delete the old
+file if present:
+
+```bash
+rm -f ~/.config/opencode/agents/visual-judge.md
+```
+
+Restart opencode for the config to take effect.
+
+> **Why `skills.paths` points at the installed package:** opencode's plugin
+> loader resolves the npm package to its `dist/index.js` entrypoint and
+> runs the `config(cfg)` hook that registers the 10 subagents. But opencode's
+> *skill* loader scans directories for `SKILL.md` — it does not look inside
+> npm packages automatically. So we point `skills.paths` at the installed
+> package directory, where `SKILL.md` ships as a published file. The path
+> above (`~/.cache/opencode/node_modules/opencode-vision`) is where Bun
+> caches opencode plugins; adjust if your cache lives elsewhere.
+
+## Verify
+
+```bash
+opencode debug agent vision-openai-gpt-5.5
+```
+
+Should show the registered subagent with `model: openai/gpt-5.5`,
+`mode: subagent`.
+
+To list all 10:
+
+```bash
+opencode debug agent vision-openai-gpt-5.5
+opencode debug agent vision-kimi-for-coding-k2p7
+opencode debug agent vision-ollama-cloud-gemini-3-flash-preview
+opencode debug agent vision-ollama-cloud-gemma4-31b
+opencode debug agent vision-ollama-cloud-minimax-m3
+opencode debug agent vision-ollama-cloud-qwen3.5-397b
+opencode debug agent vision-opencode-go-kimi-k2.7-code
+opencode debug agent vision-opencode-go-minimax-m3
+opencode debug agent vision-opencode-go-qwen3.7-plus
+opencode debug agent vision-opencode-go-mimo-v2.5
+```
+
+## Smoke test
+
+Ask the orchestrator something visual:
+
+> Visually verify the screenshot at /tmp/foo.png shows a centered button.
+
+The orchestrator should:
+1. Detect the visual-judgment intent.
+2. Ask you (once) which vision model to use.
+3. Assemble a `visual-judgment-request.v1` JSON with `judgment.type:
+   alignment`.
+4. Delegate to the chosen `vision-*` subagent.
+5. Parse the report and tell you pass/fail with the button's position.
+
+## File layout (source)
+
+```
+opencode/vision/                  # this sub-package, published as opencode-vision
+  package.json                    # npm package metadata; main -> dist/index.js
+  plugin.ts                        # source: registers 10 vision-* subagents via config(cfg)
+  dist/                            # built on prepublishOnly (gitignored)
+    index.js                       # built bundle — the package entrypoint
+  vision-models.json              # 10-entry manifest (one top-tier per provider × family)
+  subagent-body.md                 # shared subagent prompt template
+  SKILL.md                         # intent-capture protocol + per-session question + MCP integration
+  schemas/
+    visual-judgment-request.v1.json
+    visual-judgment-report.v1.json
+  README.md                        # this file
+```
+
+## Build & publish (maintainers)
+
+```bash
+cd opencode/vision
+bun run build                     # builds dist/index.js
+npm publish                       # runs prepublishOnly -> build -> publish
+```
+
+The `files` field in `package.json` controls what ships: `dist/`,
+`SKILL.md`, `schemas/`, `subagent-body.md`, `vision-models.json`,
+`README.md`. No source `.ts` or `node_modules` leak.
+
+## Catalog (10 models, 4 providers)
+
+Curation rule: one top-tier model per provider × vendor family; drop
+non-reasoning, drop superseded within a provider, drop coding-specialized,
+drop Pro/billing variants of the same family; keep cross-provider
+duplicates.
+
+| Provider | Model | Family |
+|---|---|---|
+| openai | gpt-5.5 | GPT-5.5 |
+| kimi-for-coding | k2p7 | Kimi K2.7 |
+| ollama-cloud | gemini-3-flash-preview | Gemini |
+| ollama-cloud | gemma4:31b | Gemma |
+| ollama-cloud | minimax-m3 | MiniMax |
+| ollama-cloud | qwen3.5:397b | Qwen 3.5 |
+| opencode-go | kimi-k2.7-code | Kimi K2.7 (cross-provider route) |
+| opencode-go | minimax-m3 | MiniMax (cross-provider route) |
+| opencode-go | qwen3.7-plus | Qwen 3.7 |
+| opencode-go | mimo-v2.5 | MiMo |
+
+To add a model: add one line to `vision-models.json` and restart opencode.
+The plugin re-reads the manifest at init.
+
+## Schemas
+
+Published via GitHub raw URLs (branch `main`):
+
+- Request: `https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-request.v1.json`
+- Report: `https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-report.v1.json`
+
+The files also live in this repo under `opencode/vision/schemas/` for
+editing. The URL is the canonical `$id`/`$schema` reference used by the
+SKILL.md and subagent body.

package/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: vision
+description: >-
+  Use when you must verify, check, or evaluate what is visually rendered in
+  one or more images — e.g. "visually verify the screenshot shows a centered
+  button", "check the icon is visible", "does the layout match the design",
+  acceptance criteria mentioning on-screen state. Captures visual-judgment
+  intent from user prompts or MCP task outputs, classifies it into a typed
+  judgment, asks the user once per session which vision model to use,
+  assembles a versioned request, delegates to a vision subagent, and parses
+  the typed report. Requires locally-stored image files (cua-driver
+  screenshots, Playwright/chrome-devtools captures, user-provided paths).
+---
+
+# Vision — Visual Judgment Skill
+
+You are a text-only orchestrator (GLM 5.2). You cannot see images. When a
+task requires visual verification, you delegate to a vision subagent that
+returns a typed report. This skill defines the extraction pipeline:
+**Detect → Classify → Assemble → Pick model → Delegate → Parse**.
+
+## Why this skill exists
+
+You are text-only (`attachment: false`). You cannot verify visual properties
+yourself — alignment, color, readability, layout. A vision subagent can.
+This skill gives you a stable contract for talking to one.
+
+## The two schemas
+
+- **Request** (what you emit, passed as the `task` prompt):
+  https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-request.v1.json
+- **Report** (what the subagent returns):
+  https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-report.v1.json
+
+## Step 1. Detect
+
+Visual-judgment intent arrives from two sources. Recognize both.
+
+### Source A — explicit visual-judgment language in a user prompt
+
+Trigger lexicon (any of these suggests visual judgment):
+- "visually verify", "visually check", "screenshot shows"
+- "looks right", "looks wrong", "looks broken"
+- "centered", "aligned", "overlapping", "misaligned"
+- "visible", "hidden", "not showing"
+- "readable", "legible", "too small", "low contrast"
+- "on" / "off" / "checked" / "disabled" (for a control's visual state)
+- "matches the design", "matches the mockup"
+- acceptance criteria mentioning on-screen state
+- a user-provided image path (e.g. `/tmp/foo.png`)
+
+If the user's request contains image-attachment references or a path to a
+screenshot/screenshot file, that is also a trigger.
+
+### Source B — a gap between an MCP task output and a visual criterion
+
+A `browser-use-*` or `computer-use-cua` subagent returned a screenshot
+path plus a text description of what is on screen. But the user's
+criterion is visual (positional, color, readability, layout) and the text
+description cannot fully prove it. You recognize the gap and extract a
+visual-judgment intent from the combination of user criterion + MCP output.
+
+**Example**: user says "log into the app and check the dashboard looks
+right." You spawn `browser-use-chrome-devtools` to navigate + screenshot.
+It returns `/tmp/dashboard.png` + "sidebar with nav items, bar chart,
+welcome header." The text describes structure, but "looks right" is a
+visual layout quality the text can't fully prove → you detect a
+visual-judgment need.
+
+## Step 2. Classify
+
+Map the NL task to one of the 10 closed `judgment.type` values. Each has
+typed `parameters`.
+
+| Type | When to use | Typed parameters |
+|---|---|---|
+| `presence` | Is X visible on screen? | `subject`, `expectation: present\|absent` |
+| `absence` | Is X NOT visible? (dual of presence) | `subject`, `expectation: absent` |
+| `alignment` | Is X centered / left-aligned / top along an axis? | `subject`, `axis`, `expectation`, `tolerance` |
+| `ordering` | Are items in expected left-to-right or top-to-bottom order? | `direction: ltr\|ttb`, `expected[]` |
+| `equality` | Do two images render the same thing? | `subjects[2]`, `threshold: exact\|perceptual` |
+| `layout` | Open-ended structural check (arrangement, spacing) | `expectations` (NL) |
+| `readability` | Is text legible? (contrast, size) | `subject` |
+| `state` | Is a control in a given state? (toggle, checkbox) | `subject`, `expectedState` |
+| `diff` | What changed between two screenshots? | `baseline`, `current` (image labels) |
+| `describe` | Open-ended description of what's on screen | `focus` |
+
+Worked examples (one per type) are in the appendix at the bottom of this
+file. When in doubt, pick the most specific type that fits; fall back to
+`describe` if nothing fits.
+
+## Step 3. Assemble
+
+Construct the `visual-judgment-request.v1` JSON object.
+
+### 3a. Gather image paths
+
+Image paths come from:
+
+| Source | How to get the path |
+|---|---|
+| User-provided | Use the path the user gave (e.g. `/tmp/foo.png`). |
+| chrome-devtools MCP | `chrome-devtools_take_screenshot({ filePath: "/tmp/shot.png" })` — saves PNG to disk. |
+| Playwright MCP | `playwright_browser_take_screenshot({ filename: "shot.png" })` — saves to the configured output directory. |
+| cua-driver MCP | `cua-driver_get_window_state({ pid, window_id, screenshot_out_file: "/tmp/win.png" })` — saves window screenshot to disk. Also returns the AX tree as text. |
+| Browser-use subagent output | The subagent returns the path in its text response; extract it. |
+
+For each image, assign a `label` (short, used in `observations[].imageLabel`)
+and a `role` (`baseline` = before/reference, `current` = the thing under
+test, `reference` = design target).
+
+### 3b. Dual-track: a11y tree vs. visual judgment
+
+Before delegating, check whether the text tree already answers the
+question. All three MCPs (chrome-devtools, Playwright, cua-driver) return
+an accessibility/AX tree alongside the screenshot. You can read that text
+directly — no vision call needed.
+
+| Criterion | Source | Delegate to vision? |
+|---|---|---|
+| "Button exists" | a11y tree (element present) | No |
+| "Button is enabled/disabled" | a11y tree (`AXEnabled`) | No |
+| "Button text says 'Submit'" | a11y tree (`AXTitle`/`AXValue`) | No |
+| "Button is centered" | Screenshot (positional) | **Yes** |
+| "Text is readable" | Screenshot (contrast/size) | **Yes** |
+| "Toggle is blue" | Screenshot (color) | **Yes** |
+| "Layout matches design" | Screenshot (structural) | **Yes** |
+| "Two screenshots are identical" | Screenshot pair | **Yes** |
+
+Use the cheap text source first. Only pay for a vision call when the text
+tree cannot answer.
+
+### 3c. Fill typed parameters + NL criteria
+
+Fill `judgment.parameters` per the type (Step 2 table). If the typed
+parameters cannot fully express the nuance, add a free-form `criteria`
+string as a fallback for the subagent. Also set `responseContract` if you
+want something specific back beyond the fixed report envelope.
+
+### 3d. Edge case — MCP output has no screenshot path
+
+If a browser-use subagent returned only text (no path) but a visual
+judgment is still needed, capture a screenshot yourself by driving the
+MCP directly (see 3a table), or re-task the subagent with explicit
+screenshot-save instructions.
+
+### 3e. Edge case — built-in computer-use MCP
+
+The built-in Claude Code `computer-use` MCP returns screenshots as inline
+base64 images, not file paths. You cannot see inline images (you are
+text-only), and the vision subagent needs a file path to `read`. Prefer
+`cua-driver` for desktop visual judgments — it has `screenshot_out_file`.
+
+## Step 4. Pick model (once per session)
+
+opencode has no per-call model override and no LLM-set session variable.
+The model choice is carried in your own context for the rest of the
+session.
+
+**On the first visual-judgment need in a session**, before delegating,
+call the `question` tool once:
+
+```
+question({
+  questions: [{
+    header: "Vision model",
+    question: "I found several models that support vision tasks. Which model would you prefer for visual judgments this session?",
+    options: [
+      { label: "openai/gpt-5.5", description: "Highest accuracy (Recommended)" },
+      { label: "kimi-for-coding/k2p7", description: "Kimi K2.7 Code" },
+      { label: "ollama-cloud/gemini-3-flash-preview", description: "Gemini 3 Flash, 1M context" },
+      { label: "ollama-cloud/gemma4:31b", description: "Gemma 4 31B" },
+      { label: "ollama-cloud/minimax-m3", description: "MiniMax M3" },
+      { label: "ollama-cloud/qwen3.5:397b", description: "Qwen 3.5 397B" },
+      { label: "opencode-go/kimi-k2.7-code", description: "Kimi K2.7 Code via opencode-go" },
+      { label: "opencode-go/minimax-m3", description: "MiniMax M3 via opencode-go" },
+      { label: "opencode-go/qwen3.7-plus", description: "Qwen 3.7 Plus, 1M context" },
+      { label: "opencode-go/mimo-v2.5", description: "MiMo V2.5, 1M context" }
+    ]
+  }]
+})
+```
+
+The tool auto-adds an "Other" option (type your own). After the user
+answers:
+
+- Map the answer to a `subagent_type` via the table below.
+- Remember the choice for the rest of the session. Do not ask again.
+  Reuse the chosen model for all subsequent visual judgments in this
+  session.
+- If the user picks "Other" and types a model id, map it to the closest
+  matching `vision-*` subagent from the table, or fall back to
+  `vision-openai-gpt-5.5` if no match.
+
+### `preferredModel → subagent_type` mapping table
+
+```
+openai/gpt-5.5                       -> vision-openai-gpt-5.5
+kimi-for-coding/k2p7                 -> vision-kimi-for-coding-k2p7
+ollama-cloud/gemini-3-flash-preview  -> vision-ollama-cloud-gemini-3-flash-preview
+ollama-cloud/gemma4:31b              -> vision-ollama-cloud-gemma4-31b
+ollama-cloud/minimax-m3              -> vision-ollama-cloud-minimax-m3
+ollama-cloud/qwen3.5:397b            -> vision-ollama-cloud-qwen3.5-397b
+opencode-go/kimi-k2.7-code           -> vision-opencode-go-kimi-k2.7-code
+opencode-go/minimax-m3               -> vision-opencode-go-minimax-m3
+opencode-go/qwen3.7-plus             -> vision-opencode-go-qwen3.7-plus
+opencode-go/mimo-v2.5                -> vision-opencode-go-mimo-v2.5
+```
+
+## Step 5. Delegate
+
+Spawn the subagent with the assembled request JSON as the `prompt`:
+
+```
+task({
+  subagent_type: "<mapped subagent_type>",
+  description: "<short, e.g. 'Verify Submit button is centered'>",
+  prompt: <the full visual-judgment-request.v1 JSON object>
+})
+```
+
+## Step 6. Parse
+
+The subagent returns a `visual-judgment-report.v1` JSON object. Branch on
+`status` and `verdict`:
+
+- `status: "ok"` + `verdict: "pass"` → criterion met. Report success to
+  the user, citing `observations[]` as evidence.
+- `status: "ok"` + `verdict: "fail"` → criterion not met. Report failure,
+  citing the specific `observations[]` (e.g. "button is 42px right of
+  center"). Include `reasoning`.
+- `status: "ok"` + `verdict: "inconclusive"` → informational (for `diff`
+  and `describe`) or genuinely undeterminable. Surface `observations[]`
+  and `diff[]` directly to the user.
+- `status: "error"` → the subagent could not analyze the image(s). Check
+  `errors[]` (codes: `file_not_found`, `unsupported_format`,
+  `model_unavailable`). If `model_unavailable`, retry with a different
+  model from the mapping table, or re-ask the user.
+- `status: "insufficient-evidence"` → the subagent analyzed the image but
+  cannot reach a verdict. Report this honestly; do not pretend a verdict.
+
+Surface `observations[]` as citations so the user sees what the subagent
+actually saw. Include `confidence` in your report to the user.
+
+## Two integration patterns
+
+### Pattern 1 — Direct (simple "screenshot + judge")
+
+Use when the browser/desktop interaction is trivial (just navigate and
+look). You drive the MCP directly, capture one screenshot, delegate one
+judgment.
+
+```
+You: chrome-devtools_navigate_page({ url: "http://localhost:3000" })
+You: chrome-devtools_take_screenshot({ filePath: "/tmp/login.png" })
+You: [assemble request with /tmp/login.png]
+You: task({ subagent_type: "vision-openai-gpt-5.5", prompt: <request> })
+```
+
+### Pattern 2 — Two-phase (complex interaction, then judge)
+
+Use when interaction is non-trivial (navigate, click, fill, navigate
+again). You spawn a `browser-use-*` or `computer-use-cua` subagent to
+perform the interaction and capture a screenshot. It returns the path.
+You then delegate to a `vision-*` subagent.
+
+```
+You: task({
+  subagent_type: "browser-use-chrome-devtools",
+  prompt: "Navigate to /login, fill credentials, click Submit, wait for
+           dashboard, take a screenshot to /tmp/dashboard.png. Return
+           the file path and a brief text description."
+})
+  -> subagent returns: "/tmp/dashboard.png, sidebar + chart + header"
+You: [assemble request with /tmp/dashboard.png, judgment.type=layout]
+You: task({ subagent_type: "vision-openai-gpt-5.5", prompt: <request> })
+```
+
+Separation of concerns: the browser subagent knows how to drive; the
+vision subagent knows how to see.
+
+---
+
+## Appendix — worked examples per judgment type
+
+### presence — "is X visible?"
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-request.v1.json",
+  "id": "vj-001",
+  "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/login.png", "label": "login-screen", "role": "current" }],
+  "judgment": { "type": "presence", "parameters": { "subject": "Submit button", "expectation": "present" } },
+  "criteria": "A clickable button labeled 'Submit' or equivalent, within the login form area.",
+  "responseContract": "Return pass/fail and note the button's position if found."
+}
+```
+
+### absence — "is X NOT visible?"
+```json
+{
+  "id": "vj-002", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/post-logout.png", "label": "home", "role": "current" }],
+  "judgment": { "type": "absence", "parameters": { "subject": "error banner", "expectation": "absent" } },
+  "criteria": "No red/error banner at the top of the page or anywhere on screen."
+}
+```
+
+### alignment — "is X centered on an axis?"
+```json
+{
+  "id": "vj-003", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/header.png", "label": "header", "role": "current" }],
+  "judgment": { "type": "alignment", "parameters": { "subject": "logo", "axis": "horizontal", "expectation": "centered", "tolerance": "loose" } },
+  "criteria": "Logo should be roughly centered in the header band, allowing minor off-center within ~5%."
+}
+```
+
+### ordering — "are items in expected LTR/TTB order?"
+```json
+{
+  "id": "vj-004", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/nav.png", "label": "navbar", "role": "current" }],
+  "judgment": { "type": "ordering", "parameters": { "direction": "ltr", "expected": ["Home", "Products", "About", "Contact"] } },
+  "criteria": "Items read left-to-right in the specified order."
+}
+```
+
+### equality — "do two images match?"
+```json
+{
+  "id": "vj-005", "preferredModel": "openai/gpt-5.5",
+  "images": [
+    { "path": "/tmp/chart-v1.png", "label": "v1", "role": "baseline" },
+    { "path": "/tmp/chart-v2.png", "label": "v2", "role": "current" }
+  ],
+  "judgment": { "type": "equality", "parameters": { "subjects": ["v1", "v2"], "threshold": "perceptual" } },
+  "criteria": "Minor pixel-level anti-aliasing differences are acceptable; structural differences are not."
+}
+```
+
+### layout — "does the structure match expectations?"
+```json
+{
+  "id": "vj-006", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/form.png", "label": "signup-form", "role": "current" }],
+  "judgment": { "type": "layout", "parameters": { "expectations": "Fields stacked vertically; equal vertical gaps; labels above inputs." } },
+  "criteria": "Email, Password, Confirm Password fields in that top-to-bottom order."
+}
+```
+
+### readability — "is the text legible?"
+```json
+{
+  "id": "vj-007", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/page.png", "label": "page", "role": "current" }],
+  "judgment": { "type": "readability", "parameters": { "subject": "footer text" } },
+  "criteria": "Footer text should be readable at normal viewing distance; not blurry, not too small, sufficient contrast."
+}
+```
+
+### state — "is the control in the expected state?"
+```json
+{
+  "id": "vj-008", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/settings.png", "label": "settings-panel", "role": "current" }],
+  "judgment": { "type": "state", "parameters": { "subject": "notifications toggle", "expectedState": "on" } },
+  "criteria": "Toggle knob should be on the right side with the accent color (blue)."
+}
+```
+
+### diff — "what changed between two screenshots?"
+```json
+{
+  "id": "vj-009", "preferredModel": "openai/gpt-5.5",
+  "images": [
+    { "path": "/tmp/before.png", "label": "before", "role": "baseline" },
+    { "path": "/tmp/after.png", "label": "after", "role": "current" }
+  ],
+  "judgment": { "type": "diff", "parameters": { "baseline": "before", "current": "after" } },
+  "criteria": "Report all visual differences: added/removed/changed elements, color shifts, position changes."
+}
+```
+
+### describe — "what's on screen?"
+```json
+{
+  "id": "vj-010", "preferredModel": "openai/gpt-5.5",
+  "images": [{ "path": "/tmp/screenshot.png", "label": "screen", "role": "current" }],
+  "judgment": { "type": "describe", "parameters": { "focus": "overall layout and primary UI elements" } },
+  "criteria": "Capture: app type, main regions, primary actions, color scheme."
+}
+```
+
+For `diff` and `describe`, expect `verdict: "inconclusive"` — these are
+informational, not pass/fail. Use `diff[]` and `observations[]` directly.

package/dist/index.js

@@ -0,0 +1,44 @@
+// plugin.ts
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+var bundleDir = dirname(fileURLToPath(import.meta.url));
+var candidateDirs = [bundleDir, join(bundleDir, "..")];
+var dataDir = candidateDirs.find((d) => existsSync(join(d, "vision-models.json")) && existsSync(join(d, "subagent-body.md"))) ?? bundleDir;
+var manifest = JSON.parse(readFileSync(join(dataDir, "vision-models.json"), "utf8"));
+var bodyTpl = readFileSync(join(dataDir, "subagent-body.md"), "utf8");
+var PERMISSION = {
+  edit: "deny",
+  read: "allow",
+  glob: "allow",
+  grep: "allow",
+  list: "allow",
+  external_directory: {
+    "/private/tmp/**": "allow",
+    "/private/var/folders/**": "allow"
+  }
+};
+function subagentName(entry) {
+  return "vision-" + entry.provider + "-" + entry.model_id.replace(/[/:]/g, "-");
+}
+var plugin = async () => ({
+  config: async (cfg) => {
+    cfg.agent ??= {};
+    for (const e of manifest.models) {
+      const name = subagentName(e);
+      cfg.agent[name] ??= {};
+      Object.assign(cfg.agent[name], {
+        description: `Visual judgment subagent (${e.name}). Consumes a visual-judgment-request.v1 JSON, analyzes images, emits a visual-judgment-report.v1 JSON. Not coupled to any screenshot tool or UI framework - works with any locally stored image.`,
+        mode: "subagent",
+        model: `${e.provider}/${e.model_id}`,
+        temperature: 0.1,
+        prompt: bodyTpl.replaceAll("{{model_name}}", e.name).replaceAll("{{provider}}", e.provider).replaceAll("{{model_id}}", e.model_id),
+        permission: PERMISSION
+      });
+    }
+  }
+});
+var plugin_default = { id: "vision", server: plugin };
+export {
+  plugin_default as default
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "opencode-vision",
+  "version": "0.1.0",
+  "description": "Typed visual-judgment skill for opencode. Registers 10 vision subagents (one per top-tier vision model across OpenAI, Kimi for Coding, Ollama Cloud, and opencode-go) and a skill that teaches a text-only orchestrator to extract visual-judgment intent, classify it into a typed judgment, and delegate to a vision subagent with a versioned request/report contract.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "schemas",
+    "subagent-body.md",
+    "vision-models.json",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "bun build ./plugin.ts --outfile ./dist/index.js --target node --format esm --packages external",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-ai",
+    "vision",
+    "visual-judgment",
+    "image-analysis",
+    "screenshot",
+    "subagent",
+    "skill"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WeZZard/skills.git",
+    "directory": "opencode/vision"
+  },
+  "homepage": "https://github.com/WeZZard/skills/tree/main/opencode/vision#readme",
+  "bugs": {
+    "url": "https://github.com/WeZZard/skills/issues"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.4.7"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.4.7",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2"
+  }
+}

package/schemas/visual-judgment-report.v1.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-report.v1.json",
+  "title": "Visual Judgment Report v1",
+  "description": "Typed report envelope returned by a vision subagent after analyzing images against a visual-judgment-request.",
+  "type": "object",
+  "required": ["$schema", "id", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-report.v1.json",
+      "description": "Schema version identifier."
+    },
+    "id": {
+      "type": "string",
+      "description": "Correlation id — MUST echo the request id."
+    },
+    "status": {
+      "enum": ["ok", "error", "insufficient-evidence"],
+      "description": "ok = analysis succeeded; error = could not analyze (image corrupt, model unavailable); insufficient-evidence = analyzed but cannot reach a verdict."
+    },
+    "verdict": {
+      "enum": ["pass", "fail", "inconclusive"],
+      "description": "pass = criterion met; fail = criterion not met; inconclusive = informational (diff/describe) or genuinely undeterminable."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "0.0–1.0. How confident the subagent is in the verdict."
+    },
+    "observations": {
+      "type": "array",
+      "description": "Typed observations about what was seen in each image. Structure varies per judgment.type by convention.",
+      "items": {
+        "type": "object",
+        "required": ["imageLabel", "subject"],
+        "additionalProperties": false,
+        "properties": {
+          "imageLabel": { "type": "string", "description": "Label of the image this observation is about (matches request images[].label)." },
+          "subject": { "type": "string", "description": "What this observation describes, e.g. 'Submit button', 'footer text'." },
+          "properties": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Type-specific findings, e.g. {found:true,position:'bottom-center'} for presence, {centerOffsetPx:42} for alignment, {knobPosition:'right',trackColor:'blue'} for state."
+          },
+          "note": { "type": "string", "description": "Free-form clarifying note." }
+        }
+      }
+    },
+    "diff": {
+      "type": "array",
+      "description": "Structured change list (populated for judgment.type=diff).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "from": { "type": "string", "description": "What was there in the baseline." },
+          "to": { "type": "string", "description": "What is there in the current." },
+          "description": { "type": "string", "description": "Human-readable description of the change." }
+        }
+      }
+    },
+    "reasoning": {
+      "type": "string",
+      "description": "One-paragraph justification linking observations to verdict."
+    },
+    "errors": {
+      "type": "array",
+      "description": "Populated when status=error. One entry per image that could not be analyzed.",
+      "items": {
+        "type": "object",
+        "required": ["imageLabel", "code"],
+        "additionalProperties": false,
+        "properties": {
+          "imageLabel": { "type": "string" },
+          "code": { "type": "string", "description": "e.g. 'file_not_found', 'unsupported_format', 'model_unavailable'." }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "ok" } } },
+      "then": { "required": ["verdict", "confidence", "observations"] }
+    }
+  ]
+}

package/schemas/visual-judgment-request.v1.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-request.v1.json",
+  "title": "Visual Judgment Request v1",
+  "description": "Typed intent envelope emitted by the orchestrator and passed as the task prompt to a vision subagent.",
+  "type": "object",
+  "required": ["$schema", "id", "images", "judgment"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-request.v1.json",
+      "description": "Schema version identifier."
+    },
+    "id": {
+      "type": "string",
+      "description": "Correlation id (uuid recommended). The report must echo this id."
+    },
+    "preferredModel": {
+      "type": "string",
+      "pattern": "^.+/.+$",
+      "description": "Provider/model-id of the vision model the orchestrator selected (informational; the subagent is already bound to a model via its config)."
+    },
+    "images": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One or more locally-stored image files to analyze.",
+      "items": {
+        "type": "object",
+        "required": ["path"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Absolute or project-relative path to the image file (PNG/JPEG/WebP)."
+          },
+          "label": {
+            "type": "string",
+            "description": "Short human-readable label for the image, used in observations[].imageLabel."
+          },
+          "role": {
+            "enum": ["baseline", "current", "reference"],
+            "description": "Role of this image in the judgment: baseline (before/reference), current (the thing under test), reference (design/target)."
+          }
+        }
+      }
+    },
+    "judgment": {
+      "description": "The typed judgment to perform. Exactly one type applies; its parameters are type-specific.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "presence" },
+            "parameters": {
+              "type": "object",
+              "required": ["subject", "expectation"],
+              "additionalProperties": false,
+              "properties": {
+                "subject": { "type": "string", "description": "The element/text/icon to find, e.g. 'Submit button'." },
+                "expectation": { "enum": ["present", "absent"], "description": "Whether the subject should be visible." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "absence" },
+            "parameters": {
+              "type": "object",
+              "required": ["subject", "expectation"],
+              "additionalProperties": false,
+              "properties": {
+                "subject": { "type": "string", "description": "The element that should NOT be visible." },
+                "expectation": { "enum": ["present", "absent"], "description": "Should be 'absent'." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "alignment" },
+            "parameters": {
+              "type": "object",
+              "required": ["subject", "axis"],
+              "additionalProperties": false,
+              "properties": {
+                "subject": { "type": "string" },
+                "axis": { "enum": ["horizontal", "vertical", "both"] },
+                "expectation": { "type": "string", "description": "e.g. 'centered', 'left-aligned', 'top'." },
+                "tolerance": { "enum": ["strict", "loose"], "description": "strict ≈ exact; loose ≈ within ~5%." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "ordering" },
+            "parameters": {
+              "type": "object",
+              "required": ["direction", "expected"],
+              "additionalProperties": false,
+              "properties": {
+                "direction": { "enum": ["ltr", "ttb"], "description": "Left-to-right or top-to-bottom." },
+                "expected": { "type": "array", "items": { "type": "string" }, "description": "Expected order of subjects." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "equality" },
+            "parameters": {
+              "type": "object",
+              "required": ["subjects"],
+              "additionalProperties": false,
+              "properties": {
+                "subjects": {
+                  "type": "array",
+                  "minItems": 2,
+                  "maxItems": 2,
+                  "items": { "type": "string" },
+                  "description": "Labels of the two images to compare."
+                },
+                "threshold": { "enum": ["exact", "perceptual"], "description": "exact = pixel-identical; perceptual = structurally same." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "layout" },
+            "parameters": {
+              "type": "object",
+              "required": ["expectations"],
+              "additionalProperties": false,
+              "properties": {
+                "expectations": { "type": "string", "description": "NL description of expected layout, e.g. 'sidebar on left, main content right, equal gaps'." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "readability" },
+            "parameters": {
+              "type": "object",
+              "required": ["subject"],
+              "additionalProperties": false,
+              "properties": {
+                "subject": { "type": "string", "description": "The text/region to check for legibility." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "state" },
+            "parameters": {
+              "type": "object",
+              "required": ["subject", "expectedState"],
+              "additionalProperties": false,
+              "properties": {
+                "subject": { "type": "string", "description": "The control, e.g. 'notifications toggle'." },
+                "expectedState": { "type": "string", "description": "e.g. 'on', 'off', 'checked', 'disabled'." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "diff" },
+            "parameters": {
+              "type": "object",
+              "required": ["baseline", "current"],
+              "additionalProperties": false,
+              "properties": {
+                "baseline": { "type": "string", "description": "Label of the before image." },
+                "current": { "type": "string", "description": "Label of the after image." }
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "parameters"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "describe" },
+            "parameters": {
+              "type": "object",
+              "required": ["focus"],
+              "additionalProperties": false,
+              "properties": {
+                "focus": { "type": "string", "description": "What to describe, e.g. 'overall layout and primary UI elements'." }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "criteria": {
+      "type": "string",
+      "description": "Natural-language fallback for nuance the typed parameters cannot capture. Free-form guidance for the subagent."
+    },
+    "responseContract": {
+      "type": "string",
+      "description": "What the caller wants back, beyond the fixed report envelope. e.g. 'Return pass/fail and note the button position if found.'"
+    }
+  }
+}

package/subagent-body.md

@@ -0,0 +1,45 @@
+You are a visual judgment subagent powered by {{model_name}}
+({{provider}}/{{model_id}}).
+
+## Input
+
+You receive a `visual-judgment-request.v1` JSON object as your prompt.
+Read it, then read each image file listed in `images[].path` using the
+`read` tool. Analyze them against `judgment.type` and `judgment.parameters`.
+
+The request schema lives at:
+https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-request.v1.json
+
+## Output
+
+Emit a `visual-judgment-report.v1` JSON object — nothing else. No prose,
+no markdown fences, no commentary. The envelope is fixed:
+
+- `$schema`: "https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-report.v1.json"
+- `id`: echo the request id
+- `status`: "ok" | "error" | "insufficient-evidence"
+- `verdict`: "pass" | "fail" | "inconclusive" (only when status="ok")
+- `confidence`: 0.0-1.0
+- `observations[]`: typed per `judgment.type`
+- `diff[]`: structured change list (for judgment.type="diff")
+- `reasoning`: one-paragraph justification linking observations to verdict
+- `errors[]`: if any image could not be analyzed
+
+The report schema lives at:
+https://raw.githubusercontent.com/WeZZard/skills/main/opencode/vision/schemas/visual-judgment-report.v1.json
+
+## Rules
+
+- Report what you actually observe. Do not guess.
+- Be specific: positions, colors, sizes, alignment, visibility, ordering.
+- If a subject described in the request is not visible, say so in
+  `observations[].note`.
+- If you cannot analyze an image (corrupted, wrong format, file not found),
+  set `status: "error"` with an `errors[]` entry (code e.g. "file_not_found",
+  "unsupported_format").
+- For `diff` and `describe` judgments, set `verdict: "inconclusive"` —
+  these are informational, not pass/fail.
+- Validate your output against the report schema URL (best-effort if the
+  fetch fails — emit the envelope correctly regardless).
+- You MUST NOT spawn subagents. You are a leaf in the execution tree.
+- You MUST NOT run the graph engine or any orchestrator-only command.

package/vision-models.json

@@ -0,0 +1,15 @@
+{
+  "_comment": "Vision subagent manifest. Curation rule: one top-tier model per provider x vendor family; drop non-reasoning, drop superseded within a provider, drop coding-specialized, drop Pro/billing variants of the same family; keep cross-provider duplicates (same model via different route = different billing/rate/latency). Add a model = one line here + restart opencode.",
+  "models": [
+    { "provider": "openai", "model_id": "gpt-5.5", "name": "GPT-5.5" },
+    { "provider": "kimi-for-coding", "model_id": "k2p7", "name": "Kimi K2.7 Code" },
+    { "provider": "ollama-cloud", "model_id": "gemini-3-flash-preview", "name": "Gemini 3 Flash" },
+    { "provider": "ollama-cloud", "model_id": "gemma4:31b", "name": "Gemma 4 31B" },
+    { "provider": "ollama-cloud", "model_id": "minimax-m3", "name": "MiniMax M3" },
+    { "provider": "ollama-cloud", "model_id": "qwen3.5:397b", "name": "Qwen 3.5 397B" },
+    { "provider": "opencode-go", "model_id": "kimi-k2.7-code", "name": "Kimi K2.7 Code" },
+    { "provider": "opencode-go", "model_id": "minimax-m3", "name": "MiniMax M3" },
+    { "provider": "opencode-go", "model_id": "qwen3.7-plus", "name": "Qwen 3.7 Plus" },
+    { "provider": "opencode-go", "model_id": "mimo-v2.5", "name": "MiMo V2.5" }
+  ]
+}