@mthanh/vespercli 1.8.0 → 2.0.1

package/assets/core/instructions/vesper-cli-development.instructions.md

@@ -1,85 +0,0 @@
----
-description: Patterns and rules for Vesper CLI development and asset management
-applyTo: src/cli/**/*.js
----
-
-# Vesper CLI Development Guidelines
-
-## 1. Re-initialization Safety
-
-### Reset-First Pattern
-
-When implementing `vesper init` or re-initialization logic, you **MUST** follow the Reset-First pattern to prevent data corruption or duplication.
-
-**Rule:** Delete/reset operations MUST happen **BEFORE** create/update operations.
-
-```javascript
-// ✅ Correct Pattern
-async function reinitialize() {
-	// 1. Reset first (destroy old state)
-	await deleteExistingConfig();
-	await settings.resetToDefaults();
-
-	// 2. Then create (build new state)
-	await createNewConfig();
-	await settings.writeConfig();
-}
-```
-
-**Why:**
-
-- Prevents merging old/new arrays (resulting in duplicates)
-- Ensures clean state for major version updates
-- Avoids "partial state" bugs where old settings conflict with new schemas
-
-## 2. Comprehensive Configuration Tracking
-
-The Vesper CLI MUST track every configuration change it makes to VS Code settings.
-
-### Tracking Standard
-
-All modifications to `settings.json` MUST correspond to an entry in `.vesperrc`.
-
-- **Paths**: Add modified file paths to `paths` array.
-- **MCP Servers**: Add server names to `mcp.servers` array.
-- **Agent Tools**: Add tool names to `mcp.agentTools` map.
-
-**Rule:** `resetToDefaults()` MUST use the tracked data in `.vesperrc` to revert changes. DO NOT rely on hardcoded paths for cleanup.
-
-### VS Code Settings Management
-
-Use `VESPER_MANAGED_SETTINGS` constant to define the list of settings Vesper controls.
-
-```javascript
-// src/cli/utils/settings.js
-export const VESPER_MANAGED_SETTINGS = [
-	'chat.agentFilesLocations',
-	'chat.commandCenter.enabled',
-	// ...
-];
-```
-
-## 3. Asset Management Architecture
-
-### Core vs Extended Assets
-
-The CLI distinguishes between mandatory core system files and optional catalog items.
-
-| Category     | Source Path               | Purpose                                                | Installation              |
-| ------------ | ------------------------- | ------------------------------------------------------ | ------------------------- |
-| **Core**     | `assets/core/`            | System orchestrator, base instructions, default skills | Mandatory (`vesper init`) |
-| **Extended** | `assets/{agents,skills}/` | Optional capabilities, frameworks, specialized agents  | Optional (`vesper add`)   |
-
-### Implementation Details
-
-- **Legacy Support:** `assets/core/` replaced the flat structure to separate system files from user choices.
-- **Control Flow:** `getCoreAssetEntries()` in `utils/file-ops.js` controls what `init` installs.
-- **Root Path:** `assets/` serves as the root for the Extended Catalog exposed to `vesper list`.
-
-## 3. Backend Development Principles
-
-Apply **backend-development** skill principles to CLI logic:
-
-- **Idempotency:** Commands like `init` and `add` should produce the same result if run multiple times.
-- **Error Handling:** Wrap file operations in try/catch blocks and use the logger for user-friendly errors.
-- **Atomic Operations:** When possible, ensure file writes are atomic or have rollback mechanisms (though CLI has limited transaction support).

package/assets/core/instructions/vesper-implement.instructions.md

