@mthanh/vespercli 1.8.0 → 2.0.1

package/assets/CATALOG.md

@@ -2,10 +2,20 @@
 
 Fresh, source-of-truth catalog for team assembly.
 
+This index documents the **canonical authored trees** — `assets/claude/` (the core plugin:
+package agents + skills), `assets/claude/packs/<pack>/` (the stack packs, one plugin each — see
+**Packs** below) and `assets/claude-committed/` (the committed orchestrator persona +
+user-invoked maintenance skills). These are the only hand-authored asset sources.
+
+The Copilot-format catalog under `assets/copilot/` is **generated output**, produced
+from these trees by `scripts/generate-claude-assets.js`. Never hand-edit it, and never
+list it here — it carries no authored content of its own.
+
 Format:
 
-- **Name/Id**: the canonical identifier (typically filename stem or skill `name`)
-- **Path**: relative path from `assets/` — the CLI uses this to locate and copy the asset
+- **Name/Id**: the canonical identifier (agent frontmatter `name`, or the skill folder name)
+- **Path**: relative path from `assets/` to the **authored** source
+- **Pack**: `core` (always enabled) or the pack the asset ships in (enabled per project)
 - **Description**: short, human-readable summary
 - **Pick when**: single-line criteria for selecting the item into a team/workflow
 
@@ -14,562 +24,734 @@ Format:
 
 ---
 
-## Core Agents
-
-Core agents are foundational to Vesper's workflow and are installed by default.
-
-### code-planner (Code Planner Agent)
+## Orchestrator (Committed)
 
-- Path: `core/agents/code-planner.agent.md`
-- Description: Task planner for creating actionable implementation plans.
-- Pick when: Need an implementation plan/checklist before coding; task has multiple steps/dependencies/risk; want consistent planning artifacts.
+The forced main-thread persona. Committed project-level (not a package agent) so it
+resolves in every session, including cloud/remote ones where a plugin does not load.
+It is the **only** pickable agent; every package agent below is a hidden specialist.
 
-### code-reviewer (Code Reviewer Agent)
+### vesper-orchestrator
 
-- Path: `core/agents/code-reviewer.agent.md`
-- Description: Expert reviewer for code quality, standards compliance, and implementation verification.
-- Pick when: Need strict review vs plans/standards before declaring done; suspect edge cases/regressions; need a second opinion on security/performance.
+- Path: `claude-committed/agents/vesper-orchestrator.md`
+- Description: Vesper super-orchestrator — the forced main-thread persona for a Vesper-managed Claude Code project. Routes every request to the specialist team per the always-on orchestrator playbook and team roster in `.claude/rules/`…
+- Pick when: Always — it is the entry point for a Vesper-managed workspace; never delegate to it.
 
-### feature-wrap-document (Feature Wrap and Retrospective Agent)
-
-- Path: `core/agents/feature-wrap-document.agent.md`
-- Description: Knowledge curator that captures implementation patterns and updates documentation, skills, and instructions.
-- Pick when: Task is complete and want durable learnings recorded; need patterns/decisions captured in instructions/skills/docs; want knowledge from divergences and workarounds preserved.
-
-### history-logger (History Logger)
-
-- Path: `core/agents/history-logger.agent.md`
-- Description: Standardized scribe for the history log; appends accurate, timestamped status updates.
-- Pick when: Need consistent chronological progress logging; want a single source of truth for "what happened when"; want less ambiguity during longer work.
-
-### principal-software-engineer (Principal Software Engineer Agent)
+---
 
-- Path: `core/agents/principal-software-engineer.agent.md`
-- Description: Principal-level engineering guidance focused on excellence, leadership, and pragmatic implementation.
-- Pick when: Work is complex/high-risk and needs senior technical judgment; need architecture trade-offs for long-term maintainability; want a sanity-check before implementation.
+## Packs
 
-### se-system-architecture-reviewer (SE: Architect)
+The catalog is a **core** plugin (`vesper`, `assets/claude/`) plus stack **packs** — separate
+plugins in the same marketplace, each at `assets/claude/packs/<pack>/` with its own
+`.claude-plugin/plugin.json` (`vesper-<pack>`), `agents/` and `skills/`. Core is always enabled;
+a pack is enabled **per project** when the Team Roster names one of its assets (`vespercli packs
+sync`, run by `init`/`update`; `vespercli packs enable|disable <pack>` by hand; `vespercli packs`
+lists them). Delegation names: core `vesper:<name>`, packed `vesper-<pack>:<name>`; skills
+`/vesper:<name>` and `/vesper-<pack>:<name>`. On Copilot a pack is one `chat.*Locations` entry per
+`assets/copilot/packs/<pack>/{agents,skills}` folder. Every pack also carries a byte-identical
+copy of the shared `agent-fundamentals` skill (each agent preloads it by bare name; kept in sync
+by the generator). Every entry below names its pack (`Pack:`); `assets/manifest.json` carries the
+same mapping (`assetPacks`) for the CLI.
 
-- Path: `core/agents/se-system-architecture-reviewer.agent.md`
-- Description: Architecture review specialist (Well-Architected frameworks, scalability, AI/distributed systems).
-- Pick when: Need an architecture review before committing to a design; making scalability/reliability/security trade-offs; want design validation + risk identification.
+### backend
 
-### se-technical-writer (SE: Tech Writer)
+- Plugin: `vesper-backend` (source `./packs/backend`)
+- Description: Node.js/Express, Firebase, NestJS, databases, auth and DevOps specialists and skills.
+- Agents: `firebase-developer`, `nodejs-express-developer`
+- Skills: `backend-development`, `better-auth`, `databases`, `devops`, `nestjs` (+ the shared `agent-fundamentals` copy)
 
-- Path: `core/agents/se-technical-writer.agent.md`
-- Description: Technical writing specialist for developer documentation, tutorials, and educational content.
-- Pick when: Need high-quality technical docs aimed at developers; want clear structure (how-to/reference/explanation); need docs aligned with the implementation.
+### docs
 
-### skill-creator (Skill Creator Agent)
+- Plugin: `vesper-docs` (source `./packs/docs`)
+- Description: Document processing (docx/pptx/pdf/xlsx) and multimodal (Gemini) skills.
+- Agents: —
+- Skills: `ai-multimodal`, `document-skills` (+ the shared `agent-fundamentals` copy)
 
-- Path: `core/agents/skill-creator.agent.md`
-- Description: Creates agent skills by analyzing codebase and user requirements.
-- Pick when: Need to add a new skill under `assets/skills/`; want consistent skill structure (manifest/references/usage); want actionable triggers/workflows/examples.
+### frontend
 
-### task-researcher (Task Researcher Specialist Agent)
+- Plugin: `vesper-frontend` (source `./packs/frontend`)
+- Description: React, Next.js, Tailwind and Jest/RTL specialists and skills.
+- Agents: `expert-nextjs-developer`, `expert-react-frontend-engineer`, `jest-react-component-analyzer`, `jest-react-scenario-scanner`, `jest-react-test-generator`, `jest-react-test-planner`, `jest-react-test-runner`
+- Skills: `aesthetic`, `frontend-design`, `nextjs`, `nextjs-tailwind`, `premium-frontend-ui`, `react-mui-tanstack`, `reactjs`, `tailwind-shadcn`, `tailwind-v4-vite`, `vercel-react-best-practices`, `web-design-guidelines`, `web-frameworks` (+ the shared `agent-fundamentals` copy)
 
-- Path: `core/agents/task-researcher.agent.md`
-- Description: Task research specialist for comprehensive project analysis.
-- Pick when: Need evidence-gathering before planning/implementation; need repo structure analysis + relevant docs/examples; want assumptions minimized and decisions grounded.
+### integrations
 
-### technical-product-manager (Technical Product Manager)
+- Plugin: `vesper-integrations` (source `./packs/integrations`)
+- Description: ClickUp task-board specialist, the GitLab MR guardrails skill, and the third-party GitLab CI skills (`gitlab-ci-skill`, `github-actions-to-gitlab-ci` — MIT, GitLab Inc.; each with an `UPSTREAM.json` beside its `SKILL.md`, refreshed only by `npm run vendor:sync`).
+- Agents: `clickup-agent`
+- Skills: `github-actions-to-gitlab-ci`, `gitlab-ci-skill`, `gitlab-guardrails` (+ the shared `agent-fundamentals` copy)
 
