Skip to content

Instantly share code, notes, and snippets.

@birchb

birchb/taskmaster-instructions.md

Created July 21, 2025 15:54
Show Gist options
  • Save birchb/f796f39973394ad42fc9d3b053964653 to your computer and use it in GitHub Desktop.
Save birchb/f796f39973394ad42fc9d3b053964653 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
taskmaster-instructions.md

Task Master AI - Agent Integration Guide

Essential Commands

Core Workflow Commands

# Project Setup
task-master init                                    # Initialize Task Master in current project
task-master parse-prd .taskmaster/docs/prd.txt      # Generate tasks from PRD document
task-master models --setup                        # Configure AI models interactively

# Daily Development Workflow
task-master list                                   # Show all tasks with status
task-master next                                   # Get next available task to work on
task-master show <id>                             # View detailed task information (e.g., task-master show 1.2)
task-master set-status --id=<id> --status=done    # Mark task complete

# Task Management
task-master add-task --prompt="description" --research        # Add new task with AI assistance
task-master expand --id=<id> --research --force              # Break task into subtasks
task-master update-task --id=<id> --prompt="changes"         # Update specific task
task-master update --from=<id> --prompt="changes"            # Update multiple tasks from ID onwards
task-master update-subtask --id=<id> --prompt="notes"        # Add implementation notes to subtask

# Analysis & Planning
task-master analyze-complexity --research          # Analyze task complexity
task-master complexity-report                      # View complexity analysis
task-master expand --all --research               # Expand all eligible tasks

# Dependencies & Organization
task-master add-dependency --id=<id> --depends-on=<id>       # Add task dependency
task-master move --from=<id> --to=<id>                       # Reorganize task hierarchy
task-master validate-dependencies                            # Check for dependency issues
task-master generate                                         # Update task markdown files (usually auto-called)

Key Files & Project Structure

