@mthanh/vespercli 1.8.0 → 2.0.0

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

package/assets/copilot/skills/mcp-memory/references/agent-memory-protocol.md

@@ -0,0 +1,186 @@
+# Agent Memory Protocol
+
+Per-agent memory read/write responsibilities. Each role has specific obligations for when to read from and write to the knowledge graph.
+
+**Two stores, two jobs.** Memory is for **searchable knowledge** (learnings, patterns, preferences, agent insights). The run ledger (`.vesper/.tracking/runs/`, written only by `vespercli log`) and the story folders are for **pipeline state** (what ran, how far it got, what is next). Nothing below writes task state into memory, and no agent reads memory to find out where a pipeline stopped — that is `vespercli story list` + `vespercli log tail`, the orchestrator's job.
+
+## Orchestrator (root `CLAUDE.md`)
+
+**Role**: Reader and router. Never writes directly — delegates memory writes to specialists.
+
+### Session Start Protocol
+
+1. `vespercli story list` and `vespercli log tail -n 5` — pipeline state (not memory)
+2. `mcp__memory__search_nodes("learning")` — scan recent learnings for anything affecting the current session
+3. If a run is in flight (a `started` row with no later `completed`) → resume by delegating to the appropriate next subagent, naming the handoff files
+4. Otherwise → proceed with normal routing
+
+### Pre-Delegation Check
+
+Before delegating any task:
+
+1. `mcp__memory__search_nodes("<task domain keywords>")` — find relevant learnings
+2. If learnings exist → include entity names in delegation prompt: *"Check memory entities: `learning_x`, `learning_y` before proceeding"*
+3. If agent_insight exists for this task type → use it to inform agent selection
+
+### Memory Writes
+
+The orchestrator does NOT write to memory directly. After task completion:
+- Delegate to `feature-wrap-document` for learning capture
+- Feature Wrap handles all entity creation
+
+### What the Orchestrator Reads
+
+| When | Tool | Query |
+| :---- | :---- | :---- |
+| Session start | `mcp__memory__search_nodes` | `"learning"` (state itself comes from the ledger) |
+| Before delegation | `mcp__memory__search_nodes` | Task domain keywords |
+| Agent selection | `mcp__memory__search_nodes` | `"agent_insight"` + task type |
+| User asks "what do you remember" | `mcp__memory__read_graph` | Full graph for summary |
+
+---
+
+## feature-wrap-document
+
+**Role**: Primary memory writer. Creates and maintains learning entities after implementation.
+
+### Post-Implementation Protocol
+
+After analyzing completed work (changes files, git diffs, the run ledger's rows for the slug, conversation history):
+
+1. **Identify learnings** using standard criteria:
+   - User corrected a decision
+   - Unexpected behavior required different approach
+   - Workspace-specific pattern discovered
+   - Agent selection was wrong
+   - File path or naming convention was incorrect
+
+2. **Check for duplicates**:
+   - `mcp__memory__search_nodes("<learning description keywords>")` before creating
+   - If similar entity exists → `mcp__memory__add_observations` to existing entity instead
+   - If entity is outdated → create new entity with `supersedes` relation
+
+3. **Create entities**:
+   - One `learning` entity per distinct correction/insight
+   - One `workspace_pattern` entity per discovered workspace convention
+   - One `agent_insight` entity per agent selection lesson
+   - Follow naming and observation rules from [entity-schema](entity-schema.md)
+
+4. **Create relations**:
+   - `relates_to` → link related learnings together
+   - `supersedes` → link updated learning to the one it replaces
+   - `informs` → link a workspace pattern to the learning it explains
+
+5. **Record the decision** (Implementation completions): the one-line summary of what shipped goes into the `recent-decisions.md` ring buffer (N=10) AND, when it is a durable choice, into a `learning`/`workspace_pattern` entity — the file is the convenience view, memory is the record.
+
+### What Feature Wrap Writes
+
+| Entity Type | When | Example |
+| :----------- | :---- | :------- |
+| `learning` | User correction, unexpected behavior | `learning_flow_check_ledger_first` |
+| `workspace_pattern` | Convention discovered | `workspace_pattern_server_actions_in_lib` |
+| `agent_insight` | Wrong agent was used | `agent_insight_researcher_for_migration` |
+| `preference` | User stated preference | `preference_testing_no_auto_run` |
+
+---
+
+## task-researcher
+
+**Role**: Reader before research; occasional writer for research-related learnings.
+
+### Pre-Research Protocol
+
+Before starting any research task:
+
+1. `mcp__memory__search_nodes("<research topic keywords>")` — find prior research insights
+2. If relevant `learning` entities exist → factor them into research approach
+3. If `workspace_pattern` entities exist for the domain → respect workspace conventions
+
+### Post-Research Protocol
+
+After completing research:
+
+1. If research contradicts a prior `learning` → create new learning with `supersedes` relation
+2. The research file (`.vesper/.tracking/research/YYYYMMDD-<slug>-research.md`) is the handoff; the orchestrator records the milestone with `vespercli log note`. Do not write task state into memory.
+
+### What Task Researcher Reads/Writes
+
+| Action | When | Tool |
+| :------ | :---- | :---- |
+| Read | Before research | `mcp__memory__search_nodes` with topic keywords |
+| Write | Prior learning outdated | `mcp__memory__create_entities` + `mcp__memory__create_relations` (supersedes) |
+
+---
+
+## code-planner
+
+**Role**: Reader before planning.
+
+### Pre-Planning Protocol
+
+Before creating any implementation plan:
+
+1. `mcp__memory__search_nodes("planning")` — find planning-related learnings (wrong estimates, missed deps)
+2. `mcp__memory__search_nodes("<task domain>")` — find domain-specific learnings
+3. Read the research file named in the delegation prompt — that is the researcher's handoff
+4. Factor all findings into plan estimates and dependency analysis
+
+### Post-Planning Protocol
+
+The plan/details/prompt files are the handoff to the implementation agents; the orchestrator records the milestone with `vespercli log note`. Nothing is written to memory.
+
+### What Code Planner Reads/Writes
+
+| Action | When | Tool |
+| :------ | :---- | :---- |
+| Read | Before planning | `mcp__memory__search_nodes` |
+
+---
+
+## The run ledger (`vespercli log`)
+
+**No memory interaction.** The CLI appends chronological rows (`started`, `completed`, `note`, `delegated`, `returned`) to `.vesper/.tracking/runs/YYYYMMDD-<slug>.jsonl`; the orchestrator reads them with `vespercli log tail`.
+
+Memory is for **searchable knowledge** (learnings, patterns, preferences).
+The ledger is for **chronological timeline** (what happened when).
+
+These are complementary systems — do not merge them.
+
+---
+
+## code-reviewer / principal-software-engineer
+
+**Role**: Reader only. May reference learnings when reviewing code.
+
+### During Review
+
+1. `mcp__memory__search_nodes("<review domain>")` — check if prior learnings affect review criteria
+2. If learnings exist about common mistakes in this domain → flag them proactively
+3. Do NOT write to memory — feed review findings back to the orchestrator for Feature Wrap to capture
+
+---
+
+## Cross-Agent Handoff Sequence
+
+Standard handoff flow — files carry state, the ledger carries chronology, memory carries knowledge:
+
+```
+Orchestrator: vespercli log started --pipeline implementation --slug <slug> …
+Orchestrator delegates to Task Researcher (prompt names the output path)
+  → Researcher: search_nodes → do research → writes research/<slug>-research.md
+  → Returns to orchestrator (Status: DONE) → orchestrator: vespercli log note --step 1
+
+Orchestrator delegates to Code Planner (prompt names the research path)
+  → Planner: search_nodes → reads research → writes plans/, details/, prompts/
+  → Returns to orchestrator → orchestrator: vespercli log note --step 2
+
+Orchestrator delegates to implementation agent (prompt names the prompt file)
+  → Agent: search_nodes → implement → writes changes/<slug>-changes.md
+  → Returns to orchestrator
+
+Orchestrator delegates to Feature Wrap (prompt names changes/plans/research paths)
+  → Feature Wrap: analyze → create learning entities → append recent-decisions.md
+  → Returns to orchestrator → orchestrator: vespercli log completed --status DONE
+```
+
+Each handoff preserves context through the tracking files it names; the ledger makes the sequence resumable after an interruption, and memory makes the next task smarter.