# Task Master AI - Agent Integration Guide

This guide provides AI agents with essential information for integrating Task Master across all supported AI development tools. Task Master is a task management system that enables structured, iterative development workflows through MCP integration.

## Target Audience

This guide is for AI agents operating within:

- **Claude Code** - Anthropic's CLI assistant
- **Cursor IDE** - AI-first code editor
- **Codex CLI** - OpenAI command-line interface

Users of the ai-toolkit should have Task Master globally installed and configured via MCP.

## Security Model

**Task Master uses MCP exclusively.** AI agents should never use CLI commands or access credentials directly.

**Why MCP-only:**

- Credentials are stored securely in 1Password with `op://` references
- MCP servers handle credential injection at runtime
- AI agents never see actual API keys
- Prevents credential exposure in logs, history, or error messages

**For 1Password integration details, see [agents.onepassword.md](./agents.onepassword.md)**

## Installation & Setup

Task Master integrates via MCP (Model Context Protocol) and should be installed **globally** for user-level access across all projects.

### Global MCP Installation

**Install via ai-toolkit installer** (handles all configuration automatically):

```bash
ai-toolkit install -t claude
```

This command:

- Configures Task Master MCP server globally
- Sets up API keys from 1Password (`op://` references)
- Configures credential protection in `~/.claude/settings.json`
- Makes Task Master available across all projects
- Skips installation if already configured

**Important:** Do NOT use project-level `.mcp.json` files. Task Master should be globally available for consistent workflows across all projects.

### Verify Installation

Check that Task Master MCP is configured:

```bash
claude mcp list
```

You should see `task-master-ai` in the list of connected servers.

### API Keys Required

Task Master requires API keys stored in 1Password:

| Service    | Purpose                    | 1Password Item                    |
| ---------- | -------------------------- | --------------------------------- |
| Anthropic  | Claude models (main tasks) | `op://Private/Anthropic/API Key`  |
| Perplexity | Research features          | `op://Private/Perplexity/API Key` |

Additional optional providers: OpenAI, Google, Mistral, OpenRouter, XAI

### Token Optimization

The ai-toolkit installer configures Task Master with token-optimized defaults to reduce context usage:

| Environment Variable | Default Value | Purpose                                       |
| -------------------- | ------------- | --------------------------------------------- |
| `TASK_MASTER_TOOLS`  | `standard`    | Controls which MCP tools load                 |
| `DEFAULT_TAG`        | `main`        | Default tag context for git-centric workflows |

**Tool Tiers:**

| Tier            | Tools    | Tokens      | Best For                             |
| --------------- | -------- | ----------- | ------------------------------------ |
| `all`           | 36 tools | ~21k tokens | Full functionality, complex projects |
| `standard`      | 15 tools | ~10k tokens | Most workflows (50% reduction)       |
| `core` / `lean` | 7 tools  | ~5k tokens  | Minimal context (70% reduction)      |

The `standard` tier includes essential tools: `get_tasks`, `get_task`, `set_task_status`, `add_task`, `expand_task`, `update_task`, `update_subtask`, `next_task`, `add_dependency`, `remove_dependency`, `validate_dependencies`, `initialize_project`, `models`, `parse_prd`, and `research`.

**Override at project level:**

If you need all tools for a specific project, add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "task-master-ai": {
      "env": {
        "TASK_MASTER_TOOLS": "all"
      }
    }
  }
}
```

**DEFAULT_TAG:**

The `DEFAULT_TAG=main` setting aligns Task Master with git-centric workflows where `main` is the primary branch. Tasks are tagged relative to this context.

## MCP Availability Check

**CRITICAL:** AI agents must verify MCP availability before using Task Master MCP tools.

### Check MCP Server Status

Before attempting any MCP operations, agents MUST check if the Task Master MCP server is available:

```bash
# Check if MCP server is configured
claude mcp list | grep -q "task-master-ai"
echo $?  # Returns 0 if found, 1 if not found
```

### If MCP is NOT Available

**Do NOT use CLI fallback.** Instead, guide the user to configure MCP:

```text
Task Master MCP is not configured.

