feat: Centralize AI prompts into JSON templates (#882)

* centralize prompt management * add changeset * add variant key to determine prompt version * update tests and add prompt manager test * determine internal path, don't use projectRoot * add promptManager mock * detailed prompt docs * add schemas and validator packages * add validate prompts command * add schema validation * update tests * move schemas to src/prompts/schemas * use this.promptsDir for better semantics * add prompt schemas * version schema files & update links * remove validate command * expect dependencies * update docs * fix test * remove suggestmode to ensure clean keys * remove default variant from research and update schema * now handled by prompt manager * add manual test to verify prompts * remove incorrect batch variant * consolidate variants * consolidate analyze-complexity to just default variant * consolidate parse-prd variants * add eq handler for handlebars * consolidate research prompt variants * use brevity * consolidate variants for update subtask * add not handler * consolidate variants for update-task * consolidate update-tasks variants * add conditional content to prompt when research used * update prompt tests * show correct research variant * make variant names link to below * remove changset * restore gitignore * Merge branch 'next' of https://github.com/eyaltoledano/claude-task-master into joedanz/centralize-prompts # Conflicts: # package-lock.json # scripts/modules/task-manager/expand-task.js # scripts/modules/task-manager/parse-prd.js remove unused * add else * update tests * update biome optional dependencies * responsive html output for mobile
2025-07-10 03:52:11 -04:00
parent 4bc8029080
commit a65ad0a47c
36 changed files with 6180 additions and 9034 deletions
--- a/src/prompts/README.md
+++ b/src/prompts/README.md
@@ -0,0 +1,572 @@
+# Task Master Prompt Management System
+
+This directory contains the centralized prompt templates for all AI-powered features in Task Master.
+
+## Overview
+
+The prompt management system provides:
+- **Centralized Storage**: All prompts in one location (`/src/prompts`)
+- **JSON Schema Validation**: Comprehensive validation using AJV with detailed error reporting
+- **Version Control**: Track changes to prompts over time
+- **Variant Support**: Different prompts for different contexts (research mode, complexity levels, etc.)
+- **Template Variables**: Dynamic prompt generation with variable substitution
+- **IDE Integration**: VS Code IntelliSense and validation support
+
+## Directory Structure
+
+```
+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
+```
+
+## Schema Validation
+
+All prompt templates are validated against JSON schemas located in `/src/prompts/schemas/`. The validation system:
+
+- **Structural Validation**: Ensures required fields and proper nesting
+- **Parameter Type Checking**: Validates parameter types, patterns, and ranges
+- **Template Syntax**: Validates Handlebars syntax and variable references
+- **Semantic Versioning**: Enforces proper version format
+- **Cross-Reference Validation**: Ensures parameters match template variables
+
+### Validation Features
+- **Required Fields**: `id`, `version`, `description`, `prompts.default`
+- **Type Safety**: String, number, boolean, array, object validation
+- **Pattern Matching**: Regex validation for string parameters
+- **Range Validation**: Min/max values for numeric parameters
+- **Enum Constraints**: Restricted value sets for categorical parameters
+
+## Development Workflow
+
+### Setting Up Development Environment
+1. **VS Code Integration**: Schemas are automatically configured for IntelliSense
+2. **Dependencies**: `ajv` and `ajv-formats` are required for validation
+3. **File Watching**: Changes to templates trigger automatic validation
+
+### Creating New Prompts
+1. Create a new `.json` file in `/src/prompts/`
+2. Follow the schema structure (see Template Structure section)
+3. Define parameters with proper types and validation
+4. Create system and user prompts with template variables
+5. Test with the PromptManager before committing
+
+### Modifying Existing Prompts
+1. Update the `version` field following semantic versioning
+2. Maintain backward compatibility when possible
+3. Test with existing code that uses the prompt
+4. Update documentation if parameters change
+
+## Prompt Template Reference
+
+### 1. parse-prd.json
+**Purpose**: 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 generate
+- `nextId` (number): Starting ID for tasks
+- `prdContent` (string): Content of the PRD file
+- `prdPath` (string): Path to the PRD file
+- `defaultTaskPriority` (string): Default priority for generated tasks
+
+**Optional 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.
+
+### 2. add-task.json
+**Purpose**: Generate a new task based on user description  
+**Variants**: `default`, `research` (when research mode is enabled)
+
+**Required Parameters**:
+- `prompt` (string): User's task description
+- `newTaskId` (number): ID for the new task
+
+**Optional Parameters**:
+- `existingTasks` (array): List of existing tasks for context
+- `gatheredContext` (string): Context gathered from codebase analysis
+- `contextFromArgs` (string): Additional context from manual args
+- `priority` (string): Task priority (high/medium/low, default: medium)
+- `dependencies` (array): Task dependency IDs
+- `useResearch` (boolean): Use research mode (default: false)
+
+**Usage**: Used by `task-master add-task` command to create new tasks with AI assistance.
+
+### 3. expand-task.json
+**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 generate
+- `task` (object): The task to expand
+- `nextSubtaskId` (number): Starting ID for new subtasks
+
+**Optional 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 report
+
+**Variant Selection Strategy**:
+1. **complexity-report**: Used when `expansionPrompt` exists (highest priority)
+2. **research**: Used when `useResearch === true && !expansionPrompt`
+3. **default**: Standard fallback strategy
+
+**Usage**: 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.
+
+### 4. update-task.json
+**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 update
+- `taskJson` (string): JSON string representation of the task
+- `updatePrompt` (string): Description of changes to apply
+
+**Optional 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 context
+
+**Usage**: Used by `task-master update-task` command to modify existing tasks.
+
+### 5. update-tasks.json
+**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 update
+- `updatePrompt` (string): Description of changes to apply
+
+**Optional Parameters**:
+- `useResearch` (boolean): Use research mode (default: false)
+- `projectContext` (string): Additional project context
+
+**Usage**: Used by `task-master update` command to bulk update multiple tasks.
+
+### 6. update-subtask.json
+**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 context
+- `currentDetails` (string): Current subtask details (default: "(No existing details)")
+- `updatePrompt` (string): User request for what to add
+
+**Optional Parameters**:
+- `prevSubtask` (object): The previous subtask if any
+- `nextSubtask` (object): The next subtask if any
+- `useResearch` (boolean): Use research mode (default: false)
+- `gatheredContext` (string): Additional project context
+
+**Usage**: Used by `task-master update-subtask` command to log progress and findings on subtasks.
+
+### 7. analyze-complexity.json
+**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 analyze
+
+**Optional Parameters**:
+- `gatheredContext` (string): Additional project context
+- `threshold` (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.
+
+### 8. research.json
+**Purpose**: Perform AI-powered research with project context  
+**Variants**: `default`, `low` (concise responses), `medium` (balanced), `high` (detailed)
+
+**Required Parameters**:
+- `query` (string): Research query
+
+**Optional Parameters**:
+- `gatheredContext` (string): Gathered project context
+- `detailLevel` (string): Level of detail (low/medium/high, default: medium)
+- `projectInfo` (object): Project information with properties:
+  - `root` (string): Project root path
+  - `taskCount` (number): Number of related tasks
+  - `fileCount` (number): Number of related files
+
+**Usage**: Used by `task-master research` command to get contextual information and guidance.
+
+## Template Structure
+
+Each prompt template is a JSON file with the following structure:
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+## Template Features
+
+### Variable Substitution
+Use `{{variableName}}` to inject dynamic values:
+```
+"user": "Analyze these {{tasks.length}} tasks with threshold {{threshold}}"
+```
+
+### Conditionals
+Use `{{#if variable}}...{{/if}}` for conditional content:
+```
+"user": "{{#if useResearch}}Research and {{/if}}create a task"
+```
+
+### Helper Functions
+
+#### Equality Helper
+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:
+- Compare strings: `(eq detailLevel "medium")`
+- Compare with enum values: `(eq status "pending")`
+- Multiple conditions: `{{#if (eq level "1")}}First{{/if}}{{#if (eq level "2")}}Second{{/if}}`
+
+#### Negation Helper
+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:
+- Negate boolean values: `(not useResearch)`
+- Negate truthy/falsy values: `(not emptyArray)`
+- Cleaner than separate boolean parameters: No need for `notUseResearch` flags
+
+#### Numeric Comparison Helpers
+Use `{{#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:
+- **Dynamic counting**: `{{#if (gt numTasks 0)}}exactly {{numTasks}}{{else}}an appropriate number of{{/if}}`
+- **Threshold-based behavior**: `(gte complexityScore 8)` for high-complexity handling
+- **Zero checks**: `(gt subtaskCount 0)` for conditional content generation
+- **Decimal support**: `(gt score 7.5)` for fractional comparisons
+- **Enhanced prompt sophistication**: Enables parse-prd and expand-task logic matching GitHub specifications
+
+### Loops
+Use `{{#each array}}...{{/each}}` to iterate over arrays:
+```
+"user": "Tasks:\n{{#each tasks}}- {{id}}: {{title}}\n{{/each}}"
+```
+
+### Special Loop Variables
+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}}"
+```
+
+### JSON Serialization
+Use `{{{json variable}}}` (triple braces) to serialize objects/arrays to JSON:
+```
+"user": "Analyze these tasks: {{{json tasks}}}"
+```
+
+### Nested Properties
+Access nested properties with dot notation:
+```
+"user": "Project: {{context.projectName}}"
+```
+
+## Prompt Variants
+
+Variants allow different prompts based on conditions:
+
+```json
+{
+  "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"
+    }
+  }
+}
+```
+
+### Condition Evaluation
+Conditions are JavaScript expressions evaluated with parameter values as context:
+- Simple comparisons: `useResearch === true`
+- Numeric comparisons: `threshold >= 5`
+- String matching: `priority === 'high'`
+- Complex logic: `useResearch && threshold > 7`
+
+## PromptManager Module
+
+The PromptManager is implemented in `scripts/modules/prompt-manager.js` and provides:
+- **Template loading and caching**: Templates are loaded once and cached for performance
+- **Schema validation**: Comprehensive validation using AJV with detailed error reporting
+- **Variable substitution**: Handlebars-like syntax for dynamic content
+- **Variant selection**: Automatic selection based on conditions
+- **Error handling**: Graceful fallbacks and detailed error messages
+- **Singleton pattern**: One instance per project root for efficiency
+
+### Validation Behavior
+- **Schema Available**: Full validation with detailed error messages
+- **Schema Missing**: Falls back to basic structural validation
+- **Invalid Templates**: Throws descriptive errors with field-level details
+- **Parameter Validation**: Type checking, pattern matching, range validation
+
+## Usage in Code
+
+### Basic Usage
+```javascript
+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
+});
+```
+
+### With Variants
+```javascript
+// Research variant will be selected automatically
+const { systemPrompt, userPrompt } = promptManager.loadPrompt('expand-task', {
+  useResearch: true,  // Triggers research variant
+  task: taskObject,
+  subtaskCount: 5
+});
+```
+
+### Error Handling
+```javascript
+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);
+  }
+}
+```
+
+## Adding New Prompts
+
+1. **Create the JSON file** following the template structure
+2. **Define parameters** with proper types, validation, and descriptions
+3. **Create prompts** with clear system and user templates
+4. **Use template variables** for dynamic content
+5. **Add variants** if needed for different contexts
+6. **Test thoroughly** with the PromptManager
+7. **Update this documentation** with the new prompt details
+
+### Example New Prompt
+```json
+{
+  "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."
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Template Design
+1. **Clear IDs**: Use kebab-case, descriptive identifiers
+2. **Semantic Versioning**: Follow semver for version management
+3. **Comprehensive Parameters**: Define all required and optional parameters
+4. **Type Safety**: Use proper parameter types and validation
+5. **Clear Descriptions**: Document what each prompt and parameter does
+
+### Variable Usage
+1. **Meaningful Names**: Use descriptive variable names
+2. **Consistent Patterns**: Follow established naming conventions
+3. **Safe Defaults**: Provide sensible default values
+4. **Validation**: Use patterns, enums, and ranges for validation
+
+### Variant Strategy
+1. **Simple Conditions**: Keep variant conditions easy to understand
+2. **Clear Purpose**: Each variant should have a distinct use case
+3. **Fallback Logic**: Always provide a default variant
+4. **Documentation**: Explain when each variant is used
+
+### Performance
+1. **Caching**: Templates are cached automatically
+2. **Lazy Loading**: Templates load only when needed
+3. **Minimal Variants**: Don't create unnecessary variants
+4. **Efficient Conditions**: Keep condition evaluation fast
+
+## Testing Prompts
+
+### Validation Testing
+```javascript
+// Test schema validation
+const promptManager = getPromptManager();
+const results = promptManager.validateAllPrompts();
+console.log(`Valid: ${results.valid.length}, Errors: ${results.errors.length}`);
+```
+
+### Integration Testing
+When modifying prompts, ensure to test:
+- Variable substitution works with actual data structures
+- Variant selection triggers correctly based on conditions
+- AI responses remain consistent with expected behavior
+- All parameters are properly validated
+- Error handling works for invalid inputs
+
+### Quick Testing
+```javascript
+// 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);
+```
+
+### Testing Checklist
+- [ ] Template validates against schema
+- [ ] All required parameters are defined
+- [ ] Variable substitution works correctly
+- [ ] Variants trigger under correct conditions
+- [ ] Error messages are clear and helpful
+- [ ] Performance is acceptable for repeated usage
+
+## Troubleshooting
+
+### Common Issues
+
+**Schema Validation Errors**:
+- Check required fields are present
+- Verify parameter types match schema
+- Ensure version follows semantic versioning
+- Validate JSON syntax
+
+**Variable Substitution Problems**:
+- Check variable names match parameter names
+- Verify nested property access syntax
+- Ensure array iteration syntax is correct
+- Test with actual data structures
+
+**Variant Selection Issues**:
+- Verify condition syntax is valid JavaScript
+- Check parameter values match condition expectations
+- Ensure default variant exists
+- Test condition evaluation with debug logging
+
+**Performance Issues**:
+- Check for circular references in templates
+- Verify caching is working correctly
+- Monitor template loading frequency
+- Consider simplifying complex conditions