mvp-factory-openhands/claude-code-subagents-doc.md

# Claude Code Sub-Agents - Efficiency & Cost Optimization Guide

**Purpose:** Effectively use Claude Code sub-agents for AI Dev Factory project development

---

## 🤖 Claude Code Sub-Agents Overview

### What Are Sub-Agents?
Sub-agents are specialized AI agents within Claude Code that handle specific tasks:

- **File Editor** - Create, edit, view, and analyze files
- **Bash Runner** - Execute shell commands, manage services, run tests
- **Search Agent** - Find files, code patterns, and search content
- **Explore Agent** - Deep codebase exploration and analysis
- **Plan Agent** - Create implementation plans and break down tasks
- **General-Purpose Agent** - Complex multi-step tasks
- **Code Analyzer** - Review code structure and architecture

### Benefits for AI Dev Factory
- ✅ **Targeted Actions** - Each sub-agent optimized for specific tasks
- ✅ **Cost Efficiency** - Focused tasks = fewer tokens
- ✅ **Faster Execution** - Specialized agents work quicker
- ✅ **Better Results** - Right tool for the right job
- ✅ **Parallel Execution** - Run multiple sub-agents concurrently
- ✅ **Error Prevention** - Specialized checks catch issues early

---

## 🛠️ Claude Code Sub-Agents Reference

### 1. File Editor Agent

**Purpose:** Create, edit, view, and analyze files

**Best For:**
- Creating documentation (MD files)
- Writing configuration files
- Editing code files
- File comparison and analysis

**Example Usage:**
```
Task: "Create a Node.js package.json with Express and TypeScript dependencies"
→ Uses: File Editor agent
Result: Optimized package.json with correct dependencies
```

**Cost-Saving Tips:**
- Be specific about file location and content
- Specify exact dependencies instead of "latest versions"
- Include version constraints to avoid unnecessary updates

### 2. Bash Runner Agent

**Purpose:** Execute shell commands and manage system operations

**Best For:**
- Starting/stopping services (Docker, systemd)
- Running tests and builds
- Checking service status
- Service management

**Example Usage:**
```
Task: "Check status of all Docker services: caddy, gitea, n8n, postgres"
→ Uses: Bash Runner agent
Result: Service status table with health indicators
```

**Cost-Saving Tips:**
- Group related commands into single task
- Use specific commands instead of "check everything"
- Avoid verbose output unless needed

### 3. Search Agent (Grep)

**Purpose:** Find files, code patterns, and search content efficiently

**Best For:**
- Finding specific code patterns
- Locating configuration files
- Searching for error messages
- Finding function/class definitions

**Example Usage:**
```
Task: "Find all files containing 'workflow' in /home/bam/claude/mvp-factory/"
→ Uses: Search Agent
Result: List of files with line numbers and context
```

**Cost-Saving Tips:**
- Use specific patterns instead of generic terms
- Limit search scope to relevant directories
- Use file type filters (*.md, *.js, *.py)

### 4. Explore Agent

**Purpose:** Deep codebase exploration and architecture analysis

**Best For:**
- Understanding project structure
- Analyzing architecture decisions
- Finding related components
- Comprehensive code review

**Example Usage:**
```
Task: "Analyze the n8n workflow structure in /home/bam/claude/mvp-factory/
Find patterns in node configurations and connections"
→ Uses: Explore agent
Result: Detailed architecture analysis with recommendations
```

**Cost-Saving Tips:**
- Use for complex analysis only
- Break large projects into smaller exploration tasks
- Specify what you want to understand specifically

### 5. Plan Agent

**Purpose:** Create implementation plans and break down complex tasks

**Best For:**
- Planning new features
- Breaking down Phase 3 implementation
- Task decomposition
- Roadmap creation

**Example Usage:**
```
Task: "Create implementation plan for Phase 3 autonomous build test
Break down into actionable steps with time estimates"
→ Uses: Plan agent
Result: Detailed 11-step implementation plan
```

**Cost-Saving Tips:**
- Use once per major feature
- Reference existing plans instead of recreating
- Focus on implementation details, not theory

### 6. General-Purpose Agent

**Purpose:** Handle complex multi-step tasks that require coordination

