@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/copilot/skills/mcp-memory/references/entity-schema.md

@@ -0,0 +1,141 @@
+# Entity Schema
+
+Entity types, naming conventions, observation patterns, and relation rules for the Vesper memory knowledge graph.
+
+## Entity Types
+
+### `learning`
+
+Corrections, mistakes, and better approaches discovered during work.
+
+**Naming**: `learning_<category>_<brief_slug>` — e.g., `learning_delegation_always_use_researcher_first`
+
+**Required observations** (one per observation, atomic):
+- `trigger: <what happened or went wrong>`
+- `correction: <the correct approach>`
+- `apply_when: <conditions for applying this learning>`
+- `category: <Flow|Delegation|Agent Selection|File Paths|Prompts|User Preference>`
+- `discovered: <YYYY-MM-DD>`
+
+**Example:**
+```
+Entity: learning_delegation_researcher_before_planner
+Type: learning
+Observations:
+  - "trigger: Code Planner started planning without research, produced plan with wrong assumptions"
+  - "correction: Always delegate to Task Researcher before Code Planner"
+  - "apply_when: Any new feature task that requires codebase analysis"
+  - "category: Delegation"
+  - "discovered: 2026-02-24"
+```
+
+### `preference`
+
+User preferences discovered during work sessions.
+
+**Naming**: `preference_<domain>_<brief_slug>` — e.g., `preference_testing_no_auto_run`
+
+**Required observations:**
+- `preference: <what the user prefers>`
+- `context: <when/why this preference was expressed>`
+- `discovered: <YYYY-MM-DD>`
+
+**Example:**
+```
+Entity: preference_testing_no_auto_run
+Type: preference
+Observations:
+  - "preference: Do not run tests automatically after generating them"
+  - "context: User explicitly corrected agent behavior during test generation task"
+  - "discovered: 2026-02-15"
+```
+
+### `workspace_pattern`
+
+Workspace-specific patterns that affect how subagents should operate in this project.
+
+**Naming**: `workspace_pattern_<brief_slug>` — e.g., `workspace_pattern_server_actions_in_lib`
+
+**Required observations:**
+- `pattern: <description of the pattern>`
+- `location: <where in the codebase this applies>`
+- `impact: <how this affects agent behavior>`
+- `discovered: <YYYY-MM-DD>`
+
+**Example:**
+```
+Entity: workspace_pattern_server_actions_in_lib
+Type: workspace_pattern
+Observations:
+  - "pattern: Server actions live in lib/actions/ not app/actions/"
+  - "location: lib/actions/*.ts"
+  - "impact: File creation and imports must target lib/actions/"
+  - "discovered: 2026-02-20"
+```
+
+### `agent_insight`
+
+Learnings about which subagents perform best for specific task types.
+
+**Naming**: `agent_insight_<brief_slug>` — e.g., `agent_insight_researcher_for_migration`
+
+**Required observations:**
+- `insight: <what was learned about agent selection>`
+- `wrong_choice: <which agent was tried and failed or suboptimal>`
+- `right_choice: <which agent should be used instead>`
+- `task_type: <what kind of task this applies to>`
+- `discovered: <YYYY-MM-DD>`
+
+**Example:**
+```
+Entity: agent_insight_researcher_for_migration
+Type: agent_insight
+Observations:
+  - "insight: Migration tasks need research phase before planning"
+  - "wrong_choice: Delegated directly to Code Planner"
+  - "right_choice: Task Researcher first, then Code Planner"
+  - "task_type: Database or library migration"
+  - "discovered: 2026-02-18"
+```
+
+> **No task-state type.** Vesper 2.0 removed the `task_context` entity (and its `current_task`
+> singleton). Pipeline state — which run is in flight, which step it reached, what the next agent
+> should do — lives in the run ledger (`.vesper/.tracking/runs/`, written by `vespercli log`) and
+> the story folders, and the handoff itself is the tracking file the previous agent wrote. Memory
+> holds durable knowledge only. Do not create task-state entities under any name.
+
+## Naming Rules
+
+| Rule | Convention | Example |
+| :--- | :--------- | :------ |
+| Case | `snake_case` | `learning_flow_check_history_first` |
+| Prefix | Entity type as prefix | `preference_`, `learning_`, etc. |
+| Length | Descriptive but under 80 characters | Keep slugs to 3-6 words |
+| Uniqueness | Names must be globally unique | Check with `mcp__memory__search_nodes` before creating |
+
+## Relation Rules
+
+Relations are **directed** and use **active voice** verbs.
+
+| Relation Type | Meaning | Example |
+| :------------- | :------ | :------ |
+| `blocks` | Source blocks target | `task_auth` → blocks → `task_dashboard` |
+| `depends_on` | Source depends on target | `workspace_pattern_auth_flow` → depends_on → `learning_auth_pattern` |
+| `discovered_by` | Learning discovered during task | `learning_x` → discovered_by → `task_y` |
+| `supersedes` | Source replaces target | `learning_new` → supersedes → `learning_old` |
+| `relates_to` | Loose association | `preference_x` → relates_to → `workspace_pattern_y` |
+| `informs` | Source provides context for target | `workspace_pattern_x` → informs → `learning_y` |
+
+**Rules:**
+- From/to must reference existing entity names
+- Use active voice: `blocks`, not `is_blocked_by`
+- One relation per fact — don't overload a single relation
+- `supersedes` is the preferred way to handle updated learnings (keep old for audit trail)
+
+## Observation Rules
+
+- **One fact per observation** — atomic, not compound sentences
+- **Prefix with field name** — `trigger:`, `correction:`, `pattern:`, etc.
+- **No markdown formatting** — plain text only inside observations
+- **Timestamps use ISO format** — `YYYY-MM-DD` or `YYYY-MM-DD HH:MM`
+- **Max ~200 characters per observation** — split long facts into multiple observations

