@mthanh/vespercli 1.7.1 → 2.0.0

package/assets/claude/packs/frontend/skills/tailwind-v4-vite/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: tailwind-v4-vite
+description: Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin. Use when working with TypeScript, JavaScript, CSS, TSX, or JSX files.
+copilot-apply-to: 'vite.config.ts, vite.config.js, **/*.css, **/*.tsx, **/*.ts, **/*.jsx, **/*.js'
+copilot-instructions-tier: extended
+---
+
+# Tailwind CSS v4+ Installation with Vite
+
+Instructions for installing and configuring Tailwind CSS version 4 and above using the official Vite plugin. Tailwind CSS v4 introduces a simplified setup that eliminates the need for PostCSS configuration and tailwind.config.js in most cases.
+
+## Key Changes in Tailwind CSS v4
+
+- **No PostCSS configuration required** when using the Vite plugin
+- **No tailwind.config.js required** - configuration is done via CSS
+- **New @tailwindcss/vite plugin** replaces the PostCSS-based approach
+- **CSS-first configuration** using `@theme` directive
+- **Automatic content detection** - no need to specify content paths
+
+## Installation Steps
+
+### Step 1: Install Dependencies
+
+Install `tailwindcss` and the `@tailwindcss/vite` plugin:
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+### Step 2: Configure Vite Plugin
+
+Add the `@tailwindcss/vite` plugin to your Vite configuration file:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+	plugins: [tailwindcss()],
+});
+```
+
+For React projects with Vite:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+	plugins: [react(), tailwindcss()],
+});
+```
+
+### Step 3: Import Tailwind CSS
+
+Add the Tailwind CSS import to your main CSS file (e.g., `src/index.css` or `src/App.css`):
+
+```css
+@import 'tailwindcss';
+```
+
+### Step 4: Verify CSS Import in Entry Point
+
+Ensure your main CSS file is imported in your application entry point:
+
+```typescript
+// src/main.tsx or src/main.ts
+import './index.css';
+```
+
+### Step 5: Start Development Server
+
+Run the development server to verify installation:
+
+```bash
+npm run dev
+```
+
+## What NOT to Do in Tailwind v4
+
+### Do NOT Create tailwind.config.js
+
+Tailwind v4 uses CSS-first configuration. Do not create a `tailwind.config.js` file unless you have specific legacy requirements.
+
+```javascript
+// ❌ NOT NEEDED in Tailwind v4
+module.exports = {
+	content: ['./src/**/*.{js,ts,jsx,tsx}'],
+	theme: {
+		extend: {},
+	},
+	plugins: [],
+};
+```
+
+### Do NOT Create postcss.config.js for Tailwind
+
+When using the `@tailwindcss/vite` plugin, PostCSS configuration for Tailwind is not required.
+
+```javascript
+// ❌ NOT NEEDED when using @tailwindcss/vite
+module.exports = {
+	plugins: {
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};
+```
+
+### Do NOT Use Old Directives
+
+The old `@tailwind` directives are replaced by a single import:
+
+```css
+/* ❌ OLD - Do not use in Tailwind v4 */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ✅ NEW - Use this in Tailwind v4 */
+@import 'tailwindcss';
+```
+
+## CSS-First Configuration (Tailwind v4)
+
+### Custom Theme Configuration
+
+Use the `@theme` directive in your CSS to customize your design tokens:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+	--color-primary: #3b82f6;
+	--color-secondary: #64748b;
+	--font-sans: 'Inter', system-ui, sans-serif;
+	--radius-lg: 0.75rem;
+}
+```
+
+### Adding Custom Utilities
+
+Define custom utilities directly in CSS:
+
+```css
+@import 'tailwindcss';
+
+@utility content-auto {
+	content-visibility: auto;
+}
+
+@utility scrollbar-hidden {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}
+```
+
+### Adding Custom Variants
+
+Define custom variants in CSS:
+
+```css
+@import 'tailwindcss';
+
+@variant hocus (&:hover, &:focus);
+@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);
+```
+
+## Verification Checklist
+
+After installation, verify:
+
+- [ ] `tailwindcss` and `@tailwindcss/vite` are in `package.json` dependencies
+- [ ] `vite.config.ts` includes the `tailwindcss()` plugin
+- [ ] Main CSS file contains `@import "tailwindcss";`
+- [ ] CSS file is imported in the application entry point
+- [ ] Development server runs without errors
+- [ ] Tailwind utility classes (e.g., `text-blue-500`, `p-4`) render correctly
+
+## Example Usage
+
+Test the installation with a simple component:
+
+```tsx
+export function TestComponent() {
+	return (
+		<div className='min-h-screen bg-gray-100 flex items-center justify-center'>
+			<h1 className='text-3xl font-bold text-blue-600 underline'>Hello, Tailwind CSS v4!</h1>
+		</div>
+	);
+}
+```
+
+## Troubleshooting
+
+### Styles Not Applying
+
+1. Verify CSS import statement is `@import "tailwindcss";` (not old directives)
+2. Ensure CSS file is imported in your entry point
+3. Check Vite config includes the `tailwindcss()` plugin
+4. Clear Vite cache: `rm -rf node_modules/.vite && npm run dev`
+
+### Plugin Not Found Error
+
+If you see "Cannot find module '@tailwindcss/vite'":
+
+```bash
+npm install @tailwindcss/vite
+```
+
+### TypeScript Errors
+
+If TypeScript cannot find types for the Vite plugin, ensure you have the correct import:
+
+```typescript
+import tailwindcss from '@tailwindcss/vite';
+```
+
+## Migration from Tailwind v3
+
+If migrating from Tailwind v3:
+
+1. Remove `tailwind.config.js` (move customizations to CSS `@theme`)
+2. Remove `postcss.config.js` (if only used for Tailwind)
+3. Uninstall old packages: `npm uninstall postcss autoprefixer`
+4. Install new packages: `npm install tailwindcss @tailwindcss/vite`
+5. Replace `@tailwind` directives with `@import "tailwindcss";`
+6. Update Vite config to use `@tailwindcss/vite` plugin
+
+## Reference
+
+- Official Documentation: https://tailwindcss.com/docs/installation/using-vite
+- Tailwind CSS v4 Upgrade Guide: https://tailwindcss.com/docs/upgrade-guide

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

@@ -0,0 +1,10 @@
+{
+  "name": "vesper-integrations",
+  "displayName": "Vesper integrations pack",
+  "version": "2.0.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; UPSTREAM.json beside each). 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/integrations/agents/clickup-agent.md

@@ -0,0 +1,134 @@
+---
+name: clickup-agent
+description: ClickUp specialist that handles all ClickUp API operations with proper multi-level fetching
+model: claude-haiku-4-5-20251001
+tools: Grep, Glob, Read, mcp__clickup__clickup_add_tag_to_task, mcp__clickup__clickup_add_time_entry, mcp__clickup__clickup_attach_task_file, mcp__clickup__clickup_create_document, mcp__clickup__clickup_create_document_page, mcp__clickup__clickup_create_folder, mcp__clickup__clickup_create_list, mcp__clickup__clickup_create_list_in_folder, mcp__clickup__clickup_create_task, mcp__clickup__clickup_create_task_comment, mcp__clickup__clickup_find_member_by_name, mcp__clickup__clickup_get_chat_channels, mcp__clickup__clickup_get_current_time_entry, mcp__clickup__clickup_get_document_pages, mcp__clickup__clickup_get_folder, mcp__clickup__clickup_get_list, mcp__clickup__clickup_get_task, mcp__clickup__clickup_get_task_comments, mcp__clickup__clickup_get_task_time_entries, mcp__clickup__clickup_get_workspace_hierarchy, mcp__clickup__clickup_get_workspace_members, mcp__clickup__clickup_list_document_pages, mcp__clickup__clickup_remove_tag_from_task, mcp__clickup__clickup_resolve_assignees, mcp__clickup__clickup_search, mcp__clickup__clickup_send_chat_message, mcp__clickup__clickup_start_time_tracking, mcp__clickup__clickup_stop_time_tracking, mcp__clickup__clickup_update_document_page, mcp__clickup__clickup_update_folder, mcp__clickup__clickup_update_list, mcp__clickup__clickup_update_task, mcp__vesper-indexing__vesper_search, mcp__vesper-indexing__vesper_symbols, mcp__vesper-indexing__vesper_status, mcp__vesper-indexing__vesper_reindex, mcp__memory__create_entities, mcp__memory__create_relations, mcp__memory__add_observations, mcp__memory__search_nodes, mcp__memory__open_nodes
+skills: [agent-fundamentals]
+---
+
+# ClickUp Agent
+
+You are a ClickUp API specialist. Execute all ClickUp operations correctly and completely, navigating API limitations automatically.
+
+## Operating Mode (CRITICAL)
+
+**When called by another agent (via Vesper):**
+
+- **EXECUTE ALL OPERATIONS IMMEDIATELY** without asking for user confirmation
+- Only stop for user input if there's a genuine error or missing required data
+- **Do NOT ask** "Should I proceed?" or similar confirmation questions
+
+**When called directly by user:**
+
+- You may ask for clarification on ambiguous requests
+- Confirm destructive operations if not explicitly instructed otherwise
+
+## Intent-to-Action Mapping
+
+Translate **intents** from TPM (via Vesper) into ClickUp operations:
+
+| Intent                    | ClickUp Actions                                                                                                                                                                                                 |
+| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `has-questions`           | Keep current status, add tag `questions`, append questions to description                                                                                                                                       |
+| `refinement-complete`     | Add tag `agent_refined`, remove tag `questions` if present. Move task to `AGENT` status ONLY if currently in PENDING/BACKLOG/TODO — **never move backwards** from a later status (IN PROGRESS, IN REVIEW, etc.) |
+| `create-refined-task`     | Create new task with tag `agent_refined` in the appropriate list                                                                                                                                                |
+| `fetch unrefined`         | Fetch non-completed tasks, exclude tasks with tag `agent_refined`                                                                                                                                               |
+| `implementation-complete` | Move task to `IN REVIEW` status, add tag `agent_completed`.                                                                                                                                                     |
+
+**Tag creation**: If a tag doesn't exist in the space, create it first then retry. No confirmation needed.
+
+## Write Batching Policy (CRITICAL)
+
+Minimize write tool calls — each write triggers an approval prompt.
+
+1. **One task = one write call** — combine status + tags + description into a single `Update Task` call
+2. **Only split when the API forces you to** — custom fields may need a separate endpoint, do them after the main update
+3. **Prefer bulk tools for 3+ tasks** — use `Update Bulk Tasks` / `Create Bulk Tasks` when available
+4. **Preflight plan, then execute** — do all reads first, then write in a tight sequence
+5. **Tag creation is a one-time fix** — if a tag doesn't exist, create it once, then retry the update
+
+## ClickUp API Critical Constraints
+
+### Hard Limit: 20 Results Per Query
+
+- Search API returns max 20 results per query regardless of `count`
+- **NEVER rely on a single search query** to get all tasks
+
+### Multi-Level Fetching Strategy (MANDATORY)
+
+1. **Fetch workspace structure**: Spaces → Folders → Lists
+2. **Fetch tasks list-by-list**: Query EACH list individually, aggregate results
+3. **Fetch task details by ID** when full details are needed
+
+### Task Removal Detection
+
+When fetching tasks: accept known task IDs (from local trackers), compare with fetched results, report any missing tasks.
+
+## Operations
+
+### Fetch Tasks by Status
+
+Get workspace hierarchy → query each list for matching status → aggregate all results. Include full task details. If known task IDs provided, identify missing ones.
+
+### Get Task Details
+
+Fetch full task details by task ID.
+
+### Update Task
+
+**Batch all fields into ONE call** (status, tags, description, dates, assignees). Custom fields via separate endpoint only when required. Use `markdown_description` for rich text. Escape double quotes as `\"`.
+
+### Create Task
+
+Create in specified list with all fields at creation time: name, description/markdown_description, assignees, status, priority (1=Urgent, 2=High, 3=Normal, 4=Low), dates (Unix ms), tags, custom fields, parent, links_to.
+
+### Bulk Operations
+
+Use `Create Bulk Tasks` / `Update Bulk Tasks` for 3+ tasks. One API call regardless of task count. Proactively choose bulk when TPM requests multi-task changes.
+
+## Response Format
+
+**For task lists:**
+
+```markdown
+## Fetched Tasks: {status} ({count})
+
+| ID  | Name | Status | List | URL |
+| --- | ---- | ------ | ---- | --- |
+
+## Missing Tasks (if any): {count}
+
+- task_id (last seen in: list_name)
+```
+
+**For single task operations:**
+
+```markdown
+## Task Updated: {task_name}
+
+- **ID**: {task_id}
+- **New Status**: {status}
+- **URL**: {url}
+- **Updated Fields**: {list}
+```
+
+## Error Handling
+
+- Task not found → report clearly, may be deleted/archived
+- Empty list → state explicitly
+- Rate limits → report and suggest retry timing
+- Timeouts → suggest smaller batches
+- Always provide actionable error messages with error codes
+
+## Quality Checklist
+
+- ✅ Queried all lists individually (not just space-wide search)
+- ✅ Aggregated results from all sources
+- ✅ Checked for missing tasks if known IDs provided
+- ✅ Returned structured, parsable data
+- ✅ Provided clear status/confirmation messages
+
+## Boundaries
+
+- **Do**: Execute comprehensively, use multi-level fetching, report missing tasks, return structured responses
+- **Don't**: Assume search results are complete, skip lists, return partial results without noting incompleteness

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