Walkthrough for creating an agent!

Author: jahooma

web/src/components/docs/doc-sidebar.tsx

@@ -37,6 +37,15 @@ export const sections = [
     })),
     external: false,
   },
+  {
+    title: 'Walkthroughs',
+    href: '/docs/walkthroughs',
+    subsections: getDocsByCategory('walkthroughs').map((doc) => ({
+      title: doc.title,
+      href: `/docs/walkthroughs/${doc.slug}`,
+    })),
+    external: false,
+  },
   {
     title: 'Advanced',
     href: '/docs/advanced',

web/src/content/walkthroughs/creating-your-first-agent.mdx

@@ -0,0 +1,330 @@
+---
+title: 'Creating Your First Agent'
+section: 'walkthroughs'
+tags: ['walkthrough', 'agents', 'getting-started', 'publishing']
+order: 1
+---
+
+# Creating Your First Agent
+
+This walkthrough will guide you through creating, testing, and publishing your first custom agent. We'll build a simple code reviewer agent from scratch.
+
+## Step 1: Install and Initialize
+
+First, install Codebuff globally:
+
+```bash
+npm install -g codebuff
+```
+
+Then navigate to your project and run:
+
+```bash
+codebuff init-agents
+```
+
+This creates a `.agents` directory with:
+
+- Type definitions in `.agents/types/`
+- Example agents in `.agents/examples/`
+- A starter template: `.agents/my-custom-agent.ts`
+
+You should see output like:
+
+```
+📁 Creating agent files:
+  ✓ .agents/README.md - Documentation for your agents
+  ✓ .agents/types/agent-definition.ts - TypeScript type definitions for agents
+  ✓ .agents/my-custom-agent.ts - Your first custom agent example
+  ✓ .agents/examples/01-basic-diff-reviewer.ts - Basic diff reviewer agent example
+```
+
+## Step 2: Create Your Agent
+
+Create a new file `.agents/simple-code-reviewer.ts`:
+
+```typescript
+import type { AgentDefinition } from './types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'simple-code-reviewer',
+  displayName: 'Simple Code Reviewer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+
+  // Tools this agent can use
+  toolNames: [
+    'read_files',
+    'run_terminal_command',
+    'code_search',
+    'spawn_agents'
+  ],
+
+  // Other agents this agent can spawn
+  spawnableAgents: ['codebuff/file-explorer@0.0.2'],
+
+  // When should other agents spawn this one?
+  spawnerPrompt: 'Spawn when you need to review local code changes',
+
+  // System prompt defines the agent's identity
+  systemPrompt: \`You are an expert software developer specializing in code review.
+Your job is to review code changes and provide helpful, constructive feedback.\`,
+
+  // Instructions for what the agent should do
+  instructionsPrompt: \`Review code changes by following these steps:
+1. Use git diff to see what changed
+2. Read the modified files to understand the context
+3. Look for potential issues: bugs, security problems, style violations
+4. Suggest specific improvements with examples
+5. Highlight what was done well\`,
+}
+
+export default definition
+```
+
+## Step 3: Test Your Agent Locally
+
+Now test your agent with Codebuff:
+
+1. **Start Codebuff:**
+
+   ```bash
+   codebuff
+   ```
+
+2. **Have Codebuff spawn your agent using the @ command:**
+
+   ```
+   @Simple Code Reviewer please review my recent changes
+   ```
+
+3. **Watch it work:**
+   - Your spawned agent will run `git diff` to see changes
+   - Read the modified files
+   - Provide a detailed code review
+
+Make some changes to a file first to give it something to review!
+
+## Step 4: Create a Publisher Profile
+
+Before publishing, you need a publisher profile:
+
+1. **Visit the publisher creation page:**
+
+   Go to [https://www.codebuff.com/publishers/new](https://www.codebuff.com/publishers/new)
+
+2. **Choose ownership type:**
+   - **Personal**: Publish under your own name
+   - **Organization**: Publish under a team/company
+
+3. **Fill in basic information:**
+   - **Publisher Name**: Your display name (e.g., "John Smith")
+   - **Publisher ID**: URL-friendly identifier (e.g., "john-smith")
+   - **Email**: Contact email (optional)
+
+4. **Add profile details:**
+   - **Bio**: Brief description of yourself
+   - **Avatar**: Profile picture (optional)
+
+5. **Create your profile**
+
+## Step 5: Prepare for Publishing
+
+Add your publisher ID to your agent definition:
+
+```typescript
+// Add this field to your agent definition
+const definition: AgentDefinition = {
+  id: 'simple-code-reviewer',
+  displayName: 'Simple Code Reviewer',
+  publisher: 'your-publisher-id', // ← Add this line
+  model: 'anthropic/claude-4-sonnet-20250522',
+  // ... rest of your definition
+}
+```
+
+Replace \`'your-publisher-id'\` with the ID you created in Step 4.
+
+## Step 6: Publish Your Agent
+
+Publish your agent to the Codebuff store:
+
+```bash
+codebuff publish simple-code-reviewer
+```
+
+You should see:
+
+```
+Publishing:
+  - Simple Code Reviewer (simple-code-reviewer)
+✅ Successfully published:
+  - Simple Code Reviewer (your-publisher-id/simple-code-reviewer@1.0.0)
+```
+
+## Step 7: Test Your Published Agent
+
+Now anyone can use your agent:
+
+```bash
+codebuff --agent @your-publisher-id/simple-code-reviewer@0.0.1
+```
+
+## Advanced Example: Deep Code Reviewer
+
+Once you're comfortable with basic agents, try building something more sophisticated using **programmatic control**. Here's an advanced agent that demonstrates the power of the `handleSteps` generator function:
+
+`.agents/deep-code-reviewer.ts`:
+
+```typescript
+import type { AgentDefinition } from './types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'deep-code-reviewer',
+  displayName: 'Deep Code Reviewer',
+  publisher: 'your-publisher-id',
+  model: 'anthropic/claude-sonnet-4',
+
+  spawnerPrompt:
+    'Spawn when you need to review code changes in the git diff or staged changes',
+
+  toolNames: [
+    'read_files',
+    'code_search',
+    'run_terminal_command',
+    'spawn_agents',
+  ],
+
+  // Use fully qualified agent names with publisher and version
+  spawnableAgents: [
+    'codebuff/file-explorer@0.0.1',
+    'codebuff/deep-thinker@0.0.4',
+  ],
+
+  instructionsPrompt: `Review code changes comprehensively:
+1. Analyze git diff and untracked files
+2. Find related files using file explorer
+3. Use multiple perspectives for thorough review
+4. Look for simplification opportunities
+5. Check for logical errors and edge cases`,
+
+  // This is where the magic happens - programmatic control!
+  handleSteps: function* () {
+    // Step 1: Get changed files from git
+    const { toolResult: gitDiffResult } = yield {
+      toolName: 'run_terminal_command',
+      input: { command: 'git diff HEAD --name-only' },
+    }
+
+    // Step 2: Get untracked files
+    const { toolResult: gitStatusResult } = yield {
+      toolName: 'run_terminal_command',
+      input: { command: 'git status --porcelain' },
+    }
+
+    // Step 3: Show the actual diff
+    yield {
+      toolName: 'run_terminal_command',
+      input: { command: 'git diff HEAD' },
+    }
+
+    // Step 4: Parse file paths (with error handling)
+    const changedFiles = (gitDiffResult || '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line && !line.includes('OSC'))
+
+    const untrackedFiles = (gitStatusResult || '')
+      .split('\n')
+      .filter((line) => line.startsWith('??'))
+      .map((line) => line.substring(3).trim())
+      .filter((file) => file)
+
+    const allFiles = [...changedFiles, ...untrackedFiles]
+
+    // Step 5: Read all the files
+    if (allFiles.length > 0) {
+      yield {
+        toolName: 'read_files',
+        input: { paths: allFiles },
+      }
+    }
+
+    // Step 6: Spawn file explorer to find related files
+    yield {
+      toolName: 'spawn_agents',
+      input: {
+        agents: [
+          {
+            agent_type: 'codebuff/file-explorer@0.0.1',
+            prompt: 'Find files related to the changed code',
+          },
+        ],
+      },
+    }
+
+    // Step 7: Let the LLM generate the final review
+    yield 'STEP_ALL'
+  },
+}
+
+export default definition
+```
+
+### Understanding `handleSteps`
+
+The `handleSteps` generator function gives you **precise control** over your agent's execution:
+
+**Key Concepts:**
+
+1. **`yield` tool calls**: Execute tools and get results
+
+   ```typescript
+   const { toolResult, toolError } = yield {
+     toolName: 'run_terminal_command',
+     input: { command: 'git status' }
+   }
+   ```
+
+2. **`yield 'STEP_ALL'`**: Let the LLM take over and generate responses
+
+   ```typescript
+   yield 'STEP_ALL' // LLM runs until completion
+   ```
+
+3. **`yield 'STEP'`**: Let the LLM take one step, then return control
+
+   ```typescript
+   yield 'STEP' // LLM takes one turn, then back to your code
+   ```
+
+4. **`return`**: End the agent's execution immediately
+   ```typescript
+   return // Agent stops here
+   ```
+
+**When to Use Programmatic Control:**
+
+- **Complex workflows** with multiple steps
+- **Conditional logic** based on file contents
+- **Error handling** for tool failures
+- **Dynamic agent spawning** based on analysis
+- **Data transformation** between steps
+
+**When to Use Simple Prompts:**
+
+- **Straightforward tasks** with clear instructions
+- **Creative tasks** that benefit from LLM flexibility
+- **Quick prototypes** that don't need complex logic
+
+---
+
+🎉 **Congratulations!** You've successfully:
+
+- ✅ Created a custom agent from scratch
+- ✅ Tested it locally with the @ command
+- ✅ Set up a publisher profile
+- ✅ Published your agent to the store
+- ✅ Learned the basics of agent architecture
+- ✅ Explored advanced programmatic control with `handleSteps`
+
+You're now ready to build sophisticated agents and contribute to the Codebuff ecosystem!