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
This commit is contained in:
Eyal Toledano
@@ -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.
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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 <name>`
|
||||
# - Simple, predictable workflow without automatic behavior
|
||||
```
|
||||
|
||||
### **Code Conflicts**
|
||||
@@ -391,10 +391,10 @@ task-master update-task --id=<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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 <name>` 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>`)
|
||||
* `status`: `Show only Taskmaster tasks matching this status (or multiple statuses, comma-separated), e.g., 'pending' or 'done,in-progress'.` (CLI: `-s, --status <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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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>`)
|
||||
* `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 <id>`)
|
||||
* `tag`: `Specify which tag context to get the task(s) from. Defaults to the current active tag.` (CLI: `--tag <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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>`)
|
||||
* `id`: `Required. The specific ID of the Taskmaster task, e.g., '15', you want to update.` (CLI: `-i, --id <id>`)
|
||||
* `prompt`: `Required. Explain the specific changes or provide the new information Taskmaster should incorporate into this task.` (CLI: `-p, --prompt <text>`)
|
||||
* `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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <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 <text>`)
|
||||
* `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 <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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <text>`)
|
||||
* `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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <text>`)
|
||||
* `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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <file>`)
|
||||
* `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 <file>`)
|
||||
* `threshold`: `The minimum complexity score (1-10) that should trigger a recommendation to expand a task.` (CLI: `-t, --threshold <number>`)
|
||||
* `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 <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <directory>`)
|
||||
* `tag`: `Specify which tag context to generate files for. Defaults to the current active tag.` (CLI: `--tag <name>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <text>`)
|
||||
* `taskIds`: `Comma-separated list of task/subtask IDs for context (e.g., "15,16.2,17").` (CLI: `-i, --id <ids>`)
|
||||
* `taskIds`: `Comma-separated list of task/subtask IDs from the current tag context (e.g., "15,16.2,17").` (CLI: `-i, --id <ids>`)
|
||||
* `filePaths`: `Comma-separated list of file paths for context (e.g., "src/api.js,docs/readme.md").` (CLI: `-f, --files <paths>`)
|
||||
* `customContext`: `Additional custom context text to include in the research.` (CLI: `-c, --context <text>`)
|
||||
* `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 <level>`)
|
||||
* `saveTo`: `Task or subtask ID (e.g., "15", "15.2") to automatically save the research conversation to.` (CLI: `--save-to <id>`)
|
||||
* `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 <name>`)
|
||||
* `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 <directory>`)
|
||||
* `file`: `Path to your Taskmaster 'tasks.json' file. Default relies on auto-detection.` (CLI: `-f, --file <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 <tagName> [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: `<tagName>` positional)
|
||||
* `--from-branch`: `Creates a tag with a name derived from the current git branch, ignoring the <tagName> argument.` (CLI: `--from-branch`)
|
||||
* `--copy-from-current`: `Copy tasks from the currently active tag to the new tag.` (CLI: `--copy-from-current`)
|
||||
* `--copy-from <tag>`: `Copy tasks from a specific source tag to the new tag.` (CLI: `--copy-from <tag>`)
|
||||
* `--description <text>`: `Provide an optional description for the new tag.` (CLI: `-d, --description <text>`)
|
||||
|
||||
### 28. Delete Tag (`delete_tag`)
|
||||
|
||||
* **MCP Tool:** `delete_tag`
|
||||
* **CLI Command:** `task-master delete-tag <tagName> [options]`
|
||||
* **Description:** `Permanently delete a tag and all of its associated tasks.`
|
||||
* **Key Parameters/Options:**
|
||||
* `tagName`: `Name of the tag to delete.` (CLI: `<tagName>` positional)
|
||||
* `--yes`: `Skip the confirmation prompt.` (CLI: `-y, --yes`)
|
||||
|
||||
### 29. Use Tag (`use_tag`)
|
||||
|
||||
* **MCP Tool:** `use_tag`
|
||||
* **CLI Command:** `task-master use-tag <tagName>`
|
||||
* **Description:** `Switch your active task context to a different tag.`
|
||||
* **Key Parameters/Options:**
|
||||
* `tagName`: `Name of the tag to switch to.` (CLI: `<tagName>` positional)
|
||||
|
||||
### 30. Rename Tag (`rename_tag`)
|
||||
|
||||
* **MCP Tool:** `rename_tag`
|
||||
* **CLI Command:** `task-master rename-tag <oldName> <newName>`
|
||||
* **Description:** `Rename an existing tag.`
|
||||
* **Key Parameters/Options:**
|
||||
* `oldName`: `The current name of the tag.` (CLI: `<oldName>` positional)
|
||||
* `newName`: `The new name for the tag.` (CLI: `<newName>` positional)
|
||||
|
||||
### 31. Copy Tag (`copy_tag`)
|
||||
|
||||
* **MCP Tool:** `copy_tag`
|
||||
* **CLI Command:** `task-master copy-tag <sourceName> <targetName> [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: `<sourceName>` positional)
|
||||
* `targetName`: `Name of the new tag to create.` (CLI: `<targetName>` positional)
|
||||
* `--description <text>`: `Optional description for the new tag.` (CLI: `-d, --description <text>`)
|
||||
|
||||
---
|
||||
|
||||
## 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 <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 <name>`)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
};
|
||||
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
},
|
||||
|
||||
@@ -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 <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
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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 <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