docs(agents): finalize agent docs refresh and clean up content

Consolidate and refine agent documentation across pages (agent-reference, creating-new-agents, customizing-agents); clarify control flow, add domain-specific guidance, and normalize formatting.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

web/src/content/agents/agent-reference.mdx

@@ -12,9 +12,13 @@ Complete reference for all agent configuration fields and tools.
 ## Key Terms
 
 **Agent Template:** JSON file defining agent behavior
+
 **Spawnable Agents:** Sub-agents this agent can create
+
 **Tool Names:** Capabilities (read files, run commands, etc.)
+
 **Output Mode:** Response format (last message, report, all messages)
+
 **Prompt Schema:** Input validation rules
 
 ## Agent Configuration
@@ -206,13 +210,15 @@ Programmatically control the agent's execution using a TypeScript generator func
 
 **What You Can Yield:**
 
+<MarkdownTable>
 | Yield Value | What It Does |
 |------------|-------------|
 | Tool call object | Execute a specific tool and get its result |
-| `'STEP'` | Run agent's LLM for one generation step |
-| `'STEP_ALL'` | Let agent run until completion |
-| `return` | End the agent's turn immediately |
-  
+| 'STEP' | Run agent's LLM for one generation step |
+| 'STEP_ALL' | Let agent run until completion |
+| return | End the agent's turn immediately |
+</MarkdownTable>
+
 **Tool Call Pattern:**
 ```typescript
 const { toolResult, toolError } = yield {
@@ -240,7 +246,7 @@ handleSteps: function* ({ agentState, prompt, params }) {
       }]
     }
   }
-  
+
   // Let the agent take over from here
   yield 'STEP_ALL'
 }
@@ -282,7 +288,7 @@ JSON Schema definitions for validating prompt and params when spawning the agent
       toolName: 'read_files',
       input: { paths: files.slice(0, 10) }
   }
-    
+
     // 3. Conditionally spawn different agents based on content
     if (fileContents?.includes('security')) {
       yield {

web/src/content/agents/creating-new-agents.mdx

@@ -308,22 +308,3 @@ handleSteps: function* ({ agentState, prompt, params }) {
 - Agent needs creative freedom
 - Natural language understanding is key
 - Workflow is simple and linear
-
-```
-**.agents/prompts/doc-writer-system.md**
-}
-
-**.agents/prompts/migration-guidelines.md**
-You can also reference external files for prompts:
-
-```typescript
-systemPrompt: {
-  path: "./prompts/doc-writer-system.md"
-## Programmatic Agents
-**Coming Soon** - Use JavaScript/TypeScript for complex orchestration logic.
-## Best Practices
-1. **Start small** - Begin with simple agents before complex ones
-2. **Experiment** - Try different tool/prompt combinations
-3. **Share** - Version control your `.agents/` directory
-4. **Iterate** - Improve based on usage
-5. **Coordinate agents** - Use `spawnerPrompt` to help other agents understand when to spawn your agent

web/src/content/agents/customizing-agents.mdx

@@ -21,28 +21,7 @@ Create specialized agents from scratch using TypeScript files in the `.agents/`
 
 Agents adapt to your specific workflow and project needs.
 
-Keep in mind you'll get the most value from agents if you treat them as context window managers. Design them to orchestrate and sequence work so the right files, facts, and decisions are in scope at each step. Break tasks into steps and build agents around controlling that flow — instead of trying to replicate human specialties.
-
-<MarkdownTable>
-| Aspect | Context manager agents | Specialty reviewer agents |
-| --- | --- | --- |
-| Primary job | Orchestrate multi-step workflows and manage context | Perform deep, targeted reviews or focused changes |
-| Best for | Cross-cutting tasks across many files/systems | Narrow audits or checks inside a workflow |
-| Spawns others | ✅ Often (researchers, reviewers, fixers) | ➖ Usually spawned by a manager |
-| State & checkpoints | Owns plan, state, and checkpoints | Stateless or minimal state |
-| Typical tools | read_files, code_search, spawn_agents, run_terminal_command, end_turn | read_files, code_search, str_replace (surgical diffs) |
-| Output style | Plans, orchestrated diffs, verification steps | Findings, specific diffs, pass/fail signals |
-| Examples | Migration Coordinator, PR Shepherd, Incident Triage Conductor, Release Cut Captain | Accessibility Reviewer, API Contract Enforcer, Performance Auditor, Security Reviewer |
-| When to use | Complex multi-file changes needing coordination | Precise validation or localized refactors |
-</MarkdownTable>
-
-Design checklist (use this to shape agents around task breakdown and context control):
-- Define the end state: what must be true when done?
-- List concrete steps; group them into phases (plan → edit → verify)
-- For each step: what files/data must be in context? how will you prove success?
-- Decide which steps spawn subagents (reviewer, researcher, fixer) vs. inline logic
-- Capture state and checkpoints so you can resume/recover deterministically
-- Prefer small, surgical diffs; verify before moving to the next phase
+Keep in mind you'll get the most value from agents if you treat them as context window managers. Design them to orchestrate and sequence work so the right files, facts, and decisions are in scope at each step. Break tasks into steps and build agents around controlling that flow instead of trying to replicate human specialties.
 
 **Tip:** Use specialty reviewers as spawnable subagents that your context-manager agent calls at the right time in the workflow.