From 225aa2bbf37eb575c08070d7da8c1a6f87110d9e Mon Sep 17 00:00:00 2001
From: Git Admin <gitadmin@git.oky.sh>
Date: Tue, 2 Dec 2025 10:48:24 +0000
Subject: [PATCH] Documentation optimization: Add Claude Code sub-agents guide
 & optimize CLAUDE.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Changes:
- Add claude-code-subagents-doc.md (21KB): Comprehensive guide on Claude Code
  sub-agents, cost optimization, and time reduction strategies
- Rename code.md → openhands-subagents-doc.md (9.4KB): OpenHands sub-agents guide
- Optimize CLAUDE.md: Reduced from 425 to 347 lines (~21% smaller)
  * Added concise VM specs back
  * Streamlined Phase 3 section with references
  * Consolidated n8n API to reference-only
  * Enhanced documentation file references

Result: Better organized documentation with cost-efficient structure for Phase 3

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md                             | 372 +++++-------
 claude-code-subagents-doc.md          | 801 ++++++++++++++++++++++++++
 code.md => openhands-subagents-doc.md |   0
 3 files changed, 948 insertions(+), 225 deletions(-)
 create mode 100644 claude-code-subagents-doc.md
 rename code.md => openhands-subagents-doc.md (100%)

diff --git a/CLAUDE.md b/CLAUDE.md
index e6aa776..5f8f936 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,126 +1,109 @@
 # 🚀 AI Dev Factory - Session Continuation Guide
 
 **Last Updated:** 2025-12-02
-**Current Phase:** Phase 2 - OpenHands Integration (SDK Mode) ✅ COMPLETED
-**Current Approach:** OpenHands SDK via SSH wrapper ✅
+**Current Phase:** Phase 2 ✅ COMPLETED | Phase 3 🚀 IN PROGRESS
+**Approach:** OpenHands SDK via SSH wrapper
 
 ---
 
-# Summary Instructions
-When you are using compact, please focus on test output and code changes
+## 📋 Summary Instructions
+When using compact mode, focus on test output and code changes.
 
----
+**Efficiency Guides:**
+- Claude Code optimization: `claude-code-subagents-doc.md`
+- OpenHands optimization: `openhands-subagents-doc.md`
 
 ---
 
 ## 📊 CURRENT STATUS
 
-### ✅ What's Working:
-- **Gitea:** https://git.oky.sh (HTTPS, PostgreSQL backend)
+### ✅ What's Working
+- **Gitea:** https://git.oky.sh (HTTPS, PostgreSQL)
 - **n8n:** https://n8n.oky.sh (HTTPS, workflow automation)
 - **Caddy:** Auto SSL with Let's Encrypt
-- **SSH:** n8n → localhost credentials configured and working
+- **SSH:** n8n ↔ localhost credentials working
 - **OpenHands CLI:** `/home/bam/.local/bin/openhands` (v1.3.0)
-- **OpenHands SDK Wrapper:** `/home/bam/openhands-sdk-wrapper-sh.sh` (sh-compatible)
-- **Working n8n Workflow:** "Gitea → OpenHands - FIXED WITH PASSTHROUGH" (ID: j1MmXaRhDjvkRSLa)
-- **Data Preservation:** Fixed using `$node["Node Name"].json` pattern
+- **SDK Wrapper:** `/home/bam/openhands-sdk-wrapper-sh.sh` (sh-compatible)
+- **Production Workflow:** ID `j1MmXaRhDjvkRSLa` ✅ Active
+- **Data Preservation:** Using `$node["Node Name"].json` pattern
 
-### ✅ Completed (Phase 2):
-- SSH Authentication Fixed
-- n8n Workflow Created & tested
-- Build/test cycle functional
-- Data loss issue resolved
-- Repository cleanup (7 files removed)
-- Testing infrastructure created
+### ✅ Phase 2 Completed
+The CI/CD pipeline is operational: `Gitea push → n8n → OpenHands SDK → Build/Test → Response`
 
-### 🎯 Phase 2 Goal (COMPLETED):
-The CI/CD pipeline is fully operational: Gitea push → n8n → OpenHands SDK (via SSH) → Build/Test → Response
+### 🎯 Phase 3 Goal
+Build autonomous CI/CD workflow with retry logic, error feedback, and commit status updates.
+
+**Plan:** See `phase3.md` for complete 11-step implementation
 
 ---
 
 ## 🔧 SYSTEM CONFIGURATION
 
