@posthog/agent 1.19.0 → 1.20.0

package/src/agents/research.ts

@@ -19,7 +19,14 @@ Calculate an actionabilityScore (0-1) based on:
 
 If actionabilityScore < 0.7, generate specific clarifying questions to increase confidence.
 
-DO NOT ask questions like "how should I fix this" — focus on missing information that prevents confident planning.
+Questions must present complete implementation choices, NOT request information from the user:
+options: array of strings
+- GOOD: options: ["Use Redux Toolkit (matches pattern in src/store/)", "Zustand (lighter weight)"]
+- BAD:  "Tell me which state management library to use"
+- GOOD: options: ["Place in Button.tsx (existing component)", "create NewButton.tsx (separate concerns)?"]
+- BAD: "Where should I put this code?"
+
+DO NOT ask questions like "how should I fix this" or "tell me the pattern" — present concrete options that can be directly chosen and acted upon.
 </objective>
 
 <process>
@@ -60,6 +67,9 @@ Rules:
 - questions: ONLY include if actionabilityScore < 0.7
 - Each question must have 2-3 options (maximum 3)
 - Max 3 questions total
+- Options must be complete, actionable choices that require NO additional user input
+- NEVER use options like "Tell me the pattern", "Show me examples", "Specify the approach"
+- Each option must be a full implementation decision that can be directly acted upon
 </output_format>
 
 <scoring_examples>
@@ -92,11 +102,25 @@ Questions needed: What feature? Which product area? What should it do?
   "id": "q1",
   "question": "Which caching layer should we use for API responses?",
   "options": [
-    "Redis (existing infrastructure, requires setup)",
-    "In-memory cache (simpler, but not distributed)",
-    "Browser-side caching only (minimal backend changes)"
+    "Redis with 1-hour TTL (existing infrastructure, requires Redis client setup)",
+    "In-memory LRU cache with 100MB limit (simpler, single-server only)",
+    "HTTP Cache-Control headers only (minimal backend changes, relies on browser/CDN)"
   ]
 }
+Reason: Each option is a complete, actionable decision with concrete details
+</good_example>
+
+<good_example>
+{
+  "id": "q2",
+  "question": "Where should the new analytics tracking code be placed?",
+  "options": [
+    "In the existing UserAnalytics.ts module alongside page view tracking",
+    "Create a new EventTracking.ts module in src/analytics/ for all event tracking",
+    "Add directly to each component that needs tracking (no centralized module)"
+  ]
+}
+Reason: Specific file paths and architectural patterns, no user input needed
 </good_example>
 
 <bad_example>
@@ -105,7 +129,33 @@ Questions needed: What feature? Which product area? What should it do?
   "question": "How should I implement this?",
   "options": ["One way", "Another way"]
 }
