chore: v0.17 features and improvements (#771)
* chore: task management and small bug fix. * chore: task management * feat: implement research command with enhanced context gathering - Add comprehensive research command with AI-powered queries - Implement ContextGatherer utility for reusable context extraction - Support multiple context types: tasks, files, custom text, project tree - Add fuzzy search integration for automatic task discovery - Implement detailed token breakdown display with syntax highlighting - Add enhanced UI with boxed output and code block formatting - Support different detail levels (low, medium, high) for responses - Include project-specific context for more relevant AI responses - Add token counting with gpt-tokens library integration - Create reusable patterns for future context-aware commands - Task 94.4 completed * docs: add context gathering rule and update existing rules - Create comprehensive context_gathering.mdc rule documenting ContextGatherer utility patterns, FuzzyTaskSearch integration, token breakdown display, code block syntax highlighting, and enhanced result display patterns - Update new_features.mdc to include context gathering step - Update commands.mdc with context-aware command pattern - Update ui.mdc with enhanced display patterns and syntax highlighting - Update utilities.mdc to document new context gathering utilities - Update glossary.mdc to include new context_gathering rule - Establishes standardized patterns for building intelligent, context-aware commands that can leverage project knowledge for better AI assistance * feat(fuzzy): improves fuzzy search to introspect into subtasks as well. might still need improvement. * fix(move): adjusts logic to prevent an issue when moving from parent to subtask if the target parent has no subtasks. * fix(move-task): Fix critical bugs in task move functionality - Fixed parent-to-parent task moves where original task would remain as duplicate - Fixed moving tasks to become subtasks of empty parents (validation errors) - Fixed moving subtasks between different parent tasks - Improved comma-separated batch moves with proper error handling - Updated MCP tool to use core logic instead of custom implementation - Resolves task duplication issues and enables proper task hierarchy reorganization * feat(research): Add subtasks to fuzzy search and follow-up questions - Enhanced fuzzy search to include subtasks in discovery - Added interactive follow-up question functionality using inquirer - Improved context discovery by including both tasks and subtasks - Follow-up option for research with default to 'n' for quick workflow * chore: removes task004 chat that had like 11k lines lol. * chore: formatting * feat(show): add comma-separated ID support for multi-task viewing - Enhanced get-task/show command to support comma-separated task IDs for efficient batch operations. - New features include multiple task retrieval, smart display logic, interactive action menu with batch operations, MCP array response for AI agent efficiency, and support for mixed parent tasks and subtasks. - Implementation includes updated CLI show command, enhanced MCP get_task tool, modified showTaskDirect function, and maintained full backward compatibility. - Documentation updated across all relevant files. Benefits include faster context gathering for AI agents, improved workflow with interactive batch operations, better UX with responsive layout, and enhanced API efficiency. * feat(research): Adds MCP tool for command - New MCP Tool: research tool enables AI-powered research with project context - Context Integration: Supports task IDs, file paths, custom context, and project tree - Fuzzy Task Discovery: Automatically finds relevant tasks using semantic search - Token Management: Detailed token counting and breakdown by context type - Multiple Detail Levels: Support for low, medium, and high detail research responses - Telemetry Integration: Full cost tracking and usage analytics - Direct Function: researchDirect with comprehensive parameter validation - Silent Mode: Prevents console output interference with MCP JSON responses - Error Handling: Robust error handling with proper MCP response formatting This completes subtasks 94.5 (Direct Function) and 94.6 (MCP Tool) for the research command implementation, providing a powerful research interface for integrated development environments like Cursor. Updated documentation across taskmaster.mdc, README.md, command-reference.md, examples.md, tutorial.md, and docs/README.md to highlight research capabilities and usage patterns. * chore: task management * chore: task management and removes mistakenly staged changes * fix(move): Fix move command bug that left duplicate tasks - Fixed logic in moveTaskToNewId function that was incorrectly treating task-to-task moves as subtask creation instead of task replacement - Updated moveTaskToNewId to properly handle replacing existing destination tasks instead of just placeholders - The move command now correctly replaces destination tasks and cleans up properly without leaving duplicates - Task Management: Moved task 93 (Google Vertex AI Provider) to position 88, Moved task 94 (Azure OpenAI Provider) to position 89, Updated task dependencies and regenerated task files, Cleaned up orphaned task files automatically - All important validations remain in place: Prevents moving tasks to themselves, Prevents moving parent tasks to their own subtasks, Prevents circular dependencies - Resolves the issue where moving tasks would leave both source and destination tasks in tasks.json and file system * chore: formatting * feat: Add .taskmaster directory (#619) * chore: apply requested changes from next branch (#629) * chore: rc version bump * chore: cleanup migration-guide * fix: bedrock set model and other fixes (#641) * Fix: MCP log errors (#648) * fix: projectRoot duplicate .taskmaster directory (#655) * Version Packages * chore: add package-lock.json * Version Packages * Version Packages * fix: markdown format (#622) * Version Packages * Version Packages * Fixed the Typo in cursor rules Issue:#675 (#677) Fixed the typo in the Api keys * Add one-click MCP server installation for Cursor (#671) * Update README.md - Remove trailing commas (#673) JSON doesn't allow for trailing commas, so these need to be removed in order for this to work * chore: rc version bump * fix: findTasksPath function * fix: update MCP tool * feat(ui): replace emoji complexity indicators with clean filled circle characters Replace 🟢, 🟡, 🔴 emojis with ● character in getComplexityWithColor function Update corresponding unit tests to expect ● instead of emojis Improves UI continuity * fix(ai-providers): change generateObject mode from 'tool' to 'auto' for better provider compatibility Fixes Perplexity research role failing with 'tool-mode object generation' error The hardcoded 'tool' mode was incompatible with providers like Perplexity that support structured JSON output but not function calling/tool use Using 'auto' mode allows the AI SDK to choose the best approach for each provider * Adds qwen3-235n-a22b:free to supported models. Closes #687) * chore: adds a warning when custom openrouter model is a free model which suffers from lower rate limits, restricted context, and, worst of all, no access to tool_use. * refactor: enhance add-task fuzzy search and fix duplicate banner display - **Remove hardcoded category system** in add-task that always matched 'Task management' - **Eliminate arbitrary limits** in fuzzy search results (5→25 high relevance, 3→10 medium relevance, 8→20 detailed tasks) - **Improve semantic weighting** in Fuse.js search (details=3, description=2, title=1.5) for better relevance - **Fix duplicate banner issue** by removing console.clear() and redundant displayBanner() calls from UI functions - **Enhance context generation** to rely on semantic similarity rather than rigid pattern matching - **Preserve terminal history** to address GitHub issue #553 about eating terminal lines - **Remove displayBanner() calls** from: displayHelp, displayNextTask, displayTaskById, displayComplexityReport, set-task-status, clear-subtasks, dependency-manager functions The add-task system now provides truly relevant task context based on semantic similarity rather than arbitrary categories and limits, while maintaining a cleaner terminal experience. Changes span: add-task.js, ui.js, set-task-status.js, clear-subtasks.js, list-tasks.js, dependency-manager.js Closes #553 * chore: changeset * chore: passes tests and linting * chore: more linting * ninja(sync): add sync-readme command for GitHub README export with UTM tracking and professional markdown formatting. Experimental * chore: changeset adjustment * docs: Auto-update and format models.md * chore: updates readme with npm download badges and mentions AI Jason who is joining the taskmaster core team. * chore: fixes urls in readme npm packages * chore: fixes urls in readme npm packages again * fix: readme typo * readme: fix twitter urls. * readme: removes the taskmaster list output which is too overwhelming given its size with subtasks. may re-add later. fixes likely issues in the json for manual config in cursor and windsurf in the readme. * chore: small readme nitpicks * chore: adjusts changeset from minor to patch to avoid version bump to 0.17 * readme: moves up the documentation links higher up in the readme. same with the cursor one-click install. * Fix Cursor deeplink installation with copy-paste instructions (#723) * solve merge conflics with next. not gonna deal with these much longer. * chore: update task files during rebase * chore: task management * feat: implement research command with enhanced context gathering - Add comprehensive research command with AI-powered queries - Implement ContextGatherer utility for reusable context extraction - Support multiple context types: tasks, files, custom text, project tree - Add fuzzy search integration for automatic task discovery - Implement detailed token breakdown display with syntax highlighting - Add enhanced UI with boxed output and code block formatting - Support different detail levels (low, medium, high) for responses - Include project-specific context for more relevant AI responses - Add token counting with gpt-tokens library integration - Create reusable patterns for future context-aware commands - Task 94.4 completed * fix(move): adjusts logic to prevent an issue when moving from parent to subtask if the target parent has no subtasks. * fix(move-task): Fix critical bugs in task move functionality - Fixed parent-to-parent task moves where original task would remain as duplicate - Fixed moving tasks to become subtasks of empty parents (validation errors) - Fixed moving subtasks between different parent tasks - Improved comma-separated batch moves with proper error handling - Updated MCP tool to use core logic instead of custom implementation - Resolves task duplication issues and enables proper task hierarchy reorganization * chore: removes task004 chat that had like 11k lines lol. * feat(show): add comma-separated ID support for multi-task viewing - Enhanced get-task/show command to support comma-separated task IDs for efficient batch operations. - New features include multiple task retrieval, smart display logic, interactive action menu with batch operations, MCP array response for AI agent efficiency, and support for mixed parent tasks and subtasks. - Implementation includes updated CLI show command, enhanced MCP get_task tool, modified showTaskDirect function, and maintained full backward compatibility. - Documentation updated across all relevant files. Benefits include faster context gathering for AI agents, improved workflow with interactive batch operations, better UX with responsive layout, and enhanced API efficiency. * feat(research): Adds MCP tool for command - New MCP Tool: research tool enables AI-powered research with project context - Context Integration: Supports task IDs, file paths, custom context, and project tree - Fuzzy Task Discovery: Automatically finds relevant tasks using semantic search - Token Management: Detailed token counting and breakdown by context type - Multiple Detail Levels: Support for low, medium, and high detail research responses - Telemetry Integration: Full cost tracking and usage analytics - Direct Function: researchDirect with comprehensive parameter validation - Silent Mode: Prevents console output interference with MCP JSON responses - Error Handling: Robust error handling with proper MCP response formatting This completes subtasks 94.5 (Direct Function) and 94.6 (MCP Tool) for the research command implementation, providing a powerful research interface for integrated development environments like Cursor. Updated documentation across taskmaster.mdc, README.md, command-reference.md, examples.md, tutorial.md, and docs/README.md to highlight research capabilities and usage patterns. * chore: task management * fix(move): Fix move command bug that left duplicate tasks - Fixed logic in moveTaskToNewId function that was incorrectly treating task-to-task moves as subtask creation instead of task replacement - Updated moveTaskToNewId to properly handle replacing existing destination tasks instead of just placeholders - The move command now correctly replaces destination tasks and cleans up properly without leaving duplicates - Task Management: Moved task 93 (Google Vertex AI Provider) to position 88, Moved task 94 (Azure OpenAI Provider) to position 89, Updated task dependencies and regenerated task files, Cleaned up orphaned task files automatically - All important validations remain in place: Prevents moving tasks to themselves, Prevents moving parent tasks to their own subtasks, Prevents circular dependencies - Resolves the issue where moving tasks would leave both source and destination tasks in tasks.json and file system * chore: moves to new task master config setup * feat: add comma-separated status filtering to list-tasks - supports multiple statuses like 'blocked,deferred' with comprehensive test coverage and backward compatibility - also adjusts biome.json to stop bitching about templating. * chore: linting ffs * fix(generate): Fix generate command creating tasks in legacy location - Update generate command default output directory from 'tasks' to '.taskmaster/tasks' - Fix path.dirname() usage to properly derive output directory from tasks file location - Update MCP tool description and documentation to reflect new structure - Disable Biome linting rules for noUnusedTemplateLiteral and useArrowFunction - Fixes issue where generate command was creating task files in the old 'tasks/' directory instead of the new '.taskmaster/tasks/' structure after the refactor * chore: task management * chore: task management some more * fix(get-task): makes the projectRoot argument required to prevent errors when getting tasks. * feat(tags): Implement tagged task lists migration system (Part 1/2) This commit introduces the foundational infrastructure for tagged task lists, enabling multi-context task management without remote storage to prevent merge conflicts. CORE ARCHITECTURE: • Silent migration system transforms tasks.json from old format { "tasks": [...] } to new tagged format { "master": { "tasks": [...] } } • Tag resolution layer provides complete backward compatibility - existing code continues to work • Automatic configuration and state management for seamless user experience SILENT MIGRATION SYSTEM: • Automatic detection and migration of legacy tasks.json format • Complete project migration: tasks.json + config.json + state.json • Transparent tag resolution returns old format to maintain compatibility • Zero breaking changes - all existing functionality preserved CONFIGURATION MANAGEMENT: • Added global.defaultTag setting (defaults to 'master') • New tags section with gitIntegration placeholders for future features • Automatic config.json migration during first run • Proper state.json creation with migration tracking USER EXPERIENCE: • Clean, one-time FYI notice after migration (no emojis, professional styling) • Notice appears after 'Suggested Next Steps' and is tracked in state.json • Silent operation - users unaware migration occurred unless explicitly shown TECHNICAL IMPLEMENTATION: • Enhanced readJSON() with automatic migration detection and processing • New utility functions: getCurrentTag(), resolveTag(), getTasksForTag(), setTasksForTag() • Complete migration orchestration via performCompleteTagMigration() • Robust error handling and fallback mechanisms BACKWARD COMPATIBILITY: • 100% backward compatibility maintained • Existing CLI commands and MCP tools continue to work unchanged • Legacy tasks.json format automatically upgraded on first read • All existing workflows preserved TESTING VERIFIED: • Complete migration from legacy state works correctly • Config.json properly updated with tagged system settings • State.json created with correct initial values • Migration notice system functions as designed • All existing functionality continues to work normally Part 2 will implement tag management commands (add-tag, use-tag, list-tags) and MCP tool updates for full tagged task system functionality. Related: Task 103 - Implement Tagged Task Lists System for Multi-Context Task Management * docs: Update documentation and rules for tagged task lists system - 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 * feat(mcp): Add tagInfo to responses and integrate ContextGatherer Enhances the MCP server to include 'tagInfo' (currentTag, availableTags) in all tool responses, providing better client-side context. - Introduces a new 'ContextGatherer' utility to standardize the collection of file, task, and project context for AI-powered commands. This refactors several task-manager modules ('expand-task', 'research', 'update-task', etc.) to use the new utility. - Fixes an issue in 'get-task' and 'get-tasks' MCP tools where the 'projectRoot' was not being passed correctly, preventing tag information from being included in their responses. - Adds subtask '103.17' to track the implementation of the task template importing feature. - Updates documentation ('.cursor/rules', 'docs/') to align with the new tagged task system and context gatherer logic. * fix: include tagInfo in AI service responses for MCP tools - Update all core functions that call AI services to extract and return tagInfo - Update all direct functions to include tagInfo in MCP response data - Fixes issue where add_task, expand_task, and other AI commands were not including current tag and available tags information - tagInfo includes currentTag from state.json and availableTags list - Ensures tagged task lists system information is properly propagated through the full chain: AI service -> core function -> direct function -> MCP client * fix(move-task): Update move functionality for tagged task system compatibility - incorporate GitHub commit fixes and resolve readJSON data handling * feat(tagged-tasks): Complete core tag management system implementation - Implements comprehensive tagged task lists system for multi-context task management including core tag management functions (Task 103.11), MCP integration updates, and foundational infrastructure for tagged task operations. Features tag CRUD operations, validation, metadata tracking, deep task copying, and full backward compatibility. * fix(core): Fixed move-task.js writing _rawTaggedData directly, updated writeJSON to filter tag fields, fixed CLI move command missing projectRoot, added ensureTagMetadata utility * fix(tasks): ensure list tasks triggers silent migration if necessary. * feat(tags): Complete show and add-task command tag support - show command: Added --tag flag, fixed projectRoot passing to UI functions - add-task command: Already had proper tag support and projectRoot handling - Both commands now work correctly with tagged task lists system - Migration logic works properly when viewing and adding tasks - Updated subtask 103.5 with progress on high-priority command fixes * fix(tags): Clean up rogue created properties and fix taskCount calculation - Enhanced writeJSON to automatically filter rogue created/description properties from tag objects - Fixed tags command error by making taskCount calculation dynamic instead of hardcoded - Cleaned up existing rogue created property in master tag through forced write operation - All created properties now properly located in metadata objects only - Tags command working perfectly with proper task count display - Data integrity maintained with automatic cleanup during write operations * fix(tags): Resolve critical tag deletion and migration notice bugs Major Issues Fixed: 1. Tag Deletion Bug: Fixed critical issue where creating subtasks would delete other tags - Root cause: writeJSON function wasn't accepting projectRoot/tag parameters - Fixed writeJSON signature and logic to handle tagged data structure - Added proper merging of resolved tag data back into full tagged structure 2. Persistent Migration Notice: Fixed FYI notice showing after every command - Root cause: markMigrationForNotice was resetting migrationNoticeShown to false - Fixed migration logic to only trigger on actual legacy->tagged migrations - Added proper _rawTaggedData checks to prevent false migration detection 3. Data Corruption Prevention: Enhanced data integrity safeguards - Fixed writeJSON to filter out internal properties - Added automatic cleanup of rogue properties - Improved hasTaggedStructure detection logic Commands Fixed: add-subtask, remove-subtask, and all commands now preserve tags correctly * fix(tags): Resolve tag deletion bug in remove-task command Refactored the core 'removeTask' function to be fully tag-aware, preventing data corruption. - The function now correctly reads the full tagged data structure by prioritizing '_rawTaggedData' instead of operating on a resolved single-tag view. - All subsequent operations (task removal, dependency cleanup, file writing) now correctly reference the full multi-tag data object, preserving the integrity of 'tasks.json'. - This resolves the critical bug where removing a task would delete all other tags. * fix(tasks): Ensure new task IDs are sequential within the target tag Modified the ID generation logic in 'add-task.js' to calculate the next task ID based on the highest ID within the specified tag, rather than globally across all tags. This fixes a critical bug where creating a task in a new tag would result in a high, non-sequential ID, such as ID 105 for the first task in a tag. * fix(commands): Add missing context parameters to dependency and remove-subtask commands - Add projectRoot and tag context to all dependency commands - Add projectRoot and tag context to remove-subtask command - Add --tag option to remove-subtask command - Fixes critical bug where remove-subtask was deleting other tags due to missing context - All dependency and subtask commands now properly handle tagged task lists * feat(tags): Add --tag flag support to core commands for multi-context task management - parse-prd now supports creating tasks in specific contexts - Fixed tag preservation logic to prevent data loss - analyze-complexity generates tag-specific reports - Non-existent tags created automatically - Enables rapid prototyping and parallel development workflows * feat(tags): Complete tagged task lists system with enhanced use-tag command - Multi-context task management with full CLI support - Enhanced use-tag command shows next available task after switching - Universal --tag flag support across all commands - Seamless migration with zero disruption - Complete tag management suite (add, delete, rename, copy, list) - Smart confirmation logic and data integrity protection - State management and configuration integration - Real-world use cases for teams, features, and releases * feat(tags): Complete tag support for remaining CLI commands - Add --tag flag to update, move, and set-status commands - Ensure all task operation commands now support tag context - Fix missing tag context passing to core functions - Complete comprehensive tag-aware command coverage * feat(ui): add tag indicator to all CLI commands - shows 🏷️ tag: tagname for complete context visibility across 15+ commands * fix(ui): resolve dependency 'Not found' issue when filtering - now correctly displays dependencies that exist but are filtered out of view * feat(research): Add comprehensive AI-powered research command with interactive follow-ups, save functionality, intelligent context gathering, fuzzy task discovery, multi-source context support, enhanced display with syntax highlighting, clean inquirer menus, comprehensive help, and MCP integration with saveTo parameter * feat(tags): Implement full MCP support for Tagged Task Lists and update-task append mode * chore: task management * feat(research): Enhance research command with follow-up menu, save functionality, and fix ContextGatherer token counting * feat(git-workflow): Add automatic git branch-tag integration - Implement automatic tag creation when switching to new git branches - Add branch-tag mapping system for seamless context switching - Enable auto-switch of task contexts based on current git branch - Provide isolated task contexts per branch to prevent merge conflicts - Add configuration support for enabling/disabling git workflow features - Fix ES module compatibility issues in git-utils module - Maintain zero migration impact with automatic 'master' tag creation - Support parallel development with branch-specific task contexts The git workflow system automatically detects branch changes and creates corresponding empty task tags, enabling developers to maintain separate task contexts for different features/branches while preventing task-related merge conflicts during collaborative development. Resolves git workflow integration requirements for multi-context development. * feat(git-workflow): Simplify git integration with --from-branch option - Remove automatic git workflow and branch-tag switching - we are not ready for it yet - Add --from-branch option to add-tag command for manual tag creation from git branch - Remove git workflow configuration from config.json and assets - Disable automatic tag switching functions in git-utils.js - Add createTagFromBranch function for branch-based tag creation - Support both CLI and MCP interfaces for --from-branch functionality - Fix ES module imports in git-utils.js and utils.js - Maintain user control over tag contexts without forced automation The simplified approach allows users to create tags from their current git branch when desired, without the complexity and rigidity of automatic branch-tag synchronization. Users maintain full control over their tag contexts while having convenient tools for git-based workflows when needed. * docs: Update rule files to reflect simplified git integration approach - Remove automatic git workflow features, update to manual --from-branch option, change Part 2 references to completed status * fix(commands): Fix add-tag --from-branch requiring tagName argument - Made tagName optional when using --from-branch - Added validation for either tagName or --from-branch - Fixes 'missing required argument' error with --from-branch option * fix(mcp): Prevent tag deletion on subtask update Adds a safety net to the writeJSON utility to prevent data loss when updating subtasks via the MCP server. The MCP process was inadvertently causing the _rawTaggedData property, which holds the complete multi-tag structure, to be lost. When writeJSON received the data for only a single tag, it would overwrite the entire tasks.json file, deleting all other tags. This fix makes writeJSON more robust. If it receives data that looks like a single, resolved tag without the complete structure, it re-reads the full tasks.json file from disk. It then carefully merges the updated data back into the correct tag within the full structure, preserving all other tags. * fix: resolve all remaining test failures and improve test reliability - Fix clear-subtasks test by implementing deep copy of mock data to prevent mutation issues between tests - Fix add-task test by uncommenting and properly configuring generateTaskFiles call with correct parameters - Fix analyze-task-complexity tests by properly mocking fs.writeFileSync with shared mock function - Update test expectations to match actual function signatures and data structures - Improve mock setup consistency across all test suites - Ensure all tests now pass (329 total: 318 passed, 11 skipped, 0 failed) * chore: task management --------- Co-authored-by: Eyal Toledano <eyal@microangel.so> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Ibrahim H. <bitsnaps@yahoo.fr> Co-authored-by: Saksham Goel <sakshamgoel1107@gmail.com> Co-authored-by: Joe Danziger <joe@ticc.net> Co-authored-by: Aaron Gabriel Neyer <ag@unforced.org>
This commit is contained in:
Ralph Khreish
@@ -9,7 +9,7 @@ Welcome to the Task Master documentation. Use the links below to navigate to the
|
||||
|
||||
## Reference
|
||||
|
||||
- [Command Reference](command-reference.md) - Complete list of all available commands
|
||||
- [Command Reference](command-reference.md) - Complete list of all available commands (including research and multi-task viewing)
|
||||
- [Task Structure](task-structure.md) - Understanding the task format and features
|
||||
|
||||
## Examples & Licensing
|
||||
|
||||
@@ -43,10 +43,28 @@ task-master show <id>
|
||||
# or
|
||||
task-master show --id=<id>
|
||||
|
||||
# View multiple tasks with comma-separated IDs
|
||||
task-master show 1,3,5
|
||||
task-master show 44,55
|
||||
|
||||
# View a specific subtask (e.g., subtask 2 of task 1)
|
||||
task-master show 1.2
|
||||
|
||||
# Mix parent tasks and subtasks
|
||||
task-master show 44,44.1,55,55.2
|
||||
```
|
||||
|
||||
**Multiple Task Display:**
|
||||
|
||||
- **Single ID**: Shows detailed task view with full implementation details
|
||||
- **Multiple IDs**: Shows compact summary table with interactive action menu
|
||||
- **Action Menu**: Provides copy-paste ready commands for batch operations:
|
||||
- Mark all as in-progress/done
|
||||
- Show next available task
|
||||
- Expand all tasks (generate subtasks)
|
||||
- View dependency relationships
|
||||
- Generate task files
|
||||
|
||||
## Update Tasks
|
||||
|
||||
```bash
|
||||
@@ -229,6 +247,56 @@ task-master add-task --prompt="Description" --dependencies=1,2,3
|
||||
task-master add-task --prompt="Description" --priority=high
|
||||
```
|
||||
|
||||
## Tag Management
|
||||
|
||||
Task Master supports tagged task lists for multi-context task management. Each tag represents a separate, isolated context for tasks.
|
||||
|
||||
```bash
|
||||
# List all available tags with task counts and status
|
||||
task-master tags
|
||||
|
||||
# List tags with detailed metadata
|
||||
task-master tags --show-metadata
|
||||
|
||||
# Create a new empty tag
|
||||
task-master add-tag <tag-name>
|
||||
|
||||
# Create a new tag with a description
|
||||
task-master add-tag <tag-name> --description="Feature development tasks"
|
||||
|
||||
# Create a tag based on current git branch name
|
||||
task-master add-tag --from-branch
|
||||
|
||||
# Create a new tag by copying tasks from the current tag
|
||||
task-master add-tag <new-tag> --copy-from-current
|
||||
|
||||
# Create a new tag by copying from a specific tag
|
||||
task-master add-tag <new-tag> --copy-from=<source-tag>
|
||||
|
||||
# Switch to a different tag context
|
||||
task-master use-tag <tag-name>
|
||||
|
||||
# Rename an existing tag
|
||||
task-master rename-tag <old-name> <new-name>
|
||||
|
||||
# Copy an entire tag to create a new one
|
||||
task-master copy-tag <source-tag> <target-tag>
|
||||
|
||||
# Copy a tag with a description
|
||||
task-master copy-tag <source-tag> <target-tag> --description="Copied for testing"
|
||||
|
||||
# Delete a tag and all its tasks (with confirmation)
|
||||
task-master delete-tag <tag-name>
|
||||
|
||||
# Delete a tag without confirmation prompt
|
||||
task-master delete-tag <tag-name> --yes
|
||||
```
|
||||
|
||||
**Tag Context:**
|
||||
- All task operations (list, show, add, update, etc.) work within the currently active tag
|
||||
- Use `--tag=<name>` flag with most commands to operate on a specific tag context
|
||||
- Tags provide complete isolation - tasks in different tags don't interfere with each other
|
||||
|
||||
## Initialize a Project
|
||||
|
||||
```bash
|
||||
@@ -261,4 +329,70 @@ task-master models --set-research=google/gemini-pro --openrouter
|
||||
task-master models --setup
|
||||
```
|
||||
|
||||
Configuration is stored in `.taskmasterconfig` in your project root. API keys are still managed via `.env` or MCP configuration. Use `task-master models` without flags to see available built-in models. Use `--setup` for a guided experience.
|
||||
Configuration is stored in `.taskmaster/config.json` in your project root (legacy `.taskmasterconfig` files are automatically migrated). API keys are still managed via `.env` or MCP configuration. Use `task-master models` without flags to see available built-in models. Use `--setup` for a guided experience.
|
||||
|
||||
State is stored in `.taskmaster/state.json` in your project root. It maintains important information like the current tag. Do not manually edit this file.
|
||||
|
||||
## Research Fresh Information
|
||||
|
||||
```bash
|
||||
# Perform AI-powered research with fresh, up-to-date information
|
||||
task-master research "What are the latest best practices for JWT authentication in Node.js?"
|
||||
|
||||
# Research with specific task context
|
||||
task-master research "How to implement OAuth 2.0?" --id=15,16
|
||||
|
||||
# Research with file context for code-aware suggestions
|
||||
task-master research "How can I optimize this API implementation?" --files=src/api.js,src/auth.js
|
||||
|
||||
# Research with custom context and project tree
|
||||
task-master research "Best practices for error handling" --context="We're using Express.js" --tree
|
||||
|
||||
# Research with different detail levels
|
||||
task-master research "React Query v5 migration guide" --detail=high
|
||||
|
||||
# Disable interactive follow-up questions (useful for scripting, is the default for MCP)
|
||||
# Use a custom tasks file location
|
||||
task-master research "How to implement this feature?" --file=custom-tasks.json
|
||||
|
||||
# Research within a specific tag context
|
||||
task-master research "Database optimization strategies" --tag=feature-branch
|
||||
|
||||
# Save research conversation to .taskmaster/docs/research/ directory (for later reference)
|
||||
task-master research "Database optimization techniques" --save-file
|
||||
|
||||
# Save key findings directly to a task or subtask (recommended for actionable insights)
|
||||
task-master research "How to implement OAuth?" --save-to=15
|
||||
task-master research "API optimization strategies" --save-to=15.2
|
||||
|
||||
# Combine context gathering with automatic saving of findings
|
||||
task-master research "Best practices for this implementation" --id=15,16 --files=src/auth.js --save-to=15.3
|
||||
```
|
||||
|
||||
**The research command is a powerful exploration tool that provides:**
|
||||
|
||||
- **Fresh information beyond AI knowledge cutoffs**
|
||||
- **Project-aware context** from your tasks and files
|
||||
- **Automatic task discovery** using fuzzy search
|
||||
- **Multiple detail levels** (low, medium, high)
|
||||
- **Token counting and cost tracking**
|
||||
- **Interactive follow-up questions** for deep exploration
|
||||
- **Flexible save options** (commit findings to tasks or preserve conversations)
|
||||
- **Iterative discovery** through continuous questioning and refinement
|
||||
|
||||
**Use research frequently to:**
|
||||
|
||||
- Get current best practices before implementing features
|
||||
- Research new technologies and libraries
|
||||
- Find solutions to complex problems
|
||||
- Validate your implementation approaches
|
||||
- Stay updated with latest security recommendations
|
||||
|
||||
**Interactive Features (CLI):**
|
||||
|
||||
- **Follow-up questions** that maintain conversation context and allow deep exploration
|
||||
- **Save menu** during or after research with flexible options:
|
||||
- **Save to task/subtask**: Commit key findings and actionable insights (recommended)
|
||||
- **Save to file**: Preserve entire conversation for later reference if needed
|
||||
- **Continue exploring**: Ask more follow-up questions to dig deeper
|
||||
- **Automatic file naming** with timestamps and query-based slugs when saving conversations
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
Taskmaster uses two primary methods for configuration:
|
||||
|
||||
1. **`.taskmaster/config.json` File (Recommended - New Structure)**
|
||||
1. **`.taskmaster/config.json` File (Recommended - New Structure)**
|
||||
|
||||
- This JSON file stores most configuration settings, including AI model selections, parameters, logging levels, and project defaults.
|
||||
@@ -38,6 +39,7 @@ Taskmaster uses two primary methods for configuration:
|
||||
"debug": false,
|
||||
"defaultSubtasks": 5,
|
||||
"defaultPriority": "medium",
|
||||
"defaultTag": "master",
|
||||
"projectName": "Your Project Name",
|
||||
"ollamaBaseURL": "http://localhost:11434/api",
|
||||
"azureBaseURL": "https://your-endpoint.azure.com/",
|
||||
@@ -79,10 +81,50 @@ Taskmaster uses two primary methods for configuration:
|
||||
|
||||
**Important:** Settings like model ID selections (`main`, `research`, `fallback`), `maxTokens`, `temperature`, `logLevel`, `defaultSubtasks`, `defaultPriority`, and `projectName` are **managed in `.taskmaster/config.json`** (or `.taskmasterconfig` for unmigrated projects), not environment variables.
|
||||
|
||||
## Tagged Task Lists Configuration (v0.17+)
|
||||
|
||||
Taskmaster includes a tagged task lists system for multi-context task management.
|
||||
|
||||
### Global Tag Settings
|
||||
|
||||
```json
|
||||
"global": {
|
||||
"defaultTag": "master"
|
||||
}
|
||||
```
|
||||
|
||||
- **`defaultTag`** (string): Default tag context for new operations (default: "master")
|
||||
|
||||
### Git Integration
|
||||
|
||||
Task Master provides manual git integration through the `--from-branch` option:
|
||||
|
||||
- **Manual Tag Creation**: Use `task-master add-tag --from-branch` to create a tag based on your current git branch name
|
||||
- **User Control**: No automatic tag switching - you control when and how tags are created
|
||||
- **Flexible Workflow**: Supports any git workflow without imposing rigid branch-tag mappings
|
||||
|
||||
## State Management File
|
||||
|
||||
Taskmaster uses `.taskmaster/state.json` to track tagged system runtime information:
|
||||
|
||||
```json
|
||||
{
|
||||
"currentTag": "master",
|
||||
"lastSwitched": "2025-06-11T20:26:12.598Z",
|
||||
"migrationNoticeShown": true
|
||||
}
|
||||
```
|
||||
|
||||
- **`currentTag`**: Currently active tag context
|
||||
- **`lastSwitched`**: Timestamp of last tag switch
|
||||
- **`migrationNoticeShown`**: Whether migration notice has been displayed
|
||||
|
||||
This file is automatically created during tagged system migration and should not be manually edited.
|
||||
|
||||
## Example `.env` File (for API Keys)
|
||||
|
||||
```
|
||||
# Required API keys for providers configured in .taskmasterconfig
|
||||
# Required API keys for providers configured in .taskmaster/config.json
|
||||
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
|
||||
PERPLEXITY_API_KEY=pplx-your-key-here
|
||||
# OPENAI_API_KEY=sk-your-key-here
|
||||
@@ -157,7 +199,7 @@ Google Vertex AI is Google Cloud's enterprise AI platform and requires specific
|
||||
VERTEX_LOCATION=us-central1
|
||||
```
|
||||
|
||||
5. **In .taskmasterconfig**:
|
||||
5. **In .taskmaster/config.json**:
|
||||
```json
|
||||
"global": {
|
||||
"vertexProjectId": "my-gcp-project-123",
|
||||
|
||||
147
docs/examples.md
147
docs/examples.md
@@ -21,6 +21,20 @@ What's the next task I should work on? Please consider dependencies and prioriti
|
||||
I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?
|
||||
```
|
||||
|
||||
## Viewing multiple tasks
|
||||
|
||||
```
|
||||
Can you show me tasks 1, 3, and 5 so I can understand their relationship?
|
||||
```
|
||||
|
||||
```
|
||||
I need to see the status of tasks 44, 55, and their subtasks. Can you show me those?
|
||||
```
|
||||
|
||||
```
|
||||
Show me tasks 10, 12, and 15 and give me some batch actions I can perform on them.
|
||||
```
|
||||
|
||||
## Managing subtasks
|
||||
|
||||
```
|
||||
@@ -109,3 +123,136 @@ Please add a new task to implement user profile image uploads using Cloudinary,
|
||||
```
|
||||
|
||||
(Agent runs: `task-master add-task --prompt="Implement user profile image uploads using Cloudinary" --research`)
|
||||
|
||||
## Research-Driven Development
|
||||
|
||||
### Getting Fresh Information
|
||||
|
||||
```
|
||||
Research the latest best practices for implementing JWT authentication in Node.js applications.
|
||||
```
|
||||
|
||||
(Agent runs: `task-master research "Latest best practices for JWT authentication in Node.js"`)
|
||||
|
||||
### Research with Project Context
|
||||
|
||||
```
|
||||
I'm working on task 15 which involves API optimization. Can you research current best practices for our specific implementation?
|
||||
```
|
||||
|
||||
(Agent runs: `task-master research "API optimization best practices" --id=15 --files=src/api.js`)
|
||||
|
||||
### Research Before Implementation
|
||||
|
||||
```
|
||||
Before I implement task 8 (React Query integration), can you research the latest React Query v5 patterns and any breaking changes?
|
||||
```
|
||||
|
||||
(Agent runs: `task-master research "React Query v5 patterns and breaking changes" --id=8`)
|
||||
|
||||
### Research and Update Pattern
|
||||
|
||||
```
|
||||
Research the latest security recommendations for Express.js applications and update our authentication task with the findings.
|
||||
```
|
||||
|
||||
(Agent runs:
|
||||
|
||||
1. `task-master research "Latest Express.js security recommendations" --id=12`
|
||||
2. `task-master update-subtask --id=12.3 --prompt="Updated with latest security findings: [research results]"`)
|
||||
|
||||
### Research for Debugging
|
||||
|
||||
```
|
||||
I'm having issues with our WebSocket implementation in task 20. Can you research common WebSocket problems and solutions?
|
||||
```
|
||||
|
||||
(Agent runs: `task-master research "Common WebSocket implementation problems and solutions" --id=20 --files=src/websocket.js`)
|
||||
|
||||
### Research Technology Comparisons
|
||||
|
||||
```
|
||||
We need to choose between Redis and Memcached for caching. Can you research the current recommendations for our use case?
|
||||
```
|
||||
|
||||
(Agent runs: `task-master research "Redis vs Memcached 2024 comparison for session caching" --tree`)
|
||||
|
||||
## Git Integration and Tag Management
|
||||
|
||||
### Creating Tags for Feature Branches
|
||||
|
||||
```
|
||||
I'm starting work on a new feature branch for user authentication. Can you create a matching task tag?
|
||||
```
|
||||
|
||||
(Agent runs: `task-master add-tag --from-branch`)
|
||||
|
||||
### Creating Named Tags
|
||||
|
||||
```
|
||||
Create a new tag called 'api-v2' for our API redesign work.
|
||||
```
|
||||
|
||||
(Agent runs: `task-master add-tag api-v2 --description="API v2 redesign tasks"`)
|
||||
|
||||
### Switching Tag Contexts
|
||||
|
||||
```
|
||||
Switch to the 'testing' tag so I can work on QA tasks.
|
||||
```
|
||||
|
||||
(Agent runs: `task-master use-tag testing`)
|
||||
|
||||
### Copying Tasks Between Tags
|
||||
|
||||
```
|
||||
I need to copy the current tasks to a new 'hotfix' tag for urgent fixes.
|
||||
```
|
||||
|
||||
(Agent runs: `task-master add-tag hotfix --copy-from-current --description="Urgent hotfix tasks"`)
|
||||
|
||||
### Managing Multiple Contexts
|
||||
|
||||
```
|
||||
Show me all available tags and their current status.
|
||||
```
|
||||
|
||||
(Agent runs: `task-master tags --show-metadata`)
|
||||
|
||||
### Tag Cleanup
|
||||
|
||||
```
|
||||
I've finished the 'user-auth' feature and merged the branch. Can you clean up the tag?
|
||||
```
|
||||
|
||||
(Agent runs: `task-master delete-tag user-auth`)
|
||||
|
||||
### Working with Tag-Specific Tasks
|
||||
|
||||
```
|
||||
List all tasks in the 'api-v2' tag context.
|
||||
```
|
||||
|
||||
(Agent runs: `task-master use-tag api-v2` then `task-master list`)
|
||||
|
||||
### Branch-Based Development Workflow
|
||||
|
||||
```
|
||||
I'm switching to work on the 'feature/payments' branch. Can you set up the task context for this?
|
||||
```
|
||||
|
||||
(Agent runs:
|
||||
1. `git checkout feature/payments`
|
||||
2. `task-master add-tag --from-branch --description="Payment system implementation"`
|
||||
3. `task-master list` to show tasks in the new context)
|
||||
|
||||
### Parallel Feature Development
|
||||
|
||||
```
|
||||
I need to work on both authentication and payment features simultaneously. How should I organize the tasks?
|
||||
```
|
||||
|
||||
(Agent suggests and runs:
|
||||
1. `task-master add-tag auth --description="Authentication feature tasks"`
|
||||
2. `task-master add-tag payments --description="Payment system tasks"`
|
||||
3. `task-master use-tag auth` to start with authentication work)
|
||||
|
||||
@@ -232,4 +232,4 @@ If you encounter issues during migration:
|
||||
|
||||
---
|
||||
|
||||
_This migration guide applies to Task Master v3.x and later. For older versions, please upgrade to the latest version first._
|
||||
_This migration guide applies to Task Master v0.15.x and later. For older versions, please upgrade to the latest version first._
|
||||
|
||||
@@ -137,3 +137,290 @@ The `show` command:
|
||||
8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
|
||||
|
||||
9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.
|
||||
|
||||
# Task Structure Documentation
|
||||
|
||||
Task Master uses a structured JSON format to organize and manage tasks. As of version 0.16.2, Task Master introduces **Tagged Task Lists** for multi-context task management while maintaining full backward compatibility.
|
||||
|
||||
## Tagged Task Lists System
|
||||
|
||||
Task Master now organizes tasks into separate contexts called **tags**. This enables working across multiple contexts such as different branches, environments, or project phases without conflicts.
|
||||
|
||||
### Data Structure Overview
|
||||
|
||||
**Tagged Format (Current)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"master": {
|
||||
"tasks": [
|
||||
{ "id": 1, "title": "Setup API", "status": "pending", ... }
|
||||
]
|
||||
},
|
||||
"feature-branch": {
|
||||
"tasks": [
|
||||
{ "id": 1, "title": "New Feature", "status": "pending", ... }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Legacy Format (Automatically Migrated)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"tasks": [
|
||||
{ "id": 1, "title": "Setup API", "status": "pending", ... }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Tag-based Task Lists (v0.17+) and Compatibility
|
||||
|
||||
- **Seamless Migration**: Existing `tasks.json` files are automatically migrated to use a "master" tag
|
||||
- **Zero Disruption**: All existing commands continue to work exactly as before
|
||||
- **Backward Compatibility**: Existing workflows remain unchanged
|
||||
- **Silent Process**: Migration happens transparently on first use with a friendly notification
|
||||
|
||||
## Core Task Properties
|
||||
|
||||
Each task within a tag context contains the following properties:
|
||||
|
||||
### Required Properties
|
||||
|
||||
- **`id`** (number): Unique identifier within the tag context
|
||||
|
||||
```json
|
||||
"id": 1
|
||||
```
|
||||
|
||||
- **`title`** (string): Brief, descriptive title
|
||||
|
||||
```json
|
||||
"title": "Implement user authentication"
|
||||
```
|
||||
|
||||
- **`description`** (string): Concise summary of what the task involves
|
||||
|
||||
```json
|
||||
"description": "Create a secure authentication system using JWT tokens"
|
||||
```
|
||||
|
||||
- **`status`** (string): Current state of the task
|
||||
- Valid values: `"pending"`, `"in-progress"`, `"done"`, `"review"`, `"deferred"`, `"cancelled"`
|
||||
```json
|
||||
"status": "pending"
|
||||
```
|
||||
|
||||
### Optional Properties
|
||||
|
||||
- **`dependencies`** (array): IDs of prerequisite tasks that must be completed first
|
||||
|
||||
```json
|
||||
"dependencies": [2, 3]
|
||||
```
|
||||
|
||||
- **`priority`** (string): Importance level
|
||||
|
||||
- Valid values: `"high"`, `"medium"`, `"low"`
|
||||
- Default: `"medium"`
|
||||
|
||||
```json
|
||||
"priority": "high"
|
||||
```
|
||||
|
||||
- **`details`** (string): In-depth implementation instructions
|
||||
|
||||
```json
|
||||
"details": "Use GitHub OAuth client ID/secret, handle callback, set session token"
|
||||
```
|
||||
|
||||
- **`testStrategy`** (string): Verification approach
|
||||
|
||||
```json
|
||||
"testStrategy": "Deploy and call endpoint to confirm authentication flow"
|
||||
```
|
||||
|
||||
- **`subtasks`** (array): List of smaller, more specific tasks
|
||||
```json
|
||||
"subtasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Configure OAuth",
|
||||
"description": "Set up OAuth configuration",
|
||||
"status": "pending",
|
||||
"dependencies": [],
|
||||
"details": "Configure GitHub OAuth app and store credentials"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Subtask Structure
|
||||
|
||||
Subtasks follow a similar structure to main tasks but with some differences:
|
||||
|
||||
### Subtask Properties
|
||||
|
||||
- **`id`** (number): Unique identifier within the parent task
|
||||
- **`title`** (string): Brief, descriptive title
|
||||
- **`description`** (string): Concise summary of the subtask
|
||||
- **`status`** (string): Current state (same values as main tasks)
|
||||
- **`dependencies`** (array): Can reference other subtasks or main task IDs
|
||||
- **`details`** (string): Implementation instructions and notes
|
||||
|
||||
### Subtask Example
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Handle OAuth callback",
|
||||
"description": "Process the OAuth callback and extract user data",
|
||||
"status": "pending",
|
||||
"dependencies": [1],
|
||||
"details": "Parse callback parameters, exchange code for token, fetch user profile"
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a complete example showing the tagged task structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"master": {
|
||||
"tasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Setup Express Server",
|
||||
"description": "Initialize and configure Express.js server with middleware",
|
||||
"status": "done",
|
||||
"dependencies": [],
|
||||
"priority": "high",
|
||||
"details": "Create Express app with CORS, body parser, and error handling",
|
||||
"testStrategy": "Start server and verify health check endpoint responds",
|
||||
"subtasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Initialize npm project",
|
||||
"description": "Set up package.json and install dependencies",
|
||||
"status": "done",
|
||||
"dependencies": [],
|
||||
"details": "Run npm init, install express, cors, body-parser"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Configure middleware",
|
||||
"description": "Set up CORS and body parsing middleware",
|
||||
"status": "done",
|
||||
"dependencies": [1],
|
||||
"details": "Add app.use() calls for cors() and express.json()"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Implement user authentication",
|
||||
"description": "Create secure authentication system",
|
||||
"status": "pending",
|
||||
"dependencies": [1],
|
||||
"priority": "high",
|
||||
"details": "Use JWT tokens for session management",
|
||||
"testStrategy": "Test login/logout flow with valid and invalid credentials",
|
||||
"subtasks": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"feature-auth": {
|
||||
"tasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "OAuth Integration",
|
||||
"description": "Add OAuth authentication support",
|
||||
"status": "pending",
|
||||
"dependencies": [],
|
||||
"priority": "medium",
|
||||
"details": "Integrate with GitHub OAuth for user authentication",
|
||||
"testStrategy": "Test OAuth flow with GitHub account",
|
||||
"subtasks": []
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tag Context Management
|
||||
|
||||
### Current Tag Resolution
|
||||
|
||||
Task Master automatically determines the current tag context based on:
|
||||
|
||||
1. **State Configuration**: Current tag stored in `.taskmaster/state.json`
|
||||
2. **Default Fallback**: "master" tag when no context is specified
|
||||
3. **Future Enhancement**: Git branch-based tag switching (Part 2)
|
||||
|
||||
### Tag Isolation
|
||||
|
||||
- **Context Separation**: Tasks in different tags are completely isolated
|
||||
- **Independent Numbering**: Each tag has its own task ID sequence starting from 1
|
||||
- **Parallel Development**: Multiple team members can work on separate tags without conflicts
|
||||
|
||||
## Data Validation
|
||||
|
||||
Task Master validates the following aspects of task data:
|
||||
|
||||
### Required Validations
|
||||
|
||||
- **Unique IDs**: Task IDs must be unique within each tag context
|
||||
- **Valid Status**: Status values must be from the allowed set
|
||||
- **Dependency References**: Dependencies must reference existing task IDs within the same tag
|
||||
- **Subtask IDs**: Subtask IDs must be unique within their parent task
|
||||
|
||||
### Optional Validations
|
||||
|
||||
- **Circular Dependencies**: System detects and prevents circular dependency chains
|
||||
- **Priority Values**: Priority must be one of the allowed values if specified
|
||||
- **Data Types**: All properties must match their expected data types
|
||||
|
||||
## File Generation
|
||||
|
||||
Task Master can generate individual markdown files for each task based on the JSON structure. These files include:
|
||||
|
||||
- **Task Overview**: ID, title, status, dependencies
|
||||
- **Tag Context**: Which tag the task belongs to
|
||||
- **Implementation Details**: Full task details and test strategy
|
||||
- **Subtask Breakdown**: All subtasks with their current status
|
||||
- **Dependency Status**: Visual indicators showing which dependencies are complete
|
||||
|
||||
## Migration Process
|
||||
|
||||
When Task Master encounters a legacy format `tasks.json` file:
|
||||
|
||||
1. **Detection**: Automatically detects `{"tasks": [...]}` format
|
||||
2. **Transformation**: Converts to `{"master": {"tasks": [...]}}` format
|
||||
3. **Configuration**: Updates `.taskmaster/config.json` with tagged system settings
|
||||
4. **State Creation**: Creates `.taskmaster/state.json` for tag management
|
||||
5. **Notification**: Shows one-time friendly notice about the new system
|
||||
6. **Preservation**: All existing task data is preserved exactly as-is
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Task Organization
|
||||
|
||||
- **Logical Grouping**: Use tags to group related tasks (e.g., by feature, branch, or milestone)
|
||||
- **Clear Titles**: Use descriptive titles that explain the task's purpose
|
||||
- **Proper Dependencies**: Define dependencies to ensure correct execution order
|
||||
- **Detailed Instructions**: Include sufficient detail in the `details` field for implementation
|
||||
|
||||
### Tag Management
|
||||
|
||||
- **Meaningful Names**: Use descriptive tag names that reflect their purpose
|
||||
- **Consistent Naming**: Establish naming conventions for tags (e.g., branch names, feature names)
|
||||
- **Context Switching**: Be aware of which tag context you're working in
|
||||
- **Isolation Benefits**: Leverage tag isolation to prevent merge conflicts
|
||||
|
||||
### Subtask Design
|
||||
|
||||
- **Granular Tasks**: Break down complex tasks into manageable subtasks
|
||||
- **Clear Dependencies**: Define subtask dependencies to show implementation order
|
||||
- **Implementation Notes**: Use subtask details to track progress and decisions
|
||||
- **Status Tracking**: Keep subtask status updated as work progresses
|
||||
|
||||
165
docs/tutorial.md
165
docs/tutorial.md
@@ -198,10 +198,15 @@ Ask the agent to list available tasks:
|
||||
What tasks are available to work on next?
|
||||
```
|
||||
|
||||
```
|
||||
Can you show me tasks 1, 3, and 5 to understand their current status?
|
||||
```
|
||||
|
||||
The agent will:
|
||||
|
||||
- Run `task-master list` to see all tasks
|
||||
- Run `task-master next` to determine the next task to work on
|
||||
- Run `task-master show 1,3,5` to display multiple tasks with interactive options
|
||||
- Analyze dependencies to determine which tasks are ready to be worked on
|
||||
- Prioritize tasks based on priority level and ID order
|
||||
- Suggest the next task(s) to implement
|
||||
@@ -221,6 +226,21 @@ You can ask:
|
||||
Let's implement task 3. What does it involve?
|
||||
```
|
||||
|
||||
### 2.1. Viewing Multiple Tasks
|
||||
|
||||
For efficient context gathering and batch operations:
|
||||
|
||||
```
|
||||
Show me tasks 5, 7, and 9 so I can plan my implementation approach.
|
||||
```
|
||||
|
||||
The agent will:
|
||||
|
||||
- Run `task-master show 5,7,9` to display a compact summary table
|
||||
- Show task status, priority, and progress indicators
|
||||
- Provide an interactive action menu with batch operations
|
||||
- Allow you to perform group actions like marking multiple tasks as in-progress
|
||||
|
||||
### 3. Task Verification
|
||||
|
||||
Before marking a task as complete, verify it according to:
|
||||
@@ -423,3 +443,148 @@ Can you analyze the complexity of our tasks to help me understand which ones nee
|
||||
```
|
||||
Can you show me the complexity report in a more readable format?
|
||||
```
|
||||
|
||||
### Research-Driven Development
|
||||
|
||||
Task Master includes a powerful research tool that provides fresh, up-to-date information beyond the AI's knowledge cutoff. This is particularly valuable for:
|
||||
|
||||
#### Getting Current Best Practices
|
||||
|
||||
```
|
||||
Before implementing task 5 (authentication), research the latest JWT security recommendations.
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
task-master research "Latest JWT security recommendations 2024" --id=5
|
||||
```
|
||||
|
||||
#### Research with Project Context
|
||||
|
||||
```
|
||||
Research React Query v5 migration strategies for our current API implementation.
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
task-master research "React Query v5 migration strategies" --files=src/api.js,src/hooks.js
|
||||
```
|
||||
|
||||
#### Research and Update Pattern
|
||||
|
||||
A powerful workflow is to research first, then update tasks with findings:
|
||||
|
||||
```
|
||||
Research the latest Node.js performance optimization techniques and update task 12 with the findings.
|
||||
```
|
||||
|
||||
The agent will:
|
||||
|
||||
1. Run research: `task-master research "Node.js performance optimization 2024" --id=12`
|
||||
2. Update the task: `task-master update-subtask --id=12.2 --prompt="Updated with latest performance findings: [research results]"`
|
||||
|
||||
#### When to Use Research
|
||||
|
||||
- **Before implementing any new technology**
|
||||
- **When encountering security-related tasks**
|
||||
- **For performance optimization tasks**
|
||||
- **When debugging complex issues**
|
||||
- **Before making architectural decisions**
|
||||
- **When updating dependencies**
|
||||
|
||||
The research tool automatically includes relevant project context and provides fresh information that can significantly improve implementation quality.
|
||||
|
||||
## Git Integration and Tag Management
|
||||
|
||||
Task Master supports tagged task lists for multi-context development, which is particularly useful when working with git branches or different project phases.
|
||||
|
||||
### Working with Tags
|
||||
|
||||
Tags provide isolated task contexts, allowing you to maintain separate task lists for different features, branches, or experiments:
|
||||
|
||||
```
|
||||
I'm starting work on a new feature branch. Can you create a new tag for this work?
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
# Create a tag based on your current git branch
|
||||
task-master add-tag --from-branch
|
||||
```
|
||||
|
||||
Or you can create a tag with a specific name:
|
||||
|
||||
```
|
||||
Create a new tag called 'user-auth' for authentication-related tasks.
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
task-master add-tag user-auth --description="User authentication feature tasks"
|
||||
```
|
||||
|
||||
### Switching Between Contexts
|
||||
|
||||
When working on different features or branches:
|
||||
|
||||
```
|
||||
Switch to the 'user-auth' tag context so I can work on authentication tasks.
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
task-master use-tag user-auth
|
||||
```
|
||||
|
||||
### Copying Tasks Between Tags
|
||||
|
||||
When you need to duplicate work across contexts:
|
||||
|
||||
```
|
||||
Copy all tasks from the current tag to a new 'testing' tag for QA work.
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
task-master add-tag testing --copy-from-current --description="QA and testing tasks"
|
||||
```
|
||||
|
||||
### Tag Management
|
||||
|
||||
View and manage your tag contexts:
|
||||
|
||||
```
|
||||
Show me all available tags and their current status.
|
||||
```
|
||||
|
||||
The agent will execute:
|
||||
|
||||
```bash
|
||||
task-master tags --show-metadata
|
||||
```
|
||||
|
||||
### Benefits of Tagged Task Lists
|
||||
|
||||
- **Branch Isolation**: Each git branch can have its own task context
|
||||
- **Merge Conflict Prevention**: Tasks in different tags don't interfere with each other
|
||||
- **Parallel Development**: Multiple team members can work on separate contexts
|
||||
- **Context Switching**: Easily switch between different project phases or features
|
||||
- **Experimentation**: Create experimental task lists without affecting main work
|
||||
|
||||
### Git Workflow Integration
|
||||
|
||||
A typical git workflow with Task Master tags:
|
||||
|
||||
1. **Create feature branch**: `git checkout -b feature/user-auth`
|
||||
2. **Create matching tag**: Ask agent to run `task-master add-tag --from-branch`
|
||||
3. **Work in isolated context**: All task operations work within the new tag
|
||||
4. **Switch contexts as needed**: Use `task-master use-tag <name>` to switch between different work streams
|
||||
5. **Merge and cleanup**: After merging the branch, optionally delete the tag with `task-master delete-tag <name>`
|
||||
|
||||
This workflow ensures your task management stays organized and conflicts are minimized when working with teams or multiple features simultaneously.
|
||||
|
||||
Reference in New Issue
Block a user