-### VM Details:
+### VM Specs
 ```
-Hostname: ai-dev-node
-IP: 10.10.10.11
-User: bam
-CPU: 8 vCPU
-RAM: 24GB
-OS: Ubuntu 22.04
+Hostname: ai-dev-node | IP: 10.10.10.11 | User: bam
+CPU: 8 vCPU | RAM: 24GB | OS: Ubuntu 22.04
 ```
 
-### Services Running:
+### Services
 ```bash
 cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps
 # Services: caddy, gitea, n8n, postgres
 ```
 
-### API Keys & Credentials:
+### API Keys & Credentials
 ```
-# OpenHands API Keys:
-/home/bam/openhands/.env
-Contains: MINIMAX_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY
-
-# n8n API Key (JWT Token):
-/home/bam/.n8n_api_key
-Used for: Creating, activating, editing workflows via API
-
-# SSH Key for n8n:
-/home/bam/.ssh/n8n_key
-Used for: SSH authentication from n8n to localhost
+OpenHands API Keys:    /home/bam/openhands/.env
+n8n API Token:         /home/bam/.n8n_api_key (JWT)
+SSH Private Key:       /home/bam/.ssh/n8n_key
+Gitea API Token:       Generated in Gitea settings
 ```
 
-### 📚 Documentation References:
-- **Phase 2 Details:** `phase2.md`
-- **Phase 3 Plan:** `phase3.md`
-- **n8n API Reference:** `n8n-api.md`
-- **Code Efficiency & Sub-Agents:** `code.md`
-- **Data Preservation Solution:** `N8N_DATA_PRESERVATION_SOLUTION.md`
-- **Gitea Webhook Setup:** `GITEA_N8N_WEBHOOK_GUIDE.md`
-- **Test Scripts:** `test-scripts/README.md`
+### 📚 Documentation Files
+```
+phase2.md                    - Phase 2 complete documentation (~8-10 hours)
+phase3.md                    - Phase 3 detailed plan (4-5 hours)
+n8n-api.md                   - Complete n8n API reference
+openhands-subagents-doc.md   - OpenHands sub-agents guide
+claude-code-subagents-doc.md - Claude Code sub-agents guide
+N8N_DATA_PRESERVATION_SOLUTION.md
+GITEA_N8N_WEBHOOK_GUIDE.md
+test-scripts/README.md       - 10 testing scripts with guide
+```
 
 ---
 
 ## 🚀 OPENHANDS SDK APPROACH
 
-### Overview
-Use **OpenHands CLI directly via SSH** in n8n workflows instead of running a server API.
+**Use OpenHands CLI directly via SSH** in n8n workflows (not server API).
 
-### Why SDK Approach?
-- ✅ **Reliable** - No Docker container issues or port conflicts
-- ✅ **Simple** - Direct CLI execution without API complexity
-- ✅ **Shell-compatible** - Works in SSH environment without Python dependencies
-- ✅ **Proven** - Successfully tested with n8n workflows
+### Why SDK?
+- ✅ Reliable (no Docker/port conflicts)
+- ✅ Simple (direct CLI execution)
+- ✅ Shell-compatible (no Python needed)
+- ✅ Proven (tested successfully)
 
-### Key Components:
-
-#### 1. SDK Wrapper Script
+### SDK Wrapper
 ```bash
 /home/bam/openhands-sdk-wrapper-sh.sh
 ```
-**Purpose:** Wraps OpenHands CLI for n8n SSH execution
 
-#### 2. Usage in n8n SSH Node
+### Usage in n8n SSH Node
 ```javascript
-Command: sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task here"
+Command: sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task"
 Authentication: privateKey
-Options:
-  passThrough: true
 ```
 
-#### 3. Critical Pattern: Data Preservation
-SSH nodes overwrite ALL data. Use `$node` to access previous node output:
+### ⚠️ Critical: Data Preservation Pattern
+SSH nodes overwrite ALL data. Use `$node` to preserve input:
 
 ```javascript
-// In node after SSH
 const sshOutput = $json;
 const repoData = $node["Extract Repo Info"].json;
 
 return {
-  ...repoData,              // ← Repository data preserved!
+  ...repoData,              // ← Preserves repository data!
   code: sshOutput.code,
-  signal: sshOutput.signal,
   stdout: sshOutput.stdout,
   stderr: sshOutput.stderr,
   status: 'SUCCESS'
@@ -129,47 +112,39 @@ return {
 
 **See:** `N8N_DATA_PRESERVATION_SOLUTION.md` for complete solution
 
-#### 4. Testing Scripts
-See `/home/bam/claude/mvp-factory/test-scripts/README.md` for testing instructions
-
 ---
 
 ## 🎯 WORKING N8N WORKFLOW
 
-### Current Production Workflow
 **Name:** "Gitea → OpenHands - FIXED WITH PASSTHROUGH"
 **ID:** `j1MmXaRhDjvkRSLa`
 **Status:** ✅ Active
 **Webhook:** `https://n8n.oky.sh/webhook/openhands-fixed-test`
 
