get_next_task_recommendation
Retrieve prioritized task suggestions by analyzing project status, dependencies, complexity, and preferences to enhance workflow efficiency and decision-making.
Instructions
Get intelligent recommendations for the next task to work on based on dependencies, priorities, complexity, and current project status. Smart task recommendation engine for optimal workflow management and productivity.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| considerComplexity | No | Whether to factor in task complexity for recommendations | |
| excludeBlocked | No | Whether to exclude blocked tasks from recommendations | |
| maxRecommendations | No | Maximum number of task recommendations to return | |
| preferredTags | No | Preferred task tags to prioritize in recommendations | |
| projectId | No | Filter recommendations to a specific project | |
| workingDirectory | Yes | The full absolute path to the working directory where data is stored. MUST be an absolute path, never relative. Windows: "C:\Users\username\project" or "D:\projects\my-app". Unix/Linux/macOS: "/home/username/project" or "/Users/username/project". Do NOT use: ".", "..", "~", "./folder", "../folder" or any relative paths. Ensure the path exists and is accessible before calling this tool. NOTE: When server is started with --claude flag, this parameter is ignored and a global user directory is used instead. |
Implementation Reference
- Factory function createNextTaskRecommendationTool that defines the tool with name 'get_next_task_recommendation', description, input schema, and handler. This is where the tool is created/registered.
export function createNextTaskRecommendationTool(storage: Storage, getWorkingDirectoryDescription: (config: any) => string, config: any) { return { name: 'get_next_task_recommendation', description: 'Get intelligent recommendations for the next task to work on based on dependencies, priorities, complexity, and current project status. Smart task recommendation engine for optimal workflow management.', inputSchema: z.object({ workingDirectory: z.string().describe(getWorkingDirectoryDescription(config)), projectId: z.string().optional().describe('Filter recommendations to a specific project'), maxRecommendations: z.number().min(1).max(10).optional().default(3).describe('Maximum number of task recommendations to return'), considerComplexity: z.boolean().optional().default(true).describe('Whether to factor in task complexity for recommendations'), preferredTags: z.array(z.string()).optional().describe('Preferred task tags to prioritize in recommendations'), excludeBlocked: z.boolean().optional().default(true).describe('Whether to exclude blocked tasks from recommendations') }), handler: async (args: any) => { try { const { workingDirectory, projectId, maxRecommendations, considerComplexity, preferredTags, excludeBlocked } = args; // Get all tasks, optionally filtered by project const allTasks = projectId ? await storage.getTasks(projectId) : await getAllTasksAcrossProjects(storage); if (allTasks.length === 0) { return { content: [{ type: 'text' as const, text: projectId ? `No tasks found in the specified project.` : `No tasks found. Create some tasks first using \`create_task\` or \`parse_prd\`.` }] }; } // Filter and analyze tasks const readyTasks = await findReadyTasks(allTasks, excludeBlocked); if (readyTasks.length === 0) { return { content: [{ type: 'text' as const, text: `🚫 No tasks are currently ready to work on. All tasks are either completed, blocked, or waiting for dependencies. 📊 **Task Status Summary:** ${generateTaskStatusSummary(allTasks)} 💡 **Suggestions:** 1. Check if any blocked tasks can be unblocked 2. Review task dependencies for circular references 3. Create new tasks if all current tasks are completed` }] }; } // Score and rank tasks const scoredTasks = await scoreAndRankTasks( readyTasks, allTasks, considerComplexity, preferredTags ); // Get top recommendations const recommendations = scoredTasks.slice(0, maxRecommendations); // Generate recommendation report const report = generateRecommendationReport(recommendations, allTasks); return { content: [{ type: 'text' as const, text: report }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error generating task recommendations: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } }; } - Zod inputSchema defining parameters for the tool: workingDirectory, projectId, maxRecommendations, etc.
inputSchema: z.object({ workingDirectory: z.string().describe(getWorkingDirectoryDescription(config)), projectId: z.string().optional().describe('Filter recommendations to a specific project'), maxRecommendations: z.number().min(1).max(10).optional().default(3).describe('Maximum number of task recommendations to return'), considerComplexity: z.boolean().optional().default(true).describe('Whether to factor in task complexity for recommendations'), preferredTags: z.array(z.string()).optional().describe('Preferred task tags to prioritize in recommendations'), excludeBlocked: z.boolean().optional().default(true).describe('Whether to exclude blocked tasks from recommendations') }), - The async handler function implementing the core logic: fetches tasks, filters ready tasks, scores and ranks them based on priority/complexity/tags/dependencies, generates recommendation report.
handler: async (args: any) => { try { const { workingDirectory, projectId, maxRecommendations, considerComplexity, preferredTags, excludeBlocked } = args; // Get all tasks, optionally filtered by project const allTasks = projectId ? await storage.getTasks(projectId) : await getAllTasksAcrossProjects(storage); if (allTasks.length === 0) { return { content: [{ type: 'text' as const, text: projectId ? `No tasks found in the specified project.` : `No tasks found. Create some tasks first using \`create_task\` or \`parse_prd\`.` }] }; } // Filter and analyze tasks const readyTasks = await findReadyTasks(allTasks, excludeBlocked); if (readyTasks.length === 0) { return { content: [{ type: 'text' as const, text: `🚫 No tasks are currently ready to work on. All tasks are either completed, blocked, or waiting for dependencies. 📊 **Task Status Summary:** ${generateTaskStatusSummary(allTasks)} 💡 **Suggestions:** 1. Check if any blocked tasks can be unblocked 2. Review task dependencies for circular references 3. Create new tasks if all current tasks are completed` }] }; } // Score and rank tasks const scoredTasks = await scoreAndRankTasks( readyTasks, allTasks, considerComplexity, preferredTags ); // Get top recommendations const recommendations = scoredTasks.slice(0, maxRecommendations); // Generate recommendation report const report = generateRecommendationReport(recommendations, allTasks); return { content: [{ type: 'text' as const, text: report }] }; } catch (error) { return { content: [{ type: 'text' as const, text: `Error generating task recommendations: ${error instanceof Error ? error.message : 'Unknown error'}` }], isError: true }; } } - findReadyTasks helper: identifies tasks ready to work on by checking dependencies are completed and not blocked.
async function findReadyTasks(allTasks: Task[], excludeBlocked: boolean): Promise<Task[]> { const readyTasks: Task[] = []; for (const task of allTasks) { // Skip completed tasks if (task.completed || task.status === 'done') { continue; } // Skip blocked tasks if requested if (excludeBlocked && task.status === 'blocked') { continue; } // Check if all dependencies are completed if (task.dependsOn && task.dependsOn.length > 0) { const dependenciesMet = task.dependsOn.every(depId => { const depTask = allTasks.find(t => t.id === depId); return depTask && (depTask.completed || depTask.status === 'done'); }); if (!dependenciesMet) { continue; } } readyTasks.push(task); } return readyTasks; } - scoreAndRankTasks helper: computes scores for ready tasks based on priority, complexity, tags, status, enabler bonus, and sorts them.
async function scoreAndRankTasks( readyTasks: Task[], allTasks: Task[], considerComplexity: boolean, preferredTags?: string[] ): Promise<Array<Task & { score: number; reasoning: string }>> { const scoredTasks = readyTasks.map(task => { let score = 0; const reasoningParts: string[] = []; // Priority score (40% weight) const priorityScore = (task.priority || 5) * 4; score += priorityScore; reasoningParts.push(`Priority: ${task.priority || 5}/10 (+${priorityScore})`); // Complexity consideration (20% weight) if (considerComplexity && task.complexity) { // Lower complexity gets higher score for "quick wins" const complexityScore = (11 - task.complexity) * 2; score += complexityScore; reasoningParts.push(`Complexity: ${task.complexity}/10 (+${complexityScore} for lower complexity)`); } // Tag preference bonus (15% weight) if (preferredTags && preferredTags.length > 0 && task.tags) { const tagMatches = task.tags.filter(tag => preferredTags.includes(tag)).length; const tagScore = tagMatches * 5; score += tagScore; if (tagScore > 0) { reasoningParts.push(`Tag matches: ${tagMatches} (+${tagScore})`); } } // Status bonus (10% weight) if (task.status === 'in-progress') { score += 10; reasoningParts.push(`In progress (+10)`); } // Dependency enabler bonus (15% weight) const dependentTasks = allTasks.filter(t => t.dependsOn && t.dependsOn.includes(task.id) && !t.completed && t.status !== 'done' ); if (dependentTasks.length > 0) { const enablerScore = dependentTasks.length * 3; score += enablerScore; reasoningParts.push(`Enables ${dependentTasks.length} other tasks (+${enablerScore})`); } return { ...task, score, reasoning: reasoningParts.join(', ') }; }); // Sort by score (highest first) return scoredTasks.sort((a, b) => b.score - a.score); }