Task Master Guide for HG Content Development¶

Overview¶

Task Master is an AI-powered CLI tool for managing development tasks throughout the HG Content project. It provides automated task generation from PRD documents, intelligent task breakdown, dependency management, and progress tracking.

Initial Setup¶

1. Initialize Task Master in the Project¶

# From the hg-content root directory
task-master init --name="HG Content Generation System" --description="Multi-LLM content generation platform with Next.js frontend and Python microservices"

2. Configure AI Models¶

# Run interactive setup to configure AI models
task-master models --setup

# Or set models manually
task-master models --set-main claude-3-5-sonnet-20241022
task-master models --set-research claude-3-5-sonnet-20241022

3. PRD Processing Workflow¶

Follow this standardized process for each PRD document to ensure complete coverage:

Step 1: Parse the PRD¶

# Parse each PRD document
task-master parse-prd --input=docs/plan_overview.md --num-tasks=20
task-master parse-prd --input=docs/monorepo_setup_plan.md --num-tasks=10
task-master parse-prd --input=docs/content_production_module_plan.md --num-tasks=15
task-master parse-prd --input=docs/instructions_module_plan.md --num-tasks=12
task-master parse-prd --input=docs/strategy_management_module_plan.md --num-tasks=10
task-master parse-prd --input=docs/user_interface_module_plan.md --num-tasks=15
task-master parse-prd --input=docs/llm_integration_plan.md --num-tasks=10
task-master parse-prd --input=docs/data_flow_integration_plan.md --num-tasks=8
task-master parse-prd --input=docs/deployment_scalability_plan.md --num-tasks=10

Step 2: Analyze Complexity¶

# Run complexity analysis with research
task-master analyze-complexity --research --threshold=3

Step 3: Implement Expansion Recommendations¶

# Review the complexity report
task-master complexity-report --file=reports/complexity-analysis.md

# Expand tasks based on recommendations
# The report will identify which tasks need expansion

Step 4: Expand All Tasks¶

# Ensure all complex tasks are expanded
task-master expand --all --research --force

# Verify all tasks have appropriate subtasks
task-master list --with-subtasks > reports/all-tasks-expanded.txt

Step 5: Validate PRD Coverage¶

# Generate a comprehensive task list
task-master list --with-subtasks --status=all > reports/task-coverage.txt

# Research to compare tasks with PRD
task-master research "Compare the task list in reports/task-coverage.txt with the PRD in [PRD_FILE] and identify any gaps in coverage" -f=reports/task-coverage.txt,[PRD_FILE] -s=reports/prd-coverage-analysis.md

Step 6: Generate Process Report¶

# Create a summary report of the process
task-master research "Generate a comprehensive report of the PRD processing including: 1) Number of tasks generated, 2) Complexity analysis results, 3) Expansion summary, 4) Coverage validation results" -f=reports/complexity-analysis.md,reports/task-coverage.txt,reports/prd-coverage-analysis.md -s=reports/prd-process-report.md

Step 7: Approval Gate¶

After completing steps 1-6, present the process report for approval before proceeding with development. Only after approval should development commence using the task master workflow.

Complete PRD Processing Example¶

Here's a complete example for processing the Content Production Module PRD:

# 1. Parse the PRD
task-master parse-prd --input=docs/content_production_module_plan.md --num-tasks=15

# 2. Analyze complexity
task-master analyze-complexity --research --threshold=3

# 3. Review complexity report
task-master complexity-report --file=reports/cpm-complexity.md

# 4. Expand all tasks
task-master expand --all --research --force

# 5. Validate coverage
task-master list --with-subtasks > reports/cpm-tasks.txt
task-master research "Compare tasks in reports/cpm-tasks.txt with docs/content_production_module_plan.md and identify gaps" -f=reports/cpm-tasks.txt,docs/content_production_module_plan.md -s=reports/cpm-coverage.md

# 6. Generate report
task-master research "Create CPM PRD processing report with task count, complexity analysis, and coverage validation" -f=reports/cpm-complexity.md,reports/cpm-tasks.txt,reports/cpm-coverage.md -s=reports/cpm-process-report.md

# 7. Present report and await approval
cat reports/cpm-process-report.md

Task Management Workflow¶

1. View All Tasks¶

# List all tasks
task-master list

# List tasks by status
task-master list --status=pending
task-master list --status=in-progress

# List with subtasks
task-master list --with-subtasks

2. Find Next Task to Work On¶

# Get the next task based on dependencies and priority
task-master next

3. Update Task Status¶

# Mark task as in-progress when starting
task-master set-status --id=1 --status=in-progress

# Mark as done when completed
task-master set-status --id=1 --status=done

# Other statuses: pending, review, deferred, cancelled

4. Break Down Complex Tasks¶

# Analyze task complexity
task-master analyze-complexity --research

# Expand a specific task into subtasks
task-master expand --id=5 --num=5 --research

