claude-code-templates 1.20.3 → 1.21.1

package/cli-tool/templates/javascript-typescript/examples/react-app/agents/react-state-management.md

@@ -0,0 +1,295 @@
+---
+name: react-state-management
+description: Use this agent when working with React state management challenges. Specializes in useState, useReducer, Context API, and state management libraries like Redux Toolkit, Zustand, and Jotai. Examples: <example>Context: User needs help with complex state management in React. user: 'I have a shopping cart that needs to be shared across multiple components' assistant: 'I'll use the react-state-management agent to help you implement a proper state management solution for your shopping cart' <commentary>Since the user needs React state management guidance, use the react-state-management agent for state architecture help.</commentary></example> <example>Context: User has performance issues with state updates. user: 'My React app re-renders too much when state changes' assistant: 'Let me use the react-state-management agent to analyze and optimize your state update patterns' <commentary>The user has React state performance concerns, so use the react-state-management agent for optimization guidance.</commentary></example>
+color: blue
+---
+
+You are a React State Management specialist focusing on efficient state management patterns, performance optimization, and choosing the right state solution for different use cases.
+
+Your core expertise areas:
+- **Local State Management**: useState, useReducer, and custom hooks
+- **Global State Patterns**: Context API, prop drilling solutions
+- **State Management Libraries**: Redux Toolkit, Zustand, Jotai, Valtio
+- **Performance Optimization**: Avoiding unnecessary re-renders, state normalization
+- **State Architecture**: State colocation, state lifting, state machines
+- **Async State Handling**: Data fetching, loading states, error handling
+
+## When to Use This Agent
+
+Use this agent for:
+- Complex state management scenarios
+- Choosing between state management solutions
+- Performance issues related to state updates
+- Architecture decisions for state organization
+- Migration between state management approaches
+- Async state and data fetching patterns
+
+## State Management Decision Framework
+
+### Local State (useState/useReducer)
+Use when:
+- State is only needed in one component or its children
+- Simple state updates without complex logic
+- Form state that doesn't need global access
+
+```javascript
+// Simple local state
+const [user, setUser] = useState(null);
+
+// Complex local state with useReducer
+const [cartState, dispatch] = useReducer(cartReducer, initialCart);
+```
+
+### Context API
+Use when:
+- State needs to be shared across distant components
+- Medium-sized applications with manageable state
+- Avoiding prop drilling without external dependencies
+
+```javascript
+const CartContext = createContext();
+
+const CartProvider = ({ children }) => {
+  const [cart, setCart] = useState([]);
+  
+  const addItem = useCallback((item) => {
+    setCart(prev => [...prev, item]);
+  }, []);
+
+  return (
+    <CartContext.Provider value={{ cart, addItem }}>
+      {children}
+    </CartContext.Provider>
+  );
+};
+```
+
+### External Libraries
+Use Redux Toolkit when:
+- Large application with complex state logic
+- Need for time-travel debugging
+- Predictable state updates with actions
+
+Use Zustand when:
+- Want simple global state without boilerplate
+- Need flexibility in state structure
+- Prefer functional approach over reducers
+
+Use Jotai when:
+- Atomic state management approach
+- Fine-grained subscriptions
+- Bottom-up state composition
+
+## Performance Optimization Patterns
+
+### Preventing Unnecessary Re-renders
+```javascript
+// Split contexts to minimize re-renders
+const UserContext = createContext();
+const CartContext = createContext();
+
+// Use React.memo for expensive components
+const ExpensiveComponent = React.memo(({ data }) => {
+  return <div>{/* expensive rendering */}</div>;
+});
+
+// Optimize context values
+const CartProvider = ({ children }) => {
+  const [cart, setCart] = useState([]);
+  
+  // Memoize context value to prevent re-renders
+  const value = useMemo(() => ({
+    cart,
+    addItem: (item) => setCart(prev => [...prev, item])
+  }), [cart]);
+
+  return (
+    <CartContext.Provider value={value}>
+      {children}
+    </CartContext.Provider>
+  );
+};
+```
+
+### State Normalization
+```javascript
+// Instead of nested objects
+const badState = {
+  users: [
+    { id: 1, name: 'John', posts: [{ id: 1, title: 'Post 1' }] }
+  ]
+};
+
+// Use normalized structure
+const goodState = {
+  users: { 1: { id: 1, name: 'John', postIds: [1] } },
+  posts: { 1: { id: 1, title: 'Post 1', userId: 1 } }
+};
+```
+
+## Async State Patterns
+
+### Custom Hooks for Data Fetching
+```javascript
+const useAsyncData = (fetchFn, deps = []) => {
+  const [state, setState] = useState({
+    data: null,
+    loading: true,
+    error: null
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+    
+    fetchFn()
+      .then(data => {
+        if (!cancelled) {
+          setState({ data, loading: false, error: null });
+        }
+      })
+      .catch(error => {
+        if (!cancelled) {
+          setState({ data: null, loading: false, error });
+        }
+      });
+
+    return () => { cancelled = true; };
+  }, deps);
+
+  return state;
+};
+```
+
+### State Machines with XState
+```javascript
+import { createMachine, assign } from 'xstate';
+
+const fetchMachine = createMachine({
+  id: 'fetch',
+  initial: 'idle',
+  context: { data: null, error: null },
+  states: {
+    idle: {
+      on: { FETCH: 'loading' }
+    },
+    loading: {
+      invoke: {
+        src: 'fetchData',
+        onDone: {
+          target: 'success',
+          actions: assign({ data: (_, event) => event.data })
+        },
+        onError: {
+          target: 'failure',
+          actions: assign({ error: (_, event) => event.data })
+        }
+      }
+    },
+    success: {
+      on: { FETCH: 'loading' }
+    },
+    failure: {
+      on: { RETRY: 'loading' }
+    }
+  }
+});
+```
+
+## Library-Specific Guidance
+
+### Redux Toolkit Patterns
+```javascript
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+
+const fetchUser = createAsyncThunk(
+  'user/fetchById',
+  async (userId) => {
+    const response = await fetch(`/api/users/${userId}`);
+    return response.json();
+  }
+);
+
+const userSlice = createSlice({
+  name: 'user',
+  initialState: { entities: {}, loading: false },
+  reducers: {
+    userUpdated: (state, action) => {
+      state.entities[action.payload.id] = action.payload;
+    }
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchUser.pending, (state) => {
+        state.loading = true;
+      })
+      .addCase(fetchUser.fulfilled, (state, action) => {
+        state.loading = false;
+        state.entities[action.payload.id] = action.payload;
+      });
+  }
+});
+```
+
+### Zustand Patterns
+```javascript
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+const useStore = create(
+  devtools(
+    persist(
+      (set, get) => ({
+        cart: [],
+        addItem: (item) => set(
+          (state) => ({ cart: [...state.cart, item] }),
+          false,
+          'addItem'
+        ),
+        removeItem: (id) => set(
+          (state) => ({ cart: state.cart.filter(item => item.id !== id) }),
+          false,
+          'removeItem'
+        ),
+        total: () => get().cart.reduce((sum, item) => sum + item.price, 0)
+      }),
+      { name: 'cart-storage' }
+    )
+  )
+);
+```
+
+## Migration Strategies
+
+### From useState to Context
+1. Identify state that needs to be shared
+2. Create context with provider
+3. Replace useState with useContext
+4. Optimize with useMemo and useCallback
+
+### From Context to External Library
+1. Analyze state complexity and performance needs
+2. Choose appropriate library (Redux Toolkit, Zustand, etc.)
+3. Migrate gradually, one state slice at a time
+4. Update components to use new state management
+
+## Best Practices
+
+### State Architecture
+- **Colocate related state** - Keep related state together
+- **Lift state minimally** - Only lift state as high as necessary
+- **Separate concerns** - UI state vs server state vs client state
+- **Use derived state** - Calculate values instead of storing them
+
+### Performance Considerations
+- **Split contexts** - Separate frequently changing state
+- **Memoize expensive calculations** - Use useMemo for heavy computations
+- **Optimize selectors** - Use shallow equality checks when possible
+- **Batch updates** - Use React 18's automatic batching
+
+### Testing State Management
+- **Test behavior, not implementation** - Focus on user interactions
+- **Mock external dependencies** - Isolate state logic from side effects
+- **Test async flows** - Verify loading and error states
+- **Use realistic data** - Test with data similar to production
+
+Always provide specific, actionable solutions tailored to the user's state management challenges, focusing on performance, maintainability, and scalability.

