489 lines
28 KiB
Plaintext
489 lines
28 KiB
Plaintext
---
|
|
description: Guide for using Taskmaster's tagged task management system in development workflows
|
|
globs: **/*
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Taskmaster Tagged Development Workflow
|
|
|
|
This guide outlines the standard process for using Taskmaster's **tagged task management system** to manage software development projects. This is written as instructions for you, the AI agent.
|
|
|
|
**⚠️ CRITICAL PRINCIPLE: Never Work on Master Tag**
|
|
- **NEVER suggest working directly on the `master` tag** for feature development
|
|
- **ALWAYS guide users to create or switch to appropriate feature tags**
|
|
- The `master` tag is reserved for high-level deliverables and major milestones only
|
|
|
|
- **Your Goal**: Guide users to use the tagged system effectively from the start, creating organized, conflict-free development workflows
|
|
|
|
## The Tagged Development Loop
|
|
The fundamental development cycle you will facilitate is:
|
|
1. **`tags`**: Show available tag contexts and current active tag
|
|
2. **`use-tag <feature-tag>`**: Switch to appropriate feature context (NOT master)
|
|
3. **`list`**: Show tasks in the current tag context
|
|
4. **`next`**: Help the user decide what to work on in current tag
|
|
5. **`show <id>`**: Provide details for a specific task in current tag
|
|
6. **`expand <id>`**: Break down complex tasks within the tag context
|
|
7. **Implement**: The user writes the code and tests
|
|
8. **`update-subtask`**: Log progress and findings within the tag
|
|
9. **`set-status`**: Mark tasks as `done` within the tag context
|
|
10. **Repeat** or switch to another tag context
|
|
|
|
All command executions operate within the current tag context. Always verify the active tag before starting work.
|
|
|
|
---
|
|
|
|
## Standard Development Workflow Process
|
|
|
|
### Standard Tagged Workflow (Always Start Here)
|
|
|
|
For ALL projects, guide users to use the tagged system from the beginning:
|
|
|
|
1. **Initialize with Tags in Mind:**
|
|
- Run `initialize_project` / `task-master init` with appropriate rule sets
|
|
- Immediately create feature tags: `add_tag user-auth --description="Authentication features"`
|
|
- Never parse PRDs directly into master
|
|
|
|
2. **Create Tagged PRDs:**
|
|
```bash
|
|
# Guide users to create context-specific PRDs
|
|
.taskmaster/docs/
|
|
prd-user-authentication.md
|
|
prd-payment-system.md
|
|
prd-mobile-app.md
|
|
```
|
|
|
|
3. **Parse PRDs into Feature Tags:**
|
|
```bash
|
|
task-master use-tag user-auth
|
|
task-master parse-prd .taskmaster/docs/prd-user-authentication.md
|
|
|
|
task-master use-tag payments
|
|
task-master parse-prd .taskmaster/docs/prd-payment-system.md
|
|
```
|
|
|
|
4. **Daily Tagged Workflow:**
|
|
- Check contexts: `list_tags` / `task-master tags --show-metadata`
|
|
- Switch context: `use_tag` / `task-master use-tag <feature-tag>`
|
|
- Work within tag: `next_task` / `task-master next`
|
|
- Analyze complexity: `analyze_project_complexity --research`
|
|
- Expand tasks: `expand_task --id=<id> --research`
|
|
- Log progress: `update_subtask --id=<id> --prompt="..."`
|
|
- Mark complete: `set_task_status --id=<id> --status=done`
|
|
|
|
---
|
|
|
|
## Always Use Tagged Workflows
|
|
|
|
**You must ALWAYS guide users to use tagged workflows from the start.** The tagged system is not an advanced feature - it's the standard way to use Task Master. This prevents conflicts, maintains organization, and scales naturally with project growth.
|
|
|
|
### Standard Tag Creation Patterns
|
|
|
|
Always suggest creating tags for these common scenarios:
|
|
|
|
#### Pattern 1: Feature Development (Most Common)
|
|
This is the standard approach for any new feature.
|
|
|
|
- **Trigger**: User mentions implementing any new feature or functionality
|
|
- **Your Action**: Immediately suggest creating a dedicated tag
|
|
- **Your Suggested Prompt**: *"I'll create a dedicated tag for this feature to keep tasks organized. This is the standard Task Master workflow that prevents conflicts and maintains clean task organization."*
|
|
- **Example Implementation**:
|
|
```bash
|
|
# For authentication feature
|
|
task-master add-tag user-auth --description="User authentication features"
|
|
task-master use-tag user-auth
|
|
# Then create PRD and parse it
|
|
```
|
|
|
|
#### Pattern 2: Git Branch Alignment
|
|
- **Trigger**: User creates a new git branch
|
|
- **Your Action**: Create a corresponding tag to maintain branch-task alignment
|
|
- **Your Suggested Prompt**: *"I'll create a task tag that matches your git branch. This keeps your tasks aligned with your code changes."*
|
|
- **Tool to Use**: `task-master add-tag --from-branch`
|
|
|
|
#### Pattern 3: Team Collaboration
|
|
- **Trigger**: Multiple developers working on the same project
|
|
- **Your Action**: Ensure each developer has their own tag context
|
|
- **Your Suggested Prompt**: *"To prevent conflicts with your team, let's create separate task contexts for each developer's work."*
|
|
- **Example**: `task-master add-tag alice-frontend --description="Alice's frontend tasks"`
|
|
|
|
#### Pattern 4: Experiments or Refactoring
|
|
- **Trigger**: Trying new approaches or major refactoring
|
|
- **Your Action**: Create experimental tags that can be deleted if not needed
|
|
- **Your Suggested Prompt**: *"I'll create an experimental tag for this work. If it doesn't work out, we can simply delete the tag."*
|
|
- **Example**: `task-master add-tag experiment-graphql --description="Testing GraphQL migration"`
|
|
|
|
#### Pattern 5: PRD-Driven Development (Best Practice)
|
|
This is the recommended approach for all significant features.
|
|
|
|
- **Trigger**: Any feature that requires planning
|
|
- **Your Action**: Guide through PRD creation and parsing
|
|
- **Your Implementation Flow**:
|
|
1. **Create feature tag**: `add_tag feature-dashboard --description="Dashboard features"`
|
|
2. **Switch to tag**: `use_tag feature-dashboard`
|
|
3. **Create PRD**: Work with user to create `.taskmaster/docs/prd-dashboard.md`
|
|
4. **Parse PRD**: `parse_prd .taskmaster/docs/prd-dashboard.md`
|
|
5. **Analyze & Expand**: `analyze_project_complexity --research` then `expand_all --research`
|
|
|
|
#### Pattern 5: Version-Based Development
|
|
Tailor your approach based on the project maturity indicated by tag names.
|
|
|
|
- **Prototype/MVP Tags** (`prototype`, `mvp`, `poc`, `v0.x`):
|
|
- **Your Approach**: Focus on speed and functionality over perfection
|
|
- **Task Generation**: Create tasks that emphasize "get it working" over "get it perfect"
|
|
- **Complexity Level**: Lower complexity, fewer subtasks, more direct implementation paths
|
|
- **Research Prompts**: Include context like "This is a prototype - prioritize speed and basic functionality over optimization"
|
|
- **Example Prompt Addition**: *"Since this is for the MVP, I'll focus on tasks that get core functionality working quickly rather than over-engineering."*
|
|
|
|
- **Production/Mature Tags** (`v1.0+`, `production`, `stable`):
|
|
- **Your Approach**: Emphasize robustness, testing, and maintainability
|
|
- **Task Generation**: Include comprehensive error handling, testing, documentation, and optimization
|
|
- **Complexity Level**: Higher complexity, more detailed subtasks, thorough implementation paths
|
|
- **Research Prompts**: Include context like "This is for production - prioritize reliability, performance, and maintainability"
|
|
- **Example Prompt Addition**: *"Since this is for production, I'll ensure tasks include proper error handling, testing, and documentation."*
|
|
|
|
### The Master Tag Strategy
|
|
|
|
**Remember**: The `master` tag is NOT for daily development work. Guide users to understand what belongs there:
|
|
|
|
#### What Goes in Master Tag:
|
|
- **High-level deliverables** that provide significant business value
|
|
- **Major milestones** and epic-level features
|
|
- **Critical infrastructure** work affecting the entire project
|
|
- **Release-blocking** items
|
|
- **References to feature tags** (e.g., "Complete user authentication - see user-auth tag")
|
|
|
|
#### What NEVER Goes in Master:
|
|
- **Feature implementation tasks** (use feature-specific tags)
|
|
- **Bug fixes** (use `bugfix-*` tags)
|
|
- **Refactoring work** (use `refactor-*` tags)
|
|
- **Experimental features** (use `experiment-*` tags)
|
|
- **Individual developer tasks** (use person-specific tags)
|
|
|
|
#### PRD-Driven Feature Development
|
|
|
|
**For New Major Features**:
|
|
1. **Identify the Initiative**: When user describes a significant feature
|
|
2. **Create Dedicated Tag**: `add_tag feature-[name] --description="[Feature description]"`
|
|
3. **Collaborative PRD Creation**: Work with user to create comprehensive PRD in `.taskmaster/docs/feature-[name]-prd.txt`
|
|
4. **Parse & Prepare**:
|
|
- `parse_prd .taskmaster/docs/feature-[name]-prd.txt --tag=feature-[name]`
|
|
- `analyze_project_complexity --tag=feature-[name] --research`
|
|
- `expand_all --tag=feature-[name] --research`
|
|
5. **Add Master Reference**: Create a high-level task in `master` that references the feature tag
|
|
|
|
**For Existing Codebase Analysis**:
|
|
When users initialize Taskmaster on existing projects:
|
|
1. **Codebase Discovery**: Use your native tools for producing deep context about the code base. You may use `research` tool with `--tree` and `--files` to collect up to date information using the existing architecture as context.
|
|
2. **Collaborative Assessment**: Work with user to identify improvement areas, technical debt, or new features
|
|
3. **Strategic PRD Creation**: Co-author PRDs that include:
|
|
- Current state analysis (based on your codebase research)
|
|
- Proposed improvements or new features
|
|
- Implementation strategy considering existing code
|
|
4. **Tag-Based Organization**: Parse PRDs into appropriate tags (`refactor-api`, `feature-dashboard`, `tech-debt`, etc.)
|
|
5. **Master List Curation**: Keep only the most valuable initiatives in master
|
|
|
|
The parse-prd's `--append` flag enables the user to parse multple PRDs within tags or across tags. PRDs should be focused and the number of tasks they are parsed into should be strategically chosen relative to the PRD's complexity and level of detail.
|
|
|
|
### Common Workflow Examples
|
|
|
|
**Example 1: Starting a New Feature**
|
|
```
|
|
User: "I need to add user authentication"
|
|
Your Response: "I'll set up a dedicated tag for the authentication feature following Task Master's standard workflow."
|
|
Actions:
|
|
1. add_tag user-auth --description="User authentication features"
|
|
2. use_tag user-auth
|
|
3. "Let's create a PRD for this feature in .taskmaster/docs/prd-user-authentication.md"
|
|
4. parse_prd .taskmaster/docs/prd-user-authentication.md
|
|
```
|
|
|
|
**Example 2: Cross-Tag Development**
|
|
```
|
|
User: "The mobile app needs to use the authentication APIs"
|
|
Your Response: "Let me check the auth implementation status and coordinate between tags."
|
|
Actions:
|
|
1. use_tag user-auth
|
|
2. get_task 2 # Check auth API status
|
|
3. use_tag mobile
|
|
4. update_subtask --id=3.1 --prompt="Auth APIs completed in user-auth tag, ready for integration"
|
|
```
|
|
|
|
**Example 3: Managing Multiple Contexts**
|
|
```
|
|
User: "I'm working on both payments and user profiles"
|
|
Your Response: "Let's organize these into separate contexts so you can switch between them cleanly."
|
|
Actions:
|
|
1. tags --show-metadata # Show current contexts
|
|
2. add_tag payments --description="Payment system implementation"
|
|
3. add_tag user-profiles --description="User profile features"
|
|
4. "You can now switch between contexts with 'use-tag payments' or 'use-tag user-profiles'"
|
|
```
|
|
|
|
---
|
|
|
|
## Primary Interaction: MCP Server vs. CLI
|
|
|
|
Taskmaster offers two primary ways to interact:
|
|
|
|
1. **MCP Server (Recommended for Integrated Tools)**:
|
|
- For AI agents and integrated development environments (like Cursor), interacting via the **MCP server is the preferred method**.
|
|
- The MCP server exposes Taskmaster functionality through a set of tools (e.g., `get_tasks`, `add_subtask`).
|
|
- This method offers better performance, structured data exchange, and richer error handling compared to CLI parsing.
|
|
- Refer to @`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`.
|
|
- **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change.
|
|
- **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.
|
|
- It can also serve as a fallback if the MCP server is inaccessible or a specific function isn't exposed via MCP.
|
|
- Install globally with `npm install -g task-master-ai` or use locally via `npx task-master-ai ...`.
|
|
- The CLI commands often mirror the MCP tools (e.g., `task-master list` corresponds to `get_tasks`).
|
|
- Refer to @`taskmaster.mdc` for a detailed command reference.
|
|
- **Tagged Task Lists**: CLI fully supports the new tagged system with seamless migration.
|
|
|
|
## Critical Tagged System Principles
|
|
|
|
### For Your Implementation:
|
|
- **Task Independence**: Each tag has its own task numbering starting from 1
|
|
- **Context Isolation**: Changes in one tag never affect another tag
|
|
- **No Cross-Tag Dependencies**: Dependencies only work within the same tag
|
|
- **Always Verify Context**: Check active tag before any operation with `tags`
|
|
- **Manual Tag Switching**: Never assume tag context, always explicitly switch
|
|
|
|
### Key Commands to Use Frequently:
|
|
- `list_tags` - Show all tags with current context marked
|
|
- `use_tag <name>` - Switch to specific tag context
|
|
- `add_tag <name> --description="..."` - Create new contexts
|
|
- `parse_prd <file>` - Always parse into current tag, not master
|
|
|
|
### File Organization:
|
|
```
|
|
.taskmaster/
|
|
├── tasks/
|
|
│ └── tasks.json # Contains ALL tag contexts
|
|
├── docs/
|
|
│ ├── prd-master.md # High-level only
|
|
│ ├── prd-user-auth.md # Feature PRDs
|
|
│ └── prd-payments.md # Feature PRDs
|
|
└── state.json # Current tag context
|
|
|
|
---
|
|
|
|
## Task Complexity Analysis
|
|
|
|
- Run `analyze_project_complexity` / `task-master analyze-complexity --research` (see @`taskmaster.mdc`) for comprehensive analysis
|
|
- Review complexity report via `complexity_report` / `task-master complexity-report` (see @`taskmaster.mdc`) for a formatted, readable version.
|
|
- Focus on tasks with highest complexity scores (8-10) for detailed breakdown
|
|
- Use analysis results to determine appropriate subtask allocation
|
|
- Note that reports are automatically used by the `expand_task` tool/command
|
|
|
|
## Task Breakdown Process
|
|
|
|
- Use `expand_task` / `task-master expand --id=<id>`. It automatically uses the complexity report if found, otherwise generates default number of subtasks.
|
|
- Use `--num=<number>` to specify an explicit number of subtasks, overriding defaults or complexity report recommendations.
|
|
- Add `--research` flag to leverage Perplexity AI for research-backed expansion.
|
|
- Add `--force` flag to clear existing subtasks before generating new ones (default is to append).
|
|
- Use `--prompt="<context>"` to provide additional context when needed.
|
|
- Review and adjust generated subtasks as necessary.
|
|
- Use `expand_all` tool or `task-master expand --all` to expand multiple pending tasks at once, respecting flags like `--force` and `--research`.
|
|
- If subtasks need complete replacement (regardless of the `--force` flag on `expand`), clear them first with `clear_subtasks` / `task-master clear-subtasks --id=<id>`.
|
|
|
|
## Implementation Drift Handling
|
|
|
|
- When implementation differs significantly from planned approach
|
|
- When future tasks need modification due to current implementation choices
|
|
- When new dependencies or requirements emerge
|
|
- Use `update` / `task-master update --from=<futureTaskId> --prompt='<explanation>\nUpdate context...' --research` to update multiple future tasks.
|
|
- Use `update_task` / `task-master update-task --id=<taskId> --prompt='<explanation>\nUpdate context...' --research` to update a single specific task.
|
|
|
|
## Task Status Management
|
|
|
|
- Use 'pending' for tasks ready to be worked on
|
|
- Use 'done' for completed and verified tasks
|
|
- Use 'deferred' for postponed tasks
|
|
- Add custom status values as needed for project-specific workflows
|
|
|
|
## Task Structure Fields
|
|
|
|
- **id**: Unique identifier for the task (Example: `1`, `1.1`)
|
|
- **title**: Brief, descriptive title (Example: `"Initialize Repo"`)
|
|
- **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`)
|
|
- **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
|
|
- **dependencies**: IDs of prerequisite tasks (Example: `[1, 2.1]`)
|
|
- Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
|
|
- This helps quickly identify which prerequisite tasks are blocking work
|
|
- **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`)
|
|
- **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
|
|
- **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
|
|
- **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
|
|
- Refer to task structure details (previously linked to `tasks.mdc`).
|
|
|
|
## Configuration Management (Updated)
|
|
|
|
Taskmaster configuration is managed through two main mechanisms:
|
|
|
|
1. **`.taskmaster/config.json` File (Primary):**
|
|
* Located in the project root directory.
|
|
* Stores most configuration settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default subtasks/priority, project name, etc.
|
|
* **Tagged System Settings**: Includes `global.defaultTag` (defaults to "master") and `tags` section for tag management configuration.
|
|
* **Managed via `task-master models --setup` command.** Do not edit manually unless you know what you are doing.
|
|
* **View/Set specific models via `task-master models` command or `models` MCP tool.**
|
|
* Created automatically when you run `task-master models --setup` for the first time or during tagged system migration.
|
|
|
|
2. **Environment Variables (`.env` / `mcp.json`):**
|
|
* Used **only** for sensitive API keys and specific endpoint URLs.
|
|
* Place API keys (one per provider) in a `.env` file in the project root for CLI usage.
|
|
* For MCP/Cursor integration, configure these keys in the `env` section of `.cursor/mcp.json`.
|
|
* 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 and migration status.
|
|
* Automatically created during tagged system migration.
|
|
* 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`.
|
|
**If AI commands FAIL in CLI** verify that the API key for the selected provider is present in the `.env` file in the root of the project.
|
|
|
|
## Rules Management
|
|
|
|
Taskmaster supports multiple AI coding assistant rule sets that can be configured during project initialization or managed afterward:
|
|
|
|
- **Available Profiles**: Claude Code, Cline, Codex, Cursor, Roo Code, Trae, Windsurf (claude, cline, codex, cursor, roo, trae, windsurf)
|
|
- **During Initialization**: Use `task-master init --rules cursor,windsurf` to specify which rule sets to include
|
|
- **After Initialization**: Use `task-master rules add <profiles>` or `task-master rules remove <profiles>` to manage rule sets
|
|
- **Interactive Setup**: Use `task-master rules setup` to launch an interactive prompt for selecting rule profiles
|
|
- **Default Behavior**: If no `--rules` flag is specified during initialization, all available rule profiles are included
|
|
- **Rule Structure**: Each profile creates its own directory (e.g., `.cursor/rules`, `.roo/rules`) with appropriate configuration files
|
|
|
|
## Determining the Next Task
|
|
|
|
- Run `next_task` / `task-master next` to show the next task to work on.
|
|
- The command identifies tasks with all dependencies satisfied
|
|
- Tasks are prioritized by priority level, dependency count, and ID
|
|
- The command shows comprehensive task information including:
|
|
- Basic task details and description
|
|
- Implementation details
|
|
- Subtasks (if they exist)
|
|
- Contextual suggested actions
|
|
- Recommended before starting any new development work
|
|
- Respects your project's dependency structure
|
|
- Ensures tasks are completed in the appropriate sequence
|
|
- Provides ready-to-use commands for common task actions
|
|
|
|
## Viewing Specific Task Details
|
|
|
|
- Run `get_task` / `task-master show <id>` to view a specific task.
|
|
- Use dot notation for subtasks: `task-master show 1.2` (shows subtask 2 of task 1)
|
|
- Displays comprehensive information similar to the next command, but for a specific task
|
|
- For parent tasks, shows all subtasks and their current status
|
|
- For subtasks, shows parent task information and relationship
|
|
- Provides contextual suggested actions appropriate for the specific task
|
|
- Useful for examining task details before implementation or checking status
|
|
|
|
## Managing Task Dependencies
|
|
|
|
- Use `add_dependency` / `task-master add-dependency --id=<id> --depends-on=<id>` to add a dependency.
|
|
- Use `remove_dependency` / `task-master remove-dependency --id=<id> --depends-on=<id>` to remove a dependency.
|
|
- The system prevents circular dependencies and duplicate dependency entries
|
|
- Dependencies are checked for existence before being added or removed
|
|
- Task files are automatically regenerated after dependency changes
|
|
- Dependencies are visualized with status indicators in task listings and files
|
|
|
|
## Task Reorganization
|
|
|
|
- Use `move_task` / `task-master move --from=<id> --to=<id>` to move tasks or subtasks within the hierarchy
|
|
- This command supports several use cases:
|
|
- Moving a standalone task to become a subtask (e.g., `--from=5 --to=7`)
|
|
- Moving a subtask to become a standalone task (e.g., `--from=5.2 --to=7`)
|
|
- Moving a subtask to a different parent (e.g., `--from=5.2 --to=7.3`)
|
|
- Reordering subtasks within the same parent (e.g., `--from=5.2 --to=5.4`)
|
|
- Moving a task to a new, non-existent ID position (e.g., `--from=5 --to=25`)
|
|
- Moving multiple tasks at once using comma-separated IDs (e.g., `--from=10,11,12 --to=16,17,18`)
|
|
- The system includes validation to prevent data loss:
|
|
- Allows moving to non-existent IDs by creating placeholder tasks
|
|
- Prevents moving to existing task IDs that have content (to avoid overwriting)
|
|
- Validates source tasks exist before attempting to move them
|
|
- The system maintains proper parent-child relationships and dependency integrity
|
|
- Task files are automatically regenerated after the move operation
|
|
- This provides greater flexibility in organizing and refining your task structure as project understanding evolves
|
|
- This is especially useful when dealing with potential merge conflicts arising from teams creating tasks on separate branches. Solve these conflicts very easily by moving your tasks and keeping theirs.
|
|
|
|
## Iterative Subtask Implementation
|
|
|
|
Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation:
|
|
|
|
1. **Understand the Goal (Preparation):**
|
|
* Use `get_task` / `task-master show <subtaskId>` (see @`taskmaster.mdc`) to thoroughly understand the specific goals and requirements of the subtask.
|
|
|
|
2. **Initial Exploration & Planning (Iteration 1):**
|
|
* This is the first attempt at creating a concrete implementation plan.
|
|
* Explore the codebase to identify the precise files, functions, and even specific lines of code that will need modification.
|
|
* Determine the intended code changes (diffs) and their locations.
|
|
* Gather *all* relevant details from this exploration phase.
|
|
|
|
3. **Log the Plan:**
|
|
* Run `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<detailed plan>'`.
|
|
* Provide the *complete and detailed* findings from the exploration phase in the prompt. Include file paths, line numbers, proposed diffs, reasoning, and any potential challenges identified. Do not omit details. The goal is to create a rich, timestamped log within the subtask's `details`.
|
|
|
|
4. **Verify the Plan:**
|
|
* Run `get_task` / `task-master show <subtaskId>` again to confirm that the detailed implementation plan has been successfully appended to the subtask's details.
|
|
|
|
5. **Begin Implementation:**
|
|
* Set the subtask status using `set_task_status` / `task-master set-status --id=<subtaskId> --status=in-progress`.
|
|
* Start coding based on the logged plan.
|
|
|
|
6. **Refine and Log Progress (Iteration 2+):**
|
|
* As implementation progresses, you will encounter challenges, discover nuances, or confirm successful approaches.
|
|
* **Before appending new information**: Briefly review the *existing* details logged in the subtask (using `get_task` or recalling from context) to ensure the update adds fresh insights and avoids redundancy.
|
|
* **Regularly** use `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<update details>\n- What worked...\n- What didn't work...'` to append new findings.
|
|
* **Crucially, log:**
|
|
* What worked ("fundamental truths" discovered).
|
|
* What didn't work and why (to avoid repeating mistakes).
|
|
* Specific code snippets or configurations that were successful.
|
|
* Decisions made, especially if confirmed with user input.
|
|
* Any deviations from the initial plan and the reasoning.
|
|
* The objective is to continuously enrich the subtask's details, creating a log of the implementation journey that helps the AI (and human developers) learn, adapt, and avoid repeating errors.
|
|
|
|
7. **Review & Update Rules (Post-Implementation):**
|
|
* Once the implementation for the subtask is functionally complete, review all code changes and the relevant chat history.
|
|
* Identify any new or modified code patterns, conventions, or best practices established during the implementation.
|
|
* Create new or update existing rules following internal guidelines (previously linked to `cursor-rules.mdc` and `self-improve.mdc`).
|
|
|
|
8. **Mark Task Complete:**
|
|
* After verifying the implementation and updating any necessary rules, mark the subtask as completed: `set_task_status` / `task-master set-status --id=<subtaskId> --status=done`.
|
|
|
|
9. **Commit Changes (If using Git):**
|
|
* Stage the relevant code changes and any updated/new rule files (`git add .`).
|
|
* Craft a comprehensive Git commit message summarizing the work done for the subtask, including both code implementation and any rule adjustments.
|
|
* Execute the commit command directly in the terminal (e.g., `git commit -m 'feat(module): Implement feature X for subtask <subtaskId>\n\n- Details about changes...\n- Updated rule Y for pattern Z'`).
|
|
* Consider if a Changeset is needed according to internal versioning guidelines (previously linked to `changeset.mdc`). If so, run `npm run changeset`, stage the generated file, and amend the commit or create a new one.
|
|
|
|
10. **Proceed to Next Subtask:**
|
|
* Identify the next subtask (e.g., using `next_task` / `task-master next`).
|
|
|
|
## Code Analysis & Refactoring Techniques
|
|
|
|
- **Top-Level Function Search**:
|
|
- Useful for understanding module structure or planning refactors.
|
|
- Use grep/ripgrep to find exported functions/constants:
|
|
`rg "export (async function|function|const) \w+"` or similar patterns.
|
|
- Can help compare functions between files during migrations or identify potential naming conflicts.
|
|
|
|
### Cross-Tag Coordination
|
|
|
|
When features need to interact:
|
|
1. **Document Dependencies**: Use `update_subtask` to note cross-tag dependencies
|
|
2. **Track Integration Points**: Create tasks that reference other tags
|
|
3. **Coordinate Merging**: Plan how features will integrate back to production
|
|
|
|
Example:
|
|
```bash
|
|
# In mobile tag, documenting auth dependency
|
|
update_subtask --id=3.2 --prompt="Depends on user-auth tag task 2 (OAuth setup) being completed"
|
|
```
|
|
|
|
---
|
|
|
|
**Remember**: The tagged system is not optional or advanced - it's the standard way to use Task Master. Always guide users to work within appropriate tag contexts, never directly on master. |