Cursor rule

1---
2description: Guidelines for implementing task management operations
3globs: scripts/modules/task-manager.js
4alwaysApply: false
5---
6 
7# Task Management Guidelines
8 
9## Task Structure Standards
10 
11- **Core Task Properties**:
12  - ✅ DO: Include all required properties in each task object
13  - ✅ DO: Provide default values for optional properties
14  - ❌ DON'T: Add extra properties that aren't in the standard schema
15 
16```javascript
17  // ✅ DO: Follow this structure for task objects
18  const task = {
19    id: nextId,
20    title: "Task title",
21    description: "Brief task description",
22    status: "pending", // "pending", "in-progress", "done", etc.
23    dependencies: [], // Array of task IDs
24    priority: "medium", // "high", "medium", "low"
25    details: "Detailed implementation instructions",
26    testStrategy: "Verification approach",
27    subtasks: [] // Array of subtask objects
28  };
29```
30 
31- **Subtask Structure**:
32  - ✅ DO: Use consistent properties across subtasks
33  - ✅ DO: Maintain simple numeric IDs within parent tasks
34  - ❌ DON'T: Duplicate parent task properties in subtasks
35 
36```javascript
37  // ✅ DO: Structure subtasks consistently
38  const subtask = {
39    id: nextSubtaskId, // Simple numeric ID, unique within the parent task
40    title: "Subtask title",
41    description: "Brief subtask description",
42    status: "pending",
43    dependencies: [], // Can include numeric IDs (other subtasks) or full task IDs
44    details: "Detailed implementation instructions"
45  };
46```
47 
48## Task Creation and Parsing
49 
50- **ID Management**:
51  - ✅ DO: Assign unique sequential IDs to tasks
52  - ✅ DO: Calculate the next ID based on existing tasks
53  - ❌ DON'T: Hardcode or reuse IDs
54 
55```javascript
56  // ✅ DO: Calculate the next available ID
57  const highestId = Math.max(...data.tasks.map(t => t.id));
58  const nextTaskId = highestId + 1;
59```
60 
61- **PRD Parsing**:
62  - ✅ DO: Extract tasks from PRD documents using AI
63  - ✅ DO: Provide clear prompts to guide AI task generation
64  - ✅ DO: Validate and clean up AI-generated tasks
65 
66```javascript
67  // ✅ DO: Validate AI responses
68  try {
69    // Parse the JSON response
70    taskData = JSON.parse(jsonContent);
71    
72    // Check that we have the required fields
73    if (!taskData.title || !taskData.description) {
74      throw new Error("Missing required fields in the generated task");
75    }
76  } catch (error) {
77    log('error', "Failed to parse AI's response as valid task JSON:", error);
78    process.exit(1);
79  }
80```
81 
82## Task Updates and Modifications
83 
84- **Status Management**:
85  - ✅ DO: Provide functions for updating task status
86  - ✅ DO: Handle both individual tasks and subtasks
87  - ✅ DO: Consider subtask status when updating parent tasks
88 
89```javascript
90  // ✅ DO: Handle status updates for both tasks and subtasks
91  async function setTaskStatus(tasksPath, taskIdInput, newStatus) {
92    // Check if it's a subtask (e.g., "1.2")
93    if (taskIdInput.includes('.')) {
94      const [parentId, subtaskId] = taskIdInput.split('.').map(id => parseInt(id, 10));
95      
96      // Find the parent task and subtask
97      const parentTask = data.tasks.find(t => t.id === parentId);
98      const subtask = parentTask.subtasks.find(st => st.id === subtaskId);
99      
100      // Update subtask status
101      subtask.status = newStatus;
102      
103      // Check if all subtasks are done
104      if (newStatus === 'done') {
105        const allSubtasksDone = parentTask.subtasks.every(st => st.status === 'done');
106        if (allSubtasksDone) {
107          // Suggest updating parent task
108        }
109      }
110    } else {
111      // Handle regular task
112      const task = data.tasks.find(t => t.id === parseInt(taskIdInput, 10));
113      task.status = newStatus;
114      
115      // If marking as done, also mark subtasks
116      if (newStatus === 'done' && task.subtasks && task.subtasks.length > 0) {
117        task.subtasks.forEach(subtask => {
118          subtask.status = newStatus;
119        });
120      }
121    }
122  }
123```
124 
125- **Task Expansion**:
126  - ✅ DO: Use AI to generate detailed subtasks
127  - ✅ DO: Consider complexity analysis for subtask counts
128  - ✅ DO: Ensure proper IDs for newly created subtasks
129 
130```javascript
131  // ✅ DO: Generate appropriate subtasks based on complexity
132  if (taskAnalysis) {
133    log('info', `Found complexity analysis for task ${taskId}: Score ${taskAnalysis.complexityScore}/10`);
134    
135    // Use recommended number of subtasks if available
136    if (taskAnalysis.recommendedSubtasks && numSubtasks === CONFIG.defaultSubtasks) {
137      numSubtasks = taskAnalysis.recommendedSubtasks;
138      log('info', `Using recommended number of subtasks: ${numSubtasks}`);
139    }
140  }
141```
142 
143## Task File Generation
144 
145- **File Formatting**:
146  - ✅ DO: Use consistent formatting for task files
147  - ✅ DO: Include all task properties in text files
148  - ✅ DO: Format dependencies with status indicators
149 
150```javascript
151  // ✅ DO: Use consistent file formatting
152  let content = `# Task ID: ${task.id}\n`;
153  content += `# Title: ${task.title}\n`;
154  content += `# Status: ${task.status || 'pending'}\n`;
155  
156  // Format dependencies with their status
157  if (task.dependencies && task.dependencies.length > 0) {
158    content += `# Dependencies: ${formatDependenciesWithStatus(task.dependencies, data.tasks)}\n`;
159  } else {
160    content += '# Dependencies: None\n';
161  }
162```
163 
164- **Subtask Inclusion**:
165  - ✅ DO: Include subtasks in parent task files
166  - ✅ DO: Use consistent indentation for subtask sections
167  - ✅ DO: Display subtask dependencies with proper formatting
168 
169```javascript
170  // ✅ DO: Format subtasks correctly in task files
171  if (task.subtasks && task.subtasks.length > 0) {
172    content += '\n# Subtasks:\n';
173    
174    task.subtasks.forEach(subtask => {
175      content += `## ${subtask.id}. ${subtask.title} [${subtask.status || 'pending'}]\n`;
176      
177      // Format subtask dependencies
178      if (subtask.dependencies && subtask.dependencies.length > 0) {
179        // Format the dependencies
180        content += `### Dependencies: ${formattedDeps}\n`;
181      } else {
182        content += '### Dependencies: None\n';
183      }
184      
185      content += `### Description: ${subtask.description || ''}\n`;
186      content += '### Details:\n';
187      content += (subtask.details || '').split('\n').map(line => line).join('\n');
188      content += '\n\n';
189    });
190  }
191```
192 
193## Task Listing and Display
194 
195- **Filtering and Organization**:
196  - ✅ DO: Allow filtering tasks by status
197  - ✅ DO: Handle subtask display in lists
198  - ✅ DO: Use consistent table formats
199 
200```javascript
201  // ✅ DO: Implement clear filtering and organization
202  // Filter tasks by status if specified
203  const filteredTasks = statusFilter 
204    ? data.tasks.filter(task => 
205        task.status && task.status.toLowerCase() === statusFilter.toLowerCase())
206    : data.tasks;
207```
208 
209- **Progress Tracking**:
210  - ✅ DO: Calculate and display completion statistics
211  - ✅ DO: Track both task and subtask completion
212  - ✅ DO: Use visual progress indicators
213 
214```javascript
215  // ✅ DO: Track and display progress
216  // Calculate completion statistics
217  const totalTasks = data.tasks.length;
218  const completedTasks = data.tasks.filter(task => 
219    task.status === 'done' || task.status === 'completed').length;
220  const completionPercentage = totalTasks > 0 ? (completedTasks / totalTasks) * 100 : 0;
221  
222  // Count subtasks
223  let totalSubtasks = 0;
224  let completedSubtasks = 0;
225  
226  data.tasks.forEach(task => {
227    if (task.subtasks && task.subtasks.length > 0) {
228      totalSubtasks += task.subtasks.length;
229      completedSubtasks += task.subtasks.filter(st => 
230        st.status === 'done' || st.status === 'completed').length;
231    }
232  });
233```
234 
235## Complexity Analysis
236 
237- **Scoring System**:
238  - ✅ DO: Use AI to analyze task complexity
239  - ✅ DO: Include complexity scores (1-10)
240  - ✅ DO: Generate specific expansion recommendations
241 
242```javascript
243  // ✅ DO: Handle complexity analysis properly
244  const report = {
245    meta: {
246      generatedAt: new Date().toISOString(),
247      tasksAnalyzed: tasksData.tasks.length,
248      thresholdScore: thresholdScore,
249      projectName: tasksData.meta?.projectName || 'Your Project Name',
250      usedResearch: useResearch
251    },
252    complexityAnalysis: complexityAnalysis
253  };
254```
255 
256- **Analysis-Based Workflow**:
257  - ✅ DO: Use complexity reports to guide task expansion
258  - ✅ DO: Prioritize complex tasks for more detailed breakdown
259  - ✅ DO: Use expansion prompts from complexity analysis
260 
261```javascript
262  // ✅ DO: Apply complexity analysis to workflow
263  // Sort tasks by complexity if report exists, otherwise by ID
264  if (complexityReport && complexityReport.complexityAnalysis) {
265    log('info', 'Sorting tasks by complexity...');
266    
267    // Create a map of task IDs to complexity scores
268    const complexityMap = new Map();
269    complexityReport.complexityAnalysis.forEach(analysis => {
270      complexityMap.set(analysis.taskId, analysis.complexityScore);
271    });
272    
273    // Sort tasks by complexity score (high to low)
274    tasksToExpand.sort((a, b) => {
275      const scoreA = complexityMap.get(a.id) || 0;
276      const scoreB = complexityMap.get(b.id) || 0;
277      return scoreB - scoreA;
278    });
279  }
280```
281 
282## Next Task Selection
283 
284- **Eligibility Criteria**:
285  - ✅ DO: Consider dependencies when finding next tasks
286  - ✅ DO: Prioritize by task priority and dependency count
287  - ✅ DO: Skip completed tasks
288 
289```javascript
290  // ✅ DO: Use proper task prioritization logic
291  function findNextTask(tasks) {
292    // Get all completed task IDs
293    const completedTaskIds = new Set(
294      tasks
295        .filter(t => t.status === 'done' || t.status === 'completed')
296        .map(t => t.id)
297    );
298    
299    // Filter for pending tasks whose dependencies are all satisfied
300    const eligibleTasks = tasks.filter(task => 
301      (task.status === 'pending' || task.status === 'in-progress') && 
302      task.dependencies && 
303      task.dependencies.every(depId => completedTaskIds.has(depId))
304    );
305    
306    // Sort by priority, dependency count, and ID
307    const priorityValues = { 'high': 3, 'medium': 2, 'low': 1 };
308    
309    const nextTask = eligibleTasks.sort((a, b) => {
310      // Priority first
311      const priorityA = priorityValues[a.priority || 'medium'] || 2;
312      const priorityB = priorityValues[b.priority || 'medium'] || 2;
313      
314      if (priorityB !== priorityA) {
315        return priorityB - priorityA; // Higher priority first
316      }
317      
318      // Dependency count next
319      if (a.dependencies.length !== b.dependencies.length) {
320        return a.dependencies.length - b.dependencies.length; // Fewer dependencies first
321      }
322      
323      // ID last
324      return a.id - b.id; // Lower ID first
325    })[0];
326    
327    return nextTask;
328  }
329```
330 
331Refer to [`task-manager.js`](mdc:scripts/modules/task-manager.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines.