@mthanh/vespercli 2.0.1 → 2.2.0

package/assets/claude/packs/graphify/skills/agent-fundamentals/references/terminal-discipline.md

@@ -0,0 +1,94 @@
+# Terminal Discipline — Expanded Rules
+
+Non-negotiable rules for every `Bash` command a subagent executes.
+
+## Timeout Requirements
+
+| Command Type       | Timeout  | Examples                                               |
+| -------------------- | ---------- | ---------------------------------------------------------- |
+| Quick              | 15s      | `ls`, `cat`, `echo`, `which`, `git status`             |
+| Package management | 60s      | `npm install`, `pip install`, `brew install`            |
+| Build              | 120s     | `npm run build`, `tsc`, `esbuild`, `webpack`           |
+| Test               | 300s     | `npm test`, `vitest run`, `pytest`, `playwright test`  |
+| Default            | 30s      | Anything not in the above categories                   |
+
+**Every command gets a timeout. No exceptions.**
+
+## Background Processes
+
+Commands that never terminate must be run with `run_in_background: true`:
+
+- Dev servers: `npm run dev`, `next dev`, `vite dev`
+- Watch modes: `tsc --watch`, `vitest --watch`, `nodemon`
+- Log tailing: `tail -f`, `docker logs -f`
+- Containers: `docker compose up`
+- Any long-running process the subagent doesn't need to wait for
+
+After starting a background process, check its output via the harness's background-task output mechanism rather than blocking on it.
+
+## Output Control
+
+```bash
+# Cap output to prevent context overflow
+command | head -30
+
+# Capture both stdout and stderr
+command 2>&1 | head -30
+
+# Count lines before displaying
+command | wc -l    # check size first, then decide head limit
+
+# Git: always limit
+git log --oneline -20
+git diff --stat
+
+# Grep: files-only when appropriate
+grep -rl "pattern" src/
+```
+
+**Never** let unbounded output flood the context window. If output might exceed 50 lines, pipe through `head`.
+
+## Directory Navigation
+
+```bash
+# ❌ WRONG — breaks permission-prompt matching (matching starts from `cd`)
+cd /some/path && npm run build
+
+# ✅ CORRECT — preserves working directory, approval matches `npm`
+pushd /some/path && npm run build && popd
+
+# ✅ ALSO CORRECT — if already in the right directory
+npm run build
+```
+
+The `cd && command` pattern breaks command-matching for permission prompts because matching starts from `cd`, not the actual command. Always use `pushd`/`popd` for temporary directory changes.
+
+## Runtime Version Guard (Node/nvm)
+
+Projects that pin a Node version via nvm expect every command to run under that version — running under whatever `node` happens to be on PATH can produce misleading build/test failures or silently wrong behavior.
+
+Before running any Node-based command (`npm`, `npx`, `yarn`, `pnpm`, `node`, or project scripts that wrap them):
+
+1. Check the project root for `.nvmrc` or `.node-version`.
+2. If found, chain `nvm use` into the **same** `Bash` call as the actual command — shell state (including nvm's shell function) does not persist between separate tool calls:
+   ```bash
+   nvm use > /dev/null 2>&1; npm test
+   ```
+3. If `nvm` isn't installed, no version file exists, or the switch fails — proceed anyway with whatever `node` is on PATH. **Never block the task on this.**
+
+Do not run `nvm use` as its own command and expect it to carry over to the next one — it won't.
+
+## curl Rules
+
+- Always set `--max-time 5` to prevent hanging on unresponsive hosts
+- Localhost health checks only without explicit user approval
+- Never curl external URLs without user awareness
+
+## Timeout Recovery
+
+When a command times out:
+
+1. **Diagnose first** — `ps aux | grep <process>` to check if it's still running
+2. **Report to user** — Explain what happened and why
+3. **Don't blindly retry** — The same command will likely time out again
+4. **Suggest alternatives** — Smaller scope, different approach, or user intervention

package/assets/claude/packs/graphify/skills/agent-fundamentals/references/tool-usage-patterns.md

@@ -0,0 +1,67 @@
+# Tool Usage Patterns
+
+Comprehensive guide for when to use which tools. Built-in tools trump `Bash` in every case where they're available.
+
+## File Reading
+
+| Scenario                       | Tool             | Notes                                      |
+| --------------------------------- | ------------------ | -------------------------------------------- |
+| Read known file                | `Read`            | Specify `offset`/`limit` to limit token usage |
+| Read file overview             | `Grep`            | Search for key patterns in the file        |
+| Read file existence            | `Glob`            | Glob pattern matching                      |
+| Read directory listing         | `Glob`/`Bash` (`ls`) | Lists immediate children                |
+
+**Anti-patterns:**
+- `cat file.txt` — use `Read`
+- `less file.txt` — blocks terminal, use `Read`
+- `head -n 50 file.txt` — use `Read` with a line range
+- `node -e "console.log(fs.readFileSync(...))"` — never
+
+## Code Search
+
+| Scenario                        | Tool                                          | Notes                                                |
+| ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------- |
+| Primary codebase search         | `mcp__vesper-indexing__vesper_search`          | Full-text, returns snippets with paths + line ranges |
+| Find symbols (functions/classes)| `mcp__vesper-indexing__vesper_symbols`         | Name-based lookup with locations                     |
+| Exact text / regex match        | `Grep`                                          | Fast, supports regex, glob filters                   |
+| Find files by name/glob         | `Glob`                                          | Filename/path patterns only                          |
+
+**Anti-patterns:**
+- `grep -r "pattern" .` — use `Grep`
+- `find . -name "*.ts" -exec grep` — use `Glob` + `Grep`
+- `rg "pattern"` — use `Grep`
+- `tree` / `ls -R` — use `Glob`
+
+## File Writing
+
+| Scenario                   | Tool                     | Notes                                 |
+| ----------------------------- | -------------------------- | ---------------------------------------- |
+| Create new file            | `Write`                   | Creates parent directories            |
+| Edit existing file         | `Edit`                    | Include enough surrounding context to make the match unique |
+| Multiple identical edits   | `Edit` with `replace_all` | Batch identical replacements in one call |
+| Rename / move file         | `Bash` + `mv`             | Only case where terminal is correct   |
+
+**Anti-patterns:**
+- `echo "content" > file.txt` — use `Write`
+- `python -c "open('f','w').write('...')"` — never
+- `node -e "fs.writeFileSync(...)"` — never
+- `sed -i 's/old/new/g' file` — use `Edit`
+- `perl -pi -e 's/old/new/'` — use `Edit`
+
+## Error Checking
+
+| Scenario              | Tool          | Notes                                      |
+| ------------------------ | --------------- | --------------------------------------------- |
+| Compile/lint errors   | `Bash` (project's own lint/typecheck script) | No dedicated "get errors" tool — run what CI runs |
+| Test failures         | `Bash`        | For test execution                          |
+
+## When Terminal (`Bash`) IS Correct
+
+Terminal is the right tool for:
+- Running tests (`npm test`, `vitest run`, `pytest`)
+- Package management (`npm install`, `pip install`)
+- Build commands (`npm run build`)
+- Git operations (`git status`, `git diff`)
+- Starting dev servers (with `run_in_background: true`)
+- Moving/renaming files (`mv`)
+- Operations that have no built-in tool equivalent

package/assets/claude/packs/graphify/skills/graphify-research/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: graphify-research
+description: Code knowledge graph for research-side roles (task-researcher, se-system-architecture-reviewer) when the opt-in graphify pack is enabled. Routes impact ("who calls X"), path ("how does A reach B"), architecture and onboarding questions to the graphify MCP tools (query_graph, get_node, get_neighbors, shortest_path, get_pr_impact) and keeps locate/edit questions on vesper_search / vesper_symbols. Covers qualified node names, the EXTRACTED / INFERRED / AMBIGUOUS edge tags, why GRAPH_REPORT.md is never read whole, MCP tools over the CLI, and the fallback when the server or graph is absent.
+---
+
+# graphify research
+
+The `graphify` pack gives the **research-side roles** a code knowledge graph built by
+[graphify](https://github.com/Graphify-Labs/graphify) (an external tool; PyPI `graphifyy`, CLI
+`graphify`). It complements vesper-indexing, it does not replace it: `vesper_search` /
+`vesper_symbols` remain the default codebase tool for every role, and developers, testers and
+reviewers keep using them unchanged. This skill is loaded only by `task-researcher` and
+`se-system-architecture-reviewer`, and only when the Team Roster lists it (the pack is enabled).
+
+## When the graph beats the index (measured 2026-10-01, ~25k-LOC repo)
+
+| Question shape | Use | Why |
+| :-- | :-- | :-- |
+| **Locate** — "where is `decideHostAction` defined", "which file holds the gitignore writer" | `vesper_search` / `vesper_symbols` | Tie with the graph; the index is already loaded and returns the snippet you edit |
+| **Edit** — anything that ends in a code change | `vesper_search` / `vesper_symbols` | The developer roles never use the graph |
+| **Impact** — "who calls `decideHostAction`", "what breaks if `packs.js` changes" | graphify `get_neighbors` / `get_pr_impact` | ~40% fewer tokens AND complete — FTS missed callers inside test callbacks |
+| **Path** — "how does `utils/packs.js` reach `opencode-overlay.js`" | graphify `shortest_path` | 10–25× fewer tokens than reading files along the way |
+| **Architecture / onboarding** — "what are the modules and how do they cluster", "what is central here" | graphify `query_graph` (communities, god nodes) | One query instead of a directory traversal |
+
+Rule of thumb: a question whose answer is a **set of relationships** goes to the graph; a question
+whose answer is **a location or a snippet** goes to the index. When unsure, ask the index first
+(cheap, always present) and escalate to the graph for the relationship part.
+
+## Always pass QUALIFIED node names
+
+graphify's name matching is **fuzzy**: an unqualified `packs.js` resolved to `packs.test.js`.
+Every tool call names nodes by their **path-qualified** form:
+
+- a file: `src/cli/utils/packs.js` (never `packs.js`);
+- a symbol: `src/cli/utils/packs.js#enablePack` (file `#` symbol), or the `source_file` +
+  `label` pair `get_node` returns.
+
+Resolve the qualified name once with `get_node` (or with `vesper_symbols`) before an impact or path
+query, and quote it back in your report so the reader can repeat the query.
+
+## Use the MCP server, not the CLI
+
+The `graphify` CLI reloads `graphify-out/graph.json` (tens of MB) on every call (~2 s each). The
+pack registers the MCP server `graphify` (`vespercli mcp serve graphify`, which runs
+`python -m graphify.serve graphify-out/graph.json` under the interpreter graphify recorded in
+`graphify-out/.graphify_python`), which keeps the graph resident — its tools are the ones to call:
+
+| Tool | Use |
+| :-- | :-- |
+| `query_graph` | free-form question over the graph (communities, central nodes, "how does X relate to Y") |
+| `get_node` | one node's attributes (`label`, `source_file`, `source_location`, `community`) — the name resolver |
+| `get_neighbors` | the edges around a node: callers, callees, imports — the impact tool |
+| `shortest_path` | the chain from A to B — the path tool |
+| `get_pr_impact` | the nodes a change set touches and what depends on them |
+
+Never shell out to `graphify query` / `graphify path` from an agent when the server is available.
+The one CLI command you may name (never run yourself unless asked) is `graphify update .`, which
+builds or refreshes the graph.
+
+## Read the edge tags
+
+Every edge carries a confidence tag. Weight your conclusions by it and say which tag backs each
+claim:
+
+- **EXTRACTED** — from the code via tree-sitter. Trust it.
+- **INFERRED** — LLM-derived. Verify before acting on it: confirm with `get_node` on both ends or
+  a `vesper_search` for the relationship.
+- **AMBIGUOUS** — an unresolved name (several candidates). Confirm with `vesper_search` /
+  `vesper_symbols` which candidate the code really means before you report it.
+
+## Never read GRAPH_REPORT.md whole
+
+`graphify-out/GRAPH_REPORT.md` can be hundreds of KB. Query the specific node or section you need
+(`get_node`, `get_community`, or a targeted `vesper_search` over the report for one heading) —
+never load the file into context.
+
+## Cost and data flow
+
+- Code never leaves the machine: a code-only `graphify update .` is tree-sitter extraction, **0
+  tokens**, ~35 s on a ~25k-LOC repo (tens of thousands of nodes/edges, graph.json ~56 MB).
+- Doc/PDF extraction and community **labels** call an LLM. `--no-label` skips the labels; a
+  code-only run calls nothing.
+- `graphify-out/graph.json` is **committed and shared** (`vespercli packs enable graphify` writes
+  the `.gitignore` block that ignores the rest of `graphify-out/`); the Vesper post-checkout hook
+  runs `graphify update .` after a branch checkout when the tool is on PATH, so the graph follows
+  the branch. `vespercli doctor` reports a graph built from a commit other than HEAD
+  (`graphify-stale`).
+
+## When the server or the graph is absent
+
+If the `graphify` MCP tools are unavailable, or a call reports that `graphify-out/graph.json` does
+not exist or is stale:
+
+1. **Fall back to `vesper_search` / `vesper_symbols`** for the whole question — answer it the way
+   the roles always have; do not stop, do not ask the user to install anything mid-task.
+2. In your report, add one line: "graphify graph unavailable — answered from vesper-indexing; run
+   `graphify update .` (tool: `uv tool install graphifyy`, or `pipx install graphifyy`, or
+   `python3 -m pip install --user graphifyy`) to build the graph", and, for an impact
+   question, note that FTS may miss callers inside callbacks.
+3. Never run `graphify update .`, `graphify install` or any graphify LLM path yourself unless the
+   user asks for exactly that.

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.2.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.2.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.2.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.2.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):
 
@@ -179,7 +179,7 @@ off your own inference about the host.
 - Because of direct collaboration, a `NEED_HELP` you receive means the subagent genuinely couldn't resolve it — its `Agent` tool was missing, the depth budget was spent, or the need is a full pipeline step (which is yours to route, never theirs to run). Route it per the roster and re-delegate with the answer.
 - Multiple `Agent` calls can run in parallel in a single turn — use this for independent tracks (see Orchestration Loop below). Nested spawns by your delegates count toward overall load: when delegating to agents likely to collaborate (planner, TPM, feature-wrap), keep your own parallel fan-out modest (≤ 3).
 
-**Codebase context**: Subagents MUST use `vesper-indexing` MCP tools (`mcp__vesper-indexing__vesper_search`, `mcp__vesper-indexing__vesper_symbols`) for codebase queries. If MCP is unavailable, STOP and ask the user — do NOT silently fall back. Avoid full directory traversals. If the index is empty or stale, delegate to `workspace-learner` to reindex.
+**Codebase context**: Subagents MUST use `vesper-indexing` MCP tools (`mcp__vesper-indexing__vesper_search`, `mcp__vesper-indexing__vesper_symbols`) for codebase queries. If MCP is unavailable, STOP and ask the user — do NOT silently fall back. Avoid full directory traversals. If the index is empty or stale, delegate to `workspace-learner` to reindex. When the `graphify` pack is enabled, research-side roles additionally use the graphify MCP tools (`graphify-research` skill) for impact, path and architecture questions.
 
 **Delegation prompt framing**: When referencing codebase artifacts in delegation prompts, describe **what to investigate** (concepts, patterns, behaviors), not **which files to read**. Subagents own their own discovery workflow via vesper-indexing. File paths may appear as hints, never as read commands.
 

package/assets/copilot/agents/workspace-learner.agent.md

@@ -276,7 +276,7 @@ Before assuming any subagent is available, check whether `~/.vesper/skills/vespe
 
 Run `vesper list --target claude` via `Bash` and capture the full output. This lists every subagent, command, and skill currently installed in the plugin catalog.
 
-**Packs.** The catalog is a **core** plugin plus stack **packs** (`frontend`, `playwright`, `backend`, `polyglot`, `docs`, `integrations`), and a pack is enabled per project only when the roster needs it — so the installed listing may show a pack as *disabled*. Pick from the **whole catalog index** regardless: run `vespercli catalog` (the shipped `CATALOG.md`; always complete) and read each entry's `Pack:` line. A packed specialist is delegated to as `<name>`; a packed skill is `<name>`. You never enable a pack yourself — the orchestrator runs `vespercli packs sync` after you hand off (final step below).
+**Packs.** The catalog is a **core** plugin plus stack **packs** (`frontend`, `playwright`, `backend`, `polyglot`, `docs`, `integrations`), and a pack is enabled per project only when the roster needs it — so the installed listing may show a pack as *disabled*. Pick from the **whole catalog index** regardless: run `vespercli catalog` (the shipped `CATALOG.md`; always complete) and read each entry's `Pack:` line. A packed specialist is delegated to as `<name>`; a packed skill is `<name>`. You never enable a pack yourself — the orchestrator runs `vespercli packs sync` after you hand off (final step below). Two packs are **opt-in** and never enabled by the sync: `styles` and `graphify`. When `vespercli packs` shows `graphify` as *enabled*, add the `graphify-research` skill to the Assigned Skills of the Research (`task-researcher`) and Architecture (`se-system-architecture-reviewer`) rows only — developers, testers and reviewers keep `vesper-indexing` as their codebase tool; when it is disabled, do not list the skill anywhere.
 
 #### Step 2 — Match Team Composition to Catalog
 

package/assets/copilot/packs/graphify/skills/graphify-research/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: graphify-research
+description: Code knowledge graph for research-side roles (task-researcher, se-system-architecture-reviewer) when the opt-in graphify pack is enabled. Routes impact ("who calls X"), path ("how does A reach B"), architecture and onboarding questions to the graphify MCP tools (query_graph, get_node, get_neighbors, shortest_path, get_pr_impact) and keeps locate/edit questions on vesper_search / vesper_symbols. Covers qualified node names, the EXTRACTED / INFERRED / AMBIGUOUS edge tags, why GRAPH_REPORT.md is never read whole, MCP tools over the CLI, and the fallback when the server or graph is absent.
+---
+
+# graphify research
+
+The `graphify` pack gives the **research-side roles** a code knowledge graph built by
+[graphify](https://github.com/Graphify-Labs/graphify) (an external tool; PyPI `graphifyy`, CLI
+`graphify`). It complements vesper-indexing, it does not replace it: `vesper_search` /
+`vesper_symbols` remain the default codebase tool for every role, and developers, testers and
+reviewers keep using them unchanged. This skill is loaded only by `task-researcher` and
+`se-system-architecture-reviewer`, and only when the Team Roster lists it (the pack is enabled).
+
+## When the graph beats the index (measured 2026-10-01, ~25k-LOC repo)
+
+| Question shape | Use | Why |
+| :-- | :-- | :-- |
+| **Locate** — "where is `decideHostAction` defined", "which file holds the gitignore writer" | `vesper_search` / `vesper_symbols` | Tie with the graph; the index is already loaded and returns the snippet you edit |
+| **Edit** — anything that ends in a code change | `vesper_search` / `vesper_symbols` | The developer roles never use the graph |
+| **Impact** — "who calls `decideHostAction`", "what breaks if `packs.js` changes" | graphify `get_neighbors` / `get_pr_impact` | ~40% fewer tokens AND complete — FTS missed callers inside test callbacks |
+| **Path** — "how does `utils/packs.js` reach `opencode-overlay.js`" | graphify `shortest_path` | 10–25× fewer tokens than reading files along the way |
+| **Architecture / onboarding** — "what are the modules and how do they cluster", "what is central here" | graphify `query_graph` (communities, god nodes) | One query instead of a directory traversal |
+
+Rule of thumb: a question whose answer is a **set of relationships** goes to the graph; a question
+whose answer is **a location or a snippet** goes to the index. When unsure, ask the index first
+(cheap, always present) and escalate to the graph for the relationship part.
+
+## Always pass QUALIFIED node names
+
+graphify's name matching is **fuzzy**: an unqualified `packs.js` resolved to `packs.test.js`.
+Every tool call names nodes by their **path-qualified** form:
+
+- a file: `src/cli/utils/packs.js` (never `packs.js`);
+- a symbol: `src/cli/utils/packs.js#enablePack` (file `#` symbol), or the `source_file` +
+  `label` pair `get_node` returns.
+
+Resolve the qualified name once with `get_node` (or with `vesper_symbols`) before an impact or path
+query, and quote it back in your report so the reader can repeat the query.
+
+## Use the MCP server, not the CLI
+
+The `graphify` CLI reloads `graphify-out/graph.json` (tens of MB) on every call (~2 s each). The
+pack registers the MCP server `graphify` (`vespercli mcp serve graphify`, which runs
+`python -m graphify.serve graphify-out/graph.json` under the interpreter graphify recorded in
+`graphify-out/.graphify_python`), which keeps the graph resident — its tools are the ones to call:
+
+| Tool | Use |
+| :-- | :-- |
+| `query_graph` | free-form question over the graph (communities, central nodes, "how does X relate to Y") |
+| `get_node` | one node's attributes (`label`, `source_file`, `source_location`, `community`) — the name resolver |
+| `get_neighbors` | the edges around a node: callers, callees, imports — the impact tool |
+| `shortest_path` | the chain from A to B — the path tool |
+| `get_pr_impact` | the nodes a change set touches and what depends on them |
+
+Never shell out to `graphify query` / `graphify path` from an agent when the server is available.
+The one CLI command you may name (never run yourself unless asked) is `graphify update .`, which
+builds or refreshes the graph.
+
+## Read the edge tags
+
+Every edge carries a confidence tag. Weight your conclusions by it and say which tag backs each
+claim:
+
+- **EXTRACTED** — from the code via tree-sitter. Trust it.
+- **INFERRED** — LLM-derived. Verify before acting on it: confirm with `get_node` on both ends or
+  a `vesper_search` for the relationship.
+- **AMBIGUOUS** — an unresolved name (several candidates). Confirm with `vesper_search` /
+  `vesper_symbols` which candidate the code really means before you report it.
+
+## Never read GRAPH_REPORT.md whole
+
+`graphify-out/GRAPH_REPORT.md` can be hundreds of KB. Query the specific node or section you need
+(`get_node`, `get_community`, or a targeted `vesper_search` over the report for one heading) —
+never load the file into context.
+
+## Cost and data flow
+
+- Code never leaves the machine: a code-only `graphify update .` is tree-sitter extraction, **0
+  tokens**, ~35 s on a ~25k-LOC repo (tens of thousands of nodes/edges, graph.json ~56 MB).
+- Doc/PDF extraction and community **labels** call an LLM. `--no-label` skips the labels; a
+  code-only run calls nothing.
+- `graphify-out/graph.json` is **committed and shared** (`vespercli packs enable graphify` writes
+  the `.gitignore` block that ignores the rest of `graphify-out/`); the Vesper post-checkout hook
+  runs `graphify update .` after a branch checkout when the tool is on PATH, so the graph follows
+  the branch. `vespercli doctor` reports a graph built from a commit other than HEAD
+  (`graphify-stale`).
+
+## When the server or the graph is absent
+
+If the `graphify` MCP tools are unavailable, or a call reports that `graphify-out/graph.json` does
+not exist or is stale:
+
+1. **Fall back to `vesper_search` / `vesper_symbols`** for the whole question — answer it the way
+   the roles always have; do not stop, do not ask the user to install anything mid-task.
+2. In your report, add one line: "graphify graph unavailable — answered from vesper-indexing; run
+   `graphify update .` (tool: `uv tool install graphifyy`, or `pipx install graphifyy`, or
+   `python3 -m pip install --user graphifyy`) to build the graph", and, for an impact
+   question, note that FTS may miss callers inside callbacks.
+3. Never run `graphify update .`, `graphify install` or any graphify LLM path yourself unless the
+   user asks for exactly that.

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/manifest.json

@@ -5,6 +5,7 @@
     "backend",
     "docs",
     "frontend",
+    "graphify",
     "integrations",
     "playwright",
     "polyglot",
@@ -82,6 +83,7 @@
     "gitlab-ci-skill",
     "gitlab-guardrails",
     "google-adk-python",
+    "graphify-research",
     "i-have-adhd",
     "java",
     "mcp-builder",
@@ -170,6 +172,7 @@
       "gitlab-ci-skill": "integrations",
       "gitlab-guardrails": "integrations",
       "google-adk-python": "polyglot",
+      "graphify-research": "graphify",
       "i-have-adhd": "styles",
       "java": "polyglot",
       "mcp-builder": "core",

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;