@mthanh/vespercli 2.1.0 → 2.2.1

package/README.md

@@ -88,7 +88,7 @@ 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:
 
@@ -357,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)
@@ -396,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.
 
@@ -406,6 +408,24 @@ 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) — the enable runs this for you when the tool is installed
+```
+
+When `graphify` is on PATH and `graphify-out/graph.json` does not exist yet, `packs enable graphify` (and `init`'s consent, `-y`/`--graphify` runs included — it is local, 0 tokens, no prompt) builds the graph right away with `graphify update .`; a failed build warns and leaves the pack enabled, and a re-init, `packs sync` or `worktree bootstrap` never rebuilds.
+
+**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.
@@ -421,7 +441,7 @@ 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 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). |

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.1.0",
+      "version": "2.2.1",
       "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.1.0",
-      "description": "Vesper frontend pack — React, Next.js, Tailwind and Jest/RTL specialists and skills."
+      "version": "2.2.1",
+      "description": "Vesper frontend pack \u2014 React, Next.js, Tailwind and Jest/RTL specialists and skills."
     },
     {
       "name": "vesper-playwright",
       "source": "./packs/playwright",
-      "version": "2.1.0",
-      "description": "Vesper playwright pack — Playwright end-to-end testing specialists and skills."
+      "version": "2.2.1",
+      "description": "Vesper playwright pack \u2014 Playwright end-to-end testing specialists and skills."
     },
     {
       "name": "vesper-backend",
       "source": "./packs/backend",
-      "version": "2.1.0",
-      "description": "Vesper backend pack — Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills."
+      "version": "2.2.1",
+      "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.1.0",
-      "description": "Vesper polyglot pack — Java, Flutter and Google ADK (Python) skills."
+      "version": "2.2.1",
+      "description": "Vesper polyglot pack \u2014 Java, Flutter and Google ADK (Python) skills."
     },
     {
       "name": "vesper-docs",
       "source": "./packs/docs",
-      "version": "2.1.0",
-      "description": "Vesper docs pack — Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills."
+      "version": "2.2.1",
+      "description": "Vesper docs pack \u2014 Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills."
     },
     {
       "name": "vesper-integrations",
       "source": "./packs/integrations",
-      "version": "2.1.0",
-      "description": "Vesper integrations pack — ClickUp task-board specialist, the GitLab MR guardrails skill, and the third-party GitLab CI skills (gitlab-ci-skill, github-actions-to-gitlab-ci)."
+      "version": "2.2.1",
+      "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.1.0",
-      "description": "Vesper styles pack — opt-in output styles: i-have-adhd, ponytail (third-party, MIT). Enabled by `vespercli packs enable styles`, which writes the always-on pointer rule that applies them."
+      "version": "2.2.1",
+      "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.1",
+      "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.1.0",
+  "version": "2.2.1",
   "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.1.0",
+  "version": "2.2.1",
   "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.1.0",
+  "version": "2.2.1",
   "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.1.0",
+  "version": "2.2.1",
   "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.1",
+  "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.

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