@mthanh/vespercli 1.8.0 → 2.0.1

package/assets/core/instructions/vesper-research-plan.instructions.md

@@ -1,193 +0,0 @@
----
-description: Vesper orchestration for research and planning phase steps 1-3 — task fetch, research, planning
----
-
-# Vesper Purpose: Implementation — Research & Plan Phase
-
-This instruction file contains the detailed orchestration steps for the Research & Plan phase of the Implementation purpose pipeline (Steps 1-3).
-
-## Prerequisites
-
-- ✅ Refined task or user request exists
-- Team Roster available in `.github/instructions/orchestration.instructions.md` (Vesper handles routing)
-
-## Context Injection (Vesper Responsibility)
-
-When calling subagents, Vesper appends workspace context:
-
-```
-[WORKSPACE CONTEXT - appended by Vesper]
-- Codebase context: Use vesper-indexing MCP tools (vesper_search, vesper_symbols)
-```
-
-**Codebase Reference Rule**: When building delegation prompts, always frame codebase references as **concepts to investigate** ("Investigate lease type definitions and validation patterns"), never as file-reading commands ("Read src/types/leaseTypes.ts"). File paths from stories may appear as hints, but the subagent decides how to query the codebase — via vesper-indexing, not prescribed reads.
-
-## Orchestration Steps
-
-### File Naming Convention
-
-All output files use the pattern `YYYYMMDD-[slug]-<type>.md` where `[slug]` is a short task identifier (3-5 words, kebab-case). When Vesper delegates with a `Task slug: [slug]` directive, use that exact slug. This isolates artifacts when multiple tasks run in parallel.
-
-### STEP 0: Fetch Task Details (if task reference exists)
-
-- Look up **Task Agent** from Team Roster (`task_system_*` capability)
-- Delegate to Task Agent:
-
-```
-"Fetch full task details for [task-id].
-Return: description, requirements, acceptance criteria."
-```
-
-### STEP 1: Comprehensive Research
-
-Delegate to **Researcher/Analyzer from roster** → fallback `@Task Researcher Specialist Agent`:
-
-```
-"Research implementation approach for [task].
-
-Task slug: [slug]
-Context: [task details from STEP 0]
-
-Memory: Before starting, search_nodes('<task keywords>') for prior research learnings.
-
-Save to: .vesper/.tracking/research/YYYYMMDD-[slug]-research.md
-
-Note: Task Researcher will:
-- Execute comprehensive research using all available tools
-- Evaluate alternatives and guide toward ONE recommended approach
-- Validate research completeness before signaling done
-- Remove non-selected alternatives from final document
-- Update current_task entity via add_observations when research is complete
-
-Relevant Skills: docs-seeker, sequential-thinking"
-```
-
-- Vesper appends [WORKSPACE CONTEXT] to prompt
-
-**WAIT** for researcher to complete (VESPER_RESPONSE: DONE).
-
-### STEP 2: Create Implementation Plan
-
-Delegate to **Planner from roster** → fallback `@Code Planner Agent`:
-
-```
-"Create implementation plan based on research.
-
-Task slug: [slug]
-Research: .vesper/.tracking/research/YYYYMMDD-[slug]-research.md
-Output directory: .vesper/.tracking/
-
-Memory: open_nodes(['current_task']) for research context. search_nodes('planning') for planning-related learnings.
-
-Note: Code Planner will create THREE files:
-- plans/YYYYMMDD-[slug]-plan.instructions.md (phases, tasks, dependencies)
-- details/YYYYMMDD-[slug]-details.md (full specifications per task)
-- prompts/implement-[slug].prompt.md (implementation prompt with controls)
-
-Code Planner validates research exists before planning.
-
-Relevant Skills: sequential-thinking, web-frameworks (if applicable)"
-```
-
-**WAIT** for planner to complete (VESPER_RESPONSE: DONE).
-
-### STEP 3: Architect Validation (REQUIRED)
-
-Delegate to `@SE: Architect`:
-
-```
-"Validate this implementation plan for [task].
-
-Review:
-- Research: .vesper/.tracking/research/YYYYMMDD-[slug]-research.md
-- Plan: .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.instructions.md
-- Details: .vesper/.tracking/details/YYYYMMDD-[slug]-details.md
-
-Check: feasibility, risks, alignment with architecture, completeness.
-Approve or request specific changes."
-```
-
-**IF Architect requests changes:**
-
-1. Delegate to **Planner** to revise plan
-2. Re-validate with Architect
-3. Repeat until approved (subject to the global loop limit in `vesper.agent.md`)
-
-## Output Files
-
-All outputs in `.vesper/.tracking/`:
-
-- `research/YYYYMMDD-[slug]-research.md` (from Researcher)
-- `plans/YYYYMMDD-[slug]-plan.instructions.md` (from Planner, Architect approved)
-- `details/YYYYMMDD-[slug]-details.md` (from Planner)
-- `prompts/implement-[slug]-[track].prompt.md` (from Planner — one per independent track)
-
-When only one task with one track: `implement-[slug].prompt.md` (simplified).
-
-### Implementation Tracks (Planner Responsibility)
-
-The Planner MUST identify independent implementation tracks and create:
-
-- **One prompt per track** in `prompts/` (e.g., `implement-backend-api.prompt.md`, `implement-frontend-ui.prompt.md`, `implement-db-migration.prompt.md`)
-- Each prompt specifies: target surface/stack, tasks for that track, and any dependencies on other tracks
-- The plan file lists all tracks with their dependency graph
-
-If all tasks are on the same surface → single prompt `implement-task.prompt.md` (unchanged from current behavior).
-
----
-
-## Bug Fix Overrides (when Purpose = bug fix)
-
-Bug fixes enter the same pipeline. These overrides adjust context passing for bug-specific framing.
-
-### STEP 1 Research — add to delegate prompt:
-
-```
-"Investigate bug: [description].
-
-Context:
-- Error logs / stack traces: [file path if available]
-- Reproduction steps: [user-provided or inferred]
-- Affected area: [file paths or module if known]
-
-Find root cause. Provide:
-- What is failing
-- Why it is failing
-- Where in the code the issue originates
-- Recommended fix approach
-
-Save to: .vesper/.tracking/research/YYYYMMDD-bugfix-research.md"
-```
-
-### STEP 2 Plan — add scope constraint:
-
-```
-"Requirements:
-- Minimal fix that addresses root cause (not symptoms)
-- Regression test must be part of the plan
-- Do NOT scope beyond what's needed for this fix"
-```
-
-**Output naming**: Use `bugfix` prefix (e.g., `YYYYMMDD-bugfix-research.md`, `YYYYMMDD-bugfix-changes.md`).
-
----
-
-## Skills Creation Overrides (when task = skill creation)
-
-Skills creation enters the same Implementation pipeline. The Skill Creator is the "Developer" for this task type.
-
-### STEP 1 Research — frame as skills research:
-
-```
-"Research what this skill should cover: [topic/technology].
-
-Context:
-- Existing skills: Check skills/ and .github/skills/ directories
-
-Find:
-- What patterns exist in the codebase for this domain
-- What knowledge gaps exist that a skill could fill
-- Existing similar skills to avoid duplication
-
-Save to: .vesper/.tracking/research/YYYYMMDD-skill-research.md"
-```