-Reason: Too vague, doesn't explain the tradeoffs
+Reason: Too vague, doesn't explain the tradeoffs or provide concrete details
+</bad_example>
+
+<bad_example>
+{
+  "id": "q2",
+  "question": "Which pattern should we follow for state management?",
+  "options": [
+    "Tell me which pattern the codebase currently uses",
+    "Show me examples of state management",
+    "Whatever you think is best"
+  ]
+}
+Reason: Options request user input instead of being actionable choices. Should be concrete patterns like "Zustand stores (matching existing patterns in src/stores/)" or "React Context (simpler, no new dependencies)"
+</bad_example>
+
+<bad_example>
+{
+  "id": "q3",
+  "question": "What color scheme should the button use?",
+  "options": [
+    "Use the existing theme colors",
+    "Let me specify custom colors",
+    "Match the design system"
+  ]
+}
+Reason: "Let me specify" requires user input. Should be "Primary blue (#0066FF, existing theme)" or "Secondary gray (#6B7280, existing theme)"
 </bad_example>
 </question_examples>`;
 

package/src/file-manager.ts

@@ -185,6 +185,36 @@ export class PostHogFileManager {
     }
   }
 
+  async writeTodos(taskId: string, data: any): Promise<void> {
+    this.logger.debug('Writing todos', {
+      taskId,
+      total: data.metadata?.total ?? 0,
+      completed: data.metadata?.completed ?? 0,
+    });
+
+    await this.writeTaskFile(taskId, {
+      name: 'todos.json',
+      content: JSON.stringify(data, null, 2),
+      type: 'artifact'
+    });
+
+    this.logger.info('Todos file written', {
+      taskId,
+      total: data.metadata?.total ?? 0,
+      completed: data.metadata?.completed ?? 0,
+    });
+  }
+
+  async readTodos(taskId: string): Promise<any | null> {
+    try {
+      const content = await this.readTaskFile(taskId, 'todos.json');
+      return content ? JSON.parse(content) : null;
+    } catch (error) {
+      this.logger.debug('Failed to parse todos.json', { error });
+      return null;
+    }
+  }
+
   async getTaskFiles(taskId: string): Promise<SupportingFile[]> {
     const fileNames = await this.listTaskFiles(taskId);
     const files: SupportingFile[] = [];

package/src/prompt-builder.ts

@@ -386,12 +386,16 @@ export class PromptBuilder {
     try {
       const taskFiles = await this.getTaskFiles(task.id);
       const hasPlan = taskFiles.some((f: any) => f.type === 'plan');
+      const todosFile = taskFiles.find((f: any) => f.name === 'todos.json');
 
       if (taskFiles.length > 0) {
         prompt += '\n<context>\n';
         for (const file of taskFiles) {
           if (file.type === 'plan') {
             prompt += `<plan>\n${file.content}\n</plan>\n`;
+          } else if (file.name === 'todos.json') {
+            // skip - we do this below
+            continue;
           } else {
             prompt += `<file name="${file.name}" type="${file.type}">\n${file.content}\n</file>\n`;
           }
@@ -399,6 +403,26 @@ export class PromptBuilder {
         prompt += '</context>\n';
       }
 
+      // Add todos context if resuming work
+      if (todosFile) {
+        try {
+          const todos = JSON.parse(todosFile.content);
+          if (todos.items && todos.items.length > 0) {
+            prompt += '\n<previous_todos>\n';
+            prompt += 'You previously created the following todo list for this task:\n\n';
+            for (const item of todos.items) {
+              const statusIcon = item.status === 'completed' ? '✓' : item.status === 'in_progress' ? '▶' : '○';
+              prompt += `${statusIcon} [${item.status}] ${item.content}\n`;
+            }
+            prompt += `\nProgress: ${todos.metadata.completed}/${todos.metadata.total} completed\n`;
+            prompt += '\nYou can reference this list when resuming work or create an updated list as needed.\n';
+            prompt += '</previous_todos>\n';
+          }
+        } catch (error) {
+          this.logger.debug('Failed to parse todos.json for context', { error });
+        }
+      }
+
       prompt += '\n<instructions>\n';
       if (hasPlan) {
         prompt += 'Implement the changes described in the execution plan. Follow the plan step-by-step and make the necessary file modifications.\n';

package/src/todo-manager.ts

@@ -0,0 +1,169 @@
+import type { PostHogFileManager } from './file-manager.js';
+import { Logger } from './utils/logger.js';
+
+export interface TodoItem {
+  content: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  activeForm: string;
+}
+
+export interface TodoList {
+  items: TodoItem[];
+  metadata: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+    last_updated: string;
+  };
+}
+
+export class TodoManager {
+  private fileManager: PostHogFileManager;
+  private logger: Logger;
+
+  constructor(fileManager: PostHogFileManager, logger?: Logger) {
+    this.fileManager = fileManager;
+    this.logger = logger || new Logger({ debug: false, prefix: '[TodoManager]' });
+  }
+
+  async readTodos(taskId: string): Promise<TodoList | null> {
+    try {
+      const content = await this.fileManager.readTaskFile(taskId, 'todos.json');
+      if (!content) {
+        return null;
+      }
+
+      const parsed = JSON.parse(content) as TodoList;
+      this.logger.debug('Loaded todos', {
+        taskId,
+        total: parsed.metadata.total,
+        pending: parsed.metadata.pending,
+        in_progress: parsed.metadata.in_progress,
+        completed: parsed.metadata.completed,
+      });
+
+      return parsed;
+    } catch (error) {
+      this.logger.debug('Failed to read todos.json', {
+        taskId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  async writeTodos(taskId: string, todos: TodoList): Promise<void> {
+    this.logger.debug('Writing todos', {
+      taskId,
+      total: todos.metadata.total,
+      pending: todos.metadata.pending,
+      in_progress: todos.metadata.in_progress,
+      completed: todos.metadata.completed,
+    });
+
+    await this.fileManager.writeTaskFile(taskId, {
+      name: 'todos.json',
+      content: JSON.stringify(todos, null, 2),
+      type: 'artifact',
+    });
+
+    this.logger.info('Todos saved', {
+      taskId,
+      total: todos.metadata.total,
+      completed: todos.metadata.completed,
+    });
+  }
+
+  parseTodoWriteInput(toolInput: any): TodoList {
+    const items: TodoItem[] = [];
+
+    if (toolInput.todos && Array.isArray(toolInput.todos)) {
+      for (const todo of toolInput.todos) {
+        items.push({
+          content: todo.content || '',
+          status: todo.status || 'pending',
+          activeForm: todo.activeForm || todo.content || '',
+        });
+      }
+    }
+
+    const metadata = this.calculateMetadata(items);
+
+    return { items, metadata };
+  }
+
+  private calculateMetadata(items: TodoItem[]): TodoList['metadata'] {
+    const total = items.length;
+    const pending = items.filter((t) => t.status === 'pending').length;
+    const in_progress = items.filter((t) => t.status === 'in_progress').length;
+    const completed = items.filter((t) => t.status === 'completed').length;
+
+    return {
+      total,
+      pending,
+      in_progress,
+      completed,
+      last_updated: new Date().toISOString(),
+    };
+  }
+
+  async getTodoContext(taskId: string): Promise<string> {
+    const todos = await this.readTodos(taskId);
+    if (!todos || todos.items.length === 0) {
+      return '';
+    }
+
+    const lines: string[] = ['## Previous Todo List\n'];
+    lines.push('You previously created the following todo list:\n');
+
+    for (const item of todos.items) {
+      const statusIcon =
+        item.status === 'completed' ? '✓' : item.status === 'in_progress' ? '▶' : '○';
+      lines.push(`${statusIcon} [${item.status}] ${item.content}`);
+    }
+
+    lines.push(
+      `\nProgress: ${todos.metadata.completed}/${todos.metadata.total} completed\n`
+    );
+
+    return lines.join('\n');
+  }
+
+  // check for TodoWrite tool call and persist if found
+  async checkAndPersistFromMessage(
+    message: any,
+    taskId: string
+  ): Promise<TodoList | null> {
+    if (message.type !== 'assistant' || !message.message?.content) {
+      return null;
+    }
+
+    for (const block of message.message.content) {
+      if (block.type === 'tool_use' && block.name === 'TodoWrite') {
+        try {
+          this.logger.info('TodoWrite detected, persisting todos', { taskId });
+
+          const todoList = this.parseTodoWriteInput(block.input);
+          await this.writeTodos(taskId, todoList);
+
+          this.logger.info('Persisted todos successfully', {
+            taskId,
+            total: todoList.metadata.total,
+            completed: todoList.metadata.completed,
+          });
+
+          return todoList;
+        } catch (error) {
+          this.logger.error('Failed to persist todos', {
+            taskId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          return null;
+        }
+      }
+    }
+
+    return null;
+  }
+}

package/src/workflow/steps/build.ts

@@ -3,6 +3,7 @@ import { EXECUTION_SYSTEM_PROMPT } from '../../agents/execution.js';
 import { PermissionMode } from '../../types.js';
 import type { WorkflowStepRunner } from '../types.js';
 import { finalizeStepGitActions } from '../utils.js';
+import { TodoManager } from '../../todo-manager.js';
 
 export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
     const {
@@ -82,12 +83,20 @@ export const buildStep: WorkflowStepRunner = async ({ step, context }) => {
     // Track commits made during Claude Code execution
     const commitTracker = await gitManager.trackCommitsDuring();
 
+    // Track todos from TodoWrite tool calls
+    const todoManager = new TodoManager(context.fileManager, stepLogger);
+
     for await (const message of response) {
         emitEvent(adapter.createRawSDKEvent(message));
         const transformed = adapter.transform(message);
         if (transformed) {
             emitEvent(transformed);
         }
+
+        const todoList = await todoManager.checkAndPersistFromMessage(message, task.id);
+        if (todoList) {
+            emitEvent(adapter.createArtifactEvent('todos', todoList));
+        }
     }
 
     // Finalize: commit any remaining changes and optionally push

package/src/workflow/steps/plan.ts

@@ -2,6 +2,7 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 import { PLANNING_SYSTEM_PROMPT } from '../../agents/planning.js';
 import type { WorkflowStepRunner } from '../types.js';
 import { finalizeStepGitActions } from '../utils.js';
+import { TodoManager } from '../../todo-manager.js';
 
 export const planStep: WorkflowStepRunner = async ({ step, context }) => {
     const {
@@ -96,6 +97,8 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
         options: { ...baseOptions, ...(options.queryOverrides || {}) },
     });
 
+    const todoManager = new TodoManager(fileManager, stepLogger);
+
     let planContent = '';
     for await (const message of response) {
         emitEvent(adapter.createRawSDKEvent(message));
@@ -103,10 +106,17 @@ export const planStep: WorkflowStepRunner = async ({ step, context }) => {
         if (transformed) {
             emitEvent(transformed);
         }
+
+        const todoList = await todoManager.checkAndPersistFromMessage(message, task.id);
+        if (todoList) {
+            emitEvent(adapter.createArtifactEvent('todos', todoList));
+        }
+
+        // Extract text content for plan
         if (message.type === 'assistant' && message.message?.content) {
-            for (const c of message.message.content) {
-                if (c.type === 'text' && c.text) {
-                    planContent += `${c.text}\n`;
+            for (const block of message.message.content) {
+                if (block.type === 'text' && block.text) {
+                    planContent += `${block.text}\n`;
                 }
             }
         }