-- Path: `core/agents/technical-product-manager.agent.md`
-- Description: Technical Product Manager that refines backlogs and orchestrates delivery.
-- Pick when: Need backlog refinement/scoping/prioritization; need requirements translated into acceptance criteria; want delivery coordination across engineering roles.
+### playwright
 
-### vision-analyst (Vision Analyst)
+- Plugin: `vesper-playwright` (source `./packs/playwright`)
+- Description: Playwright end-to-end testing specialists and skills.
+- Agents: `playwright-component-analyzer`, `playwright-scenario-scanner`, `playwright-test-generator`, `playwright-test-planner`, `playwright-tester`
+- Skills: `chrome-devtools`, `playwright-generate-test`, `playwright-typescript` (+ the shared `agent-fundamentals` copy)
 
-- Path: `core/agents/vision-analyst.agent.md`
-- Description: Analyzes images, screenshots, UI mockups, diagrams, charts, and visual assets — provides structured observations, insights, and recommendations without modifying files.
-- Pick when: Need visual analysis of screenshots, UI mockups, or diagrams; want structured feedback on design/layout/accessibility; need image interpretation for architecture diagrams or charts.
+### polyglot
 
-### vesper (Vesper)
+- Plugin: `vesper-polyglot` (source `./packs/polyglot`)
+- Description: Java, Flutter and Google ADK (Python) skills.
+- Agents: —
+- Skills: `flutter`, `google-adk-python`, `java` (+ the shared `agent-fundamentals` copy)
 
-- Path: `core/agents/vesper.agent.md`
-- Description: Super Orchestrator that manages workspace setup and delegates work to specialist agents.
-- Pick when: Need end-to-end orchestration of feature development; want automatic agent selection and workflow management; starting a new workspace or complex multi-step task.
+### styles
 
-### workspace-learner (Workspace Learner)
-
-- Path: `core/agents/workspace-learner.agent.md`
-- Description: Deep codebase analyst that audits stack/architecture and recommends team composition.
-- Pick when: Repo is unfamiliar and needs an onboarding-level readout; need to choose the right agents/skills for the stack; want risks and conventions identified early.
+- Plugin: `vesper-styles` (source `./packs/styles`)
+- Description: Opt-in output styles — the third-party `i-have-adhd` output style and `ponytail` decision ladder (MIT; `UPSTREAM.json` beside each). Never enabled by the roster sync: `vespercli packs enable styles` is the consent, and it also writes a ~10-line Vesper-authored always-on pointer rule (`.claude/rules/vesper-styles.md` / `.vesper/instructions/vesper-styles.instructions.md`) that loads both skills at session start; `packs disable styles` removes it.
+- Agents: —
+- Skills: `i-have-adhd`, `ponytail` (+ the shared `agent-fundamentals` copy)
 
 ---
+## Agents
 
-## Core Skills
-
-Core skills provide fundamental capabilities and are installed by default alongside core agents.
-
-### agent-fundamentals (Agent Fundamentals)
-
-- Path: `core/skills/agent-fundamentals/SKILL.md`
-- Description: Universal operating rules for all Vesper ecosystem agents — codebase query protocol, terminal discipline, tool usage patterns, and response standards.
-- Pick when: Any agent needs to search code, run terminal commands, perform file operations, or produce output. This is the baseline skill every Vesper agent should follow.
+Specialist subagents (`assets/claude/agents/<name>.md`). Delegation targets only —
+the generated Copilot twins are all emitted `user-invocable: false`.
 
-### mcp-memory (MCP Memory)
+### clickup-agent
 
-- Path: `core/skills/mcp-memory/SKILL.md`
-- Description: Persistent knowledge graph memory using @modelcontextprotocol/server-memory. Replaces flat memory.instructions.md with structured entities, relations, and observations for cross-session context.
-- Pick when: Need persistent memory across sessions; want structured learning storage; need to recall preferences/patterns/insights; using multi-agent workflows that need context handoffs.
+- Path: `claude/packs/integrations/agents/clickup-agent.md`
+- Pack: integrations (`vesper-integrations`)
+- Description: ClickUp specialist that handles all ClickUp API operations with proper multi-level fetching.
+- Pick when: Task requires ClickUp read/write (spaces/lists/tasks/comments); need correct hierarchical fetching (space → folder → list → task); want a single owner for ClickUp API correctness.
 
----
+### code-planner
 
-## Agents
+- Path: `claude/agents/code-planner.md`
+- Pack: core
+- Description: Task planner for creating actionable implementation plans.
+- Pick when: Need an implementation plan/checklist before coding; task has multiple steps/dependencies/risk; want consistent planning artifacts.
 
-### clickup-agent (ClickUp Agent)
+### code-reviewer
 
-- Path: `agents/clickup-agent/clickup-agent.agent.md`
-- Description: ClickUp specialist that handles all ClickUp API operations with proper multi-level fetching.
-- Pick when: Task requires ClickUp read/write (spaces/lists/tasks/comments); need correct hierarchical fetching (space → folder → list → task); want a single owner for ClickUp API correctness.
+- Path: `claude/agents/code-reviewer.md`
+- Pack: core
+- Description: Expert reviewer for code quality, standards compliance, and implementation verification.
+- Pick when: Need strict review vs plans/standards before declaring done; suspect edge cases/regressions; need a second opinion on security/performance.
 
-### code-tester (Code Tester Agent)
+### code-tester
 
-- Path: `agents/code-tester/code-tester.agent.md`
+- Path: `claude/agents/code-tester.md`
+- Pack: core
 - Description: Expert quality assurance engineer for code testing and validation.
 - Pick when: Need targeted test execution and validation evidence; changing behavior and need regression protection; need help interpreting failures and finding root cause.
 
-### copywriter (Document Copywriter Agent)
+### context7
+
+- Path: `claude/agents/context7.md`
+- Pack: core
+- Description: Expert in latest library versions, best practices, and correct syntax using up-to-date documentation.
+- Pick when: Need verified, up-to-date API docs for any library/framework; want version-specific accuracy over training data; need upgrade guidance and migration analysis.
+
+### copywriter
 
-- Path: `agents/copywriter/copywriter.agent.md`
+- Path: `claude/agents/copywriter.md`
+- Pack: core
 - Description: Writes clear, high-quality user-facing content (release notes, changelogs, onboarding, error messages, announcements).
 - Pick when: Deliverable is user-facing writing; need tone/clarity/structure; want consistent, professional copy across surfaces.
 
-### expert-nextjs-developer (NextJS Developer Agent)
+### expert-nextjs-developer
 
-- Path: `agents/expert-nextjs-developer/expert-nextjs-developer.agent.md`
+- Path: `claude/packs/frontend/agents/expert-nextjs-developer.md`
+- Pack: frontend (`vesper-frontend`)
 - Description: Expert Next.js developer (App Router, Server Components, modern React patterns with TypeScript).
 - Pick when: Repo is Next.js App Router/RSC; need caching/streaming/RSC-correct implementation; want performance-aware Next.js patterns.
 
-### expert-react-frontend-engineer (Expert React Frontend Engineer)
+### expert-react-frontend-engineer
 
-- Path: `agents/expert-react-frontend-engineer/expert-react-frontend-engineer.agent.md`
+- Path: `claude/packs/frontend/agents/expert-react-frontend-engineer.md`
+- Pack: frontend (`vesper-frontend`)
 - Description: Expert React frontend engineer focused on modern hooks, TypeScript, and performance.
 - Pick when: Task is React component/UI work; need TypeScript-first patterns + performance discipline; want robust state/effects and predictable rendering.
 
+### feature-wrap-document
+
+- Path: `claude/agents/feature-wrap-document.md`
+- Pack: core
+- Description: Knowledge curator that captures implementation patterns and updates documentation, skills, and instructions.
+- Pick when: Task is complete and want durable learnings recorded; need patterns/decisions captured in instructions/skills/docs; want knowledge from divergences and workarounds preserved.
+
+### firebase-developer
+
+- Path: `claude/packs/backend/agents/firebase-developer.md`
+- Pack: backend (`vesper-backend`)
+- Description: Expert Firebase developer (Firestore, Authentication, Cloud Functions, Hosting, App Hosting, Data Connect, Security Rules, full ecosystem).
+- Pick when: Building on Firebase (Firestore, Auth, Functions, Storage); need Security Rules + data modeling guidance; want Firebase best practices and cost-conscious patterns.
+
 ### janitor
 
