Best Practices

These patterns and workflows will help you move faster, stay organized, and get better results from Taskmaster across your projects.

The Recommended Workflow

Follow this cycle for the best results on any project:

Write a PRD — Describe what you want to build in plain text
Parse it — tm parse-prd generates a structured task plan
Analyze complexity — tm analyze-complexity scores every task
Review the report — tm complexity-report shows what needs breaking down
Expand complex tasks — tm expand splits high-complexity tasks into subtasks
Research unknowns — tm research gathers live information for technical decisions
Pick your next task — tm next selects the highest-priority unblocked task
Implement — Work on the task with full context from details and test strategy
Update if needed — tm update keeps future tasks aligned if plans change
Mark complete — tm set-status --id=N --status=done and move on

This cycle keeps your project structured while adapting to what you learn during implementation.

Start with Complexity Analysis

Before writing any code, run complexity analysis on your task list:

tm analyze-complexity --research

This scores every task on a 1–10 scale and recommends how many subtasks each one needs. Then review the formatted report:

tm complexity-report

Why this matters: Tasks that seem simple in a PRD often hide significant complexity. Analyzing upfront prevents surprises mid-implementation and helps you allocate time accurately.

Expand your highest-complexity tasks first:

# Expand a specific complex task
tm expand --id=5

# Expand with additional context
tm expand --id=5 --prompt="Focus on security considerations"

# Expand all pending tasks at once
tm expand --all

Research Before You Build

Use the built-in research command whenever you're working with unfamiliar technology, making architectural decisions, or need information beyond AI training data:

# Basic research
tm research "JWT best practices for refresh token rotation"

# Research with task context
tm research "React Query v5 migration" --id=15

# Research with file context
tm research "Optimize this database schema" --files=src/db/schema.ts

# Save findings directly to a task
tm research "OAuth PKCE flow" --save-to=12

Research uses your configured research model (typically Perplexity) to pull live information from the web. This is especially valuable for:

Security-sensitive implementations
New library or framework adoption
Performance optimization strategies
Debugging complex issues

Tip: Research first, then update your tasks with the findings. This produces better subtasks and implementation details than guessing.

View Multiple Tasks Together

When planning your next stretch of work, view several tasks at once for a bird's-eye perspective:

# View multiple tasks in a compact table
tm show 5,7,9

# Mix parent tasks and subtasks
tm show 44,44.1,55,55.2

The multi-task view shows a summary table with status, priority, and progress indicators. You can also perform batch operations — marking multiple tasks as in-progress, expanding all of them, or checking dependency relationships at a glance.

Keep Tasks in Sync with Reality

Plans change during implementation. When your approach diverges from what was originally planned, update future tasks so they reflect reality:

# Update all tasks from a given ID forward
tm update --from=4 --prompt="Switched from REST to GraphQL for the API layer"

# Use research-backed updates for better suggestions
tm update --from=4 --prompt="Migrating to MongoDB" --research

# Update a single task's details
tm update-task --id=3 --prompt="Need to handle pagination differently"

This rewrites future task details while preserving completed work — no need to start over or manually rewrite your plan.

Use Tags for Parallel Workstreams

Tags let you maintain separate task lists for different features, branches, or experiments:

# Create a tag from your current git branch
tm add-tag --from-branch

# Create a named tag
tm add-tag api-v2 --description="API v2 redesign"

# Switch context
tm use-tag auth

# Copy current tasks into a new tag for experimentation
tm add-tag experiment --copy-from-current

Tags prevent merge conflicts when multiple team members create tasks on different branches, and make it easy to context-switch between workstreams without losing track of progress.

Optimize MCP Token Usage

If you use Taskmaster through an MCP-enabled editor, you can control how many tools are loaded to manage context window usage:

Preset	Tools Loaded	Token Cost	Best For
`core`	7 essential	~5,000	Daily development
`standard`	15 common	~10,000	Balanced feature set
`all`	36 total	~21,000	Full functionality

Configure this in your MCP settings:

{
  "mcpServers": {
    "task-master-ai": {
      "env": {
        "TASK_MASTER_TOOLS": "standard"
      }
    }
  }
}

For long-running operations like PRD parsing or research, extend the MCP timeout:

{
  "mcpServers": {
    "task-master-ai": {
      "timeout": 300
    }
  }
}

Quick Tips

Validate dependencies regularly — Run tm validate-dependencies to catch circular or missing dependencies before they block you
Use --research liberally — Adding the --research flag to expand, update, and analyze-complexity pulls live information for better results
Keep task details specific — The more actionable your task details, the better your AI assistant can help implement them
Track status honestly — Mark tasks as in-progress when you start and done when you finish. This keeps tm next accurate
Break down early — Expand complex tasks before you start implementing, not when you're stuck halfway through

Next Steps

Advanced Tasks — AI-driven development workflow, task reorganization, and merge conflict resolution
Advanced Configuration — Config files, environment variables, and provider-specific setup