Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,13 @@

## Unreleased

Catalog hygiene patch. No new skills, no new MCP, no foreign harness runtime. Totals stay **62** (46 model-invoked, 16 manual slash commands).
Catalog update for AI LABS 8-repo wave adaptation and hygiene patch. Totals become **63** (47 model-invoked, 16 manual slash commands).

- Add first-party model-invoked specialist `img2threejs` for code-only procedural Three.js TypeScript model reconstruction from reference object images (editable Group factory, visible vs. inferred geometry spec, screenshot loop gate; no mesh blob downloads).
- Add optional `reticle` MCP (`opencode-bf reticle enable` / `disable`) registering local perception server (`npx -y @reticlehq/server mcp`). `FOREIGN_ON_DEMAND`, server is FSL-1.1-ALv2, perception only, never an auto-implementer; default verification remains `playwright-qa` / `chrome-devtools-axi`.
- Add optional `ui-skills` remote MCP (`opencode-bf ui-skills enable` / `disable`) registering `https://www.ui-skills.com/mcp` for design-skill lookup only. Product UI remains Design Bank + Impeccable + Design V2 atoms + shadcn; `BANK_MISS` never generates from random ui-skills documents.
- Anti-slop selective merge: incorporate visual and copy anti-patterns (no default purple-gradient hero, glowing mesh, Inter-on-white-card slop, fake testimonials, or "Let's dive in" clichés) into `skills/impeccable/reference/taste-guard.md` and `rules/03-prose-discipline.md` with attribution to `miqdadbadjuber/anti-slop` MIT in `skills/install-anti-slop/NOTICE.md`. Zero extra catalog skills added.
- Document warehouse dispositions for AI LABS 8 wave: `img2threejs` (NEW), `reticle` (FOREIGN_ON_DEMAND), `ui-skills` (FOREIGN_ON_DEMAND), `chisel` hooks (REJECT), `ouroboros`/Q00 (REJECT), `swiftui-skills` (DEFER), `caliper` (FOREIGN_ON_DEMAND maintainer CLI), and `anti-slop` (MERGE).
- Sync stale user-facing catalog copy (`59` / `43 model-invoked`) to the measured tree in `README.md`, `docs/skills.md`, and `docs/architecture.md`. Historical release entries keep their original numbers.
- `skill-stocktake`: replace the schema-only sweep with a verdict protocol. Every catalog item resolves to exactly one of `KEEP`, `COMPRESS`, `UPDATE`, `MERGE → <target>`, or `RETIRE`, backed by an existence pass, a currency pass, and cited evidence. The skill never rewrites or deletes another skill; `COMPRESS`/`UPDATE` hand off to `writing-for-agents` or `prompt-optimizer`.
- `eval-harness`: add `references/skill-utility.md`, an A/B utility gate that scores a task with the skill (Run B) against the same task without it (Run A). Quality parity with lower token or latency passes; `A ≈ B` on the skill's own claimed task is evidence for `RETIRE` or `COMPRESS`. Deterministic assertions first, no external harness, no API key.
Expand Down
11 changes: 7 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# OpenCodeBestFriend

Production-ready capability layer for OpenCode:
62 routed skills (core + Wave 2/3 warehouse specialists), MCP, Codebase Memory,
63 routed skills (core + Wave 2/3 warehouse specialists), MCP, Codebase Memory,
Design Bank, Design Intelligence, SmartDoc, browser and verification tooling.

