Tweak readme to give actionable info at top

Author: jahooma

.agents/README.md

@@ -1,49 +1,56 @@
-# Codebuff Agents
+# Custom Agents
 
-This directory contains your custom Codebuff agents. Each agent is a TypeScript file that defines an AI agent with specific capabilities and behavior.
+Create specialized agent workflows that coordinate multiple AI agents to tackle complex engineering tasks. Instead of a single agent trying to handle everything, you can orchestrate teams of focused specialists that work together.
 
 ## Getting Started
 
 1. **Edit an existing agent**: Start with `my-custom-agent.ts` and modify it for your needs
-2. **Check out the examples and types**: See the examples and types directories to draw inspiration and learn what's possible.
-3. **Test your agent**: Run `codebuff --agent your-agent-name`
-4. **Publish your agent**: Run `codebuff publish your-agent-name`
+2. **Test your agent**: Run `codebuff --agent your-agent-name`
+3. **Publish your agent**: Run `codebuff publish your-agent-name`
 
-## File Structure
+## Need Help?
 
-- `types/` - TypeScript type definitions
-- `examples/` - Example agents for reference
-- `my-custom-agent.ts` - Your first custom agent (edit this!)
-- Add any new agents you wish to the .agents directory
+- For detailed documentation, see [agent-guide.md](./agent-guide.md).
+- For examples, check the `examples/` directory.
+- Join our [Discord community](https://codebuff.com/discord) and ask your questions!
 
-## Agent Basics
+## Context Window Management
 
-Each agent file exports an `AgentDefinition` object with:
+### Why Agent Workflows?
 
-- `id`: Unique identifier (lowercase, hyphens only)
-- `displayName`: Human-readable name
-- `model`: AI model to use (see OpenRouter for options)
-- `toolNames`: Tools the agent can use
-- `instructionsPrompt`: Instructions for the agent's behavior
-- `spawnerPrompt`: When other agents should spawn this one
-- `spawnableAgents`: Which agents *this* agent can spawn
+Modern software projects are complex ecosystems with thousands of files, multiple frameworks, intricate dependencies, and domain-specific requirements. A single AI agent trying to understand and modify such systems faces fundamental limitations—not just in knowledge, but in the sheer volume of information it can process at once.
 
-## Common Tools
+### The Solution: Focused Context Windows
 
-- `read_files` - Read file contents
-- `write_file` - Create or modify files
-- `str_replace` - Make targeted edits
-- `run_terminal_command` - Execute shell commands
-- `code_search` - Search for code patterns
-- `spawn_agents` - Delegate to other agents
-- `end_turn` - Finish the response
+Agent workflows elegantly solve this by breaking large tasks into focused sub-problems. When working with large codebases (100k+ lines), each specialist agent receives only the narrow context it needs—a security agent sees only auth code, not UI components—keeping the context for each agent manageable while ensuring comprehensive coverage.
 
-See `types/tools.ts` for more information on each tool!
+### Why Not Just Mimic Human Roles?
 
-## Need Help?
+This is about efficient AI context management, not recreating a human department. Simply creating a "frontend-developer" agent misses the point. AI agents don't have human constraints like context-switching or meetings. Their power comes from hyper-specialization, allowing them to process a narrow domain more deeply than a human could, then coordinating seamlessly with other specialists.
+
+## Agent workflows in action
+
+Here's an example of a `git-committer` agent that creates good commit messages:
+
+```typescript
+export default {
+  id: 'git-committer',
+  displayName: 'Git Committer',
+  model: 'openai/gpt-5-nano',
+  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],
+
+  instructionsPrompt:
+    'You create meaningful git commits by analyzing changes, reading relevant files for context, and crafting clear commit messages that explain the "why" behind changes.',
+
+  async *handleSteps() {
+    // Analyze what changed
+    yield { tool: 'run_terminal_command', command: 'git diff' }
+    yield { tool: 'run_terminal_command', command: 'git log --oneline -5' }
 
-- Check the type definitions in `types/agent-definition.ts`
-- Look at examples in the `examples/` directory
-- Join the Codebuff Discord community (https://discord.com/invite/mcWTGjgTj3)
+    // Stage files and create commit with good message
+    yield 'STEP_ALL'
+  },
+}
+```
 
-Happy agent building! 🤖
+This agent systematically analyzes changes, reads relevant files for context, then creates commits with clear, meaningful messages that explain the "why" behind changes.

.agents/types/agent-definition.ts

@@ -15,6 +15,7 @@
  */
 
 import type { Message } from './codebuff-message'
+import { ToolResultOutput } from './content-part'
 import type * as Tools from './tools'
 type ToolName = Tools.ToolName
 
@@ -184,7 +185,7 @@ export interface AgentDefinition {
     void,
     {
       agentState: AgentState
-      toolResult: string | undefined
+      toolResult: ToolResultOutput[] | undefined
       stepsComplete: boolean
     }
   >
@@ -324,6 +325,7 @@ export type ModelName =
 
   // X-AI
   | 'x-ai/grok-4-07-09'
+  | 'x-ai/grok-code-fast-1'
 
   // Qwen
   | 'qwen/qwen3-coder'

common/src/templates/initial-agents-dir/README.md

@@ -2,6 +2,18 @@
 
 Create specialized agent workflows that coordinate multiple AI agents to tackle complex engineering tasks. Instead of a single agent trying to handle everything, you can orchestrate teams of focused specialists that work together.
 
+## Getting Started
+
+1. **Edit an existing agent**: Start with `my-custom-agent.ts` and modify it for your needs
+2. **Test your agent**: Run `codebuff --agent your-agent-name`
+3. **Publish your agent**: Run `codebuff publish your-agent-name`
+
+## Need Help?
+
+- For detailed documentation, see [agent-guide.md](./agent-guide.md).
+- For examples, check the `examples/` directory.
+- Join our [Discord community](https://codebuff.com/discord) and ask your questions!
+
 ## Context Window Management
 
 ### Why Agent Workflows?
@@ -42,11 +54,3 @@ export default {
 ```
 
 This agent systematically analyzes changes, reads relevant files for context, then creates commits with clear, meaningful messages that explain the "why" behind changes.
-
-## Getting started
-
-Edit `my-custom-agent.ts` with your team's patterns, then run `codebuff --agent my-custom-agent` to test it.
-
-For detailed documentation, see [agent-guide.md](./agent-guide.md).
-For examples, check the `examples/` directory.
-For help, join our [Discord community](https://codebuff.com/discord).