package/assets/copilot/skills/mcp-memory/references/memory-hygiene.md

@@ -0,0 +1,163 @@
+# Memory Hygiene
+
+Cleanup rules, deduplication strategies, lifecycle management, and maintenance triggers for the knowledge graph.
+
+## Observation Hygiene
+
+### Atomic Observations
+
+Each observation must contain exactly one fact. Split compound statements.
+
+**❌ Bad:**
+```
+"User prefers no auto-run tests and wants TypeScript strict mode enabled"
+```
+
+**✅ Good:**
+```
+"preference: Do not run tests automatically after generating them"
+"preference: TypeScript strict mode must be enabled in all projects"
+```
+
+### Observation Prefixes
+
+Always prefix observations with their field name for searchability:
+
+| Prefix | Used In | Purpose |
+| :------ | :------- | :------- |
+| `trigger:` | learning | What went wrong |
+| `correction:` | learning | The right approach |
+| `apply_when:` | learning | When to apply |
+| `category:` | learning | Classification |
+| `preference:` | preference | User preference |
+| `context:` | preference | When preference was expressed |
+| `pattern:` | workspace_pattern | Pattern description |
+| `location:` | workspace_pattern | Codebase location |
+| `impact:` | workspace_pattern | How it affects agents |
+| `insight:` | agent_insight | Agent selection learning |
+| `discovered:` | all types | ISO date of discovery |
+
+## Deduplication
+
+### Before Creating Any Entity
+
+1. `mcp__memory__search_nodes("<key terms from the new learning>")` — check for existing matches
+2. If exact match → skip creation entirely
+3. If partial match (same topic, different insight) → `mcp__memory__add_observations` to existing entity
+4. If contradiction → create new entity with `supersedes` relation to old one
+5. If genuinely new → create new entity
+
+### Search Strategy for Dedup
+
+Search with **multiple queries** to catch near-duplicates:
+
+```
+mcp__memory__search_nodes("delegation researcher planner")
+mcp__memory__search_nodes("task researcher before planning")
+```
+
+If either returns a relevant entity, update instead of creating.
+
+## Entity Lifecycle
+
+### Learning Entities
+
+| State | Trigger | Action |
+| :----- | :------- | :------ |
+| Active | Created after correction | Normal — agents consult during relevant tasks |
+| Superseded | New learning contradicts it | Create new + `supersedes` relation; keep old |
+| Obsolete | Root cause fixed permanently | `mcp__memory__delete_entities` — the learning no longer applies |
+| Stale | 90+ days without relevance | Review during hygiene sweep; delete if no longer applicable |
+
+### Preference Entities
+
+| State | Trigger | Action |
+| :----- | :------- | :------ |
+| Active | User expressed preference | Normal — agents respect during all tasks |
+| Updated | User changed preference | `mcp__memory__delete_observations` old + `mcp__memory__add_observations` new |
+| Revoked | User explicitly reversed | `mcp__memory__delete_entities` |
+
+### Workspace Pattern Entities
+
+| State | Trigger | Action |
+| :----- | :------- | :------ |
+| Active | Pattern discovered | Normal — agents follow pattern |
+| Changed | Codebase restructured | Update observations; add `updated:` observation |
+| Obsolete | Pattern no longer exists | `mcp__memory__delete_entities` |
+
+### Task Context Entities
+
+| State | Trigger | Action |
+| :----- | :------- | :------ |
+| Active | Task in progress | Updated at each handoff |
+| Complete | Task finished | `mcp__memory__delete_entities` — Feature Wrap cleans up |
+| Stale | 7+ days with no update | Delete — task likely abandoned or completed outside system |
+
+## Cleanup Triggers
+
+### Automatic (Agent-Initiated)
+
+Feature Wrap WILL perform these checks after every task:
+
+1. **No task-state cleanup is needed** — pipeline state never enters memory (the run ledger and story folders hold it); if a stray task-state entity is found, delete it
+2. **Check superseded learnings** — if a new learning supersedes an old one and the old one has no other relations, consider deletion
+3. **Remove contradicted observations** — if a new observation directly contradicts an existing one on the same entity, `mcp__memory__delete_observations` the old one
+
+### Periodic (User-Prompted or Session Start)
+
+The orchestrator MAY trigger a hygiene sweep when:
+
+- User requests "clean up memory" or "review memory"
+- Session start reveals 50+ entities (graph getting large)
+- `mcp__memory__read_graph` shows entities with no relations and old `discovered:` dates
+
+**Hygiene sweep process:**
+
+1. `mcp__memory__read_graph` — get full graph
+2. Identify entities with `discovered:` date > 90 days
+3. For each old entity: check if still relevant to current workspace
+4. Delete obsolete entities and their orphaned relations
+5. Report cleanup summary to user
+
+## Relation Hygiene
+
+### Orphaned Relations
+
+When deleting an entity, `mcp__memory__delete_entities` auto-cascades its relations. No manual cleanup needed.
+
+### Redundant Relations
+
+Avoid creating multiple relations between the same pair of entities. One relation per directional relationship.
+
+**❌ Bad:**
+```
+learning_a → relates_to → learning_b
+learning_a → informs → learning_b
+```
+
+**✅ Good:** Choose the most specific relation type:
+```
+learning_a → informs → learning_b
+```
+
+## Graph Size Guidelines
+
+| Metric | Healthy | Warning | Action Needed |
+| :------ | :------- | :------- | :-------------- |
+| Total entities | < 30 | 30-50 | Review for stale entries |
+| Total entities | — | > 50 | Mandatory hygiene sweep |
+| Learning entities | < 20 | 20-30 | Check for superseded/obsolete |
+| Task context entities | 0-2 | 3-5 | Delete completed tasks |
+| Relations per entity | 1-3 | 4-6 | Check for redundancy |
+| Observations per entity | 3-7 | 8-12 | Split entity if observations cover different topics |
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+| :------------ | :------- | :-- |
+| Dumping all task details into memory | Bloats graph, buries real learnings | Only store corrections and insights |
+| Creating entities without searching first | Duplicates accumulate | Always `mcp__memory__search_nodes` before `mcp__memory__create_entities` |
+| Compound observations | Unsearchable, hard to update | One fact per observation |
+| Generic entity names | Collisions, ambiguity | Use type prefix + descriptive slug |
+| Never deleting anything | Graph noise grows | Apply lifecycle rules above |
+| Using memory instead of `.vesper/.tracking/` | Wrong system for task artifacts | Memory = knowledge; tracking = artifacts |

