Add comprehensive skills and documentation for various technologies

.claude/commands/api-gen.md

@@ -0,0 +1,55 @@
+# /api-gen - API Generation Command
+
+## Purpose
+
+Generate API endpoints, documentation, or client code from specifications.
+
+## Usage
+
+```
+/api-gen [resource name or OpenAPI spec path]
+```
+
+---
+
+Generate API for: **$ARGUMENTS**
+
+## Workflow
+
+### Step 1: Define Resource
+
+1. Identify resource properties
+2. Define relationships
+3. Determine operations
+
+### Step 2: Generate
+
+1. Create model/schema
+2. Create routes/endpoints
+3. Add validation
+4. Generate tests
+
+### Step 3: Document
+
+1. Create OpenAPI spec
+2. Add examples
+3. Document errors
+
+## Output
+
+```markdown
+## API Generated
+
+### Endpoints
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /resources | List all |
+| POST | /resources | Create |
+| GET | /resources/:id | Get one |
+
+### Files Created
+- `src/models/resource.ts`
+- `src/routes/resource.ts`
+- `tests/resource.test.ts`
+- `docs/api/resource.md`
+```

.claude/commands/changelog.md

@@ -0,0 +1,47 @@
+# /changelog - Changelog Command
+
+## Purpose
+
+Generate changelog entries from recent commits.
+
+## Usage
+
+```
+/changelog [version or 'since:tag']
+```
+
+---
+
+Generate changelog for: **$ARGUMENTS**
+
+## Workflow
+
+1. **Analyze Commits**
+   ```bash
+   git log --oneline --since="last tag"
+   ```
+
+2. **Categorize**
+   - Added
+   - Changed
+   - Fixed
+   - Removed
+
+3. **Generate**
+   - User-friendly descriptions
+   - Link to PRs/issues
+
+## Output
+
+```markdown
+## [Version] - Date
+
+### Added
+- Feature description (#123)
+
+### Changed
+- Improvement description (#124)
+
+### Fixed
+- Bug fix description (#125)
+```

.claude/commands/commit.md

