@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/instructions/nextjs-tailwind/nextjs-tailwind.instructions.md

@@ -1,72 +0,0 @@
----
-description: 'Next.js + Tailwind development standards and instructions'
-applyTo: '**/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css'
----
-
-# 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/instructions/nodejs-javascript-vitest/nodejs-javascript-vitest.instructions.md

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

package/assets/instructions/playwright-typescript/playwright-typescript.instructions.md

@@ -1,85 +0,0 @@
----
-description: 'Playwright test generation instructions'
----
-
-## Test Writing Guidelines
-
-### Code Quality Standards
-- **Locators**: Prioritize user-facing, role-based locators (`getByRole`, `getByLabel`, `getByText`, etc.) for resilience and accessibility. Use `test.step()` to group interactions and improve test readability and reporting.
-- **Assertions**: Use auto-retrying web-first assertions. These assertions start with the `await` keyword (e.g., `await expect(locator).toHaveText()`). Avoid `expect(locator).toBeVisible()` unless specifically testing for visibility changes.
-- **Timeouts**: Rely on Playwright's built-in auto-waiting mechanisms. Avoid hard-coded waits or increased default timeouts.
-- **Clarity**: Use descriptive test and step titles that clearly state the intent. Add comments only to explain complex logic or non-obvious interactions.
-
-
-### Test Structure
-- **Imports**: Start with `import { test, expect } from '@playwright/test';`.
-- **Organization**: Group related tests for a feature under a `test.describe()` block.
-- **Hooks**: Use `beforeEach` for setup actions common to all tests in a `describe` block (e.g., navigating to a page).
-- **Titles**: Follow a clear naming convention, such as `Feature - Specific action or scenario`.
-
-
-### File Organization
-- **Location**: Store all test files in the `tests/` directory.
-- **Naming**: Use the convention `<feature-or-page>.spec.ts` (e.g., `login.spec.ts`, `search.spec.ts`).
-- **Scope**: Aim for one test file per major application feature or page.
-
-### Assertion Best Practices
-- **UI Structure**: Use `toMatchAriaSnapshot` to verify the accessibility tree structure of a component. This provides a comprehensive and accessible snapshot.
-- **Element Counts**: Use `toHaveCount` to assert the number of elements found by a locator.
-- **Text Content**: Use `toHaveText` for exact text matches and `toContainText` for partial matches.
-- **Navigation**: Use `toHaveURL` to verify the page URL after an action.
-
-
-## Example Test Structure
-
-```typescript
-import { test, expect } from '@playwright/test';
-
-test.describe('Movie Search Feature', () => {
-  test.beforeEach(async ({ page }) => {
-    // Navigate to the application before each test
-    await page.goto('https://debs-obrien.github.io/playwright-movies-app');
-  });
-
-  test('Search for a movie by title', async ({ page }) => {
-    await test.step('Activate and perform search', async () => {
-      await page.getByRole('search').click();
-      const searchInput = page.getByRole('textbox', { name: 'Search Input' });
-      await searchInput.fill('Garfield');
-      await searchInput.press('Enter');
-    });
-
-    await test.step('Verify search results', async () => {
-      // Verify the accessibility tree of the search results
-      await expect(page.getByRole('main')).toMatchAriaSnapshot(`
-        - main:
-          - heading "Garfield" [level=1]
-          - heading "search results" [level=2]
-          - list "movies":
-            - listitem "movie":
-              - link "poster of The Garfield Movie The Garfield Movie rating":
-                - /url: /playwright-movies-app/movie?id=tt5779228&page=1
-                - img "poster of The Garfield Movie"
-                - heading "The Garfield Movie" [level=2]
-      `);
-    });
-  });
-});
-```
-
-## Test Execution Strategy
-
-1. **Initial Run**: Execute tests with `npx playwright test --project=chromium`
-2. **Debug Failures**: Analyze test failures and identify root causes
-3. **Iterate**: Refine locators, assertions, or test logic as needed
-4. **Validate**: Ensure tests pass consistently and cover the intended functionality
-5. **Report**: Provide feedback on test results and any issues discovered
-
-## Quality Checklist
-
-Before finalizing tests, ensure:
-- [ ] All locators are accessible and specific and avoid strict mode violations
-- [ ] Tests are grouped logically and follow a clear structure
-- [ ] Assertions are meaningful and reflect user expectations
-- [ ] Tests follow consistent naming conventions
-- [ ] Code is properly formatted and commented

package/assets/instructions/project-management/project-management.instructions.md

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

package/assets/instructions/reactjs/reactjs.instructions.md