-- Path: `agents/janitor/janitor.agent.md`
+- Path: `claude/agents/janitor.md`
+- Pack: core
 - Description: Performs janitorial tasks including cleanup, simplification, and tech debt remediation.
 - Pick when: Need refactoring/cleanup without adding features; want less complexity/dead code/inconsistency; improving hygiene for future work.
 
+### jest-react-component-analyzer
+
+- Path: `claude/packs/frontend/agents/jest-react-component-analyzer.md`
+- Pack: frontend (`vesper-frontend`)
+- Description: Deep-analyzes React components, hooks, and utilities for testability, coverage gaps, and test recommendations.
+- Pick when: Building a Jest + RTL suite; want testability gaps and coverage assessment; need recommendations before writing tests.
+
+### jest-react-scenario-scanner
+
+- Path: `claude/packs/frontend/agents/jest-react-scenario-scanner.md`
+- Pack: frontend (`vesper-frontend`)
+- Description: Scans codebase for React components, hooks, and utilities to create/update a test scenarios inventory with coverage status.
+- Pick when: Need an inventory of components/hooks to test; want to avoid duplicating existing tests; want scenarios grounded in actual codebase structure.
+
+### jest-react-test-generator
+
+- Path: `claude/packs/frontend/agents/jest-react-test-generator.md`
+- Pack: frontend (`vesper-frontend`)
+- Description: Implements Jest + React Testing Library tests following research and plans from planner agents.
+- Pick when: Have test plans ready and want tests implemented; need tests matching project conventions; want consistent test structure with RTL best practices.
+
+### jest-react-test-planner
+
+- Path: `claude/packs/frontend/agents/jest-react-test-planner.md`
+- Pack: frontend (`vesper-frontend`)
+- Description: Research and planning agent for Jest + RTL tests (analyzes components, identifies cases, creates detailed plans).
+- Pick when: Need a thorough test plan before generating tests; want coverage for happy paths + edge cases; need guidance on mocking/test data/fixtures.
+
+### jest-react-test-runner
+
+- Path: `claude/packs/frontend/agents/jest-react-test-runner.md`
+- Pack: frontend (`vesper-frontend`)
+- Description: Executes Jest + RTL tests, diagnoses failures, fixes broken tests, and iterates until all tests pass.
+- Pick when: Need to run and debug Jest test failures; want automated fix-and-retry cycles; need test stability improvements.
+
 ### modernization
 
-- Path: `agents/modernization/modernization.agent.md`
+- Path: `claude/agents/modernization.md`
+- Pack: core
 - Description: Human-in-the-loop modernization assistant for analyzing, documenting, and planning project modernization.
 - Pick when: Upgrading frameworks/libraries or migrating architecture; need a modernization plan with risks/sequence; want "current state → target state" recommendations.
 
-### playwright-component-analyzer (Playwright: Component Analyzer)
+### nodejs-express-developer
 
-- Path: `agents/playwright-component-analyzer/playwright-component-analyzer.agent.md`
+- Path: `claude/packs/backend/agents/nodejs-express-developer.md`
+- Pack: backend (`vesper-backend`)
+- Description: Expert Express.js developer (REST APIs, middleware patterns, authentication, database integration, production-ready server architecture).
+- Pick when: Building Express.js APIs or middleware; need auth/validation/error-handling patterns; want production-hardened server architecture with TypeScript.
+
+### playwright-component-analyzer
+
+- Path: `claude/packs/playwright/agents/playwright-component-analyzer.md`
+- Pack: playwright (`vesper-playwright`)
 - Description: Analyzes React components for testability, coverage gaps, and test recommendations.
 - Pick when: Building a Playwright suite; want selectors/test hooks + testability gaps identified; need recommendations before writing tests.
 
-### playwright-scenario-scanner (Playwright: Scenario Scanner)
+### playwright-scenario-scanner
 
-- Path: `agents/playwright-scenario-scanner/playwright-scenario-scanner.agent.md`
+- Path: `claude/packs/playwright/agents/playwright-scenario-scanner.md`
+- Pack: playwright (`vesper-playwright`)
 - Description: Scans codebase for routes, components, and existing tests to create/update test-scenarios.md.
 - Pick when: Need an inventory of UI routes/features to test; want to avoid duplicating existing tests; want scenarios grounded in actual app structure.
 
-### playwright-test-generator (Playwright: Test Generator)
+### playwright-test-generator
 
-- Path: `agents/playwright-test-generator/playwright-test-generator.agent.md`
+- Path: `claude/packs/playwright/agents/playwright-test-generator.md`
+- Pack: playwright (`vesper-playwright`)
 - Description: Implements Playwright tests following research and plans from Playwright Test Planner agents.
 - Pick when: Have scenarios/plans and want tests implemented; need tests matching conventions/tooling; want consistent test structure and assertions.
 
-### playwright-test-planner (Playwright: Test Planner)
+### playwright-test-planner
 
-- Path: `agents/playwright-test-planner/playwright-test-planner.agent.md`
+- Path: `claude/packs/playwright/agents/playwright-test-planner.md`
+- Pack: playwright (`vesper-playwright`)
 - Description: Research and planning agent for Playwright tests (analyzes components, identifies cases, creates plans).
 - Pick when: Need a thorough test plan before generating tests; want coverage for happy paths + edge cases + NFRs; need guidance on fixtures/mocking/test data.
 
-### playwright-tester (Playwright Tester Mode)
+### playwright-tester
 
-- Path: `agents/playwright-tester/playwright-tester.agent.md`
+- Path: `claude/packs/playwright/agents/playwright-tester.md`
+- Pack: playwright (`vesper-playwright`)
 - Description: Testing mode for Playwright tests.
 - Pick when: Want help running/debugging Playwright tests locally/CI; need failure triage + stability improvements; want validation evidence before merging.
 
-### context7 (Context7-Expert)
-
-- Path: `agents/context7/context7.agent.md`
-- Description: Expert in latest library versions, best practices, and correct syntax using up-to-date documentation.
-- Pick when: Need verified, up-to-date API docs for any library/framework; want version-specific accuracy over training data; need upgrade guidance and migration analysis.
-
-### firebase-developer (Firebase Developer Agent)
+### principal-software-engineer
 
-- Path: `agents/firebase-developer/firebase-developer.agent.md`
-- Description: Expert Firebase developer (Firestore, Authentication, Cloud Functions, Hosting, App Hosting, Data Connect, Security Rules, full ecosystem).
-- Pick when: Building on Firebase (Firestore, Auth, Functions, Storage); need Security Rules + data modeling guidance; want Firebase best practices and cost-conscious patterns.
+- Path: `claude/agents/principal-software-engineer.md`
+- Pack: core
+- Description: Principal-level engineering guidance focused on excellence, leadership, and pragmatic implementation.
+- Pick when: Work is complex/high-risk and needs senior technical judgment; need architecture trade-offs for long-term maintainability; want a sanity-check before implementation.
 
-### jest-react-component-analyzer (Jest React: Component Analyzer)
+### refine-issue
 
-- Path: `agents/jest-react-component-analyzer/jest-react-component-analyzer.agent.md`
-- Description: Deep-analyzes React components, hooks, and utilities for testability, coverage gaps, and test recommendations.
-- Pick when: Building a Jest + RTL suite; want testability gaps and coverage assessment; need recommendations before writing tests.
+- Path: `claude/agents/refine-issue.md`
+- Pack: core
+- Description: Refines requirements with acceptance criteria, technical considerations, edge cases, and NFRs.
+- Pick when: Request is ambiguous and needs a crisp definition of done; need edge cases + NFRs captured up front; want to reduce rework by tightening scope.
 
-### jest-react-scenario-scanner (Jest React: Scenario Scanner)
+### se-system-architecture-reviewer
 
-- Path: `agents/jest-react-scenario-scanner/jest-react-scenario-scanner.agent.md`
-- Description: Scans codebase for React components, hooks, and utilities to create/update a test scenarios inventory with coverage status.
-- Pick when: Need an inventory of components/hooks to test; want to avoid duplicating existing tests; want scenarios grounded in actual codebase structure.
+- Path: `claude/agents/se-system-architecture-reviewer.md`
+- Pack: core
+- Description: Architecture review specialist (Well-Architected frameworks, scalability, AI/distributed systems).
+- Pick when: Need an architecture review before committing to a design; making scalability/reliability/security trade-offs; want design validation + risk identification.
 
