@mthanh/vespercli 2.0.1 → 2.1.0

package/README.md

@@ -1,8 +1,8 @@
 # Vesper Agent Suite
 
-A CLI that provisions an AI agent suite into your project for **Claude Code** or **GitHub Copilot Chat (VS Code)**: an orchestrator persona, specialist subagents, skills, and maintenance workflows.
+A CLI that provisions an AI agent suite into your project for **Claude Code + OpenCode** or **GitHub Copilot Chat (VS Code)**: an orchestrator persona, specialist subagents, skills, and maintenance workflows.
 
-**Vesper** gives your AI coding assistant specialized agents, reusable skills, and structured workflows. Each workspace runs **exactly one host**, Claude Code or GitHub Copilot, and you pick it with `vespercli init --host claude|copilot`. The project's workflow state (`.vesper/.tracking/`, including the run ledger, and `.vesper/memory.jsonl`) is host-neutral and survives a host switch.
+**Vesper** gives your AI coding assistant specialized agents, reusable skills, and structured workflows. Each workspace runs **exactly one host**, Claude Code (which always prepares [OpenCode](#opencode) as well) or GitHub Copilot, and you pick it with `vespercli init --host claude|copilot`. The project's workflow state (`.vesper/.tracking/`, including the run ledger, and `.vesper/memory.jsonl`) is host-neutral and survives a host switch.
 
 > **Upgrading from 1.x?** Vesper 2.0 is a breaking release. Running `vespercli init` once migrates a 1.x workspace in place and backs up everything it removes. See [Upgrading from 1.x](#upgrading-from-1x) and [`CHANGELOG.md`](CHANGELOG.md).
 
@@ -70,7 +70,7 @@ The design optimizes for compounding: mistakes convert to rules, workflows conve
 
 - Node.js >= 22.13.0 (the `vesper-indexing` MCP server uses the built-in `node:sqlite` module)
 - git (worktree bootstrap, hooks and host resolution read the repository)
-- One host: Claude Code (CLI, VS Code extension, JetBrains, or desktop app), or VS Code with GitHub Copilot Chat
+- One host: Claude Code (CLI, VS Code extension, JetBrains, or desktop app) — [OpenCode](#opencode) opens the same workspace as-is — or VS Code with GitHub Copilot Chat
 
 ## Installation
 
@@ -84,7 +84,7 @@ The session-start triggers and git hooks call `vespercli` from `PATH`. They do n
 ## Quick start
 
 ```bash
-vespercli init --host claude     # or: --host copilot
+vespercli init --host claude     # Claude Code + OpenCode; or: --host copilot
 vespercli init                   # interactive: asks "Which AI host is this workspace for?"
 ```
 
@@ -93,6 +93,7 @@ A non-interactive run (no TTY) never guesses. It re-uses the host the checked-ou
 Then say hello:
 
 - **Claude Code**: start a session in the project. It opens as the `vesper-orchestrator` agent. The first time, Claude Code asks you to trust the workspace, which loads the `vesper` plugin. Prompt `init`, and Vesper detects the missing Team Roster and runs the workspace setup.
+- **OpenCode**: open the same checkout. `opencode.json` makes `vesper-orchestrator` the default agent and loads the always-on rules; the Vesper plugin under `.opencode/plugins/` registers the specialists (see [OpenCode](#opencode)).
 - **GitHub Copilot**: reload VS Code (`Developer: Reload Window`), open Copilot Chat, pick **vesper-orchestrator** in the agent dropdown, and prompt `Vesperize`.
 
 Commit what `init` wrote (see the tables below). The committed files are what make the project a Vesper project for every clone, worktree, and teammate.
@@ -101,7 +102,7 @@ Commit what `init` wrote (see the tables below). The committed files are what ma
 
 Vesper writes only inside the project, and every file it writes is recorded in an ownership ledger (see [Ownership and removal](#ownership-and-removal)).
 
-### Claude Code (`--host claude`)
+### Claude Code + OpenCode (`--host claude`)
 
 The specialist catalog is **not copied** into the project. It ships inside the npm package as a Claude Code **marketplace** (`vesper-marketplace`) holding a **core plugin** (`vesper`) and the stack **packs** (`vesper-frontend`, `vesper-playwright`, `vesper-backend`, `vesper-polyglot`, `vesper-docs`, `vesper-integrations`, and the opt-in `vesper-styles`), all referenced in place. Core specialists resolve as `vesper:<name>` and core skills as `/vesper:<name>`; a packed one as `vesper-<pack>:<name>` / `/vesper-<pack>:<name>`. Core is always enabled; a pack is enabled per project — see [Packs](#packs).
 
@@ -118,6 +119,16 @@ The specialist catalog is **not copied** into the project. It ships inside the n
 | `CLAUDE.md` | yes | A short guarded prose pointer (`<!-- vesper:start -->…<!-- vesper:end -->`). No `@import`: the rules load natively. |
 | `.mcp.json` | no (gitignored) | The three core MCP servers plus any you added. Regenerated at every session start. |
 
+#### OpenCode (always written with `--host claude`)
+
+The Claude host always prepares OpenCode too (there is no separate OpenCode host and no flag): three small committed files, recorded in the ledger under host `claude`, removed by `reset --host claude` and by a switch to Copilot, re-provisioned by a switch back.
+
+| Path | Committed? | What it is |
+|---|---|---|
+| `opencode.json` | yes | Vesper's keys only, merged into your file (your keys and array entries are kept): `default_agent: "vesper-orchestrator"`, `instructions` (the three `.claude/rules/vesper-*.md` files, append-only), `mcp` (the same servers `.mcp.json` carries, as `["vespercli", "mcp", "serve", "<name>"]` — no machine path, so the file commits), `plugin: ["./.opencode/plugins/vesper.js"]` (append-only), and a Vesper-owned `vesper` object (`packs`: the enabled packs, mirrored by `packs enable/disable/sync`; `agentsMode`: `plugin` or `files`). A fresh file also gets `$schema`. |
+| `.opencode/agents/vesper-orchestrator.md` | yes | The primary OpenCode agent (`mode: primary`) — the same pointer to the rules as the committed Claude persona. |
+| `.opencode/plugins/vesper.js` | yes | A byte-exact copy of the shipped Vesper plugin. Refreshed on `init`/`update` when the shipped file changed; an edited copy is kept and reported. |
+
 ### GitHub Copilot (`--host copilot`)
 
 The generated Copilot catalog stays **inside the npm package** (`assets/copilot/`). Vesper points VS Code at it through workspace settings. Every package agent is generated with `user-invocable: false`, so the agent picker shows the built-in agents plus one Vesper agent.
@@ -176,9 +187,22 @@ and then works as a single generalist, following the memory and run-ledger conve
 
 Session-start work also needs `vespercli`: the `SessionStart` hook is `command -v vespercli >/dev/null 2>&1 && vespercli guard --running-host claude || true`. Where `vespercli` isn't installed, nothing runs, so `.mcp.json` and the code index are not generated.
 
+## OpenCode
+
+OpenCode ([sst/opencode](https://github.com/sst/opencode)) reads a Claude workspace natively (`CLAUDE.md`, `.claude/skills/`), but not the always-on `.claude/rules/*`. The Claude host therefore always writes the overlay in the table above, and no `reinit` is needed between the two tools — both run on the same checkout. Open the repository in OpenCode:
+
+- `vesper-orchestrator` is the primary agent (`default_agent`), and the playbook, Team Roster and whitepaper are loaded through `instructions`.
+- The three core MCP servers (and any you added with `vespercli mcp add`) run through `vespercli mcp serve <name>`, so `opencode.json` carries no machine path.
+- The specialists come from the npm package through the Vesper plugin, under the same names the roster carries (`vesper:<name>`, `vesper-<pack>:<name>`); the four maintenance skills resolve from `.claude/skills/`. `vesper.packs` in `opencode.json` mirrors the enabled packs.
+- Fallback: set `vesper.agentsMode` to `"files"` in `opencode.json` and run `vespercli opencode render-agents` — the specialists are then generated as `.opencode/agents/<name>.md` files (re-rendered by `packs enable/disable/sync`).
+
+OpenCode ignores unknown top-level keys in `opencode.json` (its config decoder drops excess properties), so the `vesper` object is harmless at runtime; an editor validating against `opencode.ai/config.json` may flag it as unknown.
+
+Verify on your install (the story's open questions): **OQ-1** the plugin registers agents at runtime (otherwise use the `files` fallback); **OQ-2** `instructions` accepts the three rule files as-is; **OQ-3** the `session.created` hook's guard output reaches the model's context; **OQ-4** `vesper:<name>` names with a `:` are accepted as agent identifiers by the Task tool.
+
 ## Which host is this?
 
-**The checked-out tree decides.** Vesper resolves the host from Vesper-only keys in files git can see, as they stand in the working tree: the plugin and `agent` keys in `.claude/settings.json` for Claude; the `.vesper/agents` settings entry and the Copilot guard task for Copilot. Generic files such as `.mcp.json` never decide the host. Every path uses this rule: the guard, bootstrap, `doctor`, `init`, `reset`, `list`, `add`, `update` and `mcp`.
+**The checked-out tree decides.** Vesper resolves the host from Vesper-only keys in files git can see, as they stand in the working tree: the plugin and `agent` keys in `.claude/settings.json`, or `default_agent: "vesper-orchestrator"` in `opencode.json` (the OpenCode overlay's key — a second Claude fingerprint, so both present is the normal state, and `opencode.json` alone still resolves Claude), for Claude; the `.vesper/agents` settings entry and the Copilot guard task for Copilot. Generic files such as `.mcp.json` never decide the host. Every path uses this rule: the guard, bootstrap, `doctor`, `init`, `reset`, `list`, `add`, `update` and `mcp`.
 
 Consequences:
 
@@ -199,6 +223,7 @@ Caveats:
 | Trigger | Command | Where it comes from |
 |---|---|---|
 | Claude Code opens the project | `vespercli guard --running-host claude` | `SessionStart` hook in `.claude/settings.json` |
+| OpenCode opens the project | `vespercli guard --running-host opencode` | the Vesper plugin (`.opencode/plugins/vesper.js`, `session.created`) — `opencode` is the Claude host's identity: a Claude workspace is healthy, a Copilot one a mismatch |
 | VS Code opens the folder | `vespercli guard --running-host copilot` | folder-open task in `.vscode/tasks.json` |
 | `git checkout`/`git switch` of a branch | `vespercli guard` (no host) | `post-checkout` git hook |
 
@@ -210,7 +235,7 @@ VS Code runs folder-open tasks only when automatic tasks are allowed in the fold
 - **Copilot direction, Claude workspace**: VS Code opens Claude workspaces too (a Claude Code user editing in VS Code), so that task's message is advisory: it names `vespercli init --host copilot` for Copilot users, says it removes the Claude Code setup, and tells Claude Code users to ignore it. Nothing is written.
 - **Copilot**: the folder-open task prints the same token and fix in the terminal, and the Copilot orchestrator playbook carries the same banner-and-continue rule. There is no sentinel file and no always-on refusal rule; a `.vesper/instructions/vesper-host-guard.instructions.md` left by an earlier 2.0 build is removed by the next `init`, `update` or `reset` when it is byte-identical to what Vesper wrote (an edited copy is kept and reported).
 
-**Plugin absence (Claude Code only).** On the healthy path of `vespercli guard --running-host claude`, after bootstrap has regenerated `.claude/settings.local.json`, the guard checks the conditions the plugin needs and writes `VESPER_PLUGIN_ABSENT` to stdout when one is verifiably missing (see [degraded mode](#claude-code-plugin-trust-and-degraded-mode)). It never writes a "present" token. At most one host token and one plugin token appear per run; a mismatch suppresses the plugin token, and the plugin token leaves the exit code unchanged.
+**Plugin absence (Claude Code only, never for `--running-host opencode` — the OpenCode plugin carries the specialists itself).** On the healthy path of `vespercli guard --running-host claude`, after bootstrap has regenerated `.claude/settings.local.json`, the guard checks the conditions the plugin needs and writes `VESPER_PLUGIN_ABSENT` to stdout when one is verifiably missing (see [degraded mode](#claude-code-plugin-trust-and-degraded-mode)). It never writes a "present" token. At most one host token and one plugin token appear per run; a mismatch suppresses the plugin token, and the plugin token leaves the exit code unchanged.
 
 **Without `--running-host`** (the git hook or a manual run) there is no identity claim: no mismatch check and no marker of either kind. The guard writes nothing unless the **committed** tree at `HEAD` carries the resolved host's keys and the working tree still agrees.
 
@@ -218,7 +243,7 @@ VS Code runs folder-open tasks only when automatic tasks are allowed in the fold
 
 ## `vespercli doctor`
 
-A **read-only** validator. It never writes, deletes, or backs anything up. It checks host resolution, the ownership ledger against disk, MCP config drift, tracking shape, the framework version, git hooks, 1.x leftovers, and user-level residue. Each finding is `ERROR`, `WARN` or `INFO` and names its fix: `vespercli init`, `vespercli init --host <host>`, `vespercli reset --host <host>`, or `vespercli worktree bootstrap` for local-only state such as a missing git hook block. A fresh worktree's ledger carries no framework version until `init` runs there once; `doctor` reports that as `ledger-unstamped` (INFO), not as a stale framework.
+A **read-only** validator. It never writes, deletes, or backs anything up. It checks host resolution, the ownership ledger against disk, MCP config drift, tracking shape, the framework version, git hooks, 1.x leftovers, user-level residue, and (INFO `opencode-overlay-missing`) a Claude workspace that lacks one of the three OpenCode overlay files — `vespercli init` adds them. Each finding is `ERROR`, `WARN` or `INFO` and names its fix: `vespercli init`, `vespercli init --host <host>`, `vespercli reset --host <host>`, or `vespercli worktree bootstrap` for local-only state such as a missing git hook block. A fresh worktree's ledger carries no framework version until `init` runs there once; `doctor` reports that as `ledger-unstamped` (INFO), not as a stale framework.
 
 ```bash
 vespercli doctor                                   # human-readable report
@@ -398,7 +423,7 @@ A newer upstream reaches your project with the next Vesper release. `vespercli p
 |---|---|
 | `vespercli init [--host claude\|copilot] [-y] [--force-default] [--path <dir>]` | Provision, switch host, re-provision, or migrate a 1.x workspace. `--target` is a deprecated alias of `--host`; `all` and comma lists are rejected. |
 | `vespercli doctor [--quiet] [--running-host <host>]` | Read-only validation; exit `0`/`1`/`2`. |
-| `vespercli guard [--running-host <host>]` | Session-start guard (installed as the hook and task). |
+| `vespercli guard [--running-host claude\|copilot\|opencode]` | Session-start guard (installed as the hook, the task and the OpenCode plugin's `session.created` hook); `opencode` stands for the Claude host. |
 | `vespercli gate [--plan <file>] [--base <ref>] [--json]` | Run the committed gate policy (`.vesper/gates.json`): checks, plan conformance, diff-size cap, protected paths. Exit `0` pass, `1` fail, `2` no config. See [Gates](#gates). |
 | `vespercli log <started\|completed\|note\|delegated\|returned> --pipeline <p> [--step <s>] [--agent <a>] [--goal <g>] [--author <a>] [--status DONE\|NEED_HELP\|BLOCKED] [--slug <slug>] [--note <text>] [--stdin] [--json]` | Append one row to the run ledger `.vesper/.tracking/runs/YYYYMMDD-<slug>.jsonl` (atomic append; `--slug` defaults to `adhoc`). `--stdin` reads a Claude Code hook's JSON. Exit `2` on a missing required field. |
 | `vespercli log tail [--slug <slug>] [-n 5] [--json]` | Print the last run-ledger rows — what the orchestrator reads on resumption. |

package/assets/claude/.claude-plugin/marketplace.json

@@ -7,49 +7,49 @@
     {
       "name": "vesper",
       "source": "./",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper core: the support, review and generic developer/tester specialists plus the catalog skills every project uses. Always enabled."
     },
     {
       "name": "vesper-frontend",
       "source": "./packs/frontend",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper frontend pack — React, Next.js, Tailwind and Jest/RTL specialists and skills."
     },
     {
       "name": "vesper-playwright",
       "source": "./packs/playwright",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper playwright pack — Playwright end-to-end testing specialists and skills."
     },
     {
       "name": "vesper-backend",
       "source": "./packs/backend",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper backend pack — Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills."
     },
     {
       "name": "vesper-polyglot",
       "source": "./packs/polyglot",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper polyglot pack — Java, Flutter and Google ADK (Python) skills."
     },
     {
       "name": "vesper-docs",
       "source": "./packs/docs",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper docs pack — Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills."
     },
     {
       "name": "vesper-integrations",
       "source": "./packs/integrations",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper integrations pack — ClickUp task-board specialist, the GitLab MR guardrails skill, and the third-party GitLab CI skills (gitlab-ci-skill, github-actions-to-gitlab-ci)."
     },
     {
       "name": "vesper-styles",
       "source": "./packs/styles",
-      "version": "2.0.1",
+      "version": "2.1.0",
       "description": "Vesper styles pack — opt-in output styles: i-have-adhd, ponytail (third-party, MIT). Enabled by `vespercli packs enable styles`, which writes the always-on pointer rule that applies them."
     }
   ]

package/assets/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper",
   "displayName": "Vesper",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper specialist subagent catalog + catalog skills for Claude Code. The orchestrator playbook, team roster, slim project whitepaper, the committed main-thread orchestrator agent, and the four maintenance skills are project-committed (see .claude/rules/, .claude/agents/, .claude/skills/) and are deliberately NOT shipped by this plugin.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/backend/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-backend",
   "displayName": "Vesper backend pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper backend pack — Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills. Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/docs/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-docs",
   "displayName": "Vesper docs pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper docs pack — Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills. Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/frontend/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-frontend",
   "displayName": "Vesper frontend pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper frontend pack — React, Next.js, Tailwind and Jest/RTL specialists and skills. Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/integrations/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-integrations",
   "displayName": "Vesper integrations pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper integrations pack — ClickUp task-board specialist, the GitLab MR guardrails skill, and the third-party GitLab CI skills (gitlab-ci-skill, github-actions-to-gitlab-ci; UPSTREAM.json beside each). Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/playwright/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-playwright",
   "displayName": "Vesper playwright pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper playwright pack — Playwright end-to-end testing specialists and skills. Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/polyglot/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-polyglot",
   "displayName": "Vesper polyglot pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Vesper polyglot pack — Java, Flutter and Google ADK (Python) skills. Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/packs/styles/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vesper-styles",
   "displayName": "Vesper styles pack",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "opt-in output styles: i-have-adhd, ponytail. Third-party skills (MIT) shipped as pack content, never written into a project; `vespercli packs enable styles` is the consent and writes the always-on pointer rule that applies them.",
   "author": {
     "name": "Vesper Maintainers"

package/assets/claude/vesper-orchestrator.md

@@ -56,7 +56,7 @@ For verified trivial edits, Vesper MAY perform the change directly instead of de
 - If no roster yet, or no role matches a task → delegate to `vesper:workspace-learner`.
 - **Namespaced delegation names (correctness invariant, not style):** every specialist is a plugin agent exposed under the `vesper:` namespace. Delegate to them by their **`vesper:<name>`** form (e.g. `vesper:code-reviewer`, `vesper:task-researcher`, `vesper:principal-software-engineer`). The Team Roster's "Agent Name" column carries these namespaced names verbatim — use them exactly as written. If a roster entry names a catalog specialist **without** the namespace (an older roster not yet revalidated), delegate to `vesper:<name>` anyway — unless that name is a project agent in `.claude/agents/`, which resolves bare — and suggest `/revalidate-team`. The ONE non-namespaced name is the committed main-thread persona `vesper-orchestrator` (the `.claude/settings.json` `agent` key value); it is a project agent, not a plugin agent, so it carries no namespace. The four maintenance skills are committed project skills invoked **unqualified** (`/reinit`, `/compact-knowledge`, `/revalidate-knowledge`, `/revalidate-team`) — never `/vesper:reinit`.
 
-- **Packs (core + packs):** the catalog is a **core** plugin (`vesper`) plus stack **packs** — separate plugins in the same marketplace (`vesper-frontend`, `vesper-playwright`, `vesper-backend`, `vesper-polyglot`, `vesper-docs`, `vesper-integrations`, the opt-in `vesper-styles`), enabled per project when the Team Roster names one of their assets. A packed specialist resolves as **`vesper-<pack>:<name>`** (e.g. `vesper-frontend:expert-react-frontend-engineer`, `vesper-playwright:playwright-tester`) and the roster carries that namespaced name verbatim; a packed skill is `/vesper-<pack>:<name>`. A roster row naming an asset of a pack that is **not enabled** here is a `vespercli doctor` finding (`pack-not-enabled`) — the fix is `vespercli packs sync`, which enables every pack the roster needs (it never disables). `init` and `update` run the same sync; `vespercli packs` lists what is shipped, enabled and needed.
+- **Packs (core + packs):** the catalog is a **core** plugin (`vesper`) plus stack **packs** — separate plugins in the same marketplace (`vesper-frontend`, `vesper-playwright`, `vesper-backend`, `vesper-polyglot`, `vesper-docs`, `vesper-integrations`, the opt-in `vesper-styles`), enabled per project when the Team Roster names one of their assets. A packed specialist resolves as **`vesper-<pack>:<name>`** (e.g. `vesper-frontend:expert-react-frontend-engineer`, `vesper-playwright:playwright-tester`) and the roster carries that namespaced name verbatim; a packed skill is `/vesper-<pack>:<name>`. A roster row naming an asset of a pack that is **not enabled** here is a `vespercli doctor` finding (`pack-not-enabled`) — the fix is `vespercli packs sync`, which enables every pack the roster needs (it never disables). `init` and `update` run the same sync; `vespercli packs` lists what is shipped, enabled and needed. On OpenCode the same namespaced names resolve through the Vesper plugin.
 
 **What you MAY read** (routing files only — to decide WHO to delegate to, never to do the work yourself):
 

package/assets/hooks/pre-commit

@@ -28,7 +28,7 @@ if [ "$(git config --type=bool --get vesper.hooks 2>/dev/null)" != "false" ]; th
 # No `exit 0` inside this block: it may sit inside a user's or a hook manager's
 # hook with lines after it, and those must always run. Only the mr.json refusal
 # exits (non-zero, to abort the commit on purpose).
-vesper_git_paths=".claude/vesper/context .claude/agents .claude/commands .claude/skills .claude/rules .vesper/skills .vesper/instructions .vesper/agents .vesper/context .vesper/.tracking .vesper/memory.jsonl .vesper/gates.json CLAUDE.md"
+vesper_git_paths=".claude/vesper/context .claude/agents .claude/commands .claude/skills .claude/rules .vesper/skills .vesper/instructions .vesper/agents .vesper/context .vesper/.tracking .vesper/memory.jsonl .vesper/gates.json CLAUDE.md opencode.json .opencode"
 
 vesper_staged=$(git diff --cached --name-only)
 

package/assets/opencode/vesper-plugin.js

@@ -0,0 +1,120 @@
+/**
+ * Vesper OpenCode plugin — TEMPLATE. `vespercli init --host claude` copies it to
+ * `.opencode/plugins/vesper.js` (committed). Plain ESM, no dependencies, runs under Bun.
+ *
+ * What it does (every `vespercli` call is guarded; nothing here ever throws into OpenCode):
+ *  1. Locates the installed package: `vespercli --print-assets-dir` (fallback: `VESPER_ASSETS_DIR`).
+ *  2. Reads Vesper's keys in `opencode.json`: `vesper.packs` (the enabled packs) and
+ *     `vesper.agentsMode` (`"plugin"` default | `"files"`).
+ *  3. `config` hook (plugin mode): registers every core + enabled-pack specialist as an OpenCode
+ *     subagent (`vesper:<name>` / `vesper-<pack>:<name>`) by adding them to the loaded config's
+ *     `agent` map — converted from the Claude catalog by the package's own renderer
+ *     (`dist/opencode-render.js`), never a second converter here.
+ *  4. `session.created` → `vespercli guard --running-host opencode`; a `VESPER_HOST_MISMATCH` on
+ *     its stdout is shown as a TUI toast and appended to the session's first message so the
+ *     playbook's host-mismatch warning fires.
+ *  5. `tool.execute.after` on the `task` tool → `vespercli log delegated` (run-ledger enrichment).
+ *
+ * OpenCode loads every export of this module as a plugin function, so this file exports exactly one.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const TOKEN = 'VESPER_HOST_MISMATCH';
+
+function vespercli(args, cwd) {
+  try {
+    const stdout = execFileSync('vespercli', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000 });
+    return { ok: true, stdout: String(stdout) };
+  } catch (err) {
+    return { ok: false, stdout: String(err?.stdout || ''), stderr: String(err?.stderr || err?.message || '') };
+  }
+}
+
+function readVesperSettings(dir) {
+  const out = { packs: [], agentsMode: 'plugin' };
+  try {
+    const v = JSON.parse(readFileSync(join(dir, 'opencode.json'), 'utf-8'))?.vesper;
+    if (Array.isArray(v?.packs)) out.packs = v.packs.filter((p) => typeof p === 'string');
+    if (v?.agentsMode === 'files') out.agentsMode = 'files';
+  } catch { /* no opencode.json / no vesper key → defaults */ }
+  return out;
+}
+
+function agentFiles(dir, plugin) {
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.md')).sort().map((f) => ({ name: f.slice(0, -3), plugin, path: join(dir, f) }));
+  } catch { return []; }
+}
+
+async function loadRenderer(assetsDir) {
+  const root = resolve(assetsDir, '..');
+  for (const rel of ['dist/opencode-render.js', 'src/cli/utils/opencode-render.js']) {
+    const abs = join(root, rel);
+    if (existsSync(abs)) return import(pathToFileURL(abs).href);
+  }
+  return null;
+}
+
+export const VesperPlugin = async ({ client, directory, worktree }) => {
+  const dir = directory || worktree || process.cwd();
+  const settings = readVesperSettings(dir);
+  const log = async (level, message) => {
+    try { await client?.app?.log?.({ body: { service: 'vesper', level, message } }); } catch { /* best effort */ }
+  };
+  const available = vespercli(['--version'], dir).ok;
+  const located = available ? vespercli(['--print-assets-dir'], dir) : { ok: false };
+  const assetsDir = located.ok ? located.stdout.trim() : (process.env.VESPER_ASSETS_DIR || '');
+  const render = assetsDir ? await loadRenderer(assetsDir).catch(() => null) : null;
+  if (settings.agentsMode === 'plugin' && !render) {
+    await log('warn', 'Vesper: the @mthanh/vespercli package was not found (vespercli on PATH, or VESPER_ASSETS_DIR) — specialists not registered. Install it, or run `vespercli opencode render-agents` and set `vesper.agentsMode: "files"` in opencode.json.');
+  }
+  const pending = new Map(); // sessionID → the mismatch banner to append once
+
+  return {
+    config: async (config) => {
+      if (settings.agentsMode !== 'plugin' || !render) return;
+      config.agent ??= {};
+      const sources = agentFiles(join(assetsDir, 'claude', 'agents'), 'vesper');
+      for (const pack of settings.packs) sources.push(...agentFiles(join(assetsDir, 'claude', 'packs', pack, 'agents'), `vesper-${pack}`));
+      for (const src of sources) {
+        try {
+          const { frontmatter, body } = render.parseAgentMarkdown(readFileSync(src.path, 'utf-8'));
+          const { id, config: agent } = render.convertClaudeAgent({ name: src.name, frontmatter, body, plugin: src.plugin });
+          if (!config.agent[id]) config.agent[id] = agent;
+        } catch (err) { await log('warn', `Vesper: could not register ${src.plugin}:${src.name}: ${err?.message || err}`); }
+      }
+    },
+
+    event: async ({ event }) => {
+      if (event?.type !== 'session.created' || !available) return;
+      const info = event.properties?.info;
+      if (info?.parentID) return; // a subagent session — the guard ran for its parent
+      const res = vespercli(['guard', '--running-host', 'opencode', '--path', dir], dir);
+      const lines = res.stdout.split('\n');
+      const at = lines.indexOf(TOKEN);
+      if (at === -1) return;
+      const banner = lines.slice(at).filter(Boolean).join('\n');
+      pending.set(info?.id ?? '*', banner);
+      try { await client?.tui?.showToast?.({ body: { title: 'Vesper', message: lines[at + 1] || TOKEN, variant: 'warning' } }); } catch { /* headless */ }
+    },
+
+    'chat.message': async (input, output) => {
+      const banner = pending.get(input?.sessionID) ?? pending.get('*');
+      if (!banner) return;
+      pending.delete(input?.sessionID); pending.delete('*');
+      const part = (output?.parts || []).find((p) => p?.type === 'text' && typeof p.text === 'string');
+      if (part) part.text = `${part.text}\n\n${banner}`;
+    },
+
+    'tool.execute.after': async (input) => {
+      if (input?.tool !== 'task' || !available) return;
+      const agent = input.args?.subagent_type || input.args?.agent || 'unknown';
+      vespercli(['log', 'delegated', '--pipeline', 'hook', '--agent', String(agent), '--note', 'opencode', '--session', String(input.sessionID || ''), '--path', dir], dir);
+    },
+  };
+};
+
+export default VesperPlugin;