docs/task-structure.md
Tasks in Task Master follow a specific format designed to provide comprehensive information for both humans and AI assistants.
Tasks in tasks.json have the following structure:
id: Unique identifier for the task (Example: 1)title: Brief, descriptive title of the task (Example: "Initialize Repo")description: Concise description of what the task involves (Example: "Create a new repository, set up initial structure.")status: Current state of the task (Example: "pending", "done", "deferred")dependencies: IDs of tasks that must be completed before this task (Example: [1, 2])
priority: Importance level of the task (Example: "high", "medium", "low")details: In-depth implementation instructions (Example: "Use GitHub client ID/secret, handle callback, set session token.")testStrategy: Verification approach (Example: "Deploy and call endpoint to confirm 'Hello World' response.")subtasks: List of smaller, more specific tasks that make up the main task (Example: [{"id": 1, "title": "Configure OAuth", ...}])Individual task files follow this format:
# Task ID: <id>
# Title: <title>
# Status: <status>
# Dependencies: <comma-separated list of dependency IDs>
# Priority: <priority>
# Description: <brief description>
# Details:
<detailed implementation notes>
# Test Strategy:
<verification approach>
The analyze-complexity command:
The generated report contains:
The complexity-report command:
The expand command automatically checks for and uses the complexity report:
When a complexity report exists:
Example workflow:
# Generate the complexity analysis report with research capabilities
task-master analyze-complexity --research
# Review the report in a readable format
task-master complexity-report
# Expand tasks using the optimized recommendations
task-master expand --id=8
# or expand all tasks
task-master expand --all
The next command:
The show command:
Start with a detailed PRD: The more detailed your PRD, the better the generated tasks will be.
Review generated tasks: After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.
Analyze task complexity: Use the complexity analysis feature to identify which tasks should be broken down further.
Follow the dependency chain: Always respect task dependencies - the Cursor agent will help with this.
Update as you go: If your implementation diverges from the plan, use the update command to keep future tasks aligned with your current approach.
Break down complex tasks: Use the expand command to break down complex tasks into manageable subtasks.
Regenerate task files: After any updates to tasks.json, regenerate the task files to keep them in sync.
Communicate context to the agent: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
Validate dependencies: Periodically run the validate-dependencies command to check for invalid or circular dependencies.
Task Master uses a structured JSON format to organize and manage tasks. As of version 0.16.2, Task Master introduces Tagged Task Lists for multi-context task management while maintaining full backward compatibility.
Task Master now organizes tasks into separate contexts called tags. This enables working across multiple contexts such as different branches, environments, or project phases without conflicts.
Tagged Format (Current):
{
"master": {
"tasks": [
{ "id": 1, "title": "Setup API", "status": "pending", ... }
]
},
"feature-branch": {
"tasks": [
{ "id": 1, "title": "New Feature", "status": "pending", ... }
]
}
}
Legacy Format (Automatically Migrated):
{
"tasks": [
{ "id": 1, "title": "Setup API", "status": "pending", ... }
]
}
tasks.json files are automatically migrated to use a "master" tagEach task within a tag context contains the following properties:
id (number): Unique identifier within the tag context
"id": 1
title (string): Brief, descriptive title
"title": "Implement user authentication"
description (string): Concise summary of what the task involves
"description": "Create a secure authentication system using JWT tokens"
status (string): Current state of the task
"pending", "in-progress", "done", "review", "deferred", "cancelled""status": "pending"
dependencies (array): IDs of prerequisite tasks that must be completed first
"dependencies": [2, 3]
priority (string): Importance level
"high", "medium", "low""medium""priority": "high"
details (string): In-depth implementation instructions
"details": "Use GitHub OAuth client ID/secret, handle callback, set session token"
testStrategy (string): Verification approach
"testStrategy": "Deploy and call endpoint to confirm authentication flow"
subtasks (array): List of smaller, more specific tasks
"subtasks": [
{
"id": 1,
"title": "Configure OAuth",
"description": "Set up OAuth configuration",
"status": "pending",
"dependencies": [],
"details": "Configure GitHub OAuth app and store credentials"
}
]
Subtasks follow a similar structure to main tasks but with some differences:
id (number): Unique identifier within the parent tasktitle (string): Brief, descriptive titledescription (string): Concise summary of the subtaskstatus (string): Current state (same values as main tasks)dependencies (array): Can reference other subtasks or main task IDsdetails (string): Implementation instructions and notes{
"id": 2,
"title": "Handle OAuth callback",
"description": "Process the OAuth callback and extract user data",
"status": "pending",
"dependencies": [1],
"details": "Parse callback parameters, exchange code for token, fetch user profile"
}
Here's a complete example showing the tagged task structure:
{
"master": {
"tasks": [
{
"id": 1,
"title": "Setup Express Server",
"description": "Initialize and configure Express.js server with middleware",
"status": "done",
"dependencies": [],
"priority": "high",
"details": "Create Express app with CORS, body parser, and error handling",
"testStrategy": "Start server and verify health check endpoint responds",
"subtasks": [
{
"id": 1,
"title": "Initialize npm project",
"description": "Set up package.json and install dependencies",
"status": "done",
"dependencies": [],
"details": "Run npm init, install express, cors, body-parser"
},
{
"id": 2,
"title": "Configure middleware",
"description": "Set up CORS and body parsing middleware",
"status": "done",
"dependencies": [1],
"details": "Add app.use() calls for cors() and express.json()"
}
]
},
{
"id": 2,
"title": "Implement user authentication",
"description": "Create secure authentication system",
"status": "pending",
"dependencies": [1],
"priority": "high",
"details": "Use JWT tokens for session management",
"testStrategy": "Test login/logout flow with valid and invalid credentials",
"subtasks": []
}
]
},
"feature-auth": {
"tasks": [
{
"id": 1,
"title": "OAuth Integration",
"description": "Add OAuth authentication support",
"status": "pending",
"dependencies": [],
"priority": "medium",
"details": "Integrate with GitHub OAuth for user authentication",
"testStrategy": "Test OAuth flow with GitHub account",
"subtasks": []
}
]
}
}
Task Master automatically determines the current tag context based on:
.taskmaster/state.jsonTask Master validates the following aspects of task data:
Task Master can generate individual markdown files for each task based on the JSON structure. These files include:
When Task Master encounters a legacy format tasks.json file:
{"tasks": [...]} format{"master": {"tasks": [...]}} format.taskmaster/config.json with tagged system settings.taskmaster/state.json for tag managementdetails field for implementation