@@ -1,250 +0,0 @@
----
-description: Vesper orchestration for implementation pipeline steps 4-10 — validation, coding, review, testing, documentation wrap-up
----
-
-# Vesper Purpose: Implementation — Code & Review Phase
-
-This instruction file expands the Implementation purpose pipeline Steps 4-10 from `vesper.agent.md` with detailed orchestration.
-
-**Step mapping** (instruction step → main pipeline step):
-
-| Instruction Step | Main Pipeline Step | Action                  |
-| :--------------- | :----------------- | :---------------------- |
-| STEP 4           | Step 4             | Validate Planning Files |
-| STEP 5           | Step 5             | Execute Implementation  |
-| STEP 6           | Step 6             | Code Review + Fix Loop  |
-| STEP 7           | Step 7             | Unit Testing            |
-| STEP 8           | Step 8             | Documentation Wrap-Up   |
-| STEP 9           | Step 9             | Feature Wrap            |
-| STEP 10          | Step 10            | Update Task Board       |
-
-Steps 1-3 (Research, Plan, Architect Validation) are covered by `#instruction:vesper-research-plan`.
-Step 11 (Log completion) is handled directly by Vesper.
-
-## Prerequisites
-
-- ✅ Research & Plan phase complete (plans, details, prompts exist)
-- Developer resolved from Team Roster
-
-## Orchestration Steps
-
-### STEP 4: Validate Planning Files (BLOCKING)
-
-Search for required files from the Plan phase:
-
-- [ ] `.vesper/.tracking/prompts/implement-*.prompt.md`
-- [ ] `.vesper/.tracking/plans/YYYYMMDD-*-plan.instructions.md`
-- [ ] `.vesper/.tracking/details/YYYYMMDD-*-details.md`
-- [ ] `.vesper/.tracking/research/YYYYMMDD-*-research.md`
-
-**Memory context**: `search_nodes("current_task")` — if a `task_context` entity exists from the planning phase, check its `status` and `key_decisions` observations for quick context.
-
-**IF ANY FILE MISSING:**
-
-- STOP and report: "Planning incomplete. Cannot proceed. Missing: [list]"
-- Suggest: "Run Research & Plan phase first"
-- DO NOT PROCEED
-
-### STEP 5: Execute Implementation (⚡ PARALLEL BY TRACK)
-
-The plan may contain multiple independent implementation tracks (e.g., backend API + frontend UI + database migration). Each track has its own prompt file.
-
-1. List all prompt files: `.vesper/.tracking/prompts/implement-*.prompt.md`
-2. For EACH prompt file, resolve the matching Developer from Team Roster (the prompt specifies the surface/stack — match to the best agent)
-3. Delegate ALL independent tracks in parallel — one subagent per track
-4. Each developer tracks changes in their own file: `.vesper/.tracking/changes/YYYYMMDD-[slug]-[track]-changes.md`
-
-Delegate to each Developer:
-
-```
-"Execute implementation using the prepared prompt.
-
-Implementation Prompt: .vesper/.tracking/prompts/implement-[slug]-[track].prompt.md
-
-The prompt contains:
-- References to plan, details, and research files
-- Step-by-step instructions for this track
-- Success criteria
-
-Memory: Check open_nodes(['current_task']) for task context and search_nodes('<task domain>') for relevant learnings before starting.
-
-Follow the implementation prompt exactly.
-Track changes in: .vesper/.tracking/changes/YYYYMMDD-[slug]-[track]-changes.md"
-```
-
-**Single track**: If only one prompt file exists, this is a standard single-developer delegation — no change from previous behavior.
-
-**WAIT** for ALL tracks to complete before proceeding to review.
-
-If any track returns `NEED_HELP` or `BLOCKED` → handle that track without blocking other running tracks.
-
-Note: Developer follows `#instruction:task-implementation`
-
-### STEP 6: Code Review — ⚡ PARALLEL
-
-After implementation, call BOTH reviewers in parallel:
-
-**Delegate to `@Code Reviewer Agent`:**
-
-```
-"Review changes for [task].
-
-Changes file: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
-Plan: .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.instructions.md
-
-Focus: Code quality, standards compliance, maintainability, test coverage.
-Approve or request specific changes."
-```
-
-**Delegate to `@Principal Software Engineer Agent`:**
-
-```
-"Review changes for [task].
-
-Changes file: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
-Plan: .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.instructions.md
-
-Focus: Architecture alignment, security, performance, scalability, design patterns.
-Approve or request specific changes."
-```
-
-Consolidate feedback from both reviewers.
-
-**IF any reviewer has feedback:**
-
-1. Delegate to Developer to fix all issues
-2. Re-review with BOTH reviewers (parallel)
-3. Repeat until both approve (subject to the global loop limit in `vesper.agent.md`)
-
-### STEP 7: Unit Testing
-
-Delegate to **Tester from roster** → fallback Developer:
-
-```
-"Write unit tests for implemented code.
-
-Scope: Unit tests ONLY (integration/E2E tests are handled in Testing purpose)
-
-Requirements:
-- Cover all acceptance criteria from the plan
-- Include edge cases identified in research
-- Test individual functions/components in isolation
-
-Track in: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md"
-```
-
-**WAIT** for unit tests to pass. If tests fail and require code changes, loop with Developer until green (subject to the global loop limit in `vesper.agent.md`).
-
-### STEP 8: Documentation Wrap-Up
-
-Delegate to `@SE: Tech Writer`:
-
-```
-"Update documentation for completed implementation.
-
-Review:
-- Changes: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
-- Details: .vesper/.tracking/details/YYYYMMDD-[slug]-details.md
-
-Update: README, API docs, inline comments as needed.
-Capture learnings for future reference."
-```
-
-### STEP 9: Feature Wrap
-
-**Delegate to `@Feature Wrap and Retrospective Agent`:**
-
-```
-"Analyze completed implementation for knowledge capture.
-
-Changes file: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
-
-Identify:
-- Patterns worth documenting
-- Instruction updates needed
-- Skill opportunities
-- Newly discovered best practices, pitfalls, or workspace-specific insights
-
-Memory: Use MCP Memory tools (memory/*) to create learning, workspace_pattern, and agent_insight entities.
-Follow #skill:mcp-memory for entity schema and hygiene rules.
-Clean up current_task entity if task is complete.
-
-Present numbered proposals. Vesper will approve."
-```
-
-**Vesper Approval:**
-
-- Review agent proposals
-- Approve ONLY what is truly reusable and necessary
-- Skip one-off solutions or obvious patterns
-- Criteria: "Would this help future tasks significantly?"
-
-### STEP 10: Update Task Board & Move Story
-
-**Always** (regardless of Task Management): Move story file from `inprogress/` to `inreview/`.
-
-**Additionally, if Task Management configured AND task reference exists**:
-
-Delegate to Task Agent (from Team Roster):
-
-```
-"Update task [task-id] status to IN REVIEW.
-Add comment: Implementation complete. Changes tracked in .vesper/.tracking/changes/"
-```
-
-**WAIT** for confirmation before proceeding to Step 11 (Log completion).
-
-## Output
-
-- Code changes implemented
-- `.vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md` (complete log)
-- Unit tests written and passing
-- Documentation updated
-- Story file moved to `inreview/`
-- Task status: IN REVIEW (if Task Management configured)
-
-## Next
-
-→ After Step 11 (Log completion, handled by Vesper), **E2E/integration testing** auto-triggers via Testing purpose (Mode A: Post-Implementation). See `#instruction:vesper-qa-e2e`.
-
-## Post-Flow: Memory Update
-
-After feature wrap complete, execute `#prompt:memory-update` to review if any learnings should be recorded.
-
----
-
-## Bug Fix Review Focus (when Purpose = bug fix)
-
-When delegating to reviewers in STEP 6 for a bug fix, add to the delegate prompt:
-
-```
-"Additional review focus for bug fix:
-- Fix addresses root cause (not just symptoms)
-- Regression test covers the exact scenario
-- No unintended side effects introduced
-- Is the fix minimal and scoped correctly?"
-```
-
-Bug fixes often reveal patterns worth documenting — ensure Feature Wrap in STEP 9 captures root cause categories, testing gaps, or common pitfalls.
-
----
-
-## Skills Implementation (when task = skill creation)
-
-When the task is creating a skill, STEP 5 delegates to `@Skill Creator Agent` instead of the Developer from roster:
-
-```
-"Create skill for [topic/technology].
-
-Research: .vesper/.tracking/research/YYYYMMDD-skill-research.md
-Plan: .vesper/.tracking/plans/YYYYMMDD-skill-plan.instructions.md
-
-Relevant Skills: skill-creator"
-```
-
-If Skill Creator's VESPER_RESPONSE is `NEED_HELP` asking about workspace patterns:
-
-1. Delegate to `@Workspace Learner` to answer the specific question (do NOT re-scan the codebase)
-2. Return answer to Skill Creator in a follow-up call
-
-**Output**: New skill file created in `.github/skills/` or `skills/`