-### Workflow Structure:
+### Structure
 ```
-[1] Gitea Webhook (POST)
+[1] Gitea Webhook
      ↓
-[2] Extract Repo Info (Code node)
+[2] Extract Repo Info (Code)
      ↓
-[3] Start OpenHands Build (SSH node)
+[3] OpenHands Build (SSH)
      → sh /home/bam/openhands-sdk-wrapper-sh.sh "<task>"
      ↓
-[4] Wait 10s for Initialization
+[4] Wait 10s
      ↓
-[5] Check Build Status (Code node)
-     → Uses $node["Extract Repo Info"].json to preserve data
+[5] Check Build Status (Code) - uses $node pattern
      ↓
-[6] Format Build Response (Code node)
+[6] Format Response (Code)
      ↓
-[7] Send Response (HTTP Response node)
+[7] HTTP Response
 ```
 
-### Quick Test:
+### Quick Test
 ```bash
 curl -X POST https://n8n.oky.sh/webhook/openhands-fixed-test \
   -H "Content-Type: application/json" \
   -d '{
-    "repository": {
-      "name": "test-project",
-      "full_name": "gitadmin/test-project"
-    },
+    "repository": {"name": "test-project", "full_name": "gitadmin/test-project"},
     "ref": "refs/heads/main",
     "after": "abc123def456"
   }'
@@ -180,36 +155,28 @@ curl -X POST https://n8n.oky.sh/webhook/openhands-fixed-test \
 ## 🎯 PHASE 3: AUTONOMOUS BUILD TEST MVP
 
 ### Overview
-Build production-ready autonomous CI/CD workflow with retry logic, error feedback, and commit status updates.
+Production-ready autonomous CI/CD with retry logic, error feedback, and Gitea status updates.
 
-### Workflow: "Autonomous Build Test"
-
-#### Flow Design:
+### Workflow: 11-Node Design
 ```
 [1] Git Push (Gitea webhook)
      ↓
-[2] Extract commit info (Code node)
+[2] Extract commit info
      ↓
-[3] Start OpenHands (SSH node)
-     → Task: "Build project in /workspace/[project]"
+[3] Start OpenHands Build
      ↓
-[4] Wait for completion (Wait node)
+[4] Wait for completion
      ↓
-[5] Check build results (Code node)
-     → Capture exit code + errors
+[5] Check build results
      ↓
 [6] Decision: Build OK?
-     ├─ YES → [7] Update Gitea status → [8] Success notification
-     └─ NO → [9] Format error feedback
-               ↓
-          [10] Retry counter check
-               ├─ < 3 → Back to [3] (retry with feedback)
-               └─ ≥ 3 → [11] Final failure notification
+     ├─ YES → Update Gitea → Success notification
+     └─ NO → Format errors → Retry check → Retry or Fail
 ```
 
-### Key Components:
+### Key Components
 
-**A. Iteration Counter (n8n staticData)**
+**A. Retry Counter (n8n staticData)**
 ```javascript
 $workflow.staticData = $workflow.staticData || {};
 $workflow.staticData.retry_count = ($workflow.staticData.retry_count || 0) + 1;
@@ -219,137 +186,95 @@ if ($workflow.staticData.retry_count >= 3) {
 }
 ```
 
-**B. Error Collection & Formatting**
+**B. Error Feedback**
 ```javascript
 const errors = sshOutput.stderr || sshOutput.stdout;
-const errorMsg = `Build failed. Errors:\n${errors}\n\nPlease fix these issues.`;
-
 return {
   status: 'FAILED',
-  error_message: errorMsg,
+  error_message: `Build failed:\n${errors}\nPlease fix.`,
   retry_count: $workflow.staticData.retry_count
 };
 ```
 
-**C. Feedback Loop**
-```javascript
-const task = `Build project /workspace/${project_name}.
-Previous build failed with errors: ${previous_error}
-Please fix these issues and ensure a successful build.`;
-```
-
-**D. Gitea Commit Status Update**
+**C. Gitea Status Update**
 ```bash
 POST https://git.oky.sh/api/v1/repos/{owner}/{repo}/statuses/{sha}
 Authorization: token {GITEA_TOKEN}
