@mthanh/vespercli 2.0.1 → 2.2.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,15 +84,16 @@ 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?"
 ```
 
-A non-interactive run (no TTY) never guesses. It re-uses the host the checked-out tree already carries, and otherwise needs `--host`. `-y`/`--force-default` default the follow-up questions only, never the host choice.
+A non-interactive run (no TTY) never guesses. It re-uses the host the checked-out tree already carries, and otherwise needs `--host`. `-y`/`--force-default` default the follow-up questions only, never the host choice. The last follow-up question, on both hosts, is the opt-in [graphify](#graphify-optional) pack (default no; `--graphify` answers yes without asking, which is also the only way to get it in a `-y`/`--force-default`/non-TTY run; a workspace that already has the pack is never asked again and never loses it).
 
 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
@@ -332,6 +357,7 @@ Every workspace gets three core servers: `vesper-indexing` (fast code search ove
 vespercli mcp                   # status for the checkout's host
 vespercli mcp list              # catalog + custom servers, and which are installed
 vespercli mcp add clickup       # add an optional catalog server (recorded in .vesperrc)
+vespercli mcp add graphify      # the graphify pack's server (packs enable graphify does this too)
 vespercli mcp remove clickup
 vespercli mcp enable | disable  # the core servers
 vespercli mcp sync              # re-sync tool auto-approval (Copilot) / refresh config (Claude)
@@ -371,6 +397,7 @@ The catalog is a **core** plugin plus six stack **packs**, and a project enables
 | `polyglot` | `vesper-polyglot` | — | `java`, `flutter`, `google-adk-python` |
 | `docs` | `vesper-docs` | — | `document-skills`, `ai-multimodal` |
 | `integrations` | `vesper-integrations` | `clickup-agent` | `gitlab-guardrails` |
+| `graphify` (opt-in) | `vesper-graphify` | — | `graphify-research` (see [graphify](#graphify-optional)) |
 
 Every pack also carries a byte-identical copy of the shared `agent-fundamentals` skill (every agent preloads it by bare name; the generator keeps the copies in sync). `vespercli catalog` (the shipped `assets/CATALOG.md`) names each asset's pack, and `assets/manifest.json` carries the same mapping for the CLI.
 
@@ -381,6 +408,22 @@ Every pack also carries a byte-identical copy of the shared `agent-fundamentals`
 
 Only the core key resolves the host: a workspace whose settings carry pack keys alone resolves nothing. `reset --host <host>` removes the pack keys or locations with the core ones, and a host switch replays them onto the new host. `vespercli doctor` reports a roster naming an asset of a disabled pack as `pack-not-enabled` (WARN, fix `vespercli packs sync`) and an enabled pack the roster does not use as `pack-unused` (INFO). A workspace provisioned before packs keeps working: core resolves as before, and the next `init` (or `packs sync`) enables what its roster needs.
 
+## graphify (optional)
+
+The opt-in `graphify` pack gives the **research-side roles** (`task-researcher`, `se-system-architecture-reviewer`) a code knowledge graph built by [graphify](https://github.com/Graphify-Labs/graphify) — an **external tool** installed on your machine (PyPI package `graphifyy`, CLI `graphify`); Vesper ships only its own `graphify-research` skill, which routes impact ("who calls X"), path ("how does A reach B") and architecture questions to the graphify MCP tools and keeps locate/edit questions on `vesper_search` / `vesper_symbols`. `vesper-indexing` remains the default codebase tool for every role; developers, testers and reviewers are unchanged.
+
+```bash
+uv tool install graphifyy          # the tool (external) — or: pipx install graphifyy / python3 -m pip install --user graphifyy
+vespercli packs enable graphify    # the consent — prepares the workspace, see below (vespercli init asks the same question)
+graphify update .                  # builds graphify-out/graph.json (~35 s on a 25k-LOC repo, 0 tokens)
+```
+
+**Installing the tool.** Three routes, in the order Vesper prefers them: `uv tool install graphifyy` when [uv](https://docs.astral.sh/uv/) is on PATH, `pipx install graphifyy` when pipx is, `python3 -m pip install --user graphifyy` when only Python is; with none of them, install uv first (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `pip install uv`). `vespercli init` offers the pack as its last follow-up question (default no, `--graphify` answers yes) and, interactively, when the tool is not on PATH, offers to run this machine's install command for you (`Install graphifyy now? (<command>)`, default yes; a failed install prints the hint and never fails init). `packs enable graphify` makes the same offer; `-y`, `--force-default` and non-TTY runs never install anything and print the command instead. `vespercli doctor`'s `graphify-missing` fix and `vespercli mcp status` name the same command.
+
+`packs enable graphify` writes three things, all ledger-recorded and removed by `packs disable graphify`, `reset --host` and a host switch (replayed on the new host): a guarded **`.gitignore` sub-block** (`graphify-out/*` ignored, `!graphify-out/graph.json` so the graph itself is **committed and shared**), a guarded sub-block in Vesper's **`post-checkout` hook** that runs `graphify update .` after a branch checkout and is a no-op when the tool is not on PATH, and the **`graphify` MCP server** — registered on both hosts as `vespercli mcp serve graphify` (the same registration as `vespercli mcp add graphify`, and the `opencode.json` mirror), which runs `python -m graphify.serve graphify-out/graph.json` under the interpreter graphify recorded in `graphify-out/.graphify_python` when it built the graph (a `uv tool` / `pipx` install lives in its own venv, so a bare `python` would not import it), else `python3` / `python` on PATH. When the roster lists `graphify-research` on the two research rows, `workspace-learner` writes it there and nowhere else.
+
+**Data flow.** Code never leaves the machine: a code-only `graphify update .` is tree-sitter extraction at **0 tokens**. Doc/PDF extraction and community *labels* call an LLM — pass `--no-label` to skip the labels. Agents use the MCP server (the graph stays resident), never the CLI (which reloads the ~50 MB `graph.json` per call), always pass path-qualified node names (matching is fuzzy), never read `GRAPH_REPORT.md` whole, and weight every edge by its `EXTRACTED` / `INFERRED` / `AMBIGUOUS` tag. `vespercli doctor` reports, never as an error: `graphify-missing` (tool not on PATH), `graphify-no-graph` (no `graph.json` yet) and `graphify-stale` (the graph's built-from commit is not HEAD — `graphify update .`).
+
 ## Third-party skills (packs)
 
 Third-party content is **pack content**: shipped in the npm package like every other pack asset, served through the pack's plugin (Claude) or injected folder (Copilot), pinned to an upstream commit in an `UPSTREAM.json` beside each `SKILL.md` (with the upstream `LICENSE` verbatim), never fetched at command time — and **never written into a project**. Nothing lands under `.claude/skills/` or `.vesper/skills/`; there is no consent prompt, no `--adhd`/`--ponytail` flag and no `~/.vesperrc` record any more.
@@ -396,9 +439,9 @@ A newer upstream reaches your project with the next Vesper release. `vespercli p
 
 | Command | What it does |
 |---|---|
-| `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 init [--host claude\|copilot] [-y] [--force-default] [--graphify] [--path <dir>]` | Provision, switch host, re-provision, or migrate a 1.x workspace. `--graphify` enables the opt-in [graphify](#graphify-optional) pack without asking (otherwise the last follow-up question; the default is no pack). `--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/CATALOG.md

@@ -73,6 +73,13 @@ same mapping (`assetPacks`) for the CLI.
 - Agents: `expert-nextjs-developer`, `expert-react-frontend-engineer`, `jest-react-component-analyzer`, `jest-react-scenario-scanner`, `jest-react-test-generator`, `jest-react-test-planner`, `jest-react-test-runner`
 - Skills: `aesthetic`, `frontend-design`, `nextjs`, `nextjs-tailwind`, `premium-frontend-ui`, `react-mui-tanstack`, `reactjs`, `tailwind-shadcn`, `tailwind-v4-vite`, `vercel-react-best-practices`, `web-design-guidelines`, `web-frameworks` (+ the shared `agent-fundamentals` copy)
 
+### graphify
+
+- Plugin: `vesper-graphify` (source `./packs/graphify`)
+- Description: Opt-in code knowledge graph for the research-side roles. [graphify](https://github.com/Graphify-Labs/graphify) is an **external tool** (`uv tool install graphifyy`), never vendored — the pack ships only Vesper's own `graphify-research` skill. Never enabled by the roster sync: `vespercli packs enable graphify` is the consent; it also writes the `.gitignore` block (`graphify-out/*` ignored, `graphify-out/graph.json` committed), the `post-checkout` sub-block that runs `graphify update .` when the tool is on PATH, and registers the `graphify` MCP server (`python -m graphify.serve`); `packs disable graphify` removes all three. `vesper-indexing` stays the default codebase tool for every role.
+- Agents: —
+- Skills: `graphify-research` (+ the shared `agent-fundamentals` copy)
+
 ### integrations
 
 - Plugin: `vesper-integrations` (source `./packs/integrations`)
@@ -492,6 +499,13 @@ Copilot `.instructions.md` with that glob, in the tier named by its
 - Description: Build, evaluate, and deploy AI agents using Google ADK (Agent Development Kit) for Python.
 - Pick when: Implementing agents in Python with tools and orchestration; need multi-agent hierarchies or workflow agents (sequential/parallel/loop); deploying to Vertex AI Agent Engine / Cloud Run.
 
+### graphify-research
+
+- Path: `claude/packs/graphify/skills/graphify-research/`
+- Pack: graphify (`vesper-graphify`)
+- Description: Vesper-authored routing for the graphify code knowledge graph (MCP tools `query_graph`, `get_node`, `get_neighbors`, `shortest_path`, `get_pr_impact`): impact, path, architecture and onboarding questions go to the graph; locate/edit questions stay on `vesper_search` / `vesper_symbols`. Always path-qualified node names (fuzzy matching), EXTRACTED / INFERRED / AMBIGUOUS edge tags, never read `GRAPH_REPORT.md` whole, MCP server over the CLI, fallback to vesper-indexing when the graph or server is absent.
+- Pick when: Only with the opt-in `graphify` pack enabled, and only on the Research (`task-researcher`) and Architecture (`se-system-architecture-reviewer`) rows — never for developers, testers or reviewers.
+
 ### i-have-adhd
 
 - Path: `claude/packs/styles/skills/i-have-adhd/`

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

@@ -7,50 +7,56 @@
     {
       "name": "vesper",
       "source": "./",
-      "version": "2.0.1",
+      "version": "2.2.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",
-      "description": "Vesper frontend pack — React, Next.js, Tailwind and Jest/RTL specialists and skills."
+      "version": "2.2.0",
+      "description": "Vesper frontend pack \u2014 React, Next.js, Tailwind and Jest/RTL specialists and skills."
     },
     {
       "name": "vesper-playwright",
       "source": "./packs/playwright",
-      "version": "2.0.1",
-      "description": "Vesper playwright pack — Playwright end-to-end testing specialists and skills."
+      "version": "2.2.0",
+      "description": "Vesper playwright pack \u2014 Playwright end-to-end testing specialists and skills."
     },
     {
       "name": "vesper-backend",
       "source": "./packs/backend",
-      "version": "2.0.1",
-      "description": "Vesper backend pack — Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills."
+      "version": "2.2.0",
+      "description": "Vesper backend pack \u2014 Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills."
     },
     {
       "name": "vesper-polyglot",
       "source": "./packs/polyglot",
-      "version": "2.0.1",
-      "description": "Vesper polyglot pack — Java, Flutter and Google ADK (Python) skills."
+      "version": "2.2.0",
+      "description": "Vesper polyglot pack \u2014 Java, Flutter and Google ADK (Python) skills."
     },
     {
       "name": "vesper-docs",
       "source": "./packs/docs",
-      "version": "2.0.1",
-      "description": "Vesper docs pack — Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills."
+      "version": "2.2.0",
+      "description": "Vesper docs pack \u2014 Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills."
     },
     {
       "name": "vesper-integrations",
       "source": "./packs/integrations",
-      "version": "2.0.1",
-      "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)."
+      "version": "2.2.0",
+      "description": "Vesper integrations pack \u2014 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",
-      "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."
+      "version": "2.2.0",
+      "description": "Vesper styles pack \u2014 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."
+    },
+    {
+      "name": "vesper-graphify",
+      "source": "./packs/graphify",
+      "version": "2.2.0",
+      "description": "Vesper graphify pack \u2014 opt-in code knowledge graph for the research-side roles (the `graphify-research` skill). graphify is an external tool installed separately (`uv tool install graphifyy`); `vespercli packs enable graphify` prepares the workspace and registers its MCP server."
     }
   ]
 }

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

@@ -1,7 +1,7 @@
 {
   "name": "vesper",
   "displayName": "Vesper",
-  "version": "2.0.1",
+  "version": "2.2.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/agents/workspace-learner.md

@@ -275,7 +275,7 @@ Before assuming any subagent is available, check whether `~/.claude/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 `vesper-<pack>:<name>`; a packed skill is `/vesper-<pack>:<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 `vesper-<pack>:<name>`; a packed skill is `/vesper-<pack>:<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/claude/orchestration.md.tpl

@@ -6,7 +6,7 @@ description: 'Vesper orchestration data — team roster, task management, routin
 
 **Source of truth**: this file is the single authority for this project's available specialist subagents, their roles, and their skill assignments. The orchestrator playbook (the always-on `.claude/rules/vesper-orchestrator.md` rule) routes purely by the names listed in the **Team Roster** below.
 
-**Delegation-name convention (correctness invariant):** every specialist Agent Name in the roster below is the plugin's **namespaced** name — `vesper:<name>` for a core specialist, `vesper-<pack>:<name>` for one shipped by a pack (the catalog index `assets/CATALOG.md` / `vespercli catalog` names each asset's pack) — that is exactly the `subagent_type` the orchestrator must delegate with, since the specialist catalog ships as the `vesper` marketplace plugin plus its packs. The one exception is the committed main-thread persona `vesper-orchestrator` (a project agent, no namespace), used only as the `.claude/settings.json` `agent` key value. `workspace-learner` MUST preserve the plugin prefix on every specialist name it writes here. A packed asset named here (agent or assigned skill) needs its pack enabled for this project: `vespercli packs sync` enables what this roster needs (`init`/`update` run it too; `vespercli doctor` reports a gap as `pack-not-enabled`).
+**Delegation-name convention (correctness invariant):** every specialist Agent Name in the roster below is the plugin's **namespaced** name — `vesper:<name>` for a core specialist, `vesper-<pack>:<name>` for one shipped by a pack (the catalog index `assets/CATALOG.md` / `vespercli catalog` names each asset's pack) — that is exactly the `subagent_type` the orchestrator must delegate with, since the specialist catalog ships as the `vesper` marketplace plugin plus its packs. The one exception is the committed main-thread persona `vesper-orchestrator` (a project agent, no namespace), used only as the `.claude/settings.json` `agent` key value. `workspace-learner` MUST preserve the plugin prefix on every specialist name it writes here. A packed asset named here (agent or assigned skill) needs its pack enabled for this project: `vespercli packs sync` enables what this roster needs (`init`/`update` run it too; `vespercli doctor` reports a gap as `pack-not-enabled`). When the opt-in `graphify` pack is enabled (`vespercli packs enable graphify`), the Research and Architecture rows (`task-researcher`, `se-system-architecture-reviewer`) additionally carry the `graphify-research` skill — impact, path and architecture questions go to the graphify MCP tools; every other role keeps `vesper-indexing` unchanged.
 
 ## Repository Policy
 

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.2.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.2.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.2.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/graphify/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "vesper-graphify",
+  "displayName": "Vesper graphify pack",
+  "version": "2.2.0",
+  "description": "opt-in code knowledge graph for the research-side roles: the Vesper-authored `graphify-research` skill (graph vs FTS routing, qualified node names, EXTRACTED/INFERRED/AMBIGUOUS edge tags). graphify itself (https://github.com/Graphify-Labs/graphify) is an external tool installed separately (`uv tool install graphifyy`), never vendored; `vespercli packs enable graphify` is the consent and prepares the workspace (gitignore + post-checkout blocks, the graphify MCP server). vesper-indexing stays the default codebase tool.",
+  "author": {
+    "name": "Vesper Maintainers"
+  },
+  "license": "MIT"
+}

package/assets/claude/packs/graphify/skills/agent-fundamentals/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: agent-fundamentals
+description: Universal operating rules for all Vesper subagents — codebase query protocol, terminal discipline, tool usage patterns, and response standards. Use when any subagent needs to search code, run terminal commands, perform file operations, or produce output. This is the baseline skill every Vesper subagent should follow.
+---
+
+# Vesper Agent Fundamentals
+
+Universal operating rules for every subagent in the Vesper ecosystem. These are non-negotiable behaviors — not guidelines.
+
+## Codebase Query Protocol
+
+**PRIMARY**: `vesper-indexing` MCP tools are the first-choice codebase exploration method.
+
+| Tool                                  | Purpose                                               |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `mcp__vesper-indexing__vesper_search`  | Full-text code search → returns snippets + file paths |
+| `mcp__vesper-indexing__vesper_symbols` | Find functions, classes, exports by name + location   |
+| `mcp__vesper-indexing__vesper_status`  | Check index health before querying                    |
+| `mcp__vesper-indexing__vesper_reindex` | Rebuild index if stale or empty                       |
+
+- Results include actual source code — skip `Read` unless you need wider surrounding context.
+- If the index is empty or MCP unavailable → **STOP and report**. Do NOT silently fall back to directory traversals or `find` commands.
+- For broader exploration beyond indexed content: `Grep`, `Glob` are acceptable secondary tools.
+- **Archives are off-limits in normal pipelines**: never read, grep, or search `.vesper/history-archive/` or `.vesper/.tracking/archive/` during ordinary work — they are index-excluded and reachable only via `/revalidate-knowledge`. See [codebase-query.md](references/codebase-query.md).
+
+## Terminal Discipline
+
+See [terminal-discipline.md](references/terminal-discipline.md) for expanded rules and examples.
+
+| Rule                       | Requirement                                                            |
+| --------------------------- | -------------------------------------------------------------------------- |
+| **Timeout**                | Every command gets one. Quick=15s, build=120s, test=300s. Default=30s. |
+| **No foreground blockers** | `tail -f`, `watch`, dev servers → always run with `run_in_background: true`. |
+| **Output cap**             | `\| head -30` if output may exceed 50 lines.                           |
+| **Stderr capture**         | `2>&1 \| head -N` for both stdout and stderr.                          |
+| **No `cd &&` chaining**    | Use `pushd path && command && popd` instead.                           |
+| **Runtime version guard**  | Node commands → check `.nvmrc`/`.node-version`, chain `nvm use` in the same call. Ignore if unavailable. |
+| **Tools-first**            | Never use `Bash` for tasks built-in tools handle.                     |
+
+## Tool Usage Hierarchy
+
+See [tool-usage-patterns.md](references/tool-usage-patterns.md) for comprehensive patterns and anti-patterns.
+
+**Always prefer built-in tools over `Bash` equivalents:**
+
+| Task          | ✅ Correct Tool          | ❌ Never Do This                             |
+| -------------- | -------------------------- | ---------------------------------------------- |
+| Read a file   | `Read`                    | `cat`, `less`, `node -e "fs.readFileSync()"` |
+| Search code   | `Grep`, `mcp__vesper-indexing__vesper_search` | `grep -r`, `find . -exec grep` |
+| Find files    | `Glob`                    | `find .`, `ls -R`, `tree`                    |
+| Create a file | `Write`                   | `echo > file`, `python -c "open().write()"`  |
+| Edit a file   | `Edit`                    | `sed -i`, `node -e "fs.writeFileSync()"`     |
+| Check errors  | `Bash` (the project's own lint/typecheck command) | Manual terminal compilation |
+
+## Secret & Credential Handling
+
+**NEVER write a secret to a file.** No token, API key, password, private key, or connection string carrying an embedded secret may be written into any file you `Write` or `Edit` — regardless of git host, language, or task.
+
+| Trigger                                                          | Required Action                                                                                                                                                        |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A value about to be written looks like a token/credential/secret | **STOP** — do not write it. Require explicit user confirmation before proceeding.                                                                                      |
+| You are a subagent and cannot ask the user directly              | **Escalate, don't write** — surface the blocker and stop (same reflex as the Codebase Query Protocol's "STOP and report"), rather than silently writing the secret. Return `NEED_HELP` to the orchestrator so a human is asked before any write. |
+| The user explicitly approves writing the value                   | Proceed, then **record the approved exception** back into the project's instructions (`CLAUDE.md` or the relevant `.claude/vesper/*.md`) so the same value isn't re-flagged on a later pass. |
+
+- Detection is on the **value**, not the file: a secret-shaped string (a long random token, `ghp_…`/`glpat-…`-style prefixes, a PEM `-----BEGIN … PRIVATE KEY-----` block, a `user:password@host` connection URL) triggers the stop — even inside configs, tests, or docs.
+- Prefer a placeholder or environment-variable reference (`${MY_TOKEN}`) over the literal secret whenever a file genuinely needs the name.
+- When in doubt, halt and surface it — never silently work around it.
+
+## Direct Collaboration (Nested Delegation)
+
+If your toolset includes `Agent`, you may delegate directly to another specialist instead of returning `NEED_HELP` to the orchestrator. This is the preferred path for bounded assists — it saves a full round-trip through the orchestrator.
+
+**Protocol:**
+
+1. **Roster only**: Pick the collaborator from the Team Roster (`.claude/vesper/orchestration.md`) and use its **exact name** as the `subagent_type`. If it's not on the roster, it doesn't exist.
+2. **Depth accounting**: Your delegation prompt includes a `Nesting depth: N` marker (the orchestrator is depth 0; its direct delegates are depth 1). When you delegate, include `Nesting depth: N+1` in the prompt. If no marker was given, assume you are at depth 1.
+3. **Depth budget**: If your depth N ≥ 3, do NOT delegate — end with `Status: NEED_HELP` instead and describe what you need in `Next:`. (The platform maximum is 5; stopping at 3 leaves headroom for your collaborator to make one nested call of its own.)
+4. **Point assists only**: Nested delegation is for a bounded question, review, lookup, or gap-fill — never for executing a whole pipeline step that belongs on the orchestrator's todo list. If the work you need is a pipeline step, return `NEED_HELP`.
+5. **Self-contained prompts**: Same rules the orchestrator follows — include file paths, enough background to act, the expected output, the depth marker, and the requirement to end with the `Status:/Summary:/Next:` footer.
+6. **Fold results in**: Your collaborator's final message returns to YOU, not the orchestrator. Incorporate it into your own artifacts/output, and note the collaboration in your final `Summary:` so the orchestrator has the full picture.
+7. **Fallback is always available**: `Agent` tool missing from your toolset, the call fails, or the depth budget is spent → end with `Status: NEED_HELP` and what you need in `Next:`. The orchestrator will route it.
+
+## Response Standards
+
+- **Be direct**: State findings, don't narrate your process.
+- **Show evidence**: Back claims with file paths, line numbers, or code snippets.
+- **Report blockers immediately**: If MCP tools fail, index is empty, or permissions block you — say so. Don't silently work around it.
+- **No verbose preambles**: Skip "I'll now..." or "Let me..." — just do the work.
+- **Structured output**: Use Markdown tables, bullet lists, and code blocks. Walls of text = failure.

package/assets/claude/packs/graphify/skills/agent-fundamentals/references/codebase-query.md

@@ -0,0 +1,95 @@
+# Codebase Query Protocol
+
+How Vesper subagents should explore and understand any codebase.
+
+## Priority Order
+
+```
+1. vesper-indexing MCP tools       (PRIMARY — always try first)
+2. Grep                            (SECONDARY — when index lacks coverage)
+3. Glob + Read                     (TERTIARY — targeted file inspection)
+4. Bash                            (LAST RESORT — only for operations with no built-in equivalent)
+```
+
+## Archive Exclusion (normal pipelines)
+
+Archived knowledge directories — `.vesper/history-archive/`, `.vesper/.tracking/archive/`, and `.vesper/.tracking/stories/completed/archive/` — are **excluded from all normal-pipeline reads, greps, and searches**. They are also excluded from the `vesper-indexing` index (`DEFAULT_EXCLUDES`), so `vesper_search`/`vesper_symbols` never surface their contents. Do NOT `Grep`, `Read`, or otherwise crawl these paths during ordinary research, planning, implementation, or review work. They hold intentionally retired material (rotated history, archived tracking artifacts) and are reachable **only** through the explicit `/revalidate-knowledge` flow, which re-validates archived knowledge against current code. If you think you need something from an archive, that is a signal to surface `/revalidate-knowledge` to the user — not to read the archive directly.
+
+## vesper-indexing MCP Tools
+
+### mcp__vesper-indexing__vesper_search
+
+Full-text code search across the indexed workspace. Returns matching code snippets with file paths and line ranges.
+
+```
+Use for: Finding specific code patterns, function calls, variable usage,
+         string literals, error messages, configuration values
+```
+
+**Key behavior**: Results include actual source code. In most cases, you DO NOT need a follow-up `Read` unless you need wider context beyond the returned snippet.
+
+### mcp__vesper-indexing__vesper_symbols
+
+Find functions, classes, exports, and other symbols by name. Returns symbol type, location, and surrounding code.
+
+```
+Use for: Finding function definitions, class declarations, exported modules,
+         understanding module interfaces, locating entry points
+```
+
+### mcp__vesper-indexing__vesper_status
+
+Check the health and state of the search index.
+
+```
+Use for: Verifying the index is populated before querying,
+         checking if a reindex is needed after major file changes
+```
+
+### mcp__vesper-indexing__vesper_reindex
+
+Force a rebuild of the search index.
+
+```
+Use for: After bulk file operations, when vesper_status reports stale data,
+         when search results seem incomplete
+```
+
+## Index Failure Protocol
+
+If vesper-indexing tools fail or return empty results:
+
+1. **STOP** — do not silently fall back
+2. **Report** the failure to the user: "vesper-indexing MCP is unavailable/empty"
+3. **Fall back explicitly** to `Grep` with a note
+4. **Never** start crawling directories with `find`, `ls -R`, or `tree` as a hidden workaround
+
+## Secondary Tools
+
+### Grep
+
+Best for exact text matches, regex patterns, filtering by file type.
+
+```
+Use when:
+- You know the exact string or pattern
+- You need regex matching
+- You want to scope to specific files (glob filter)
+```
+
+### Glob
+
+Best for finding files by name or path pattern.
+
+```
+Use when:
+- You know the filename but not the location
+- You need all files matching a glob (e.g., **/*.test.ts)
+- You're looking for configuration files
+```
+
+## Exploration Efficiency
+
+- **Batch when possible**: Multiple `Grep` calls with regex alternation (`pattern1|pattern2`) instead of sequential single-pattern searches
+- **Read targeted ranges**: Use `Read` with a specific `offset`/`limit`, not the entire file
+- **Use subagents for deep exploration**: For complex multi-step searches, delegate to a specialist subagent (from the Team Roster) via the `Agent` tool instead of manually chaining 10+ search calls. Specialist agents own their own discovery — never invoke a subagent that bypasses the roster.