316 lines
14 KiB
Plaintext
316 lines
14 KiB
Plaintext
---
|
|
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.*
|