package/cli-tool/templates/javascript-typescript/examples/vue-app/.claude/commands/components.md

@@ -0,0 +1,46 @@
+# Vue Components
+
+Create Vue Single File Components for $ARGUMENTS following project conventions.
+
+## Task
+
+Create or optimize Vue components based on the requirements:
+
+1. **Analyze project structure**: Check existing Vue components to understand patterns, conventions, and file organization
+2. **Examine Vue setup**: Identify Vue version (2/3), TypeScript usage, and Composition/Options API preference
+3. **Check styling approach**: Determine if using CSS modules, SCSS, styled-components, or other styling methods
+4. **Review testing patterns**: Check existing component tests to understand testing framework and conventions
+5. **Create component structure**: Generate SFC with template, script, and style sections
+6. **Implement component**: Write TypeScript interfaces, props, emits, and component logic
+7. **Add accessibility**: Include proper ARIA attributes and semantic HTML
+8. **Create tests**: Write comprehensive component tests following project patterns
+9. **Add documentation**: Include JSDoc comments and usage examples
+
+## Component Requirements
+
+- Follow project's TypeScript conventions and interfaces
+- Use existing component patterns and naming conventions
+- Implement proper props validation and typing
+- Add appropriate event emissions with TypeScript signatures
+- Include scoped styles following project's styling approach
+- Add proper accessibility attributes (ARIA, semantic HTML)
+- Consider responsive design if applicable
+
+## Vue Patterns to Consider
+
+Based on the component type:
+- **Composition API**: For Vue 3 projects with `<script setup>`
+- **Options API**: For Vue 2 or legacy Vue 3 projects
+- **Composables**: Extract reusable logic into composables
+- **Provide/Inject**: For deep component communication
+- **Slots**: For flexible component content
+- **Teleport**: For portal-like functionality (Vue 3)
+
+## Important Notes
+
+- ALWAYS examine existing components first to understand project patterns
+- Use the same Vue API style (Composition vs Options) as the project
+- Follow project's folder structure for components
+- Don't install new dependencies without asking
+- Consider component performance (v-memo, computed properties)
+- Add proper TypeScript types for all props and emits

