Cursor rule

1---
2description: 
3globs: 
4alwaysApply: false
5---
6- **Global CLI Commands**
7  - Task Master now provides a global CLI through the `task-manager` command
8  - All functionality from `scripts/dev.js` is available through this interface
9  - Install globally with `npm install -g claude-task-manager` or use locally via `npx`
10  - Use `task-manager <command>` instead of `node scripts/dev.js <command>`
11  - Examples:
12    - `task-manager list` instead of `node scripts/dev.js list`
13    - `task-manager next` instead of `node scripts/dev.js next`
14    - `task-manager expand --id=3` instead of `node scripts/dev.js expand --id=3`
15  - All commands accept the same options as their script equivalents
16  - The CLI provides additional commands like `task-manager init` for project setup
17 
18- **Development Workflow Process**
19  - Start new projects by running `task-manager init` or `node scripts/dev.js parse-prd --input=<prd-file.txt>` to generate initial tasks.json
20  - Begin coding sessions with `task-manager list` to see current tasks, status, and IDs
21  - Analyze task complexity with `task-manager analyze-complexity --research` before breaking down tasks
22  - Select tasks based on dependencies (all marked 'done'), priority level, and ID order
23  - Clarify tasks by checking task files in tasks/ directory or asking for user input
24  - View specific task details using `task-manager show <id>` to understand implementation requirements
25  - Break down complex tasks using `task-manager expand --id=<id>` with appropriate flags
26  - Clear existing subtasks if needed using `task-manager clear-subtasks --id=<id>` before regenerating
27  - Implement code following task details, dependencies, and project standards
28  - Verify tasks according to test strategies before marking as complete
29  - Mark completed tasks with `task-manager set-status --id=<id> --status=done`
30  - Update dependent tasks when implementation differs from original plan
31  - Generate task files with `task-manager generate` after updating tasks.json
32  - Maintain valid dependency structure with `task-manager fix-dependencies` when needed
33  - Respect dependency chains and task priorities when selecting work
34  - Report progress regularly using the list command
35 
36- **Task Complexity Analysis**
37  - Run `node scripts/dev.js analyze-complexity --research` for comprehensive analysis
38  - Review complexity report in scripts/task-complexity-report.json
39  - Or use `node scripts/dev.js complexity-report` for a formatted, readable version of the report
40  - Focus on tasks with highest complexity scores (8-10) for detailed breakdown
41  - Use analysis results to determine appropriate subtask allocation
42  - Note that reports are automatically used by the expand command
43 
44- **Task Breakdown Process**
45  - For tasks with complexity analysis, use `node scripts/dev.js expand --id=<id>`
46  - Otherwise use `node scripts/dev.js expand --id=<id> --subtasks=<number>`
47  - Add `--research` flag to leverage Perplexity AI for research-backed expansion
48  - Use `--prompt="<context>"` to provide additional context when needed
49  - Review and adjust generated subtasks as necessary
50  - Use `--all` flag to expand multiple pending tasks at once
51  - If subtasks need regeneration, clear them first with `clear-subtasks` command
52 
53- **Implementation Drift Handling**
54  - When implementation differs significantly from planned approach
55  - When future tasks need modification due to current implementation choices
56  - When new dependencies or requirements emerge
57  - Call `node scripts/dev.js update --from=<futureTaskId> --prompt="<explanation>"` to update tasks.json
58 
59- **Task Status Management**
60  - Use 'pending' for tasks ready to be worked on
61  - Use 'done' for completed and verified tasks
62  - Use 'deferred' for postponed tasks
63  - Add custom status values as needed for project-specific workflows
64 
65- **Task File Format Reference**
66```
67  # Task ID: <id>
68  # Title: <title>
69  # Status: <status>
70  # Dependencies: <comma-separated list of dependency IDs>
71  # Priority: <priority>
72  # Description: <brief description>
73  # Details:
74  <detailed implementation notes>
75 
76  # Test Strategy:
77  <verification approach>
78```
79 
80- **Command Reference: parse-prd**
81  - Legacy Syntax: `node scripts/dev.js parse-prd --input=<prd-file.txt>`
82  - CLI Syntax: `task-manager parse-prd --input=<prd-file.txt>`
83  - Description: Parses a PRD document and generates a tasks.json file with structured tasks
84  - Parameters:
85    - `--input=<file>`: Path to the PRD text file (default: sample-prd.txt)
86    - `--num-tasks=<number>`: Number of tasks to generate (if not specified, AI will determine based on complexity)
87    - `--knowledge-base=<path>, -k`: Path to business knowledge documents to use as context
88  - Example: `task-manager parse-prd --input=requirements.txt`
89  - Notes: Will overwrite existing tasks.json file. Use with caution.
90 
91- **Command Reference: update**
92  - Legacy Syntax: `node scripts/dev.js update --from=<id> --prompt="<prompt>"`
93  - CLI Syntax: `task-manager update --from=<id> --prompt="<prompt>"`
94  - Description: Updates tasks with ID >= specified ID based on the provided prompt
95  - Parameters:
96    - `--from=<id>`: Task ID from which to start updating (required)
97    - `--prompt="<text>"`: Explanation of changes or new context (required)
98  - Example: `task-manager update --from=4 --prompt="Now we are using Express instead of Fastify."`
99  - Notes: Only updates tasks not marked as 'done'. Completed tasks remain unchanged.
100 
101- **Command Reference: generate**
102  - Legacy Syntax: `node scripts/dev.js generate`
103  - CLI Syntax: `task-manager generate`
104  - Description: Generates individual task files in tasks/ directory based on tasks.json
105  - Parameters:
106    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
107    - `--output=<dir>, -o`: Output directory (default: 'tasks')
108  - Example: `task-manager generate`
109  - Notes: Overwrites existing task files. Creates tasks/ directory if needed.
110 
111- **Command Reference: set-status**
112  - Legacy Syntax: `node scripts/dev.js set-status --id=<id> --status=<status>`
113  - CLI Syntax: `task-manager set-status --id=<id> --status=<status>`
114  - Description: Updates the status of a specific task in tasks.json
115  - Parameters:
116    - `--id=<id>`: ID of the task to update (required)
117    - `--status=<status>`: New status value (required)
118  - Example: `task-manager set-status --id=3 --status=done`
119  - Notes: Common values are 'done', 'pending', and 'deferred', but any string is accepted.
120 
121- **Command Reference: list**
122  - Legacy Syntax: `node scripts/dev.js list`
123  - CLI Syntax: `task-manager list`
124  - Description: Lists all tasks in tasks.json with IDs, titles, and status
125  - Parameters:
126    - `--status=<status>, -s`: Filter by status
127    - `--with-subtasks`: Show subtasks for each task
128    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
129  - Example: `task-manager list`
130  - Notes: Provides quick overview of project progress. Use at start of sessions.
131 
132- **Command Reference: expand**
133  - Legacy Syntax: `node scripts/dev.js expand --id=<id> [--num=<number>] [--research] [--prompt="<context>"]`
134  - CLI Syntax: `task-manager expand --id=<id> [--num=<number>] [--research] [--prompt="<context>"]`
135  - Description: Expands a task with subtasks for detailed implementation
136  - Parameters:
137    - `--id=<id>`: ID of task to expand (required unless using --all)
138    - `--all`: Expand all pending tasks, prioritized by complexity
139    - `--num=<number>`: Number of subtasks to generate (if not specified, AI will determine based on task complexity)
140    - `--research`: Use Perplexity AI for research-backed generation
141    - `--prompt="<text>"`: Additional context for subtask generation
142    - `--force`: Regenerate subtasks even for tasks that already have them
143    - `--knowledge-base=<path>, -k`: Path to business knowledge documents to use as context
144  - Example: `task-manager expand --id=3 --num=5 --research --prompt="Focus on security aspects"`
145  - Notes: Uses complexity report recommendations if available. If no subtask count is specified, AI will analyze task complexity and determine the optimal number of subtasks.
146 
147- **Command Reference: analyze-complexity**
148  - Legacy Syntax: `node scripts/dev.js analyze-complexity [options]`
149  - CLI Syntax: `task-manager analyze-complexity [options]`
150  - Description: Analyzes task complexity and generates expansion recommendations
151  - Parameters:
152    - `--output=<file>, -o`: Output file path (default: scripts/task-complexity-report.json)
153    - `--model=<model>, -m`: Override LLM model to use
154    - `--threshold=<number>, -t`: Minimum score for expansion recommendation (default: 5)
155    - `--file=<path>, -f`: Use alternative tasks.json file
156    - `--research, -r`: Use Perplexity AI for research-backed analysis
157  - Example: `task-manager analyze-complexity --research`
158  - Notes: Report includes complexity scores, recommended subtasks, and tailored prompts.
159 
160- **Command Reference: clear-subtasks**
161  - Legacy Syntax: `node scripts/dev.js clear-subtasks --id=<id>`
162  - CLI Syntax: `task-manager clear-subtasks --id=<id>`
163  - Description: Removes subtasks from specified tasks to allow regeneration
164  - Parameters:
165    - `--id=<id>`: ID or comma-separated IDs of tasks to clear subtasks from
166    - `--all`: Clear subtasks from all tasks
167  - Examples:
168    - `task-manager clear-subtasks --id=3`
169    - `task-manager clear-subtasks --id=1,2,3`
170    - `task-manager clear-subtasks --all`
171  - Notes:
172    - Task files are automatically regenerated after clearing subtasks
173    - Can be combined with expand command to immediately generate new subtasks
174    - Works with both parent tasks and individual subtasks
175 
176- **Task Structure Fields**
177  - **id**: Unique identifier for the task (Example: `1`)
178  - **title**: Brief, descriptive title (Example: `"Initialize Repo"`)
179  - **description**: Concise summary of what the task involves (Example: `"Create a new repository, set up initial structure."`)
180  - **status**: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
181  - **dependencies**: IDs of prerequisite tasks (Example: `[1, 2]`)
182    - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
183    - This helps quickly identify which prerequisite tasks are blocking work
184  - **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`)
185  - **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
186  - **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
187  - **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
188 
189- **Environment Variables Configuration**
190  - **ANTHROPIC_API_KEY** (Required): Your Anthropic API key for Claude (Example: `ANTHROPIC_API_KEY=sk-ant-api03-...`)
191  - **MODEL** (Default: `"claude-3-7-sonnet-20250219"`): Claude model to use (Example: `MODEL=claude-3-opus-20240229`)
192  - **MAX_TOKENS** (Default: `"4000"`): Maximum tokens for responses (Example: `MAX_TOKENS=8000`)
193  - **TEMPERATURE** (Default: `"0.7"`): Temperature for model responses (Example: `TEMPERATURE=0.5`)
194  - **DEBUG** (Default: `"false"`): Enable debug logging (Example: `DEBUG=true`)
195  - **LOG_LEVEL** (Default: `"info"`): Console output level (Example: `LOG_LEVEL=debug`)
196  - **DEFAULT_SUBTASKS** (Default: `"3"`): Default subtask count (Example: `DEFAULT_SUBTASKS=5`)
197  - **DEFAULT_PRIORITY** (Default: `"medium"`): Default priority (Example: `DEFAULT_PRIORITY=high`)
198  - **PROJECT_NAME** (Default: `"MCP SaaS MVP"`): Project name in metadata (Example: `PROJECT_NAME=My Awesome Project`)
199  - **PROJECT_VERSION** (Default: `"1.0.0"`): Version in metadata (Example: `PROJECT_VERSION=2.1.0`)
200  - **PERPLEXITY_API_KEY**: For research-backed features (Example: `PERPLEXITY_API_KEY=pplx-...`)
201  - **PERPLEXITY_MODEL** (Default: `"sonar-medium-online"`): Perplexity model (Example: `PERPLEXITY_MODEL=sonar-large-online`)
202 
203- **Determining the Next Task**
204  - Run `task-manager next` to show the next task to work on
205  - The next command identifies tasks with all dependencies satisfied
206  - Tasks are prioritized by priority level, dependency count, and ID
207  - The command shows comprehensive task information including:
208    - Basic task details and description
209    - Implementation details
210    - Subtasks (if they exist)
211    - Contextual suggested actions
212  - Recommended before starting any new development work
213  - Respects your project's dependency structure
214  - Ensures tasks are completed in the appropriate sequence
215  - Provides ready-to-use commands for common task actions
216 
217- **Viewing Specific Task Details**
218  - Run `task-manager show <id>` or `task-manager show --id=<id>` to view a specific task
219  - Use dot notation for subtasks: `task-manager show 1.2` (shows subtask 2 of task 1)
220  - Displays comprehensive information similar to the next command, but for a specific task
221  - For parent tasks, shows all subtasks and their current status
222  - For subtasks, shows parent task information and relationship
223  - Provides contextual suggested actions appropriate for the specific task
224  - Useful for examining task details before implementation or checking status
225 
226- **Managing Task Dependencies**
227  - Use `task-manager add-dependency --id=<id> --depends-on=<id>` to add a dependency
228  - Use `task-manager remove-dependency --id=<id> --depends-on=<id>` to remove a dependency
229  - The system prevents circular dependencies and duplicate dependency entries
230  - Dependencies are checked for existence before being added or removed
231  - Task files are automatically regenerated after dependency changes
232  - Dependencies are visualized with status indicators in task listings and files
233 
234- **Command Reference: add-dependency**
235  - Legacy Syntax: `node scripts/dev.js add-dependency --id=<id> --depends-on=<id>`
236  - CLI Syntax: `task-manager add-dependency --id=<id> --depends-on=<id>`
237  - Description: Adds a dependency relationship between two tasks
238  - Parameters:
239    - `--id=<id>`: ID of task that will depend on another task (required)
240    - `--depends-on=<id>`: ID of task that will become a dependency (required)
241  - Example: `task-manager add-dependency --id=22 --depends-on=21`
242  - Notes: Prevents circular dependencies and duplicates; updates task files automatically
243 
244- **Command Reference: remove-dependency**
245  - Legacy Syntax: `node scripts/dev.js remove-dependency --id=<id> --depends-on=<id>`
246  - CLI Syntax: `task-manager remove-dependency --id=<id> --depends-on=<id>`
247  - Description: Removes a dependency relationship between two tasks
248  - Parameters:
249    - `--id=<id>`: ID of task to remove dependency from (required)
250    - `--depends-on=<id>`: ID of task to remove as a dependency (required)
251  - Example: `task-manager remove-dependency --id=22 --depends-on=21`
252  - Notes: Checks if dependency actually exists; updates task files automatically
253 
254- **Command Reference: validate-dependencies**
255  - Legacy Syntax: `node scripts/dev.js validate-dependencies [options]`
256  - CLI Syntax: `task-manager validate-dependencies [options]`
257  - Description: Checks for and identifies invalid dependencies in tasks.json and task files
258  - Parameters:
259    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
260  - Example: `task-manager validate-dependencies`
261  - Notes:
262    - Reports all non-existent dependencies and self-dependencies without modifying files
263    - Provides detailed statistics on task dependency state
264    - Use before fix-dependencies to audit your task structure
265 
266- **Command Reference: fix-dependencies**
267  - Legacy Syntax: `node scripts/dev.js fix-dependencies [options]`
268  - CLI Syntax: `task-manager fix-dependencies [options]`
269  - Description: Finds and fixes all invalid dependencies in tasks.json and task files
270  - Parameters:
271    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
272  - Example: `task-manager fix-dependencies`
273  - Notes:
274    - Removes references to non-existent tasks and subtasks
275    - Eliminates self-dependencies (tasks depending on themselves)
276    - Regenerates task files with corrected dependencies
277    - Provides detailed report of all fixes made
278 
279- **Command Reference: complexity-report**
280  - Legacy Syntax: `node scripts/dev.js complexity-report [options]`
281  - CLI Syntax: `task-manager complexity-report [options]`
282  - Description: Displays the task complexity analysis report in a formatted, easy-to-read way
283  - Parameters:
284    - `--file=<path>, -f`: Path to the complexity report file (default: 'scripts/task-complexity-report.json')
285  - Example: `task-manager complexity-report`
286  - Notes:
287    - Shows tasks organized by complexity score with recommended actions
288    - Provides complexity distribution statistics
289    - Displays ready-to-use expansion commands for complex tasks
290    - If no report exists, offers to generate one interactively
291 
292- **Command Reference: add-task**
293  - CLI Syntax: `task-manager add-task [options]`
294  - Description: Add a new task to tasks.json using AI
295  - Parameters:
296    - `--file=<path>, -f`: Path to the tasks file (default: 'tasks/tasks.json')
297    - `--prompt=<text>, -p`: Description of the task to add (required)
298    - `--dependencies=<ids>, -d`: Comma-separated list of task IDs this task depends on
299    - `--priority=<priority>`: Task priority (high, medium, low) (default: 'medium')
300  - Example: `task-manager add-task --prompt="Create user authentication using Auth0"`
301  - Notes: Uses AI to convert description into structured task with appropriate details
302 
303- **Command Reference: init**
304  - CLI Syntax: `task-manager init`
305  - Description: Initialize a new project with Task Master structure
306  - Parameters: None
307  - Example: `task-manager init`
308  - Notes:
309    - Creates initial project structure with required files
310    - Prompts for project settings if not provided
311    - Merges with existing files when appropriate
312    - Can be used to bootstrap a new Task Master project quickly
313 
314- **Code Analysis & Refactoring Techniques**
315  - **Top-Level Function Search**
316    - Use grep pattern matching to find all exported functions across the codebase
317    - Command: `grep -E "export (function|const) \w+|function \w+\(|const \w+ = \(|module\.exports" --include="*.js" -r ./`
318    - Benefits:
319      - Quickly identify all public API functions without reading implementation details
320      - Compare functions between files during refactoring (e.g., monolithic to modular structure)
321      - Verify all expected functions exist in refactored modules
322      - Identify duplicate functionality or naming conflicts
323    - Usage examples:
324      - When migrating from `scripts/dev.js` to modular structure: `grep -E "function \w+\(" scripts/dev.js`
325      - Check function exports in a directory: `grep -E "export (function|const)" scripts/modules/`
326      - Find potential naming conflicts: `grep -E "function (get|set|create|update)\w+\(" -r ./`
327    - Variations:
328      - Add `-n` flag to include line numbers
329      - Add `--include="*.ts"` to filter by file extension
330      - Use with `| sort` to alphabetize results
331    - Integration with refactoring workflow:
332      - Start by mapping all functions in the source file
333      - Create target module files based on function grouping
334      - Verify all functions were properly migrated
335      - Check for any unintentional duplications or omissions
336