mvp-factory-openhands/CLAUDE.md

# 🚀 AI Dev Factory - Session Continuation Guide

**Last Updated:** 2025-12-02
**Current Phase:** Phase 2 ✅ COMPLETED | Phase 3 🚀 IN PROGRESS
**Approach:** OpenHands SDK via SSH wrapper

---

## 📋 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)
- **n8n:** https://n8n.oky.sh (HTTPS, workflow automation)
- **Caddy:** Auto SSL with Let's Encrypt
- **SSH:** n8n ↔ localhost credentials working
- **OpenHands CLI:** `/home/bam/.local/bin/openhands` (v1.3.0)
- **SDK Wrapper:** `/home/bam/openhands-sdk-wrapper-sh.sh` (sh-compatible)
- **Production Workflow:** ID `j1MmXaRhDjvkRSLa` ✅ Active
- **Data Preservation:** Using `$node["Node Name"].json` pattern

### ✅ Phase 2 Completed
The CI/CD pipeline is operational: `Gitea push → n8n → OpenHands SDK → 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 Specs
```
Hostname: ai-dev-node | IP: 10.10.10.11 | User: bam
CPU: 8 vCPU | RAM: 24GB | OS: Ubuntu 22.04
```

### Services
```bash
cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps
# Services: caddy, gitea, n8n, postgres
```

### API Keys & Credentials
```
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 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
custom-subagents-usage-guide.md - Custom project-specific sub-agents guide
agent-templates.md           - Copy-paste ready agent templates
N8N_DATA_PRESERVATION_SOLUTION.md
GITEA_N8N_WEBHOOK_GUIDE.md
test-scripts/README.md       - 10 testing scripts with guide
```

---

## 🚀 OPENHANDS SDK APPROACH

**Use OpenHands CLI directly via SSH** in n8n workflows (not server API).

### Why SDK?
- ✅ Reliable (no Docker/port conflicts)
- ✅ Simple (direct CLI execution)
- ✅ Shell-compatible (no Python needed)
- ✅ Proven (tested successfully)

### SDK Wrapper
```bash
/home/bam/openhands-sdk-wrapper-sh.sh
```

### Usage in n8n SSH Node
```javascript
Command: sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task"
Authentication: privateKey
```

### ⚠️ Critical: Data Preservation Pattern
SSH nodes overwrite ALL data. Use `$node` to preserve input:

```javascript
const sshOutput = $json;
const repoData = $node["Extract Repo Info"].json;

return {
  ...repoData,              // ← Preserves repository data!
  code: sshOutput.code,
  stdout: sshOutput.stdout,
  stderr: sshOutput.stderr,
  status: 'SUCCESS'
};
```

**See:** `N8N_DATA_PRESERVATION_SOLUTION.md` for complete solution

---

## 🤖 CUSTOM SUB-AGENTS

Create **project-specific sub-agents** as Markdown files with YAML frontmatter:

### How to Create:
```bash
# Create agents directory
mkdir -p .claude/agents

# Use /agents command (recommended)
/agents create

# Or create files manually
cat > .claude/agents/n8n-workflow-specialist.md << 'EOF'
---
name: n8n-workflow-specialist
description: n8n workflow specialist
model: sonnet
---

You are a specialized n8n workflow agent...
EOF
```

### Available Custom Agents:
- **n8n-workflow-specialist** - Workflow design, debugging, data preservation
- **openhands-sdk-specialist** - CLI integration, task optimization
- **gitea-integration-specialist** - Webhooks, API, repository management
- **security-audit-specialist** - API keys, permissions, security checks
- **docker-services-specialist** - Service management, troubleshooting
- **phase3-implementation-specialist** - Autonomous build test MVP

### Usage in Conversation:
```
"Use the n8n-workflow-specialist agent to debug my workflow"
"Have the security-audit-specialist check API key permissions"
```

**See:** `agent-templates.md` for file templates
**Guide:** `custom-subagents-usage-guide.md` for complete documentation

---

## 🎯 WORKING N8N WORKFLOW

**Name:** "Gitea → OpenHands - FIXED WITH PASSTHROUGH"
**ID:** `j1MmXaRhDjvkRSLa`
**Status:** ✅ Active
**Webhook:** `https://n8n.oky.sh/webhook/openhands-fixed-test`

