Tutorial

This tutorial will guide you through setting up and using TaskGraph for AI-driven development.

Initial Setup

You need Claude Code installed and signed in (run claude once) and Node.js 22.13 or later. TaskGraph needs no API keys.

Install the package

npm install -g taskgraph-ai

Initialize your project from its folder:

taskgraph init

This creates .taskgraph/ and imports TaskGraph’s workflow guide from your project’s CLAUDE.md. Add --mcp to also write a .mcp.json entry for the MCP server.

(Optional) Use the MCP server. Slash commands and the CLI do everything without it. To drive TaskGraph in plain language, register the server and run /mcp in Claude Code to check that it is connected:

claude mcp add taskgraph-ai --scope user \
  --env TASKGRAPH_TOOLS=standard \
  -- npx -y taskgraph-ai

Place your PRD in .taskgraph/docs/ (for example .taskgraph/docs/prd.md).
Talk to Claude Code (or use the /taskgraph: slash commands from the plugin or the CLI):

Can you parse my PRD at .taskgraph/docs/prd.md?
What's the next task I should work on?
Can you help me implement task 3?

Common Commands

After setting up TaskGraph, you can use these commands via slash commands, AI prompts or the CLI:

# Parse a PRD and generate tasks
taskgraph parse-prd .taskgraph/docs/prd.md

# List all tasks
taskgraph list

# Show the next task to work on
taskgraph next

Initial Task Generation

In Claude Code, instruct the agent to generate tasks from your PRD:

Please use the taskgraph parse-prd command to generate tasks from my PRD. The PRD is located at .taskgraph/docs/prd.md.

The agent will execute:

taskgraph parse-prd .taskgraph/docs/prd.md

This will:

Parse your PRD document
Generate a structured tasks.json file with tasks, dependencies, priorities, and test strategies
The agent will understand this process due to the imported CLAUDE.md guide

Generate Individual Task Files

Next, ask the agent to generate individual task files:

Please generate individual task files from tasks.json

AI-Driven Development Workflow

Claude Code is pre-configured (via the imported CLAUDE.md guide) to follow this workflow:

1. Task Discovery and Selection

Ask the agent to list available tasks:

What tasks are available to work on next?

Can you show me tasks 1, 3, and 5 to understand their current status?

The agent will:

Run taskgraph list to see all tasks
Run taskgraph next to determine the next task to work on
Run taskgraph show 1,3,5 to display multiple tasks with interactive options
Analyze dependencies to determine which tasks are ready to be worked on
Prioritize tasks by priority, then by how much work they unblock, then fewer dependencies, then ID order
Suggest the next task(s) to implement

2. Task Implementation

When implementing a task, the agent will:

Reference the task’s details section for implementation specifics
Consider dependencies on previous tasks
Follow the project’s coding standards
Create appropriate tests based on the task’s testStrategy

You can ask:

Let's implement task 3. What does it involve?

2.1. Viewing Multiple Tasks

For efficient context gathering and batch operations:

Show me tasks 5, 7, and 9 so I can plan my implementation approach.

The agent will:

Run taskgraph show 5,7,9 to display a compact summary table
Show task status, priority, and progress indicators
Provide an interactive action menu with batch operations
Allow you to perform group actions like marking multiple tasks as in-progress

3. Task Verification

Before marking a task as complete, verify it according to:

The task’s specified testStrategy
Any automated tests in the codebase
Manual verification if required

4. Task Completion

When a task is completed, tell the agent:

Task 3 is now complete. Please update its status.

The agent will execute:

taskgraph set-status --id=3 --status=done

5. Handling Implementation Drift

If during implementation, you discover that:

The current approach differs significantly from what was planned
Future tasks need to be modified due to current implementation choices
New dependencies or requirements have emerged

Tell the agent:

We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks (from ID 4) to reflect this change?

The agent will execute:

taskgraph update --from=4 --prompt="Now we are using MongoDB instead of PostgreSQL."

# OR, if research is needed to find best practices for MongoDB:
taskgraph update --from=4 --prompt="Update to use MongoDB, researching best practices" --research

This will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.

6. Reorganizing Tasks

If you need to reorganize your task structure:

I think subtask 5.2 would fit better as part of task 7 instead. Can you move it there?

The agent will execute:

taskgraph move --from=5.2 --to=7.3

You can reorganize tasks in various ways:

