mvp-factory-openhands/CLAUDE.md

# 🚀 AI Dev Factory - Session Continuation Guide

**Last Updated:** 2025-12-03
**Current Phase:** Phase 2 ✅ COMPLETED | Phase 3 🚀 IN PROGRESS (Simplified)
**Approach:** Todo-based autonomous development with OpenHands SDK

---

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

## 🎯 WORKSPACE RULES (CRITICAL - ALWAYS REMEMBER)

### ⚠️ HOME DIRECTORY USAGE
- **NEVER** use `/home/bam/` home directory for project files
- **ALWAYS** use `/home/bam/claude/mvp-factory/` for all project work
- **ONLY** access home directory for:
  - System tools (docker, git, etc.)
  - Credentials (SSH keys, API keys in `.ssh/`, `.n8n_api_key`)
  - When specific tools require home directory access
- **ASK PERMISSION** before accessing `/home/bam/` for any other purpose

### 📁 PROJECT STRUCTURE
All project files must be organized in:
```
/home/bam/claude/mvp-factory/
├── test-scripts/      # All scripts (.py, .sh, .js)
├── docs/             # Documentation (.md)
├── openhands/        # OpenHands workspace
├── services/         # Docker services
└── implementations/  # Code implementations
```

### 🚫 FILES TO KEEP AWAY FROM HOME
**Never create these in `/home/bam/`:**
- Scripts (.py, .sh, .js)
- Test files
- Documentation (.md)
- Configuration files (.json, .yml, .yaml)
- Any project-related content

**These belong in `/home/bam/claude/mvp-factory/`:**
- All development work
- All testing
- All documentation
- All project files

---

## 📊 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 SDK:** ✅ Verified working - creates TODO.md successfully
- **Direct SDK Test:** ✅ Created TODO.md with 26 structured tasks
- **Production Workflows:** 2 active workflows (see Status section below)
- **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 (Simplified)
Build todo-based autonomous system: `Prompt → TODOs → Execute → Test → Commit → Repeat`

**Plan:** See `SIMPLIFIED_PHASE3_PLAN.md` for complete 6-node 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
```
SIMPLIFIED_PHASE3_PLAN.md    - Todo-based autonomous development plan (1255 lines)
SESSION_SUMMARY.md           - Latest investigation: TODO.md creation issue
CURRENT_STATUS.md            - Current n8n workflow status (2 active workflows)
TEST_COMMANDS.md             - Commands to test workflows and verify TODO.md
phase2.md                    - Phase 2 complete documentation
phase3.md                    - Old Phase 3 plan (superseded)
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 (Direct Python)

**Use OpenHands SDK directly via Python** in n8n Code nodes (no SSH wrapper).

### Why Direct SDK?
- ✅ No SSH overhead (faster)
- ✅ Structured JSON output
- ✅ Direct Python integration
- ✅ Better error handling
- ✅ Simpler architecture

### SDK Wrapper
```bash
/home/bam/openhands-sdk-wrapper-fixed.py  (Python script)
```

### Usage in n8n Code Node
```javascript
const { execSync } = require('child_process');

const command = `python3 /home/bam/openhands-sdk-wrapper-fixed.py "${task}" --workspace ${workspace} --json`;

try {
  const output = execSync(command, { encoding: 'utf-8' });
  const result = JSON.parse(output);

  return {
    success: result.success,
    files_created: result.files_created || [],
    error: result.error || null
  };
} catch (error) {
  return { success: false, error: error.message };
}
```

### ⚠️ Critical: Data Preservation Pattern
Code nodes preserve data by merging:

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

return {
  ...repoData,        // ← Preserves repository data!
  current_data: current
};
```

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

---

## 📊 ACTIVE N8N WORKFLOWS

### Workflow 1: Old (Code-Only) ❌
- **ID:** `eZ5zoeglwRrL7lOf`
- **Name:** "Todo-Based MVP Builder"
- **Status:** ✅ Active
- **Webhook:** `https://n8n.oky.sh/webhook/todo-mvp-builder`
- **Problem:** ❌ Missing SSH node - Code nodes never execute OpenHands

### Workflow 2: New (SSH-Based) ✅
- **ID:** `p6Gt8h23NrsWIk4R`
- **Name:** "Todo-Based MVP Builder"
- **Status:** ✅ Active
- **Webhook:** `https://n8n.oky.sh/webhook/real-todo-mvp`
- **Structure:** 8 nodes with proper SSH SDK Call
- **Note:** Imported during investigation (requires approval to keep)

### Investigation Results
✅ **OpenHands SDK Verified:** Creates TODO.md successfully (26 tasks)
❌ **Old Workflow Issue:** Missing SSH node prevents OpenHands execution
✅ **New Workflow Status:** Has correct SSH structure

