Overhaul the example agents

Author: jahooma

.agents/changes-reviewer.ts

@@ -14,18 +14,19 @@ const definition: AgentDefinition = {
 
   includeMessageHistory: false,
 
+  spawnPurposePrompt:
+    'Spawn when you need to review code changes in the git diff or staged changes',
+
+  toolNames: ['read_files', 'run_terminal_command', 'spawn_agents'],
+  spawnableAgents: ['codebuff/file-explorer@0.0.1'],
+
   inputSchema: {
     prompt: {
       type: 'string',
       description:
         'Please provide a short description of the changes you want to review',
     },
   },
-  outputMode: 'last_message',
-
-  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],
-
-  spawnPurposePrompt: 'Spawn when you need to review code changes',
 
   systemPrompt:
     'You are an expert software developer. Your job is to review code changes and provide helpful feedback.',
@@ -102,7 +103,16 @@ Use the following guidelines to review the changes and suggest improvements:
       }
     }
 
-    // Step 7: Let AI review the changes (and take as many steps as needed)
+    // Step 5: Put words in the AI's mouth to get it to spawn the file explorer.
+    yield {
+      toolName: 'add_message',
+      args: {
+        role: 'assistant',
+        content:
+          'Now I will spawn a file explorer to find any missing codebase context, and then review the changes.',
+      },
+    }
+
     yield 'STEP_ALL'
   },
 }

.agents/examples/diff-reviewer-1.ts …gents/examples/01-basic-diff-reviewer.ts.agents/examples/diff-reviewer-1.ts renamed to .agents/examples/01-basic-diff-reviewer.ts .agents/examples/diff-reviewer-1.ts renamed to .agents/examples/01-basic-diff-reviewer.ts

@@ -1,8 +1,8 @@
 import type { AgentDefinition } from '../types/agent-definition'
 
 const definition: AgentDefinition = {
-  id: 'diff-reviewer-1',
-  displayName: 'Diff Reviewer (Level 1)',
+  id: 'basic-diff-reviewer',
+  displayName: 'Basic Diff Reviewer',
   model: 'anthropic/claude-4-sonnet-20250522',
   toolNames: ['read_files', 'run_terminal_command'],
 

.agents/git-committer.ts …xamples/02-intermediate-git-committer.ts.agents/git-committer.ts renamed to .agents/examples/02-intermediate-git-committer.ts .agents/git-committer.ts renamed to .agents/examples/02-intermediate-git-committer.ts

@@ -1,15 +1,11 @@
-import { publisher, version } from './constants'
-
 import type {
   AgentDefinition,
   AgentStepContext,
-} from './types/agent-definition'
+} from '../types/agent-definition'
 
 const definition: AgentDefinition = {
   id: 'git-committer',
-  version,
-  publisher,
-  displayName: 'Git Committer',
+  displayName: 'Intermediate Git Committer',
   model: 'anthropic/claude-4-sonnet-20250522',
   toolNames: ['read_files', 'run_terminal_command', 'add_message', 'end_turn'],
 
@@ -20,20 +16,17 @@ const definition: AgentDefinition = {
     },
   },
 
-  includeMessageHistory: false,
-  outputMode: 'last_message',
-
   spawnPurposePrompt:
     'Spawn when you need to commit code changes to git with an appropriate commit message',
 
   systemPrompt:
     'You are an expert software developer. Your job is to create a git commit with a really good commit message.',
 
   instructionsPrompt:
