fix: renamed examples to be more generic

Author: brandonkachen

.agents/sonnet4-agent-builder.ts

@@ -0,0 +1,149 @@
+import type { AgentConfig } from './types/agent-config'
+
+const config: AgentConfig = {
+  id: 'sonnet4-agent-builder',
+  displayName: 'Bob the Agent Builder',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  inputSchema: {
+    prompt: {
+      description: 'What agent type you would like to create or edit.',
+      type: 'string',
+    },
+  },
+  outputMode: 'json',
+  includeMessageHistory: false,
+  toolNames: [
+    'write_file',
+    'str_replace',
+    'run_terminal_command',
+    'read_files',
+    'code_search',
+    'spawn_agents',
+    'add_message',
+    'set_output',
+    'end_turn',
+  ],
+  subagents: ['file-picker'],
+  parentPrompt:
+    'Creates new agent templates for the codebuff mult-agent system',
+  systemPrompt:
+    '# Agent Builder\n\nYou are an expert agent builder specialized in creating new agent templates for the codebuff system. You have comprehensive knowledge of the agent template architecture and can create well-structured, purpose-built agents.\n\n## Agent Template Patterns\n\n1. **Base Agent Pattern**: Full-featured agents with comprehensive tool access\n2. **Specialized Agent Pattern**: Focused agents with limited tool sets\n3. **Thinking Agent Pattern**: Agents that spawn thinker sub-agents\n4. **Research Agent Pattern**: Agents that start with web search\n\n## Best Practices\n\n1. **Use as few fields as possible**: Leave out fields that are not needed to reduce complexity\n2. **Minimal Tools**: Only include tools the agent actually needs\n3. **Clear and Concise Prompts**: Write clear, specific prompts that have no unnecessary words\n4. **Consistent Naming**: Follow naming conventions (kebab-case for IDs)\n5. **Appropriate Model**: Choose the right model for the task complexity\n\n## Your Task\n\nWhen asked to create an agent template, you should:\n1. Understand the requested agent\'s purpose and capabilities\n2. Choose appropriate tools for the agent\'s function\n3. Write a comprehensive system prompt\n4. Create the complete agent template file in .agents/\n5. Ensure the template follows all conventions and best practices\n6. Use the AgentConfig interface for the configuration\n7. Start the file with: import type { AgentConfig } from "./types/agent-config"\n\nCreate agent templates that are focused, efficient, and well-documented. Always import the AgentConfig type and export a default configuration object.',
+  instructionsPrompt:
+    "You are helping to create or edit an agent template. The user will describe what kind of agent they want to create or how they want to modify an existing agent.\n\n## Example Agents for Reference\n\nYou have access to three example agents in `.agents/examples/` that demonstrate different complexity levels:\n\n1. **Level 1 - Code Reviewer**: Simple agent with basic tools (read_files, write_file, set_output, end_turn)\n2. **Level 2 - Test Generator**: Intermediate agent with subagents and handleSteps logic\n3. **Level 3 - Documentation Writer**: Advanced agent with comprehensive tools, multiple subagents, and complex orchestration\n\n**IMPORTANT**: When creating new agents, first examine these examples to find connections and patterns that relate to the user's request. Look for:\n- Similar tool combinations\n- Comparable complexity levels\n- Related functionality patterns\n- Appropriate model choices\n- Relevant prompt structures\n\nUse these examples as inspiration and starting points, adapting their patterns to fit the user's specific needs.\n\nFor new agents, analyze their request and create a complete agent template that:\n- Has a clear purpose and appropriate capabilities\n- Leaves out fields that are not needed\n- Uses only the tools it needs\n- Follows naming conventions\n- Is properly structured\n- Draws inspiration from relevant example agents\n\nFor editing existing agents:\n- First read the existing agent file they want to edit using read_files\n- Understand the current structure and functionality\n- Make the requested changes while preserving what works\n- Maintain best practices and ensure the agent still works effectively\n- Use str_replace for targeted edits or write_file for major restructuring\n\nWhen editing, always start by reading the current agent file to understand its structure before making changes. Ask clarifying questions if needed, then create or update the template file in the appropriate location.\n\nIMPORTANT: Always end your response with the end_turn tool when you have completed the agent creation or editing task.",
+  stepPrompt: '',
+
+  // Generator function that defines the agent's execution flow
+  handleSteps: function* ({ agentState, prompt, params }) {
+    const AGENT_TEMPLATES_DIR = '.agents'
+    const TYPES_DIR = `${AGENT_TEMPLATES_DIR}/types`
+    const TEMPLATE_TYPES_PATH = `${TYPES_DIR}/agent-config.d.ts`
+    const TOOL_DEFINITIONS_PATH = `${TYPES_DIR}/tools.d.ts`
+
+    // Step 1: Create directory structure
+    yield {
+      toolName: 'run_terminal_command',
+      args: {
+        command: `mkdir -p ${TYPES_DIR}`,
+        process_type: 'SYNC',
+        timeout_seconds: 10,
+      },
+    }
+
+    // Step 2: Read and write the agent config template
+    const { toolResult: configResult } = yield {
+      toolName: 'read_files',
+      args: {
+        paths: ['common/src/util/types/agent-config.ts'],
+      },
+    }
+
+    if (configResult?.result) {
+      yield {
+        toolName: 'write_file',
+        args: {
+          path: TEMPLATE_TYPES_PATH,
+          instructions: 'Create agent template type definitions file',
+          content: configResult.result,
+        },
+      }
+    }
+
+    // Step 3: Read and write the tools definitions
+    const { toolResult: toolsResult } = yield {
+      toolName: 'read_files',
+      args: {
+        paths: ['common/src/util/types/tools.d.ts'],
+      },
+    }
+
+    if (toolsResult?.result) {
+      yield {
+        toolName: 'write_file',
+        args: {
+          path: TOOL_DEFINITIONS_PATH,
+          instructions: 'Create tools type file',
+          content: toolsResult.result,
+        },
+      }
+    }
+
+    // Step 4: Copy example agents for reference
+    const { toolResult: exampleAgentsResult } = yield {
+      toolName: 'read_files',
+      args: {
+        paths: [
+          'common/src/util/example-1.ts',
+          'common/src/util/example-2.ts',
+          'common/src/util/example-3.ts',
+        ],
+      },
+    }
+
+    if (exampleAgentsResult?.result) {
+      const exampleFiles = exampleAgentsResult.result
+        .split('\n\n')
+        .filter(Boolean)
+
+      // Write example 1
+      if (exampleFiles[0]) {
+        yield {
+          toolName: 'write_file',
+          args: {
+            path: `${AGENT_TEMPLATES_DIR}/example-1.ts`,
+            instructions: 'Copy example 1 agent',
+            content: exampleFiles[0],
+          },
+        }
+      }
+
+      // Write example 2
+      if (exampleFiles[1]) {
+        yield {
+          toolName: 'write_file',
+          args: {
+            path: `${AGENT_TEMPLATES_DIR}/example-2.ts`,
+            instructions: 'Copy example 2 agent',
+            content: exampleFiles[1],
+          },
+        }
+      }
+
+      // Write example 3
+      if (exampleFiles[2]) {
+        yield {
+          toolName: 'write_file',
+          args: {
+            path: `${AGENT_TEMPLATES_DIR}/example-3.ts`,
+            instructions: 'Copy example 3 agent',
+            content: exampleFiles[2],
+          },
+        }
+      }
+    }
+
+    // Step 5: Let the agent ask questions and understand what the user wants
+    yield 'STEP_ALL'
+  },
+}
+
+export default config