Moving a standalone task to become a subtask: --from=5 --to=7
Moving a subtask to become a standalone task: --from=5.2 --to=7
Moving a subtask to a different parent: --from=5.2 --to=7.3
Reordering subtasks within the same parent: --from=5.2 --to=5.4
Moving a task to a new ID position: --from=5 --to=25 (even if task 25 doesn’t exist yet)
Moving multiple tasks at once: --from=10,11,12 --to=16,17,18 (must have same number of IDs, TaskGraph will look through each position)

When moving tasks to new IDs:

The system automatically creates placeholder tasks for non-existent destination IDs
This prevents accidental data loss during reorganization
Any tasks that depend on moved tasks will have their dependencies updated
When moving a parent task, all its subtasks are automatically moved with it and renumbered

This is particularly useful as your project understanding evolves and you need to refine your task structure.

7. Resolving Merge Conflicts with Tasks

When working with a team, you might encounter merge conflicts in your tasks.json file if multiple team members create tasks on different branches. The move command makes resolving these conflicts straightforward:

I just merged the main branch and there's a conflict with tasks.json. My teammates created tasks 10-15 while I created tasks 10-12 on my branch. Can you help me resolve this?

The agent will help you:

Keep your teammates’ tasks (10-15)
Move your tasks to new positions to avoid conflicts:

# Move your tasks to new positions (e.g., 16-18)
taskgraph move --from=10 --to=16
taskgraph move --from=11 --to=17
taskgraph move --from=12 --to=18

This approach preserves everyone’s work while maintaining a clean task structure, making it much easier to handle task conflicts than trying to manually merge JSON files.

8. Breaking Down Complex Tasks

For complex tasks that need more granularity:

Task 5 seems complex. Can you break it down into subtasks?

The agent will execute:

taskgraph expand --id=5 --num=3

You can provide additional context:

Please break down task 5 with a focus on security considerations.

The agent will execute:

taskgraph expand --id=5 --prompt="Focus on security aspects"

You can also expand all pending tasks:

Please break down all pending tasks into subtasks.

The agent will execute:

taskgraph expand --all

For research-backed subtask generation using the configured research model:

Please break down task 5 using research-backed generation.

The agent will execute:

taskgraph expand --id=5 --research

Example Claude Code Interactions

Starting a new project

I've just initialized a new project with TaskGraph. I have a PRD at .taskgraph/docs/prd.md.
Can you help me parse it and set up the initial tasks?

Working on tasks

What's the next task I should work on? Please consider dependencies and priorities.

Implementing a specific task

I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?

Managing subtasks

I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?

Handling changes

We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?

Completing work

I've finished implementing the authentication system described in task 2. All tests are passing.
Please mark it as complete and tell me what I should work on next.

Analyzing complexity

Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?

Viewing complexity report

Can you show me the complexity report in a more readable format?

Research-Driven Development

TaskGraph includes a powerful research tool that provides fresh, up-to-date information beyond the AI’s knowledge cutoff. This is particularly valuable for:

Getting Current Best Practices

Before implementing task 5 (authentication), research the latest JWT security recommendations.

The agent will execute:

taskgraph research "Latest JWT security recommendations 2024" --id=5

Research with Project Context

Research React Query v5 migration strategies for our current API implementation.

The agent will execute:

taskgraph research "React Query v5 migration strategies" --files=src/api.js,src/hooks.js

Research and Update Pattern

A powerful workflow is to research first, then update tasks with findings:

Research the latest Node.js performance optimization techniques and update task 12 with the findings.

The agent will:

Run research: taskgraph research "Node.js performance optimization 2024" --id=12
Update the task: taskgraph update-subtask --id=12.2 --prompt="Updated with latest performance findings: [research results]"

When to Use Research

Before implementing any new technology
When encountering security-related tasks
For performance optimization tasks
When debugging complex issues
Before making architectural decisions
When updating dependencies

The research tool automatically includes relevant project context and provides fresh information that can significantly improve implementation quality.

Git Integration and Tag Management

TaskGraph supports tagged task lists for multi-context development, which is particularly useful when working with git branches or different project phases.

Working with Tags

Tags provide isolated task contexts, allowing you to maintain separate task lists for different features, branches, or experiments:

I'm starting work on a new feature branch. Can you create a new tag for this work?

The agent will execute:

# Create a tag based on your current git branch
taskgraph tags add <name> --from-branch

Or you can create a tag with a specific name:

Create a new tag called 'user-auth' for authentication-related tasks.

The agent will execute:

taskgraph tags add user-auth --description="User authentication feature tasks"

Switching Between Contexts

When working on different features or branches:

Switch to the 'user-auth' tag context so I can work on authentication tasks.

The agent will execute:

taskgraph tags use user-auth

Copying Tasks Between Tags

When you need to duplicate work across contexts:

Copy all tasks from the current tag to a new 'testing' tag for QA work.

The agent will execute:

taskgraph tags add testing --copy-from=master --description="QA and testing tasks"

Tag Management

View and manage your tag contexts:

Show me all available tags and their current status.

The agent will execute:

taskgraph tags --show-metadata

Benefits of Tagged Task Lists

Branch Isolation: Each git branch can have its own task context
Merge Conflict Prevention: Tasks in different tags don’t interfere with each other
Parallel Development: Multiple team members can work on separate contexts
Context Switching: Easily switch between different project phases or features
Experimentation: Create experimental task lists without affecting main work

Git Workflow Integration

A typical git workflow with TaskGraph tags:

Create feature branch: git checkout -b feature/user-auth
Create matching tag: Ask the agent to run taskgraph tags add <name> --from-branch
Work in isolated context: All task operations work within the new tag
Switch contexts as needed: Use taskgraph tags use <name> to switch between different work streams
Merge and cleanup: After merging the branch, optionally delete the tag with taskgraph tags remove <name>

This workflow ensures your task management stays organized and conflicts are minimized when working with teams or multiple features simultaneously.

Welcome

Getting Started

Best Practices

Technical Capabilities

Initial Setup

Common Commands

Initial Task Generation

Generate Individual Task Files

AI-Driven Development Workflow

1. Task Discovery and Selection

2. Task Implementation

2.1. Viewing Multiple Tasks

3. Task Verification

4. Task Completion

5. Handling Implementation Drift

6. Reorganizing Tasks

7. Resolving Merge Conflicts with Tasks

8. Breaking Down Complex Tasks

Example Claude Code Interactions

Starting a new project

Working on tasks

Implementing a specific task

Managing subtasks

Handling changes

Completing work

Analyzing complexity

Viewing complexity report

Research-Driven Development

Getting Current Best Practices

Research with Project Context

Research and Update Pattern

When to Use Research

Git Integration and Tag Management

Working with Tags

Switching Between Contexts

Copying Tasks Between Tags

Tag Management

Benefits of Tagged Task Lists

Git Workflow Integration

​Initial Setup

​Common Commands

​Initial Task Generation

​Generate Individual Task Files

​AI-Driven Development Workflow

​1. Task Discovery and Selection

​2. Task Implementation

​2.1. Viewing Multiple Tasks

​3. Task Verification

​4. Task Completion

​5. Handling Implementation Drift

​6. Reorganizing Tasks

​7. Resolving Merge Conflicts with Tasks

​8. Breaking Down Complex Tasks

​Example Claude Code Interactions

​Starting a new project

​Working on tasks

​Implementing a specific task

​Managing subtasks

​Handling changes

​Completing work

​Analyzing complexity

​Viewing complexity report

​Research-Driven Development

​Getting Current Best Practices

​Research with Project Context

​Research and Update Pattern

​When to Use Research

​Git Integration and Tag Management

​Working with Tags

​Switching Between Contexts

​Copying Tasks Between Tags

​Tag Management

​Benefits of Tagged Task Lists

​Git Workflow Integration

Initial Setup

Common Commands

Initial Task Generation

Generate Individual Task Files

AI-Driven Development Workflow

1. Task Discovery and Selection

2. Task Implementation

2.1. Viewing Multiple Tasks

3. Task Verification

4. Task Completion

5. Handling Implementation Drift

6. Reorganizing Tasks

7. Resolving Merge Conflicts with Tasks

8. Breaking Down Complex Tasks

Example Claude Code Interactions

Starting a new project

Working on tasks

Implementing a specific task

Managing subtasks

Handling changes

Completing work

Analyzing complexity

Viewing complexity report

Research-Driven Development

Getting Current Best Practices

Research with Project Context

Research and Update Pattern

When to Use Research

Git Integration and Tag Management

Working with Tags

Switching Between Contexts

Copying Tasks Between Tags

Tag Management

Benefits of Tagged Task Lists

Git Workflow Integration