-### jest-react-test-generator (Jest React: Test Generator)
+### se-technical-writer
 
-- Path: `agents/jest-react-test-generator/jest-react-test-generator.agent.md`
-- Description: Implements Jest + React Testing Library tests following research and plans from planner agents.
-- Pick when: Have test plans ready and want tests implemented; need tests matching project conventions; want consistent test structure with RTL best practices.
+- Path: `claude/agents/se-technical-writer.md`
+- Pack: core
+- Description: Technical writing specialist for developer documentation, tutorials, and educational content.
+- Pick when: Need high-quality technical docs aimed at developers; want clear structure (how-to/reference/explanation); need docs aligned with the implementation.
 
-### jest-react-test-planner (Jest React: Test Planner)
+### skill-creator
 
-- Path: `agents/jest-react-test-planner/jest-react-test-planner.agent.md`
-- Description: Research and planning agent for Jest + RTL tests (analyzes components, identifies cases, creates detailed plans).
-- Pick when: Need a thorough test plan before generating tests; want coverage for happy paths + edge cases; need guidance on mocking/test data/fixtures.
+- Path: `claude/agents/skill-creator.md`
+- Pack: core
+- Description: Creates agent skills by analyzing codebase and user requirements.
+- Pick when: Need to add a new skill under `assets/claude/skills/`; want consistent skill structure (manifest/references/usage); want actionable triggers/workflows/examples.
 
-### jest-react-test-runner (Jest React: Test Runner)
+### task-researcher
 
-- Path: `agents/jest-react-test-runner/jest-react-test-runner.agent.md`
-- Description: Executes Jest + RTL tests, diagnoses failures, fixes broken tests, and iterates until all tests pass.
-- Pick when: Need to run and debug Jest test failures; want automated fix-and-retry cycles; need test stability improvements.
+- Path: `claude/agents/task-researcher.md`
+- Pack: core
+- Description: Task research specialist for comprehensive project analysis.
+- Pick when: Need evidence-gathering before planning/implementation; need repo structure analysis + relevant docs/examples; want assumptions minimized and decisions grounded.
 
-### nodejs-express-developer (Express.js Developer Agent)
+### technical-product-manager
 
-- Path: `agents/nodejs-express-developer/nodejs-express-developer.agent.md`
-- Description: Expert Express.js developer (REST APIs, middleware patterns, authentication, database integration, production-ready server architecture).
-- Pick when: Building Express.js APIs or middleware; need auth/validation/error-handling patterns; want production-hardened server architecture with TypeScript.
+- Path: `claude/agents/technical-product-manager.md`
+- Pack: core
+- Description: Technical Product Manager that refines backlogs and orchestrates delivery.
+- Pick when: Need backlog refinement/scoping/prioritization; need requirements translated into acceptance criteria; want delivery coordination across engineering roles.
 
-### refine-issue (Refine Issue)
+### vision-analyst
 
-- Path: `agents/refine-issue/refine-issue.agent.md`
-- Description: Refines requirements with acceptance criteria, technical considerations, edge cases, and NFRs.
-- Pick when: Request is ambiguous and needs a crisp definition of done; need edge cases + NFRs captured up front; want to reduce rework by tightening scope.
+- Path: `claude/agents/vision-analyst.md`
+- Pack: core
+- Description: Analyzes images, screenshots, UI mockups, diagrams, charts, and visual assets — provides structured observations, insights, and recommendations without modifying files.
+- Pick when: Need visual analysis of screenshots, UI mockups, or diagrams; want structured feedback on design/layout/accessibility; need image interpretation for architecture diagrams or charts.
 
-### vitest (Vitest: Senior Test Engineer)
+### vitest
 
-- Path: `agents/vitest/vitest.agent.md`
+- Path: `claude/agents/vitest.md`
+- Pack: core
 - Description: Senior Vitest engineer — writes, debugs, and fixes Vitest tests for any TypeScript/JavaScript project with deep knowledge of v4 APIs, mocking, coverage, and performance.
 - Pick when: Need Vitest tests written, debugged, or optimized; project uses Vitest v4 with TypeScript/JavaScript; want expert mocking, coverage, snapshot, or browser-mode testing.
 
+### workspace-learner
+
+- Path: `claude/agents/workspace-learner.md`
+- Pack: core
+- Description: Deep codebase analyst that audits stack/architecture and recommends team composition.
+- Pick when: Repo is unfamiliar and needs an onboarding-level readout; need to choose the right agents/skills for the stack; want risks and conventions identified early.
+
 ---
 
 ## Skills
 
+Package skills (`assets/claude/skills/<name>/`). Model-invocable: loaded by relevance
+to the task at hand. A skill carrying `copilot-apply-to:` additionally generates a
+Copilot `.instructions.md` with that glob, in the tier named by its
+`copilot-instructions-tier:` key — `core` (injected for every Copilot project) or
+`extended` (opt-in per project, as in 1.x). Every instruction today is `extended`.
+
 ### aesthetic
 
-- Path: `skills/aesthetic/`
+- Path: `claude/packs/frontend/skills/aesthetic/`
+- Pack: frontend (`vesper-frontend`)
 - Description: Create aesthetically beautiful interfaces following proven design principles.
 - Pick when: Need stronger UI/UX visual hierarchy and design direction; implementing polished UI and want design-system alignment; want micro-interactions and "finish" beyond basic UI.
 
+### agent-fundamentals
+
+- Path: `claude/skills/agent-fundamentals/`
+- Pack: core
+- Description: Universal operating rules for all Vesper ecosystem agents — codebase query protocol, terminal discipline, tool usage patterns, and response standards.
+- Pick when: Any agent needs to search code, run terminal commands, perform file operations, or produce output. This is the baseline skill every Vesper agent should follow.
+
 ### ai-multimodal
 
-- Path: `skills/ai-multimodal/`
+- Path: `claude/packs/docs/skills/ai-multimodal/`
+- Pack: docs (`vesper-docs`)
 - Description: Process and generate multimedia content (audio/image/video/docs) using Google Gemini API.
 - Pick when: Need to analyze or generate images/video/audio; need OCR/transcription/scene analysis/image generation; building multimodal AI features into an app.
 
 ### backend-development
 
-- Path: `skills/backend-development/`
+- Path: `claude/packs/backend/skills/backend-development/`
+- Pack: backend (`vesper-backend`)
 - Description: Production-ready backend development across APIs, auth, databases, testing, security, performance, and operations.
 - Pick when: Designing/implementing backend services (REST/GraphQL/gRPC); need secure auth/rate limiting/OWASP-minded practices; want scalable patterns (caching/microservices) + test strategy.
 
 ### better-auth
 
-- Path: `skills/better-auth/`
+- Path: `claude/packs/backend/skills/better-auth/`
+- Pack: backend (`vesper-backend`)
 - Description: Implement authentication/authorization with Better Auth (email/password, OAuth, 2FA, passkeys, sessions, RBAC).
 - Pick when: Adding auth to a TypeScript app and want a modern solution; need OAuth/MFA/passkeys/WebAuthn; need secure session management and role-based access.
 
 ### chrome-devtools
 
-- Path: `skills/chrome-devtools/`
+- Path: `claude/packs/playwright/skills/chrome-devtools/`
+- Pack: playwright (`vesper-playwright`)
 - Description: Browser automation, debugging, and performance analysis using Puppeteer/Chrome DevTools.
 - Pick when: Need to automate browser interactions for debugging/capture; investigating performance/network/rendering issues; need repeatable scripts for screenshots/workflows.
 
 ### code-review
 
-- Path: `skills/code-review/`
+- Path: `claude/skills/code-review/`
+- Pack: core
 - Description: Practices for receiving feedback, requesting reviews, and verifying before completion.
 - Pick when: About to claim completion and need verification gates; responding to review feedback and need a rigorous approach; want consistent review workflows with evidence.
 
+### create-specification
+
+- Path: `claude/skills/create-specification/`
+- Pack: core
+- Description: Create a new specification file optimized for generative AI consumption.
+- Pick when: Need a crisp, AI-friendly spec for implementation; want a consistent structure for requirements and constraints; starting a feature and need a spec-first artifact.
+
 ### databases
 
-- Path: `skills/databases/`
+- Path: `claude/packs/backend/skills/databases/`
+- Pack: backend (`vesper-backend`)
 - Description: MongoDB and PostgreSQL design, querying, performance, migrations, and operations.
 - Pick when: Designing schemas/indexes/complex queries; need performance tuning and query plan analysis; doing migrations/backups/production DB operations.
 
 ### debugging _(parent)_
 
