bb775e3180
- Updated task-structure.md with comprehensive tagged format explanation - Updated all .cursor/rules/*.mdc files to reflect tagged system - Completed subtask 103.16: Update Documentation for Tagged Task Lists System
148 lines
11 KiB
Plaintext
148 lines
11 KiB
Plaintext
# 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.
|
|
<info added on 2025-06-11T20:46:18.649Z>
|
|
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.
|
|
</info added on 2025-06-11T20:46:18.649Z>
|
|
|
|
## 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.
|
|
<info added on 2025-06-11T20:46:57.669Z>
|
|
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.
|
|
</info added on 2025-06-11T20:46:57.669Z>
|
|
|
|
## 4. Develop Tag Management CLI Commands [pending]
|
|
### 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.
|
|
|
|
## 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.
|
|
<info added on 2025-06-11T18:23:45.185Z>
|
|
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.
|
|
</info added on 2025-06-11T18:23:45.185Z>
|
|
|
|
## 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.
|
|
<info added on 2025-06-11T20:49:28.104Z>
|
|
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.
|
|
</info added on 2025-06-11T20:49:28.104Z>
|
|
|
|
## 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 [pending]
|
|
### 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:
|
|
<info added on 2025-06-11T20:50:25.721Z>
|
|
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.
|
|
</info added on 2025-06-11T20:50:25.721Z>
|
|
|
|
## 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
|
|
<info added on 2025-06-11T21:12:52.662Z>
|
|
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.
|
|
</info added on 2025-06-11T21:12:52.662Z>
|
|
|