**Best For:**
- Complex debugging scenarios
- Multi-service integration tasks
- End-to-end testing workflows
- Complex system configuration

**Example Usage:**
```
Task: "Debug n8n workflow data preservation issue
Analyze SSH node behavior and suggest solutions"
→ Uses: General-Purpose agent
Result: Complete debugging report with working solution
```

**Cost-Saving Tips:**
- Use only when other agents can't handle it
- Break into smaller sub-tasks when possible
- Be very specific about the problem

---

## 💰 Cost Optimization Strategies

### 1. Token Budget Management

**Strategy: Progressive Token Allocation**

```
Initial Task: 500 tokens
Retry with Context: +250 tokens (750 total)
Detailed Debugging: +250 tokens (1000 total)
Complex Analysis: +500 tokens (1500 total)
```

**Implementation:**
- Start with minimal context
- Add context only when needed
- Avoid unnecessary explanation in prompts
- Use "compact mode" for routine tasks

**Example:**
```bash
# Instead of:
"Please analyze the entire codebase structure and provide detailed recommendations"

# Use:
"Find all workflow files in /home/bam/claude/mvp-factory/ and list their purposes"
```

### 2. Efficient Task Formulation

**❌ High-Cost Approach:**
```
Task: "Analyze the entire AI Dev Factory project, understand all components,
review documentation, check for issues, and provide recommendations"
```

**✅ Low-Cost Approach:**
```bash
Task: "Find all .md files in /home/bam/claude/mvp-factory/ and list their topics"
Task: "Check if all Phase 2 documentation is complete"
Task: "Review Phase 3 implementation checklist"
```

**Why:** Smaller, specific tasks = fewer tokens = lower cost

### 3. Use Structured Commands

**✅ Instead of:**
```
"Please look at my code and see if there are any issues"
```

**✅ Use:**
```bash
Task: "Search for TODO comments in /home/bam/claude/mvp-factory/"
Task: "Find all files modified after Phase 2 completion"
Task: "Check if all API keys are documented"
```

### 4. Leverage File Editor for Batch Operations

**Efficient Pattern:**
```bash
Task: "Create package.json for n8n workflow testing"
Task: "Create workflow configuration file"
Task: "Update CLAUDE.md with new reference"
```

**Instead of One Large Task:**
```bash
Task: "Create test infrastructure, update docs, and configure workflow"
```

### 5. Cache & Reuse Context

**Strategy:**
- Keep files organized for easy access
- Reference existing files instead of recreating
- Use consistent file locations
- Document decisions for future reference

**Example:**
```bash
# Reference existing plan instead of creating new
Task: "Update phase3.md with progress from Step 1"
Task: "Mark Step 2 as completed in todo list"
```

---

## ⏱️ Time Reduction Techniques

### 1. Parallel Sub-Agent Execution

**OpenHands Can Run Multiple Sub-Agents Concurrently:**
```bash
Task: [
  "Check Docker services status",
  "Find all workflow documentation",
  "List n8n workflows via API"
]
→ Runs in parallel = 3x faster
```

**When to Use Parallel:**
- Independent tasks
- Checking multiple services
- Searching different directories
- Verifying multiple configurations

