---
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 <id>               # Provide details for a specific task (from cache)
5.  expand <id>             # 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 <task-id>
./scripts/tm_context.sh get <task-id>
```

> **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='<prd-file.txt>'` (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 <task-id>` 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=<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 <task-id>` 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=<id> --status=done` (see @`taskmaster.mdc`)
-   **CRITICAL**: Update cache after status changes using `./scripts/tm_cache.sh update <task-id>`
-   Update dependent tasks when implementation differs from original plan using `update` / `task-master update --from=<id> --prompt="..."` or `update_task` / `task-master update-task --id=<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 <task-id>
  ```

**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 <task-id>

# 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=<task-id> --force --research
    
    # Verify expansion was successful
    task-master show <task-id>

# 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 <task-id>
# 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=<task-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 <task-id>
  ./scripts/validate_loc.sh
  ./scripts/validate_timestamps.sh
  ./scripts/validate_tests.sh <task-id>
  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 <task-id> --final
  task-master set-status --id=<task-id> --status=done
  ./scripts/tm_cache.sh update <task-id>
  
  # ✅ DO: Update CHANGELOG.md for completed work
  ./scripts/update_changelog.sh <task-id> --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 <task-id>
./scripts/validate_loc.sh                    # Check file size limits
./scripts/validate_timestamps.sh             # Check UTC timestamp compliance
./scripts/validate_tests.sh <task-id>        # 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.*
