# Task ID: 103
# Title: Implement Tagged Task Lists System for Multi-Context Task Management
# Status: pending
# Dependencies: 3, 11, 19
# Priority: medium
# Description: Develop a comprehensive tagged task lists system enabling users to organize, filter, and manage tasks across multiple contexts (e.g., personal, branch, version) with full backward compatibility.
# Details:
1. Extend the tasks.json schema to support a 'tags' structure, with 'master' as the default tag containing all existing tasks. Ensure seamless migration for users without tags.
2. Add a 'defaultTag' configuration option to config.json in the global section, defaulting to 'master'.
3. Implement tag management CLI commands: add-tag, delete, list, use (switch), rename, and copy. Each command should update the relevant data structures and persist changes.
4. Update all existing task commands (list, add-task, set-status, etc.) to accept a --tag flag, filtering or applying actions within the specified tag context.
5. Implement automatic tag creation from git branch names using a --from-branch flag, integrating with git APIs to detect current branch.
6. Maintain the current tag state in .taskmaster/state.json with currentTag set to 'master' by default, ensuring session persistence and correct context switching.
7. Guarantee backward compatibility: users without tags continue to operate in the 'master' context transparently.
8. Provide comprehensive documentation and migration notes for users, and update help menus to reflect new tag-related features.
# Test Strategy:
- Migrate an existing tasks.json and verify all tasks appear under the 'master' tag.
- Create, delete, rename, and copy tags using add-tag and other commands; confirm correct data structure updates and persistence.
- Switch between tags and verify task isolation and context switching.
- Use --tag flag with all supported commands and confirm correct filtering and operation.
- Test --from-branch flag by switching git branches and verifying tag creation and selection.
- Simulate usage without tags to ensure backward compatibility.
- Review documentation and help menus for accuracy and completeness.
- Run automated and manual tests for all new and modified commands, including edge cases (e.g., duplicate tag names, tag deletion with tasks).
# Subtasks:
## 1. Design Extended tasks.json Schema for Tag Support [done]
### Dependencies: None
### Description: Define and document the updated tasks.json schema to include a 'tags' structure, ensuring 'master' is the default tag containing all existing tasks.
### Details:
Create a schema that supports multiple tags, with backward compatibility for users without tags.
Implementation completed in Part 1: SCHEMA DESIGN: Defined data structure transformation from {"tasks": [...]} to {"master": {"tasks": [...]}}. Tags are direct top-level keys, not nested under a "tags" wrapper. Each tag contains a "tasks" array with the standard task structure. Tag resolution layer provides 100% backward compatibility by intercepting tagged format and returning old format transparently to existing code.
## 2. Implement Seamless Migration for Existing Users [done]
### Dependencies: 103.1
### Description: Develop a migration script or logic to move existing tasks into the 'master' tag for users upgrading from previous versions.
### Details:
Ensure no data loss and that users without tags continue to operate transparently.
## 3. Add 'defaultTag' Configuration Option to config.json Global Section [done]
### Dependencies: 103.1
### Description: Introduce a 'defaultTag' field in the global section of config.json, defaulting to 'master', and update configuration handling logic.
### Details:
Allow users to set and persist their preferred default tag in the global configuration section.
Added global.defaultTag configuration option to .taskmaster/config.json structure in assets/config.json. Implemented complete tags section including autoSwitchOnBranch and gitIntegration options. Created migrateConfigJson() function in utils.js to handle updating existing configuration files during the migration process. Configuration is automatically created and updated during the silent migration process to ensure seamless transition for existing users.
## 4. Develop Tag Management CLI Commands [done]
### Dependencies: 103.1, 103.3
### Description: Implement CLI commands for tag management: add-tag, delete, list, use (switch), rename, and copy, ensuring all changes are persisted.
### Details:
Each command should update the tasks.json and config files as needed. The primary command for creating tags should be 'add-tag' to maintain consistency with other task-master commands.
✅ **COMPLETED: CLI Command Integration for Tag Management**
Successfully implemented complete CLI command integration for all tag management functions with enhanced UX features:
**Commands Implemented:**
1. **`task-master tags [--show-metadata]`** - List all available tags
- Shows tag names, task counts, completion status
- Optional metadata display (creation date, description)
- Dynamic table width that adapts to terminal size
- Current tag indicator with visual highlighting
2. **`task-master add-tag [options]`** - Create new tags
- `--copy-from-current` - Copy tasks from current tag
- `--copy-from=` - Copy tasks from specified tag
- `-d, --description ` - Set tag description
- **Default behavior: Creates empty tags** (fixed from previous copying behavior)
3. **`task-master delete-tag [--yes]`** - Delete tags with enhanced safety
- **Changed from `--force` to `--yes`** for consistency
- **Double confirmation system** using inquirer:
- First: Yes/No confirmation prompt
- Second: Type tag name to confirm deletion
- Visual warning box showing impact
- Automatic current tag switching if deleting active tag
4. **`task-master use-tag `** - Switch tag contexts
- Updates current tag in state.json
- Validates tag existence before switching
- Clear success messaging
5. **`task-master rename-tag `** - Rename existing tags
- Validates both source and target names
- Updates current tag reference if renaming active tag
6. **`task-master copy-tag [options]`** - Copy tags
- `-d, --description ` - Set description for new tag
- Deep copy of all tasks and metadata
**Key Improvements Made:**
Enhanced User Experience:
- **Double confirmation for destructive operations** using inquirer prompts
- **Consistent option naming** (`--yes` instead of `--force`)
- **Dynamic table layouts** that use full terminal width
- **Visual warning boxes** for dangerous operations
- **Contextual help displays** on command errors
Technical Fixes:
- **Fixed critical `_rawTaggedData` corruption bug** in readJSON/writeJSON cycle
- **Dynamic task counting** instead of stored counters (eliminates sync issues)
- **Master tag metadata enhancement** with creation dates and descriptions
- **Proper error handling** with command-specific help displays
CLI Integration:
- **Added all commands to help menu** in ui.js under "Tag Management" section
- **Comprehensive help functions** for each command with examples
- **Error handlers with contextual help** for better user guidance
- **Consistent command patterns** following established CLI conventions
**Testing Completed:**
- ✅ Created empty tags (default behavior)
- ✅ Created tags with task copying (explicit flags)
- ✅ Listed tags with and without metadata
- ✅ Double confirmation for tag deletion
- ✅ Tag switching and current tag persistence
- ✅ Table width responsiveness
- ✅ Master tag metadata enhancement
- ✅ Error handling and help displays
**Files Modified:**
- `scripts/modules/commands.js` - Added all tag management commands
- `scripts/modules/task-manager/tag-management.js` - Enhanced functions with inquirer
- `scripts/modules/ui.js` - Added tag commands to help menu
- Fixed critical data corruption bug in utils.js
The CLI integration is now complete and production-ready with enhanced safety features and improved user experience!
## 5. Update Task Commands to Support --tag Flag [pending]
### Dependencies: 103.4
### Description: Modify all existing task-related CLI commands (list, add-task, set-status, etc.) to accept a --tag flag, applying actions within the specified tag context.
### Details:
Ensure commands filter or apply actions only to tasks within the selected tag.
Dependencies: [4, 13, 14] - Requires CLI commands foundation, MCP tools integration, and state management utilities to properly implement --tag flag support across both CLI and MCP interfaces.
## 6. Integrate Automatic Tag Creation from Git Branches [pending]
### Dependencies: 103.4
### Description: Implement logic to create tags based on git branch names using a --from-branch flag, integrating with git APIs to detect the current branch.
### Details:
Enable seamless context switching between code branches and task tags. Use add-tag internally when creating tags from branch names.
## 7. Update State Management for Current Tag Tracking [done]
### Dependencies: 103.4
### Description: Ensure .taskmaster/state.json properly tracks the current tag with currentTag field set to 'master' by default during initialization.
### Details:
Update initialization logic to create state.json with currentTag set to 'master', ensuring the state file accurately reflects the active tag across sessions.
STATE MANAGEMENT: Updated scripts/init.js to create state.json during initialization with proper initial state: currentTag: 'master', lastSwitched timestamp, branchTagMapping, migrationNoticeShown flag. createStateJson() function in utils.js handles state file creation during migration. State management integrated into complete migration system.
## 8. Ensure Full Backward Compatibility [pending]
### Dependencies: 103.2, 103.5, 103.7
### Description: Guarantee that users without tags continue to operate in the 'master' context without disruption or required changes.
### Details:
Test all workflows for legacy users and ensure no regressions.
## 9. Update Documentation and Help Menus [pending]
### Dependencies: 103.4, 103.5, 103.6, 103.8
### Description: Revise user documentation, migration notes, and CLI help menus to reflect new tag-related features and usage patterns, specifically documenting the add-tag command.
### Details:
Provide clear instructions and examples for all tag management features, ensuring add-tag command is properly documented with consistent naming.
## 10. Conduct Comprehensive System Testing and QA [pending]
### Dependencies: 103.8, 103.9
### Description: Perform end-to-end testing of the tagged task lists system, including migration, tag management, task operations, and context switching.
### Details:
Ensure all features work as intended and meet quality standards, with specific focus on add-tag command functionality.
## 11. Create Core Tag Management Functions [pending]
### Dependencies: 103.1, 103.3
### Description: Implement core tag management functions in scripts/modules/task-manager/ following the established pattern. Include functions for createTag, deleteTag, listTags, useTag, renameTag, copyTag, and tag resolution logic.
### Details:
## 12. Implement MCP Direct Functions for Tag Management [pending]
### Dependencies: 103.11
### Description: Create MCP direct function wrappers in mcp-server/src/core/direct-functions/ for all tag management operations, following the established pattern like add-task.js
### Details:
## 13. Create MCP Tools for Tag Management [pending]
### Dependencies: 103.12
### Description: Implement MCP tools in mcp-server/src/tools/ for all tag management operations (add-tag, delete-tag, list-tags, use-tag, rename-tag, copy-tag), following the established pattern like add-task.js
### Details:
## 14. Create State Management Utilities [done]
### Dependencies: 103.3, 103.7
### Description: Implement utilities for reading/writing current tag state, tag resolution logic (currentTag from state -> --tag flag -> defaultTag fallback), and state file validation
### Details:
## 15. Implement Tasks.json Migration Logic [done]
### Dependencies: 103.1, 103.2
### Description: Create specific migration logic to transform existing tasks.json format (array of tasks) to the new tagged format ({tags: {master: {tasks: [...]}}}). Include validation and rollback capabilities.
### Details:
MIGRATION LOGIC: Implemented in scripts/modules/utils.js with performCompleteTagMigration(), migrateConfigJson(), createStateJson(), and markMigrationForNotice() functions. Silent migration triggers on readJSON() for tasks.json files. Migration notice system implemented in commands.js with displayTaggedTasksFYI() from ui.js. Complete 3-part migration: tasks.json + config.json + state.json all handled automatically.
## 16. Update Documentation for Tagged Task Lists System [done]
### Dependencies: 103.8, 103.9
### Description: Update all documentation in /docs to reflect the new tagged task lists architecture and migration system
### Details:
Update docs to be aware of the new tagged structure: - Update command-reference.md with new tag-related commands - Update task-structure.md to explain tagged format - Update configuration.md with tagged system config - Update tutorial.md with tagged workflow - Update migration-guide.md for tagged migration - Ensure all examples reflect new structure
COMPLETED: All documentation files have been successfully updated to reflect the tagged task lists system. Key updates include:
- docs/task-structure.md: Added complete tagged format explanation, data structure overview, migration details, and best practices
- docs/configuration.md: Updated with tagged system configuration, state management, and new settings
- docs/migration-guide.md: Added comprehensive tagged system migration process, verification steps, and team coordination guidelines
- .cursor/rules/*.mdc files: Updated architecture.mdc, dev_workflow.mdc, taskmaster.mdc, tasks.mdc, utilities.mdc, new_features.mdc, git_workflow.mdc, and glossary.mdc to be aware of tagged system
All documentation now properly reflects Part 1 implementation and prepares for Part 2 features. Documentation is fully aligned with the new tagged task structure.
## 17. Implement Task Template Importing from External .json Files [pending]
### Dependencies: None
### Description: Implement a mechanism to import tasks from external .json files, treating them as task templates. This allows users to add new .json files to the .taskmaster/tasks folder. The system should read these files, extract tasks under a specific tag, and merge them into the main tasks.json. The 'master' tag from template files must be ignored to prevent conflicts, and the primary tasks.json file will always take precedence over imported tags.
### Details:
Key implementation steps: 1. Develop a file watcher or a manual import command to detect and process new .json files in the tasks directory. 2. Implement logic to read an external json file, identify the tag key, and extract the array of tasks. 3. Handle potential conflicts: if an imported tag already exists in the main tasks.json, the existing tasks should be preserved and new ones appended, or the import should be skipped based on a defined precedence rule. 4. Ignore any 'master' key in template files to protect the integrity of the main task list. 5. Update task ID sequencing to ensure imported tasks are assigned unique IDs that don't conflict with existing tasks.