@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/claude/skills/vesper-orchestration/references/research-plan-pipeline.md

@@ -0,0 +1,214 @@
+# Research & Plan Pipeline (Steps 1-3)
+
+Detailed orchestration steps for the Research & Plan phase of the Implementation purpose pipeline.
+
+## Prerequisites
+
+- ✅ Refined task or user request exists
+- ✅ The orchestrator has chosen a scope tier of **M** or **L** (the playbook's tier table). An **S**
+  change never enters this reference — it goes straight to the S delegation in the playbook
+- Team Roster available in `.claude/rules/vesper-orchestration.md` (the orchestrator handles routing)
+
+**Tier shape**: **M** runs STEP 1 (short) and STEP 2 only. **L** runs STEPs 1-3. The Researcher's
+report is also the tier check — it may raise M to L, never lower a tier (see STEP 1).
+
+## Context Injection (Orchestrator Responsibility)
+
+When calling subagents, the orchestrator appends workspace context:
+
+```
+[WORKSPACE CONTEXT - appended by Vesper]
+- Codebase context: Use vesper-indexing MCP tools (vesper_search, vesper_symbols)
+- Nesting depth: 1
+```
+
+**Codebase Reference Rule**: When building delegation prompts, always frame codebase references as
+**concepts to investigate** ("Investigate lease type definitions and validation patterns"), never as
+file-reading commands ("Read src/types/leaseTypes.ts"). File paths from stories may appear as hints,
+but the subagent decides how to query the codebase — via vesper-indexing, not prescribed reads.
+
+## Orchestration Steps
+
+### File Naming Convention
+
+All output files use the pattern `YYYYMMDD-[slug]-<type>.md` where `[slug]` is a short task
+identifier (3-5 words, kebab-case). When the orchestrator delegates with a `Task slug: [slug]`
+directive, use that exact slug. This isolates artifacts when multiple tasks run in parallel.
+
+### STEP 0: Fetch Task Details (if task reference exists)
+
+- Look up the **Task Agent** in the Team Roster
+- Delegate to the Task Agent:
+
+```
+"Fetch full task details for [task-id].
+Return: description, requirements, acceptance criteria."
+```
+
+Skip this step entirely when Task Management is `Local` or absent — the user's raw input is the
+task context.
+
+### STEP 1: Research (M: short; L: comprehensive)
+
+Delegate to the **Researcher/Analyzer from roster** → fallback `vesper:task-researcher`:
+
+```
+"Research implementation approach for [task].
+
+Task slug: [slug]
+Tier: [M|L] — on M keep the research short: the change is bounded to one surface, ~10 files at most.
+Nesting depth: 1
+Context: [task details from STEP 0]
+
+Memory: Before starting, search_nodes('<task keywords>') for prior research learnings.
+
+Save to: .vesper/.tracking/research/YYYYMMDD-[slug]-research.md
+
+Expectations:
+- Execute comprehensive research using all available tools
+- Evaluate alternatives and guide toward ONE recommended approach
+- Validate research completeness before signaling done
+- Remove non-selected alternatives from the final document
+- The research file is the handoff — the orchestrator records the milestone with `vespercli log note`
+- Tier check: if the change turns out cross-cutting, multi-surface, or in need of a new pattern,
+  end your final message with `Tier: raise to L — <why>` (above the Status line). You may raise the
+  tier, never lower it.
+
+Apply your assigned skills: docs-seeker, sequential-thinking"
+```
+
+**WAIT** for the researcher's final message (`Status: DONE`). If it carries `Tier: raise to L`, the
+orchestrator restarts the pipeline as L (budget and steps of the L row) and logs a
+`vespercli log note … --step tier` row — the research file is reused, not redone.
+
+### STEP 2: Create Implementation Plan
+
+Delegate to the **Planner from roster** → fallback `vesper:code-planner`:
+
+```
+"Create implementation plan based on research.
+
+Task slug: [slug]
+Nesting depth: 1
+Research: .vesper/.tracking/research/YYYYMMDD-[slug]-research.md
+Output directory: .vesper/.tracking/
+
+Memory: search_nodes('planning') for planning-related learnings (the research file above is the task context).
+
+Produce THREE files:
+- plans/YYYYMMDD-[slug]-plan.md (phases, tasks, dependencies)
+- details/YYYYMMDD-[slug]-details.md (full specifications per task)
+- prompts/implement-[slug].prompt.md (implementation prompt with controls)
+
+Validate that the research file exists before planning.
+
+Apply your assigned skills: sequential-thinking, project-management"
+```
+
+**WAIT** for the planner's final message (`Status: DONE`).
+
+### STEP 3: Architect Validation (L only — M skips this step)
+
+Delegate to `vesper:se-system-architecture-reviewer`:
+
+```
+"Validate this implementation plan for [task].
+
+Nesting depth: 1
+
+Review:
+- Research: .vesper/.tracking/research/YYYYMMDD-[slug]-research.md
+- Plan: .vesper/.tracking/plans/YYYYMMDD-[slug]-plan.md
+- Details: .vesper/.tracking/details/YYYYMMDD-[slug]-details.md
+
+Check: feasibility, risks, alignment with architecture, completeness.
+Approve or request specific changes."
+```
+
+**IF the architect requests changes:**
+
+1. Delegate to the **Planner** to revise the plan
+2. Re-validate with the architect
+3. Repeat until approved (subject to the global loop limit in the orchestrator playbook)
+
+## Output Files
+
+All outputs in `.vesper/.tracking/`:
+
+- `research/YYYYMMDD-[slug]-research.md` (from the Researcher)
+- `plans/YYYYMMDD-[slug]-plan.md` (from the Planner, architect approved)
+- `details/YYYYMMDD-[slug]-details.md` (from the Planner)
+- `prompts/implement-[slug]-[track].prompt.md` (from the Planner — one per independent track)
+
+When only one task with one track: `implement-[slug].prompt.md` (simplified).
+
+### Implementation Tracks (Planner Responsibility)
+
+The Planner MUST identify independent implementation tracks and create:
+
+- **One prompt per track** in `prompts/` (e.g., `implement-backend-api.prompt.md`,
+  `implement-frontend-ui.prompt.md`, `implement-db-migration.prompt.md`)
+- Each prompt specifies: target surface/stack, tasks for that track, and any dependencies on other tracks
+- The plan file lists all tracks with their dependency graph
+
+If all tasks are on the same surface → a single prompt `implement-task.prompt.md`.
+
+---
+
+## Bug Fix Overrides (when Purpose = bug fix)
+
+Bug fixes enter the same pipeline. These overrides adjust context passing for bug-specific framing.
+
+### STEP 1 Research — add to the delegate prompt:
+
+```
+"Investigate bug: [description].
+
+Context:
+- Error logs / stack traces: [file path if available]
+- Reproduction steps: [user-provided or inferred]
+- Affected area: [file paths or module if known]
+
+Find root cause. Provide:
+- What is failing
+- Why it is failing
+- Where in the code the issue originates
+- Recommended fix approach
+
+Save to: .vesper/.tracking/research/YYYYMMDD-bugfix-research.md"
+```
+
+### STEP 2 Plan — add scope constraint:
+
+```
+"Requirements:
+- Minimal fix that addresses root cause (not symptoms)
+- Regression test must be part of the plan
+- Do NOT scope beyond what's needed for this fix"
+```
+
+**Output naming**: Use the `bugfix` prefix (e.g., `YYYYMMDD-bugfix-research.md`,
+`YYYYMMDD-bugfix-changes.md`).
+
+---
+
+## Skill Creation Overrides (when task = skill creation)
+
+Skill creation enters the same Implementation pipeline. The Knowledge Codifier
+(`vesper:skill-creator`) is the "Developer" for this task type.
+
+### STEP 1 Research — frame as skills research:
+
+```
+"Research what this skill should cover: [topic/technology].
+
+Context:
+- Existing skills: check the installed catalog skills and the `.vesper/skills/` override home
+
+Find:
+- What patterns exist in the codebase for this domain
+- What knowledge gaps exist that a skill could fill
+- Existing similar skills to avoid duplication
+
+Save to: .vesper/.tracking/research/YYYYMMDD-skill-research.md"
+```

package/assets/claude/skills/vscode-agent-config/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: vscode-agent-config
+description: 'VS Code configuration for agentic workflows — auto-approval of safe terminal commands and MCP tools, folder-to-workspace migration, and troubleshooting agent permission or MCP connection problems. Use when configuring VS Code for Vesper, Copilot, Cline or similar agents.'
+---
+
 # Skill: VS Code Agent Configuration
 
 ## When to Use