To set it up:
1. Run: ai-toolkit install -t claude
2. Ensure 1Password is unlocked
3. Restart Claude Code

This will securely configure Task Master with your API keys from 1Password.
```

**Why no CLI fallback:**

- CLI requires exposing credentials in environment variables
- Environment variables can leak to logs, error messages, command history
- 1Password `op://` references only work with MCP server startup
- MCP provides secure credential injection without exposure

## Project Structure

After initializing Task Master in a project, the following structure is created:

````text
project/
├── .taskmaster/
│   ├── tasks/
│   │   ├── tasks.json          # Main task database (auto-managed)
│   │   ├── task-1.md          # Individual task files (auto-generated)
│   │   └── task-2.md
│   ├── docs/
│   │   └── prd.txt            # Product Requirements Document
│   ├── reports/
│   │   └── task-complexity-report.json
│   ├── templates/
│   │   └── example_prd.txt
│   ├── config.json            # AI model configuration
│   └── CLAUDE.md             # Auto-generated Task Master reference
├── .claude/
│   ├── settings.json          # Claude Code tool allowlist
│   └── commands/             # Custom slash commands
└── .env                      # API keys (gitignored)
```text

**Important:**

- Never manually edit `tasks.json` - use MCP tools instead
- Never manually edit `.taskmaster/config.json` - use `models` MCP tool
- `.taskmaster/CLAUDE.md` is auto-generated by Task Master initialization
- Root `CLAUDE.md` should reference this guide, not `.taskmaster/CLAUDE.md`

## MCP Tools Reference

Use MCP tools instead of CLI commands. MCP tools provide better error handling and integration with AI workflows.

### Project Setup

```javascript
// Initialize Task Master in current project
mcp__task_master_ai__initialize_project({ projectRoot: "/absolute/path/to/project" })

// Parse PRD to generate tasks
mcp__task_master_ai__parse_prd({
  projectRoot: "/absolute/path/to/project",
  input: ".taskmaster/docs/prd.txt",
  numTasks: "10",
  research: true
})

// Configure AI models
mcp__task_master_ai__models({
  projectRoot: "/absolute/path/to/project",
  setMain: "claude-3-5-sonnet-20241022",
  setResearch: "perplexity-llama-3.1-sonar-large-128k-online",
  setFallback: "gpt-4o-mini"
})
```text

### Daily Workflow

```javascript
// Get next available task
mcp__task_master_ai__next_task({ projectRoot: "/absolute/path/to/project" })

// Get all tasks with optional status filter
mcp__task_master_ai__get_tasks({
  projectRoot: "/absolute/path/to/project",
  status: "pending",
  withSubtasks: true
})

// Get specific task details
mcp__task_master_ai__get_task({
  projectRoot: "/absolute/path/to/project",
  id: "1.2"
})

// Update task status
mcp__task_master_ai__set_task_status({
  projectRoot: "/absolute/path/to/project",
  id: "1.2",
  status: "done"
})
```text

### Task Management

```javascript
// Add new task with AI assistance
mcp__task_master_ai__add_task({
  projectRoot: "/absolute/path/to/project",
  prompt: "Implement user authentication with JWT",
  research: true
})

// Expand task into subtasks
mcp__task_master_ai__expand_task({
  projectRoot: "/absolute/path/to/project",
  id: "1",
  num: "5",
  research: true
})

// Update specific task
mcp__task_master_ai__update_task({
  projectRoot: "/absolute/path/to/project",
  id: "1.2",
  prompt: "Add OAuth2 support to authentication"
})

// Update subtask with implementation notes
mcp__task_master_ai__update_subtask({
  projectRoot: "/absolute/path/to/project",
  id: "1.2",
  prompt: "Implemented JWT token generation and validation"
})

// Update multiple tasks from ID onwards
mcp__task_master_ai__update({
  projectRoot: "/absolute/path/to/project",
  from: "5",
  prompt: "Adjust tasks to use new authentication system"
})
```text

### Analysis & Planning

```javascript
// Analyze task complexity
mcp__task_master_ai__analyze_project_complexity({
  projectRoot: "/absolute/path/to/project",
  research: true,
  threshold: 5
})