package/assets/core/instructions/vesper-qa-e2e.instructions.md

@@ -1,155 +0,0 @@
----
-description: Vesper orchestration for E2E and integration testing after implementation completes
----
-
-# Vesper Purpose: Testing — Orchestration Steps
-
-This instruction file contains the detailed orchestration steps for the Testing purpose.
-
-## Mode A: Post-Implementation (Auto-triggered after Implementation pipeline completes — Step 11)
-
-Uses existing materials from the completed Implementation pipeline — no research or planning needed.
-
-### Prerequisites
-
-- ✅ Implementation complete
-- ✅ Changes file exists: `.vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md`
-- ✅ Details file exists: `.vesper/.tracking/details/YYYYMMDD-[slug]-details.md`
-
-### STEP 1: Run E2E/Integration Tests
-
-Delegate to **Tester from roster**:
-
-```
-"Execute E2E and integration tests for [task/feature].
-
-Scope:
-- Integration tests for API changes
-- E2E tests for user flows
-- Cross-browser testing (if applicable)
-
-Reference:
-- Changes: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
-- Details: .vesper/.tracking/details/YYYYMMDD-[slug]-details.md
-
-Report results and any failures."
-```
-
-### STEP 2: Log Issues (if tests fail)
-
-**IF tests fail:**
-
-Delegate to Tester:
-
-```
-"Log test failures to issues file.
-
-Create/update: .vesper/.tracking/issues/YYYYMMDD-[slug]-issues.md
-
-For each failure include:
-- Test name and file
-- Expected vs actual behavior
-- Steps to reproduce
-- Error logs/screenshots
-- Severity (critical/high/medium/low)
-
-Format as actionable bug reports."
-```
-
-### STEP 3: Fix Issues
-
-**IF issues logged:**
-
-Delegate to **Developer from roster**:
-
-```
-"Fix issues identified in QA testing.
-
-Issues: .vesper/.tracking/issues/YYYYMMDD-[slug]-issues.md
-
-For each issue:
-- Implement fix
-- Add/update unit test to cover the case
-- Update changes file
-
-Track in: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md"
-```
-
-### STEP 4: Re-run Tests
-
-After fixes applied:
-
-1. Return to STEP 1
-2. Repeat until all tests pass (subject to the global loop limit in `vesper.agent.md`)
-
-### STEP 5: Review Test Quality
-
-Delegate to `@Code Reviewer Agent`:
-
-```
-"Review test quality for [task].
-
-Test files: [paths from Tester output]
-Changes: .vesper/.tracking/changes/YYYYMMDD-[slug]-changes.md
-
-Check: coverage, edge cases, maintainability, no flaky tests."
-```
-
-### STEP 6: Update Status (when all tests pass)
-
-Delegate to **Task Agent** (from Team Roster, if Task Management configured):
-
-```
-"Update task [task-id] status to DONE.
-Add comment: QA complete. All E2E/integration tests passing."
-```
-
----
-
-## Mode B: Standalone (User explicitly requests tests)
-
-Full pipeline — same rigor as Implementation.
-
-### Steps
-
-| Step | Action                                                      | Agent                                                                          |
-| :--- | :---------------------------------------------------------- | :----------------------------------------------------------------------------- |
-| 1    | Research (understand system, existing tests, coverage gaps) | Researcher/Analyzer from roster → fallback `@Task Researcher Specialist Agent` |
-| 2    | Plan (test strategy, cases, scope)                          | Planner from roster → fallback `@Code Planner Agent`                           |
-| 3    | Write + run tests                                           | Tester from roster                                                             |
-| 4    | Fix failures (if any)                                       | Developer from roster                                                          |
-| 5    | Re-run tests                                                | Tester from roster                                                             |
-| 6    | Review test quality                                         | `@Code Reviewer Agent`                                                         |
-| 7    | Feature wrap                                                | `@Feature Wrap and Retrospective Agent`                                        |
-| 8    | Log completion                                              | `@History Logger`                                                              |
-
-**Loop**: Steps 3-5 repeat until tests pass (subject to the global loop limit in `vesper.agent.md`). Issues logged in `issues/`.
-
----
-
-## Output
-
-- E2E/Integration tests passing
-- `.vesper/.tracking/issues/YYYYMMDD-[slug]-issues.md` (resolved issues log)
-- Additional unit tests for edge cases found
-- Task status: DONE
-
-## Issue File Format
-
-```markdown
-# QA Issues: [Task Name]
-
-## Issue 1: [Test Name]
-
-- **Severity**: critical/high/medium/low
-- **Test File**: path/to/test.spec.ts
-- **Expected**: What should happen
-- **Actual**: What actually happened
-- **Steps to Reproduce**:
-  1. Step 1
-  2. Step 2
-- **Error Log**: [stack trace or error message]
-- **Status**: OPEN / FIXED / VERIFIED
-
-## Issue 2: ...
-```

