# CLAUDE.md

## Development Guidelines

If you need clarification please ask. Do not overcomplicate things - try to reduce complexity without reducing functionality and keep the solution concise. Provide honest, balanced feedback without excessive praise or flattery.

### Code Style and Conventions
- Follow existing code patterns and conventions in the codebase
- Use TypeScript for type safety
- Maintain consistent formatting across files
- NO comments unless explicitly requested
- Prefer editing existing files over creating new ones
- Only use emojis if the user explicitly requests it

### Before Making Changes
- First understand the file's existing code conventions
- Check neighboring files for patterns and library usage
- Verify libraries/frameworks are already in use
- Never assume a library is available without checking
- Follow existing import patterns and framework choices

### Task Management Best Practices
- For complex multi-step tasks (3+ steps), use a structured approach
- Break down complex features into manageable subtasks
- Track progress systematically
- Update task status in real-time
- Complete current tasks before starting new ones
- Document implementation details and decisions

### Security and Best Practices
- Never expose or log secrets and keys
- Never commit secrets to the repository
- Follow security best practices
- Maintain clean, idiomatic code
- Ensure all changes result in working code

## Code Documentation Best Practices

### Documentation Structure
When documenting patterns and conventions, follow this format:
```markdown
---
description: Clear, one-line description of what the pattern enforces
scope: path/to/files/*.ext, other/path/**/*
priority: boolean
---

- **Main Points in Bold**
  - Sub-points with details
  - Examples and explanations
```

### File References
- Use markdown links to reference files
- Example: [package.json](package.json) for code references
- Keep references relative to project root

### Code Examples
Use language-specific code blocks with good/bad examples:
```typescript
// ✅ DO: Show good examples
const goodExample = true;

// ❌ DON'T: Show anti-patterns
const badExample = false;
```

## Continuous Improvement

### Rule Improvement Triggers
- New code patterns not covered by existing rules
- Pattern appears in 3+ files (consider standardizing)
- Common bugs that could be prevented by a rule
- Code reviews repeatedly mention the same feedback
- New security or performance patterns emerge

### Rule Improvement Process
- Monitor for new code patterns not covered by existing rules
- When a pattern appears in 3+ files, consider standardizing it
- Update rules after major refactors or when better examples emerge
- Track common error patterns that could be prevented
- Document migration paths for deprecated patterns

### Pattern Recognition
- Compare new code with existing patterns
- Identify repeated implementations across files
- Look for consistent error handling approaches
- Monitor test patterns and coverage
- Cross-reference related documentation

### Rule Quality Guidelines
- Rules should be actionable and specific
- Examples should come from actual code
- References should be up to date
- Patterns should be consistently enforced
- Use bullet points for clarity
- Keep descriptions concise
- Include both DO and DON'T examples
- Reference actual code over theoretical examples

### Rule Maintenance
- Add new rules when patterns are used in 3+ files
- Modify rules when better examples exist
- Remove rules that no longer apply
- Mark outdated patterns as deprecated
- Document migration paths for deprecated patterns
- Update references to external docs
- Maintain links between related rules

## Taskmaster Overview

### Primary Interaction Methods

Task Master offers two ways to interact:

1. **MCP Server (Recommended for Integrated Tools)**:
   - Preferred method for AI agents and IDEs like Claude Code
   - Better performance, structured data exchange, and error handling
   - Exposed through MCP tools (e.g., `get_tasks`, `add_subtask`)
   - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool definitions change

2. **`task-master` CLI (For Users & Fallback)**:
   - User-friendly interface for direct terminal interaction
   - Fallback if MCP server is inaccessible
   - Install globally: `npm install -g task-master-ai`
   - Use locally: `npx task-master-ai ...`

### Configuration Management

1. **`.taskmaster/config.json` File (Primary)**:
   - Stores AI model selections, parameters, logging level, project settings
   - **Managed via `task-master models --setup` command**
   - **View/Set models via `task-master models` or `models` MCP tool**
   - DO NOT edit manually unless necessary