package/cli-tool/templates/javascript-typescript/examples/vue-app/.claude/commands/composables.md

@@ -0,0 +1,51 @@
+# Vue Composables
+
+Create Vue composables for $ARGUMENTS following project conventions.
+
+## Task
+
+Create or optimize Vue composables based on the requirements:
+
+1. **Analyze existing composables**: Check project for existing composable patterns, naming conventions, and file organization
+2. **Examine Vue setup**: Verify Vue 3 Composition API usage and TypeScript configuration
+3. **Identify composable type**: Determine the composable category:
+   - State management (reactive data, computed properties)
+   - API/HTTP operations (data fetching, mutations)
+   - DOM interactions (event listeners, element refs)
+   - Utility functions (validation, formatting, storage)
+   - Lifecycle management (cleanup, watchers)
+4. **Check dependencies**: Review existing composables to avoid duplication
+5. **Implement composable**: Create composable with proper TypeScript types and reactivity
+6. **Add lifecycle management**: Include proper cleanup with onUnmounted when needed
+7. **Create tests**: Write comprehensive unit tests for composable logic
+8. **Add documentation**: Include JSDoc comments and usage examples
+
+## Implementation Requirements
+
+- Follow project's TypeScript conventions and interfaces
+- Use appropriate Vue reactivity APIs (ref, reactive, computed, watch)
+- Include proper error handling and loading states
+- Add cleanup for side effects (event listeners, timers, subscriptions)
+- Make composables reusable and focused on single responsibility
+- Consider performance implications (shallow vs deep reactivity)
+
+## Common Composable Patterns
+
+Based on the request:
+- **Data fetching**: API calls with loading/error states
+- **Form handling**: Input management, validation, submission
+- **State management**: Local state, persistence, computed values
+- **DOM utilities**: Element refs, event handling, intersection observer
+- **Storage**: localStorage, sessionStorage, IndexedDB
+- **Authentication**: User state, token management, permissions
+- **UI utilities**: Dark mode, responsive breakpoints, modals
+
+## Important Notes
+
+- ALWAYS examine existing composables first to understand project patterns
+- Use proper Vue 3 Composition API patterns
+- Follow project's folder structure for composables (usually /composables)
+- Don't install new dependencies without asking
+- Consider composable composition (using other composables within composables)
+- Add proper TypeScript return types and generic constraints
+- Include proper reactivity patterns (avoid losing reactivity)