-- Path: `skills/debugging/`
+- Path: `claude/skills/debugging/`
+- Pack: core
 - Description: Debugging methodology bundle — installs all four sub-skills below.
 - Pick when: Need structured debugging workflows; want defense-in-depth, root-cause tracing, systematic debugging, and verification practices as a set.
-- Sub-skills:
-  - **defense-in-depth** (`skills/debugging/defense-in-depth/`) — Validate at every layer data passes through to make bugs impossible.
-  - **root-cause-tracing** (`skills/debugging/root-cause-tracing/`) — Systematically trace bugs backward through the call stack to find the original trigger.
-  - **systematic-debugging** (`skills/debugging/systematic-debugging/`) — Four-phase debugging framework that ensures root-cause investigation before attempting fixes.
-  - **verification-before-completion** (`skills/debugging/verification-before-completion/`) — Run verification commands and confirm output before claiming success.
+- Sub-skills: `defense-in-depth`, `root-cause-tracing`, `systematic-debugging`, `verification-before-completion`
 
 ### devops
 
-- Path: `skills/devops/`
+- Path: `claude/packs/backend/skills/devops/`
+- Pack: backend (`vesper-backend`)
 - Description: Deploy/manage infrastructure across Cloudflare + Docker + Google Cloud; CI/CD and platform ops.
 - Pick when: Deploying to edge/serverless (Workers, Pages, KV/R2/D1); need containerization or CI/CD pipeline work; need operational guidance (monitoring, rollout strategies).
 
 ### docs-seeker
 
-- Path: `skills/docs-seeker/`
+- Path: `claude/skills/docs-seeker/`
+- Pack: core
 - Description: Internet documentation search using llms.txt, GitHub repositories, and parallel exploration.
 - Pick when: Need up-to-date official docs for a library/framework; need to compare multiple sources quickly; need structured extraction and summarization.
 
+### document
+
+- Path: `claude/skills/document/`
+- Pack: core
+- Description: Diátaxis documentation expert — writes tutorials, how-to guides, reference and explanation as four distinct document types.
+- Pick when: Producing or restructuring developer documentation; need the right Diátaxis type for the reader's goal; want consistent tone, terminology and structure across docs.
+- Note: authored without SKILL.md frontmatter (see Catalog Metadata).
+
 ### document-skills _(parent)_
 
-- Path: `skills/document-skills/`
+- Path: `claude/packs/docs/skills/document-skills/`
+- Pack: docs (`vesper-docs`)
 - Description: Document processing bundle — installs all four sub-skills below.
 - Pick when: Need programmatic document creation/editing across Word, PDF, PowerPoint, and Excel formats.
-- Sub-skills:
-  - **docx** (`skills/document-skills/docx/`) — Create/edit/analyze .docx with formatting preservation, tracked changes, and extraction.
-  - **pdf** (`skills/document-skills/pdf/`) — PDF toolkit for extraction, generation, merging/splitting, and forms.
-  - **pptx** (`skills/document-skills/pptx/`) — Create/edit/analyze .pptx presentations (layouts, notes, content).
-  - **xlsx** (`skills/document-skills/xlsx/`) — Spreadsheet creation/editing/analysis with formulas, formatting, and visualization.
+- Sub-skills: `docx`, `pdf`, `pptx`, `xlsx`
+
+### flutter
+
+- Path: `claude/packs/polyglot/skills/flutter/`
+- Pack: polyglot (`vesper-polyglot`)
+- Description: Best practices for writing Dart and Flutter code, following the official Effective Dart style guide and the Flutter team's app-architecture recommendations.
+- Pick when: Working in a Dart/Flutter codebase; need naming/style, error-handling and asynchrony conventions; want the recommended MVVM layering, state management, DI, data/repository, navigation and testing patterns.
+- Copilot applyTo: `**/*.dart`
 
 ### frontend-design
 
-- Path: `skills/frontend-design/`
+- Path: `claude/packs/frontend/skills/frontend-design/`
+- Pack: frontend (`vesper-frontend`)
 - Description: Build distinctive, production-grade frontend interfaces with high design quality.
 - Pick when: Need UI implementation that's polished and non-generic; building reusable components/pages in React/Next; want design-led decisions baked into the code.
 
-### gitlab-guardrails
+### github-actions-to-gitlab-ci
 
-- Path: `skills/gitlab-guardrails/`
-- Description: Vesper-owned GitLab MR safety policy — blocks the experimental `glab mr create --recover` flag and detects/removes stray `mr.json` recovery files before commit. Self-contained (in force even when the synced GitLab skills are absent).
-- Pick when: Creating/updating/reviewing GitLab merge requests or running any `glab mr` command; want a guardrail against leaking `--recover`/`mr.json` recovery state into the repo; agent role runs `Bash`/`glab`.
+- Path: `claude/packs/integrations/skills/github-actions-to-gitlab-ci/`
+- Pack: integrations (`vesper-integrations`)
+- Description: Third-party (GitLab Inc., MIT; `UPSTREAM.json` beside the `SKILL.md`, refreshed only by `npm run vendor:sync`): migrate, translate or convert GitHub Actions workflows to GitLab CI/CD pipelines — syntax mapping, marketplace-action equivalents, a validator script.
+- Pick when: A workflow under `.github/workflows/` must become a `.gitlab-ci.yml`, or the user compares GitHub Actions with GitLab CI/CD coming from a GitHub background.
 
-### premium-frontend-ui
+### gitlab-ci-skill
 
-- Path: `skills/premium-frontend-ui/`
-- Description: Craft immersive, award-level, high-performance web experiences with advanced motion, premium typography, and architectural craftsmanship (GSAP, Framer Motion, Lenis, SplitType, React Three Fiber).
-- Pick when: Building premium landing/hero/portfolio/marketing sites that must feel "award-winning" or "cinematic"; implementing scroll-driven narratives, parallax, or custom-cursor micro-interactions; need performance- and accessibility-aware heavy animation.
+- Path: `claude/packs/integrations/skills/gitlab-ci-skill/`
+- Pack: integrations (`vesper-integrations`)
+- Description: Third-party (GitLab Inc., MIT; `UPSTREAM.json` beside the `SKILL.md`, refreshed only by `npm run vendor:sync`): author, debug or optimise a GitLab CI/CD pipeline — `.gitlab-ci.yml` from scratch, adding jobs, local validation, failing-pipeline debugging, CI/CD Catalog components, image/cache choices.
+- Pick when: Any GitLab CI work — the user mentions GitLab CI, `.gitlab-ci.yml`, pipelines or stages in a non-GitHub context.
 
-### react-mui-tanstack
+### gitlab-guardrails
 
-- Path: `skills/react-mui-tanstack/`
-- Description: React development guidelines for MUI v7 + TanStack Router/Query stack (Suspense, lazy loading, file organization, TypeScript).
-- Pick when: Project uses MUI v7 + TanStack Router/Query; need conventions for Suspense-based data fetching; want consistent file organization and component patterns for that stack.
+- Path: `claude/packs/integrations/skills/gitlab-guardrails/`
+- Pack: integrations (`vesper-integrations`)
+- Description: Vesper-owned GitLab MR safety policy — blocks the experimental `glab mr create --recover` flag and detects/removes stray `mr.json` recovery files before commit. Self-contained (in force even when the third-party GitLab skills are absent).
+- Pick when: Creating/updating/reviewing GitLab merge requests or running any `glab mr` command; want a guardrail against leaking `--recover`/`mr.json` recovery state into the repo; agent role runs `Bash`/`glab`.
 
 ### google-adk-python
 
-- Path: `skills/google-adk-python/`
+- Path: `claude/packs/polyglot/skills/google-adk-python/`
+- Pack: polyglot (`vesper-polyglot`)
 - Description: Build, evaluate, and deploy AI agents using Google ADK (Agent Development Kit) for Python.
 - Pick when: Implementing agents in Python with tools and orchestration; need multi-agent hierarchies or workflow agents (sequential/parallel/loop); deploying to Vertex AI Agent Engine / Cloud Run.
 