// View complexity report
mcp__task_master_ai__complexity_report({
  projectRoot: "/absolute/path/to/project"
})

// Expand all pending tasks
mcp__task_master_ai__expand_all({
  projectRoot: "/absolute/path/to/project",
  num: "3",
  research: true
})
```text

### Dependencies & Organization

```javascript
// Add task dependency
mcp__task_master_ai__add_dependency({
  projectRoot: "/absolute/path/to/project",
  id: "2",
  dependsOn: "1"
})

// Remove dependency
mcp__task_master_ai__remove_dependency({
  projectRoot: "/absolute/path/to/project",
  id: "2",
  dependsOn: "1"
})

// Validate dependencies
mcp__task_master_ai__validate_dependencies({
  projectRoot: "/absolute/path/to/project"
})

// Fix invalid dependencies
mcp__task_master_ai__fix_dependencies({
  projectRoot: "/absolute/path/to/project"
})

// Move task to new position
mcp__task_master_ai__move_task({
  projectRoot: "/absolute/path/to/project",
  from: "5",
  to: "3"
})
```text

### Tags & Organization

```javascript
// List all tags
mcp__task_master_ai__list_tags({
  projectRoot: "/absolute/path/to/project"
})

// Add new tag
mcp__task_master_ai__add_tag({
  projectRoot: "/absolute/path/to/project",
  name: "feature/auth",
  description: "Authentication feature tasks"
})

// Switch to tag context
mcp__task_master_ai__use_tag({
  projectRoot: "/absolute/path/to/project",
  name: "feature/auth"
})
```text

### Research

```javascript
// Perform research query with project context
mcp__task_master_ai__research({
  projectRoot: "/absolute/path/to/project",
  query: "Best practices for JWT token expiration",
  taskIds: "1.2,1.3",
  saveTo: "1.2"
})
```text

## Standard Development Workflows

### Initial Project Setup

1. Initialize Task Master in project
2. Create or obtain PRD document
3. Parse PRD to generate tasks
4. Analyze task complexity
5. Expand complex tasks into subtasks

```javascript
// 1. Initialize
mcp__task_master_ai__initialize_project({ projectRoot: "/path/to/project" })

// 2. Parse PRD (assumes prd.txt exists in .taskmaster/docs/)
mcp__task_master_ai__parse_prd({
  projectRoot: "/path/to/project",
  input: ".taskmaster/docs/prd.txt",
  numTasks: "10",
  research: true
})

// 3. Analyze complexity
mcp__task_master_ai__analyze_project_complexity({
  projectRoot: "/path/to/project",
  research: true
})

// 4. Expand all tasks
mcp__task_master_ai__expand_all({
  projectRoot: "/path/to/project",
  research: true
})
```text

### Daily Development Loop

1. Get next available task
2. Review task details and subtasks
3. Mark task as in-progress
4. Implement code
5. Log implementation notes to subtask
6. Mark subtask as done
7. Repeat for remaining subtasks
8. Mark main task as done

```javascript
// 1. Get next task
mcp__task_master_ai__next_task({ projectRoot: "/path/to/project" })

// 2. Review task details
mcp__task_master_ai__get_task({
  projectRoot: "/path/to/project",
  id: "1.2"
})

// 3. Mark as in-progress
mcp__task_master_ai__set_task_status({
  projectRoot: "/path/to/project",
  id: "1.2",
  status: "in-progress"
})

// 4. During implementation, log notes
mcp__task_master_ai__update_subtask({
  projectRoot: "/path/to/project",
  id: "1.2",
  prompt: "Implemented JWT token generation with 1-hour expiration"
})

// 5. Mark as done
mcp__task_master_ai__set_task_status({
  projectRoot: "/path/to/project",
  id: "1.2",
  status: "done"
})
```text

### Iterative Task Refinement

When implementing a subtask:

1. Review subtask requirements
2. Explore codebase to understand context
3. Log detailed implementation plan
4. Mark as in-progress
5. Implement code following plan
6. Log what worked and what didn't
7. Mark as done

```javascript
// Log implementation plan
mcp__task_master_ai__update_subtask({
  projectRoot: "/path/to/project",
  id: "1.2.1",
  prompt: "Plan: Create JWT utility class with generate() and validate() methods"
})

