directus-task-management/TASK_MASTER_SETUP.md

# Task Master Project Initialization Guide

## Overview

This guide provides step-by-step instructions for initializing a Task Master project to manage the development of the Directus Task Management Suite. This creates a tactical project management layer alongside the strategic BMad planning documents.

## Quick Setup Commands

```bash
# Navigate to project directory
cd /Users/stevenhardge/Documents/projects/my-ai-projects/projects/directus-task-management

# Initialize Task Master in this directory
task-master init

# Create PRD for Task Master parsing
cp planning/01-bmad-prd.md .taskmaster/docs/prd.txt

# Parse PRD to generate initial tasks
task-master parse-prd .taskmaster/docs/prd.txt --num=15

# Analyze task complexity and expand key tasks
task-master analyze-complexity --research
task-master expand --all --research
```

## Detailed Setup Process

### Step 1: Initialize Task Master Project

**Command:**
```bash
cd /Users/stevenhardge/Documents/projects/my-ai-projects/projects/directus-task-management
task-master init
```

**Expected Output:**
```
✅ Task Master initialized successfully
✅ Created .taskmaster/ directory structure
✅ Created .taskmaster/config.json with default settings
✅ Created .taskmaster/tasks/tasks.json
✅ Created .taskmaster/docs/ directory
```

**Verification:**
```bash
ls -la .taskmaster/
# Should show: config.json, docs/, tasks/, reports/
```

### Step 2: Prepare Project Requirements Document

**Copy BMad PRD for Task Master:**
```bash
# Copy the comprehensive PRD created in BMad planning
cp planning/01-bmad-prd.md .taskmaster/docs/prd.txt

# Verify content
head -20 .taskmaster/docs/prd.txt
```

**Alternative: Create Focused PRD for Development**
If you prefer a more focused PRD specifically for the development work:

```bash
cat > .taskmaster/docs/prd.txt << 'EOF'
# Directus Task Management Suite - Development PRD

## Project Overview
Build a comprehensive task management system on Directus CMS that integrates with existing AI development ecosystem including Claude Code agents, BMad methodology, and Task Master CLI.

## Core Requirements

### Phase 1: Foundation (Weeks 1-2)
- Design and implement 10 Directus collections for task management
- Build 22 new MCP tools for programmatic task operations
- Create basic task CRUD operations via Directus admin interface
- Set up project hierarchy and customizable status workflows

### Phase 2: AI Integration (Weeks 3-4) 
- Implement AI-powered task creation using natural language prompts
- Build Claude Code agent context integration through MCP tools
- Add automated progress tracking from git events and agent activity
- Create task templates aligned with BMad methodology

### Phase 3: Workflow Integration (Weeks 5-6)
- Build BMad workflow templates and step tracking
- Implement Task Master bidirectional synchronization
- Add team collaboration features through web interface
- Create progress analytics dashboard

### Phase 4: Advanced Features (Weeks 7-8)
- Advanced dependency management with critical path analysis
- Time tracking and resource utilization analytics
- Performance optimizations for 10,000+ tasks
- Production deployment with monitoring

## Technical Architecture
- Platform: Directus CMS (existing instance at https://enias.zeabur.app)
- Integration: 22 new MCP tools extending existing 40+ tool ecosystem
- Database: 10 new collections with strategic indexing
- Sync: Bidirectional with Task Master using conflict resolution
- Performance: <100ms response times, cursor-based pagination

## Success Criteria
- 70% efficiency improvement in task management workflows
- 80% of tasks created through AI assistance
- 99.9% system uptime and data integrity
- Seamless integration with existing development tools

## Key Deliverables by Phase
1. **Phase 1**: Functional task management web interface
2. **Phase 2**: AI-powered task creation and agent integration  
3. **Phase 3**: BMad methodology support and Task Master sync
4. **Phase 4**: Analytics dashboard and production optimization
EOF
```

### Step 3: Generate Initial Tasks

**Parse PRD to Create Tasks:**
```bash
# Generate tasks from PRD (15 high-level tasks recommended)
task-master parse-prd .taskmaster/docs/prd.txt --num=15 --research

# Alternative: Let Task Master determine optimal number
task-master parse-prd .taskmaster/docs/prd.txt --num=0 --research
```