+### i-have-adhd
+
+- Path: `claude/packs/styles/skills/i-have-adhd/`
+- Pack: styles (`vesper-styles`)
+- Description: Third-party (Ayoub Ghriss, MIT; `UPSTREAM.json` beside the `SKILL.md`): an output style for a reader with ADHD — lead with the next action, number multi-step work, restate state across turns, suppress tangents, make wins visible. `disable-model-invocation: true` upstream; the pack's pointer rule (written by `vespercli packs enable styles`) applies it on every reply.
+- Pick when: Never by the roster — an opt-in output style the user enables with `vespercli packs enable styles`.
+
+### java
+
+- Path: `claude/packs/polyglot/skills/java/`
+- Pack: polyglot (`vesper-polyglot`)
+- Description: Guidelines for building Java base applications. Use when working with Java files.
+- Pick when: Guidelines for building Java base applications. Use when working with Java files.
+- Copilot applyTo: `**/*.java`
+
 ### mcp-builder
 
-- Path: `skills/mcp-builder/`
+- Path: `claude/skills/mcp-builder/`
+- Pack: core
 - Description: Build high-quality MCP servers (Python FastMCP or Node/TypeScript MCP SDK).
 - Pick when: Exposing tools/resources/prompts via MCP; need correct server design and tool ergonomics; want best practices for robustness and evaluation.
 
+### mcp-memory
+
+- Path: `claude/skills/mcp-memory/`
+- Pack: core
+- Description: Persistent knowledge graph memory using @modelcontextprotocol/server-memory. Replaces flat memory.instructions.md with structured entities, relations, and observations for cross-session context.
+- Pick when: Need persistent memory across sessions; want structured learning storage; need to recall preferences/patterns/insights; using multi-agent workflows that need context handoffs.
+
 ### mermaidjs-v11
 
-- Path: `skills/mermaidjs-v11/`
+- Path: `claude/skills/mermaidjs-v11/`
+- Pack: core
 - Description: Create diagrams with Mermaid.js v11 (flowcharts, sequence, ER, timelines, architecture diagrams).
 - Pick when: Need architecture or workflow diagrams in docs; want consistent diagram syntax with examples; need CLI/integration guidance for rendering.
 
-### problem-solving _(parent)_
+### nestjs
 
-- Path: `skills/problem-solving/`
-- Description: Creative problem-solving bundle — installs all six sub-skills below.
-- Pick when: Stuck on a hard problem; need creative thinking frameworks; want a toolkit of techniques for breaking through design/engineering blocks.
-- Sub-skills:
-  - **meta-pattern-recognition** (`skills/problem-solving/meta-pattern-recognition/`) — Spot patterns appearing in 3+ domains to find universal principles.
-  - **collision-zone-thinking** (`skills/problem-solving/collision-zone-thinking/`) — Force unrelated concepts together to discover emergent properties.
-  - **inversion-exercise** (`skills/problem-solving/inversion-exercise/`) — Flip core assumptions to reveal hidden constraints and alternatives.
-  - **scale-game** (`skills/problem-solving/scale-game/`) — Test at extremes (1000x bigger/smaller, instant/year-long) to reveal fundamentals.
-  - **simplification-cascades** (`skills/problem-solving/simplification-cascades/`) — Find one insight that eliminates multiple components.
-  - **when-stuck** (`skills/problem-solving/when-stuck/`) — Dispatch to the right problem-solving technique based on how you're stuck.
+- Path: `claude/packs/backend/skills/nestjs/`
+- Pack: backend (`vesper-backend`)
+- Description: NestJS development standards and best practices for building scalable Node.js server-side applications
+- Pick when: NestJS development standards and best practices for building scalable Node.js server-side applications
 
-### vercel-react-best-practices
+### nextjs
 
-- Path: `skills/vercel-react-best-practices/`
-- Description: Vercel Engineering guidelines for React/Next.js performance optimization (rules by category and impact).
-- Pick when: Writing/refactoring React or Next.js components/pages; optimizing bundle size/waterfalls/server-client performance; want a prioritized performance checklist.
-
-### sequential-thinking
-
-- Path: `skills/sequential-thinking/`
-- Description: Systematic step-by-step reasoning for multi-stage problems (with revisions/branching).
-- Pick when: Problem is ambiguous with multiple plausible approaches; need careful decomposition and decision tracking; want to reduce errors from premature convergence.
-
-### skill-creator
+- Path: `claude/packs/frontend/skills/nextjs/`
+- Pack: frontend (`vesper-frontend`)
+- Description: NextJS development standards and best practices
+- Pick when: NextJS development standards and best practices
 
-- Path: `skills/skill-creator/`
-- Description: Create or update a skill with specialized knowledge, workflows, and tool integration.
-- Pick when: Want to add or update a skill under `assets/skills/`; need consistent manifests/triggers/workflows; want the skill to be reusable across projects.
+### nextjs-tailwind
 
-### tailwind-shadcn
+- Path: `claude/packs/frontend/skills/nextjs-tailwind/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Next.js + Tailwind development standards and instructions. Use when working with TSX, TypeScript, JSX, JavaScript, or CSS files.
+- Pick when: Next.js + Tailwind development standards and instructions. Use when working with TSX, TypeScript, JSX, JavaScript, or CSS files.
+- Copilot applyTo: `**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css`
 
-- Path: `skills/tailwind-shadcn/`
-- Description: Build accessible UIs with shadcn/ui (Radix UI) + Tailwind CSS — components, theming, dark mode, responsive layouts.
-- Pick when: Project uses Tailwind + shadcn/ui; need accessible component patterns (dialogs, forms, tables); want consistent theming and responsive styling.
+### nodejs-javascript-vitest
 
-### vesper-catalog-editing-safety
+- Path: `claude/skills/nodejs-javascript-vitest/`
+- Pack: core
+- Description: Guidelines for writing Node.js and JavaScript code with Vitest testing
+- Pick when: Guidelines for writing Node.js and JavaScript code with Vitest testing
 
-- Path: `skills/vesper-catalog-editing-safety/`
-- Description: Pre-edit safety checklist for touching Vesper's own asset catalog and provisioning code (`assets/`, `scripts/generate-claude-assets.js`, `src/cli/utils/settings.js`, `src/cli/utils/claude-target.js`).
-- Pick when: Editing any catalog asset (agent/skill/prompt/instruction), the Claude-asset generator, or Copilot/Claude settings-injection code in this repo; need to know the dual asset tree boundary, discovery wiring, or the git-hygiene dual list before making the change.
+### playwright-generate-test
 
-### web-design-guidelines
+- Path: `claude/packs/playwright/skills/playwright-generate-test/`
+- Pack: playwright (`vesper-playwright`)
+- Description: Generate a Playwright test based on a scenario using Playwright MCP.
+- Pick when: Have a scenario and want a Playwright test generated; want to use MCP-backed tooling for generation; need consistent test scaffolding from a prompt.
 
-- Path: `skills/web-design-guidelines/`
-- Description: Review UI code for web interface guidelines compliance (UX/accessibility best practices).
-- Pick when: Auditing UI/UX or accessibility; need a checklist-style review of UI implementation; want actionable improvements for usability.
+### playwright-typescript
 
-### web-frameworks
+- Path: `claude/packs/playwright/skills/playwright-typescript/`
+- Pack: playwright (`vesper-playwright`)
+- Description: Playwright test generation instructions
+- Pick when: Playwright test generation instructions
 
-- Path: `skills/web-frameworks/`
-- Description: Build full-stack web apps with Next.js (App Router/RSC), Turborepo, and RemixIcon.
-- Pick when: Building a Next.js/Turborepo codebase; need server rendering/caching/performance patterns; want best practices for monorepos and icon integration.
+### ponytail
 
----
+- Path: `claude/packs/styles/skills/ponytail/`
+- Pack: styles (`vesper-styles`)
+- Description: Third-party (DietrichGebert, MIT; `UPSTREAM.json` beside the `SKILL.md`; rule text only, no upstream hooks or scripts ship): the "laziest solution that actually works" decision ladder — YAGNI first, stdlib before custom code, platform features before dependencies, one line before fifty; intensity lite/full/ultra. The pack's pointer rule (written by `vespercli packs enable styles`) applies it on every reply.
+- Pick when: Never by the roster — an opt-in coding style the user enables with `vespercli packs enable styles`.
 
-## Core Instructions
+### premium-frontend-ui
 
-Core instructions are part of Vesper's orchestration workflows.
+- Path: `claude/packs/frontend/skills/premium-frontend-ui/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Craft immersive, award-level, high-performance web experiences with advanced motion, premium typography, and architectural craftsmanship (GSAP, Framer Motion, Lenis, SplitType, React Three Fiber).
+- Pick when: Building premium landing/hero/portfolio/marketing sites that must feel "award-winning" or "cinematic"; implementing scroll-driven narratives, parallax, or custom-cursor micro-interactions; need performance- and accessibility-aware heavy animation.
 
-### vesper-implement.instructions
+### problem-solving _(parent)_
 
-- Path: `core/instructions/vesper-implement.instructions.md`
-- Description: Vesper Flow 3 implementation orchestration steps.
-- Pick when: In the "implement" phase with plan/research artifacts ready; need enforcement of prerequisites + missing-artifact checks; want reviewers invoked in the correct order.
+- Path: `claude/skills/problem-solving/`
+- Pack: core
+- Description: Creative problem-solving bundle — installs all six sub-skills below.
+- Pick when: Stuck on a hard problem; need creative thinking frameworks; want a toolkit of techniques for breaking through design/engineering blocks.
+- Sub-skills: `collision-zone-thinking`, `inversion-exercise`, `meta-pattern-recognition`, `scale-game`, `simplification-cascades`, `when-stuck`
 
-### vesper-qa-e2e.instructions
+### project-management
 
-- Path: `core/instructions/vesper-qa-e2e.instructions.md`
-- Description: Vesper Flow 4 QA & E2E testing orchestration steps.
-- Pick when: Implementation is done and need QA/E2E validation; want structured issue logging for QA findings; need consistent go/no-go gates.
+- Path: `claude/skills/project-management/`
+- Pack: core
+- Description: Project-management conventions template — task-management system of record, story/issue workflow, statuses and estimation, filled in per project.
+- Pick when: Need the agreed task board, workflow states and story conventions before refining or tracking work; onboarding the Technical Product Manager to a project's process.
+- Note: authored without SKILL.md frontmatter (see Catalog Metadata).
 
-### vesper-reinit.instructions
+### react-mui-tanstack
 
-- Path: `core/instructions/vesper-reinit.instructions.md`
-- Description: Vesper re-initialization and memory file rules for refreshing workspace setup.
-- Pick when: User requests re-initialization of workspace; need to refresh workspace learning and team roster; want memory file constraints enforced during setup.
+- Path: `claude/packs/frontend/skills/react-mui-tanstack/`
+- Pack: frontend (`vesper-frontend`)
+- Description: React development guidelines for MUI v7 + TanStack Router/Query stack (Suspense, lazy loading, file organization, TypeScript).
+- Pick when: Project uses MUI v7 + TanStack Router/Query; need conventions for Suspense-based data fetching; want consistent file organization and component patterns for that stack.
 
-### vesper-research-plan.instructions
+### reactjs
 
-- Path: `core/instructions/vesper-research-plan.instructions.md`
-- Description: Vesper Flow 2 research & planning orchestration steps.
-- Pick when: Task needs discovery and planning before implementation; want standardized research artifacts; need a reproducible planning workflow.
+- Path: `claude/packs/frontend/skills/reactjs/`
+- Pack: frontend (`vesper-frontend`)
+- Description: ReactJS development standards and best practices. Use when working with JSX, TSX, JavaScript, TypeScript, CSS, or SCSS files.
+- Pick when: ReactJS development standards and best practices. Use when working with JSX, TSX, JavaScript, TypeScript, CSS, or SCSS files.
+- Copilot applyTo: `**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss`
 
----
+### repo-story-time
 
-## Instructions
+- Path: `claude/skills/repo-story-time/`
+- Pack: core
+- Description: Generate a comprehensive repository summary and narrative story from commit history.
+- Pick when: Want a "what happened" narrative for onboarding or review; need a summary of evolution and major decisions; preparing documentation or a project retrospective.
 
-### document.instructions
+### self-explanatory-code-commenting
 
-- Path: `instructions/document/document.instructions.md`
-- Description: Diátaxis Documentation Expert guidance for writing and structuring docs.
-- Pick when: Writing docs and want correct doc type (tutorial/how-to/reference/explanation); need clearer structure and audience alignment; want documentation quality gates.
+- Path: `claude/skills/self-explanatory-code-commenting/`
+- Pack: core
+- Description: Conventions for writing and reviewing code comments: prefer self-explanatory code, comment WHY not WHAT, and avoid obvious, redundant, outdated, dead-code, or decorative comments. Language-agnostic (examples in JavaScript)…
+- Pick when: Conventions for writing and reviewing code comments: prefer self-explanatory code, comment WHY not WHAT, and avoid obvious, redundant, outdated, dead-code, or decorative comments…
+- Copilot applyTo: `**/*.py, **/*.js, **/*.ts, **/*.java, **/*.cs, **/*.cpp, **/*.go, **/*.rb`
 
-### java.instructions
+### sequential-thinking
 
-- Path: `instructions/java/java.instructions.md`
-- Description: Java development instructions and best practices for this workspace.
-- Pick when: Task is Java-based (build tooling/conventions/testing); need idiomatic Java patterns; want consistency across Java changes.
+- Path: `claude/skills/sequential-thinking/`
+- Pack: core
+- Description: Systematic step-by-step reasoning for multi-stage problems (with revisions/branching).
+- Pick when: Problem is ambiguous with multiple plausible approaches; need careful decomposition and decision tracking; want to reduce errors from premature convergence.
 
-### nestjs.instructions
+### skill-creator
 
-- Path: `instructions/nestjs/nestjs.instructions.md`
-- Description: NestJS development best practices.
-- Pick when: Working in a NestJS service; need patterns for modules/providers/controllers; want consistent validation/DI/testing approaches.
+- Path: `claude/skills/skill-creator/`
+- Pack: core
+- Description: Create or update a skill with specialized knowledge, workflows, and tool integration.
+- Pick when: Want to add or update a skill under `assets/claude/skills/`; need consistent manifests/triggers/workflows; want the skill to be reusable across projects.
 
-### nextjs.instructions
+### tailwind-shadcn
 
-- Path: `instructions/nextjs/nextjs.instructions.md`
-- Description: Next.js best practices for LLM-assisted work (2025).
-- Pick when: Implementing in a Next.js codebase; need guardrails around App Router/RSC conventions; want to avoid common Next.js pitfalls.
+- Path: `claude/packs/frontend/skills/tailwind-shadcn/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Build accessible UIs with shadcn/ui (Radix UI) + Tailwind CSS — components, theming, dark mode, responsive layouts.
+- Pick when: Project uses Tailwind + shadcn/ui; need accessible component patterns (dialogs, forms, tables); want consistent theming and responsive styling.
 
-### nextjs-tailwind.instructions
+### tailwind-v4-vite
 
-- Path: `instructions/nextjs-tailwind/nextjs-tailwind.instructions.md`
-- Description: Next.js + Tailwind development instructions.
-- Pick when: Implementing UI in Next.js with Tailwind; need consistent styling conventions and patterns; want accessibility + component composition guardrails.
+- Path: `claude/packs/frontend/skills/tailwind-v4-vite/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin. Use when working with TypeScript, JavaScript, CSS, TSX, or JSX files.
+- Pick when: Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin. Use when working with TypeScript, JavaScript, CSS, TSX, or JSX files.
+- Copilot applyTo: `vite.config.ts, vite.config.js, **/*.css, **/*.tsx, **/*.ts, **/*.jsx, **/*.js`
 
-### nodejs-javascript-vitest.instructions
+### task-implementation
 
-- Path: `instructions/nodejs-javascript-vitest/nodejs-javascript-vitest.instructions.md`
-- Description: Guidelines for writing Node.js and JavaScript code with Vitest testing.
-- Pick when: Writing Node.js/JavaScript with ES2022+ and ESM; need Vitest testing conventions; want consistent coding standards (async/await, functions over classes, no null).
+- Path: `claude/skills/task-implementation/`
+- Pack: core
+- Description: Instructions for implementing task plans with progressive tracking and change record - Brought to you by microsoft/edge-ai. Use when working with task change-record files under .vesper/.tracking/changes/.
+- Pick when: Instructions for implementing task plans with progressive tracking and change record - Brought to you by microsoft/edge-ai…
+- Copilot applyTo: `**/.vesper/.tracking/changes/*.md`
 
-### playwright-typescript.instructions
+### vercel-react-best-practices
 
