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

14 KiB
Raw Permalink Blame History

🚀 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

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

/home/bam/openhands-sdk-wrapper-fixed.py  (Python script)

Usage in n8n Code Node

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:

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:

# 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

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)

$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

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

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

# 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

# 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

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