@mthanh/vespercli 1.7.1 → 2.0.0

package/assets/copilot/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/copilot/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 `isBackground: 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/copilot/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 `isBackground: true`)
+- Moving/renaming files (`mv`)
+- Operations that have no built-in tool equivalent

package/assets/copilot/skills/create-specification/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: create-specification
+description: Create a new specification file optimized for Generative AI consumption. Use when asked to write, author, or draft a specification, spec, or requirements document for a solution component, feature, or system. Produces a clear, unambiguous, machine-readable Markdown spec covering purpose, definitions, requirements/constraints/guidelines, interfaces and data contracts, acceptance criteria, test-automation strategy, rationale, dependencies, examples/edge cases, and validation criteria — saved under `.vesper/.tracking/specs/`.
+---
+
+# Create Specification
+
+Author a specification file that defines the requirements, constraints, and interfaces for a solution component in a way that is clear, unambiguous, and structured for effective use by Generative AIs. Follow established documentation standards and keep the content machine-readable and self-contained.
+
+## When to Use
+
+Invoke this skill when the user asks to create, write, draft, or author a specification (spec) for a purpose they provide — a feature, a component, an integration, a process, or a system.
+
+## Best Practices for AI-Ready Specifications
+
+- Use precise, explicit, and unambiguous language.
+- Clearly distinguish between requirements, constraints, and recommendations.
+- Use structured formatting (headings, lists, tables) for easy parsing.
+- Avoid idioms, metaphors, or context-dependent references.
+- Define all acronyms and domain-specific terms.
+- Include examples and edge cases where applicable.
+- Ensure the document is self-contained and does not rely on external context.
+
+## Output Location and Naming
+
+Save the specification in the `.vesper/.tracking/specs/` directory, named by the convention `YYYYMMDD-task-description-specification.md`. Write well-formed Markdown.
+
+## Required Structure
+
+Every specification must fill out all sections of the following template. Structure the front matter exactly as shown.
+
+````md
+---
+title: [Concise Title Describing the Specification's Focus]
+version: [Optional: e.g., 1.0, Date]
+date_created: [YYYY-MM-DD]
+last_updated: [Optional: YYYY-MM-DD]
+owner: [Optional: Team/Individual responsible for this spec]
+tags: [Optional: List of relevant tags or categories, e.g., `infrastructure`, `process`, `design`, `app` etc]
+---
+
+# Introduction
+
+[A short concise introduction to the specification and the goal it is intended to achieve.]
+
+## 1. Purpose & Scope
+
+[Provide a clear, concise description of the specification's purpose and the scope of its application. State the intended audience and any assumptions.]
+
+## 2. Definitions
+
+[List and define all acronyms, abbreviations, and domain-specific terms used in this specification.]
+
+## 3. Requirements, Constraints & Guidelines
+
+[Explicitly list all requirements, constraints, rules, and guidelines. Use bullet points or tables for clarity.]
+
+- **REQ-001**: Requirement 1
+- **SEC-001**: Security Requirement 1
+- **[3 LETTERS]-001**: Other Requirement 1
+- **CON-001**: Constraint 1
+- **GUD-001**: Guideline 1
+- **PAT-001**: Pattern to follow 1
+
+## 4. Interfaces & Data Contracts
+
+[Describe the interfaces, APIs, data contracts, or integration points. Use tables or code blocks for schemas and examples.]
+
+## 5. Acceptance Criteria
+
+[Define clear, testable acceptance criteria for each requirement using Given-When-Then format where appropriate.]
+
+- **AC-001**: Given [context], When [action], Then [expected outcome]
+- **AC-002**: The system shall [specific behavior] when [condition]
+- **AC-003**: [Additional acceptance criteria as needed]
+
+## 6. Test Automation Strategy
+
+[Define the testing approach, frameworks, and automation requirements.]
+
+- **Test Levels**: Unit, Integration, End-to-End
+- **Frameworks**: [test frameworks appropriate to the stack]
+- **Test Data Management**: [approach for test data creation and cleanup]
+- **CI/CD Integration**: [automated testing in the project's CI pipeline]
+- **Coverage Requirements**: [minimum code coverage thresholds]
+- **Performance Testing**: [approach for load and performance testing]
+
+## 7. Rationale & Context
+
+[Explain the reasoning behind the requirements, constraints, and guidelines. Provide context for design decisions.]
+
+## 8. Dependencies & External Integrations
+
+[Define the external systems, services, and architectural dependencies required for this specification. Focus on **what** is needed rather than **how** it's implemented. Avoid specific package or library versions unless they represent architectural constraints.]
+
+### External Systems
+
+- **EXT-001**: [External system name] - [Purpose and integration type]
+
+### Third-Party Services
+
+- **SVC-001**: [Service name] - [Required capabilities and SLA requirements]
+
+### Infrastructure Dependencies
+
+- **INF-001**: [Infrastructure component] - [Requirements and constraints]
+
+### Data Dependencies
+
+- **DAT-001**: [External data source] - [Format, frequency, and access requirements]
+
+### Technology Platform Dependencies
+
+- **PLT-001**: [Platform/runtime requirement] - [Version constraints and rationale]
+
+### Compliance Dependencies
+
+- **COM-001**: [Regulatory or compliance requirement] - [Impact on implementation]
+
+**Note**: This section should focus on architectural and business dependencies, not specific package implementations. For example, specify "OAuth 2.0 authentication library" rather than a specific vendor package and version.
+
+## 9. Examples & Edge Cases
+
+    ```code
+    // Code snippet or data example demonstrating the correct application of the guidelines, including edge cases
+    ```
+
+## 10. Validation Criteria
+
+[List the criteria or tests that must be satisfied for compliance with this specification.]
+
+## 11. Related Specifications / Further Reading
+
+[Link to related spec 1]
+[Link to relevant external documentation]
+````

package/assets/copilot/skills/document/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: document
+description: 'Diátaxis-framework technical writing — tutorials, how-to guides, reference and explanation documents that are clear, accurate and user-centred. Use when writing or restructuring README files, API docs, guides or any software documentation.'
+---
+
+# Diátaxis Documentation Expert
+
+You are an expert technical writer specializing in creating high-quality software documentation.
+Your work is strictly guided by the principles and structure of the Diátaxis Framework (https://diataxis.fr/).
+
+## GUIDING PRINCIPLES
+
+1. **Clarity:** Write in simple, clear, and unambiguous language.
+2. **Accuracy:** Ensure all information, especially code snippets and technical details, is correct and up-to-date.
+3. **User-Centricity:** Always prioritize the user's goal. Every document must help a specific user achieve a specific task.
+4. **Consistency:** Maintain a consistent tone, terminology, and style across all documentation.
+
+## YOUR TASK: The Four Document Types
+
+You will create documentation across the four Diátaxis quadrants. You must understand the distinct purpose of each:
+
+- **Tutorials:** Learning-oriented, practical steps to guide a newcomer to a successful outcome. A lesson.
+- **How-to Guides:** Problem-oriented, steps to solve a specific problem. A recipe.
+- **Reference:** Information-oriented, technical descriptions of machinery. A dictionary.
+- **Explanation:** Understanding-oriented, clarifying a particular topic. A discussion.
+
+## WORKFLOW
+
+You will follow this process for every documentation request:
+
+1. **Acknowledge & Clarify:** Acknowledge my request and ask clarifying questions to fill any gaps in the information I provide. You MUST determine the following before proceeding:
+    - **Document Type:** (Tutorial, How-to, Reference, or Explanation)
+    - **Target Audience:** (e.g., novice developers, experienced sysadmins, non-technical users)
+    - **User's Goal:** What does the user want to achieve by reading this document?
+    - **Scope:** What specific topics should be included and, importantly, excluded?
+
+2. **Propose a Structure:** Based on the clarified information, propose a detailed outline (e.g., a table of contents with brief descriptions) for the document. Await my approval before writing the full content.
+
+3. **Generate Content:** Once I approve the outline, write the full documentation in well-formatted Markdown. Adhere to all guiding principles.
+
+## CONTEXTUAL AWARENESS
+
+- When I provide other markdown files, use them as context to understand the project's existing tone, style, and terminology.
+- DO NOT copy content from them unless I explicitly ask you to.
+- You may not consult external websites or other sources unless I provide a link and instruct you to do so.

package/assets/copilot/skills/mcp-memory/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: mcp-memory
+description: Persistent knowledge graph memory using @modelcontextprotocol/server-memory MCP server. Structured entities, relations, and observations for cross-session context. Use at session start to recall learnings, after implementation to capture corrections, after user corrections to store preferences, and when searching for prior research or planning insights. Covers entity design (learning, preference, workspace_pattern, agent_insight), per-agent memory protocols, and memory hygiene rules. Memory holds project knowledge, never pipeline state — the run ledger (`vespercli log`) and the story folders own that.
+---
+
+# MCP Memory
+
+Persistent knowledge graph memory for Vesper subagents via `@modelcontextprotocol/server-memory` MCP tools (`mcp__memory__*`). This server is configured in this project's `.vscode/mcp.json`.
+
+## Overview
+
+The memory system stores learnings, preferences, patterns, and task context as **entities** in a knowledge graph. Each entity has a name, type, and atomic observations. Entities connect via directed **relations**. Data persists in `.vesper/memory.jsonl` across sessions.
+
+## When to Use
+
+- **Session start** — Recall relevant learnings for the task's domain (pipeline state comes from `vespercli story list` + `vespercli log tail`, never from memory)
+- **Before delegating** — Check memory for learnings about the target domain
+- **After user corrections** — Store the correction as a `learning` entity
+- **After implementation** — Capture patterns, mistakes, and insights
+- **Before research/planning** — Search for prior findings on similar topics
+
+## Available MCP Tools
+
+| Tool                            | Purpose                                       |
+| :-------------------------------- | :-------------------------------------------- |
+| `mcp__memory__create_entities`     | Create new entities with observations         |
+| `mcp__memory__create_relations`    | Link entities with directed relations         |
+| `mcp__memory__add_observations`    | Append facts to existing entities             |
+| `mcp__memory__delete_entities`     | Remove obsolete entities (cascades relations) |
+| `mcp__memory__delete_observations` | Remove outdated observations                  |
+| `mcp__memory__delete_relations`    | Remove specific relations                     |
+| `mcp__memory__read_graph`          | Read entire knowledge graph                   |
+| `mcp__memory__search_nodes`        | Search names, types, and observations         |
+| `mcp__memory__open_nodes`          | Retrieve specific nodes by name               |
+
+## Entity Types
+
+Four entity types power the Vesper memory system. See [entity-schema](references/entity-schema.md) for naming conventions, observation patterns, and examples.
+
+| Type                | Created By                                  |
+| :------------------- | :--------------------------------------------- |
+| `learning`          | Feature Wrap                                   |
+| `preference`        | Any subagent                                   |
+| `workspace_pattern` | Feature Wrap                                   |
+| `agent_insight`     | Orchestrator, Feature Wrap                     |
+
+There is no task-state entity. Cross-agent handoffs travel through the tracking files
+(`.vesper/.tracking/{research,plans,details,prompts,changes}/`) and the run ledger
+(`.vesper/.tracking/runs/`, written only by `vespercli log`); memory stays a knowledge graph.
+
+## Per-Agent Memory Protocol
+
+Each role has specific memory read/write responsibilities. See [agent-memory-protocol](references/agent-memory-protocol.md) for detailed per-agent instructions.
+
+**Quick reference:**
+
+- **Orchestrator (root `CLAUDE.md`)**: Read on session start; check before delegating; never write directly
+- **Feature Wrap**: Primary writer — creates `learning`, `workspace_pattern`, `agent_insight` entities
+- **Task Researcher**: Read before research; write `learning` if prior research exists on topic
+- **Code Planner**: Read before planning; search for planning-related learnings
+- **Run ledger** (`vespercli log`, CLI-written): no memory interaction — chronology lives in `.vesper/.tracking/runs/`, knowledge lives here
+
+## Memory Criteria
+
+**STORE in memory**:
+
+1. User corrected an agent's decision
+2. Unexpected behavior required a different approach
+3. Workspace-specific pattern discovered
+4. Agent selection was wrong
+5. File path or naming convention was incorrect
+
+**DO NOT store**:
+
+- Task-specific implementation details
+- Code patterns (belong in skills)
+- General best practices
+- Temporary workarounds
+- Content already in `.vesper/instructions/vesper-context.instructions.md`
+
+## Handoff Protocol
+
+When a subagent finishes work and another subagent will continue, the handoff is the **file it
+wrote** (research → plan → details/prompts → changes), named by path in the next delegation
+prompt, plus the orchestrator's `vespercli log note`/`returned` row. Memory carries no task state:
+the next subagent runs `mcp__memory__search_nodes("<task domain>")` for relevant `learning` /
+`workspace_pattern` entities and reads the handoff file for everything else.
+
+## Memory Hygiene
+
+Atomic observations, snake_case names, active-voice relations, and regular cleanup. See [memory-hygiene](references/memory-hygiene.md) for lifecycle rules, deduplication, and cleanup triggers.
+
+## References
+
+- [Entity Schema](references/entity-schema.md) — Types, naming, observations, examples
+- [Agent Memory Protocol](references/agent-memory-protocol.md) — Per-agent read/write rules
+- [Memory Hygiene](references/memory-hygiene.md) — Cleanup, deduplication, lifecycle