// After implementation, log results
mcp__task_master_ai__update_subtask({
  projectRoot: "/path/to/project",
  id: "1.2.1",
  prompt: "Completed: JWT utility implemented. Used jsonwebtoken library. Added expiration validation."
})
```text

### Complex Workflows

For large migrations or multi-step processes:

1. Create markdown PRD file describing changes
2. Parse new PRD with `--append` flag
3. Analyze complexity of new tasks
4. Expand new tasks into subtasks
5. Work through systematically
6. Log progress on each task/subtask

```javascript
// Parse additional PRD
mcp__task_master_ai__parse_prd({
  projectRoot: "/path/to/project",
  input: ".taskmaster/docs/migration-checklist.md",
  append: true,
  research: true
})

// Analyze new tasks (assuming they start at ID 15)
mcp__task_master_ai__analyze_project_complexity({
  projectRoot: "/path/to/project",
  from: 15,
  research: true
})
```text

### Agent Workflow with MCP

**Complete workflow for AI agents to follow:**

```typescript
// Step 1: Check MCP availability
async function checkTaskMasterMCPAvailable(): Promise<boolean> {
  try {
    const result = await bash('claude mcp list | grep -q "task-master-ai"');
    return result.exitCode === 0;
  } catch {
    return false;
  }
}

// Step 2: Use Task Master MCP (or guide user to install)
async function getNextTask(projectRoot: string) {
  const mcpAvailable = await checkTaskMasterMCPAvailable();

  if (mcpAvailable) {
    // Use MCP tools
    return await mcp__task_master_ai__next_task({ projectRoot });
  } else {
    // Guide user to install - do NOT use CLI fallback
    throw new Error(
      "Task Master MCP is not configured.\n\n" +
      "To set it up:\n" +
      "1. Run: ai-toolkit install -t claude\n" +
      "2. Ensure 1Password is unlocked\n" +
      "3. Restart Claude Code"
    );
  }
}
````

**Example usage in agent context:**

```typescript
// When starting work on tasks
async function startTaskWork() {
  const projectRoot = '/absolute/path/to/project';

  try {
    // Get next task via MCP
    const task = await mcp__task_master_ai__next_task({ projectRoot });

    console.log(`Working on task ${task.id}: ${task.title}`);

    // Continue with implementation...
  } catch (error) {
    console.error('Failed to get next task:', error.message);
    console.log('Please run: ai-toolkit install -t claude');
  }
}
```

## Task Structure

### Task ID Format

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

### Task Status Values

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

### Task Fields

````json
{
  "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. Implement refresh token mechanism.",
  "testStrategy": "Unit tests for auth functions, integration tests for login flow",
  "subtasks": []
}
```text

## Custom Slash Commands

Task Master workflows can be streamlined with custom slash commands. These should be created in `.claude/commands/` directory.

### /taskmaster-next

Find and display the next available task.

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

Steps:
1. Use mcp__task_master_ai__next_task to get the next task
2. If a task is available, use mcp__task_master_ai__get_task to get full details
3. Provide a summary of what needs to be implemented
4. Suggest the first implementation step
```text

### /taskmaster-complete

Complete a task and move to the next one.

```markdown
Complete Task Master task: $ARGUMENTS

Steps:
1. Use mcp__task_master_ai__get_task to review task details
2. Verify all implementation is complete
3. Run any tests related to this task
4. Use mcp__task_master_ai__set_task_status to mark as done
5. Use mcp__task_master_ai__next_task to show the next available task
```text

### /taskmaster-expand

Expand a task into subtasks with AI assistance.

```markdown
Expand Task Master task into subtasks: $ARGUMENTS

Steps:
1. Use mcp__task_master_ai__get_task to review current task
2. Use mcp__task_master_ai__expand_task with research enabled
3. Display the generated subtasks
4. Suggest starting with the first subtask
```text