OpenCodeBestFriend is an installer and runtime overlay for [OpenCode](https://opencode.ai). It is **not** Claude Code, **not** a model provider, and **not** a dump of a developer home directory.

## What it is

- 62 skills: 46 model-invoked, 16 manual slash commands
- 63 skills: 47 model-invoked, 16 manual slash commands
- A thin `AGENTS.md` router (lazy, one primary specialist)
- Core MCP: Codebase Memory, Context7, shadcn
- Design Bank discovery or download (media is **not** in git)
Expand Down Expand Up @@ -97,6 +97,7 @@ Default: repository evidence first. Then at most one specialist.
| Photoreal / media | `visual-studio` |
| Scroll-led storytelling | `scroll-craft` |
| Scroll-driven 3D / camera world | `scroll-world` |
| Procedural Three.js object from image | `img2threejs` |
| Deterministic HTML composition video | `hyperframes` |
| Documents (PDF/DOCX/answer/extract/review) | `smartdoc` |
| Reusable book/module knowledge | `smartbook-ingest` |
Expand Down Expand Up @@ -125,10 +126,12 @@ Core (installed):
Optional:

- `serena` — host binary may exist; MCP is **not** registered unless you run `opencode-bf serena enable`
- `exa` — `FOREIGN_ON_DEMAND`; installer never adds, removes, or overwrites it
- `stitch` — `opencode-bf stitch enable` registers Google Stitch as a remote comp/mock source. Not an owned core server and not a production UI implementer: hand screens to `found-this-design` or `impeccable` before shipping. Keys are never written into config, only referenced as `{env:STITCH_API_KEY}`, or omitted with `--oauth`. `opencode-bf stitch disable` removes only that server key. Absent is not a `doctor` failure; a malformed entry fails closed.
- `reticle` — `opencode-bf reticle enable` registers Reticle as a local perception server (`npx -y @reticlehq/server mcp`). `FOREIGN_ON_DEMAND`. Server package is FSL-1.1-ALv2 (competing-use clause); SDK packages (Apache-2.0) are not vendored. Never an auto-implementer; default verification remains `playwright-qa` / `chrome-devtools-axi`. `opencode-bf reticle disable` removes only that server key. Absent is not a `doctor` failure; a malformed entry fails closed.
- `ui-skills` — `opencode-bf ui-skills enable` registers UI Skills (`https://www.ui-skills.com/mcp`) as an optional remote MCP server. `FOREIGN_ON_DEMAND` for design-skill lookup only. Product UI remains Design Bank + Impeccable + Design V2 atoms + shadcn; `BANK_MISS` never generates from a random ui-skills document. `opencode-bf ui-skills disable` removes only that server key. Absent is not a `doctor` failure; a malformed entry fails closed.
- `exa` — `FOREIGN_ON_DEMAND`; installer never adds, removes, or overwrites it

NVIDIA SkillEvaluator is `FOREIGN_ON_DEMAND` in the same sense: a maintainer may run it externally for embedding-based overlap scoring or live catalog evaluation. The installer never adds it, `doctor` does not fail when it is absent, and a malformed MCP entry for it fails closed like any other schema violation.
NVIDIA SkillEvaluator is `FOREIGN_ON_DEMAND` in the same sense: a maintainer may run it externally for embedding-based overlap scoring or live catalog evaluation. Caliper is `FOREIGN_ON_DEMAND` similarly: a maintainer may `pipx install caliper-eval` off-tree for prompt/agent benchmark evaluation. Neither is vendored into `lib/`, the installer never adds them, `doctor` does not fail when they are absent, and a malformed MCP entry fails closed like any other schema violation.

The installer merges only owned MCP keys. Provider, model, permissions, plugins, and foreign MCP stay yours.

Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@
┌───────────────────┼────────────────────┐
▼ ▼ ▼
Skills MCP Rules
46 automatic Codebase Memory Verification
16 manual Context7 Engineering
47 automatic Codebase Memory Verification
16 manual Context7 Engineering
shadcn
Expand Down
6 changes: 6 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ Optional:

- `serena` — `opencode-bf serena enable` if the binary is on PATH
- `stitch` — `opencode-bf stitch enable` (remote comp/mock source only; auth via `{env:STITCH_API_KEY}` or `--oauth`)
- `reticle` — `opencode-bf reticle enable` (local stdio via `npx -y @reticlehq/server mcp`; perception only, never auto-implementer)
- `ui-skills` — `opencode-bf ui-skills enable` (remote HTTP `https://www.ui-skills.com/mcp`; design-skill lookup only)
- `exa` — foreign; never add/remove/overwrite

Merge is parse-aware. Comment-free JSON is rewritten with `json.dumps`. JSONC with comments is patched surgically (owned MCP keys only). If surgical merge cannot be verified, install fails closed instead of destroying comments.
Expand All @@ -23,3 +25,7 @@ Doctor reports `CONFIGURED` for owned MCP entries present in config. That is not
`opencode-bf serena enable` adds Serena only if absent. JSONC comments, provider keys, and foreign MCP are preserved via the same surgical merge as core MCP. Invalid config fails closed.

`opencode-bf stitch enable` configures Google Stitch as an optional remote comp/mock server (`https://stitch.googleapis.com/mcp`). It is not an owned core server and not a UI implementer. Keys are never written directly to config, only referenced via `{env:STITCH_API_KEY}` or omitted when using `--oauth`. `opencode-bf stitch disable` surgically removes only the stitch server key.

`opencode-bf reticle enable` configures Reticle as an optional local perception MCP server (`npx -y @reticlehq/server mcp`). It is `FOREIGN_ON_DEMAND`. The server package is FSL-1.1-ALv2 (competing-use clause); SDK packages (Apache-2.0) are not vendored. Reticle is never an auto-implementer; after a feature is done, default verification remains `playwright-qa` or `chrome-devtools-axi`. Reticle is extra perception if the user enabled it. `opencode-bf reticle disable` surgically removes only the reticle server key. Absent is not a doctor failure; a malformed entry fails closed.

`opencode-bf ui-skills enable` configures UI Skills as an optional remote MCP server (`https://www.ui-skills.com/mcp`). It is `FOREIGN_ON_DEMAND` for design-skill lookup only (`list_skills`, `get_skill`). Product UI remains Design Bank + Impeccable + Design V2 atoms + shadcn; `BANK_MISS` never generates from a random ui-skills document. `opencode-bf ui-skills disable` surgically removes only the ui-skills server key. Absent is not a doctor failure; a malformed entry fails closed.
2 changes: 1 addition & 1 deletion docs/routing.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ MANUAL_NOT_INVOKED

Never list unused tools as used.

UI direction from the bank routes to `found-this-design` first, which stops before component implementation. Visual UI and UI atoms (buttons, inputs, cards, nav) route to `impeccable` after Design V2 shortlist; BANK_MISS ≠ generate (+ shadcn/Design V2 internal). Stitch MCP is for screen/comp generation only, then found-this-design or impeccable with Design V2 atom shortlisting; never implement production UI from Stitch alone. Motion UI routes to `emil-design-eng`. Still/ads/non-UI surface route to `visual-studio`. Scroll-led stories route to `scroll-craft`, while continuous camera 3D fly-throughs route to `scroll-world`.
UI direction from the bank routes to `found-this-design` first, which stops before component implementation. Visual UI and UI atoms (buttons, inputs, cards, nav) route to `impeccable` after Design V2 shortlist; BANK_MISS ≠ generate (+ shadcn/Design V2 internal). Stitch MCP is for screen/comp generation only, then found-this-design or impeccable with Design V2 atom shortlisting; never implement production UI from Stitch alone. UI Skills MCP is design-skill lookup only; product UI remains Design Bank + Impeccable + Design V2 atoms + shadcn; BANK_MISS ≠ generate from a random ui-skills document. Motion UI routes to `emil-design-eng`. Still/ads/non-UI surface route to `visual-studio`. Scroll-led stories route to `scroll-craft`, while continuous camera 3D fly-throughs route to `scroll-world`. Procedural Three.js object models from reference images route to `img2threejs`.

Browser verification follows four explicit doors: exploratory application UI routes to `playwright-qa`, persistent multi-account sessions route to `browser-act`, observed Chromium cause routes to `chrome-devtools-axi`, and button handler sequential undo / shared-store side effects route to `click-path-audit`.

Expand Down
4 changes: 2 additions & 2 deletions docs/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

Policy: `vendor/skill-policy.json` plus `vendor/skill-allowlist.txt`.

- 46 model-invoked skills live under `skills/` and install to `~/.config/opencode/skills/` (core + Wave 2/3 warehouse specialists)
- 47 model-invoked skills live under `skills/` and install to `~/.config/opencode/skills/` (core + Wave 2/3 warehouse specialists)
- 16 manual skills live under `manual-skills/` and install to `~/.config/opencode/bestfriend/skills/` plus `commands/`

`smartdoc` is per-job document intelligence. `smartbook-ingest` compiles reusable local knowledge. `humanizer` cleans user-facing prose tells (`/unslop` is its manual alias). `academic` manages scholarly research, writing, and peer review. `hyperframes` handles deterministic HTML-to-MP4 video composition. `diagram-design` crafts editorial HTML/SVG diagrams. Warehouse diagnostics include `agent-architecture-audit` (agent stack layers), `cost-aware-llm-pipeline` (token budgeting), `eval-harness` (benchmarks), `prompt-optimizer` (prompt refinement), and `skill-stocktake` (catalog hygiene). Wave 3 adds `api-design`, `contract-first`, `automation-audit-ops`, `code-tour`, and `click-path-audit`. Handwriting is a SmartDoc renderer, not a skill.
`smartdoc` is per-job document intelligence. `smartbook-ingest` compiles reusable local knowledge. `humanizer` cleans user-facing prose tells (`/unslop` is its manual alias). `academic` manages scholarly research, writing, and peer review. `hyperframes` handles deterministic HTML-to-MP4 video composition. `diagram-design` crafts editorial HTML/SVG diagrams. `img2threejs` reconstructs procedural Three.js models from reference images. Warehouse diagnostics include `agent-architecture-audit` (agent stack layers), `cost-aware-llm-pipeline` (token budgeting), `eval-harness` (benchmarks), `prompt-optimizer` (prompt refinement), and `skill-stocktake` (catalog hygiene). Wave 3 adds `api-design`, `contract-first`, `automation-audit-ops`, `code-tour`, and `click-path-audit`. Handwriting is a SmartDoc renderer, not a skill.

OpenCode 1.18.x has no `disable-model-invocation` field. Manual skills must not be copied into the discovered skills directory.

Expand Down
17 changes: 17 additions & 0 deletions docs/warehouse-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -350,3 +350,20 @@ This inventory establishes the contract for warehouse skills across the five ana
| `affaan-m/ECC` | `windows-desktop-e2e` | **REJECT** | `-` | Language/framework pattern sprawl already covered by repo context + Context7 docs | `-` |
| `affaan-m/ECC` | `workspace-surface-audit` | **DEFER** | `-` | Specialized domain procedure deferred for future warehouse wave evaluation | `-` |
| `affaan-m/ECC` | `x-api` | **REJECT** | `-` | Third-party vendor operations and niche business workflows; reject proprietary automation | `-` |

---

## Wave AI LABS 8 Evaluation

Evaluation and disposition contract for the AI LABS 8-repo wave (procedural 3D, perception, hooks, UI registries, harness runtimes, mobile platforms, eval benchmarks, anti-slop):

| Candidate / Repo | Decision | BestFriend Target | Reason |
| :--- | :---: | :--- | :--- |
| `img2threejs` | **NEW** | `skills/img2threejs` | Procedural Three.js TypeScript Group reconstruction from reference object image; quality-gated, no downloaded mesh blobs. |
| `reticle` | **FOREIGN_ON_DEMAND** | `mcp.reticle` | Optional visual perception MCP (`npx -y @reticlehq/server mcp`). Server licensed under FSL-1.1-ALv2; not vendored. Perception only, never auto-implementer. |
| `chisel` (hooks) | **REJECT** | `-` | Session/prompt/tool hooks coupled to Claude Code runtime. Context Guard remains NOT_PORTED. |
| `ui-skills` | **FOREIGN_ON_DEMAND** | `mcp.ui-skills` | Optional remote MCP (`https://www.ui-skills.com/mcp`) for design-skill lookup only. Product UI remains Design Bank + Impeccable + Design V2 + shadcn. |
| `ouroboros` / Q00 | **REJECT** | `-` | Autonomous evolution harness / continuous-learning runtime rejected. Interview primitives already live in `grill-with-docs` / `ask-matt` / `to-spec`. |
| `swiftui-skills` | **DEFER** | `-` | Apple platform / Xcode 26 ecosystem deferred. Target platform gate remains Linux x86_64 and OpenCode 1.18.x. |
| `caliper` | **FOREIGN_ON_DEMAND** | `-` | Benchmark CLI runner (`caliper-eval`). Maintainer may run off-tree via pipx; zero `lib/` vendor coupling. |
| `anti-slop` | **MERGE** | `install-anti-slop`, `impeccable`, `rules/03-prose-discipline.md` | Anti-pattern guardrails merged into existing taste, prose, and linting references; zero extra catalog skills. |
18 changes: 18 additions & 0 deletions lib/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,13 @@
cmd_install,
cmd_restore,
cmd_restore_list,
cmd_reticle_disable,
cmd_reticle_enable,
cmd_serena_enable,
cmd_stitch_disable,
cmd_stitch_enable,
cmd_ui_skills_disable,
cmd_ui_skills_enable,
cmd_uninstall,
)
from lib.integrity import cmd_verify # noqa: E402
Expand Down Expand Up @@ -104,6 +108,12 @@ def build_parser() -> argparse.ArgumentParser:
st.add_argument("action", choices=["enable", "disable"])
st.add_argument("--oauth", action="store_true", help="use OAuth/Bearer auth instead of STITCH_API_KEY header")

