From 60c0f26f3c27baeb9e38d074c47532a39e34034c Mon Sep 17 00:00:00 2001 From: Eyal Toledano Date: Fri, 13 Jun 2025 19:35:28 -0400 Subject: [PATCH] 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 --- .cursor/rules/architecture.mdc | 4 +- .cursor/rules/dev_workflow.mdc | 8 +- .cursor/rules/git_workflow.mdc | 24 +++--- .cursor/rules/taskmaster.mdc | 136 +++++++++++++++++++++++++++------ .cursor/rules/utilities.mdc | 4 +- .taskmaster/tasks/tasks.json | 4 +- docs/command-reference.md | 87 +++++++++++++++++++-- docs/configuration.md | 32 +++----- docs/examples.md | 80 +++++++++++++++++++ docs/tutorial.md | 93 ++++++++++++++++++++++ 10 files changed, 400 insertions(+), 72 deletions(-) diff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdc index 8c62c096..6ec9aaeb 100644 --- a/.cursor/rules/architecture.mdc +++ b/.cursor/rules/architecture.mdc @@ -76,7 +76,7 @@ alwaysApply: false - Tool `execute` methods call **direct function wrappers** (`mcp-server/src/core/direct-functions/*.js`), passing the normalized `projectRoot` and other args. - Direct functions use path utilities (`mcp-server/src/core/utils/`) to resolve paths based on `projectRoot` from session. - Direct functions implement silent mode, logger wrappers, and call core logic functions from `scripts/modules/`. - - **Tagged Task Lists**: MCP tools need updating to handle tagged format (Part 2 implementation). + - **Tagged Task Lists**: MCP tools fully support the tagged format with complete tag management capabilities. - Manages MCP caching and response formatting. - **[`init.js`](mdc:scripts/init.js): Project Initialization Logic** @@ -287,7 +287,7 @@ Follow these steps to add MCP support for an existing Task Master command (see [ - Call core logic. - Return `{ success: true/false, data/error, fromCache: boolean }`. - Export the wrapper function. - - **Note**: Tag-aware MCP tools will be implemented in Part 2 of the tagged system. + - **Note**: Tag-aware MCP tools are fully implemented with complete tag management support. 3. **Update `task-master-core.js` with Import/Export**: Add imports/exports for the new `*Direct` function. diff --git a/.cursor/rules/dev_workflow.mdc b/.cursor/rules/dev_workflow.mdc index 64e75a26..f03658b4 100644 --- a/.cursor/rules/dev_workflow.mdc +++ b/.cursor/rules/dev_workflow.mdc @@ -18,7 +18,7 @@ Task Master offers two primary ways to interact: - Refer to [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details on the MCP architecture and available tools. - A comprehensive list and description of MCP tools and their corresponding CLI commands can be found in [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc). - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change. - - **Note**: MCP tools will be updated for tagged task lists support in Part 2 of the implementation. + - **Note**: MCP tools fully support tagged task lists with complete tag management capabilities. 2. **`task-master` CLI (For Users & Fallback)**: - The global `task-master` command provides a user-friendly interface for direct terminal interaction. @@ -58,7 +58,7 @@ Task Master now supports **tagged task lists** for multi-context task management } ``` -**Coming in Part 2**: CLI commands for tag management (`add-tag`, `use-tag`, `list-tags`) and enhanced MCP support. +**Tag Management**: CLI commands for tag management (`add-tag`, `use-tag`, `list-tags`, `delete-tag`, `rename-tag`, `copy-tag`) are now available with manual git integration via `--from-branch` option. ## Standard Development Workflow Process @@ -153,9 +153,9 @@ Taskmaster configuration is managed through two main mechanisms: * Available keys/variables: See `assets/env.example` or the Configuration section in the command reference (previously linked to `taskmaster.mdc`). 3. **`.taskmaster/state.json` File (Tagged System State):** - * Tracks current tag context, migration status, and tag-branch mappings. + * Tracks current tag context and migration status. * Automatically created during tagged system migration. - * Contains: `currentTag`, `lastSwitched`, `branchTagMapping`, `migrationNoticeShown`. + * Contains: `currentTag`, `lastSwitched`, `migrationNoticeShown`. **Important:** Non-API key settings (like model selections, `MAX_TOKENS`, `TASKMASTER_LOG_LEVEL`) are **no longer configured via environment variables**. Use the `task-master models` command (or `--setup` for interactive configuration) or the `models` MCP tool. **If AI commands FAIL in MCP** verify that the API key for the selected provider is present in the `env` section of `.cursor/mcp.json`. diff --git a/.cursor/rules/git_workflow.mdc b/.cursor/rules/git_workflow.mdc index 6487afaa..44058478 100644 --- a/.cursor/rules/git_workflow.mdc +++ b/.cursor/rules/git_workflow.mdc @@ -41,10 +41,10 @@ Task Master's **tagged task lists system** provides significant benefits for Git - **Zero Disruption**: All existing Git workflows continue unchanged - **Backward Compatibility**: Legacy projects work exactly as before -### **Future Enhancements (Part 2)** -- **Automatic Tag Creation**: Create tags based on git branch names -- **Branch-Tag Mapping**: Automatically switch tag contexts with branch changes -- **Git Integration**: Enhanced git branch integration features +### **Manual Git Integration** +- **Manual Tag Creation**: Use `--from-branch` option to create tags from current git branch +- **Manual Context Switching**: Explicitly switch tag contexts as needed for different branches +- **Simplified Integration**: Focused on manual control rather than automatic workflows ## **Workflow Overview** @@ -328,10 +328,10 @@ Mention any dependent tasks or follow-up work needed. # 2. Tasks in separate tags are completely isolated # 3. Use Task Master's move functionality to reorganize if needed -# Future (Part 2): Enhanced git integration -# - Automatic tag creation based on branch names -# - Branch-tag mapping for seamless context switching -# - Git hooks for automated tag management +# Manual git integration available: +# - Use `task-master add-tag --from-branch` to create tags from current branch +# - Manually switch contexts with `task-master use-tag ` +# - Simple, predictable workflow without automatic behavior ``` ### **Code Conflicts** @@ -391,10 +391,10 @@ task-master update-task --id= --prompt="Task cancelled due to..." - **Clean Merges**: Reduced likelihood of task-related merge conflicts - **Parallel Development**: Multiple developers can work simultaneously without task conflicts -### **Future Git Integration (Part 2)** -- **Branch-Tag Mapping**: Automatic tag switching based on git branch -- **Git Hooks**: Automated tag management during branch operations -- **Enhanced Workflow**: Seamless integration between git branches and task contexts +### **Manual Git Integration** +- **Branch-Based Tag Creation**: Use `--from-branch` option to create tags from current git branch +- **Manual Context Management**: Explicitly switch tag contexts as needed +- **Predictable Workflow**: Simple, manual control without automatic behavior --- diff --git a/.cursor/rules/taskmaster.mdc b/.cursor/rules/taskmaster.mdc index 3404f504..906a3056 100644 --- a/.cursor/rules/taskmaster.mdc +++ b/.cursor/rules/taskmaster.mdc @@ -11,7 +11,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov **Important:** Several MCP tools involve AI processing... The AI-powered tools include `parse_prd`, `analyze_project_complexity`, `update_subtask`, `update_task`, `update`, `expand_all`, `expand_task`, and `add_task`. -**Tagged Task Lists System:** Task Master now supports tagged task lists for multi-context task management. Existing projects automatically migrate to use a "master" tag with zero disruption. All commands continue to work unchanged while providing the foundation for enhanced multi-context workflows. MCP tools will be updated for full tagged support in Part 2 of the implementation. +**🏷️ Tagged Task Lists System:** Task Master now supports **tagged task lists** for multi-context task management. This allows you to maintain separate, isolated lists of tasks for different features, branches, or experiments. Existing projects are seamlessly migrated to use a default "master" tag. Most commands now support a `--tag ` flag to specify which context to operate on. If omitted, commands use the currently active tag. --- @@ -39,6 +39,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov * `yes`: `Skip prompts and use defaults/provided arguments. Default is false.` (CLI: `-y, --yes`) * **Usage:** Run this once at the beginning of a new project, typically via an integrated tool like Cursor. Operates on the current working directory of the MCP server. * **Important:** Once complete, you *MUST* parse a prd in order to generate tasks. There will be no tasks files until then. The next step after initializing should be to create a PRD using the example PRD in .taskmaster/templates/example_prd.txt. +* **Tagging:** Use the `--tag` option to parse the PRD into a specific, non-default tag context. If the tag doesn't exist, it will be created automatically. Example: `task-master parse-prd spec.txt --tag=new-feature`. ### 2. Parse PRD (`parse_prd`) @@ -94,8 +95,9 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **CLI Command:** `task-master list [options]` * **Description:** `List your Taskmaster tasks, optionally filtering by status and showing subtasks.` * **Key Parameters/Options:** - * `status`: `Show only Taskmaster tasks matching this status, e.g., 'pending' or 'done'.` (CLI: `-s, --status `) + * `status`: `Show only Taskmaster tasks matching this status (or multiple statuses, comma-separated), e.g., 'pending' or 'done,in-progress'.` (CLI: `-s, --status `) * `withSubtasks`: `Include subtasks indented under their parent tasks in the list.` (CLI: `--with-subtasks`) + * `tag`: `Specify which tag context to list tasks from. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) * **Usage:** Get an overview of the project status, often used at the start of a work session. @@ -112,11 +114,12 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **MCP Tool:** `get_task` * **CLI Command:** `task-master show [id] [options]` -* **Description:** `Display detailed information for a specific Taskmaster task or subtask by its ID.` +* **Description:** `Display detailed information for one or more specific Taskmaster tasks or subtasks by ID.` * **Key Parameters/Options:** - * `id`: `Required. The ID of the Taskmaster task, e.g., '15', or subtask, e.g., '15.2', you want to view.` (CLI: `[id]. Supports comma-separated list of tasks to get multiple tasks at once.` positional or `-i, --id `) + * `id`: `Required. The ID of the Taskmaster task (e.g., '15'), subtask (e.g., '15.2'), or a comma-separated list of IDs ('1,5,10.2') you want to view.` (CLI: `[id]` positional or `-i, --id `) + * `tag`: `Specify which tag context to get the task(s) from. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) -* **Usage:** Understand the full details, implementation notes, and test strategy for a specific task before starting work. +* **Usage:** Understand the full details for a specific task. When multiple IDs are provided, a summary table is shown. * **CRITICAL INFORMATION** If you need to collect information from multiple tasks, use comma-separated IDs (i.e. 1,2,3) to receive an array of tasks. Do not needlessly get tasks one at a time if you need to get many as that is wasteful. --- @@ -171,13 +174,15 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **MCP Tool:** `update_task` * **CLI Command:** `task-master update-task [options]` -* **Description:** `Modify a specific Taskmaster task or subtask by its ID, incorporating new information or changes.` +* **Description:** `Modify a specific Taskmaster task by ID, incorporating new information or changes. By default, this replaces the existing task details.` * **Key Parameters/Options:** - * `id`: `Required. The specific ID of the Taskmaster task, e.g., '15', or subtask, e.g., '15.2', you want to update.` (CLI: `-i, --id `) + * `id`: `Required. The specific ID of the Taskmaster task, e.g., '15', you want to update.` (CLI: `-i, --id `) * `prompt`: `Required. Explain the specific changes or provide the new information Taskmaster should incorporate into this task.` (CLI: `-p, --prompt `) + * `append`: `If true, appends the prompt content to the task's details with a timestamp, rather than replacing them. Behaves like update-subtask.` (CLI: `--append`) * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`) + * `tag`: `Specify which tag context the task belongs to. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) -* **Usage:** Refine a specific task based on new understanding or feedback. Example CLI: `task-master update-task --id='15' --prompt='Clarification: Use PostgreSQL instead of MySQL.\nUpdate schema details...'` +* **Usage:** Refine a specific task based on new understanding. Use `--append` to log progress without creating subtasks. * **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. ### 10. Update Subtask (`update_subtask`) @@ -186,12 +191,12 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **CLI Command:** `task-master update-subtask [options]` * **Description:** `Append timestamped notes or details to a specific Taskmaster subtask without overwriting existing content. Intended for iterative implementation logging.` * **Key Parameters/Options:** - * `id`: `Required. The specific ID of the Taskmaster subtask, e.g., '15.2', you want to add information to.` (CLI: `-i, --id `) - * `prompt`: `Required. Provide the information or notes Taskmaster should append to the subtask's details. Ensure this adds *new* information not already present.` (CLI: `-p, --prompt `) - * `research`: `Enable Taskmaster to use the research role for more informed updates. Requires appropriate API key.` (CLI: `-r, --research`) + * `id`: `Required. The ID of the Taskmaster task, e.g., '5', or subtask, e.g., '5.2', to permanently remove.` (CLI: `-i, --id `) + * `yes`: `Skip the confirmation prompt and immediately delete the task.` (CLI: `-y, --yes`) + * `tag`: `Specify which tag context to remove the task from. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) -* **Usage:** Add implementation notes, code snippets, or clarifications to a subtask during development. Before calling, review the subtask's current details to append only fresh insights, helping to build a detailed log of the implementation journey and avoid redundancy. Example CLI: `task-master update-subtask --id='15.2' --prompt='Discovered that the API requires header X.\nImplementation needs adjustment...'` -* **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. +* **Usage:** Permanently delete tasks or subtasks that are no longer needed in the project. +* **Notes:** Use with caution as this operation cannot be undone. Consider using 'blocked', 'cancelled', or 'deferred' status instead if you just want to exclude a task from active planning but keep it for reference. The command automatically cleans up dependency references in other tasks. ### 11. Set Task Status (`set_task_status`) @@ -231,6 +236,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov * `research`: `Enable Taskmaster to use the research role for more informed subtask generation. Requires appropriate API key.` (CLI: `-r, --research`) * `prompt`: `Optional: Provide extra context or specific instructions to Taskmaster for generating the subtasks.` (CLI: `-p, --prompt `) * `force`: `Optional: If true, clear existing subtasks before generating new ones. Default is false (append).` (CLI: `--force`) + * `tag`: `Specify which tag context the task belongs to. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) * **Usage:** Generate a detailed implementation plan for a complex task before starting coding. Automatically uses complexity report recommendations if available and `num` is not specified. * **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. @@ -245,6 +251,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov * `research`: `Enable research role for more informed subtask generation. Requires appropriate API key.` (CLI: `-r, --research`) * `prompt`: `Optional: Provide extra context for Taskmaster to apply generally during expansion.` (CLI: `-p, --prompt `) * `force`: `Optional: If true, clear existing subtasks before generating new ones for each eligible task. Default is false (append).` (CLI: `--force`) + * `tag`: `Specify which tag context to expand. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) * **Usage:** Useful after initial task generation or complexity analysis to break down multiple tasks at once. * **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. @@ -338,6 +345,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **CLI Command:** `task-master fix-dependencies [options]` * **Description:** `Automatically fix dependency issues (like circular references or links to non-existent tasks) in your Taskmaster tasks.` * **Key Parameters/Options:** + * `tag`: `Specify which tag context to fix dependencies in. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) * **Usage:** Clean up dependency errors automatically. @@ -351,9 +359,10 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **CLI Command:** `task-master analyze-complexity [options]` * **Description:** `Have Taskmaster analyze your tasks to determine their complexity and suggest which ones need to be broken down further.` * **Key Parameters/Options:** - * `output`: `Where to save the complexity analysis report (default: '.taskmaster/reports/task-complexity-report.json').` (CLI: `-o, --output `) + * `output`: `Where to save the complexity analysis report. Default is '.taskmaster/reports/task-complexity-report.json' (or '..._tagname.json' if a tag is used).` (CLI: `-o, --output `) * `threshold`: `The minimum complexity score (1-10) that should trigger a recommendation to expand a task.` (CLI: `-t, --threshold `) * `research`: `Enable research role for more accurate complexity analysis. Requires appropriate API key.` (CLI: `-r, --research`) + * `tag`: `Specify which tag context to analyze. Defaults to the current active tag.` (CLI: `--tag `) * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) * **Usage:** Used before breaking down tasks to identify which ones need the most attention. * **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. @@ -369,6 +378,21 @@ This document provides a detailed reference for interacting with Taskmaster, cov --- +## File Management + +### 24. Generate Task Files (`generate`) + +* **MCP Tool:** `generate` +* **CLI Command:** `task-master generate [options]` +* **Description:** `Create or update individual Markdown files for each task based on your tasks.json.` +* **Key Parameters/Options:** + * `output`: `The directory where Taskmaster should save the task files (default: in a 'tasks' directory).` (CLI: `-o, --output `) + * `tag`: `Specify which tag context to generate files for. Defaults to the current active tag.` (CLI: `--tag `) + * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) +* **Usage:** Run this after making changes to tasks.json to keep individual task files up to date. This command is now manual and no longer runs automatically. + +--- + ## AI-Powered Research ### 25. Research (`research`) @@ -378,11 +402,15 @@ This document provides a detailed reference for interacting with Taskmaster, cov * **Description:** `Perform AI-powered research queries with project context to get fresh, up-to-date information beyond the AI's knowledge cutoff.` * **Key Parameters/Options:** * `query`: `Required. Research query/prompt (e.g., "What are the latest best practices for React Query v5?").` (CLI: `[query]` positional or `-q, --query `) - * `taskIds`: `Comma-separated list of task/subtask IDs for context (e.g., "15,16.2,17").` (CLI: `-i, --id `) + * `taskIds`: `Comma-separated list of task/subtask IDs from the current tag context (e.g., "15,16.2,17").` (CLI: `-i, --id `) * `filePaths`: `Comma-separated list of file paths for context (e.g., "src/api.js,docs/readme.md").` (CLI: `-f, --files `) * `customContext`: `Additional custom context text to include in the research.` (CLI: `-c, --context `) * `includeProjectTree`: `Include project file tree structure in context (default: false).` (CLI: `--tree`) * `detailLevel`: `Detail level for the research response: 'low', 'medium', 'high' (default: medium).` (CLI: `--detail `) + * `saveTo`: `Task or subtask ID (e.g., "15", "15.2") to automatically save the research conversation to.` (CLI: `--save-to `) + * `saveFile`: `If true, saves the research conversation to a markdown file in '.taskmaster/docs/research/'.` (CLI: `--save-file`) + * `noFollowup`: `Disables the interactive follow-up question menu in the CLI.` (CLI: `--no-followup`) + * `tag`: `Specify which tag context to use for task-based context gathering. Defaults to the current active tag.` (CLI: `--tag `) * `projectRoot`: `The directory of the project. Must be an absolute path.` (CLI: Determined automatically) * **Usage:** **This is a POWERFUL tool that agents should use FREQUENTLY** to: * Get fresh information beyond knowledge cutoff dates @@ -406,17 +434,79 @@ This document provides a detailed reference for interacting with Taskmaster, cov --- -## File Management +## Tag Management -### 24. Generate Task Files (`generate`) +This new suite of commands allows you to manage different task contexts (tags). -* **MCP Tool:** `generate` -* **CLI Command:** `task-master generate [options]` -* **Description:** `Create or update individual Markdown files for each task based on your tasks.json.` +### 26. List Tags (`tags`) + +* **MCP Tool:** `list_tags` +* **CLI Command:** `task-master tags [options]` +* **Description:** `List all available tags with task counts, completion status, and other metadata.` * **Key Parameters/Options:** - * `output`: `The directory where Taskmaster should save the task files (default: in a 'tasks' directory).` (CLI: `-o, --output `) - * `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file `) -* **Usage:** Run this after making changes to tasks.json to keep individual task files up to date. + * `--show-metadata`: `Include detailed metadata in the output (e.g., creation date, description).` (CLI: `--show-metadata`) + +### 27. Add Tag (`add_tag`) + +* **MCP Tool:** `add_tag` +* **CLI Command:** `task-master add-tag [options]` +* **Description:** `Create a new, empty tag context, or copy tasks from another tag.` +* **Key Parameters/Options:** + * `tagName`: `Name of the new tag to create (alphanumeric, hyphens, underscores).` (CLI: `` positional) + * `--from-branch`: `Creates a tag with a name derived from the current git branch, ignoring the argument.` (CLI: `--from-branch`) + * `--copy-from-current`: `Copy tasks from the currently active tag to the new tag.` (CLI: `--copy-from-current`) + * `--copy-from `: `Copy tasks from a specific source tag to the new tag.` (CLI: `--copy-from `) + * `--description `: `Provide an optional description for the new tag.` (CLI: `-d, --description `) + +### 28. Delete Tag (`delete_tag`) + +* **MCP Tool:** `delete_tag` +* **CLI Command:** `task-master delete-tag [options]` +* **Description:** `Permanently delete a tag and all of its associated tasks.` +* **Key Parameters/Options:** + * `tagName`: `Name of the tag to delete.` (CLI: `` positional) + * `--yes`: `Skip the confirmation prompt.` (CLI: `-y, --yes`) + +### 29. Use Tag (`use_tag`) + +* **MCP Tool:** `use_tag` +* **CLI Command:** `task-master use-tag ` +* **Description:** `Switch your active task context to a different tag.` +* **Key Parameters/Options:** + * `tagName`: `Name of the tag to switch to.` (CLI: `` positional) + +### 30. Rename Tag (`rename_tag`) + +* **MCP Tool:** `rename_tag` +* **CLI Command:** `task-master rename-tag ` +* **Description:** `Rename an existing tag.` +* **Key Parameters/Options:** + * `oldName`: `The current name of the tag.` (CLI: `` positional) + * `newName`: `The new name for the tag.` (CLI: `` positional) + +### 31. Copy Tag (`copy_tag`) + +* **MCP Tool:** `copy_tag` +* **CLI Command:** `task-master copy-tag [options]` +* **Description:** `Copy an entire tag context, including all its tasks and metadata, to a new tag.` +* **Key Parameters/Options:** + * `sourceName`: `Name of the tag to copy from.` (CLI: `` positional) + * `targetName`: `Name of the new tag to create.` (CLI: `` positional) + * `--description `: `Optional description for the new tag.` (CLI: `-d, --description `) + +--- + +## Miscellaneous + +### 32. Sync Readme (`sync-readme`) -- experimental + +* **MCP Tool:** N/A +* **CLI Command:** `task-master sync-readme [options]` +* **Description:** `Exports your task list to your project's README.md file, useful for showcasing progress.` +* **Key Parameters/Options:** + * `status`: `Filter tasks by status (e.g., 'pending', 'done').` (CLI: `-s, --status `) + * `withSubtasks`: `Include subtasks in the export.` (CLI: `--with-subtasks`) + * `tag`: `Specify which tag context to export from. Defaults to the current active tag.` (CLI: `--tag `) --- diff --git a/.cursor/rules/utilities.mdc b/.cursor/rules/utilities.mdc index 1b0e7e0f..e4f18460 100644 --- a/.cursor/rules/utilities.mdc +++ b/.cursor/rules/utilities.mdc @@ -800,8 +800,7 @@ Refer to [`context_gathering.mdc`](mdc:.cursor/rules/context_gathering.mdc) for // Add tags section if missing if (!config.tags) { config.tags = { - enabledGitworkflow: false, - autoSwitchTagWithBranch: false + // Git integration settings removed - now manual only }; modified = true; } @@ -824,7 +823,6 @@ Refer to [`context_gathering.mdc`](mdc:.cursor/rules/context_gathering.mdc) for const initialState = { currentTag: 'master', lastSwitched: new Date().toISOString(), - branchTagMapping: {}, migrationNoticeShown: false }; diff --git a/.taskmaster/tasks/tasks.json b/.taskmaster/tasks/tasks.json index c0db3b66..ec29f8b6 100644 --- a/.taskmaster/tasks/tasks.json +++ b/.taskmaster/tasks/tasks.json @@ -6592,7 +6592,7 @@ 8 ], "details": "Provide clear instructions and examples for all tag management features, ensuring add-tag command is properly documented with consistent naming.", - "status": "pending", + "status": "done", "testStrategy": "Review documentation for completeness and clarity; user acceptance testing." }, { @@ -6748,7 +6748,7 @@ ], "metadata": { "created": "2025-06-13T02:49:12.129Z", - "updated": "2025-06-13T20:18:22.896Z", + "updated": "2025-06-13T23:34:21.222Z", "description": "Tasks for master context" } }, diff --git a/docs/command-reference.md b/docs/command-reference.md index 610edf4a..f628f647 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -247,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 + +# Create a new tag with a description +task-master add-tag --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 --copy-from-current + +# Create a new tag by copying from a specific tag +task-master add-tag --copy-from= + +# Switch to a different tag context +task-master use-tag + +# Rename an existing tag +task-master rename-tag + +# Copy an entire tag to create a new one +task-master copy-tag + +# Copy a tag with a description +task-master copy-tag --description="Copied for testing" + +# Delete a tag and all its tasks (with confirmation) +task-master delete-tag + +# Delete a tag without confirmation prompt +task-master delete-tag --yes +``` + +**Tag Context:** +- All task operations (list, show, add, update, etc.) work within the currently active tag +- Use `--tag=` 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 @@ -279,7 +329,9 @@ 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 @@ -299,18 +351,34 @@ task-master research "Best practices for error handling" --context="We're using # Research with different detail levels task-master research "React Query v5 migration guide" --detail=high -# Save research results to a file -task-master research "Database optimization techniques" --save=research/db-optimization.md +# 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 tool that provides:** +**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** +- **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:** @@ -319,3 +387,12 @@ task-master research "Database optimization techniques" --save=research/db-optim - 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 diff --git a/docs/configuration.md b/docs/configuration.md index 8e05b7e4..77b5c228 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -44,10 +44,6 @@ Taskmaster uses two primary methods for configuration: "azureBaseURL": "https://your-endpoint.azure.com/", "vertexProjectId": "your-gcp-project-id", "vertexLocation": "us-central1" - }, - "tags": { - "enabledGitworkflow": false, - "autoSwitchTagWithBranch": false } } ``` @@ -86,19 +82,7 @@ Taskmaster uses two primary methods for configuration: ## Tagged Task Lists Configuration (v0.17+) -Taskmaster includes a tagged task lists system for multi-context task management. The following settings control this functionality: - -### Tags Configuration Section - -```json -"tags": { - "enabledGitworkflow": false, - "autoSwitchTagWithBranch": false -} -``` - -- **`enabledGitworkflow`** (boolean): Enable git branch integration features (Part 2 feature) -- **`autoSwitchTagWithBranch`** (boolean): Automatically switch tag context when git branch changes +Taskmaster includes a tagged task lists system for multi-context task management. ### Global Tag Settings @@ -110,6 +94,14 @@ Taskmaster includes a tagged task lists system for multi-context task management - **`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: @@ -118,14 +110,12 @@ Taskmaster uses `.taskmaster/state.json` to track tagged system runtime informat { "currentTag": "master", "lastSwitched": "2025-06-11T20:26:12.598Z", - "branchTagMapping": {}, "migrationNoticeShown": true } ``` - **`currentTag`**: Currently active tag context - **`lastSwitched`**: Timestamp of last tag switch -- **`branchTagMapping`**: Mapping between git branches and tag names - **`migrationNoticeShown`**: Whether migration notice has been displayed This file is automatically created during tagged system migration and should not be manually edited. @@ -133,7 +123,7 @@ This file is automatically created during tagged system migration and should not ## 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 @@ -208,7 +198,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", diff --git a/docs/examples.md b/docs/examples.md index 31c07197..dc6ed603 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -176,3 +176,83 @@ We need to choose between Redis and Memcached for caching. Can you research the ``` (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) diff --git a/docs/tutorial.md b/docs/tutorial.md index bcdb63d6..b8f0c244 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -495,3 +495,96 @@ The agent will: - **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 ` to switch between different work streams +5. **Merge and cleanup**: After merging the branch, optionally delete the tag with `task-master delete-tag ` + +This workflow ensures your task management stays organized and conflicts are minimized when working with teams or multiple features simultaneously.