-    'Follow the steps to create a good commit: analyze changes with git diff and git log, read relevant files for context, stage appropriate files, analyze changes, and create a commit with proper formatting including the Codebuff footer.',
+    'Follow the steps to create a good commit: analyze changes with git diff and git log, read relevant files for context, stage appropriate files, analyze changes, and create a commit with proper formatting.',
 
   handleSteps: function* ({ agentState, prompt, params }: AgentStepContext) {
-    // Step 1: Run git diff and git log to analyze changes
+    // Step 1: Run git diff and git log to analyze changes.
     yield {
       toolName: 'run_terminal_command',
       args: {
@@ -52,7 +45,7 @@ const definition: AgentDefinition = {
       },
     }
 
-    // Step 2: Let AI analyze the changes and read relevant files for context
+    // Step 2: Put words in AI's mouth so it will read files next.
     yield {
       toolName: 'add_message',
       args: {
@@ -62,16 +55,16 @@ const definition: AgentDefinition = {
       },
     }
 
-    // Step 3: Let AI decide which files to read and stage
+    // Step 3: Let AI generate a step to decide which files to read.
     yield 'STEP'
 
-    // Step 4: Let AI analyze staged changes and compose commit message
+    // Step 4: Put words in AI's mouth to analyze the changes and create a commit.
     yield {
       toolName: 'add_message',
       args: {
         role: 'assistant',
         content:
-          "Now I'll analyze the staged changes and create a commit with the proper Codebuff footer format.",
+          "Now I'll analyze the changes and create a commit with a good commit message.",
       },
     }
 

.agents/examples/03-advanced-file-explorer.ts

@@ -0,0 +1,73 @@
+import type { AgentDefinition } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'advanced-file-explorer',
+  displayName: 'Dora the File Explorer',
+  model: 'openai/gpt-5',
+
+  spawnPurposePrompt:
+    'Spawns multiple file picker agents in parallel to comprehensively explore the codebase from different perspectives',
+
+  includeMessageHistory: false,
+  toolNames: ['spawn_agents', 'set_output'],
+  spawnableAgents: [`codebuff/file-picker@0.0.1`],
+
+  inputSchema: {
+    prompt: {
+      description: 'What you need to accomplish by exploring the codebase',
+      type: 'string',
+    },
+    params: {
+      type: 'object',
+      properties: {
+        prompts: {
+          description:
+            'List of 1-4 different parts of the codebase that could be useful to explore',
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+        },
+      },
+      required: ['prompts'],
+      additionalProperties: false,
+    },
+  },
+  outputMode: 'structured_output',
+  outputSchema: {
+    type: 'object',
+    properties: {
+      results: {
+        type: 'string',
+        description: 'The results of the file exploration',
+      },
+    },
+    required: ['results'],
+    additionalProperties: false,
+  },
+
+  handleSteps: function* ({ prompt, params }) {
+    const prompts: string[] = params?.prompts ?? []
+    const filePickerPrompts = prompts.map(
+        (focusPrompt) =>
+          `Based on the overall goal "${prompt}", find files related to this specific area: ${focusPrompt}`,
+      ),
+      { toolResult: spawnResult } = yield {
+        toolName: 'spawn_agents',
+        args: {
+          agents: filePickerPrompts.map((promptText) => ({
+            agent_type: 'codebuff/file-picker@0.0.1',
+            prompt: promptText,
+          })),
+        },
+      }
+    yield {
+      toolName: 'set_output',
+      args: {
+        results: spawnResult,
+      },
+    }
+  },
+}
+
+export default definition

.agents/examples/diff-reviewer-2.ts

@@ -7,13 +7,16 @@ const definition: AgentDefinition = {
   version,
   publisher,
   displayName: 'Dora the File Explorer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+
   spawnPurposePrompt:
     'Spawns multiple file picker agents in parallel to comprehensively explore the codebase from different perspectives',
-  model: 'anthropic/claude-4-sonnet-20250522',
-  outputMode: 'structured_output',
+
   includeMessageHistory: false,
   toolNames: ['spawn_agents', 'set_output'],
   spawnableAgents: [`file-picker`],
+
+  outputMode: 'structured_output',
   inputSchema: {
     prompt: {
       description: 'What you need to accomplish by exploring the codebase',
@@ -35,6 +38,18 @@ const definition: AgentDefinition = {
       additionalProperties: false,
     },
   },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      results: {
+        type: 'string',
+        description: 'The results of the file exploration',
+      },
+    },
+    required: ['results'],
+    additionalProperties: false,
+  },
+
   handleSteps: function* ({ prompt, params }) {
     const prompts: string[] = params?.prompts ?? []
     const filePickerPrompts = prompts.map(