package/assets/core/instructions/vscode-mcp-tools.instructions.md

@@ -1,138 +0,0 @@
----
-description: VS Code MCP tool auto-approval patterns and dynamic schema handling
-applyTo: '**/settings.js, **/mcp.json'
----
-
-# VS Code MCP Tools Integration
-
-Guidelines for integrating MCP tools with VS Code settings.
-
-## Tool Name Format
-
-Use **tool names only** — not `server_tool` format:
-
-```javascript
-// ✅ Correct
-'vesper_search';
-'clickup_get_task';
-
-// ❌ Wrong
-'vesper-indexing_vesper_search';
-'clickup_clickup_get_task';
-```
-
-## Dynamic Schema Validation
-
-VS Code validates `chat.tools.eligibleForAutoApproval` against a **dynamic schema**:
-
-- Tools from discovered MCP servers are valid
-- Tools from undiscovered MCP servers show "Value is not accepted" warnings
-- Warnings disappear once the MCP server is started and tools are registered
-
-**Implication**: Settings files may show warnings until MCP servers are discovered. This is expected behavior.
-
-## Adding Agent-Specific Tools
-
-When an agent requires MCP tools, follow this pattern:
-
-### 1. Define Tools in Settings
-
-```javascript
-// src/cli/utils/settings.js
-export const MCP_TOOLS_BY_AGENT = {
-	'agent-name': [
-		'tool_name_1',
-		'tool_name_2',
-		// ...
-	],
-};
-```
-
-### 2. Auto-Add on Agent Addition
-
-The `add.js` command automatically calls `addAgentToolsToAutoApproval()` when:
-
-- Asset type is `agents`
-- Agent name exists in `MCP_TOOLS_BY_AGENT`
-
-### 3. User Experience
-
-```bash
-$ vesper add agents clickup-agent
-
-✓ Added 1 asset(s):
-  agents/clickup-agent
-  + 32 MCP tools auto-approved for clickup-agent
-
-Reload VS Code to apply changes
-```
-
-## Deprecated Settings
-
-| Setting                      | Status     | Alternative                   |
-| ---------------------------- | ---------- | ----------------------------- |
-| `chat.mcp.discovery.enabled` | Deprecated | VS Code handles automatically |
-| `chat.mcp.autoStart`         | Deprecated | VS Code handles automatically |
-
-## Core vs Agent Tools
-
-| Category                | When Added                 | Tools                                                            |
-| ----------------------- | -------------------------- | ---------------------------------------------------------------- |
-| Core (`MCP_TOOLS_CORE`) | `vesper init`              | vesper\_\*, sequentialthinking, memory tools (create_entities..) |
-| Agent-specific          | `vesper add agents <name>` | Defined in `MCP_TOOLS_BY_AGENT`                                  |
-
-## Adding Core MCP Servers
-
-Follow this pattern to add a default MCP server:
-
-### 1. Register Tools for Auto-Approval
-
-Add tool names to `MCP_TOOLS_CORE` in `src/cli/utils/settings.js`:
-
-```javascript
-// src/cli/utils/settings.js
-export const MCP_TOOLS_CORE = ['server-tool-1', 'server-tool-2'];
-```
-
-### 2. Define Server Configuration
-
-Add the server configuration to `MCP_SERVERS` in `src/cli/utils/settings.js`:
-
-```javascript
-// src/cli/utils/settings.js
-export const MCP_SERVERS = {
-	'server-name': {
-		command: 'npx',
-		args: ['-y', '@modelcontextprotocol/server-name'],
-		disabled: false, // Optional default state
-	},
-};
-```
-
-### 3. Update Configuration Logic
-
-Update `configureMcpServer()` in `src/cli/utils/settings.js` to handle the new server:
-
-```javascript
-// src/cli/utils/settings.js
-// inside configureMcpServer()
-if (MCP_SERVERS['server-name'] && !MCP_SERVERS['server-name'].disabled) {
-  config.mcpServers['server-name'] = {
-    command: MCP_SERVERS['server-name'].command,
-    args: MCP_SERVERS['server-name'].args,
-    env: { ...process.env, ... }
-  };
-  configuredServers.push('server-name');
-}
-```
-
-### 4. Update Success Message
-
-Update `displaySuccessMessage()` in `src/cli/commands/init.js` to confirm server setup:
-
-```javascript
-// src/cli/commands/init.js
-logger.success(`+ Core MCP Servers configured: [server-name, ...]`);
-```
-
-3.  **Update CLI Prompts** (`src/cli/commands/init.js`) to mention the new server in success messages.