**See:** `CURRENT_STATUS.md` for details, `TEST_COMMANDS.md` for verification

---

## 🤖 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: TODO-BASED AUTONOMOUS DEVELOPMENT

### Overview
Simple 6-node workflow that builds full-stack apps through structured todos.

### Workflow: 6-Node Design
```
[1] Git Push (Gitea webhook)
     ↓
[2] Extract repo info & prompt
     ↓
[3] Get next todo (or finish)
     ↓
[4] Execute todo (OpenHands SDK)
     ↓
[5] Test changes
     ↓
[6] Commit & push to Gitea
     ↓
     └─ Loop back to [3]
```

### How It Works

**Step 1:** User pushes: `MVP Prompt: Create a full-stack todo app`
**Step 2:** OpenHands creates TODO.md with 6-8 tasks
**Step 3:** Loop executes each task:
- Execute with OpenHands SDK
- Test the changes
- Commit to Gitea
- Advance to next task

**Step 4:** Repeat until all todos complete

### Key Components

**A. Todo State (n8n staticData)**
```javascript
$workflow.staticData = $workflow.staticData || {};
$workflow.staticData.todos = $workflow.staticData.todos || {};

const currentIndex = $workflow.staticData.todos.current_index || 0;
const todos = $workflow.staticData.todos.list || [];

if (currentIndex < todos.length) {
  return { todo: todos[currentIndex], index: currentIndex };
} else {
  return { action: 'complete', message: 'All todos finished' };
}
```

**B. Todo Creation**
```javascript
const prompt = "Create a full-stack todo app";
const task = `Analyze prompt and create TODO.md with structured tasks`;

const sdkOutput = callOpenHandsSDK(task);
$workflow.staticData.todos.list = sdkOutput.tasks;
$workflow.staticData.todos.current_index = 0;
```

**C. Commit Message Pattern**
```javascript
const messages = {
  created: '📋 TODOs created from prompt',
  completed: '✅ Complete: {task_name}',
  finished: '🎉 MVP Complete: {app_name}'
};
```

### Success Criteria
- [ ] Initial prompt creates TODO.md with ≥5 todos
- [ ] Each todo executes and commits changes
- [ ] Loop continues until all todos complete
- [ ] Final application builds successfully
- [ ] End-to-end test passes

**Complete Details:** See `SIMPLIFIED_PHASE3_PLAN.md` (8 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`

3. **Phase 3 Investigation:** TODO.md Creation Issue
   - ✅ Root cause identified: Missing SSH node in active workflow
   - ✅ OpenHands SDK verified working (creates TODO.md with 26 tasks)
   - ✅ Two workflows active: old (incomplete) and new (correct structure)
   - ✅ Documentation created: `SESSION_SUMMARY.md`, `CURRENT_STATUS.md`, `TEST_COMMANDS.md`
   - **Issue:** Old workflow missing SSH SDK Call node

### 🎯 In Progress (Simplified)
**Phase 3:** Todo-Based Autonomous Development
- 6-node simple workflow (vs 11-node complex)
- OpenHands SDK integration verified working
- Todo creation and execution loop (pending testing)
- Full-stack app proof of concept
- **Decision required:** Keep/remove imported workflow (ID: p6Gt8h23NrsWIk4R)
- **Plan:** `SIMPLIFIED_PHASE3_PLAN.md`
- **Testing:** `TEST_COMMANDS.md`

---

## 🎉 FINAL STATUS

- **Repository:** https://git.oky.sh/gitadmin/mvp-factory-openhands
- **n8n Instance:** https://n8n.oky.sh
- **Production Workflows:** 2 active (eZ5zoeglwRrL7lOf, p6Gt8h23NrsWIk4R)
- **OpenHands SDK:** ✅ Verified working (creates TODO.md)
- **Data Preservation:** ✅ Working
- **Documentation:** ✅ Organized & Updated (8 files)
- **Phase 2:** ✅ COMPLETE
- **Phase 3:** 🚀 IN PROGRESS (Investigation complete, testing pending)

**Current Goal:**
1. Decide on workflow to use (keep old + add SSH, or keep new)
2. Test TODO.md creation via webhook
3. Implement full todo execution loop

**Key Files:**
- `SIMPLIFIED_PHASE3_PLAN.md` - Implementation plan
- `SESSION_SUMMARY.md` - Investigation results
- `CURRENT_STATUS.md` - Workflow status
- `TEST_COMMANDS.md` - Testing procedures

---

*Last Updated: 2025-12-03*
*Phase 2 complete, Phase 3 investigation complete, testing pending*