@@ -1,162 +0,0 @@
----
-description: 'ReactJS development standards and best practices'
-applyTo: '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss'
----
-
-# 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/instructions/self-explanatory-code-commenting/self-explanatory-code-commenting.instructions.md

@@ -1,162 +0,0 @@
----
-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).'
-applyTo: '**/*.py, **/*.js, **/*.ts, **/*.java, **/*.cs, **/*.cpp, **/*.go, **/*.rb'
----
-
-# Self-explanatory Code Commenting Instructions
-
-## Core Principle
-**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
-We do not need comments most of the time.
-
-## Commenting Guidelines
-
-### ❌ AVOID These Comment Types
-
-**Obvious Comments**
-```javascript
-// Bad: States the obvious
-let counter = 0;  // Initialize counter to zero
-counter++;  // Increment counter by one
-```
-
-**Redundant Comments**
-```javascript
-// Bad: Comment repeats the code
-function getUserName() {
-    return user.name;  // Return the user's name
-}
-```
-
-**Outdated Comments**
-```javascript
-// Bad: Comment doesn't match the code
-// Calculate tax at 5% rate
-const tax = price * 0.08;  // Actually 8%
-```
-
-### ✅ WRITE These Comment Types
-
-**Complex Business Logic**
-```javascript
-// Good: Explains WHY this specific calculation
-// Apply progressive tax brackets: 10% up to 10k, 20% above
-const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);
-```
-
-**Non-obvious Algorithms**
-```javascript
-// Good: Explains the algorithm choice
-// Using Floyd-Warshall for all-pairs shortest paths
-// because we need distances between all nodes
-for (let k = 0; k < vertices; k++) {
-    for (let i = 0; i < vertices; i++) {
-        for (let j = 0; j < vertices; j++) {
-            // ... implementation
-        }
-    }
-}
-```
-
-**Regex Patterns**
-```javascript
-// Good: Explains what the regex matches
-// Match email format: username@domain.extension
-const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
-```
-
-**API Constraints or Gotchas**
-```javascript
-// Good: Explains external constraint
-// GitHub API rate limit: 5000 requests/hour for authenticated users
-await rateLimiter.wait();
-const response = await fetch(githubApiUrl);
-```
-
-## Decision Framework
-
-Before writing a comment, ask:
-1. **Is the code self-explanatory?** → No comment needed
-2. **Would a better variable/function name eliminate the need?** → Refactor instead
-3. **Does this explain WHY, not WHAT?** → Good comment
-4. **Will this help future maintainers?** → Good comment
-
-## Special Cases for Comments
-
-### Public APIs
-```javascript
-/**
- * Calculate compound interest using the standard formula.
- * 
- * @param {number} principal - Initial amount invested
- * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
- * @param {number} time - Time period in years
- * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
- * @returns {number} Final amount after compound interest
- */
-function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
-    // ... implementation
-}
-```
-
-### Configuration and Constants
-```javascript
-// Good: Explains the source or reasoning
-const MAX_RETRIES = 3;  // Based on network reliability studies
-const API_TIMEOUT = 5000;  // AWS Lambda timeout is 15s, leaving buffer
-```
-
-### Annotations
-```javascript
-// TODO: Replace with proper user authentication after security review
-// FIXME: Memory leak in production - investigate connection pooling
-// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
-// NOTE: This implementation assumes UTC timezone for all calculations
-// WARNING: This function modifies the original array instead of creating a copy
-// PERF: Consider caching this result if called frequently in hot path
-// SECURITY: Validate input to prevent SQL injection before using in query
-// BUG: Edge case failure when array is empty - needs investigation
-// REFACTOR: Extract this logic into separate utility function for reusability
-// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
-```
-
-## Anti-Patterns to Avoid
-
-### Dead Code Comments
-```javascript
-// Bad: Don't comment out code
-// const oldFunction = () => { ... };
-const newFunction = () => { ... };
-```
-
-### Changelog Comments
-```javascript
-// Bad: Don't maintain history in comments
-// Modified by John on 2023-01-15
-// Fixed bug reported by Sarah on 2023-02-03
-function processData() {
-    // ... implementation
-}
-```
-
-### Divider Comments
-```javascript
-// Bad: Don't use decorative comments
-//=====================================
-// UTILITY FUNCTIONS
-//=====================================
-```
-
-## Quality Checklist
-
-Before committing, ensure your comments:
-- [ ] Explain WHY, not WHAT
-- [ ] Are grammatically correct and clear
-- [ ] Will remain accurate as code evolves
-- [ ] Add genuine value to code understanding
-- [ ] Are placed appropriately (above the code they describe)
-- [ ] Use proper spelling and professional language
-
-## Summary
-
-Remember: **The best comment is the one you don't need to write because the code is self-documenting.**