@@ -0,0 +1,219 @@
+# /commit - Smart Commit Command
+
+## Purpose
+
+Create a well-formatted commit with auto-generated message based on staged changes.
+
+## Usage
+
+```
+/commit [optional message hint]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: Optional hint for commit message focus (e.g., "auth", "bugfix", "refactor")
+
+---
+
+Create a commit for staged changes with hint: **$ARGUMENTS**
+
+## Workflow
+
+### Step 1: Analyze Changes
+
+1. **Check Status**
+   ```bash
+   git status
+   ```
+
+2. **View Staged Changes**
+   ```bash
+   git diff --staged
+   ```
+
+3. **Review Recent Commits**
+   ```bash
+   git log --oneline -5
+   ```
+
+### Step 2: Categorize Changes
+
+Determine commit type:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `style`: Formatting
+- `refactor`: Code restructuring
+- `test`: Adding tests
+- `chore`: Maintenance
+
+### Step 3: Generate Message
+
+Follow conventional commit format:
+```
+type(scope): subject
+
+body (optional)
+
+footer (optional)
+```
+
+### Step 4: Create Commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): subject
+
+- Change 1
+- Change 2
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Commit Message Guidelines
+
+### Subject Line
+- Max 50 characters
+- Imperative mood ("Add" not "Added")
+- No period at end
+- Capitalize first letter
+
+### Body
+- Wrap at 72 characters
+- Explain what and why
+- Use bullet points for multiple changes
+
+### Examples
+
+#### Feature
+```
+feat(auth): add password reset functionality
+
+- Add reset token generation
+- Implement email sending
+- Add rate limiting for reset requests
+
+Closes #123
+```
+
+#### Bug Fix
+```
+fix(api): handle null user in profile endpoint
+
+The profile endpoint crashed when accessing deleted users.
+Added null check and proper 404 response.
+
+Fixes #456
+```
+
+#### Refactor
+```
+refactor(database): extract query builders
+
+Split large database service into focused modules
+for better maintainability and testing.
+```
+
+#### Documentation
+```
+docs(readme): update installation instructions
+
+- Add prerequisites section
+- Update configuration examples
+- Fix broken links
+```
+
+#### Test
+```
+test(auth): add missing login tests
+
+- Add test for invalid credentials
+- Add test for locked account
+- Add test for expired session
+```
+
+#### Chore
+```
+chore(deps): update dependencies
+
+- Update React to 18.2
+- Update TypeScript to 5.3
+- Remove unused packages
+```
+
+## Output
+
+### Commit Created
+
+```markdown
+## Commit Created
+
+**Hash**: `abc1234`
+**Branch**: `feature/auth-improvements`
+
+### Message
+```
+feat(auth): add OAuth2 login support
+
+- Implement Google OAuth provider
+- Implement GitHub OAuth provider
+- Add session token generation
+- Update user model for OAuth data
+
+Closes #789
+```
+
+### Files Changed
+| Status | File |
+|--------|------|
+| M | src/auth/providers.ts |
+| A | src/auth/oauth/google.ts |
+| A | src/auth/oauth/github.ts |
+| M | src/models/user.ts |
+| A | tests/auth/oauth.test.ts |
+
+### Stats
+- 5 files changed
+- 234 insertions(+)
+- 12 deletions(-)
+
+### Next Steps
+```bash
+# Push to remote
+git push -u origin feature/auth-improvements
+
+# Create PR
+gh pr create
+```
+```
+
+## Pre-Commit Checks
+
+Before committing:
+- [ ] No secrets in staged files
+- [ ] No debug statements
+- [ ] No TODO comments (unless intentional)
+- [ ] Code is formatted
+
+## Amending Commits
+
+If pre-commit hooks modify files:
+```bash
+# Stage modified files and amend
+git add -A
+git commit --amend --no-edit
+```
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Commit message format
+- Required sections
+- Issue reference format
+- Co-author settings

.claude/commands/debug.md

@@ -0,0 +1,53 @@
+# /debug - Debug Command
+
+## Purpose
+
+Analyze and debug an error, exception, or unexpected behavior.
+
+## Usage
+
+```
+/debug [error message or description]
+```
+
+---
+
+Debug issue: **$ARGUMENTS**
+
+## Workflow
+
+### Step 1: Analyze Error
+
+1. Parse error message and stack trace
+2. Identify error location
+3. Understand error type
+
+### Step 2: Investigate
+
+1. Trace execution path
+2. Check related code
+3. Form hypotheses
+
+### Step 3: Fix
+
+1. Implement minimal fix
+2. Verify fix works
+3. Add regression test
+
+## Output
+
+```markdown
+## Debug Report
+
+### Error
+[Error message]
+
+### Root Cause
+[Explanation]
+
+### Fix
+[Code changes]
+
+### Prevention
+[Test added]
+```

.claude/commands/deploy.md

@@ -0,0 +1,72 @@
+# /deploy - Deployment Command
+
+## Purpose
+
+Deploy the application to a specified environment with proper checks.
+
+## Usage
+
+```
+/deploy [environment: staging | production]
+```
+
+---
+
+Deploy to: **$ARGUMENTS**
+
+## Workflow
+
+### Pre-Deploy Checks
+
+1. **Verify Build**
+   ```bash
+   pnpm build
+   ```
+
+2. **Run Tests**
+   ```bash
+   pnpm test
+   ```
+
+3. **Security Scan**
+   ```bash
+   npm audit --audit-level=high
+   ```
+
+### Deploy
+
+1. **Staging**
+   ```bash
+   # Deploy to staging environment
+   ```
+
+2. **Production** (requires confirmation)
+   ```bash
+   # Deploy to production environment
+   ```
+
+### Post-Deploy
+
+1. **Verify Deployment**
+   - Health checks
+   - Smoke tests
+
+2. **Monitor**
+   - Check logs
+   - Watch metrics
+
+## Output
+
+```markdown
+## Deployment Complete
+
+**Environment**: staging
+**Version**: v1.2.3
+**URL**: https://staging.example.com
+
+### Checks
+- [x] Build successful
+- [x] Tests passing
+- [x] Security scan clean
+- [x] Health check passed
+```

.claude/commands/doc.md

@@ -0,0 +1,243 @@
+# /doc - Documentation Command
+
+## Purpose
+
+Generate or update documentation including API docs, README files, code comments, and technical specifications.
+
+## Usage
+
+```
+/doc [target | 'api' | 'readme' | 'changelog']
+```
+
+## Arguments
+
+- `$ARGUMENTS`:
+  - File/function path: Document specific code
+  - `api`: Generate API documentation
+  - `readme`: Update README file
+  - `changelog`: Generate changelog from commits
+
+---
+
+Generate documentation for: **$ARGUMENTS**
+
+## Workflow
+
+### For Code Documentation
+
+1. **Analyze Code**
+   - Read the code thoroughly
+   - Understand purpose and behavior
+   - Identify inputs and outputs
+   - Note side effects
+
+2. **Generate Documentation**
+   - Add docstrings/JSDoc
+   - Include examples
+   - Document edge cases
+   - Add type annotations
+
+### For API Documentation
+
+1. **Find All Endpoints**
+   - Scan route definitions
+   - Identify HTTP methods
+   - Note authentication requirements
+
+2. **Document Each Endpoint**
+   - Request format
+   - Response format
+   - Error responses
+   - Examples
+
+### For README
+
+1. **Analyze Project**
+   - Purpose and features
+   - Installation steps
+   - Usage examples
+   - Configuration
+
+2. **Generate/Update**
+   - Clear structure
+   - Working examples
+   - Up-to-date info
+
+### For Changelog
+
+1. **Analyze Commits**
+   ```bash
+   git log --oneline --since="last release"
+   ```
+
+2. **Categorize Changes**
+   - Added
+   - Changed
+   - Fixed
+   - Removed
+
+## Templates
+
+### Python Docstring
+```python
+def calculate_discount(price: float, percentage: float) -> float:
+    """
+    Calculate discounted price.
+
+    Args:
+        price: Original price in dollars.
+        percentage: Discount percentage (0-100).
+
+    Returns:
+        The discounted price.
+
+    Raises:
+        ValueError: If percentage is not between 0 and 100.
+
+    Example:
+        >>> calculate_discount(100.0, 20)
+        80.0
+    """
+```
+
+### TypeScript JSDoc
+```typescript
+/**
+ * Calculate discounted price.
+ *
+ * @param price - Original price in dollars
+ * @param percentage - Discount percentage (0-100)
+ * @returns The discounted price
+ * @throws {RangeError} If percentage is not between 0 and 100
+ *
+ * @example
+ * calculateDiscount(100, 20); // returns 80
+ */
+```
+
+### API Endpoint
+```markdown
+## POST /api/orders
+
+Create a new order.
+
+### Authentication
+Requires Bearer token.
+
+### Request Body
+```json
+{
+  "items": [
+    { "productId": "123", "quantity": 2 }
+  ],
+  "shippingAddress": {
+    "street": "123 Main St",
+    "city": "New York",
+    "zip": "10001"
+  }
+}
+```
+
+### Response (201 Created)
+```json
+{
+  "id": "order_456",
+  "status": "pending",
+  "total": 99.99,
+  "createdAt": "2024-01-15T10:00:00Z"
+}
+```
+
+### Errors
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | INVALID_ITEMS | Items array is empty |
+| 401 | UNAUTHORIZED | Invalid or missing token |
+| 422 | OUT_OF_STOCK | Item not available |
+```
+
+### README Section
+```markdown
+## Installation
+
+```bash
+npm install my-package
+```
+
+## Quick Start
+
+```typescript
+import { Client } from 'my-package';
+
+const client = new Client({ apiKey: 'your-key' });
+const result = await client.fetch();
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | string | required | Your API key |
+| `timeout` | number | 5000 | Request timeout in ms |
+```
+
+### Changelog Entry
+```markdown
+## [1.2.0] - 2024-01-15
+
+### Added
+- Password reset functionality (#123)
+- Email verification for new accounts
+
+### Changed
+- Improved error messages for validation failures
+- Updated dependencies to latest versions
+
+### Fixed
+- Race condition in session handling (#456)
+- Incorrect timezone in date displays
+```
+
+## Output
+
+### Documentation Report
+
+```markdown
+## Documentation Updated
+
+### Files Modified
+- `src/services/auth.ts` - Added JSDoc comments
+- `docs/api/auth.md` - New API documentation
+- `README.md` - Updated configuration section
+
+### Documentation Added
+
+#### Code Comments
+- `AuthService.login()` - Full JSDoc with examples
+- `AuthService.logout()` - Parameter documentation
+- `validateToken()` - Return type and exceptions
+
+#### API Documentation
+- POST /api/auth/login
+- POST /api/auth/logout
+- POST /api/auth/refresh
+
+### Coverage
+- Functions documented: 15/18 (83%)
+- Endpoints documented: 12/12 (100%)
+
+### Next Steps
+1. Add examples to remaining functions
+2. Create getting started guide
+3. Add architecture diagram
+```
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Documentation format
+- Required sections
+- Example requirements
+- API documentation tool

.claude/commands/feature.md