package/assets/core/prompts/compact-knowledge.prompt.md

@@ -1,14 +0,0 @@
----
-description: 'Compact persisted Vesper knowledge (history.md, memory graph, completed tracking stories) so a fresh session does not have to ingest all of it'
----
-
-# Compact Knowledge
-
-Compact persisted Vesper knowledge — distinct from Claude Code's `/compact` or any context-window summarization; this compacts what's **on disk / in the memory graph**, not the current conversation.
-
-Delegate:
-
-1. `@History Logger` in Compaction Mode: rotate `.vesper/history.md` (archive entries older than the last 30 into `.vesper/history-archive/YYYYMM.md`), archive **every** `.vesper/.tracking/stories/completed/` entry unconditionally, and archive each completed story's correlated `research/plans/details/prompts/changes` tracking artifacts into `.vesper/.tracking/archive/YYYYMM/<slug>/` (idempotent move; flag any slug with no recorded feature-wrap as `.unwrapped` so `/revalidate-knowledge` re-extracts it).
-2. `@Feature Wrap and Retrospective Agent` in Memory Compaction Mode: merge/dedupe stale entities in the MCP memory graph, never touching `current_task` or active entities.
-
-Report what was archived/merged from both. Nothing is deleted — only moved to archive files or consolidated within the memory graph.

