claudemaster/CLAUDE.md

Task management MCP server optimized for Claude Code - no API keys required

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with Claudemaster.

## Overview

Claudemaster is a task management MCP server specifically optimized for Claude Code integration. Unlike traditional task management tools, it requires **no API keys** and leverages Claude Code's native capabilities for intelligent task management.

## Commands

### Development & Testing
```bash
npm test                    # Run all tests
npm run test:watch         # Run tests in watch mode  
npm run test:coverage      # Run tests with coverage
npm run format             # Format code with Biome
npm run format-check       # Check code formatting
npm run mcp-server         # Start Claudemaster MCP server
```

### Using Claudemaster in Claude Code
```bash
# Install Claudemaster
npm install -g claudemaster

# Or use directly with npx
npx claudemaster
```

## Architecture

### Core Structure (Simplified from Task Master)
- **MCP Server**: `mcp-server/server.js` - Main entry point for Claudemaster
- **Task Engine**: `mcp-server/src/core/task-engine.js` - Pure task operations (no AI dependencies)
- **Claude Templates**: `mcp-server/src/core/claude-templates.js` - Optimized prompts for Claude Code
- **MCP Tools**: `mcp-server/src/tools/` - Claude Code optimized tools

### Key Differences from Task Master
- **No AI Providers**: Removed all external AI service dependencies
- **No API Keys**: Works entirely within Claude Code's capabilities  
- **Simplified Dependencies**: Only 4 core packages (fastmcp, chalk, uuid, zod)
- **Claude-Optimized**: Every tool designed for Claude Code workflows

### Task Management Flow
1. **Initialize Project**: `initialize_claudemaster` sets up `.taskmaster/` directory
2. **PRD Analysis**: `claude_guided_prd_parsing` provides prompts for Claude Code to analyze requirements
3. **Task Creation**: `save_parsed_tasks` stores Claude's analysis results
4. **Development**: `get_next_task` recommends what to work on
5. **Task Expansion**: `claude_guided_task_expansion` helps break down complex tasks

### Core Tools for Claude Code

#### Project Setup
- `initialize_claudemaster` - Set up project structure and templates
- `project_health_check` - Analyze project status and provide recommendations

#### PRD & Task Creation  
- `claude_guided_prd_parsing` - Guide Claude through PRD analysis
- `save_parsed_tasks` - Save Claude's task analysis results
- `analyze_project_complexity` - Identify tasks needing breakdown

#### Development Workflow
- `get_next_task` - Get intelligent next task recommendations
- `claude_guided_task_expansion` - Break down complex tasks with Claude
- `save_task_subtasks` - Save subtask breakdown results
- `generate_implementation_plan` - Create detailed implementation guides

#### Basic Operations
- `list_tasks` / `get_task` - View tasks and details
- `add_task` / `update_task` / `remove_task` - Manage tasks
- `set_task_status` - Update progress
- `add_subtask` / `remove_subtask` - Manage subtasks
- `validate_dependencies` - Check task relationships

### Configuration & Storage
- **Project Config**: `.taskmaster/claudemaster.json` - Project settings and metadata
- **Tasks Database**: `.taskmaster/tasks.json` - All project tasks and subtasks
- **Templates**: `.taskmaster/templates/` - PRD and document templates
- **Documentation**: `.taskmaster/docs/` - Project requirements and guides

### Claude Code Integration Patterns

#### Initialization
```
"Initialize Claudemaster for my [React/Node.js/Full-stack] project"
→ Uses initialize_claudemaster with appropriate project type
→ Creates optimized structure and examples
```

#### PRD Analysis
```
"Parse my PRD and create structured tasks"
→ Uses claude_guided_prd_parsing to provide analysis prompts
→ Claude analyzes PRD content with context-aware guidance
→ Uses save_parsed_tasks to store results
```

#### Development Planning
```
"What should I work on next?"
→ Uses get_next_task for intelligent recommendations
→ Considers dependencies, priorities, and project context
```

#### Task Breakdown
```
"Break down this complex task into subtasks"
→ Uses claude_guided_task_expansion with task context
→ Provides structured prompts for effective breakdown
→ Uses save_task_subtasks to store results
```

### Smart Templates

Claudemaster includes intelligent templates that adapt to project types:

- **React Apps**: Component-focused tasks, state management, testing strategies
- **Node.js APIs**: Endpoint design, database integration, middleware setup
- **Full-Stack**: Frontend-backend integration, shared type systems, deployment
- **General**: Flexible templates for any project type

### Development Notes
- **ES Modules**: Uses `"type": "module"` - import/export syntax required
- **Node 18+**: Requires Node.js 18.0.0 or higher
- **No External APIs**: All intelligence comes from Claude Code integration
- **File-Based Storage**: Uses JSON files for persistence
- **Zero Configuration**: No setup required beyond MCP integration

### Best Practices for Claude Code Integration

1. **Use Specific Contexts**: Provide project type, technology stack, and current state
2. **Leverage Templates**: Use provided templates for consistent structure
3. **Iterative Breakdown**: Break complex tasks into 1-4 hour subtasks
4. **Regular Health Checks**: Monitor project progress and identify issues
5. **Document Decisions**: Use implementation plans for complex features

### Troubleshooting

#### Common Issues
- **MCP Connection**: Ensure Claudemaster is in Claude Code's MCP configuration
- **File Permissions**: Verify write access to project directory
- **Project Structure**: Check that `.taskmaster/` directory exists

#### Debug Mode
```bash
# Enable debug logging
DEBUG=true npx claudemaster
```

### Migration from Task Master

Key changes when migrating:
1. Remove all API key environment variables
2. Update MCP configuration to use `claudemaster` instead of `task-master-ai`
3. Copy existing `tasks.json` to `.taskmaster/tasks.json`
4. Run `initialize_claudemaster` to set up new structure