**Expected Output:**
```
✅ Parsing PRD document: .taskmaster/docs/prd.txt
🔍 Using research mode for enhanced task generation
✅ Generated 15 high-level tasks from PRD content
✅ Tasks saved to .taskmaster/tasks/tasks.json
✅ Individual task files created in .taskmaster/tasks/
```

**Verify Task Generation:**
```bash
# List generated tasks
task-master list

# View task summary
task-master show 1
```

### Step 4: Analyze and Expand Tasks

**Run Complexity Analysis:**
```bash
# Analyze all tasks for complexity and expansion recommendations
task-master analyze-complexity --research

# View complexity report
task-master complexity-report
```

**Expand High-Complexity Tasks:**
```bash
# Expand all tasks that meet complexity threshold
task-master expand --all --research

# Alternative: Expand specific high-complexity tasks
task-master expand --id=1 --research --num=5
task-master expand --id=5 --research --num=4
task-master expand --id=8 --research --num=6
```

**Expected Results:**
- High-level tasks broken down into actionable subtasks
- Implementation guidance for each subtask
- Dependency relationships established
- Time estimates provided

### Step 5: Configure Development Workflow

**Set Up Models (if not already configured):**
```bash
# Configure AI models for task operations
task-master models --set-main claude-3-5-sonnet-20241022
task-master models --set-research perplexity-llama-3.1-sonar-large-128k-online
task-master models --set-fallback gpt-4o-mini

# Verify configuration
task-master models
```

**Create Development Tags:**
```bash
# Add relevant tags to tasks for better organization
task-master update-task --id=1 --prompt="Add tags: directus, mcp, collections, database"
task-master update-task --id=2 --prompt="Add tags: mcp, tools, api, integration"
task-master update-task --id=3 --prompt="Add tags: ai, nlp, claude, automation"
```

## Expected Task Structure

After initialization, you should have a Task Master project with approximately:

### High-Level Tasks (Examples)
1. **Design Core Collection Schema** - Database design for 10 collections
2. **Implement MCP Tools Suite** - 22 new tools for task operations
3. **Build AI Task Creation** - Natural language to task conversion
4. **Create Task CRUD Interface** - Basic web interface operations
5. **Develop Status Workflow System** - Customizable task statuses
6. **Build Project Hierarchy** - Multi-level project organization
7. **Implement Agent Integration** - Claude Code context provision
8. **Create BMad Templates** - Workflow methodology support
9. **Build Task Master Sync** - Bidirectional data synchronization
10. **Develop Analytics Dashboard** - Progress tracking and metrics
11. **Implement Time Tracking** - Resource utilization monitoring
12. **Build Dependency Management** - Task relationship handling
13. **Create Team Collaboration** - Multi-user workflow support
14. **Performance Optimization** - Scaling for large datasets
15. **Production Deployment** - Monitoring and reliability

### Subtask Structure (Example for Task 1)
**1. Design Core Collection Schema**
- 1.1 Design projects collection with hierarchy support
- 1.2 Design tasks collection with rich metadata
- 1.3 Design task_statuses collection with workflow rules
- 1.4 Design task_dependencies for relationship management
- 1.5 Design integration collections for external systems
- 1.6 Create database indexes for performance optimization
- 1.7 Implement collection relationships and constraints

## Daily Development Workflow

### Starting Development Work
```bash
# Get next available task
task-master next

# View task details
task-master show <task-id>

# Mark task as in-progress
task-master set-status --id=<task-id> --status=in-progress
```

### During Development
```bash
# Update task with progress notes
task-master update-subtask --id=<subtask-id> --prompt="Implementation notes: [describe progress]"

# Add time entries (optional)
task-master add-time-entry --id=<task-id> --hours=2.5 --description="Schema design work"
```

### Completing Tasks
```bash
# Mark subtask as complete
task-master set-status --id=<subtask-id> --status=done

# When all subtasks complete, mark parent as done
task-master set-status --id=<task-id> --status=done

# Get next task
task-master next
```

