@posthog/agent 1.13.0 → 1.14.0

package/src/agents/research.ts

@@ -1,100 +1,80 @@
-export const RESEARCH_SYSTEM_PROMPT = `# PostHog AI Coding Agent - Research Mode
-
-You are a PostHog AI Coding Agent operating in RESEARCH mode.
-
-## Your Role
-
-You are a research agent that explores codebases to understand implementation context and generate clarifying questions for development tasks.
-
-## Important Constraints
-
-- **Read-Only Mode**: You can only read files, search code, and analyze the codebase
-- **No Modifications**: You cannot make any changes or edits to code files
-- **Research Focus**: Your goal is understanding and asking the right questions
-
-## Available Tools
-
-- File reading and exploration
-- Code search and analysis
-- Repository structure analysis
-- Documentation review
-
-## Research Process
-
-When given a task, follow this systematic approach:
-
-1. **Codebase Analysis**
-   - Explore the repository structure
-   - Identify relevant files and components
-   - Understand existing patterns and conventions
-   - Review related code and dependencies
-   - Look for similar implementations or patterns
-
-2. **Decision Point Identification**
-   - Identify areas where implementation decisions need to be made
-   - Find multiple viable approaches in the codebase
-   - Note where user preferences would affect the implementation
-   - Consider architectural or design pattern choices
-
-3. **Question Generation**
-   - Generate 3-5 clarifying questions
-   - Each question should offer 2-3 concrete options based on codebase analysis
-   - Options should reference actual patterns/approaches found in the code
-   - Always include option c) as "Something else (please specify)" for flexibility
-   - Focus on high-impact decisions that affect the implementation approach
-
-## Output Format
-
-The artifact MUST follow this EXACT markdown format (this is critical for parsing):
+export const RESEARCH_SYSTEM_PROMPT = `<role>
+PostHog AI Research Agent — analyze codebases to understand implementation context and identify areas of focus for development tasks.
+</role>
+
+<constraints>
+- Read-only: analyze files, search code, explore structure
+- No modifications or code changes
+</constraints>
+
+<objective>
+Your PRIMARY goal is to understand the codebase thoroughly and provide context for the planning phase.
+
+ONLY generate clarifying questions if:
+- The task description is genuinely vague or ambiguous
+- There are multiple valid architectural approaches with significant tradeoffs
+- Critical information is missing that cannot be inferred from the codebase
+
+DO NOT ask questions like "how should I fix this" or "what approach do you prefer" — that defeats the purpose of autonomous task execution. The user has already specified what they want done.
+</objective>
+
+<process>
+1. Explore repository structure and identify relevant files/components
+2. Understand existing patterns, conventions, and dependencies
+3. Locate similar implementations or related code
+4. Identify the key areas of the codebase that will be affected
+5. Document your findings to provide context for planning
+6. ONLY if genuinely needed: generate 2-3 specific clarification questions
+</process>
+
+<output_format>
+Output ONLY the markdown artifact with no preamble:
 
 \`\`\`markdown
-# Research Questions
-
-Based on my analysis of the codebase, here are the key questions to guide implementation:
-
-## Question 1: [Question text - be specific and clear]
+# Research Findings
 
-**Options:**
-- a) [Concrete option based on existing pattern - reference specific files/components]
-- b) [Alternative approach based on another pattern - reference specific files/components]  
-- c) Something else (please specify)
+## Codebase Analysis
+[Brief summary of relevant code structure, patterns, and files]
 
-## Question 2: [Next question - be specific and clear]
+## Key Areas of Focus
+[List specific files/components that need modification]
 
-**Options:**
-- a) [Option with specific code references]
-- b) [Alternative with specific code references]
-- c) Something else (please specify)
+## Implementation Context
+[Important patterns, dependencies, or constraints found in the code]
 
-## Question 3: [Continue with 3-5 questions total]
+## Clarifying Questions
+[ONLY include this section if it will increase the quality of the plan]
 
+## Question 1: [Specific architectural decision]
 **Options:**
-- a) [Option]
-- b) [Alternative]
+- a) [Concrete option with file references]
+- b) [Alternative with file references]
 - c) Something else (please specify)
 \`\`\`
 
-## CRITICAL FORMAT REQUIREMENTS
-
-- Use EXACTLY "## Question N:" format for question headers (h2 level, not h3)
-- Each question MUST be followed by "**Options:**" on its own line
-- Each option MUST start with "- a)", "- b)", "- c)", etc.
-- Always include "c) Something else (please specify)" as the last option
-- Do NOT add extra sections between questions
-- Keep context and analysis BEFORE the questions section, not mixed in
-
-## Important Requirements
-
-- DO NOT GENERATE ANY QUESTIONS IF YOU DON'T HAVE ANY (instead say "No questions required")
-- Generate up to 5 questions (no more)
-- Make options specific and reference actual code/patterns you find
-- Each question must have at least 2 concrete options plus "Something else"
-- Focus on architectural and implementation approach decisions
-- Reference specific files, components, or patterns in your options
-- Make sure the questions help guide a clear implementation path
-- Respond only with the markdown content above, no other text or formatting, no acknowledgement, no explanation, no nothing.
-
-## Final Step
-
-Your research should be thorough enough that the questions help clarify the user's preferences and guide the planning phase effectively.`;
+Format requirements:
+- Use "## Question N:" for question headers (h2)
+- Follow with "**Options:**" on its own line
+- Start options with "- a)", "- b)", "- c)"
+- Always include "c) Something else (please specify)"
+- Max 3 questions total
+</output_format>
+
+<examples>
+<good_example>
+Task: "Fix authentication bug in login flow"
+Output: Research findings showing auth flow files, patterns used, NO questions needed
+</good_example>
+
+<bad_example>
+Task: "Fix authentication bug"
+Output: "How should I fix the authentication? a) Fix it one way b) Fix it another way"
+Reason: Don't ask HOW to do the task — that's what the agent is for
+</bad_example>
+
+<good_example>
+Task: "Add caching to API endpoints"
+Output: Research showing existing cache implementations, question about cache backend choice IF multiple production systems are already in use
+</good_example>
+</examples>`;
 

package/src/prompt-builder.ts

@@ -213,42 +213,50 @@ export class PromptBuilder {
       repositoryPath
     );
 
-    // Process URL references in description  
+    // Process URL references in description
     const { description: processedDescription, referencedResources } = await this.processUrlReferences(
       descriptionAfterFiles
     );
 
-    let prompt = '';
-    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+    let prompt = '<task>\n';
+    prompt += `<title>${task.title}</title>\n`;
+    prompt += `<description>${processedDescription}</description>\n`;
 
     if ((task as any).primary_repository) {
-      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
     }
+    prompt += '</task>\n';
 
     // Add referenced files from @ mentions
     if (referencedFiles.length > 0) {
-      prompt += `\n\n## Referenced Files\n\n`;
+      prompt += '\n<referenced_files>\n';
       for (const file of referencedFiles) {
-        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+        prompt += `<file path="${file.path}">\n\`\`\`\n${file.content}\n\`\`\`\n</file>\n`;
       }
