gitadmin
/
mvp-factory-openhands
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation optimization: Add Claude Code sub-agents guide & optimize CLAUDE.md 

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>
This commit is contained in:
Git Admin 2025-12-02 10:48:24 +00:00
parent 299009524b
commit 225aa2bbf3
3 changed files with 948 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

372
CLAUDE.md
View File

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

801
claude-code-subagents-doc.md Normal file
View File

@ -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*

0
code.md → openhands-subagents-doc.md
View File