package/assets/core/instructions/vesper-reinit.instructions.md

@@ -1,99 +0,0 @@
----
-description: Vesper re-initialization pipeline and memory file rules for workspace refresh
----
-
-# Vesper: Re-initialization & Memory File Rules
-
-This instruction file covers two concerns:
-
-1. **Re-initialization** — the full pipeline for refreshing workspace setup when explicitly requested
-2. **Memory File Rules** — constraints for creating/updating `memory.instructions.md` (applies to both initial setup and re-initialization)
-
----
-
-## Re-initialization Pipeline
-
-Triggered when user explicitly asks to re-initialize (e.g., "Re-vesperize", "re-initialize", "refresh workspace setup").
-
-### Prerequisites
-
-- ✅ `.github/instructions/orchestration.instructions.md` with a Team Roster already exists
-- This is NOT a first-time setup — this is a refresh of an existing workspace
-
-### Orchestration Steps
-
-| Step | Action                                                                                                                                                                                    | Agent                                   |
-| :--- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- |
-| 1    | Force full re-scan of codebase. Do NOT skip with "already current" — treat as fresh analysis. Compare with existing `copilot-instructions.md` and produce a diff summary of what changed. | `@Workspace Learner`                    |
-| 2    | Review Team Roster changes: validate agent composition still fits the project's current needs. Approve or recommend additions/removals.                                                   | `@SE: Architect`                        |
-| 3    | Present Workspace Learner's diff summary + Architect's roster recommendations to user for confirmation.                                                                                   | Vesper (via `vscode/askQuestions`)      |
-| 4    | Apply confirmed changes to `copilot-instructions.md` and `orchestration.instructions.md`.                                                                                                 | `@Workspace Learner`                    |
-| 5    | Scoped memory update (see Memory Protocol below).                                                                                                                                         | `@Feature Wrap and Retrospective Agent` |
-| 6    | Log `"Workspace re-initialized"`                                                                                                                                                          | `@History Logger`                       |
-
-### Step 1 — Force Re-scan
-
-Delegate to `@Workspace Learner`:
-
-```
-"Force full workspace re-scan. This is a RE-INITIALIZATION — do NOT skip with 'already current'.
-Treat this as a fresh analysis. Compare results with the existing copilot-instructions.md.
-Produce a diff summary: what changed, what's new, what was removed.
-Save updated copilot-instructions.md and produce the diff summary in your response."
-```
-
-### Step 2 — Architect Roster Review
-
-Delegate to `@SE: Architect` with the current Team Roster included in the prompt:
-
-```
-"Review the current Team Roster against the updated copilot-instructions.md.
-
-Current Team Roster:
-[Vesper: paste the Team Roster table from orchestration.instructions.md here]
-
-Evaluate:
-- Are all current agents still needed?
-- Are there gaps — new capabilities needed that no current agent covers?
-- Should any agents be added or removed based on how the project has evolved?
-
-Provide specific recommendations: keep / add / remove for each agent role."
-```
-
-### Step 3 — User Confirmation
-
-Use `vscode/askQuestions` with options and allow free-form input:
-
-- **"Apply all changes"** — accept both workspace learning and roster updates
-- **"Apply workspace learning only"** — keep current Team Roster unchanged
-- **"Cancel"** — abort re-initialization, keep everything as-is
-
-### Step 4 — Apply Changes
-
-Based on user's choice:
-
-- **"Apply all changes"** → Delegate to `@Workspace Learner` to apply copilot-instructions + roster changes
-- **"Apply workspace learning only"** → Delegate to `@Workspace Learner` to apply copilot-instructions only, skip roster changes
-- **"Cancel"** → Stop. Log `"Re-initialization cancelled by user"` and return
-
-### Step 5 — Memory Update
-
-Delegate to `@Feature Wrap and Retrospective Agent` using the Memory Protocol below.
-
-### Step 6 — Log
-
-Delegate to `@History Logger`: log `"Workspace re-initialized"` with summary of what changed.
-
----
-
-## Memory Protocol
-
-When initializing or updating memory, delegate to `@Feature Wrap and Retrospective Agent` with `#skill:mcp-memory`.
-
-The skill defines entity schema, per-agent memory protocols, and hygiene rules for the MCP Memory knowledge graph.
-
-This applies to:
-
-- **Initial creation** (Auto-Setup Step 2 in `vesper.agent.md`)
-- **Re-initialization** (Step 5 above)
-- **Post-implementation memory updates** (Feature Wrap agent)