@@ -0,0 +1,191 @@
+# /feature - Feature Development Workflow
+
+## Purpose
+
+End-to-end feature development workflow that orchestrates planning, implementation guidance, testing, and code review.
+
+## Usage
+
+```
+/feature [feature description or issue reference]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: Feature description, issue number, or requirement specification
+
+---
+
+Implement a complete feature development workflow for: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Planning
+
+First, analyze the feature request and create an implementation plan:
+
+1. **Understand Requirements**
+   - Parse the feature description thoroughly
+   - Identify acceptance criteria
+   - List assumptions that need validation
+   - Clarify any ambiguous requirements with the user
+
+2. **Explore Codebase**
+   - Find related existing implementations
+   - Identify patterns and conventions to follow
+   - Locate integration points
+   - Note dependencies
+
+3. **Create Task Breakdown**
+   - Decompose into atomic, verifiable tasks
+   - Order tasks by dependencies
+   - Include testing requirements
+   - Estimate complexity (S/M/L)
+
+4. **Use TodoWrite** to track all tasks
+
+### Phase 2: Research (If Needed)
+
+If the feature involves unfamiliar technology:
+
+1. Research best practices and patterns
+2. Find examples in the codebase or documentation
+3. Identify potential pitfalls
+4. Document key decisions
+
+### Phase 3: Implementation Guidance
+
+For each implementation task:
+
+1. **Identify Target Files**
+   - Existing files to modify
+   - New files to create
+   - Tests to add/update
+
+2. **Provide Implementation Direction**
+   - Code structure recommendations
+   - Patterns to follow
+   - Edge cases to handle
+   - Error handling approach
+
+3. **Review Progress**
+   - Mark tasks complete as you go
+   - Identify blockers early
+   - Adjust plan if needed
+
+### Phase 4: Testing
+
+After implementation:
+
+1. **Generate Tests**
+   - Unit tests for new functions
+   - Integration tests for workflows
+   - Edge case coverage
+
+2. **Run Test Suite**
+   ```bash
+   # Python
+   pytest -v --cov=src
+
+   # TypeScript
+   pnpm test
+   ```
+
+3. **Verify Coverage**
+   - Ensure new code is tested
+   - Coverage should not decrease
+
+### Phase 5: Code Review
+
+Before completion:
+
+1. **Self-Review Checklist**
+   - [ ] Code follows project conventions
+   - [ ] No security vulnerabilities
+   - [ ] Error handling is complete
+   - [ ] Documentation updated
+   - [ ] Tests are passing
+
+2. **Review Staged Changes**
+   ```bash
+   git diff --staged
+   ```
+
+3. **Address Any Issues**
+   - Fix critical issues immediately
+   - Note recommendations for future
+
+### Phase 6: Completion
+
+1. **Verify All Tasks Complete**
+   - All TodoWrite items done
+   - All tests passing
+   - Documentation updated
+
+2. **Prepare for Commit**
+   - Stage appropriate files
+   - Generate commit message
+   - Create PR if requested
+
+## Output
+
+### Deliverables
+
+1. **Implementation Plan** - Structured task breakdown
+2. **Code Changes** - Feature implementation
+3. **Tests** - Comprehensive test coverage
+4. **Documentation** - Updated docs if needed
+5. **Commit/PR** - Ready for merge
+
+### Summary Format
+
+```markdown
+## Feature Implementation Complete
+
+### Feature
+[Feature description]
+
+### Changes Made
+- `path/to/file.ts` - [What was added/modified]
+- `path/to/file.test.ts` - [Tests added]
+
+### Tests
+- [x] Unit tests passing
+- [x] Integration tests passing
+- [x] Coverage: XX%
+
+### Documentation
+- [x] Code comments added
+- [x] README updated (if applicable)
+
+### Ready for Review
+```bash
+git status
+git diff --staged
+```
+
+### Next Steps
+1. Review changes
+2. Run full test suite
+3. Create PR
+```
+
+## Example
+
+**Input**: `/feature Add password reset functionality with email verification`
+
+**Output**:
+1. Plan with 8 tasks covering model, service, routes, email, tests
+2. Implementation of password reset flow
+3. Tests for happy path and error cases
+4. Updated API documentation
+5. Commit message and PR description
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Set minimum test coverage requirements
+- Define required documentation updates
+- Configure branch naming conventions
+- Set PR template requirements

.claude/commands/fix.md

@@ -0,0 +1,244 @@
+# /fix - Bug Fix Workflow
+
+## Purpose
+
+Smart debugging and bug fixing workflow that analyzes errors, identifies root causes, implements fixes, and adds regression tests.
+
+## Usage
+
+```
+/fix [error message, bug description, or issue reference]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: Error message, stack trace, bug description, or issue number
+
+---
+
+Analyze and fix the following issue: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Error Analysis
+
+1. **Parse Error Information**
+   - Extract error type and message
+   - Parse stack trace if available
+   - Identify the failing location
+
+2. **Gather Context**
+   - When does this error occur?
+   - What triggers it?
+   - Is it reproducible?
+   - When did it start happening?
+
+3. **Check for Known Patterns**
+   - Common error patterns
+   - Similar issues in codebase
+   - Recent changes that might have caused it
+
+### Phase 2: Root Cause Investigation
+
+1. **Trace Execution**
+   - Follow the code path to the error
+   - Identify state at each step
+   - Find where expectations diverge
+
+2. **Form Hypotheses**
+   - List possible causes ranked by likelihood
+   - Identify minimal tests to validate each
+
+3. **Validate Hypothesis**
+   - Test the most likely cause first
+   - Confirm root cause before fixing
+   - Don't fix symptoms only
+
+### Phase 3: Search Related Code
+
+1. **Find Similar Code**
+   - Search for similar patterns
+   - Check if same bug exists elsewhere
+   - Identify shared code that might be affected
+
+2. **Review Recent Changes**
+   ```bash
+   git log --oneline -20
+   git blame [file]
+   ```
+
+### Phase 4: Implement Fix
+
+1. **Develop Minimal Fix**
+   - Fix the root cause, not symptoms
+   - Keep changes minimal and focused
+   - Consider edge cases
+
+2. **Add Defensive Code** (if appropriate)
+   - Input validation
+   - Null checks
+   - Error handling
+
+3. **Update Related Code** (if needed)
+   - Fix same issue in similar code
+   - Update shared utilities
+
+### Phase 5: Verification
+
+1. **Test the Fix**
+   - Verify original error is resolved
+   - Check related functionality
+   - Run existing test suite
+
+2. **Add Regression Test**
+   - Write test that would have caught this bug
+   - Include edge cases discovered
+   - Ensure test fails without fix
+
+3. **Run Full Test Suite**
+   ```bash
+   # Python
+   pytest -v
+
+   # TypeScript
+   pnpm test
+   ```
+
+### Phase 6: Documentation
+
+1. **Document the Fix**
+   - What was the issue
+   - What caused it
+   - How it was fixed
+
+2. **Update Comments** (if needed)
+   - Add clarifying comments
+   - Document non-obvious behavior
+
+## Output
+
+### Bug Fix Summary
+
+```markdown
+## Bug Fix Complete
+
+### Issue
+[Original error/bug description]
+
+### Root Cause
+[Explanation of what caused the bug]
+
+### Location
+`path/to/file.ts:42` - [function/method name]
+
+### Fix Applied
+
+**Before:**
+```[language]
+// Problematic code
+```
+
+**After:**
+```[language]
+// Fixed code
+```
+
+### Explanation
+[Why this fix resolves the issue]
+
+### Regression Test Added
+`path/to/test.ts` - `test_[scenario]`
+
+### Verification
+- [x] Original error no longer occurs
+- [x] Existing tests pass
+- [x] New regression test passes
+- [x] No new issues introduced
+
+### Related Areas Checked
+- [x] `path/to/similar.ts` - No similar issue
+
+### Commands to Verify
+```bash
+pytest tests/test_file.py -v
+# or
+pnpm test path/to/file.test.ts
+```
+```
+
+## Common Fix Patterns
+
+### Null/Undefined Access
+
+```typescript
+// Before
+const name = user.profile.name;
+
+// After
+const name = user?.profile?.name ?? 'Unknown';
+```
+
+### Missing Error Handling
+
+```python
+# Before
+data = json.loads(response.text)
+
+# After
+try:
+    data = json.loads(response.text)
+except json.JSONDecodeError as e:
+    logger.error(f"Invalid JSON response: {e}")
+    raise InvalidResponseError("Failed to parse response")
+```
+
+### Race Condition
+
+```typescript
+// Before
+const data = await fetchData();
+setState(data); // May be unmounted
+
+// After
+useEffect(() => {
+  let cancelled = false;
+  fetchData().then(data => {
+    if (!cancelled) setState(data);
+  });
+  return () => { cancelled = true; };
+}, []);
+```
+
+### Off-by-One Error
+
+```python
+# Before
+for i in range(len(items) + 1):  # IndexError
+    process(items[i])
+
+# After
+for i in range(len(items)):
+    process(items[i])
+# or
+for item in items:
+    process(item)
+```
+
+## Example
+
+**Input**: `/fix TypeError: Cannot read property 'email' of undefined in UserService.ts:45`
+
+**Output**:
+1. Analysis: User object is undefined when accessed
+2. Root cause: async fetch didn't await, user not loaded yet
+3. Fix: Add null check and proper async handling
+4. Regression test: Test for case when user is not loaded
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Set required test coverage for fixes
+- Define severity levels for bugs
+- Configure error reporting format
+- Set required review process

