> ## Documentation Index
> Fetch the complete documentation index at: https://taskgraph-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Task Structure

> Tasks in TaskGraph follow a specific format designed to provide comprehensive information for both humans and AI assistants.

## Task Fields in tasks.json

Tasks in tasks.json have the following structure:

| Field | Description | Example |
| - | - | - |
| `id` | Unique identifier for the task. | `1` |
| `title` | Brief, descriptive title. | `"Initialize Repo"` |
| `description` | What the task involves. | `"Create a new repository, set up initial structure."` |
| `status` | Current state. | `"pending"`, `"done"`, `"deferred"` |
| `dependencies` | Prerequisite task IDs. ✅ Completed, ⏱️ Pending | `[1, 2]` |
| `priority` | Task importance. | `"high"`, `"medium"`, `"low"` |
| `details` | Implementation instructions. | `"Use GitHub client ID/secret, handle callback..."` |
| `testStrategy` | How to verify success. | `"Deploy and confirm 'Hello World' response."` |
| `subtasks` | Nested subtasks related to the main task. | `[{"id": 1, "title": "Configure OAuth", ...}]` |
| `metadata` | Optional user-defined data (see below). | `{"githubIssue": 42, "sprint": "Q1-S3"}` |

The statuses are `pending`, `in-progress`, `review`, `done`, `deferred`, `cancelled` and `blocked`. Files from Task Master or an AI tool may say `completed`: TaskGraph reads it as `done` on a task or a subtask, in tasks.json and archive.json, and the next save writes `done`.

## Task File Format

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>
```

## User-Defined Metadata Field

The `metadata` field allows you to store arbitrary custom data on tasks without requiring schema changes. This is useful for:

* **External IDs**: Link tasks to GitHub issues, Jira tickets, Linear issues, etc.
* **Workflow data**: Track sprints, story points, custom statuses
* **Integration data**: Store sync timestamps, external system references
* **Custom tracking**: UUIDs, version numbers, audit information

### Key Characteristics

> **Fully Optional**
>
> The field is optional. Existing tasks work without it.

> **AI-Safe**
>
> AI operations preserve your metadata - it's never overwritten by AI.

> **Flexible Schema**
>
> Store any JSON-serializable data: strings, numbers, objects, arrays.

> **Subtask Support**
>
> Both tasks and subtasks can have their own metadata.

### Usage Examples

**GitHub Issue Linking**

```json theme={null}
{
  "id": 1,
  "title": "Implement authentication",
  "metadata": {
    "githubIssue": 42,
    "githubIssueUrl": "https://github.com/org/repo/issues/42"
  }
}
```

**Sprint & Project Management**

```json theme={null}
{
  "id": 2,
  "title": "Refactor API endpoints",
  "metadata": {
    "sprint": "Q1-S3",
    "storyPoints": 5,
    "epic": "API Modernization"
  }
}
```

**External System Integration**

```json theme={null}
{
  "id": 3,
  "title": "Fix login bug",
  "metadata": {
    "jira": {
      "key": "PROJ-123",
      "type": "bug",
      "priority": "P1"
    },
    "importedAt": "2024-01-15T10:30:00Z",
    "lastSyncedAt": "2024-01-20T14:00:00Z"
  }
}
```

**Stable UUID Tracking**

```json theme={null}
{
  "id": 4,
  "title": "Add user preferences",
  "metadata": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": 2,
    "createdBy": "import-script"
  }
}
```

> [!WARNING]
>
> **Security Note**: Do not store secrets, API keys, or sensitive credentials in
> the metadata field. Task data may be visible in logs, exports, or shared with
> AI providers.

### Where a task came from

`parse-prd` records the PRD section each task implements in `metadata.source`: the PRD's path relative to the project root, then the heading's anchor as GitHub would write it.

```json theme={null}
"metadata": {
  "source": "docs/prd.md#authentication",
  "sourceHash": "3f9a1c0e5b7d2a64"
}
```

`sourceHash` is a hash of that section's text when the task was made. The tag's own metadata keeps the hash of every section of the PRD (`prdSections`), so `parse-prd --append` can tell which sections are new, changed or removed since the last parse.

The AI is given the PRD's headings and picks one per task; an answer that matches no heading is dropped rather than stored. `expand` copies the source to each new subtask. `taskgraph show` prints it under the status line, and `taskgraph validate-dependencies` uses it to list PRD sections that have no task (see [Managing Task Dependencies](https://taskgraph-ai.com/capabilities/cli-updating-commands.md#managing-task-dependencies)).

### Metadata Behavior

| Operation | Metadata Behavior |
| - | - |
| `parse-prd` | New tasks get `source` and `sourceHash`, the PRD section they came from |
| `update-task` | Existing metadata is preserved unless explicitly changed |
| `expand` | Parent task metadata is preserved; subtasks inherit `source` only |
| `update-subtask` | Subtask metadata is preserved |
| Manual edit | You can add/modify metadata directly in tasks.json |
| MCP (with flag) | Use the `metadata` parameter to explicitly update metadata |

### Updating Metadata via MCP

The `update_task` and `update_subtask` MCP tools support a `metadata` parameter for updating task metadata. This feature is disabled by default for safety.

**To enable MCP metadata updates:**

Add `TASKGRAPH_ALLOW_METADATA_UPDATES=true` to your MCP server environment configuration in `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "taskgraph-ai": {
      "command": "npx",
      "args": ["-y", "taskgraph-ai"],
      "env": {
        "TASKGRAPH_ALLOW_METADATA_UPDATES": "true"
      }
    }
  }
}
```

**Usage example:**

```javascript theme={null}
// Update task metadata (merges with existing)
update_task({
  id: "1",
  projectRoot: "/path/to/project",
  metadata: '{"githubIssue": 42, "sprint": "Q1-S3"}'
})