2. **Environment Variables (`.env` / `mcp.json`)**:
   - Used **only** for sensitive API keys and endpoint URLs
   - Place API keys in `.env` file (project root) for CLI usage
   - For MCP integration, configure keys in the MCP configuration's `env` section
   - Available keys: `ANTHROPIC_API_KEY`, `PERPLEXITY_API_KEY`, `OPENAI_API_KEY`, etc.

**Important**: If AI commands fail in MCP, verify API key exists in your MCP configuration. If failing in CLI, check `.env` file.

## Taskmaster Development Workflow

### Standard Development Process

1. (not needed as it will be likely done by user) **Initialize Project**: Run `initialize_project` / `task-master init`
2. (not needed as it will be likely done by user) **Parse PRD**: Use `parse_prd` / `task-master parse-prd --input='<prd-file.txt>'` to generate initial tasks
3. **Review Tasks**: Start with `get_tasks` / `task-master list` to see current status
4. **Find Next Task**: Use `next_task` / `task-master next` to identify what to work on
5. **Analyze Complexity**: Run `analyze_project_complexity` / `task-master analyze-complexity --research`
6. **Review Report**: Check with `complexity_report` / `task-master complexity-report`
7. **Expand Tasks**: Break down complex tasks with `expand_task` / `task-master expand --id=<id> --force --research`
8. **Implement**: Code following task details and project standards
9. **Update Status**: Mark completed with `set_task_status` / `task-master set-status --id=<id> --status=done`
10. **Update Dependencies**: When implementation differs, use `update` / `task-master update --from=<id> --prompt="..."`
11. **Add New Tasks**: For discovered work, use `add_task` / `task-master add-task --prompt="..." --research`
12. **Generate Files**: Run `generate` / `task-master generate` after updating tasks.json

### Task Status Management
- `pending`: Tasks ready to be worked on
- `in-progress`: Currently being worked on
- `done`: Completed and verified
- `review`: Awaiting review
- `deferred`: Postponed tasks
- `cancelled`: No longer needed

### Dependency Management
- Add: `add_dependency` / `task-master add-dependency --id=<id> --depends-on=<id>`
- Remove: `remove_dependency` / `task-master remove-dependency --id=<id> --depends-on=<id>`
- Validate: `validate_dependencies` / `task-master validate-dependencies`
- Fix: `fix_dependencies` / `task-master fix-dependencies`

### Task Reorganization
- Move tasks: `move_task` / `task-master move --from=<id> --to=<id>`
- Supports moving tasks to become subtasks, subtasks to tasks, reordering, etc.
- Useful for resolving merge conflicts in tasks.json

### Iterative Subtask Implementation

1. **Understand Goal**: Use `get_task` / `task-master show <subtaskId>`
2. **Initial Exploration**: Identify files, functions, and code changes needed
3. **Log Plan**: Run `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<detailed plan>'`
4. **Verify Plan**: Check with `get_task` to confirm plan was logged
5. **Begin Implementation**: Set status to `in-progress`
6. **Refine and Log Progress**: Regularly update with findings:
   - What worked (fundamental truths)
   - What didn't work and why
   - Successful code snippets
   - Decisions made
   - Deviations from plan
7. **Review & Update Documentation**: After implementation, update relevant documentation and patterns in this file
8. **Mark Complete**: Set status to `done`
9. **Commit Changes**: Create comprehensive commit with code and rule updates
10. **Next Subtask**: Move to next task with `next_task`

## Taskmaster Quick Reference

### Essential Commands
- `task-master init` - Initialize project
- `task-master list` - View all tasks
- `task-master next` - Show next task to work on
- `task-master show <id>` - View task details
- `task-master add-task -p "<description>"` - Add new task
- `task-master set-status -i <id> -s done` - Mark task complete
- `task-master expand -i <id>` - Break down complex task
- `task-master update-subtask -i <id> -p "<notes>"` - Add implementation notes

### Task Workflow
1. Start with `task-master list` to see current status
2. Use `task-master next` to identify what to work on
3. Break down complex tasks with `task-master expand`
4. Track progress with `task-master set-status`
5. Document findings with `task-master update-subtask`

### Important Notes
- AI-powered operations may take up to a minute
- Always check dependencies before starting tasks
- Use `--research` flag for external knowledge when needed
- Maintain task files with `task-master generate` after changes

