mvp-factory-openhands/WORKFLOW_SUMMARY.md

# Todo-Based MVP Builder Workflow - Summary

## ✅ Successfully Created

### Workflow Details
- **Name:** Todo-Based MVP Builder
- **ID:** L0VYVJyEwGsA1bqe
- **Status:** Active ✅
- **Nodes:** 6 nodes
- **Webhook Path:** /webhook/todo-mvp-builder
- **Webhook URL:** https://n8n.oky.sh/webhook/todo-mvp-builder

### 6-Node Structure

#### Node 1: Webhook
- **Type:** Webhook
- **Path:** todo-mvp-builder
- **Method:** POST
- **Response Mode:** Response Node
- **Purpose:** Receives Gitea push events

#### Node 2: Extract Repo Info (Code)
- **Purpose:** Parse repository data from webhook payload
- **Extracts:**
  - repo_name
  - repo_full_name
  - repo_clone_url
  - branch
  - commit_sha
  - commit_message
  - is_initial_push (checks for "MVP Prompt:" prefix)
  - prompt (extracted from commit message)

#### Node 3: Get Next Todo (Code)
- **Purpose:** Manage todo state using workflow.staticData
- **Logic:**
  - If initial push (is_initial_push = true): Set status to 'CREATING_TODOS'
  - If todos exist: Get next todo by index
  - If all todos complete: Set status to 'SUCCESS'
  - If no todos: Return error

#### Node 4: Execute Todo (Code)
- **Purpose:** Execute tasks via OpenHands SDK (placeholder implementation)
- **Handles:**
  - create_todos action: Prepares task for TODO.md creation
  - execute_todo action: Prepares task for todo execution
- **Note:** Currently returns placeholder data - SDK integration is TODO

#### Node 5: Test Changes (Code)
- **Purpose:** Validate execution results
- **Logic:**
  - If success: Return success status with commit message
  - If failure: Return failure status but continue for debugging
- **Formats:**
  - Commit message with emoji (📋 for todos, ✅ for completed tasks)
  - Gitea status state (success/failure)

#### Node 6: Commit & Push (Code)
- **Purpose:** Format results and manage loop
- **Logic:**
  - Logs what would be committed to Gitea
  - Sets loop=true to continue to next todo
  - Handles final completion status
- **Loop:** Connects back to Node 3 (Get Next Todo)

### Data Flow

```
Gitea Push
  ↓
Webhook Trigger
  ↓
Extract Repo Info (parses payload, detects MVP Prompt)
  ↓
Get Next Todo (manages state, gets current todo)
  ↓
Execute Todo (calls OpenHands SDK - placeholder)
  ↓
Test Changes (validates results)
  ↓
Commit & Push (logs commit, loops back)
  ↓
Get Next Todo (continues or completes)
```

### State Management (staticData)

The workflow uses `$workflow.staticData` to persist data between iterations:

```javascript
workflow.staticData.todos = {
  status: 'CREATING_TODOS' | 'IN_PROGRESS' | 'COMPLETE',
  prompt: '...',           // Original MVP prompt
  current_index: 0,        // Current todo index
  list: [...],             // Array of todos
  results: [...],          // Execution results
  pending_task: '...'      // SDK task to execute
};
```

### Key Features Implemented

✅ **6-Node Workflow Structure**
✅ **Data Preservation Pattern** (using spread operator in code nodes)
✅ **Todo State Management** (staticData tracking)
✅ **Loop Mechanism** (Commit & Push → Get Next Todo)
✅ **Initial Push Detection** (MVP Prompt prefix)
✅ **Test Structure** (success/failure handling)
✅ **Commit Message Formatting** (with emojis)

### TODOs for Full Implementation

🔲 **Node 4: Execute Todo**
- Implement actual OpenHands SDK call
- Add SSH node or HTTP client to call SDK wrapper
- Parse SDK JSON output

🔲 **Node 6: Commit & Push**
- Implement actual Gitea API calls
- Create commits with formatted messages
- Update commit statuses in Gitea

### Success Criteria - Current Status

- [x] Workflow created in n8n
- [x] All 6 nodes configured
- [x] Webhook URL accessible
- [x] Manual trigger works (without errors - skeleton mode)
- [x] Loop structure connected
- [x] Data preservation pattern implemented

### Test Command (Current State)

Since webhook registration may have a delay, use the n8n UI or API to test:

```bash
# Via n8n UI:
# 1. Open https://n8n.oky.sh
# 2. Navigate to workflow "Todo-Based MVP Builder"
# 3. Click "Test workflow"
# 4. Send test data

# Via API (if execution endpoint works):
curl -X POST https://n8n.oky.sh/api/v1/workflows/L0VYVJyEwGsA1bqe/execute \
  -H "X-N8N-API-KEY: $(cat /home/bam/.n8n_api_key)" \
  -H "Content-Type: application/json" \
  -d '{"input": {"body": {...test data...}}}'
```

### Files Created

1. `/home/bam/claude/mvp-factory/todo-mvp-builder-workflow.json` - Workflow definition
2. `/home/bam/claude/mvp-factory/create_workflow.py` - Script to create and activate workflow
3. `/home/bam/claude/mvp-factory/todo-workflow-info.json` - Workflow metadata
4. `/home/bam/claude/mvp-factory/check_workflow.py` - Script to check workflow status
5. `/home/bam/claude/mvp-factory/debug_api.py` - API debugging script

### Next Steps (Step 3 of 8 in SIMPLIFIED_PHASE3_PLAN.md)

According to the simplified phase 3 plan, the next step is:

**Step 3: Implement SDK Integration (45 min)**
- Test OpenHands SDK wrapper directly
- Create SDK call function in Node 4
- Handle JSON output parsing
- Test with simple task: "Create a test file"

This will replace the placeholder logic in Node 4 with actual OpenHands SDK calls.

### Notes

- This is a **skeleton implementation** - nodes are configured but SDK integration is not yet implemented
- The workflow will execute through all nodes without errors
- Current output will show placeholder data from Node 4
- Loop will work but todos list is empty (will show "No todos found" message)
- Actual OpenHands execution will be added in the next implementation step

---

**Status: Step 2 of 8 Complete ✅**
**Created: 2025-12-03**
**Workflow ID: L0VYVJyEwGsA1bqe**