.agents/types/agent-config.d.ts

@@ -4,18 +4,16 @@
  * This file provides TypeScript type definitions for creating custom Codebuff agents.
  * Import these types in your agent files to get full type safety and IntelliSense.
  *
- * Usage:
- *   import { AgentConfig, ToolName, ModelName } from './agent-config'
+ * Usage in .agents/your-agent.ts:
+ *   import { AgentConfig, ToolName, ModelName } from './types/agent-config'
  *
  *   const config: AgentConfig = {
- *     // Your agent configuration with full type safety
+ *     // ... your agent configuration with full type safety ...
  *   }
+ *   
+ *   export default config
  */
 
-import type * as Tools from './tools'
-export type { Tools }
-type ToolName = Tools.ToolName
-
 // ============================================================================
 // Core Agent Configuration Types
 // ============================================================================
@@ -43,26 +41,6 @@ export interface AgentConfig {
   /** Other agents this agent can spawn. */
   subagents?: SubagentName[]
 
-  // ============================================================================
-  // Prompts
-  // ============================================================================
-
-  /** Prompt for when to spawn this agent as a subagent. Include the main purpose and use cases.
-   * This field is key if the agent is a subagent and intended to be spawned. */
-  parentPrompt?: string
-
-  /** Background information for the agent. Fairly optional. Prefer using instructionsPrompt for agent instructions. */
-  systemPrompt?: string
-
-  /** Instructions for the agent.
-   * IMPORTANT: Updating this prompt is the best way to shape the agent's behavior.
-   * This prompt is inserted after each user input. */
-  instructionsPrompt?: string
-
-  /** Prompt inserted at each agent step. Powerful for changing the agent's behavior,
-   * but usually not necessary for smart models. Prefer instructionsPrompt for most instructions. */
-  stepPrompt?: string
-
   // ============================================================================
   // Input and Output
   // ============================================================================
@@ -78,21 +56,50 @@ export interface AgentConfig {
     params?: JsonSchema
   }
 
-  /** Whether to include conversation history. Defaults to false.
+  /** Whether to include conversation history from the parent agent in context.
+   * 
+   * Defaults to false.
    * Use this if the agent needs to know all the previous messages in the conversation.
    */
   includeMessageHistory?: boolean
 
   /** How the agent should output a response to its parent (defaults to 'last_message')
+   * 
    * last_message: The last message from the agent, typcically after using tools.
+   * 
    * all_messages: All messages from the agent, including tool calls and results.
+   * 
    * json: Make the agent output a JSON object. Can be used with outputSchema or without if you want freeform json output.
    */
   outputMode?: 'last_message' | 'all_messages' | 'json'
 
   /** JSON schema for structured output (when outputMode is 'json') */
   outputSchema?: JsonSchema
 
+  // ============================================================================
+  // Prompts
+  // ============================================================================
+
+  /** Prompt for when to spawn this agent as a subagent. Include the main purpose and use cases.
+   * 
+   * This field is key if the agent is a subagent and intended to be spawned. */
+  parentPrompt?: string
+
+  /** Background information for the agent. Fairly optional. Prefer using instructionsPrompt for agent instructions. */
+  systemPrompt?: string
+
+  /** Instructions for the agent.
+   * 
+   * IMPORTANT: Updating this prompt is the best way to shape the agent's behavior.
+   * This prompt is inserted after each user input. */
+  instructionsPrompt?: string
+
+  /** Prompt inserted at each agent step.
+   * 
+   * Powerful for changing the agent's behavior, but usually not necessary for smart models.
+   * Prefer instructionsPrompt for most instructions. */
+  stepPrompt?: string
+
   // ============================================================================
   // Handle Steps
   // ============================================================================
@@ -298,3 +305,7 @@ export type SubagentName =
   | 'thinker'
   | 'reviewer'
   | (string & {})
+
+import type * as Tools from './tools'
+export type { Tools }
+type ToolName = Tools.ToolName

backend/src/templates/agents/agent-aware-base.ts

@@ -57,23 +57,27 @@ export const agentAwareBase = (
   const exampleAgentContents: Record<string, string> = {}
 
   try {
-    const exampleAgentsDir = path.join(
-      __dirname,
-      '../../../../common/src/util/example-agents',
-    )
-    const files = fs.readdirSync(exampleAgentsDir)
+    const exampleAgentsDir = path.join(__dirname, `${COMMON_UTIL_PATH}`)
+    // Check if directory exists before trying to read it
+    if (fs.existsSync(exampleAgentsDir)) {
+      const files = fs.readdirSync(exampleAgentsDir)
 
-    files
-      .filter((file) => file.endsWith('.ts'))
-      .forEach((filename) => {
-        try {
-          const fullPath = path.join(exampleAgentsDir, filename)
-          const content = fs.readFileSync(fullPath, 'utf8')
-          exampleAgentContents[filename] = content
-        } catch (error) {
-          console.warn(`Could not read example agent ${filename}:`, error)
-        }
-      })
+      files
+        .filter((file) => file.endsWith('.ts') && file.startsWith('example-'))
+        .forEach((filename) => {
+          try {
+            const fullPath = path.join(exampleAgentsDir, filename)
+            const content = fs.readFileSync(fullPath, 'utf8')
+            exampleAgentContents[filename] = content
+          } catch (error) {
+            console.warn(`Could not read example agent ${filename}:`, error)
+          }
+        })
+    } else {
+      console.warn(
+        `Example agents directory does not exist: ${exampleAgentsDir}`,
+      )
+    }
   } catch (error) {
     console.warn('Could not read example agents directory:', error)
   }
@@ -216,9 +220,9 @@ You can now proceed directly to agent creation or editing.
 
 Three example agents are now available in your \`.agents/\` directory:
 
-1. **level-1-code-reviewer.ts**: Simple agent with basic tools (read_files, write_file, set_output, end_turn)
-2. **level-2-test-generator.ts**: Intermediate agent with subagents and handleSteps logic
-3. **level-3-documentation-writer.ts**: Advanced agent with comprehensive tools, multiple subagents, and complex orchestration
+1. **example-1.ts**: Simple agent with basic tools (read_files, write_file, set_output, end_turn)
+2. **example-2.ts**: Intermediate agent with subagents and handleSteps logic
+3. **example-3.ts**: Advanced agent with comprehensive tools, multiple subagents, and complex orchestration
 
 **IMPORTANT**: Examine these examples to find connections and patterns that relate to the user's request. Look for:
 - Similar tool combinations
@@ -260,6 +264,7 @@ IMPORTANT: Always end your response with the end_turn tool when you have complet
           command: `mkdir -p ${TYPES_DIR}`,
           process_type: 'SYNC',
           timeout_seconds: 10,
+          cb_easp: false,
         },
       }
 
@@ -270,6 +275,7 @@ IMPORTANT: Always end your response with the end_turn tool when you have complet
           path: TEMPLATE_TYPES_PATH,
           instructions: 'Create agent template type definitions file',
           content: agentTemplateContent,
+          cb_easp: false,
         },
       }
 
@@ -280,6 +286,7 @@ IMPORTANT: Always end your response with the end_turn tool when you have complet
           path: TOOL_DEFINITIONS_PATH,
           instructions: 'Create tools type file',
           content: toolDefinitionsContent,
+          cb_easp: false,
         },
       }
 
@@ -290,6 +297,7 @@ IMPORTANT: Always end your response with the end_turn tool when you have complet
           role: 'assistant',
           content:
             "I'll read the example agent files to understand the patterns and then help you create your agent.",
+          cb_easp: false,
         },
       }
 
@@ -299,9 +307,10 @@ IMPORTANT: Always end your response with the end_turn tool when you have complet
           yield {
             toolName: 'write_file',
             args: {
-              path: `${AGENT_TEMPLATES_DIR}/${filename}`,
+              path: `${AGENT_TEMPLATES_DIR}${filename}`,
               instructions: `Copy example agent file ${filename}`,
               content: content,
+              cb_easp: false,
             },
           }
         }