### Structure
```
[1] Gitea Webhook
     ↓
[2] Extract Repo Info (Code)
     ↓
[3] OpenHands Build (SSH)
     → sh /home/bam/openhands-sdk-wrapper-sh.sh "<task>"
     ↓
[4] Wait 10s
     ↓
[5] Check Build Status (Code) - uses $node pattern
     ↓
[6] Format Response (Code)
     ↓
[7] HTTP Response
```

### 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"},
    "ref": "refs/heads/main",
    "after": "abc123def456"
  }'
```

---

## 🎯 PHASE 3: AUTONOMOUS BUILD TEST MVP

### Overview
Production-ready autonomous CI/CD with retry logic, error feedback, and Gitea status updates.

### Workflow: 11-Node Design
```
[1] Git Push (Gitea webhook)
     ↓
[2] Extract commit info
     ↓
[3] Start OpenHands Build
     ↓
[4] Wait for completion
     ↓
[5] Check build results
     ↓
[6] Decision: Build OK?
     ├─ YES → Update Gitea → Success notification
     └─ NO → Format errors → Retry check → Retry or Fail
```

### Key Components

**A. Retry Counter (n8n staticData)**
```javascript
$workflow.staticData = $workflow.staticData || {};
$workflow.staticData.retry_count = ($workflow.staticData.retry_count || 0) + 1;

if ($workflow.staticData.retry_count >= 3) {
  return { action: 'fail', message: 'Max retries exceeded' };
}
```

**B. Error Feedback**
```javascript
const errors = sshOutput.stderr || sshOutput.stdout;
return {
  status: 'FAILED',
  error_message: `Build failed:\n${errors}\nPlease fix.`,
  retry_count: $workflow.staticData.retry_count
};
```

**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"}
```

### 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 project

**Complete Details:** See `phase3.md` (11 implementation steps, 4-5 hours)

---

## 🔑 N8N API REFERENCE

**See:** `n8n-api.md` for complete documentation

### Quick Operations
```bash
# List workflows
curl -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows

# Activate workflow
curl -X POST -H "Authorization: Bearer $(cat /home/bam/.n8n_api_key)" \
  https://n8n.oky.sh/api/v1/workflows/<ID>/activate

# 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

### Service Management
```bash
# Status
cd /home/bam && docker compose -f services/services-stack/docker-compose.yml ps

# 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
```

### Testing
See: `/home/bam/claude/mvp-factory/test-scripts/README.md`

---

## 🔐 CREDENTIALS

### Login URLs
- **n8n:** https://n8n.oky.sh (User: admin)
- **Gitea:** https://git.oky.sh (Admin account)

### 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
```

---

## 📝 KEY LEARNINGS

### OpenHands SDK vs API Server
- **SDK via SSH:** ✅ Reliable, simple, production-ready
- **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
- Code nodes preserve data by merging with previous output

### Best Practices
- 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 STATUS

### ✅ 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 & tested
   - n8n workflow integrated
   - Build/test cycle functional
   - Data preservation fixed
   - Repository cleaned up (7 files removed)
   - Testing infrastructure created
   - **Details:** `phase2.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 (ID: j1MmXaRhDjvkRSLa)
- **Data Preservation:** ✅ Working
- **Documentation:** Organized & Updated
- **Phase 2:** ✅ COMPLETE
- **Phase 3:** 🚀 IN PROGRESS

**Current Goal:** Build Phase 3 - Autonomous Build Test MVP

---

*Last Updated: 2025-12-02*
*Phase 2 complete, Phase 3 in progress*