package/assets/copilot/skills/nodejs-javascript-vitest/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: nodejs-javascript-vitest
+description: Guidelines for writing Node.js and JavaScript code with Vitest testing
+---
+
+# Code Generation Guidelines
+
+## Coding standards
+
+- Use JavaScript with ES2022 features and Node.js (20+) ESM modules
+- Use Node.js built-in modules and avoid external dependencies where possible
+- Ask the user if you require any additional dependencies before adding them
+- Always use async/await for asynchronous code, and use 'node:util' promisify function to avoid callbacks
+- Keep the code simple and maintainable
+- Use descriptive variable and function names
+- Do not add comments unless absolutely necessary, the code should be self-explanatory
+- Never use `null`, always use `undefined` for optional values
+- Prefer functions over classes
+
+## Testing
+
+- Use Vitest for testing
+- Write tests for all new features and bug fixes
+- Ensure tests cover edge cases and error handling
+- NEVER change the original code to make it easier to test, instead, write tests that cover the original code as it is
+
+## Documentation
+
+- When adding new features or making significant changes, update the README.md file where necessary
+
+## User interactions
+
+- Ask questions if you are unsure about the implementation details, design choices, or need clarification on the requirements
+- Always answer in the same language as the question, but use english for the generated content like code, comments or docs