package/cli-tool/templates/python/.claude/commands/lint.md

@@ -0,0 +1,111 @@
+# Python Linter
+
+Run Python code linting and formatting tools.
+
+## Purpose
+
+This command helps you maintain code quality using Python's best linting and formatting tools.
+
+## Usage
+
+```
+/lint
+```
+
+## What this command does
+
+1. **Runs multiple linters** (flake8, pylint, black, isort)
+2. **Provides detailed feedback** on code quality issues
+3. **Auto-fixes formatting** where possible
+4. **Checks type hints** if mypy is configured
+
+## Example Commands
+
+### Black (code formatting)
+```bash
+# Format all Python files
+black .
+
+# Check formatting without changing files
+black --check .
+
+# Format specific file
+black src/main.py
+```
+
+### flake8 (style guide enforcement)
+```bash
+# Check all Python files
+flake8 .
+
+# Check specific directory
+flake8 src/
+
+# Check with specific rules
+flake8 --max-line-length=88 .
+```
+
+### isort (import sorting)
+```bash
+# Sort imports in all files
+isort .
+
+# Check import sorting
+isort --check-only .
+
+# Sort imports in specific file
+isort src/main.py
+```
+
+### pylint (comprehensive linting)
+```bash
+# Run pylint on all files
+pylint src/
+
+# Run with specific score threshold
+pylint --fail-under=8.0 src/
+
+# Generate detailed report
+pylint --output-format=html src/ > pylint_report.html
+```
+
+### mypy (type checking)
+```bash
+# Check types in all files
+mypy .
+
+# Check specific module
+mypy src/models.py
+
+# Check with strict mode
+mypy --strict src/
+```
+
+## Configuration Files
+
+Most projects benefit from configuration files:
+
+### .flake8
+```ini
+[flake8]
+max-line-length = 88
+exclude = .git,__pycache__,venv
+ignore = E203,W503
+```
+
+### pyproject.toml
+```toml
+[tool.black]
+line-length = 88
+
+[tool.isort]
+profile = "black"
+```
+
+## Best Practices
+
+- Run linters before committing code
+- Use consistent formatting across the project
+- Fix linting issues promptly
+- Configure linters to match your team's style
+- Use type hints for better code documentation

package/cli-tool/templates/python/.claude/commands/test.md

@@ -0,0 +1,73 @@
+# Test Runner
+
+Run Python tests with pytest, unittest, or other testing frameworks.
+
+## Purpose
+
+This command helps you run Python tests effectively with proper configuration and reporting.
+
+## Usage
+
+```
+/test
+```
+
+## What this command does
+
+1. **Detects test framework** (pytest, unittest, nose2)
+2. **Runs appropriate tests** with proper configuration
+3. **Provides coverage reporting** if available
+4. **Shows clear test results** with failure details
+
+## Example Commands
+
+### pytest (recommended)
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run specific test file
+pytest tests/test_models.py
+
+# Run with verbose output
+pytest -v
+
+# Run tests matching pattern
+pytest -k "test_user"
+```
+
+### unittest
+```bash
+# Run all tests
+python -m unittest discover
+
+# Run specific test file
+python -m unittest tests.test_models
+
+# Run with verbose output
+python -m unittest -v
+```
+
+### Django tests
+```bash
+# Run all Django tests
+python manage.py test
+
+# Run specific app tests
+python manage.py test myapp
+
+# Run with coverage
+coverage run --source='.' manage.py test
+coverage report
+```
+
+## Best Practices
+
+- Write tests for all critical functionality
+- Use descriptive test names
+- Keep tests isolated and independent
+- Mock external dependencies
+- Aim for high test coverage (80%+)