@mthanh/vespercli 2.1.0 → 2.2.1

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.1.0",
+  "version": "2.2.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; 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.1.0",
+  "version": "2.2.1",
   "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.1.0",
+  "version": "2.2.1",
   "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.1.0",
+  "version": "2.2.1",
   "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

@@ -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/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",