package/assets/copilot/skills/project-management/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: project-management
+description: 'Project-management conventions for agents — which task system is the source of truth, story lifecycle, status mapping and tracking rules. Use when creating, refining, moving or reporting on tasks and stories (e.g. as the Technical Product Manager).'
+---
+
+# Project Management Instructions (MANDATORY)
+
+Last updated: 2026-01-30
+Owner: <fill>
+
+This file is the single source of truth for **project management conventions** used by agents (e.g., the Technical Product Manager agent).
+
+## 1) Task Management System
+
+Which task management system is the source of truth?
+
+- System: <ClickUp | Jira | Local | Other>
+- Workspace/Org (if applicable): <fill>
+
+Purpose: This determines which MCP tools/agents must be used for reads/writes.
+
+## Agent Tracking (Always `.vesper/.tracking/`)
+
+Regardless of whether the task system is ClickUp, Jira, or Local, agent tracking files (refinement progress, batch logs, implementation progress) MUST live under:
+
+- `.vesper/.tracking/`
+
+## 2) Task System Configuration
+
+### ClickUp (fill only if System = ClickUp)
+
+- Space name: <fill>
+- Space ID (optional): <fill>
+- Default List/Folder (optional): <fill>
+- URL (optional): <fill>
+
+- Username/handle (ClickUp only; used ONLY if your branch naming pattern includes `{username}`):
+  - Examples: `thanh_tran`, `ttran`, `thanh`
+  - Username/handle: <fill>
+
+### Jira (fill only if System = Jira)
+
+- Project key: <fill>
+- Board name (optional): <fill>
+- URL (optional): <fill>
+
+### Local (fill only if System = Local)
+
+- Stories root folder: `docs/stories`
+- Backlog file: `docs/stories/backlog.md`
+- Tasks folder (optional): `docs/stories/tasks/`
+
+Note: `docs/stories` is for the local story/task _source of truth_ only. Agent tracking remains under `.vesper/.tracking/`.
+
+## 3) Status Model + Labels
+
+### Status Flow
+
+Define the canonical statuses and expected flow for THIS project.
+
+You MUST define these groups (names can differ per system):
+
+- Backlog statuses: <comma-separated>
+- In progress statuses: <comma-separated>
+- Review statuses: <comma-separated>
+- Done statuses: <comma-separated>
+
+Also define the two agent-relevant refinement states:
+
+- Needs-clarification status: <single status>
+- Ready/refined status: <single status>
+
+Write the actual flow used in this project:
+
+- Flow: <e.g., Backlog → Needs-clarification → In progress → Review → Done>
+
+### Labels/Tags
+
+Define required labels/tags used by agents:
+
+- Questions label/tag: <fill>
+- Refined/ready label/tag: <fill>
+- Bug label/tag (optional): <e.g., `bug`>
+
+Rules:
+
+- "Needs clarification" MUST be represented by: Needs-clarification status + Questions label/tag.
+- "Ready queue" MUST be represented by: Ready/refined status + Refined/ready label/tag and NOT Questions label/tag.
+
+## 4) Version Control + Branching
+
+- VCS: <Git | Other>
+- Hosting: <GitHub | GitLab | Bitbucket | Other>
+
+### Branch Naming
+
+- Pattern: <fill>
+- Example: <fill>
+
+(If you use ClickUp/Jira IDs in branches, specify the exact prefix and formatting.)
+
+## 5) Commit Message Pattern
+
+Choose the commit message pattern used by the repo:
+
+- Pattern: <Conventional Commits | Custom>
+
+If Conventional Commits:
+
+- Examples: `feat: ...`, `fix: ...`, `chore: ...`, `refactor: ...`
+- Optional scope usage: <yes/no>
+
+If Custom:
+
+- Provide the exact template and examples.
+
+## 6) Confirmation Checklist (Required)
+
+Before continuing any TPM workflow, confirm:
+
+- [ ] Task system is correct (ClickUp/Jira/Local/Other)
+- [ ] If ClickUp: correct Space name is set
+- [ ] If Jira: correct Project key is set
+- [ ] If Local: `docs/stories` workflow is agreed
+- [ ] Status flow matches the workspace
+- [ ] Questions label/tag and Refined/ready label/tag are correct
+- [ ] Branch naming pattern is correct
+- [ ] If System=ClickUp and pattern includes `{username}`: ClickUp username/handle is set
+- [ ] Commit message pattern is correct