-Body:
-{
-  "state": "success",
-  "description": "Build passed",
-  "context": "openhands/autonomous-build"
-}
+Body: {"state": "success", "description": "Build passed"}
 ```
 
-### Success Criteria:
-- [ ] End-to-end workflow completes successfully
-- [ ] OpenHands executes build tasks autonomously
-- [ ] Retry logic works (max 3 attempts)
+### Success Criteria
+- [ ] End-to-end workflow completes
+- [ ] OpenHands executes autonomously
+- [ ] Retry logic (max 3 attempts)
 - [ ] Error feedback to OpenHands
 - [ ] Gitea commit status updated
-- [ ] Tested with real MVP project build
+- [ ] Tested with real project
 
-### Implementation Steps:
-1. Create test repository in Gitea
-2. Configure Gitea webhook
-3. Build n8n workflow with retry logic
-4. Test successful build path
-5. Test failure path with retry
-6. Test max retries path
-7. Test Gitea commit status updates
-8. Test with real MVP project
-
-**See:** `phase3.md` for complete detailed plan
+**Complete Details:** See `phase3.md` (11 implementation steps, 4-5 hours)
 
 ---
 
-## 🔑 N8N API QUICK REFERENCE
+## 🔑 N8N API REFERENCE
 
-See `n8n-api.md` for complete documentation
+**See:** `n8n-api.md` for complete documentation
 
-### Common Operations:
-
-#### List Workflows
+### Quick Operations
 ```bash
+# List workflows
 curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
   https://n8n.oky.sh/api/v1/workflows
-```
 
-#### Create Workflow
-```bash
-curl -X POST \
-  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
-  -H "Content-Type: application/json" \
-  https://n8n.oky.sh/api/v1/workflows \
-  -d '{"name":"My Workflow","nodes":[...]}'
-```
+# Activate workflow
+curl -X POST -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
+  https://n8n.oky.sh/api/v1/workflows/<ID>/activate
 
-#### Activate Workflow
-```bash
-curl -X POST \
-  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
-  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/activate
-```
-
-#### Execute Workflow
-```bash
-curl -X POST \
-  -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
-  https://n8n.oky.sh/api/v1/workflows/<WORKFLOW_ID>/execute
+# Execute workflow
+curl -X POST -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
+  https://n8n.oky.sh/api/v1/workflows/<ID>/execute
 ```
 
 ---
 
 ## 📚 REFERENCE COMMANDS
 
-### Quick Status Check:
+### Service Management
 ```bash
-# All services status
+# Status
 cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps
 