### /taskmaster-log

Log implementation notes to current subtask.

```markdown
Log implementation notes to Task Master subtask: $ARGUMENTS

Format: /taskmaster-log <subtask-id> <notes>

Steps:
1. Parse subtask ID and notes from arguments
2. Use mcp__task_master_ai__update_subtask to log notes
3. Confirm notes were saved
```text

### /taskmaster-status

Show current Task Master status and progress.

```markdown
Display Task Master project status.

Steps:
1. Use mcp__task_master_ai__get_tasks with status filter
2. Show count of tasks by status (pending, in-progress, done, blocked)
3. Show current in-progress tasks
4. Show next 3 pending tasks
```text

### /taskmaster-research

Perform research query with Task Master context.

```markdown
Research a topic with Task Master context: $ARGUMENTS

Steps:
1. Use mcp__task_master_ai__research with the query
2. Display research results
3. Ask if results should be saved to a specific task
```text

## Tool Allowlist Configuration

For Claude Code, configure tool allowlist in `.claude/settings.json`:

```json
{
  "allowedTools": [
    "Edit",
    "Read",
    "Glob",
    "Grep",
    "Bash(git add:*)",
    "Bash(git commit:*)",
    "Bash(npm run *)",
    "Bash(bun run *)",
    "Bash(task *)",
    "mcp__task_master_ai__*"
  ]
}
```text

This allows all Task Master MCP tools without individual approval prompts.

## Best Practices for AI Agents

### MCP-Only Usage

**Always use MCP tools for Task Master.** Never use CLI commands or access credentials directly.

```bash
# Check if MCP server is available
claude mcp list | grep -q "task-master-ai"

# If available: Use MCP tools
# If NOT available: Guide user to run ai-toolkit install
````

**If MCP is not configured**, inform the user:

```text
Task Master MCP is not configured.
Run: ai-toolkit install -t claude
```

See [MCP Availability Check](#mcp-availability-check) section for complete workflow.

### Context Management

- Use `/clear` between different tasks to maintain focus
- Task Master reference files (`.taskmaster/CLAUDE.md`) are auto-loaded by Task Master
- This guide provides comprehensive Task Master integration information
- Pull specific task context using `get_task` MCP tool when needed

### Logging Implementation Progress

Always log implementation progress to subtasks:

````javascript
// Before implementation
mcp__task_master_ai__update_subtask({
  projectRoot: "/path/to/project",
  id: "1.2.1",
  prompt: "Plan: Implement JWT token generation with HS256 algorithm"
})

// After implementation
mcp__task_master_ai__update_subtask({
  projectRoot: "/path/to/project",
  id: "1.2.1",
  prompt: "Completed: JWT generation working. Added tests. Token expires in 1 hour."
})
```text

### Research-Backed Operations

For complex technical tasks, enable research mode:

```javascript
mcp__task_master_ai__add_task({
  projectRoot: "/path/to/project",
  prompt: "Implement secure password hashing",
  research: true  // Enables research for informed recommendations
})
```text

Research mode requires `PERPLEXITY_API_KEY` in environment.

### Multi-Task Updates

When changes affect multiple tasks:

```javascript
// Update all tasks from ID 5 onwards
mcp__task_master_ai__update({
  projectRoot: "/path/to/project",
  from: "5",
  prompt: "Update tasks to use new database schema"
})
```text

### Git Integration

Reference Task Master tasks in commit messages:

```bash
git commit -m "feat: implement JWT auth (task 1.2)"
```text

Create pull requests referencing completed tasks:

```bash
gh pr create \
  --title "Complete task 1.2: User authentication" \
  --body "Implements JWT auth system as specified in task 1.2"
```text

### Parallel Development

For complex projects, use multiple AI agent sessions:

```bash
# Terminal 1: Main implementation
cd project && claude

# Terminal 2: Testing and validation
cd project && claude

# Terminal 3: Documentation updates
cd project && claude
```text

Each session can work on different Task Master tasks simultaneously.

## AI-Powered Operations