**When NOT to Use Parallel:**
- Dependent tasks (B needs A's output)
- Complex analysis requiring sequential steps
- Tasks that modify the same files

### 2. Incremental Analysis

**Instead of Full Analysis:**
```bash
Task: "Analyze entire codebase structure"
```

**Use Incremental:**
```bash
Task: "Check if any files changed since last review"
Task: "Find new files added to project"
Task: "Review modified documentation only"
```

### 3. Smart Command Grouping

**Group Related Commands:**
```bash
# Instead of 3 separate tasks:
Task: "Check n8n status"
Task: "Check Gitea status"
Task: "Check Caddy status"

# Use one task:
Task: "Check status of all Docker services: n8n, gitea, caddy, postgres
Report which are running and which have issues"
```

### 4. Pre-configured Task Templates

**Common Tasks Template:**
```bash
# Service Status Check
Task: "Check status of Docker services in /home/bam/services/services-stack/
List running, stopped, and unhealthy services"

# Documentation Check
Task: "Check if all Phase 3 documentation is present:
phase3.md, implementation steps, success criteria"

# API Health Check
Task: "Verify n8n API is accessible: curl https://n8n.oky.sh/api/v1/workflows"
```

---

## 🎯 Best Practices for AI Dev Factory Project

### 1. Documentation Tasks

**Efficient Pattern:**
```bash
Task: "Create implementation plan for Step X of Phase 3
Include: prerequisites, commands, verification, troubleshooting"

Task: "Update todo list with completed tasks
Mark Step X as completed, add next steps"

Task: "Create checklist for testing Phase 3 workflow
Include: success criteria, test scenarios, verification steps"
```

### 2. Code Review Tasks

**Use Targeted Reviews:**
```bash
Task: "Review n8n workflow configuration for data preservation issues
Check if $node pattern is used correctly"

Task: "Verify all API keys are documented with proper locations
Check .env, .n8n_api_key, SSH keys"

Task: "Review Phase 3 implementation for missing components
Check if all 11 workflow nodes are defined"
```

### 3. Testing Tasks

**Systematic Testing:**
```bash
Task: "Test SDK wrapper: sh /home/bam/openhands-sdk-wrapper-sh.sh 'Create test file'
Verify output format and exit codes"

Task: "Test n8n webhook: curl -X POST https://n8n.oky.sh/webhook/openhands-fixed-test
Check if workflow executes and returns success"

Task: "Verify data preservation: Check if repo data is preserved after SSH node
Review node configuration and output"
```

### 4. Debugging Tasks

**Efficient Debugging:**
```bash
# Step 1: Identify the problem
Task: "Check n8n execution logs for recent workflow runs
Find any failed nodes or error messages"

# Step 2: Analyze the issue
Task: "Review SSH node configuration in workflow ID: j1MmXaRhDjvkRSLa
Check if passThrough is set correctly"

# Step 3: Implement fix
Task: "Update node configuration to use $node pattern for data preservation
Verify the fix works with test execution"
```

---

## 🔧 Error Prevention Strategies

### 1. Validation Before Execution

**Always Validate First:**
```bash
Task: "Check if prerequisites are met before starting Phase 3
Verify: Gitea accessible, n8n running, OpenHands configured"

Task: "Validate file permissions for API keys
Check: /home/bam/.n8n_api_key, /home/bam/openhands/.env, /home/bam/.ssh/n8n_key"

Task: "Verify workflow exists before trying to update it
Check: workflow ID j1MmXaRhDjvkRSLa is active"
```

### 2. Incremental Changes

**Avoid Large Changes:**
```bash
# Instead of:
Task: "Update all documentation files with new Phase 3 info"

# Use:
Task: "Update CLAUDE.md with Phase 3 overview"
Task: "Update phase3.md with Step 1 completion"
Task: "Update todo list with progress"
```

### 3. Verification After Changes

**Always Verify:**
```bash
Task: "After creating new workflow, verify it's active
Check: curl https://n8n.oky.sh/api/v1/workflows"

Task: "After updating documentation, check for broken links
Verify all referenced files exist"

Task: "After modifying configs, test if services still start
Run: docker compose -f /home/bam/services/services-stack/docker-compose.yml ps"
```

### 4. Use Dry-Run Mode

**For Destructive Operations:**
```bash
Task: "Review git status before making changes
List: modified files, untracked files, staged changes"

Task: "Show what would be deleted before deleting files
Preview: which files will be removed, their sizes"

Task: "Check if workflow update would succeed
Verify: API token is valid, workflow ID exists"
```

---

## 📊 Claude Code Task Optimization Templates

### 1. Service Management

**Template:**
```bash
Task: "Manage service: [service-name]
Actions: [start/stop/restart/status]
Location: /home/bam/services/services-stack/
Verify: Check if service is healthy after operation"
```

**Example:**
```bash
Task: "Restart n8n service
Location: /home/bam/services/services-stack/
Verify: Check if n8n API is accessible after restart
Report: Service status and any errors"
```

### 2. Documentation Updates

**Template:**
```bash
Task: "Update [file-name].md with [specific change]
Location: /home/bam/claude/mvp-factory/
Changes: [list specific changes]
Verify: Check file exists and changes are correct"
```

**Example:**
```bash
Task: "Update phase3.md with Step 1 completion
Location: /home/bam/claude/mvp-factory/
Changes: Mark 'Setup Test Repository' as completed
Verify: Check checkbox is updated and timestamp added"
```

### 3. Code Analysis

**Template:**
```bash
Task: "Analyze [component] for [specific issue]
Scope: [file or directory]
Focus: [specific aspects to check]
Report: [what to report back]"
```

**Example:**
```bash
Task: "Analyze n8n workflow for data preservation
Scope: workflow ID j1MmXaRhDjvkRSLa
Focus: Check if $node pattern is used after SSH nodes
Report: Which nodes need fixing and how"
```

### 4. Testing Tasks

**Template:**
```bash
Task: "Test [component] [action]
Setup: [prerequisites]
Execute: [specific commands]
Verify: [expected results]
Cleanup: [if needed]"
```

**Example:**
```bash
Task: "Test n8n workflow execution
Setup: Workflow ID j1MmXaRhDjvkRSLa is active
Execute: POST to webhook with test data
Verify: HTTP 200 response, workflow completes
Report: Success/failure, execution time, any errors"
```

---

## 🚀 Phase 3 Implementation Strategy

### Efficient Task Breakdown

**Step 1: Setup Test Repository (20 min)**
```bash
Task: "Create test repository in Gitea
Name: autonomous-build-test
Description: Test repo for Phase 3 autonomous build testing
Verify: Repository is created and accessible"
```

**Step 2: Configure Webhook (15 min)**
```bash
Task: "Configure Gitea webhook for test repository
URL: https://n8n.oky.sh/webhook/autonomous-build-test
Events: Push events
Verify: Test webhook delivery succeeds"
```

**Step 3: Build Workflow (60 min)**
```bash
# Task 3a: Design workflow structure
Task: "Design 11-node workflow structure for autonomous build test
Document: Node types, connections, data flow"

# Task 3b: Create workflow nodes
Task: "Create workflow nodes in n8n
Nodes: Webhook, Extract Repo, Initialize Retry, OpenHands Build, Wait, Check Results, Decision, Update Gitea, Format Error, Check Retry, Retry Loop"

# Task 3c: Configure connections
Task: "Connect workflow nodes according to flow design
Verify: All connections are correct"
```

**Step 4: Test Success Path (30 min)**
```bash
Task: "Test workflow with valid code
Setup: Push working code to test repo
Execute: Trigger webhook
Verify: Build succeeds, Gitea status updated to success
Report: Execution details and any issues"
```

**Step 5: Test Failure Path (45 min)**
```bash
Task: "Test workflow with intentional errors
Setup: Push code with build errors
Execute: Trigger webhook
Verify: Errors detected, retry counter increments
Report: Error messages and retry behavior"
```

**Step 6: Test Max Retries (30 min)**
```bash
Task: "Test workflow with persistent errors
Setup: Push code that fails 3 times
Execute: Let workflow retry 3 times
Verify: Stops after 3 attempts, final failure notification
Report: Retry count and final status"
```

---

## 📈 Success Metrics

### Performance Targets

**Efficiency Metrics:**
- **Documentation Task Time:** < 5 minutes (instead of 30+ minutes)
- **Code Review Time:** < 10 minutes (instead of 60+ minutes)
- **Error Detection:** < 2 minutes (instead of manual debugging)
- **Test Execution:** < 3 minutes (instead of 30+ minutes)

**Cost Metrics:**
- **Token Usage:** < 3000 tokens per task
- **Retry Rate:** < 20% (tasks completed on first attempt)
- **Error Rate:** < 5% (successful task completion)
- **Documentation Updates:** < 500 tokens each

**Quality Metrics:**
- **Task Accuracy:** 95%+ (correct implementation)
- **Documentation Coverage:** 100% (all changes documented)
- **Test Coverage:** 100% (all paths tested)
- **Error Prevention:** 90%+ (issues caught before deployment)

---

## 🔍 Troubleshooting Common Issues

### Issue: High Token Usage

**Symptoms:** Task uses 5000+ tokens

**Solutions:**
- Break task into smaller subtasks
- Be more specific in task descriptions
- Use targeted searches instead of general analysis
- Reference existing files instead of recreating

**Example Fix:**
```bash
# Before: "Analyze entire project"
Task: "Count lines in phase3.md"

# After: More specific
Task: "Find TODO items in phase3.md"
```

### Issue: Tasks Taking Too Long

**Symptoms:** Task execution > 10 minutes

**Solutions:**
- Use parallel execution for independent tasks
- Specify exact files/directories to work with
- Use incremental analysis
- Avoid unnecessary verification steps

**Example Fix:**
```bash
# Before: "Check everything"
Task: "Verify all services are running"

# After: Specific
Task: "Check if n8n container is running: docker ps | grep n8n"
```

### Issue: Incorrect Results

**Symptoms:** Task completes but output is wrong

**Solutions:**
- Be more specific about expected output
- Include examples in task description
- Verify prerequisites before execution
- Use validation tasks

**Example Fix:**
```bash
# Before: Vague
Task: "Update documentation"

# After: Specific
Task: "Add checkbox [ ] for Step 1 in phase3.md and mark it as completed"
```

### Issue: Sub-Agent Not Working

**Symptoms:** Task doesn't use expected sub-agent

**Solutions:**
- Use task keywords that trigger the right agent
- Search → Use "find", "search", "grep"
- Explore → Use "analyze", "explore", "understand"
- Plan → Use "plan", "break down", "design"
- Bash → Use "run", "execute", "check status"

**Example Fix:**
```bash
# To trigger Search Agent:
Task: "Find all workflow files containing 'SSH'"

# To trigger Explore Agent:
Task: "Analyze the architecture of the n8n workflow"

# To trigger Bash Runner:
Task: "Check Docker service status"
```

---

## 📚 Quick Reference Commands

### Common Tasks

**Check All Services:**
```bash
Task: "Check status of all Docker services
Command: cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps
Report: Running/Stopped/Unhealthy services"
```

**Verify Documentation:**
```bash
Task: "Check if all Phase 3 files exist
Files: phase3.md, claude-code-subagents-doc.md, openhands-subagents-doc.md
Report: Missing files and file sizes"
```

**Test n8n Workflow:**
```bash
Task: "Test n8n workflow execution
Workflow ID: j1MmXaRhDjvkRSLa
Test: POST to webhook with sample data
Verify: HTTP 200 and success response"
```

**Update Phase Progress:**
```bash
Task: "Mark Step X as completed in phase3.md
Action: Change [ ] to [X] for specific step
Add: Completion timestamp and notes
Verify: Change is saved correctly"
```

### Efficiency Tips

1. **Use specific file paths** instead of "the project directory"
2. **Include expected output format** in task description
3. **Reference existing files** instead of recreating
4. **Break complex tasks** into smaller steps
5. **Use validation tasks** before making changes
6. **Group related commands** into single tasks
7. **Avoid unnecessary explanation** in prompts
8. **Use consistent naming** for files and tasks

---

## 🎓 Advanced Strategies

### 1. Task Chaining

**Pattern:**
```bash
Task 1: "Create plan for Phase 3 Step 1"
Task 2: "Execute Step 1 according to plan"
Task 3: "Mark Step 1 as completed"
Task 4: "Create plan for Step 2"
...
```

### 2. Context Preservation

**Pattern:**
```bash
# Reference previous tasks
Task: "Based on previous analysis of n8n workflow,
implement the suggested data preservation fix"

Task: "Continue from where we left off in Phase 3
Next step is: Configure Gitea webhook"
```

### 3. Iterative Refinement

**Pattern:**
```bash
# First pass: Basic implementation
Task: "Create basic workflow structure"

# Second pass: Add details
Task: "Add error handling to workflow"

# Third pass: Optimize
Task: "Optimize workflow for faster execution"
```

### 4. Verification Loop

**Pattern:**
```bash
Task: "Make changes to [file]"
Task: "Verify changes are correct"
Task: "If errors found, fix them"
Task: "Verify again until perfect"
```

---

*Claude Code Sub-Agents Guide - Last Updated: 2025-12-02*
*Optimized for AI Dev Factory Project*