package/assets/core/prompts/memory-update.prompt.md

@@ -1,94 +0,0 @@
----
-description: 'Review completed task and update MCP Memory knowledge graph with learnings'
----
-
-# Memory Update (MCP Knowledge Graph)
-
-Review the recently completed task and capture learnings in the MCP Memory knowledge graph.
-
-**Full protocol**: See `#skill:mcp-memory` for entity schema, naming conventions, and hygiene rules.
-
-## Context
-
-- Changes file: `.vesper/.tracking/changes/YYYYMMDD-*-changes.md` (most recent)
-- Issues file: `.vesper/.tracking/issues/YYYYMMDD-*-issues.md` (if exists)
-
-## Review Criteria
-
-Only add to memory if:
-
-1. **User corrected Vesper's decision** during this task
-2. **Unexpected behavior** required a different approach than planned
-3. **Workspace-specific pattern** discovered that affects future work
-4. **Agent selection** was wrong and had to be changed
-5. **File path or naming** convention was incorrect
-
-## DO NOT add
-
-- Task-specific implementation details
-- Code patterns (those belong in skills)
-- General best practices already known
-- Temporary workarounds
-- Content already in `copilot-instructions.md`
-- Project descriptions, tech stack lists, file structures, or general best practices
-
-## Capture Process
-
-### 1. Search Before Creating
-
-Before creating any entity, run `search_nodes` with relevant keywords to check for duplicates.
-
-- **Exact match** → skip creation
-- **Partial match** (same topic, new insight) → `add_observations` to existing entity
-- **Contradiction** → create new entity with `supersedes` relation to old one
-- **Genuinely new** → create new entity
-
-### 2. Create Learning Entities
-
-For each correction/insight meeting the criteria above, create one entity:
-
-```
-create_entities([{
-  "name": "learning_<category>_<brief_slug>",
-  "entityType": "learning",
-  "observations": [
-    "trigger: <what happened or went wrong>",
-    "correction: <the correct approach>",
-    "apply_when: <conditions for applying this learning>",
-    "category: <Flow|Delegation|Agent Selection|File Paths|Prompts|User Preference>",
-    "discovered: <YYYY-MM-DD>"
-  ]
-}])
-```
-
-### 3. Create Supporting Entities (if applicable)
-
-- **Workspace pattern discovered** → create `workspace_pattern` entity
-- **Agent selection lesson** → create `agent_insight` entity
-- **User preference expressed** → create `preference` entity
-
-### 4. Link Related Entities
-
-```
-create_relations([{
-  "from": "learning_x",
-  "to": "learning_y",
-  "relationType": "relates_to"
-}])
-```
-
-### 5. Clean Up Task Context
-
-If the task is fully complete:
-
-```
-delete_entities(["current_task"])
-```
-
-## Categories
-
-`Flow`, `Delegation`, `Agent Selection`, `File Paths`, `Prompts`, `User Preference`
-
-## If no learnings
-
-Reply: "No memory updates needed."

package/assets/core/prompts/revalidate-knowledge.prompt.md

@@ -1,19 +0,0 @@
----
-description: 'Revalidate archived Vesper knowledge against the current codebase and re-balance the slim-core/on-demand context split — a heavier, semantic re-validation pass distinct from /compact-knowledge trim/dedupe.'
----
-
-# Revalidate Knowledge
-
-Re-establish the truth of the project whitepaper. Unlike `#compact-knowledge` (which is triggered on *size* and only trims/dedupes/archives non-destructively), this flow is triggered on *staleness/drift* and performs a genuine **semantic re-validation** of previously captured knowledge against the code as it actually is today. This is **user-invoked** — Vesper only ever *suggests* it (on staleness signals), never auto-runs it.
-
-Delegate in parallel:
-
-1. `@Workspace Learner` (inherits its mandatory reindex-first workflow):
-   - **Review all archived content** — `.vesper/history-archive/` and `.vesper/.tracking/archive/` (the only sanctioned reason to read these otherwise off-limits directories). Revalidate the durable knowledge they captured against the current code and decisions; correct or drop anything the code no longer supports. **Prioritize `.unwrapped`-flagged archives** (`/compact-knowledge` tags archived slugs that never got a feature-wrap) for knowledge re-extraction first.
-   - **Re-balance the context split** — re-derive the slim core (`.claude/vesper/context.md`: Big Picture Architecture + Domain Model + Critical Workflows + Freshness header only, ≤200 lines) and the on-demand tier (`.claude/vesper/context/{conventions,integrations,technical-debt,recent-decisions}.md`), extracting any core overflow back into the on-demand files.
-   - **Re-validate Technical Debt** — drop bullets the current code has resolved; keep/append only what still holds.
-   - On completion, set the `Last revalidation` stamp in the core Freshness header to today's date (per the freshness parse contract).
-
-2. `@Feature Wrap and Retrospective Agent` (memory-graph side): merge/dedupe and re-validate stale entities in the MCP memory graph against the revalidated whitepaper, never touching `current_task` or active entities.
-
-Report what was revalidated, corrected, dropped, re-extracted (especially from `.unwrapped` archives), and re-balanced. Nothing is deleted — outdated knowledge is corrected in place or consolidated; source archives remain on disk.

