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
parent
299009524b
commit
225aa2bbf3
372
CLAUDE.md
372
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
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
Loading…
Reference in New Issue