.claude/commands/help.md

@@ -0,0 +1,59 @@
+# /help - Help Command
+
+## Purpose
+
+Display available commands and their usage.
+
+## Usage
+
+```
+/help [command name]
+```
+
+---
+
+Show help for: **$ARGUMENTS**
+
+## Available Commands
+
+### Development Workflow
+| Command | Description |
+|---------|-------------|
+| `/feature` | Full feature development workflow |
+| `/fix` | Debug and fix bugs |
+| `/review` | Code review |
+| `/test` | Generate tests |
+| `/tdd` | Test-driven development |
+| `/refactor` | Improve code structure |
+
+### Git & Deployment
+| Command | Description |
+|---------|-------------|
+| `/commit` | Create commit with message |
+| `/ship` | Commit + PR workflow |
+| `/pr` | Create pull request |
+| `/deploy` | Deploy to environment |
+
+### Documentation
+| Command | Description |
+|---------|-------------|
+| `/doc` | Generate documentation |
+| `/plan` | Create implementation plan |
+
+### Security & Quality
+| Command | Description |
+|---------|-------------|
+| `/security-scan` | Scan for vulnerabilities |
+| `/api-gen` | Generate API code |
+
+## Getting Help
+
+For detailed help on a specific command:
+```
+/help [command-name]
+```
+
+For general Claude Code help:
+```
+/help
+```

.claude/commands/optimize.md

@@ -0,0 +1,49 @@
+# /optimize - Performance Optimization Command
+
+## Purpose
+
+Analyze and optimize code performance.
+
+## Usage
+
+```
+/optimize [file or function]
+```
+
+---
+
+Optimize: **$ARGUMENTS**
+
+## Workflow
+
+1. **Analyze Current Performance**
+   - Identify bottlenecks
+   - Check complexity
+   - Profile if possible
+
+2. **Identify Opportunities**
+   - Algorithm improvements
+   - Caching opportunities
+   - Async optimizations
+
+3. **Implement Optimizations**
+   - Make targeted changes
+   - Verify improvements
+   - Ensure correctness
+
+## Output
+
+```markdown
+## Optimization Report
+
+### Before
+- Time complexity: O(n²)
+- Estimated time: 500ms
+
+### After
+- Time complexity: O(n log n)
+- Estimated time: 50ms
+
+### Changes Made
+- [Description of optimizations]
+```

.claude/commands/plan.md

@@ -0,0 +1,201 @@
+# /plan - Task Planning Command
+
+## Purpose
+
+Create structured implementation plans with task breakdown, dependencies, and time estimates for complex work.
+
+## Usage
+
+```
+/plan [task description or feature request]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: Description of the task, feature, or work to plan
+
+---
+
+Create a detailed implementation plan for: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Understanding
+
+1. **Parse Requirements**
+   - Identify core functionality needed
+   - List explicit requirements
+   - Note implicit requirements
+   - Identify acceptance criteria
+
+2. **Clarify Ambiguities**
+   - Ask questions if unclear
+   - List assumptions made
+   - Note dependencies on decisions
+
+### Phase 2: Research
+
+1. **Explore Codebase**
+   - Find related implementations
+   - Identify patterns to follow
+   - Locate integration points
+   - Note conventions
+
+2. **Technical Research** (if needed)
+   - Research unfamiliar technologies
+   - Find best practices
+   - Identify potential pitfalls
+
+### Phase 3: Task Breakdown
+
+1. **Decompose Work**
+   - Break into atomic tasks
+   - Each task: 15-60 minutes
+   - Clear completion criteria
+
+2. **Order by Dependencies**
+   - What blocks what
+   - Parallel opportunities
+   - Critical path
+
+3. **Add Estimates**
+   - S: <30 min
+   - M: 30-60 min
+   - L: 1-2 hours
+   - XL: 2-4 hours
+
+### Phase 4: Documentation
+
+1. **Create Plan Document**
+   - Summary
+   - Task list
+   - Files to modify
+   - Risks
+
+2. **Track with TodoWrite**
+   - Add all tasks
+   - Set initial status
+
+## Output
+
+### Implementation Plan
+
+```markdown
+## Plan: [Feature/Task Name]
+
+### Summary
+[2-3 sentence overview of what will be built]
+
+### Scope
+
+**In Scope**
+- [What will be done]
+
+**Out of Scope**
+- [What won't be done]
+
+**Assumptions**
+- [Key assumptions made]
+
+---
+
+### Tasks
+
+#### Phase 1: Setup [Total: Xh]
+| # | Task | Size | Depends On |
+|---|------|------|------------|
+| 1 | Create data model | M | - |
+| 2 | Set up database migration | S | 1 |
+| 3 | Add model tests | M | 1 |
+
+#### Phase 2: Core Implementation [Total: Xh]
+| # | Task | Size | Depends On |
+|---|------|------|------------|
+| 4 | Implement service layer | L | 1 |
+| 5 | Add business logic | M | 4 |
+| 6 | Write service tests | M | 5 |
+
+#### Phase 3: API Layer [Total: Xh]
+| # | Task | Size | Depends On |
+|---|------|------|------------|
+| 7 | Create API endpoints | M | 5 |
+| 8 | Add validation | S | 7 |
+| 9 | Write API tests | M | 8 |
+
+#### Phase 4: Integration [Total: Xh]
+| # | Task | Size | Depends On |
+|---|------|------|------------|
+| 10 | Integrate with frontend | M | 7 |
+| 11 | End-to-end testing | M | 10 |
+| 12 | Update documentation | S | 11 |
+
+---
+
+### Files to Create/Modify
+
+**Create**
+- `src/models/feature.py` - Data model
+- `src/services/feature.py` - Business logic
+- `src/api/feature.py` - API endpoints
+- `tests/test_feature.py` - Tests
+
+**Modify**
+- `src/api/__init__.py` - Register routes
+- `docs/api.md` - API documentation
+
+---
+
+### Dependencies
+
+**External**
+- [Package X] - For [purpose]
+
+**Internal**
+- Requires [existing feature] to be complete
+
+---
+
+### Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk 1] | High | [How to mitigate] |
+| [Risk 2] | Medium | [How to mitigate] |
+
+---
+
+### Questions for Stakeholders
+1. [Question about requirement]
+2. [Question about edge case]
+
+---
+
+### Success Criteria
+- [ ] All tasks completed
+- [ ] Tests passing with 80%+ coverage
+- [ ] API documentation updated
+- [ ] Code reviewed and approved
+```
+
+## Plan Templates
+
+### Feature Plan
+For new functionality
+
+### Bug Fix Plan
+For debugging and fixing issues
+
+### Refactor Plan
+For code improvements
+
+### Migration Plan
+For data or system migrations
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Task size definitions
+- Required plan sections
+- Estimation approach
+- Risk assessment criteria

.claude/commands/pr.md

@@ -0,0 +1,70 @@
+# /pr - Create Pull Request
+
+## Purpose
+
+Create a well-documented pull request with proper description and checks.
+
+## Usage
+
+```
+/pr [title or 'auto']
+```
+
+---
+
+Create a pull request: **$ARGUMENTS**
+
+## Workflow
+
+### Step 1: Prepare Changes
+
+```bash
+git status
+git diff main...HEAD
+```
+
+### Step 2: Verify Ready
+
+- [ ] All tests passing
+- [ ] Code reviewed
+- [ ] No merge conflicts
+- [ ] Branch pushed
+
+### Step 3: Create PR
+
+```bash
+gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
+## Summary
+- [Change 1]
+- [Change 2]
+
+## Test Plan
+- [ ] Unit tests
+- [ ] Manual testing
+
+## Screenshots
+[If applicable]
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] No breaking changes
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+## Output
+
+```markdown
+## Pull Request Created
+
+**URL**: https://github.com/org/repo/pull/123
+**Title**: feat(auth): add OAuth support
+**Base**: main ← feature/oauth
+
+### Changes
+- 5 files changed
+- +234 -12 lines
+```

.claude/commands/refactor.md

@@ -0,0 +1,59 @@
+# /refactor - Refactoring Command
+
+## Purpose
+
+Improve code structure, readability, or performance without changing behavior.
+
+## Usage
+
+```
+/refactor [file or function] [goal: clean | extract | simplify | optimize]
+```
+
+---
+
+Refactor: **$ARGUMENTS**
+
+## Workflow
+
+### Step 1: Understand Current Code
+
+1. Read the code thoroughly
+2. Identify what it does
+3. Note existing tests
+
+### Step 2: Plan Refactoring
+
+1. Identify improvement opportunities
+2. Ensure tests exist
+3. Plan incremental changes
+
+### Step 3: Execute
+
+1. Make small, focused changes
+2. Run tests after each change
+3. Commit incrementally
+
+## Refactoring Types
+
+- **Extract**: Pull out reusable functions
+- **Simplify**: Reduce complexity
+- **Rename**: Improve clarity
+- **Clean**: Remove dead code
+
+## Output
+
+```markdown
+## Refactoring Complete
+
+### Changes Made
+- Extracted `validateInput()` function
+- Simplified conditional logic
+- Renamed `x` to `userCount`
+
+### Before/After
+[Code comparison]
+
+### Tests
+All passing
+```

.claude/commands/research.md

@@ -0,0 +1,54 @@
+# /research - Research Command
+
+## Purpose
+
+Research a technology, library, or approach with comprehensive analysis.
+
+## Usage
+
+```
+/research [topic or technology]
+```
+
+---
+
+Research: **$ARGUMENTS**
+
+## Workflow
+
+1. **Gather Information**
+   - Official documentation
+   - Community resources
+   - Comparisons
+
+2. **Analyze**
+   - Pros and cons
+   - Best practices
+   - Alternatives
+
+3. **Recommend**
+   - Summary
+   - Recommendation
+   - Next steps
+
+## Output
+
+```markdown
+## Research: [Topic]
+
+### Summary
+[Overview]
+
+### Pros
+- [Pro 1]
+- [Pro 2]
+
+### Cons
+- [Con 1]
+
+### Alternatives
+[Comparison table]
+
+### Recommendation
+[Clear recommendation]
+```

.claude/commands/review.md

@@ -0,0 +1,262 @@
+# /review - Code Review Command
+
+## Purpose
+
+Comprehensive code review with focus on quality, security, performance, and maintainability.
+
+## Usage
+
+```
+/review [file path | 'staged' | 'pr' | PR number]
+```
+
+## Arguments
+
+- `$ARGUMENTS`:
+  - File path: Review specific file(s)
+  - `staged`: Review all staged changes
+  - `pr`: Review current branch changes vs main
+  - PR number: Review specific pull request
+
+---
+
+Perform a comprehensive code review for: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Identify Review Scope
+
+1. **Determine What to Review**
+   - Single file: Read the specified file
+   - `staged`: Get staged changes with `git diff --staged`
+   - `pr`: Get branch diff with `git diff main...HEAD`
+   - PR number: Fetch PR details with `gh pr view`
+
+2. **Gather Context**
+   - Understand the purpose of changes
+   - Check related tests
+   - Review CLAUDE.md for project standards
+
+### Phase 2: Code Quality Review
+
+Check each file for:
+
+1. **Correctness**
+   - Logic errors and bugs
+   - Edge case handling
+   - Null/undefined safety
+   - Type correctness
+
+2. **Clarity**
+   - Clear naming (variables, functions, classes)
+   - Readable structure
+   - Appropriate comments
+   - Self-documenting code
+
+3. **Consistency**
+   - Follows project conventions
+   - Matches existing patterns
+   - Style guide compliance
+
+4. **Complexity**
+   - Function length (prefer <30 lines)
+   - Cyclomatic complexity
+   - Nesting depth
+
+### Phase 3: Security Review
+
+Check for security issues:
+
+1. **Input Validation**
+   - User input sanitization
+   - Type validation
+   - Size/length limits
+
+2. **Authentication/Authorization**
+   - Proper auth checks
+   - Role-based access control
+   - Session management
+
+3. **Data Protection**
+   - Sensitive data handling
+   - Encryption where needed
+   - PII protection
+
+4. **Injection Prevention**
+   - SQL injection
+   - XSS vulnerabilities
+   - Command injection
+
+5. **Secrets**
+   - No hardcoded credentials
+   - No API keys in code
+   - Proper env var usage
+
+### Phase 4: Performance Review
+
+Check for performance issues:
+
+1. **Algorithmic Efficiency**
+   - Time complexity
+   - Unnecessary loops
+   - Redundant operations
+
+2. **Memory Usage**
+   - Large object creation
+   - Memory leaks
+   - Unbounded caches
+
+3. **Database**
+   - N+1 queries
+   - Missing indexes
+   - Large result sets
+
+4. **Async Operations**
+   - Proper async/await
+   - Parallel where possible
+   - Timeout handling
+
+### Phase 5: Maintainability Review
+
+Check for maintainability:
+
+1. **SOLID Principles**
+   - Single responsibility
+   - Open/closed
+   - Dependency injection
+
+2. **DRY**
+   - Code duplication
+   - Opportunity for reuse
+
+3. **Testing**
+   - Test coverage
+   - Test quality
+   - Edge case tests
+
+4. **Documentation**
+   - API documentation
+   - Complex logic explanation
+   - Usage examples
+
+## Output Format
+
+```markdown
+## Code Review: [Target]
+
+**Reviewed**: [files/changes]
+**Verdict**: [Approve | Request Changes | Needs Discussion]
+
+---
+
+### Critical Issues (Must Fix)
+
+#### 1. [Security] SQL Injection Risk
+**File**: `src/api/users.ts:42`
+**Severity**: Critical
+
+```typescript
+// Current code
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+```
+
+**Issue**: User input directly interpolated into SQL query.
+
+**Fix**:
+```typescript
+const query = 'SELECT * FROM users WHERE id = $1';
+const result = await db.query(query, [userId]);
+```
+
+---
+
+### Recommendations (Should Fix)
+
+#### 1. Missing Error Handling
+**File**: `src/services/auth.ts:78`
+
+```typescript
+// Current
+const user = await db.findUser(email);
+return user.password; // May throw if user is null
+```
+
+**Suggestion**:
+```typescript
+const user = await db.findUser(email);
+if (!user) {
+  throw new NotFoundError('User not found');
+}
+return user.password;
+```
+
+---
+
+### Suggestions (Nice to Have)
+
+1. Consider extracting the validation logic in `src/utils/validate.ts:23` into a separate function for reusability.
+
+2. The constant `MAX_RETRIES` in `src/api/client.ts` could be moved to configuration.
+
+---
+
+### What's Good
+
+- Clean separation of concerns between controller and service layers
+- Comprehensive error handling in the authentication flow
+- Good test coverage for edge cases in `auth.test.ts`
+
+---
+
+### Summary
+
+Found **1 critical issue** (security), **2 recommendations**, and **2 suggestions**.
+
+**Priority Actions**:
+1. Fix SQL injection vulnerability immediately
+2. Add null check for user lookup
+
+**Ready for merge**: No - Critical issues must be addressed first
+```
+
+## Review Checklist
+
+### Security
+- [ ] No hardcoded secrets
+- [ ] Input validation present
+- [ ] Output encoding for rendered content
+- [ ] SQL parameterization
+- [ ] Proper auth checks
+- [ ] No eval() or dynamic code execution
+
+### Quality
+- [ ] Clear naming conventions
+- [ ] Functions are focused (single responsibility)
+- [ ] Error handling is complete
+- [ ] No commented-out code
+- [ ] No debug statements left
+
+### Testing
+- [ ] New code has tests
+- [ ] Edge cases covered
+- [ ] Tests are deterministic
+
+### Documentation
+- [ ] Public APIs documented
+- [ ] Complex logic explained
+- [ ] Breaking changes noted
+
+## Example
+
+**Input**: `/review staged`
+
+**Output**: Complete review of all staged changes with security scan, code quality assessment, and actionable feedback organized by severity.
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Set required review checklist items
+- Define severity levels
+- Configure approval criteria
+- Set documentation requirements

.claude/commands/security-scan.md

@@ -0,0 +1,52 @@
+# /security-scan - Security Scanning Command
+
+## Purpose
+
+Scan code and dependencies for security vulnerabilities.
+
+## Usage
+
+```
+/security-scan [scope: deps | code | secrets | all]
+```
+
+---
+
+Run security scan: **$ARGUMENTS**
+
+## Workflow
+
+### Dependency Scan
+
+```bash
+npm audit
+pip-audit
+```
+
+### Code Scan
+
+- SQL injection patterns
+- XSS vulnerabilities
+- Command injection
+
+### Secret Detection
+
+- API keys
+- Passwords
+- Tokens
+
+## Output
+
+```markdown
+## Security Scan Results
+
+### Summary
+| Type | Critical | High | Medium |
+|------|----------|------|--------|
+| Dependencies | 0 | 2 | 5 |
+| Code | 0 | 1 | 3 |
+| Secrets | 0 | 0 | 0 |
+
+### Findings
+[Detailed findings with remediation]
+```

.claude/commands/ship.md