package/assets/core/skills/agent-fundamentals/SKILL.md

@@ -1,75 +0,0 @@
----
-name: agent-fundamentals
-description: Universal operating rules for all Vesper ecosystem agents — codebase query protocol, terminal discipline, tool usage patterns, and response standards. Use when any agent needs to search code, run terminal commands, perform file operations, or produce output. This is the baseline skill every Vesper agent should follow.
----
-
-# Vesper Agent Fundamentals
-
-Universal operating rules for every agent 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                                               |
-| ---------------- | ----------------------------------------------------- |
-| `vesper_search`  | Full-text code search → returns snippets + file paths |
-| `vesper_symbols` | Find functions, classes, exports by name + location   |
-| `vesper_status`  | Check index health before querying                    |
-| `vesper_reindex` | Rebuild index if stale or empty                       |
-
-- Results include actual source code — skip `read_file` 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_search`, `semantic_search`, `file_search` 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 `isBackground: 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 terminal 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 terminal equivalents:**
-
-| Task          | ✅ Correct Tool                | ❌ Never Do This                             |
-| ------------- | ------------------------------ | -------------------------------------------- |
-| Read a file   | `read_file`                    | `cat`, `less`, `node -e "fs.readFileSync()"` |
-| Search code   | `grep_search`, `vesper_search` | `grep -r`, `find . -exec grep`               |
-| Find files    | `file_search`                  | `find .`, `ls -R`, `tree`                    |
-| Create a file | `create_file`                  | `echo > file`, `python -c "open().write()"`  |
-| Edit a file   | `replace_string_in_file`       | `sed -i`, `node -e "fs.writeFileSync()"`     |
-| Check errors  | `get_errors`                   | 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 create (`create_file`) or edit (`replace_string_in_file`) — 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.    |
-| 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.
-
-## 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/core/skills/agent-fundamentals/references/codebase-query.md

@@ -1,106 +0,0 @@
-# Codebase Query Protocol
-
-How Vesper agents should explore and understand any codebase.
-
-## Priority Order
-
-```
-1. vesper-indexing MCP tools  (PRIMARY — always try first)
-2. grep_search / semantic_search  (SECONDARY — when index lacks coverage)
-3. file_search + read_file  (TERTIARY — targeted file inspection)
-4. run_in_terminal  (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_search`, `read_file`, 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
-
-### 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_file` unless you need wider context beyond the returned snippet.
-
-### 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
-```
-
-### 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
-```
-
-### 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_search` and `semantic_search` with a note
-4. **Never** start crawling directories with `find`, `ls -R`, or `tree` as a hidden workaround
-
-## Secondary Tools
-
-### grep_search
-
-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 (includePattern)
-```
-
-### semantic_search
-
-Best for natural language queries when you don't know exact terms.
-
-```
-Use when:
-- You're exploring unfamiliar code
-- You don't know the exact function/variable names
-- You want conceptual matches, not literal text
-```
-
-### file_search
-
-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_search` calls with regex alternation (`pattern1|pattern2`) instead of sequential single-pattern searches
-- **Read targeted ranges**: Use `read_file` with specific `startLine`/`endLine`, not the entire file
-- **Use subagents for deep exploration**: For complex multi-step searches, use the `search_subagent` tool instead of manually chaining 10+ search calls. Specialist agents (from the Team Roster) own their own discovery — never invoke utility agents that bypass the roster.