claude-task-master/.changeset/six-cups-see.md

---
"task-master-ai": minor
---

Introduces Tagged Lists: AI Multi-Context Task Management System

This major feature release introduces Tagged Lists, a comprehensive system that transforms Taskmaster into a multi-context task management powerhouse. You can now organize tasks into completely isolated contexts, enabling parallel (agentic) development workflows, team collaboration, and project experimentation without conflicts.

**🏷️ Tagged Task Lists Architecture:**

The new tagged system fundamentally improves how tasks are organized:
- **Legacy Format**: `{ "tasks": [...] }` 
- **New Tagged Format**: `{ "master": { "tasks": [...], "metadata": {...} }, "feature-xyz": { "tasks": [...], "metadata": {...} } }`
- **Automatic Migration**: Existing projects will seamlessly migrate to tagged format with zero user intervention
- **State Management**: New `.taskmaster/state.json` tracks current tag, last switched time, migration status and more.
- **Configuration Integration**: Enhanced `.taskmaster/config.json` with tag-specific settings and defaults.

By default, your existing task list will be migrated to the `master` tag.

**🚀 Complete Tag Management Suite:**

**Core Tag Commands:**
- `task-master tags [--show-metadata]` - List all tags with task counts, completion stats, and metadata
- `task-master add-tag <name> [options]` - Create new tag contexts with optional task copying
- `task-master delete-tag <name> [--yes]` - Delete tags (and attached tasks) with double confirmation protection
- `task-master use-tag <name>` - Switch contexts and immediately see next available task
- `task-master rename-tag <old> <new>` - Rename tags with automatic current tag reference updates
- `task-master copy-tag <source> <target> [options]` - Duplicate tag contexts for experimentation

**🤖 Full MCP Integration for Tag Management:**

Task Master's multi-context capabilities are now fully exposed through the MCP server, enabling powerful agentic workflows:
- **`list_tags`**: List all available tag contexts.
- **`add_tag`**: Programmatically create new tags.
- **`delete_tag`**: Remove tag contexts.
- **`use_tag`**: Switch the agent's active task context.
- **`rename_tag`**: Rename existing tags.
- **`copy_tag`**: Duplicate entire task contexts for experimentation.

**Tag Creation Options:**
- `--copy-from-current` - Copy tasks from currently active tag
- `--copy-from=<tag>` - Copy tasks from specific tag
- `--from-branch` - Creates a new tag using the active git branch name (for `add-tag` only)
- `--description="<text>"` - Add custom tag descriptions
- Empty tag creation for fresh contexts

**🎯 Universal --tag Flag Support:**

Every task operation now supports tag-specific execution:
- `task-master list --tag=feature-branch` - View tasks in specific context
- `task-master add-task --tag=experiment --prompt="..."` - Create tasks in specific tag
- `task-master parse-prd document.txt --tag=v2-redesign` - Parse PRDs into dedicated contexts
- `task-master analyze-complexity --tag=performance-work` - Generate tag-specific reports
- `task-master set-status --tag=hotfix --id=5 --status=done` - Update tasks in specific contexts
- `task-master expand --tag=research --id=3` - Break down tasks within tag contexts

This way you or your agent can store out of context tasks into the appropriate tags for later, allowing you to maintain a groomed and scoped master list. Focus on value, not chores.

**📊 Enhanced Workflow Features:**

**Smart Context Switching:**
- `use-tag` command shows immediate next task after switching
- Automatic tag creation when targeting non-existent tags
- Current tag persistence across terminal sessions
- Branch-tag mapping for future Git integration

**Intelligent File Management:**
- Tag-specific complexity reports: `task-complexity-report_tagname.json`
- Master tag uses default filenames: `task-complexity-report.json`
- Automatic file isolation prevents cross-tag contamination

**Advanced Confirmation Logic:**
- Commands only prompt when target tag has existing tasks
- Empty tags allow immediate operations without confirmation
- Smart append vs overwrite detection

**🔄 Seamless Migration & Compatibility:**

**Zero-Disruption Migration:**
- Existing `tasks.json` files automatically migrate on first command
- Master tag receives proper metadata (creation date, description)
- Migration notice shown once with helpful explanation
- All existing commands work identically to before

**State Management:**
- `.taskmaster/state.json` tracks current tag and migration status
- Automatic state creation and maintenance
- Branch-tag mapping foundation for Git integration
- Migration notice tracking to avoid repeated notifications
- Grounds for future context additions

**Backward Compatibility:**
- All existing workflows continue unchanged
- Legacy commands work exactly as before
- Gradual adoption - users can ignore tags entirely if desired
- No breaking changes to existing tasks or file formats

**💡 Real-World Use Cases:**

**Team Collaboration:**
- `task-master add-tag alice --copy-from-current` - Create teammate-specific contexts
- `task-master add-tag bob --copy-from=master` - Onboard new team members
- `task-master use-tag alice` - Switch to teammate's work context

**Feature Development:**
- `task-master parse-prd feature-spec.txt --tag=user-auth` - Dedicated feature planning
- `task-master add-tag experiment --copy-from=user-auth` - Safe experimentation
- `task-master analyze-complexity --tag=user-auth` - Feature-specific analysis

**Release Management:**
- `task-master add-tag v2.0 --description="Next major release"` - Version-specific planning
- `task-master copy-tag master v2.1` - Release branch preparation
- `task-master use-tag hotfix` - Emergency fix context

**Project Phases:**
- `task-master add-tag research --description="Discovery phase"` - Research tasks
- `task-master add-tag implementation --copy-from=research` - Development phase
- `task-master add-tag testing --copy-from=implementation` - QA phase

**🛠️ Technical Implementation:**

**Data Structure:**
- Tagged format with complete isolation between contexts
- Rich metadata per tag (creation date, description, update tracking)
- Automatic metadata enhancement for existing tags
- Clean separation of tag data and internal state

**Performance Optimizations:**
- Dynamic task counting without stored counters
- Efficient tag resolution and caching
- Minimal file I/O with smart data loading
- Responsive table layouts adapting to terminal width

**Error Handling:**
- Comprehensive validation for tag names (alphanumeric, hyphens, underscores)
- Reserved name protection (master, main, default)
- Graceful handling of missing tags and corrupted data
- Detailed error messages with suggested corrections

This release establishes the foundation for advanced multi-context workflows while maintaining the simplicity and power that makes Task Master effective for individual developers.