These MCP tools make AI calls and may take 30-60 seconds:

- `parse_prd` - Generates tasks from PRD
- `analyze_project_complexity` - Analyzes task complexity
- `expand_task` - Breaks task into subtasks
- `expand_all` - Expands all pending tasks
- `add_task` - Creates new task with AI
- `update` - Updates multiple tasks
- `update_task` - Updates single task
- `update_subtask` - Updates subtask
- `research` - Performs research query

Plan accordingly and inform users when these operations are running.

## Troubleshooting

### MCP Connection Issues

If Task Master MCP tools are unavailable:

1. **Check MCP server status**: `claude mcp list | grep task-master-ai`
2. **Verify 1Password is unlocked**: Open 1Password app and authenticate
3. **Verify API keys exist in 1Password**: Check `Private/Anthropic` and `Private/Perplexity` items
4. **Restart Claude Code**: MCP servers load credentials at startup
5. **Re-run installer**: `ai-toolkit install -t claude`

**If MCP is not configured:**

Run the installer to configure MCP with secure credential handling:

```bash
ai-toolkit install -t claude
````

This will:

- Configure Task Master MCP server
- Set up `op://` references for API keys
- Configure credential protection in settings.json

**Do NOT manually configure MCP with raw credentials.** The installer handles secure configuration automatically.

### Model Configuration Issues

If AI operations fail:

````javascript
// Check current model configuration
mcp__task_master_ai__models({ projectRoot: "/path/to/project" })

// Set different models
mcp__task_master_ai__models({
  projectRoot: "/path/to/project",
  setMain: "claude-3-5-sonnet-20241022",
  setFallback: "gpt-4o-mini"
})
```text

### Task File Sync Issues

If tasks.json and markdown files are out of sync:

```javascript
// Regenerate task markdown files
mcp__task_master_ai__generate({ projectRoot: "/path/to/project" })
```text

### Dependency Issues

If dependency errors occur:

```javascript
// Validate dependencies
mcp__task_master_ai__validate_dependencies({ projectRoot: "/path/to/project" })

// Fix invalid dependencies
mcp__task_master_ai__fix_dependencies({ projectRoot: "/path/to/project" })
```text

## Important Reminders

1. **Use MCP tools exclusively** - Never use CLI commands or access credentials directly
2. **Guide users to installer** - If MCP is not configured, tell users to run `ai-toolkit install -t claude`
3. **Never manually edit tasks.json** - Use MCP tools for all modifications
4. **Use absolute paths** - All `projectRoot` parameters must be absolute paths
5. **Log implementation progress** - Update subtasks with notes during implementation
6. **Enable research mode** - Use `research: true` for complex technical tasks
7. **Mark tasks as in-progress** - Update status when starting work on a task
8. **Validate dependencies** - Run validation after adding/removing dependencies
9. **Use tags for organization** - Create tags for features, sprints, or team members
10. **Reference tasks in commits** - Include task IDs in commit messages and PRs
11. **Check task status regularly** - Use `get_tasks` MCP tool to monitor progress

## Cross-Tool Compatibility

### Claude Code

Full Task Master support via MCP. Use custom slash commands for streamlined workflows.

### Cursor IDE

MCP support available. Configure in Cursor settings under "MCP Servers". Use same MCP tools as Claude Code.

### Codex CLI

MCP support available. Configure via Codex settings. Limited slash command support.

## Documentation Standards

When generating project documentation, follow markdown formatting standards:

- See [docs/guides/agent-documentation-standards.md](../agent-documentation-standards.md) for AI agent documentation standards
- Key principle: Structure and concepts first, implementation details hidden
- This guide is AI-agent-focused and does not use collapsible sections

---

**For comprehensive Task Master documentation:**

- Task Master GitHub: https://github.com/eyaltoledano/task-master-ai
- Task Master NPM: https://www.npmjs.com/package/task-master-ai

**For ai-toolkit installation and configuration:**

- See root CLAUDE.md for ai-toolkit project guidelines
- See .taskmaster/CLAUDE.md (auto-generated) for Task Master project-specific reference
````