// Update only metadata (no prompt required)
update_task({
  id: "1",
  projectRoot: "/path/to/project",
  metadata: '{"status": "reviewed"}'
})
```

> [!NOTE]
>
> The `metadata` parameter accepts a JSON string. The new metadata is merged with existing metadata, allowing you to update specific fields without losing others.

## Features in Detail

> **Analyzing Task Complexity**
>
> The `analyze-complexity` command:
>
> * Analyzes each task using AI to assess its complexity on a scale of 1-10
> * Recommends optimal number of subtasks based on configured DEFAULT\_SUBTASKS
> * Generates tailored prompts for expanding each task
> * Creates a comprehensive JSON report with ready-to-use commands
> * Saves the report to scripts/task-complexity-report.json by default
>
> The generated report contains:
>
> * Complexity analysis for each task (scored 1-10)
> * Recommended number of subtasks based on complexity
> * AI-generated expansion prompts customized for each task
> * Ready-to-run expansion commands directly within each task analysis

> **Viewing Complexity Report**
>
> The `complexity-report` command:
>
> * Displays a formatted, easy-to-read version of the complexity analysis report
> * Shows tasks organized by complexity score (highest to lowest)
> * Provides complexity distribution statistics (low, medium, high)
> * Highlights tasks recommended for expansion based on threshold score
> * Includes ready-to-use expansion commands for each complex task
> * If no report exists, offers to generate one on the spot

> **Smart Task Expansion**
>
> The `expand` command automatically checks for and uses the complexity report:
>
> When a complexity report exists:
>
> * Tasks are automatically expanded using the recommended subtask count and prompts
> * When expanding all tasks, they're processed in order of complexity (highest first)
> * Research-backed generation is preserved from the complexity analysis
> * You can still override recommendations with explicit command-line options
>
> Example workflow:
>
> ```bash theme={null}
> # Generate the complexity analysis report with research capabilities
> taskgraph analyze-complexity --research
>
> # Review the report in a readable format
> taskgraph complexity-report
>
> # Expand tasks using the optimized recommendations
> taskgraph expand --id=8
> # or expand all tasks
> taskgraph expand --all
> ```

> **Finding the Next Task**
>
> The `next` command:
>
> * Identifies tasks that are pending/in-progress and have all dependencies done
> * Prefers subtasks of an in-progress parent, then orders candidates by priority, then by how many unfinished tasks they unblock, then by fewer dependencies, then by task ID (see [Dependency Graph](https://taskgraph-ai.com/capabilities/dependency-graph.md))
> * Displays comprehensive information about the selected task:
>   * Basic task details (ID, title, priority, dependencies)
>   * Implementation details
>   * Subtasks (if they exist)
> * Provides contextual suggested actions:
>   * Command to mark the task as in-progress
>   * Command to mark the task as done
>   * Commands for working with subtasks

> **Viewing Specific Task Details**
>
> The `show` command:
>
> * Displays comprehensive details about a specific task or subtask
> * Shows task status, priority, dependencies, and detailed implementation notes
> * For parent tasks, displays all subtasks and their status
> * For a subtask, prints the same status line as `next`: dependencies on siblings as full IDs (`depends on 3.1`), and the parent's priority when the subtask has none of its own
> * Provides contextual action suggestions based on the task's state
> * Works with both regular tasks and subtasks (using the format taskId.subtaskId)

## Best Practices for AI-Driven Development

> **📝 Detailed PRD**
>
> The more detailed your PRD, the better the generated tasks will be.

> **👀 Review Tasks**
>
> After parsing the PRD, review the tasks to ensure they make sense and have
> appropriate dependencies.

> **📊 Analyze Complexity**
>
> Use the complexity analysis feature to identify which tasks should be broken
> down further.

> **⛓️ Follow Dependencies**
>
> Always respect task dependencies - Claude Code will help with this.

> **🔄 Update As You Go**
>
> If your implementation diverges from the plan, use the update command to
> keep future tasks aligned.

> **📦 Break Down Tasks**
>
> Use the expand command to break down complex tasks into manageable subtasks.

> **🔄 Regenerate Files**
>
> After any updates to tasks.json, regenerate the task files to keep them in
> sync.

> **💬 Provide Context**
>
> When asking Claude Code 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.

## Tagged Task Lists

`tasks.json` organizes tasks into separate contexts called **tags**, so you can keep different branches, features or project phases apart.

```json theme={null}
{
  "master": {
    "tasks": [
      { "id": 1, "title": "Setup API", "status": "pending" }
    ]
  },
  "feature-branch": {
    "tasks": [
      { "id": 1, "title": "New Feature", "status": "pending" }
    ]
  }
}
```

* **Isolation:** tasks in different tags never interfere, and each tag numbers its tasks from 1.
* **Current tag:** stored in `.taskgraph/state.json`, falling back to `master`. Override it per command with `--tag`.
* **Dependencies** must reference tasks in the same tag, and subtask IDs must be unique within their parent.
* **Legacy files:** a `tasks.json` in the old `{"tasks": [...]}` shape is converted to `{"master": {"tasks": [...]}}` on first read, with all data preserved.

See [Cross-Tag Task Movement](https://taskgraph-ai.com/capabilities/cross-tag-movement) for moving tasks between tags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.