@mthanh/vespercli 1.8.0 → 2.0.1

package/assets/claude/packs/frontend/skills/agent-fundamentals/references/terminal-discipline.md

@@ -0,0 +1,94 @@
+# Terminal Discipline — Expanded Rules
+
+Non-negotiable rules for every `Bash` command a subagent executes.
+
+## Timeout Requirements
+
+| Command Type       | Timeout  | Examples                                               |
+| -------------------- | ---------- | ---------------------------------------------------------- |
+| Quick              | 15s      | `ls`, `cat`, `echo`, `which`, `git status`             |
+| Package management | 60s      | `npm install`, `pip install`, `brew install`            |
+| Build              | 120s     | `npm run build`, `tsc`, `esbuild`, `webpack`           |
+| Test               | 300s     | `npm test`, `vitest run`, `pytest`, `playwright test`  |
+| Default            | 30s      | Anything not in the above categories                   |
+
+**Every command gets a timeout. No exceptions.**
+
+## Background Processes
+
+Commands that never terminate must be run with `run_in_background: true`:
+
+- Dev servers: `npm run dev`, `next dev`, `vite dev`
+- Watch modes: `tsc --watch`, `vitest --watch`, `nodemon`
+- Log tailing: `tail -f`, `docker logs -f`
+- Containers: `docker compose up`
+- Any long-running process the subagent doesn't need to wait for
+
+After starting a background process, check its output via the harness's background-task output mechanism rather than blocking on it.
+
+## Output Control
+
+```bash
+# Cap output to prevent context overflow
+command | head -30
+
+# Capture both stdout and stderr
+command 2>&1 | head -30
+
+# Count lines before displaying
+command | wc -l    # check size first, then decide head limit
+
+# Git: always limit
+git log --oneline -20
+git diff --stat
+
+# Grep: files-only when appropriate
+grep -rl "pattern" src/
+```
+
+**Never** let unbounded output flood the context window. If output might exceed 50 lines, pipe through `head`.
+
+## Directory Navigation
+
+```bash
+# ❌ WRONG — breaks permission-prompt matching (matching starts from `cd`)
+cd /some/path && npm run build
+
+# ✅ CORRECT — preserves working directory, approval matches `npm`
+pushd /some/path && npm run build && popd
+
+# ✅ ALSO CORRECT — if already in the right directory
+npm run build
+```
+
+The `cd && command` pattern breaks command-matching for permission prompts because matching starts from `cd`, not the actual command. Always use `pushd`/`popd` for temporary directory changes.
+
+## Runtime Version Guard (Node/nvm)
+
+Projects that pin a Node version via nvm expect every command to run under that version — running under whatever `node` happens to be on PATH can produce misleading build/test failures or silently wrong behavior.
+
+Before running any Node-based command (`npm`, `npx`, `yarn`, `pnpm`, `node`, or project scripts that wrap them):
+
+1. Check the project root for `.nvmrc` or `.node-version`.
+2. If found, chain `nvm use` into the **same** `Bash` call as the actual command — shell state (including nvm's shell function) does not persist between separate tool calls:
+   ```bash
+   nvm use > /dev/null 2>&1; npm test
+   ```
+3. If `nvm` isn't installed, no version file exists, or the switch fails — proceed anyway with whatever `node` is on PATH. **Never block the task on this.**
+
+Do not run `nvm use` as its own command and expect it to carry over to the next one — it won't.
+
+## curl Rules
+
+- Always set `--max-time 5` to prevent hanging on unresponsive hosts
+- Localhost health checks only without explicit user approval
+- Never curl external URLs without user awareness
+
+## Timeout Recovery
+
+When a command times out:
+
+1. **Diagnose first** — `ps aux | grep <process>` to check if it's still running
+2. **Report to user** — Explain what happened and why
+3. **Don't blindly retry** — The same command will likely time out again
+4. **Suggest alternatives** — Smaller scope, different approach, or user intervention

package/assets/claude/packs/frontend/skills/agent-fundamentals/references/tool-usage-patterns.md

@@ -0,0 +1,67 @@
+# Tool Usage Patterns
+
+Comprehensive guide for when to use which tools. Built-in tools trump `Bash` in every case where they're available.
+
+## File Reading
+
+| Scenario                       | Tool             | Notes                                      |
+| --------------------------------- | ------------------ | -------------------------------------------- |
+| Read known file                | `Read`            | Specify `offset`/`limit` to limit token usage |
+| Read file overview             | `Grep`            | Search for key patterns in the file        |
+| Read file existence            | `Glob`            | Glob pattern matching                      |
+| Read directory listing         | `Glob`/`Bash` (`ls`) | Lists immediate children                |
+
+**Anti-patterns:**
+- `cat file.txt` — use `Read`
+- `less file.txt` — blocks terminal, use `Read`
+- `head -n 50 file.txt` — use `Read` with a line range
+- `node -e "console.log(fs.readFileSync(...))"` — never
+
+## Code Search
+
+| Scenario                        | Tool                                          | Notes                                                |
+| ---------------------------------- | ------------------------------------------------- | ---------------------------------------------------- |
+| Primary codebase search         | `mcp__vesper-indexing__vesper_search`          | Full-text, returns snippets with paths + line ranges |
+| Find symbols (functions/classes)| `mcp__vesper-indexing__vesper_symbols`         | Name-based lookup with locations                     |
+| Exact text / regex match        | `Grep`                                          | Fast, supports regex, glob filters                   |
+| Find files by name/glob         | `Glob`                                          | Filename/path patterns only                          |
+
+**Anti-patterns:**
+- `grep -r "pattern" .` — use `Grep`
+- `find . -name "*.ts" -exec grep` — use `Glob` + `Grep`
+- `rg "pattern"` — use `Grep`
+- `tree` / `ls -R` — use `Glob`
+
+## File Writing
+
+| Scenario                   | Tool                     | Notes                                 |
+| ----------------------------- | -------------------------- | ---------------------------------------- |
+| Create new file            | `Write`                   | Creates parent directories            |
+| Edit existing file         | `Edit`                    | Include enough surrounding context to make the match unique |
+| Multiple identical edits   | `Edit` with `replace_all` | Batch identical replacements in one call |
+| Rename / move file         | `Bash` + `mv`             | Only case where terminal is correct   |
+
+**Anti-patterns:**
+- `echo "content" > file.txt` — use `Write`
+- `python -c "open('f','w').write('...')"` — never
+- `node -e "fs.writeFileSync(...)"` — never
+- `sed -i 's/old/new/g' file` — use `Edit`
+- `perl -pi -e 's/old/new/'` — use `Edit`
+
+## Error Checking
+
+| Scenario              | Tool          | Notes                                      |
+| ------------------------ | --------------- | --------------------------------------------- |
+| Compile/lint errors   | `Bash` (project's own lint/typecheck script) | No dedicated "get errors" tool — run what CI runs |
+| Test failures         | `Bash`        | For test execution                          |
+
+## When Terminal (`Bash`) IS Correct
+
+Terminal is the right tool for:
+- Running tests (`npm test`, `vitest run`, `pytest`)
+- Package management (`npm install`, `pip install`)
+- Build commands (`npm run build`)
+- Git operations (`git status`, `git diff`)
+- Starting dev servers (with `run_in_background: true`)
+- Moving/renaming files (`mv`)
+- Operations that have no built-in tool equivalent

package/assets/claude/packs/frontend/skills/nextjs-tailwind/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: nextjs-tailwind
+description: Next.js + Tailwind development standards and instructions. Use when working with TSX, TypeScript, JSX, JavaScript, or CSS files.
+copilot-apply-to: '**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css'
+copilot-instructions-tier: extended
+---
+
+# Next.js + Tailwind Development Instructions
+
+Instructions for high-quality Next.js applications with Tailwind CSS styling and TypeScript.
+
+## Project Context
+
+- Latest Next.js (App Router)
+- TypeScript for type safety
+- Tailwind CSS for styling
+
+## Development Standards
+
+### Architecture
+- App Router with server and client components
+- Group routes by feature/domain
+- Implement proper error boundaries
+- Use React Server Components by default
+- Leverage static optimization where possible
+
+### TypeScript
+- Strict mode enabled
+- Clear type definitions
+- Proper error handling with type guards
+- Zod for runtime type validation
+
+### Styling
+- Tailwind CSS with consistent color palette
+- Responsive design patterns
+- Dark mode support
+- Follow container queries best practices
+- Maintain semantic HTML structure
+
+### State Management
+- React Server Components for server state
+- React hooks for client state
+- Proper loading and error states
+- Optimistic updates where appropriate
+
+### Data Fetching
+- Server Components for direct database queries
+- React Suspense for loading states
+- Proper error handling and retry logic
+- Cache invalidation strategies
+
+### Security
+- Input validation and sanitization
+- Proper authentication checks
+- CSRF protection
+- Rate limiting implementation
+- Secure API route handling
+
+### Performance
+- Image optimization with next/image
+- Font optimization with next/font
+- Route prefetching
+- Proper code splitting
+- Bundle size optimization
+
+## Implementation Process
+1. Plan component hierarchy
+2. Define types and interfaces
+3. Implement server-side logic
+4. Build client components
+5. Add proper error handling
+6. Implement responsive styling
+7. Add loading states
+8. Write tests

package/assets/claude/packs/frontend/skills/reactjs/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: reactjs
+description: ReactJS development standards and best practices. Use when working with JSX, TSX, JavaScript, TypeScript, CSS, or SCSS files.
+copilot-apply-to: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
+copilot-instructions-tier: extended
+---
+
+# ReactJS Development Instructions
+
+Instructions for building high-quality ReactJS applications with modern patterns, hooks, and best practices following the official React documentation at https://react.dev.
+
+## Project Context
+- Latest React version (React 19+)
+- TypeScript for type safety (when applicable)
+- Functional components with hooks as default
+- Follow React's official style guide and best practices
+- Use modern build tools (Vite, Create React App, or custom Webpack setup)
+- Implement proper component composition and reusability patterns
+
+## Development Standards
+
+### Architecture
+- Use functional components with hooks as the primary pattern
+- Implement component composition over inheritance
+- Organize components by feature or domain for scalability
+- Separate presentational and container components clearly
+- Use custom hooks for reusable stateful logic
+- Implement proper component hierarchies with clear data flow
+
+### TypeScript Integration
+- Use TypeScript interfaces for props, state, and component definitions
+- Define proper types for event handlers and refs
+- Implement generic components where appropriate
+- Use strict mode in `tsconfig.json` for type safety
+- Leverage React's built-in types (`React.FC`, `React.ComponentProps`, etc.)
+- Create union types for component variants and states
+
+### Component Design
+- Follow the single responsibility principle for components
+- Use descriptive and consistent naming conventions
+- Implement proper prop validation with TypeScript or PropTypes
+- Design components to be testable and reusable
+- Keep components small and focused on a single concern
+- Use composition patterns (render props, children as functions)
+
+### State Management
+- Use `useState` for local component state
+- Implement `useReducer` for complex state logic
+- Leverage `useContext` for sharing state across component trees
+- Consider external state management (Redux Toolkit, Zustand) for complex applications
+- Implement proper state normalization and data structures
+- Use React Query or SWR for server state management
+
+### Hooks and Effects
+- Use `useEffect` with proper dependency arrays to avoid infinite loops
+- Implement cleanup functions in effects to prevent memory leaks
+- Use `useMemo` and `useCallback` for performance optimization when needed
+- Create custom hooks for reusable stateful logic
+- Follow the rules of hooks (only call at the top level)
+- Use `useRef` for accessing DOM elements and storing mutable values
+
+### Styling
+- Use CSS Modules, Styled Components, or modern CSS-in-JS solutions
+- Implement responsive design with mobile-first approach
+- Follow BEM methodology or similar naming conventions for CSS classes
+- Use CSS custom properties (variables) for theming
+- Implement consistent spacing, typography, and color systems
+- Ensure accessibility with proper ARIA attributes and semantic HTML
+
+### Performance Optimization
+- Use `React.memo` for component memoization when appropriate
+- Implement code splitting with `React.lazy` and `Suspense`
+- Optimize bundle size with tree shaking and dynamic imports
+- Use `useMemo` and `useCallback` judiciously to prevent unnecessary re-renders
+- Implement virtual scrolling for large lists
+- Profile components with React DevTools to identify performance bottlenecks
+
+### Data Fetching
+- Use modern data fetching libraries (React Query, SWR, Apollo Client)
+- Implement proper loading, error, and success states
+- Handle race conditions and request cancellation
+- Use optimistic updates for better user experience
+- Implement proper caching strategies
+- Handle offline scenarios and network errors gracefully
+
+### Error Handling
+- Implement Error Boundaries for component-level error handling
+- Use proper error states in data fetching
+- Implement fallback UI for error scenarios
+- Log errors appropriately for debugging
+- Handle async errors in effects and event handlers
+- Provide meaningful error messages to users
+
+### Forms and Validation
+- Use controlled components for form inputs
+- Implement proper form validation with libraries like Formik, React Hook Form
+- Handle form submission and error states appropriately
+- Implement accessibility features for forms (labels, ARIA attributes)
+- Use debounced validation for better user experience
+- Handle file uploads and complex form scenarios
+
+### Routing
+- Use React Router for client-side routing
+- Implement nested routes and route protection
+- Handle route parameters and query strings properly
+- Implement lazy loading for route-based code splitting
+- Use proper navigation patterns and back button handling
+- Implement breadcrumbs and navigation state management
+
+### Testing
+- Write unit tests for components using React Testing Library
+- Test component behavior, not implementation details
+- Use Jest for test runner and assertion library
+- Implement integration tests for complex component interactions
+- Mock external dependencies and API calls appropriately
+- Test accessibility features and keyboard navigation
+
+### Security
+- Sanitize user inputs to prevent XSS attacks
+- Validate and escape data before rendering
+- Use HTTPS for all external API calls
+- Implement proper authentication and authorization patterns
+- Avoid storing sensitive data in localStorage or sessionStorage
+- Use Content Security Policy (CSP) headers
+
+### Accessibility
+- Use semantic HTML elements appropriately
+- Implement proper ARIA attributes and roles
+- Ensure keyboard navigation works for all interactive elements
+- Provide alt text for images and descriptive text for icons
+- Implement proper color contrast ratios
+- Test with screen readers and accessibility tools
+
+## Implementation Process
+1. Plan component architecture and data flow
+2. Set up project structure with proper folder organization
+3. Define TypeScript interfaces and types
+4. Implement core components with proper styling
+5. Add state management and data fetching logic
+6. Implement routing and navigation
+7. Add form handling and validation
+8. Implement error handling and loading states
+9. Add testing coverage for components and functionality
+10. Optimize performance and bundle size
+11. Ensure accessibility compliance
+12. Add documentation and code comments
+
+## Additional Guidelines
+- Follow React's naming conventions (PascalCase for components, camelCase for functions)
+- Use meaningful commit messages and maintain clean git history
+- Implement proper code splitting and lazy loading strategies
+- Document complex components and custom hooks with JSDoc
+- Use ESLint and Prettier for consistent code formatting
+- Keep dependencies up to date and audit for security vulnerabilities
+- Implement proper environment configuration for different deployment stages
+- Use React Developer Tools for debugging and performance analysis
+
+## Common Patterns
+- Higher-Order Components (HOCs) for cross-cutting concerns
+- Render props pattern for component composition
+- Compound components for related functionality
+- Provider pattern for context-based state sharing
+- Container/Presentational component separation
+- Custom hooks for reusable logic extraction

package/assets/claude/packs/frontend/skills/tailwind-v4-vite/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: tailwind-v4-vite
+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.
+copilot-apply-to: 'vite.config.ts, vite.config.js, **/*.css, **/*.tsx, **/*.ts, **/*.jsx, **/*.js'
+copilot-instructions-tier: extended
+---
+
+# Tailwind CSS v4+ Installation with Vite
+
+Instructions for installing and configuring Tailwind CSS version 4 and above using the official Vite plugin. Tailwind CSS v4 introduces a simplified setup that eliminates the need for PostCSS configuration and tailwind.config.js in most cases.
+
+## Key Changes in Tailwind CSS v4
+
+- **No PostCSS configuration required** when using the Vite plugin
+- **No tailwind.config.js required** - configuration is done via CSS
+- **New @tailwindcss/vite plugin** replaces the PostCSS-based approach
+- **CSS-first configuration** using `@theme` directive
+- **Automatic content detection** - no need to specify content paths
+
+## Installation Steps
+
+### Step 1: Install Dependencies
+
+Install `tailwindcss` and the `@tailwindcss/vite` plugin:
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+### Step 2: Configure Vite Plugin
+
+Add the `@tailwindcss/vite` plugin to your Vite configuration file:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+	plugins: [tailwindcss()],
+});
+```
+
+For React projects with Vite:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+	plugins: [react(), tailwindcss()],
+});
+```
+
+### Step 3: Import Tailwind CSS
+
+Add the Tailwind CSS import to your main CSS file (e.g., `src/index.css` or `src/App.css`):
+
+```css
+@import 'tailwindcss';
+```
+
+### Step 4: Verify CSS Import in Entry Point
+
+Ensure your main CSS file is imported in your application entry point:
+
+```typescript
+// src/main.tsx or src/main.ts
+import './index.css';
+```
+
+### Step 5: Start Development Server
+
+Run the development server to verify installation:
+
+```bash
+npm run dev
+```
+
+## What NOT to Do in Tailwind v4
+
+### Do NOT Create tailwind.config.js
+
+Tailwind v4 uses CSS-first configuration. Do not create a `tailwind.config.js` file unless you have specific legacy requirements.
+
+```javascript
+// ❌ NOT NEEDED in Tailwind v4
+module.exports = {
+	content: ['./src/**/*.{js,ts,jsx,tsx}'],
+	theme: {
+		extend: {},
+	},
+	plugins: [],
+};
+```
+
+### Do NOT Create postcss.config.js for Tailwind
+
+When using the `@tailwindcss/vite` plugin, PostCSS configuration for Tailwind is not required.
+
+```javascript
+// ❌ NOT NEEDED when using @tailwindcss/vite
+module.exports = {
+	plugins: {
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};
+```
+
+### Do NOT Use Old Directives
+
+The old `@tailwind` directives are replaced by a single import:
+
+```css
+/* ❌ OLD - Do not use in Tailwind v4 */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ✅ NEW - Use this in Tailwind v4 */
+@import 'tailwindcss';
+```
+
+## CSS-First Configuration (Tailwind v4)
+
+### Custom Theme Configuration
+
+Use the `@theme` directive in your CSS to customize your design tokens:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+	--color-primary: #3b82f6;
+	--color-secondary: #64748b;
+	--font-sans: 'Inter', system-ui, sans-serif;
+	--radius-lg: 0.75rem;
+}
+```
+
+### Adding Custom Utilities
+
+Define custom utilities directly in CSS:
+
+```css
+@import 'tailwindcss';
+
+@utility content-auto {
+	content-visibility: auto;
+}
+
+@utility scrollbar-hidden {
+	scrollbar-width: none;
+	&::-webkit-scrollbar {
+		display: none;
+	}
+}
+```
+
+### Adding Custom Variants
+
+Define custom variants in CSS:
+
+```css
+@import 'tailwindcss';
+
+@variant hocus (&:hover, &:focus);
+@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);
+```
+
+## Verification Checklist
+
+After installation, verify:
+
+- [ ] `tailwindcss` and `@tailwindcss/vite` are in `package.json` dependencies
+- [ ] `vite.config.ts` includes the `tailwindcss()` plugin
+- [ ] Main CSS file contains `@import "tailwindcss";`
+- [ ] CSS file is imported in the application entry point
+- [ ] Development server runs without errors
+- [ ] Tailwind utility classes (e.g., `text-blue-500`, `p-4`) render correctly
+
+## Example Usage
+
+Test the installation with a simple component:
+
+```tsx
+export function TestComponent() {
+	return (
+		<div className='min-h-screen bg-gray-100 flex items-center justify-center'>
+			<h1 className='text-3xl font-bold text-blue-600 underline'>Hello, Tailwind CSS v4!</h1>
+		</div>
+	);
+}
+```
+
+## Troubleshooting
+
+### Styles Not Applying
+
+1. Verify CSS import statement is `@import "tailwindcss";` (not old directives)
+2. Ensure CSS file is imported in your entry point
+3. Check Vite config includes the `tailwindcss()` plugin
+4. Clear Vite cache: `rm -rf node_modules/.vite && npm run dev`
+
+### Plugin Not Found Error
+
+If you see "Cannot find module '@tailwindcss/vite'":
+
+```bash
+npm install @tailwindcss/vite
+```
+
+### TypeScript Errors
+
+If TypeScript cannot find types for the Vite plugin, ensure you have the correct import:
+
+```typescript
+import tailwindcss from '@tailwindcss/vite';
+```
+
+## Migration from Tailwind v3
+
+If migrating from Tailwind v3:
+
+1. Remove `tailwind.config.js` (move customizations to CSS `@theme`)
+2. Remove `postcss.config.js` (if only used for Tailwind)
+3. Uninstall old packages: `npm uninstall postcss autoprefixer`
+4. Install new packages: `npm install tailwindcss @tailwindcss/vite`
+5. Replace `@tailwind` directives with `@import "tailwindcss";`
+6. Update Vite config to use `@tailwindcss/vite` plugin
+
+## Reference
+
+- Official Documentation: https://tailwindcss.com/docs/installation/using-vite
+- Tailwind CSS v4 Upgrade Guide: https://tailwindcss.com/docs/upgrade-guide

package/assets/claude/packs/integrations/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "vesper-integrations",
+  "displayName": "Vesper integrations pack",
+  "version": "2.0.1",
+  "description": "Vesper integrations pack — ClickUp task-board specialist, the GitLab MR guardrails skill, and the third-party GitLab CI skills (gitlab-ci-skill, github-actions-to-gitlab-ci; UPSTREAM.json beside each). Enabled per project by `vespercli packs sync` when the Team Roster names one of its assets.",
+  "author": {
+    "name": "Vesper Maintainers"
+  },
+  "license": "MIT"
+}