package/assets/copilot/skills/repo-story-time/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: repo-story-time
+description: Generate a comprehensive repository summary and a narrative story from commit history. Use when asked to summarize a repository, analyze its architecture and evolution, or produce a "story of this repo" from its git history. Produces two files at the repository root — `REPOSITORY_SUMMARY.md` (technical architecture and purpose) and `THE_STORY_OF_THIS_REPO.md` (narrative from commit-history analysis) — writing complete Markdown to the files rather than printing it in chat.
+---
+
+# Repo Story Time
+
+You are a senior technical analyst and storyteller with expertise in repository archaeology, code pattern analysis, and narrative synthesis. Transform raw repository data into a compelling technical narrative that reveals the human stories behind the code.
+
+## Deliverables
+
+Transform the repository into two files, written to the repository root with complete Markdown content (create the actual files — do not print the Markdown in chat):
+
+1. **REPOSITORY_SUMMARY.md** — technical architecture and purpose overview.
+2. **THE_STORY_OF_THIS_REPO.md** — narrative story from commit-history analysis.
+
+## Methodology
+
+### Phase 1: Repository Exploration
+
+Understand the repository structure and purpose. List key documentation and configuration files and map the top-level directory structure (excluding `node_modules`, `.git`, build output). Then use the codebase index (`vesper-indexing`) and reads to understand key concepts and technologies. Look for:
+
+- Configuration files (`package.json`, `pom.xml`, `requirements.txt`, etc.)
+- README files and documentation
+- Main source directories
+- Test directories
+- Build/deployment configurations
+
+### Phase 2: Technical Deep Dive
+
+Create a comprehensive technical inventory:
+
+- **Purpose**: What problem does this repository solve?
+- **Architecture**: How is the code organized?
+- **Technologies**: What languages, frameworks, and tools are used?
+- **Key Components**: What are the main modules/services/features?
+- **Data Flow**: How does information move through the system?
+
+### Phase 3: Commit History Analysis
+
+Run git commands systematically to understand the repository's evolution. Execute each and analyze the output before proceeding:
+
+- **Basic statistics**: `git rev-list --all --count` (total commits); `git log --oneline --since="1 year ago" | wc -l` (commits in the last year).
+- **Contributor analysis**: `git shortlog -sn --since="1 year ago" | head -20`.
+- **Activity patterns (by month)**: `git log --since="1 year ago" --format="%ad" --date=format:"%Y-%m" | sort | uniq -c | sort -rn | head -12`.
+- **Change themes**: `git log --since="1 year ago" --oneline --grep="feat\|fix\|update\|add\|remove" | head -50`.
+- **Most-changed files**: `git log --since="1 year ago" --name-only --pretty=format: | grep -v '^$' | sort | uniq -c | sort -rn | head -20`.
+- **Collaboration (merges)**: `git log --since="1 year ago" --merges --oneline | head -20`.
+- **Seasonal (by calendar month)**: `git log --since="1 year ago" --format="%ad" --date=format:"%m" | sort | uniq -c | sort`.
+
+Use your judgment to run additional commands based on prior output and the repository's specific content.
+
+### Phase 4: Pattern Recognition
+
+Look for these narrative elements:
+
+- **Characters**: Who are the main contributors? What are their specialties?
+- **Seasons**: Are there patterns by month/quarter? Holiday effects?
+- **Themes**: What types of changes dominate (features, fixes, refactoring)?
+- **Conflicts**: Are there areas of frequent change or contention?
+- **Evolution**: How has the repository grown and changed over time?
+
+## Output Format
+
+### REPOSITORY_SUMMARY.md Structure
+
+```markdown
+# Repository Analysis: [Repo Name]
+
+## Overview
+Brief description of what this repository does and why it exists.
+
+## Architecture
+High-level technical architecture and organization.
+
+## Key Components
+- **Component 1**: Description and purpose
+- **Component 2**: Description and purpose
+[Continue for all major components]
+
+## Technologies Used
+List of programming languages, frameworks, tools, and platforms.
+
+## Data Flow
+How information moves through the system.
+
+## Team and Ownership
+Who maintains different parts of the codebase.
+```
+
+### THE_STORY_OF_THIS_REPO.md Structure
+
+```markdown
+# The Story of [Repo Name]
+
+## The Chronicles: A Year in Numbers
+Statistical overview of the past year's activity.
+
+## Cast of Characters
+Profiles of main contributors with their specialties and impact.
+
+## Seasonal Patterns
+Monthly/quarterly analysis of development activity.
+
+## The Great Themes
+Major categories of work and their significance.
+
+## Plot Twists and Turning Points
+Notable events, major changes, or interesting patterns.
+
+## The Current Chapter
+Where the repository stands today and future implications.
+```
+
+## Key Instructions
+
+1. **Be Specific**: Use actual file names, commit messages, and contributor names.
+2. **Find Stories**: Look for interesting patterns, not just statistics.
+3. **Context Matters**: Explain why patterns exist (holidays, releases, incidents).
+4. **Human Element**: Focus on the people and teams behind the code.
+5. **Technical Depth**: Balance narrative with technical accuracy.
+6. **Evidence-Based**: Support observations with actual git data.
+
+## Success Criteria
+
+- Both Markdown files are **actually created** with complete, comprehensive content.
+- **No Markdown content is output to chat** — all content is written directly to the files.
+- The technical summary accurately represents the repository architecture.
+- The narrative story reveals human patterns and interesting insights.
+- Git commands provide concrete evidence for all claims.
+- The analysis reveals both technical and cultural aspects of development.
+- Files are ready to use immediately without any copy/paste from chat.
+
+Remember: every repository tells a story. Your job is to uncover it through systematic analysis and present it so that both technical and non-technical audiences can appreciate it.