Document --agent override behavior

Author: brandonkachen

README.md

@@ -61,7 +61,7 @@ Control how Codebuff runs with these flags:
 - `--print, -p` - Print-only mode, run once and exit (for scripts/CI)
 
 **Agent Control**:
-- `--agent <id>` - Run specific agent (e.g., `--agent file-picker`)
+- `--agent <id>` - Run specific agent (skips loading local `.agents` overrides)
 - `--spawn <id>` - Spawn agent directly (e.g., `--spawn reviewer`)
 - `--params <json>` - Pass JSON parameters to agent
 

cli/src/index.tsx

@@ -99,7 +99,7 @@ function parseArgs(): ParsedArgs {
     .version(loadPackageVersion(), '-v, --version', 'Print the CLI version')
     .option(
       '--agent <agent-id>',
-      'Specify which agent to use (e.g., "base", "ask", "file-picker")',
+      'Run a specific agent id (skips loading local .agents overrides)',
     )
     .option('--clear-logs', 'Remove any existing CLI log files before starting')
     .option(
@@ -180,7 +180,8 @@ async function main(): Promise<void> {
   const showProjectPicker =
     projectRoot === '/' || projectRoot === homeDir || gitRoot === null
 
-  // Initialize agent registry (loads user agents via SDK)
+  // Initialize agent registry (loads user agents via SDK).
+  // When --agent is provided, skip local .agents to avoid overrides.
   if (isPublishCommand || !hasAgentOverride) {
     await initializeAgentRegistry()
   }

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

@@ -5,7 +5,7 @@ Create specialized agent workflows that coordinate multiple AI agents to tackle
 ## 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`
+2. **Test your agent**: Run `codebuff` without `--agent` so local `.agents` load, then invoke your agent from a prompt
 3. **Publish your agent**: Run `codebuff publish your-agent-name`
 
 ## Need Help?
@@ -228,7 +228,7 @@ async *handleSteps() {
 
 ## Testing Your Agent
 
-1. **Local Testing**: `codebuff --agent your-agent-name`
+1. **Local Testing**: Run `codebuff` without `--agent` so local `.agents` load, then invoke your agent from a prompt
 2. **Debug Mode**: Add logging to your `handleSteps` function
 3. **Unit Testing**: Test individual functions in isolation
 4. **Integration Testing**: Test agent coordination workflows