+      prompt += '</referenced_files>\n';
     }
 
     // Add referenced resources from URL mentions
     if (referencedResources.length > 0) {
-      prompt += `\n\n## Referenced Resources\n\n`;
+      prompt += '\n<referenced_resources>\n';
       for (const resource of referencedResources) {
-        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+        prompt += `<resource type="${resource.type}" url="${resource.url}">\n`;
+        prompt += `<title>${resource.title}</title>\n`;
+        prompt += `<content>${resource.content}</content>\n`;
+        prompt += '</resource>\n';
       }
+      prompt += '</referenced_resources>\n';
     }
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const contextFiles = taskFiles.filter((f: any) => f.type === 'context' || f.type === 'reference');
       if (contextFiles.length > 0) {
-        prompt += `\n\n## Supporting Files`;
+        prompt += '\n<supporting_files>\n';
         for (const file of contextFiles) {
-          prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+          prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
         }
+        prompt += '</supporting_files>\n';
       }
     } catch (error) {
       this.logger.debug('No existing task files found for research', { taskId: task.id });
@@ -264,42 +272,50 @@ export class PromptBuilder {
       repositoryPath
     );
 
-    // Process URL references in description  
+    // Process URL references in description
     const { description: processedDescription, referencedResources } = await this.processUrlReferences(
       descriptionAfterFiles
     );
 
-    let prompt = '';
-    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+    let prompt = '<task>\n';
+    prompt += `<title>${task.title}</title>\n`;
+    prompt += `<description>${processedDescription}</description>\n`;
 
     if ((task as any).primary_repository) {
-      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
     }
+    prompt += '</task>\n';
 
     // Add referenced files from @ mentions
     if (referencedFiles.length > 0) {
-      prompt += `\n\n## Referenced Files\n\n`;
+      prompt += '\n<referenced_files>\n';
       for (const file of referencedFiles) {
-        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+        prompt += `<file path="${file.path}">\n\`\`\`\n${file.content}\n\`\`\`\n</file>\n`;
       }
+      prompt += '</referenced_files>\n';
     }
 
     // Add referenced resources from URL mentions
     if (referencedResources.length > 0) {
-      prompt += `\n\n## Referenced Resources\n\n`;
+      prompt += '\n<referenced_resources>\n';
       for (const resource of referencedResources) {
-        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+        prompt += `<resource type="${resource.type}" url="${resource.url}">\n`;
+        prompt += `<title>${resource.title}</title>\n`;
+        prompt += `<content>${resource.content}</content>\n`;
+        prompt += '</resource>\n';
       }
+      prompt += '</referenced_resources>\n';
     }
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const contextFiles = taskFiles.filter((f: any) => f.type === 'context' || f.type === 'reference');
       if (contextFiles.length > 0) {
-        prompt += `\n\n## Supporting Files`;
+        prompt += '\n<supporting_files>\n';
         for (const file of contextFiles) {
-          prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+          prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
         }
+        prompt += '</supporting_files>\n';
       }
     } catch (error) {
       this.logger.debug('No existing task files found for planning', { taskId: task.id });
@@ -315,7 +331,12 @@ export class PromptBuilder {
 
     const planTemplate = await this.generatePlanTemplate(templateVariables);
 
-    prompt += `\n\nPlease analyze the codebase and create a detailed implementation plan for this task. Use the following template structure for your plan:\n\n${planTemplate}\n\nFill in each section with specific, actionable information based on your analysis. Replace all placeholder content with actual details about this task.`;
+    prompt += '\n<instructions>\n';
+    prompt += 'Analyze the codebase and create a detailed implementation plan. Use the template structure below, filling each section with specific, actionable information.\n';
+    prompt += '</instructions>\n\n';
+    prompt += '<plan_template>\n';
+    prompt += planTemplate;
+    prompt += '\n</plan_template>';
 
     return prompt;
   }
@@ -327,56 +348,71 @@ export class PromptBuilder {
       repositoryPath
     );
 
-    // Process URL references in description  
+    // Process URL references in description
     const { description: processedDescription, referencedResources } = await this.processUrlReferences(
       descriptionAfterFiles
     );
 
-    let prompt = '';
-    prompt += `## Current Task\n\n**Task**: ${task.title}\n**Description**: ${processedDescription}`;
+    let prompt = '<task>\n';
+    prompt += `<title>${task.title}</title>\n`;
+    prompt += `<description>${processedDescription}</description>\n`;
 
     if ((task as any).primary_repository) {
-      prompt += `\n**Repository**: ${(task as any).primary_repository}`;
+      prompt += `<repository>${(task as any).primary_repository}</repository>\n`;
     }
+    prompt += '</task>\n';
 
     // Add referenced files from @ mentions
     if (referencedFiles.length > 0) {
-      prompt += `\n\n## Referenced Files\n\n`;
+      prompt += '\n<referenced_files>\n';
       for (const file of referencedFiles) {
-        prompt += `### ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n\n`;
+        prompt += `<file path="${file.path}">\n\`\`\`\n${file.content}\n\`\`\`\n</file>\n`;
       }
+      prompt += '</referenced_files>\n';
     }
 
     // Add referenced resources from URL mentions
     if (referencedResources.length > 0) {
-      prompt += `\n\n## Referenced Resources\n\n`;
+      prompt += '\n<referenced_resources>\n';
       for (const resource of referencedResources) {
-        prompt += `### ${resource.title} (${resource.type})\n**URL**: ${resource.url}\n\n${resource.content}\n\n`;
+        prompt += `<resource type="${resource.type}" url="${resource.url}">\n`;
+        prompt += `<title>${resource.title}</title>\n`;
+        prompt += `<content>${resource.content}</content>\n`;
+        prompt += '</resource>\n';
       }
+      prompt += '</referenced_resources>\n';
     }
 
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const hasPlan = taskFiles.some((f: any) => f.type === 'plan');
+
       if (taskFiles.length > 0) {
-        prompt += `\n\n## Context and Supporting Information`;
+        prompt += '\n<context>\n';
         for (const file of taskFiles) {
           if (file.type === 'plan') {
-            prompt += `\n\n### Execution Plan\n${file.content}`;
+            prompt += `<plan>\n${file.content}\n</plan>\n`;
           } else {
-            prompt += `\n\n### ${file.name} (${file.type})\n${file.content}`;
+            prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
           }
         }
+        prompt += '</context>\n';
       }
+
+      prompt += '\n<instructions>\n';
       if (hasPlan) {
-        prompt += `\n\nPlease implement the changes described in the execution plan above. Follow the plan step-by-step and make the necessary file modifications. You must actually edit files and make changes - do not just analyze or review.`;
+        prompt += 'Implement the changes described in the execution plan. Follow the plan step-by-step and make the necessary file modifications.\n';
       } else {
-        prompt += `\n\nPlease implement the changes described in the task above. You must actually edit files and make changes - do not just analyze or review.`;
+        prompt += 'Implement the changes described in the task. Make the necessary file modifications to complete the task.\n';
       }
+      prompt += '</instructions>';
     } catch (error) {
       this.logger.debug('No supporting files found for execution', { taskId: task.id });
-      prompt += `\n\nPlease implement the changes described in the task above.`;
+      prompt += '\n<instructions>\n';
+      prompt += 'Implement the changes described in the task.\n';
+      prompt += '</instructions>';
     }
+
     return prompt;
   }
 }