## Taskmaster Command Reference

### Initialization & Setup

#### Initialize Project
- **MCP**: `initialize_project`
- **CLI**: `task-master init`
- **Options**: `--name`, `--description`, `--version`, `-y/--yes`
- **Important**: Must parse PRD after init to generate tasks

#### Parse PRD
- **MCP**: `parse_prd`
- **CLI**: `task-master parse-prd [file]`
- **Options**: `--input`, `--output`, `--num-tasks`, `--force`
- **Note**: AI-powered, may take up to a minute

### AI Model Configuration

#### Manage Models
- **MCP**: `models`
- **CLI**: `task-master models`
- **Options**: `--set-main`, `--set-research`, `--set-fallback`, `--ollama`, `--openrouter`, `--setup`
- **Note**: Configuration stored in `.taskmaster/config.json`

### Task Viewing

#### List Tasks
- **MCP**: `get_tasks`
- **CLI**: `task-master list`
- **Options**: `--status`, `--with-subtasks`, `--file`

#### Next Task
- **MCP**: `next_task`
- **CLI**: `task-master next`
- **Shows**: Task with all dependencies satisfied

#### Show Task
- **MCP**: `get_task`
- **CLI**: `task-master show <id>`
- **Supports**: Task IDs (e.g., "5") and subtask IDs (e.g., "5.2")

### Task Modification

#### Add Task
- **MCP**: `add_task`
- **CLI**: `task-master add-task`
- **Required**: `--prompt`
- **Options**: `--dependencies`, `--priority`, `--research`

#### Add Subtask
- **MCP**: `add_subtask`
- **CLI**: `task-master add-subtask`
- **Required**: Parent ID and either title or task-id
- **Options**: `--parent`, `--title`, `--description`, `--details`

#### Update Multiple Tasks
- **MCP**: `update`
- **CLI**: `task-master update`
- **Required**: `--from`, `--prompt`
- **Updates**: All tasks from ID onward

#### Update Single Task
- **MCP**: `update_task`
- **CLI**: `task-master update-task`
- **Required**: `--id`, `--prompt`

#### Update Subtask
- **MCP**: `update_subtask`
- **CLI**: `task-master update-subtask`
- **Required**: `--id` (format: "parent.subtask"), `--prompt`
- **Purpose**: Append timestamped implementation notes

#### Set Status
- **MCP**: `set_task_status`
- **CLI**: `task-master set-status`
- **Required**: `--id`, `--status`
- **Statuses**: pending, in-progress, done, review, deferred, cancelled

### Task Structure

#### Expand Task
- **MCP**: `expand_task`
- **CLI**: `task-master expand`
- **Options**: `--id`, `--num`, `--research`, `--force`, `--prompt`
- **Note**: Uses complexity report if available

#### Expand All
- **MCP**: `expand_all`
- **CLI**: `task-master expand --all`
- **Expands**: All eligible pending/in-progress tasks

#### Clear Subtasks
- **MCP**: `clear_subtasks`
- **CLI**: `task-master clear-subtasks`
- **Options**: `--id` or `--all`

#### Move Task
- **MCP**: `move_task`
- **CLI**: `task-master move`
- **Required**: `--from`, `--to`
- **Supports**: Multiple moves with comma-separated IDs

### Analysis & Reporting

#### Analyze Complexity
- **MCP**: `analyze_project_complexity`
- **CLI**: `task-master analyze-complexity`
- **Options**: `--threshold`, `--research`, `--output`

#### View Complexity Report
- **MCP**: `complexity_report`
- **CLI**: `task-master complexity-report`

### File Management

#### Generate Task Files
- **MCP**: `generate`
- **CLI**: `task-master generate`
- **Creates**: Individual markdown files for each task

### Task Structure Fields
- **id**: Unique identifier (e.g., "1", "1.1")
- **title**: Brief descriptive title
- **description**: Concise summary
- **status**: Current state
- **dependencies**: Prerequisite task IDs
- **priority**: high, medium, or low
- **details**: Implementation instructions
- **testStrategy**: Verification approach
- **subtasks**: Nested task list