# Task Master AI - Claude Code Integration Guide ## Tagged Task Management System Task Master uses a **tagged task management system** that organizes tasks into separate, isolated contexts called **tags**. This enables working across multiple contexts such as different features, branches, or project phases without conflicts. ### Tagged System Benefits - **Complete Context Isolation**: Each tag maintains its own task numbering (starting from 1) - **Parallel Development**: Multiple features can be developed simultaneously without conflicts - **Independent Dependencies**: Task dependencies are managed within each tag context - **Flexible Organization**: Align tags with git branches, features, or project phases - **Team Collaboration**: Clear ownership and responsibility per tag context ## Essential Commands ### Tag Management Commands ```bash # Tag Context Management task-master tags # List all available tags with status task-master tags --show-metadata # List tags with detailed metadata task-master add-tag # Create a new empty tag task-master add-tag --description="desc" # Create tag with description task-master add-tag --from-branch # Create tag from current git branch task-master use-tag # Switch to a different tag context task-master copy-tag # Copy entire tag to create new one task-master delete-tag # Delete tag and all its tasks task-master rename-tag # Rename an existing tag # Tag-based Task Operations (all work within current tag context) task-master list # Show tasks in current tag task-master next # Get next task in current tag task-master show # View task in current tag (e.g., 1.2) task-master add-task --prompt="description" # Add task to current tag ``` ### Core Workflow Commands ```bash # Project Setup task-master init # Initialize Task Master with tagged system task-master models --setup # Configure AI models interactively # Tagged PRD Workflow task-master use-tag # Switch to tag context task-master parse-prd .taskmaster/docs/prd-.md # Generate tasks from PRD in current tag # Daily Development Workflow (within current tag) task-master list # Show all tasks in current tag task-master next # Get next available task in current tag task-master show # View detailed task information task-master set-status --id= --status=done # Mark task complete in current tag # Task Management (within current tag) task-master expand --id= --research --force # Break task into subtasks task-master update-task --id= --prompt="changes" # Update specific task task-master update --from= --prompt="changes" # Update multiple tasks from ID onwards task-master update-subtask --id= --prompt="notes" # Add implementation notes to subtask # Analysis & Planning (within current tag) task-master analyze-complexity --research # Analyze task complexity in current tag task-master complexity-report # View complexity analysis for current tag task-master expand --all --research # Expand all eligible tasks in current tag # Dependencies & Organization (within current tag) task-master add-dependency --id= --depends-on= # Add task dependency task-master move --from= --to= # Reorganize task hierarchy task-master validate-dependencies # Check for dependency issues task-master generate # Update task markdown files ``` ## Tagged Workflow Integration ### ⚠️ CRITICAL RULE: Never Work on Master Tag **NEVER work directly on the `master` tag.** Always switch to a feature-specific tag before working with Task Master: ```bash # ❌ BAD - Working on master tag task-master use-tag master task-master next # Don't do this! # ✅ GOOD - Switch to feature tag first task-master add-tag modal-panel-isolation --description="Modal panel isolation feature" task-master use-tag modal-panel-isolation task-master parse-prd .taskmaster/docs/prd-modal-panel-isolation.md task-master next # Now this is correct! ``` ### Setting Up Tagged Contexts #### 1. Initialize Multiple Tag Contexts ```bash # Create tag contexts for different features/areas task-master add-tag user-auth --description="User authentication features" task-master add-tag payments --description="Payment system implementation" task-master add-tag mobile --description="Mobile app development" task-master add-tag admin --description="Admin dashboard features" ``` #### 2. Organize Tagged PRDs Create PRDs for different contexts: ``` .taskmaster/docs/ prd-master.md # Main project PRD prd-user-authentication.md # Authentication feature PRD prd-payment-system.md # Payment system PRD prd-mobile-app.md # Mobile app PRD prd-admin-dashboard.md # Admin features PRD ``` #### 3. Parse PRDs into Tag Contexts ```bash # Switch to authentication context and parse its PRD task-master use-tag user-auth task-master parse-prd .taskmaster/docs/prd-user-authentication.md # Switch to payments context and parse its PRD task-master use-tag payments task-master parse-prd .taskmaster/docs/prd-payment-system.md # Continue for each feature area... ``` ### Daily Tagged Development Workflow #### 1. Tag Context Management ```bash # Check available tag contexts task-master tags --show-metadata # Switch to desired context (NEVER master for feature work!) task-master use-tag user-auth # Work within that context task-master next # Find next task in current tag task-master show # Review task details in current tag ``` #### 2. Cross-Tag Development ```bash # Work on authentication, then switch to mobile task-master use-tag user-auth task-master list # See auth tasks # ... work on auth tasks ... task-master use-tag mobile task-master list # See mobile tasks # ... work on mobile tasks ... ``` #### 3. Tag-Specific Implementation ```bash # Within a tag context, all operations are isolated task-master update-subtask --id=2.1 --prompt="implementation notes..." # Updates task 2.1 in current tag only task-master set-status --id=3 --status=done # Marks task 3 done in current tag only ``` ### Advanced Tagged Workflows #### Branch-Based Tag Management ```bash # Align tag contexts with git branches git checkout -b feature/authentication task-master add-tag --from-branch # Creates tag from branch name git checkout -b feature/payments task-master add-tag --from-branch # Creates another tag ``` #### Tag Copying and Templates ```bash # Create new contexts from existing ones task-master copy-tag user-auth admin-auth --description="Admin authentication" # Copy tasks from current tag to new context task-master add-tag testing --copy-from-current --description="QA testing tasks" ``` #### Cross-Tag Coordination When coordinating work across tags: 1. **Plan Integration Points**: Identify where different tag contexts need to interact 2. **Manual Coordination**: Note cross-tag dependencies in task details 3. **Tag Switching**: Use `task-master use-tag` to switch contexts as needed 4. **Documentation**: Use `task-master update-subtask` to document cross-tag decisions ## Key Files & Project Structure ### Core Files - `.taskmaster/tasks/tasks.json` - Tagged task data file (auto-managed) - `.taskmaster/state.json` - Current tag context and state information - `.taskmaster/config.json` - AI model configuration (use `task-master models` to modify) - `.taskmaster/docs/prd-.md` - Product Requirements Documents for each tag - `.taskmaster/tasks/*.md` - Individual task files (auto-generated, tagged by context) ### Tagged Task Structure ```json { "master": { "tasks": [ { "id": 1, "title": "Setup API", "status": "pending", ... } ] }, "user-auth": { "tasks": [ { "id": 1, "title": "OAuth Integration", "status": "pending", ... } ] }, "payments": { "tasks": [ { "id": 1, // Independent numbering per tag "title": "Setup Stripe Integration", "description": "Configure Stripe payment processing", "status": "pending", "priority": "high", "dependencies": [], "details": "Use Stripe API for payment processing...", "testStrategy": "Test payment flow with test cards" } ] } } ``` ### Claude Code Integration Files - `CLAUDE.md` - Auto-loaded context for Claude Code (this file) - `.claude/settings.json` - Claude Code tool allowlist and preferences - `.claude/commands/` - Custom slash commands for repeated workflows - `.mcp.json` - MCP server configuration (project-specific) ### Directory Structure ``` project/ ├── .taskmaster/ │ ├── tasks/ # Tagged task files directory │ │ ├── tasks.json # Tagged task database │ │ ├── task-1.md # Individual task files (tagged) │ │ └── task-2.md │ ├── docs/ # Documentation directory │ │ ├── prd-master.md # Main PRD │ │ ├── prd-user-authentication.md # Auth PRD │ │ ├── prd-payment-system.md # Payment PRD │ │ └── prd-mobile-app.md # Mobile PRD │ ├── reports/ # Analysis reports directory │ │ └── task-complexity-report.json │ ├── templates/ # Template files │ │ └── example_prd.md # Example PRD template │ ├── state.json # Current tag context and state │ └── config.json # AI models & settings ├── .claude/ │ ├── settings.json # Claude Code configuration │ └── commands/ # Custom slash commands ├── .mcp.json # MCP configuration └── CLAUDE.md # This file - auto-loaded by Claude Code ``` ### Essential MCP Tools ```javascript help; // = shows available taskmaster commands // Tag management list_tags; // = task-master tags add_tag; // = task-master add-tag use_tag; // = task-master use-tag copy_tag; // = task-master copy-tag delete_tag; // = task-master delete-tag // Tagged workflow initialize_project; // = task-master init (with tagged system) parse_prd; // = task-master parse-prd (in current tag) // Tag-aware operations (all work within current tag) get_tasks; // = task-master list next_task; // = task-master next get_task; // = task-master show set_task_status; // = task-master set-status // Task management add_task; // = task-master add-task expand_task; // = task-master expand update_task; // = task-master update-task update_subtask; // = task-master update-subtask update; // = task-master update // Analysis analyze_project_complexity; // = task-master analyze-complexity complexity_report; // = task-master complexity-report ``` ## Claude Code Workflow Integration ### Tagged Project Initialization ```bash # Initialize Task Master with tagged system task-master init # Set up multiple tag contexts task-master add-tag user-auth --description="Authentication features" task-master add-tag payments --description="Payment system" task-master add-tag mobile --description="Mobile app" # Parse PRDs into respective contexts task-master use-tag user-auth task-master parse-prd .taskmaster/docs/prd-user-authentication.md task-master use-tag payments task-master parse-prd .taskmaster/docs/prd-payment-system.md # Analyze and expand within each context task-master use-tag user-auth task-master analyze-complexity --research task-master expand --all --research ``` ### Multi-Context Development Loop ```bash # Morning: Check all contexts task-master tags --show-metadata # Overview of all tag contexts # Work on authentication task-master use-tag user-auth task-master next # Find next auth task task-master show # Review auth task details # Afternoon: Switch to payments task-master use-tag payments task-master next # Find next payment task task-master show # Review payment task details # Log progress in current context task-master update-subtask --id= --prompt="implementation progress..." ``` ### Multi-Claude Tagged Workflows For complex projects with multiple tag contexts: ```bash # Terminal 1: Authentication development cd project && claude # > task-master use-tag user-auth # Terminal 2: Payment system development cd project-payment-worktree && claude # > task-master use-tag payments # Terminal 3: Mobile app development cd project-mobile-worktree && claude # > task-master use-tag mobile ``` ## Tagged Task Structure & IDs ### Tag-Specific Task IDs - **Independent Numbering**: Each tag maintains its own task sequence starting from 1 - **Main tasks**: `1`, `2`, `3`, etc. (within each tag) - **Subtasks**: `1.1`, `1.2`, `2.1`, etc. (within each tag) - **Sub-subtasks**: `1.1.1`, `1.1.2`, etc. (within each tag) ### Tagged Task Context ```json { "user-auth": { "tasks": [ { "id": 1, "title": "Setup OAuth Provider", "description": "Configure GitHub OAuth integration", "status": "pending", "priority": "high", "dependencies": [], "details": "Use GitHub OAuth client ID/secret...", "testStrategy": "Test OAuth flow with GitHub account", "subtasks": [ { "id": 1, "title": "Register OAuth App", "status": "pending", "dependencies": [] } ] } ] }, "payments": { "tasks": [ { "id": 1, // Independent numbering per tag "title": "Setup Stripe Integration", "description": "Configure Stripe payment processing", "status": "pending", "priority": "high", "dependencies": [], "details": "Use Stripe API for payment processing...", "testStrategy": "Test payment flow with test cards" } ] } } ``` ## Claude Code Best Practices with Tagged System ### Tag Context Awareness - Always know your current tag context: `task-master tags` shows current context - Use `/clear` between different tag contexts to maintain focus - Use `task-master show ` to pull specific task context when needed - Remember: Task IDs are independent per tag (each tag has its own task 1, 2, 3...) ### Tagged Implementation Strategy 1. **Context Setup**: `task-master use-tag ` - Switch to appropriate context 2. **Task Discovery**: `task-master show ` - Understand requirements within tag 3. **Planning**: `task-master update-subtask --id= --prompt="detailed plan"` - Log plan in context 4. **Status Management**: `task-master set-status --id= --status=in-progress` - Start work in context 5. **Implementation**: Implement code following logged plan 6. **Progress Logging**: `task-master update-subtask --id= --prompt="progress notes"` - Log within context 7. **Completion**: `task-master set-status --id= --status=done` - Complete within context ### Cross-Tag Development Patterns #### Feature Integration Workflow ```bash # 1. Implement core feature in its tag task-master use-tag user-auth task-master show 2 # Review auth API task # ... implement auth APIs ... task-master set-status --id=2 --status=done # 2. Switch to consuming feature's tag task-master use-tag mobile task-master show 3 # Review mobile integration task task-master update-subtask --id=3.1 --prompt="Auth APIs completed in user-auth tag, ready for integration" # ... implement integration ... ``` #### Cross-Tag Documentation ```bash # Document cross-tag dependencies task-master use-tag mobile task-master update-subtask --id=3.2 --prompt="Depends on user-auth tag task 2 (OAuth setup) being completed" # Document integration decisions task-master update-subtask --id=3.3 --prompt="Using JWT tokens from auth service, implemented in user-auth tag" ``` ### Complex Tagged Workflows #### Multi-Feature Migration 1. **Create Migration PRD**: `touch .taskmaster/docs/prd-migration.md` 2. **Create Migration Tag**: `task-master add-tag migration --description="System migration tasks"` 3. **Parse Migration**: `task-master use-tag migration && task-master parse-prd .taskmaster/docs/prd-migration.md` 4. **Cross-Reference**: Document which existing tags are affected in migration tasks 5. **Coordinate**: Use `task-master update-subtask` to log progress across affected tags #### Tag Lifecycle Management ```bash # Development lifecycle task-master add-tag feature-x --description="New feature development" # Create task-master use-tag feature-x # Develop task-master copy-tag feature-x testing-x --description="Feature testing" # Test task-master delete-tag feature-x # Cleanup ``` ### Git Integration with Tagged System Tagged Task Master works excellently with git workflows: ```bash # Align tags with branches git checkout -b feature/user-authentication task-master add-tag --from-branch # Work within tag context task-master use-tag feature-user-authentication task-master next # Commit with tag context git commit -m "feat: implement OAuth setup (user-auth tag, task 1.2)" # Create PR with tag context gh pr create --title "Complete user-auth tag: OAuth integration" --body "Implements all user authentication tasks from user-auth tag context" ``` ### Parallel Development with Tagged Worktrees ```bash # Create worktrees for different tag contexts git worktree add ../project-auth feature/auth-system git worktree add ../project-payment feature/payment-system git worktree add ../project-mobile feature/mobile-app # Run Claude Code in each worktree with different tag contexts cd ../project-auth && claude # Terminal 1: user-auth tag cd ../project-payment && claude # Terminal 2: payments tag cd ../project-mobile && claude # Terminal 3: mobile tag ``` ## Troubleshooting Tagged System ### Tag Context Issues ```bash # Check current tag context task-master tags # Shows current tag (marked with *) # Switch if needed task-master use-tag # List tasks in current context task-master list ``` ### Cross-Tag Dependencies - **Note**: Task dependencies only work within the same tag context - **Workaround**: Document cross-tag dependencies in task details using `update-subtask` - **Coordination**: Use clear naming and documentation for cross-tag integration points ### Task File Sync Issues ```bash # Regenerate task files for current tag task-master generate # Fix dependencies within current tag task-master fix-dependencies ``` ## Important Tagged System Notes ### Tag Context Isolation - **Task IDs are independent per tag** - each tag has its own sequence starting from 1 - **Dependencies only work within tags** - cannot create dependencies across tags - **Status and progress are tag-specific** - marking task 1 done in tag A doesn't affect task 1 in tag B - **Current tag context affects all operations** - always verify you're in the correct tag ### AI-Powered Operations (within current tag) These commands work within the current tag context and may take up to a minute: - `parse_prd` / `task-master parse-prd` - Generates tasks in current tag - `analyze_project_complexity` / `task-master analyze-complexity` - Analyzes current tag's tasks - `expand_task` / `task-master expand` - Expands tasks in current tag - `add_task` / `task-master add-task` - Adds to current tag - `update` / `task-master update` - Updates tasks in current tag ### File Management with Tagged System - Never manually edit `tasks.json` - contains all tag contexts, use commands instead - Current tag context is stored in `.taskmaster/state.json` - Task markdown files are generated with tag context information - Use `task-master generate` after any manual changes ### Claude Code Session Management with Tags - Use `/clear` when switching between tag contexts to maintain focus - Start sessions by checking tag context: `task-master tags` - Use `task-master use-tag ` to switch contexts within session - Headless mode with tag context: `claude -p "task-master use-tag auth && task-master next"` The tagged system ensures your task management scales with project complexity while maintaining clear organization and preventing conflicts across different feature areas or development contexts.