@mthanh/vespercli 1.8.0 → 2.0.0

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

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

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

@@ -0,0 +1,10 @@
+{
+  "name": "vesper-docs",
+  "displayName": "Vesper docs pack",
+  "version": "2.0.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"
+  },
+  "license": "MIT"
+}

package/assets/claude/packs/docs/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/docs/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/docs/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/docs/skills/agent-fundamentals/references/tool-usage-patterns.md

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

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

@@ -0,0 +1,10 @@
+{
+  "name": "vesper-frontend",
+  "displayName": "Vesper frontend pack",
+  "version": "2.0.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"
+  },
+  "license": "MIT"
+}

package/assets/claude/packs/frontend/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/frontend/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.