tst-claude-code-samples/.cursor/rules/taskmaster/taskmaster.mdc

---
description: Comprehensive reference for Taskmaster MCP tools and CLI commands
globs: **/*
alwaysApply: true
---

# Taskmaster Tool & Command Reference

**Core Concept:** Tagged task management system - tasks organized in isolated contexts (tags) for features/branches/phases.

**⚠️ CRITICAL:** Never work on `master` tag - use feature tags. Master is for high-level deliverables only.

**Note:** MCP tools recommended over CLI (better performance/error handling). AI tools may take ~1min: `parse_prd`, `analyze_project_complexity`, `update_*`, `expand_*`, `add_task`.

## Commands Reference

### Initialize Project
**MCP:** `initialize_project` | **CLI:** `task-master init`
- Setup Taskmaster file structure and config
- Key params: `projectName`, `projectDescription`, `projectVersion`, `skipInstall`, `addAliases`
- **Important:** Must parse PRD after init to generate tasks
- Example PRD template in `.taskmaster/templates/example_prd.txt`

### Parse PRD
**MCP:** `parse_prd` | **CLI:** `task-master parse-prd`
- Parse PRD/text file to generate tasks.json
- Params: `input`, `output`, `numTasks`, `force`, `tag`
- Always parse into feature tags, not master
- Create PRDs per context: `prd-<feature>.md`
- **AI tool - may take ~1min**

### Models Configuration
**MCP:** `models` | **CLI:** `task-master models`
- View/set AI models for roles: main, research, fallback
- Params: `setMain`, `setResearch`, `setFallback`, `ollama`, `openrouter`
- Config stored in `.taskmaster/config.json` (don't edit manually)
- API keys required in mcp.json (MCP) or .env (CLI)
- Costs in $: 3 = $3.00, 0.8 = $0.80

### Task Viewing
**Get Tasks:** `get_tasks` / `task-master list`
- Filter by status, show subtasks, specify tag

**Next Task:** `next_task` / `task-master next`
- Shows next available task based on dependencies

**Get Task:** `get_task` / `task-master show`
- View specific task(s) - use comma-separated IDs for multiple (1,2,3)
- **CRITICAL:** Use batch IDs to avoid multiple calls

### Task Creation
**Add Task:** `add_task` / `task-master add-task`
- Params: `prompt` (required), `dependencies`, `priority`, `research`, `tag`
- **AI tool - may take ~1min**

**Add Subtask:** `add_subtask` / `task-master add-subtask`
- Add to parent or convert existing task
- Params: `id` (parent), `taskId`, `title`, `description`, `details`, `dependencies`, `status`

### Task Updates
**Update Tasks:** `update` / `task-master update`
- Update multiple tasks from ID onwards
- Params: `from` (required), `prompt` (required), `research`
- **AI tool - may take ~1min**

**Update Task:** `update_task` / `task-master update-task`
- Update single task by ID
- Params: `id`, `prompt`, `append`, `research`
- Use `--append` to log progress
- **AI tool - may take ~1min**

**Update Subtask:** `update_subtask` / `task-master update-subtask`
- Append timestamped progress to subtask
- Params: `id`, `prompt`, `research`
- **AI tool - may take ~1min**

**Set Status:** `set_task_status` / `task-master set-status`
- Update status: pending, in-progress, done, review, cancelled
- Supports multiple IDs: '15,15.2,16'

**Remove Task:** `remove_task` / `task-master remove-task`
- Permanently delete task/subtask
- Consider using status instead of deletion

### Task Breakdown
**Expand Task:** `expand_task` / `task-master expand`
- Break task into subtasks
- Params: `id`, `num`, `research`, `prompt`, `force`
- Uses complexity report if available
- **AI tool - may take ~1min**

**Expand All:** `expand_all` / `task-master expand --all`
- Expand all eligible tasks
- Same params as expand_task
- **AI tool - may take ~1min**

**Clear Subtasks:** `clear_subtasks` / `task-master clear-subtasks`
- Remove all subtasks from parent(s)

**Remove Subtask:** `remove_subtask` / `task-master remove-subtask`
- Remove or convert subtask to top-level task

**Move Task:** `move_task` / `task-master move`
- Move task/subtask in hierarchy
- Params: `from`, `to` (supports comma-separated)
- Useful for merge conflicts

### Dependency Management
**Add/Remove Dependency:** `add_dependency`/`remove_dependency`
- Define task prerequisites

**Validate/Fix Dependencies:** `validate_dependencies`/`fix_dependencies`
- Check and fix circular references or missing tasks

### Analysis
**Analyze Complexity:** `analyze_project_complexity` / `task-master analyze-complexity`
- Score tasks 1-10, suggest expansions
- **AI tool - may take ~1min**

**View Report:** `complexity_report` / `task-master complexity-report`

### Files
**Generate:** `generate` / `task-master generate`
- Create markdown files from tasks.json

### Research
**Research:** `research` / `task-master research`
- Get fresh info beyond AI cutoff
- Params: `query`, `taskIds`, `filePaths`, `customContext`, `includeProjectTree`, `detailLevel`
- **USE FREQUENTLY** for:
  - Latest best practices
  - New tech guidance
  - Security updates
  - Dependency changes
- **AI tool - may take ~1min**

### Tag Management (Essential)
**List Tags:** `list_tags` / `task-master tags`

**Add Tag:** `add_tag` / `task-master add-tag`
- Create feature/branch contexts
- Options: `--from-branch`, `--copy-from`, `--description`

**Use Tag:** `use_tag` / `task-master use-tag`
- **CRITICAL:** Switch to feature tag before work

**Delete/Rename/Copy Tag:** Standard operations

### Misc
**Sync Readme:** CLI only - `task-master sync-readme` (experimental)

## Configuration

**Config File:** `.taskmaster/config.json` (via `models` command)
**API Keys:** `.env` (CLI) or `mcp.json` env section (MCP)
- Required: Provider-specific API keys
- Optional: `AZURE_OPENAI_ENDPOINT`, `OLLAMA_BASE_URL`

## Key Concepts

**Tagged System:**
- Each tag = isolated task context (1, 2, 3...)
- No cross-tag dependencies
- Always verify active tag
- Never edit tasks.json manually

**Workflow:** See [dev-workflow.mdc](mdc:.cursor/rules/taskmaster/dev-workflow.mdc) for patterns

**Quick Reference:**
1. `add_tag` → `use_tag` → `parse_prd`
2. `analyze_complexity` → `expand_task/expand_all`
3. `next_task` → implement → `update_subtask` → `set_task_status`