-# n8n workflows via API
+# Restart
+cd /home/bam && docker compose -f services/services-stack/docker-compose.yml restart
+
+# Logs
+docker logs -f n8n
+docker logs -f caddy
+docker logs -f gitea
+
+# n8n workflows
 curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
   https://n8n.oky.sh/api/v1/workflows
 ```
 
-### Restart Services:
-```bash
-cd /home/bam && docker compose -f services/services-stack/docker-compose.yml restart
-```
-
-### View Logs:
-```bash
-docker logs -f n8n
-docker logs -f caddy
-docker logs -f gitea
-```
-
-### Testing SDK:
-See `/home/bam/claude/mvp-factory/test-scripts/README.md`
+### Testing
+See: `/home/bam/claude/mvp-factory/test-scripts/README.md`
 
 ---
 
-## 🔐 CREDENTIALS REFERENCE
+## 🔐 CREDENTIALS
 
-### Login Credentials:
-- **n8n URL:** https://n8n.oky.sh (User: admin)
-- **Gitea URL:** https://git.oky.sh (Admin account)
+### Login URLs
+- **n8n:** https://n8n.oky.sh (User: admin)
+- **Gitea:** https://git.oky.sh (Admin account)
 
-### API Keys & Tokens:
-- **OpenHands (MiniMax):** `/home/bam/openhands/.env` → MINIMAX_API_KEY
-- **OpenHands (DeepSeek):** `/home/bam/openhands/.env` → DEEPSEEK_API_KEY
-- **n8n API Token:** `/home/bam/.n8n_api_key` (JWT format)
-- **SSH Private Key:** `/home/bam/.ssh/n8n_key`
-- **Gitea API Token:** Generated in Gitea user settings
+### API Keys
+```
+OpenHands (MiniMax):  /home/bam/openhands/.env → MINIMAX_API_KEY
+OpenHands (DeepSeek): /home/bam/openhands/.env → DEEPSEEK_API_KEY
+n8n API:              /home/bam/.n8n_api_key (JWT)
+SSH Key:              /home/bam/.ssh/n8n_key
+Gitea API:            Generated in Gitea user settings
+```
 
 ---
 
@@ -357,62 +282,59 @@ See `/home/bam/claude/mvp-factory/test-scripts/README.md`
 
 ### OpenHands SDK vs API Server
 - **SDK via SSH:** ✅ Reliable, simple, production-ready
-- **API Server:** ❌ Docker complexity, port conflicts, reliability issues
+- **API Server:** ❌ Docker complexity, port conflicts
 
 ### n8n Data Flow
-- SSH nodes **overwrite ALL data** - Use `$node["Previous Node"].json`
-- `passThrough: true` does NOT preserve input data
-- Code nodes can preserve data by merging with previous output
+- SSH nodes **overwrite ALL data** → Use `$node["Previous Node"].json`
+- `passThrough: true` does NOT preserve input
+- Code nodes preserve data by merging with previous output
 
 ### Best Practices
-- Use `$node` pattern for data preservation after nodes that overwrite
-- Test SDK scripts before integrating into n8n
-- Keep API keys in secure locations with proper permissions (600)
-- Implement retry logic with max attempts to prevent infinite loops
-- Update commit status in Gitea for better visibility
+- Use `$node` pattern for data preservation
+- Test SDK scripts before n8n integration
+- Keep API keys secure (permissions 600)
+- Implement max retry limits (prevent infinite loops)
+- Update Gitea commit status for visibility
 
 ---
 
-## 🏆 PROJECT COMPLETION STATUS
+## 🏆 PROJECT STATUS
 
-**✅ PHASES COMPLETE:**
-
-1. **Phase 1: Infrastructure Setup** ✅
+### ✅ Complete
+1. **Phase 1:** Infrastructure Setup
    - Gitea, n8n, Caddy running with SSL
    - Docker compose configured
    - SSH authentication working
 
-2. **Phase 2: OpenHands Integration (SDK)** ✅
-   - SDK wrapper created and tested
+2. **Phase 2:** OpenHands Integration (SDK)
+   - SDK wrapper created & tested
    - n8n workflow integrated
    - Build/test cycle functional
    - Data preservation fixed
-   - Repository cleaned up
-   - Documentation complete
-   - **Details:** See `phase2.md`
+   - Repository cleaned up (7 files removed)
+   - Testing infrastructure created
+   - **Details:** `phase2.md`
 
-**🎯 PHASE 3: AUTONOMOUS BUILD TEST MVP** (In Progress)
-
-**Phase 3 Complete When:**
-- [ ] Retry logic working (max 3 attempts)
-- [ ] Error feedback to OpenHands
-- [ ] Commit status updates in Gitea
-- [ ] Tested with real MVP project build
-- **Plan:** See `phase3.md`
+### 🎯 In Progress
+**Phase 3:** Autonomous Build Test MVP
+- Retry logic with error feedback
+- Gitea commit status updates
+- Real project build testing
+- **Plan:** `phase3.md`
 
 ---
 
 ## 🎉 FINAL STATUS
 
-**Repository:** https://git.oky.sh/gitadmin/mvp-factory-openhands
-**n8n Instance:** https://n8n.oky.sh
-**Production Workflow:** Active & Tested (ID: j1MmXaRhDjvkRSLa)
-**Data Preservation:** Working
-**Documentation:** Organized & Updated
-**Phase 2:** ✅ COMPLETE
-**Phase 3:** 🚀 IN PROGRESS
+- **Repository:** https://git.oky.sh/gitadmin/mvp-factory-openhands
+- **n8n Instance:** https://n8n.oky.sh
+- **Production Workflow:** Active (ID: j1MmXaRhDjvkRSLa)
+- **Data Preservation:** ✅ Working
+- **Documentation:** Organized & Updated
+- **Phase 2:** ✅ COMPLETE
+- **Phase 3:** 🚀 IN PROGRESS
 
-**Current Status:** Building Phase 3 - Autonomous Build Test MVP
+**Current Goal:** Build Phase 3 - Autonomous Build Test MVP
 
 ---
 
diff --git a/claude-code-subagents-doc.md b/claude-code-subagents-doc.md
new file mode 100644
index 0000000..96af236
--- /dev/null
+++ b/claude-code-subagents-doc.md
@@ -0,0 +1,801 @@
+# 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*
diff --git a/code.md b/openhands-subagents-doc.md
similarity index 100%
rename from code.md
rename to openhands-subagents-doc.md