## Integration with BMad Planning

### Linking Strategic and Tactical Levels

The Task Master project provides **tactical execution tracking** while the BMad planning documents provide **strategic direction**:

**Strategic Level (BMad Documents):**
- Product vision and requirements ([01-bmad-prd.md](planning/01-bmad-prd.md))
- System architecture decisions ([02-bmad-architecture.md](planning/02-bmad-architecture.md))
- Market research and analysis ([03-bmad-research-analysis.md](planning/03-bmad-research-analysis.md))
- Technical validation ([04-bmad-validation.md](planning/04-bmad-validation.md))

**Tactical Level (Task Master):**
- Granular task breakdown and tracking
- Daily development workflow management
- Progress monitoring and velocity tracking
- Implementation-level dependencies

### Cross-Reference Pattern

**Reference Strategic Context in Tasks:**
```bash
# Link tactical tasks to strategic planning
task-master update-task --id=1 --prompt="Reference: See architecture decisions in planning/02-bmad-architecture.md for collection design patterns"

task-master update-task --id=3 --prompt="Reference: AI integration patterns documented in planning/03-bmad-research-analysis.md section on AI Integration Research"
```

**Update Strategic Documents with Tactical Progress:**
```bash
# Periodically update BMad documents with implementation findings
# (Manual process - updates to planning/*.md files as insights emerge)
```

## Maintenance and Updates

### Regular Maintenance
```bash
# Weekly: Update task progress and velocity
task-master generate  # Regenerate task files from JSON

# Monthly: Analyze project health
task-master complexity-report
task-master validate-dependencies
```

### Adding New Requirements
```bash
# For new requirements discovered during development
task-master add-task --prompt="[New requirement description]" --research

# For urgent bug fixes or issues
task-master add-task --prompt="Fix: [Issue description]" --priority=high
```

### Integration Testing
```bash
# Validate Task Master integration with project
task-master validate-dependencies
task-master fix-dependencies  # If issues found
```

## Troubleshooting

### Common Issues

**1. Task Master Command Not Found:**
```bash
# Install Task Master globally
npm install -g task-master-ai

# Verify installation
task-master --version
```

**2. API Keys Not Configured:**
```bash
# Check environment variables
echo $ANTHROPIC_API_KEY
echo $PERPLEXITY_API_KEY

# Configure in .env file or Task Master config
task-master models --setup
```

**3. PRD Parsing Fails:**
```bash
# Verify PRD file exists and is readable
cat .taskmaster/docs/prd.txt | head -10

# Try parsing with different parameters
task-master parse-prd .taskmaster/docs/prd.txt --num=10 --force
```

**4. Tasks Not Expanding:**
```bash
# Check complexity analysis first
task-master analyze-complexity

# Try expanding specific tasks
task-master expand --id=1 --force --num=5
```

## Success Validation

After setup, verify the Task Master project is working correctly:

### ✅ Validation Checklist
- [ ] Task Master initialized in project directory
- [ ] PRD successfully parsed into tasks
- [ ] 10-20 high-level tasks generated
- [ ] Complexity analysis completed
- [ ] High-complexity tasks expanded into subtasks
- [ ] Can view and navigate task hierarchy
- [ ] Can update task status and progress
- [ ] Dependencies are properly linked
- [ ] Tasks reference strategic planning documents

### 📊 Expected Metrics
- **Total Tasks**: 15-25 high-level tasks
- **Total Subtasks**: 50-100 subtasks (after expansion)
- **Task Complexity**: Mix of trivial (20%), minor (40%), major (30%), critical (10%)
- **Dependencies**: 20-30% of tasks have dependencies
- **Estimated Hours**: 200-400 hours total project effort

### 🔗 Strategic-Tactical Alignment
- Each major BMad planning phase has corresponding Task Master tasks
- Implementation tasks reference appropriate strategic planning documents
- Tactical progress can inform strategic planning updates
- Both levels support the overall project delivery timeline

This setup creates a comprehensive tactical project management layer that complements the strategic BMad planning, enabling efficient development workflow while maintaining visibility into both strategic direction and tactical execution progress.