--- description: Execution patterns and gate checks for Taskmaster development - loaded by agent_workflow.mdc alwaysApply: false --- # Taskmaster Development Workflow **⚠️ IMPORTANT: This rule is loaded by agent_workflow.mdc for task execution. Do not read directly.** This guide outlines the standard process for using Taskmaster to manage software development projects with strict cache validation. It is written as a set of instructions for you, the AI agent. ## Core Principles - **Default Stance**: For most projects, the user can work directly within the `master` task context. Your initial actions should operate on this default context unless a clear pattern for multi-context work emerges. - **Goal**: Your role is to elevate the user's workflow by intelligently introducing advanced features like **Tagged Task Lists** when you detect the appropriate context. Do not force tags on the user; suggest them as a helpful solution to a specific need. ## Implementation Patterns ### Basic Development Loop The fundamental development cycle you will facilitate is: ```bash # ✅ DO: Follow this sequence 1. list # Show what needs to be done 2. next # Help decide what to work on 3. check context # Validate task context using cache system 4. show # Provide details for a specific task (from cache) 5. expand # Break down complex tasks into subtasks 6. Implement # User writes code and tests 7. update-subtask # Log progress and findings on behalf of user 8. set-status # Mark tasks and subtasks as done 9. update-changelog # Update CHANGELOG.md for completed work 10. Repeat ``` #### Before Starting Any Task **ALWAYS** validate task context before beginning work: ```bash # ✅ DO: Validate before starting ./scripts/tm_context.sh check ./scripts/tm_context.sh get ``` > **Note**: For detailed tool reference information, MCP vs CLI usage strategy, and command examples, see [taskmaster.mdc](mdc:.cursor/rules/taskmaster/taskmaster.mdc). ### Tool Integration Strategy **MCP Tools**: Use for AI-powered operations (see [taskmaster.mdc](mdc:.cursor/rules/taskmaster/taskmaster.mdc) - MCP Usage section) **CLI Commands**: Use for all other operations (see [taskmaster.mdc](mdc:.cursor/rules/taskmaster/taskmaster.mdc) - CLI Usage section) **Cache Operations**: Use utility scripts for context validation and cache management ## Standard Development Workflow Process ### Simple Workflow (Default Starting Point) For new projects or when users are getting started, operate within the `master` tag context: - Start new projects by running `initialize_project` tool / `task-master init` or `parse_prd` / `task-master parse-prd --input=''` (see @`taskmaster.mdc`) to generate initial tasks.json with tagged structure - Configure rule sets during initialization with `--rules` flag (e.g., `task-master init --rules cursor,windsurf`) or manage them later with `task-master rules add/remove` commands - Begin coding sessions with `get_tasks` / `task-master list` (see @`taskmaster.mdc`) to see current tasks, status, and IDs - Determine the next task to work on using `next_task` / `task-master next` (see @`taskmaster.mdc`) - **CRITICAL**: Validate task context using `./scripts/tm_context.sh check ` before starting work - **GATE CHECK 1**: Context validation passed - task context is valid and accessible - - **CRITICAL**: Complete task expansion and complexity analysis BEFORE test design: - - Analyze task complexity with `analyze_project_complexity` / `task-master analyze-complexity --research` (see @`taskmaster.mdc`) - - Review complexity report using `complexity_report` / `task-master complexity-report` (see @`taskmaster.mdc`) - - Expand task if needed: Use `expand_task` / `task-master expand --id= --force --research` (see @`taskmaster.mdc`) with appropriate flags - - Ensure all complex tasks (complexity score 6+) have proper subtask breakdown - - **This step is mandatory** - never proceed to test design without proper task expansion - **GATE CHECK 2**: Task expansion complete - all complex tasks have subtasks, complexity analysis available - - Select tasks based on dependencies (all marked 'done'), priority level, and ID order - View specific task details using `./scripts/tm_cache.sh get ` to understand implementation requirements - **GATE CHECK 3**: Task selection complete - dependencies satisfied, implementation requirements clear - - **Now design tests** with complete task context and subtasks - **GATE CHECK 4**: Test design complete - comprehensive test plan covers all subtasks and edge cases - - Implement code following task details, dependencies, and project standards - **GATE CHECK 5**: Implementation complete - code passes all tests, follows project standards - Mark completed tasks with `set_task_status` / `task-master set-status --id= --status=done` (see @`taskmaster.mdc`) - **CRITICAL**: Update cache after status changes using `./scripts/tm_cache.sh update ` - Update dependent tasks when implementation differs from original plan using `update` / `task-master update --from= --prompt="..."` or `update_task` / `task-master update-task --id= --prompt="..."` (see @`taskmaster.mdc`) --- ### Enhanced Simple Workflow (Strict Quality Enforcement) **When to Use**: For projects requiring strict adherence to TDD, low-LOC, and UTC timestamp rules. #### Enhanced 5-Step Workflow (Strict Enforcement) ##### Step 1: Context & Task Selection ```bash # ✅ DO: Validate context first task-master next ./scripts/tm_context.sh check ``` **GATE CHECK 1**: Context validation passed - task context is valid and accessible ##### Step 2: Task Expansion & Complexity Analysis (REQUIRED BEFORE TEST DESIGN) ```bash # ✅ DO: Ensure task is properly expanded before test design # Check if task has subtasks task-master show # If no subtasks or complexity analysis missing: if task_needs_expansion: # Get project complexity first if missing task-master analyze-complexity --research # Expand task with appropriate flags task-master expand --id= --force --research # Verify expansion was successful task-master show # Ensure all complex tasks (complexity score 6+) have subtasks # **CRITICAL**: This step prevents test design without proper planning # Complex tasks without subtasks lead to incomplete test coverage ``` **GATE CHECK 2**: Task expansion complete - all complex tasks have subtasks, complexity analysis available ##### Step 3: Test Design & Planning (REQUIRED BEFORE CODE) ```bash # ✅ DO: Design tests after task is properly expanded task-master show # Now you have complete task context with subtasks for comprehensive test design ``` **GATE CHECK 3**: Test design complete - comprehensive test plan covers all subtasks and edge cases ##### Step 4: Test Implementation & Validation ```bash # ✅ DO: Write tests first task-master set-status --id= --status=in-progress # Write tests first (REQUIRED) # Implement minimal code to pass tests # Run tests: uv run pytest ``` **GATE CHECK 4**: Test implementation complete - all tests pass, minimal code implemented ##### Step 5: Code Quality & LOC Enforcement ```bash # ✅ DO: Validate quality before progress ./scripts/validate_quality.sh ./scripts/validate_loc.sh ./scripts/validate_timestamps.sh ./scripts/validate_tests.sh uv run black src/ tests/ && uv run ruff check --fix src/ tests/ ``` **GATE CHECK 5**: Code quality validated - all quality checks pass, formatting and linting complete ##### Step 6: Completion & Next Steps ```bash # ✅ DO: Final validation before completion ./scripts/validate_quality.sh --final task-master set-status --id= --status=done ./scripts/tm_cache.sh update # ✅ DO: Update CHANGELOG.md for completed work ./scripts/update_changelog.sh --type=task task-master next ``` **GATE CHECK 6**: Task completion validated - final quality check passed, status updated, cache synced, CHANGELOG.md updated ### Gate Check Validation System **Purpose**: Each gate check serves as a validation point to ensure the workflow is being followed correctly before proceeding to the next step. **How to Use Gate Checks**: ```bash # Before proceeding to next step, verify the current gate check criteria: # GATE CHECK 1: Context validation passed - task context is valid and accessible # GATE CHECK 2: Task expansion complete - all complex tasks have subtasks, complexity analysis available # GATE CHECK 3: Test design complete - comprehensive test plan covers all subtasks and edge cases # GATE CHECK 4: Test implementation complete - all tests pass, minimal code implemented # GATE CHECK 5: Code quality validated - all quality checks pass, formatting and linting complete # GATE CHECK 6: Task completion validated - final quality check passed, status updated, cache synced, CHANGELOG.md updated # If any gate check fails, resolve the issue before proceeding # Use these checks during code reviews and team syncs ``` **Gate Check Enforcement**: - **Mandatory**: Each gate check must pass before proceeding - **Verifiable**: Each check has clear, measurable criteria - **Documentable**: Record gate check status in task updates - **Reviewable**: Use gate checks during code reviews ### Automatic Quality Checks ```bash # ✅ DO: Use comprehensive validation ./scripts/validate_quality.sh ./scripts/validate_loc.sh # Check file size limits ./scripts/validate_timestamps.sh # Check UTC timestamp compliance ./scripts/validate_tests.sh # Check test coverage and passing ./scripts/validate_formatting.sh # Check code formatting and linting ``` ## Leveling Up: Agent-Led Multi-Context Workflows ### When to Introduce Tags: Decision Patterns #### Pattern 1: Simple Git Feature Branching ```bash # ✅ DO: Create tag for feature branches # Trigger: User creates new git branch # Action: Propose creating new tag that mirrors branch name # Tool: task-master add-tag --from-branch ``` #### Pattern 2: Team Collaboration ```bash # ✅ DO: Create separate tag for collaboration # Trigger: User mentions working with teammates # Action: Suggest separate tag to prevent conflicts # Tool: task-master add-tag my-work --copy-from-current ``` #### Pattern 3: Experiments or Risky Refactors ```bash # ✅ DO: Use sandboxed tags for experiments # Trigger: User wants to try something risky # Action: Propose temporary tag for experimental work # Tool: task-master add-tag experiment-name --description="Description" ``` #### Pattern 4: Large Feature Initiatives (PRD-Driven) ```bash # ✅ DO: Use comprehensive PRD workflow # Trigger: User describes large multi-step feature # Action: Propose PRD-driven workflow # Implementation: # 1. Create empty tag: task-master add-tag feature-xyz # 2. Collaborate on PRD creation # 3. Parse PRD: task-master parse-prd prd.txt --tag feature-xyz # 4. Prepare task list: analyze-complexity and expand-all ``` ### Advanced Workflow (Tag-Based & PRD-Driven) #### Master List Strategy (High-Value Focus) ```bash # ✅ DO: Keep master focused on high-value items # High-level deliverables with significant business value # Major milestones and epic-level features # Critical infrastructure work # Release-blocking items # ❌ DON'T: Put detailed implementation in master # Detailed implementation subtasks # Refactoring work # Experimental features # Team member-specific tasks ``` #### PRD-Driven Feature Development **For New Major Features**: ```markdown # ✅ DO: Follow structured approach 1. Identify the Initiative 2. Create Dedicated Tag: add_tag feature-[name] 3. Collaborative PRD Creation 4. Parse & Prepare: parse_prd, analyze_complexity, expand_all 5. Add Master Reference: Create high-level task in master ``` **For Existing Codebase Analysis**: ```markdown # ✅ DO: Research existing codebase 1. Codebase Discovery using research tool 2. Collaborative Assessment 3. Strategic PRD Creation 4. Tag-Based Organization 5. Master List Curation ``` > **Note**: For detailed tool reference information, see [taskmaster.mdc](mdc:.cursor/rules/taskmaster/taskmaster.mdc) - Tool-Specific Reference Information section. ## Performance Guidelines - **Quality Gates**: Enforce TDD, LOC, and UTC compliance - **Progress Logging**: Log comprehensive implementation details - **Rule Updates**: Continuously improve based on new patterns - **Validation Scripts**: Use automatic quality checks - **Documentation Updates**: Automatically update CHANGELOG.md for all completed work ## Rule Loading Information **This rule is automatically loaded by [agent_workflow.mdc](mdc:.cursor/rules/agent_workflow.mdc) for task execution patterns and gate checks.** **For decision-making and workflow guidance, see [agent_workflow.mdc](mdc:.cursor/rules/agent_workflow.mdc).** ## File References - **Tool Reference**: [taskmaster.mdc](mdc:.cursor/rules/taskmaster/taskmaster.mdc) - Complete MCP tools and CLI commands reference - **Decision Making**: [agent_workflow.mdc](mdc:.cursor/rules/agent_workflow.mdc) - Central decision-making hub - **Project Structure**: [project-structure.mdc](mdc:.cursor/rules/project-structure.mdc) - File organization and coding patterns - **Template References**: [rule-templates.mdc](mdc:.cursor/rules/templates/rule-templates.mdc) - **Related Rules**: [tdd.mdc](mdc:.cursor/rules/tests/tdd.mdc), [low-loc.mdc](mdc:.cursor/rules/low-loc.mdc), [utc-timestamps.mdc](mdc:.cursor/rules/utc-timestamps.mdc) --- *This workflow provides a general guideline. Adapt it based on your specific project needs and team practices.*