# Expand all pending tasks
task-master expand --all --research

5. Add New Tasks¶

# Add a task using AI
task-master add-task --prompt="Implement rate limiting for LLM API calls" --dependencies=3,4 --priority=high

# Add a subtask manually
task-master add-subtask --parent=5 --title="Configure Redis connection" --description="Set up Redis client with connection pooling"

Development Phases and Task Organization¶

Phase 1: Foundation Setup¶

# Tag for foundation tasks
task-master add-tag foundation --description="Core infrastructure and setup tasks"
task-master use-tag foundation

# Key tasks:
# - Monorepo structure setup
# - Supabase project initialization
# - BWS secrets configuration
# - Base deployment configurations

Phase 2: Backend Services¶

# Tag for backend development
task-master add-tag backend --copy-from-current --description="Python microservices development"
task-master use-tag backend

# Key tasks:
# - CPM FastAPI implementation
# - IM service development
# - LLM abstraction layer
# - Job queue setup

Phase 3: Frontend Development¶

# Tag for frontend tasks
task-master add-tag frontend --copy-from-current --description="Next.js UI development"
task-master use-tag frontend

# Key tasks:
# - Authentication with Supabase
# - Dashboard components
# - Content generation forms
# - Real-time updates

Phase 4: Integration & Deployment¶

# Tag for deployment tasks
task-master add-tag deployment --copy-from-current --description="Deployment and integration tasks"
task-master use-tag deployment

# Key tasks:
# - Railway deployment setup
# - Vercel configuration
# - CI/CD pipeline
# - Integration testing

Research and Context Queries¶

Use the research command to get AI-powered insights with project context:

# Research implementation approaches
task-master research "What's the best way to implement rate limiting for multiple LLM providers?" -i=3,4,5 -f=services/cpm/src/llm_client.py

# Research with specific context
task-master research "How should we structure the job queue for content generation?" -c="We're using FastAPI BackgroundTasks for MVP but planning to migrate to Celery"

# Save research output
task-master research "Supabase RLS policies for multi-tenant content" -s=research/supabase-rls.md

Dependency Management¶

# Add dependencies between tasks
task-master add-dependency --id=10 --depends-on=5
task-master add-dependency --id=10 --depends-on=6

# Validate dependencies
task-master validate-dependencies

# Fix invalid dependencies automatically
task-master fix-dependencies

Progress Tracking and Reporting¶

# Generate complexity report
task-master complexity-report --file=reports/complexity-analysis.md

# Sync tasks to README
task-master sync-readme --with-subtasks --status=all

# Export specific status to README
task-master sync-readme --status=in-progress

Best Practices¶

1. Task Granularity¶

Keep top-level tasks focused on deliverable features
Use subtasks for implementation details
Aim for tasks completable in 1-4 hours

2. Status Management¶

Update status immediately when starting/completing tasks
Use "review" status for tasks pending code review
Use "deferred" for tasks postponed to future phases

3. Dependencies¶

Define dependencies for tasks that truly block others
Avoid circular dependencies
Review dependency graph regularly

4. Research Integration¶

Use research command before implementing complex features
Save important research findings for team reference
Include file context when researching specific implementations

5. Tag Management¶

Create tags for major development phases
Use tags to switch between different work contexts
Copy tags to preserve task history while starting new phases

Integration with Development Workflow¶

1. Daily Workflow¶

# Start of day
task-master next                    # Find next task
task-master show <id>              # Review task details
task-master set-status --id=<id> --status=in-progress

# During development
task-master update-subtask --id=<id> --prompt="Implemented Redis connection pooling"

# End of task
task-master set-status --id=<id> --status=done
task-master sync-readme            # Update project README

2. Sprint Planning¶

# Analyze pending work
task-master list --status=pending
task-master complexity-report

# Expand complex tasks
task-master expand --id=<id> --research

# Update task priorities
task-master update-task --id=<id> --prompt="Increase priority due to customer requirement"

3. Progress Reporting¶

# Generate status report
task-master list --status=done | head -20    # Recent completions
task-master list --status=in-progress         # Current work
task-master next                              # Upcoming tasks

Troubleshooting¶

Issue: API Key Errors¶

Ensure environment variables are set:

export ANTHROPIC_API_KEY=your-key
export GOOGLE_API_KEY=your-key    # If using Gemini

Issue: Task Not Found¶

# List all tasks to find correct ID
task-master list --with-subtasks

# Show specific task details
task-master show <id>

Issue: Dependency Conflicts¶

# Identify issues
task-master validate-dependencies

# Auto-fix if possible
task-master fix-dependencies

Command Reference¶

For complete command documentation, run:

task-master help
task-master help <command>

Key commands for this project: - parse-prd: Generate tasks from plan documents - list: View tasks and status - next: Find next task to work on - expand: Break down complex tasks - set-status: Update task progress - research: Get AI insights with context - sync-readme: Update project README with tasks