-- Path: `instructions/playwright-typescript/playwright-typescript.instructions.md`
-- Description: Playwright + TypeScript testing instructions.
-- Pick when: Writing Playwright tests in TypeScript; need conventions for fixtures/selectors/reliability; want tests maintainable and stable.
+- Path: `claude/packs/frontend/skills/vercel-react-best-practices/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Vercel Engineering guidelines for React/Next.js performance optimization (rules by category and impact).
+- Pick when: Writing/refactoring React or Next.js components/pages; optimizing bundle size/waterfalls/server-client performance; want a prioritized performance checklist.
 
-### project-management.instructions
+### vesper-catalog-editing-safety
 
-- Path: `instructions/project-management/project-management.instructions.md`
-- Description: Mandatory project management instructions.
-- Pick when: Need planning cadence/status reporting/delivery hygiene; want consistent task tracking + definition of done; want to reduce scope creep and missed acceptance criteria.
+- Path: `claude/skills/vesper-catalog-editing-safety/`
+- Pack: core
+- Description: Pre-edit safety checklist for touching Vesper's own asset catalog and provisioning code (`assets/`, `scripts/generate-claude-assets.js`, `src/cli/utils/settings.js`, `src/cli/utils/claude-target.js`).
+- Pick when: Editing any catalog asset (agent/skill/prompt/instruction), the Claude-asset generator, or Copilot/Claude settings-injection code in this repo; need to know the dual asset tree boundary, discovery wiring, or the git-hygiene dual list before making the change.
 
-### reactjs.instructions
+### vesper-orchestration
 
-- Path: `instructions/reactjs/reactjs.instructions.md`
-- Description: ReactJS development instructions.
-- Pick when: Implementing React components/hooks; need conventions for state/effects/performance; want consistent React code patterns in this repo.
+- Path: `claude/skills/vesper-orchestration/`
+- Pack: core
+- Description: Detailed step-by-step orchestration pipelines the Vesper super-orchestrator delegates through — research & plan, implementation, QA/E2E testing, re-initialization, plus the bug-fix and skill-creation context overrides.
+- Pick when: Running or resuming a Vesper purpose pipeline; need the per-step delegation prompts, tracking-file naming, output contracts, or the bug-fix overrides the orchestrator playbook defers to.
 
-### self-explanatory-code-commenting.instructions
+### vscode-agent-config
 
-- Path: `instructions/self-explanatory-code-commenting/self-explanatory-code-commenting.instructions.md`
-- Description: Guidance for writing self-explanatory code with minimal comments.
-- Pick when: Refactoring for readability; want to avoid noisy comments and improve naming/structure; need a standard for "when to comment".
+- Path: `claude/skills/vscode-agent-config/`
+- Pack: core
+- Description: Configure VS Code for agentic workflows — terminal/MCP auto-approval, agent request limits, and the chat settings Vesper injects.
+- Pick when: Setting up VS Code for Vesper/Copilot agents; tuning auto-approval for safe terminal commands or MCP tools; debugging why an agent, skill or instruction is not being discovered.
+- Note: authored without SKILL.md frontmatter (see Catalog Metadata).
 
-### tailwind-v4-vite.instructions
+### web-design-guidelines
 
-- Path: `instructions/tailwind-v4-vite/tailwind-v4-vite.instructions.md`
-- Description: Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin.
-- Pick when: Setting up Tailwind CSS v4 in a Vite project; need @tailwindcss/vite plugin configuration; migrating from PostCSS-based Tailwind to v4 CSS-first setup.
+- Path: `claude/packs/frontend/skills/web-design-guidelines/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Review UI code for web interface guidelines compliance (UX/accessibility best practices).
+- Pick when: Auditing UI/UX or accessibility; need a checklist-style review of UI implementation; want actionable improvements for usability.
 
-### task-implementation.instructions
+### web-frameworks
 
-- Path: `instructions/task-implementation/task-implementation.instructions.md`
-- Description: Implementation instructions for executing an approved plan.
-- Pick when: Have an implementation plan and need to execute it safely; want progress tracking/validation/scope control; need consistent implementation artifacts and checkpoints.
+- Path: `claude/packs/frontend/skills/web-frameworks/`
+- Pack: frontend (`vesper-frontend`)
+- Description: Build full-stack web apps with Next.js (App Router/RSC), Turborepo, and RemixIcon.
+- Pick when: Building a Next.js/Turborepo codebase; need server rendering/caching/performance patterns; want best practices for monorepos and icon integration.
 
 ---
 
-## Prompts
+## Maintenance Skills (Committed, User-Invoked)
 
-### create-specification
-
-- Path: `prompts/create-specification/create-specification.prompt.md`
-- Description: Create a new specification file optimized for generative AI consumption.
-- Pick when: Need a crisp, AI-friendly spec for implementation; want a consistent structure for requirements and constraints; starting a feature and need a spec-first artifact.
+Committed skills (`assets/claude-committed/skills/<name>/`) carrying
+`disable-model-invocation: true`. That single key is the discriminator that makes the
+generator emit a Copilot `.prompt.md` (a slash command) instead of a skill — and it is
+only safe because emission is scoped to this tree. Never invoked autonomously.
 
-### memory-update
-
-- Path: `core/prompts/memory-update.prompt.md`
-- Description: Review completed task and update Vesper memory with learnings.
-- Pick when: Task completed and want durable learnings recorded; user corrected decisions or new workspace patterns emerged; want to keep memory focused and non-noisy.
-
-### playwright-generate-test
+### /compact-knowledge
 
-- Path: `prompts/playwright-generate-test/playwright-generate-test.prompt.md`
-- Description: Generate a Playwright test based on a scenario using Playwright MCP.
-- Pick when: Have a scenario and want a Playwright test generated; want to use MCP-backed tooling for generation; need consistent test scaffolding from a prompt.
+- Path: `claude-committed/skills/compact-knowledge/`
+- Description: Use when the user asks to compact / archive persisted Vesper knowledge (completed tracking stories, memory.jsonl), or explicitly runs `/compact-knowledge`…
+- Pick when: User explicitly runs the slash command; never model-selected.
 
-### repo-story-time
+### /reinit
 
-- Path: `prompts/repo-story-time/repo-story-time.prompt.md`
-- Description: Generate a comprehensive repository summary and narrative story from commit history.
-- Pick when: Want a "what happened" narrative for onboarding or review; need a summary of evolution and major decisions; preparing documentation or a project retrospective.
+- Path: `claude-committed/skills/reinit/`
+- Description: Use when the user asks to re-initialize / re-vesperize / refresh the Vesper workspace setup, or explicitly runs `/reinit`. Do NOT invoke autonomously.
+- Pick when: User explicitly runs the slash command; never model-selected.
 
-### revalidate-knowledge
+### /revalidate-knowledge
 
-- Path: `core/prompts/revalidate-knowledge.prompt.md`
+- Path: `claude-committed/skills/revalidate-knowledge/`
 - Description: Revalidate archived Vesper knowledge against the current codebase and re-balance the slim-core/on-demand context split — a heavier, semantic re-validation pass distinct from `/compact-knowledge`'s trim/dedupe.
 - Pick when: The project context feels stale or drifted from the code (staleness signal, not size); want archived knowledge (prioritizing `.unwrapped` entries) re-checked and re-extracted; need the slim core and on-demand context tiers rebalanced. User-invoked only — Vesper suggests it, never auto-runs it.
 
+### /revalidate-team
+
+- Path: `claude-committed/skills/revalidate-team/`
+- Description: Use when the user asks to revalidate the Vesper team roster against the currently installed specialist catalog, or explicitly runs `/revalidate-team`. A roster review, not a full re-init. Do NOT invoke autonomously.
+- Pick when: User explicitly runs the slash command; never model-selected.
+
 ---
 
 ## Catalog Metadata
 
-- **Version**: 1.4.0
-- **Last Updated**: 2026-07-21
+- **Version**: 2.0.0
+- **Last Updated**: 2026-09-28
+- **Authored agents**: 33 (+1 committed orchestrator) — 18 core, 15 in packs
+- **Authored skills**: 50 package + 4 committed maintenance — 20 core, 30 in packs (4 of them third-party, each with an `UPSTREAM.json`)
+- **Packs**: 7 (backend, docs, frontend, integrations, playwright, polyglot, styles — the last opt-in)
+- **Generated output**: `assets/copilot/{agents,skills,prompts,instructions-extended,packs/<pack>/{agents,skills}}` (+ `instructions/`
+  when the core tier is non-empty) — do not hand-edit; regenerate with `node scripts/generate-claude-assets.js`