ret = sub.add_parser("reticle", help="optional Reticle local perception MCP")
ret.add_argument("action", choices=["enable", "disable"])

uis = sub.add_parser("ui-skills", help="optional UI Skills remote MCP")
uis.add_argument("action", choices=["enable", "disable"])

sd = sub.add_parser("smartdoc", help="document profiles, extract, status")
add_smartdoc_cli(sd)
sb = sub.add_parser("smartbook", help="reusable SmartBook lifecycle")
Expand Down Expand Up @@ -163,6 +173,14 @@ def main(argv: list[str] | None = None) -> int:
if args.action == "enable":
return cmd_stitch_enable(oauth=args.oauth)
return cmd_stitch_disable()
if cmd == "reticle":
if args.action == "enable":
return cmd_reticle_enable()
return cmd_reticle_disable()
if cmd == "ui-skills":
if args.action == "enable":
return cmd_ui_skills_enable()
return cmd_ui_skills_disable()
if cmd == "smartdoc":
return dispatch_smartdoc(args)
if cmd == "smartbook":
Expand Down
27 changes: 24 additions & 3 deletions lib/doctor.py
Original file line number Diff line number Diff line change
Expand Up @@ -118,13 +118,14 @@ def mcp_status_map() -> dict[str, str]:
try:
data = jsonc.load_path(cfg)
except (OSError, json.JSONDecodeError, ValueError):
return {k: "FAIL" for k in ("codebase-memory-mcp", "context7", "shadcn", "serena", "stitch", "exa")}
return {k: "FAIL" for k in ("codebase-memory-mcp", "context7", "shadcn", "serena", "stitch", "reticle", "ui-skills", "exa")}
mcp = data.get("mcp") or {}
owned = {"codebase-memory-mcp", "context7", "shadcn"}
for name in ("codebase-memory-mcp", "context7", "shadcn", "serena", "stitch", "exa"):
optional = {"serena", "stitch", "reticle", "ui-skills", "exa"}
for name in ("codebase-memory-mcp", "context7", "shadcn", "serena", "stitch", "reticle", "ui-skills", "exa"):
spec = mcp.get(name)
if spec is None:
out[name] = "OPTIONAL_ABSENT" if name in {"serena", "stitch", "exa"} else "FAIL"
out[name] = "OPTIONAL_ABSENT" if name in optional else "FAIL"
continue
if not isinstance(spec, dict):
out[name] = "FAIL"
Expand All @@ -144,6 +145,26 @@ def mcp_status_map() -> dict[str, str]:
continue
out[name] = "CONFIGURED"
continue
if name == "reticle":
typ = spec.get("type")
cmd = spec.get("command")
if typ != "local" or not isinstance(cmd, list) or not cmd:
out[name] = "FAIL"
continue
out[name] = "CONFIGURED"
continue
if name == "ui-skills":
typ = spec.get("type")
url = spec.get("url")
if typ != "remote" or url != "https://www.ui-skills.com/mcp":
out[name] = "FAIL"
continue
headers = spec.get("headers")
if headers is not None and not isinstance(headers, dict):
out[name] = "FAIL"
continue
out[name] = "CONFIGURED"
continue
if name not in owned:
out[name] = "FOREIGN"
continue
Expand Down
Loading
Loading