@@ -0,0 +1,217 @@
+# /ship - Ship Code Command
+
+## Purpose
+
+Complete workflow to commit changes, run reviews, execute tests, and create a pull request ready for merge.
+
+## Usage
+
+```
+/ship [commit message or 'quick']
+```
+
+## Arguments
+
+- `$ARGUMENTS`:
+  - Commit message: Use as commit subject
+  - `quick`: Auto-generate message, skip review
+
+---
+
+Ship the current changes with: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Pre-Ship Checks
+
+1. **Check Repository Status**
+   ```bash
+   git status
+   git diff --staged
+   ```
+
+2. **Identify Changes**
+   - Files modified
+   - Files added
+   - Files deleted
+
+3. **Quick Validation**
+   - No secrets in changes
+   - No debug statements
+   - No commented-out code
+
+### Phase 2: Code Review (unless 'quick')
+
+1. **Run Self-Review**
+   - Check code quality
+   - Verify style compliance
+   - Identify security issues
+
+2. **Address Critical Issues**
+   - Fix any critical problems
+   - Note recommendations
+
+### Phase 3: Run Tests
+
+1. **Execute Test Suite**
+   ```bash
+   # Python
+   pytest -v
+
+   # TypeScript
+   pnpm test
+   ```
+
+2. **Verify All Pass**
+   - No failing tests
+   - No new warnings
+
+3. **Check Coverage**
+   - Coverage not decreased
+   - New code is tested
+
+### Phase 4: Create Commit
+
+1. **Stage Changes**
+   ```bash
+   git add -A
+   ```
+
+2. **Generate Commit Message**
+   - Follow conventional commit format
+   - Reference issues if applicable
+
+3. **Create Commit**
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   type(scope): subject
+
+   body
+
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+   Co-Authored-By: Claude <noreply@anthropic.com>
+   EOF
+   )"
+   ```
+
+### Phase 5: Push and Create PR
+
+1. **Push to Remote**
+   ```bash
+   git push -u origin [branch-name]
+   ```
+
+2. **Create Pull Request**
+   ```bash
+   gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
+   ## Summary
+   - Change 1
+   - Change 2
+
+   ## Test Plan
+   - [ ] Tests pass
+   - [ ] Manual testing
+
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   EOF
+   )"
+   ```
+
+## Output
+
+### Ship Report
+
+```markdown
+## Ship Complete
+
+### Commit
+**Hash**: `abc1234`
+**Message**: `feat(auth): add password reset functionality`
+
+### Changes
+| File | Change |
+|------|--------|
+| `src/auth/reset.ts` | Added |
+| `src/auth/routes.ts` | Modified |
+| `tests/auth/reset.test.ts` | Added |
+
+### Checks
+- [x] Code review passed
+- [x] Tests passing (42 tests)
+- [x] Coverage: 85% (+3%)
+- [x] No security issues
+
+### Pull Request
+**URL**: https://github.com/org/repo/pull/123
+**Title**: feat(auth): add password reset functionality
+**Base**: main
+**Status**: Ready for review
+
+### Next Steps
+1. Request review from team
+2. Address any feedback
+3. Merge when approved
+```
+
+## Quick Ship Mode
+
+When using `/ship quick`:
+- Skip detailed code review
+- Auto-generate commit message
+- Minimal output
+
+```bash
+# Quick ship for small changes
+/ship quick
+```
+
+## Commit Message Generation
+
+Based on changes, generate appropriate message:
+
+### Feature
+```
+feat(scope): add [feature]
+
+- Added [component/function]
+- Implemented [functionality]
+- Added tests for [scenarios]
+```
+
+### Bug Fix
+```
+fix(scope): resolve [issue]
+
+- Fixed [bug description]
+- Added null check for [case]
+- Updated tests
+```
+
+### Refactor
+```
+refactor(scope): improve [area]
+
+- Extracted [logic] to [location]
+- Renamed [old] to [new]
+- Simplified [complex code]
+```
+
+## Pre-Ship Checklist
+
+- [ ] All changes staged
+- [ ] No unintended files included
+- [ ] Tests pass
+- [ ] No secrets in code
+- [ ] No debug statements
+- [ ] Commit message is descriptive
+- [ ] PR description is complete
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Required checks before ship
+- Commit message format
+- PR template requirements
+- Auto-merge settings

.claude/commands/status.md

@@ -0,0 +1,55 @@
+# /status - Project Status Command
+
+## Purpose
+
+Get current project status including tasks, git state, and recent activity.
+
+## Usage
+
+```
+/status
+```
+
+---
+
+Show current project status.
+
+## Workflow
+
+1. **Check Git Status**
+   ```bash
+   git status
+   git log --oneline -5
+   ```
+
+2. **Review Todos**
+   - In progress
+   - Pending
+   - Completed today
+
+3. **Recent Activity**
+   - Recent commits
+   - Open PRs
+   - Open issues
+
+## Output
+
+```markdown
+## Project Status
+
+### Git
+- Branch: `feature/xyz`
+- Status: Clean / X modified files
+
+### Tasks
+- In Progress: X
+- Pending: Y
+- Completed: Z
+
+### Recent Commits
+1. [commit message]
+2. [commit message]
+
+### Open PRs
+- #123: [title]
+```

.claude/commands/tdd.md

@@ -0,0 +1,88 @@
+# /tdd - Test-Driven Development Workflow
+
+## Purpose
+
+Start a TDD workflow: write failing tests first, then implement to make them pass.
+
+## Usage
+
+```
+/tdd [feature or function description]
+```
+
+---
+
+Start TDD workflow for: **$ARGUMENTS**
+
+## Workflow
+
+### Phase 1: Red - Write Failing Tests
+
+1. **Understand Requirements**
+   - What should the code do?
+   - What are the inputs/outputs?
+   - What edge cases exist?
+
+2. **Write Tests First**
+   ```python
+   def test_feature_does_expected_thing():
+       result = feature("input")
+       assert result == "expected"
+   ```
+
+3. **Run Tests (Expect Failure)**
+   ```bash
+   pytest -v  # Should fail
+   ```
+
+### Phase 2: Green - Make Tests Pass
+
+1. **Implement Minimal Code**
+   - Just enough to pass tests
+   - No premature optimization
+
+2. **Run Tests (Expect Success)**
+   ```bash
+   pytest -v  # Should pass
+   ```
+
+### Phase 3: Refactor
+
+1. **Improve Code Quality**
+   - Clean up implementation
+   - Remove duplication
+   - Improve naming
+
+2. **Run Tests (Ensure Still Passing)**
+   ```bash
+   pytest -v  # Should still pass
+   ```
+
+### Phase 4: Repeat
+
+Add more test cases and repeat the cycle.
+
+## TDD Best Practices
+
+- Write one test at a time
+- Tests should be specific and focused
+- Keep the red-green-refactor cycle short
+- Commit after each green phase
+
+## Output
+
+```markdown
+## TDD Session: [Feature]
+
+### Tests Written
+1. `test_basic_functionality` - [description]
+2. `test_edge_case` - [description]
+
+### Implementation
+`src/feature.py` - [description]
+
+### Cycle Summary
+- Red: 3 tests written
+- Green: All passing
+- Refactor: Extracted helper function
+```

.claude/commands/test.md

@@ -0,0 +1,259 @@
+# /test - Test Generation Command
+
+## Purpose
+
+Generate comprehensive tests for specified code including unit tests, integration tests, and edge cases.
+
+## Usage
+
+```
+/test [file path | function name | 'coverage' | 'all']
+```
+
+## Arguments
+
+- `$ARGUMENTS`:
+  - File path: Generate tests for specific file
+  - Function name: Generate tests for specific function
+  - `coverage`: Analyze and improve test coverage
+  - `all`: Run all tests and report results
+
+---
+
+Generate comprehensive tests for: **$ARGUMENTS**
+
+## Workflow
+
+### For File/Function Testing
+
+1. **Analyze Target Code**
+   - Read the code to understand functionality
+   - Identify inputs, outputs, and side effects
+   - Note dependencies to mock
+   - Find existing tests for patterns
+
+2. **Design Test Cases**
+   - **Happy Path**: Normal operation with valid inputs
+   - **Edge Cases**: Boundary values, empty inputs, limits
+   - **Error Cases**: Invalid inputs, exceptions
+   - **Integration Points**: External dependencies
+
+3. **Generate Tests**
+   - Follow project testing conventions
+   - Use appropriate mocking strategies
+   - Write clear, descriptive test names
+   - Include setup and teardown
+
+4. **Run and Verify**
+   ```bash
+   # Python
+   pytest [test_file] -v
+
+   # TypeScript
+   pnpm test [test_file]
+   ```
+
+### For Coverage Analysis
+
+1. **Run Coverage Report**
+   ```bash
+   # Python
+   pytest --cov=src --cov-report=term-missing
+
+   # TypeScript
+   pnpm test --coverage
+   ```
+
+2. **Identify Gaps**
+   - Find untested functions
+   - Identify untested branches
+   - Note missing edge cases
+
+3. **Generate Missing Tests**
+   - Prioritize by risk
+   - Focus on critical paths
+   - Add edge case coverage
+
+## Test Templates
+
+### Python (pytest)
+
+```python
+import pytest
+from unittest.mock import Mock, patch
+from src.module import function_under_test
+
+class TestFunctionUnderTest:
+    """Tests for function_under_test."""
+
+    def test_with_valid_input_returns_expected(self):
+        """Test that valid input produces expected output."""
+        result = function_under_test("valid_input")
+        assert result == "expected_output"
+
+    def test_with_empty_input_returns_default(self):
+        """Test that empty input returns default value."""
+        result = function_under_test("")
+        assert result == "default"
+
+    def test_with_invalid_input_raises_error(self):
+        """Test that invalid input raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid input"):
+            function_under_test(None)
+
+    @pytest.mark.parametrize("input_val,expected", [
+        ("a", "result_a"),
+        ("b", "result_b"),
+        ("c", "result_c"),
+    ])
+    def test_parametrized_inputs(self, input_val, expected):
+        """Test multiple input variations."""
+        assert function_under_test(input_val) == expected
+
+    @patch('src.module.external_service')
+    def test_with_mocked_dependency(self, mock_service):
+        """Test with mocked external dependency."""
+        mock_service.call.return_value = "mocked_result"
+        result = function_under_test("input")
+        assert result == "expected_with_mock"
+        mock_service.call.assert_called_once_with("input")
+```
+
+### TypeScript (vitest)
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { functionUnderTest } from './module';
+
+describe('functionUnderTest', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return expected output for valid input', () => {
+    const result = functionUnderTest('valid_input');
+    expect(result).toBe('expected_output');
+  });
+
+  it('should return default for empty input', () => {
+    const result = functionUnderTest('');
+    expect(result).toBe('default');
+  });
+
+  it('should throw error for invalid input', () => {
+    expect(() => functionUnderTest(null)).toThrow('Invalid input');
+  });
+
+  it.each([
+    ['a', 'result_a'],
+    ['b', 'result_b'],
+    ['c', 'result_c'],
+  ])('should handle input %s correctly', (input, expected) => {
+    expect(functionUnderTest(input)).toBe(expected);
+  });
+
+  it('should work with mocked dependency', async () => {
+    vi.mock('./external-service', () => ({
+      call: vi.fn().mockResolvedValue('mocked_result'),
+    }));
+
+    const result = await functionUnderTest('input');
+    expect(result).toBe('expected_with_mock');
+  });
+});
+```
+
+### React Component (Testing Library)
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { UserForm } from './UserForm';
+
+describe('UserForm', () => {
+  it('should render form fields', () => {
+    render(<UserForm onSubmit={vi.fn()} />);
+
+    expect(screen.getByLabelText(/name/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument();
+  });
+
+  it('should call onSubmit with form data', async () => {
+    const onSubmit = vi.fn();
+    render(<UserForm onSubmit={onSubmit} />);
+
+    fireEvent.change(screen.getByLabelText(/name/i), {
+      target: { value: 'John' },
+    });
+    fireEvent.change(screen.getByLabelText(/email/i), {
+      target: { value: 'john@example.com' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: /submit/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({
+        name: 'John',
+        email: 'john@example.com',
+      });
+    });
+  });
+
+  it('should show validation error for invalid email', async () => {
+    render(<UserForm onSubmit={vi.fn()} />);
+
+    fireEvent.change(screen.getByLabelText(/email/i), {
+      target: { value: 'invalid' },
+    });
+    fireEvent.blur(screen.getByLabelText(/email/i));
+
+    expect(await screen.findByText(/invalid email/i)).toBeInTheDocument();
+  });
+});
+```
+
+## Output
+
+### Test Generation Report
+
+```markdown
+## Tests Generated
+
+### Target
+`src/services/auth.ts` - AuthService class
+
+### Tests Created
+- `tests/services/auth.test.ts`
+
+### Test Cases
+1. `login_with_valid_credentials_returns_token` - Happy path
+2. `login_with_invalid_password_throws_error` - Error case
+3. `login_with_nonexistent_user_throws_error` - Error case
+4. `refresh_token_with_valid_token_returns_new_token` - Happy path
+5. `refresh_token_with_expired_token_throws_error` - Edge case
+6. `logout_invalidates_session` - Happy path
+
+### Coverage Impact
+- Before: 65%
+- After: 88%
+- New lines covered: 42
+
+### Run Tests
+```bash
+pytest tests/services/auth.test.ts -v
+```
+
+### Notes
+- Mocked database calls using pytest-mock
+- Added edge case for token expiration
+- Consider adding integration tests for full auth flow
+```
+
+<!-- CUSTOMIZATION POINT -->
+## Variations
+
+Modify behavior via CLAUDE.md:
+- Preferred test framework
+- Minimum coverage targets
+- Test naming conventions
+- Required test categories