Core Files

  • .taskmaster/tasks/tasks.json - Main task data file (auto-managed)
  • .taskmaster/config.json - AI model configuration (use task-master models to modify)
  • .taskmaster/docs/prd.txt - Product Requirements Document for parsing
  • .taskmaster/tasks/*.txt - Individual task files (auto-generated from tasks.json)
  • .env - API keys for CLI usage

Kilo Code Integration Files

  • KILOCODE.md - Auto-loaded context for Kilo Code (this file)
  • .kilocode/settings.json - Kilo Code tool allowlist and preferences
  • .kilocode/commands/ - Custom slash commands for repeated workflows
  • .mcp.json - MCP server configuration (project-specific)

Directory Structure

project/
├── .taskmaster/
│   ├── tasks/              # Task files directory
│   │   ├── tasks.json      # Main task database
│   │   ├── task-1.md      # Individual task files
│   │   └── task-2.md
│   ├── docs/              # Documentation directory
│   │   ├── prd.txt        # Product requirements
│   ├── reports/           # Analysis reports directory
│   │   └── task-complexity-report.json
│   ├── templates/         # Template files
│   │   └── example_prd.txt  # Example PRD template
│   └── config.json        # AI models & settings
├── .kilocode/
│   ├── settings.json      # Kilo Code configuration
│   └── commands/         # Custom slash commands
├── .env                  # API keys
├── .mcp.json            # MCP configuration
└── KILOCODE.md            # This file - auto-loaded by Kilo Code

MCP Integration

Task Master provides an MCP server that Kilo Code can connect to. Configure in .mcp.json:

{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "--package=task-master-ai", "task-master-ai"],
      "env": {
        "ANTHROPIC_API_KEY": "your_key_here",
        "PERPLEXITY_API_KEY": "your_key_here",
        "OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
        "GOOGLE_API_KEY": "GOOGLE_API_KEY_HERE",
        "XAI_API_KEY": "XAI_API_KEY_HERE",
        "OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
        "MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
        "AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
        "OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
      }
    }
  }
}

Essential MCP Tools

help; // = shows available taskmaster commands
// Project setup
initialize_project; // = task-master init
parse_prd; // = task-master parse-prd

// Daily workflow
get_tasks; // = task-master list
next_task; // = task-master next
get_task; // = task-master show <id>
set_task_status; // = task-master set-status

// Task management
add_task; // = task-master add-task
expand_task; // = task-master expand
update_task; // = task-master update-task
update_subtask; // = task-master update-subtask
update; // = task-master update

// Analysis
analyze_project_complexity; // = task-master analyze-complexity
complexity_report; // = task-master complexity-report

Kilo Code Workflow Integration

Standard Development Workflow

1. Project Initialization

# Initialize Task Master
task-master init

# Create or obtain PRD, then parse it
task-master parse-prd .taskmaster/docs/prd.txt

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

If tasks already exist, another PRD can be parsed (with new information only!) using parse-prd with --append flag. This will add the generated tasks to the existing list of tasks..

2. Daily Development Loop

# Start each session
task-master next                           # Find next available task
task-master show <id>                     # Review task details

# During implementation, check in code context into the tasks and subtasks
task-master update-subtask --id=<id> --prompt="implementation notes..."

# Complete tasks
task-master set-status --id=<id> --status=done

3. Multi-Kilo Workflows

For complex projects, use multiple Kilo Code sessions:

# Terminal 1: Main implementation
cd project && kilocode

# Terminal 2: Testing and validation
cd project-test-worktree && kilocode

# Terminal 3: Documentation updates
cd project-docs-worktree && kilocode

Custom Slash Commands

Create .kilocode/commands/taskmaster-next.md:

Find the next available Task Master task and show its details.

Steps:

1. Run `task-master next` to get the next task
2. If a task is available, run `task-master show <id>` for full details
3. Provide a summary of what needs to be implemented
4. Suggest the first implementation step

Create .kilocode/commands/taskmaster-complete.md:

Complete a Task Master task: $ARGUMENTS

Steps:

1. Review the current task with `task-master show $ARGUMENTS`
2. Verify all implementation is complete
3. Run any tests related to this task
4. Mark as complete: `task-master set-status --id=$ARGUMENTS --status=done`
5. Show the next available task with `task-master next`

Tool Allowlist Recommendations

Add to .kilocode/settings.json:

{
  "allowedTools": [
    "Edit",
    "Bash(task-master *)",
    "Bash(git commit:*)",
    "Bash(git add:*)",
    "Bash(npm run *)",
    "mcp__task_master_ai__*"
  ]
}

Configuration & Setup

API Keys Required

At least one of these API keys must be configured:

  • ANTHROPIC_API_KEY (Claude models) - Recommended
  • PERPLEXITY_API_KEY (Research features) - Highly recommended
  • OPENAI_API_KEY (GPT models)
  • GOOGLE_API_KEY (Gemini models)
  • MISTRAL_API_KEY (Mistral models)
  • OPENROUTER_API_KEY (Multiple models)
  • XAI_API_KEY (Grok models)

An API key is required for any provider used across any of the 3 roles defined in the models command.

Model Configuration

# Interactive setup (recommended)
task-master models --setup

# Set specific models
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

Task Structure & IDs

Task ID Format

  • Main tasks: 1, 2, 3, etc.
  • Subtasks: 1.1, 1.2, 2.1, etc.
  • Sub-subtasks: 1.1.1, 1.1.2, etc.

Task Status Values

  • pending - Ready to work on
  • in-progress - Currently being worked on
  • done - Completed and verified
  • deferred - Postponed
  • cancelled - No longer needed
  • blocked - Waiting on external factors

Task Fields

{
  "id": "1.2",
  "title": "Implement user authentication",
  "description": "Set up JWT-based auth system",
  "status": "pending",
  "priority": "high",
  "dependencies": ["1.1"],
  "details": "Use bcrypt for hashing, JWT for tokens...",
  "testStrategy": "Unit tests for auth functions, integration tests for login flow",
  "subtasks": []
}

Kilo Code Best Practices with Task Master

Context Management

  • Use /clear between different tasks to maintain focus
  • This CLAUDE.md file is automatically loaded for context
  • Use task-master show <id> to pull specific task context when needed

Iterative Implementation

  1. task-master show <subtask-id> - Understand requirements
  2. Explore codebase and plan implementation
  3. task-master update-subtask --id=<id> --prompt="detailed plan" - Log plan
  4. task-master set-status --id=<id> --status=in-progress - Start work
  5. Implement code following logged plan
  6. task-master update-subtask --id=<id> --prompt="what worked/didn't work" - Log progress
  7. task-master set-status --id=<id> --status=done - Complete task

Complex Workflows with Checklists

For large migrations or multi-step processes:

  1. Create a markdown PRD file describing the new changes: touch task-migration-checklist.md (prds can be .txt or .md)
  2. Use Taskmaster to parse the new prd with task-master parse-prd --append (also available in MCP)
  3. Use Taskmaster to expand the newly generated tasks into subtasks. Consdier using analyze-complexity with the correct --to and --from IDs (the new ids) to identify the ideal subtask amounts for each task. Then expand them.
  4. Work through items systematically, checking them off as completed
  5. Use task-master update-subtask to log progress on each task/subtask and/or updating/researching them before/during implementation if getting stuck

Git Integration

Task Master works well with gh CLI:

# Create PR for completed task
gh pr create --title "Complete task 1.2: User authentication" --body "Implements JWT auth system as specified in task 1.2"

# Reference task in commits
git commit -m "feat: implement JWT auth (task 1.2)"

Parallel Development with Git Worktrees

# Create worktrees for parallel task development
git worktree add ../project-auth feature/auth-system
git worktree add ../project-api feature/api-refactor

# Run Claude Code in each worktree
cd ../project-auth && claude    # Terminal 1: Auth work
cd ../project-api && claude     # Terminal 2: API work

Troubleshooting

AI Commands Failing

# Check API keys are configured
cat .env                           # For CLI usage

# Verify model configuration
task-master models

# Test with different model
task-master models --set-fallback gpt-4o-mini

MCP Connection Issues

  • Check .mcp.json configuration
  • Verify Node.js installation
  • Use --mcp-debug flag when starting Kilo Code
  • Use CLI as fallback if MCP unavailable

Task File Sync Issues

# Regenerate task files from tasks.json
task-master generate

# Fix dependency issues
task-master fix-dependencies

DO NOT RE-INITIALIZE. That will not do anything beyond re-adding the same Taskmaster core files.

Important Notes

AI-Powered Operations

These commands make AI calls and may take up to a minute:

  • parse_prd / task-master parse-prd
  • analyze_project_complexity / task-master analyze-complexity
  • expand_task / task-master expand
  • expand_all / task-master expand --all
  • add_task / task-master add-task
  • update / task-master update
  • update_task / task-master update-task
  • update_subtask / task-master update-subtask

File Management

  • Never manually edit tasks.json - use commands instead
  • Never manually edit .taskmaster/config.json - use task-master models
  • Task markdown files in tasks/ are auto-generated
  • Run task-master generate after manual changes to tasks.json

Kilo Code Session Management

  • Use /clear frequently to maintain focused context
  • Create custom slash commands for repeated Task Master workflows
  • Configure tool allowlist to streamline permissions
  • Use headless mode for automation: kilocode -p "task-master next"

Multi-Task Updates

  • Use update --from=<id> to update multiple future tasks
  • Use update-task --id=<id> for single task updates
  • Use update-subtask --id=<id> for implementation logging

Research Mode

  • Add --research flag for research-based AI enhancement
  • Requires a research model API key like Perplexity (PERPLEXITY_API_KEY) in environment
  • Provides more informed task creation and updates
  • Recommended for complex technical tasks

This guide ensures Kilo Code has immediate access to Task Master's essential functionality for agentic development workflows.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment