src/prompts/README.md
This directory contains the centralized prompt templates for all AI-powered features in Task Master.
The prompt management system provides:
/src/prompts)src/prompts/
├── README.md # This file
├── schemas/ # JSON schemas for validation
│ ├── README.md # Schema documentation
│ ├── prompt-template.schema.json # Main template schema
│ ├── parameter.schema.json # Parameter validation schema
│ └── variant.schema.json # Prompt variant schema
├── parse-prd.json # PRD parsing prompts
├── expand-task.json # Task expansion prompts
├── add-task.json # Task creation prompts
├── update-tasks.json # Bulk task update prompts
├── update-task.json # Single task update prompts
├── update-subtask.json # Subtask update prompts
├── analyze-complexity.json # Complexity analysis prompts
└── research.json # Research query prompts
All prompt templates are validated against JSON schemas located in /src/prompts/schemas/. The validation system:
id, version, description, prompts.defaultajv and ajv-formats are required for validation.json file in /src/prompts/version field following semantic versioningPurpose: Parse a Product Requirements Document into structured tasks
Variants: default, research (when research mode is enabled)
Required Parameters:
numTasks (number): Target number of tasks to generatenextId (number): Starting ID for tasksprdContent (string): Content of the PRD fileprdPath (string): Path to the PRD filedefaultTaskPriority (string): Default priority for generated tasksOptional Parameters:
research (boolean): Enable research mode for latest best practices (default: false)Usage: Used by task-master parse-prd command to convert PRD documents into actionable task lists.
Purpose: Generate a new task based on user description
Variants: default, research (when research mode is enabled)
Required Parameters:
prompt (string): User's task descriptionnewTaskId (number): ID for the new taskOptional Parameters:
existingTasks (array): List of existing tasks for contextgatheredContext (string): Context gathered from codebase analysiscontextFromArgs (string): Additional context from manual argspriority (string): Task priority (high/medium/low, default: medium)dependencies (array): Task dependency IDsuseResearch (boolean): Use research mode (default: false)Usage: Used by task-master add-task command to create new tasks with AI assistance.
Purpose: Break down a task into detailed subtasks with three sophisticated strategies
Variants: complexity-report (when expansionPrompt exists), research (when research mode is enabled), default (standard case)
Required Parameters:
subtaskCount (number): Number of subtasks to generatetask (object): The task to expandnextSubtaskId (number): Starting ID for new subtasksOptional Parameters:
additionalContext (string): Additional context for expansion (default: "")complexityReasoningContext (string): Complexity analysis reasoning context (default: "")gatheredContext (string): Gathered project context (default: "")useResearch (boolean): Use research mode (default: false)expansionPrompt (string): Expansion prompt from complexity reportVariant Selection Strategy:
expansionPrompt exists (highest priority)useResearch === true && !expansionPromptUsage: Used by task-master expand command to break complex tasks into manageable subtasks using the most appropriate strategy based on available context and complexity analysis.
Purpose: Update a single task with new information, supporting full updates and append mode
Variants: default, append (when appendMode is true), research (when research mode is enabled)
Required Parameters:
task (object): The task to updatetaskJson (string): JSON string representation of the taskupdatePrompt (string): Description of changes to applyOptional Parameters:
appendMode (boolean): Whether to append to details or do full update (default: false)useResearch (boolean): Use research mode (default: false)currentDetails (string): Current task details for context (default: "(No existing details)")gatheredContext (string): Additional project contextUsage: Used by task-master update-task command to modify existing tasks.
Purpose: Update multiple tasks based on new context or changes
Variants: default, research (when research mode is enabled)
Required Parameters:
tasks (array): Array of tasks to updateupdatePrompt (string): Description of changes to applyOptional Parameters:
useResearch (boolean): Use research mode (default: false)projectContext (string): Additional project contextUsage: Used by task-master update command to bulk update multiple tasks.
Purpose: Append information to a subtask by generating only new content
Variants: default, research (when research mode is enabled)
Required Parameters:
parentTask (object): The parent task contextcurrentDetails (string): Current subtask details (default: "(No existing details)")updatePrompt (string): User request for what to addOptional Parameters:
prevSubtask (object): The previous subtask if anynextSubtask (object): The next subtask if anyuseResearch (boolean): Use research mode (default: false)gatheredContext (string): Additional project contextUsage: Used by task-master update-subtask command to log progress and findings on subtasks.
Purpose: Analyze task complexity and generate expansion recommendations
Variants: default, research (when research mode is enabled), batch (when analyzing >10 tasks)
Required Parameters:
tasks (array): Array of tasks to analyzeOptional Parameters:
gatheredContext (string): Additional project contextthreshold (number): Complexity threshold for expansion recommendation (1-10, default: 5)useResearch (boolean): Use research mode for deeper analysis (default: false)Usage: Used by task-master analyze-complexity command to determine which tasks need breakdown.
Purpose: Perform AI-powered research with project context
Variants: default, low (concise responses), medium (balanced), high (detailed)
Required Parameters:
query (string): Research queryOptional Parameters:
gatheredContext (string): Gathered project contextdetailLevel (string): Level of detail (low/medium/high, default: medium)projectInfo (object): Project information with properties:
root (string): Project root pathtaskCount (number): Number of related tasksfileCount (number): Number of related filesUsage: Used by task-master research command to get contextual information and guidance.
Each prompt template is a JSON file with the following structure:
{
"id": "unique-identifier",
"version": "1.0.0",
"description": "What this prompt does",
"metadata": {
"author": "system",
"created": "2024-01-01T00:00:00Z",
"updated": "2024-01-01T00:00:00Z",
"tags": ["category", "feature"],
"category": "task"
},
"parameters": {
"paramName": {
"type": "string|number|boolean|array|object",
"required": true|false,
"default": "default value",
"description": "Parameter description",
"enum": ["option1", "option2"],
"pattern": "^[a-z]+$",
"minimum": 1,
"maximum": 100
}
},
"prompts": {
"default": {
"system": "System prompt template",
"user": "User prompt template"
},
"variant-name": {
"condition": "JavaScript expression",
"system": "Variant system prompt",
"user": "Variant user prompt",
"metadata": {
"description": "When to use this variant"
}
}
}
}
Use {{variableName}} to inject dynamic values:
"user": "Analyze these {{tasks.length}} tasks with threshold {{threshold}}"
Use {{#if variable}}...{{/if}} for conditional content:
"user": "{{#if useResearch}}Research and {{/if}}create a task"
Use {{#if (eq variable "value")}}...{{/if}} for string comparisons:
"user": "{{#if (eq detailLevel \"low\")}}Provide a brief summary{{/if}}"
"user": "{{#if (eq priority \"high\")}}URGENT: {{/if}}{{taskTitle}}"
The eq helper enables clean conditional logic based on parameter values:
(eq detailLevel "medium")(eq status "pending"){{#if (eq level "1")}}First{{/if}}{{#if (eq level "2")}}Second{{/if}}Use {{#if (not variable)}}...{{/if}} for negation conditions:
"user": "{{#if (not useResearch)}}Use basic analysis{{/if}}"
"user": "{{#if (not hasSubtasks)}}This task has no subtasks{{/if}}"
The not helper enables clean negative conditional logic:
(not useResearch)(not emptyArray)notUseResearch flagsUse {{#if (gt variable number)}}...{{/if}} for greater than comparisons:
"user": "generate {{#if (gt numTasks 0)}}approximately {{numTasks}}{{else}}an appropriate number of{{/if}} top-level development tasks"
"user": "{{#if (gt complexity 5)}}This is a complex task{{/if}}"
"system": "create {{#if (gt subtaskCount 0)}}exactly {{subtaskCount}}{{else}}an appropriate number of{{/if}} subtasks"
Use {{#if (gte variable number)}}...{{/if}} for greater than or equal comparisons:
"user": "{{#if (gte priority 8)}}HIGH PRIORITY{{/if}}"
"user": "{{#if (gte threshold 1)}}Analysis enabled{{/if}}"
"system": "{{#if (gte complexityScore 8)}}Use detailed breakdown approach{{/if}}"
The numeric comparison helpers enable sophisticated conditional logic:
{{#if (gt numTasks 0)}}exactly {{numTasks}}{{else}}an appropriate number of{{/if}}(gte complexityScore 8) for high-complexity handling(gt subtaskCount 0) for conditional content generation(gt score 7.5) for fractional comparisonsUse {{#each array}}...{{/each}} to iterate over arrays:
"user": "Tasks:\n{{#each tasks}}- {{id}}: {{title}}\n{{/each}}"
Inside {{#each}} blocks, you have access to:
{{@index}}: Current array index (0-based){{@first}}: Boolean, true for first item{{@last}}: Boolean, true for last item"user": "{{#each tasks}}{{@index}}. {{title}}{{#unless @last}}\n{{/unless}}{{/each}}"
Use {{{json variable}}} (triple braces) to serialize objects/arrays to JSON:
"user": "Analyze these tasks: {{{json tasks}}}"
Access nested properties with dot notation:
"user": "Project: {{context.projectName}}"
Variants allow different prompts based on conditions:
{
"prompts": {
"default": {
"system": "Default system prompt",
"user": "Default user prompt"
},
"research": {
"condition": "useResearch === true",
"system": "Research-focused system prompt",
"user": "Research-focused user prompt"
},
"high-complexity": {
"condition": "complexityScore >= 8",
"system": "Complex task handling prompt",
"user": "Detailed breakdown request"
}
}
}
Conditions are JavaScript expressions evaluated with parameter values as context:
useResearch === truethreshold >= 5priority === 'high'useResearch && threshold > 7The PromptManager is implemented in scripts/modules/prompt-manager.js and provides:
import { getPromptManager } from '../prompt-manager.js';
const promptManager = getPromptManager();
const { systemPrompt, userPrompt, metadata } = promptManager.loadPrompt('add-task', {
// Parameters matching the template's parameter definitions
prompt: 'Create a user authentication system',
newTaskId: 5,
priority: 'high',
useResearch: false
});
// Use with AI service
const result = await generateObjectService({
systemPrompt,
prompt: userPrompt,
// ... other AI parameters
});
// Research variant will be selected automatically
const { systemPrompt, userPrompt } = promptManager.loadPrompt('expand-task', {
useResearch: true, // Triggers research variant
task: taskObject,
subtaskCount: 5
});
try {
const result = promptManager.loadPrompt('invalid-template', {});
} catch (error) {
if (error.message.includes('Schema validation failed')) {
console.error('Template validation error:', error.message);
} else if (error.message.includes('not found')) {
console.error('Template not found:', error.message);
}
}
{
"id": "new-feature",
"version": "1.0.0",
"description": "Generate code for a new feature",
"parameters": {
"featureName": {
"type": "string",
"required": true,
"pattern": "^[a-zA-Z][a-zA-Z0-9-]*$",
"description": "Name of the feature to implement"
},
"complexity": {
"type": "string",
"required": false,
"enum": ["simple", "medium", "complex"],
"default": "medium",
"description": "Feature complexity level"
}
},
"prompts": {
"default": {
"system": "You are a senior software engineer.",
"user": "Create a {{complexity}} {{featureName}} feature."
}
}
}
// Test schema validation
const promptManager = getPromptManager();
const results = promptManager.validateAllPrompts();
console.log(`Valid: ${results.valid.length}, Errors: ${results.errors.length}`);
When modifying prompts, ensure to test:
// Test prompt loading and variable substitution
const promptManager = getPromptManager();
const result = promptManager.loadPrompt('research', {
query: 'What are the latest React best practices?',
detailLevel: 'medium',
gatheredContext: 'React project with TypeScript'
});
console.log('System:', result.systemPrompt);
console.log('User:', result.userPrompt);
console.log('Metadata:', result.metadata);
Schema Validation Errors:
Variable Substitution Problems:
Variant Selection Issues:
Performance Issues: