clawd/memory/kb/tools/ralph-workflow.md

Ralph Workflow - Sistem Complet

Locație: moltbot (LXC 110) - Claude Code instalat local Workspace: ~/workspace/ Helper: ~/clawd/tools/ralph_workflow.py

Componente

1. Skill Ralph (Claude Code)

Locație: ~/.claude/skills/ralph/

Comenzi disponibile:

• /ralph:prd - Generează PRD structurat cu întrebări adaptive
• /ralph:convert - Convertește PRD markdown în prd.json + configurare proiect

Features:

• Detecție automată context (proiect nou vs feature existent)
• Întrebări adaptive (10 pentru nou, 5-7 pentru feature)
• Web research opțional pentru best practices
• Generare .claude/settings.json cu allow-list per tech stack
• Configurare automată scripts/ralph/

2. Ralph Loop (ralph.sh)

Locație: Copiat automat în PROJECT/scripts/ralph/ralph.sh

Funcționare:

1. Citește prd.json
2. Selectează story cu priority minimă + passes=false
3. Rulează claude pentru implementare
4. Quality checks: typecheck, lint, test
5. Git commit dacă OK → passes: true
6. Update progress.txt cu learnings
7. Repetă până toate complete sau max iterations

3. Helper Python

Locație: ~/clawd/tools/ralph_workflow.py

Funcții:

• create_prd() - Apelează Claude Code cu /ralph:prd
• convert_prd() - Apelează Claude Code cu /ralph:convert
• run_ralph() - Lansează ralph.sh în background/foreground
• check_status() - Verifică progres (stories complete/incomplete, learnings)

Workflow Complet (pentru Echo)

Night Execute (23:00)

Pas 1: Planning cu Opus (Echo)

from tools.ralph_workflow import create_prd, convert_prd, run_ralph

# Creează PRD
prd_file = create_prd(
    project_name="task-tracker",  # kebab-case
    description="""
    Vreau un task tracker simplu pentru CLI.
    Features:
    - Add/list/done tasks
    - SQLite storage
    - Export markdown
    """
)

# Convertește în prd.json
prd_json = convert_prd(prd_file)

# Lansează Ralph în background
run_ralph(prd_json, max_iterations=20, background=True)

Pas 2: Git init + push

cd ~/workspace/task-tracker
git init
git remote add origin https://gitea.romfast.ro/romfast/task-tracker
git add .
git commit -m "Initial commit with PRD and Ralph config"
git push -u origin main

Morning Report (08:30)

Verifică status:

from tools.ralph_workflow import check_status
from pathlib import Path

status = check_status(Path.home() / "workspace" / "task-tracker")

print(f"✅ Complete: {len(status['complete'])}")
print(f"🔄 Incomplete: {len(status['incomplete'])}")
print(f"📚 Learnings: {status['learnings'][-3:]}")

Raportează în Discord:

## 🔄 Proiecte Ralph

### task-tracker
- Status: ✅ 5/8 stories complete
- Progress:
  - ✅ US-001: Database schema + migrations
  - ✅ US-002: Add task CLI command
  - ✅ US-003: List tasks with filters
  - ✅ US-004: Mark task as done
  - ✅ US-005: Export to markdown
  - 🔄 US-006: Tests for all commands (în progres)
  - ⚠️ US-007: README documentation (blocat)
  - 🔄 US-008: CI/CD setup

📚 Learnings:
- SQLite migrations best practices
- Click CLI argument parsing
- Pytest fixtures for DB testing

🔗 Link: https://gitea.romfast.ro/romfast/task-tracker

Structură Proiect

După workflow complet:

~/workspace/PROJECT-NAME/
├── tasks/
│   └── prd-PROJECT-NAME.md      # PRD markdown (generat de /ralph:prd)
├── scripts/
│   └── ralph/
│       ├── prd.json              # Stories pentru Ralph (generat de /ralph:convert)
│       ├── progress.txt          # Learnings per iterație (generat de ralph.sh)
│       ├── ralph.sh              # Loop autonom (copiat de /ralph:convert)
│       ├── prompt.md             # Instrucțiuni per iterație (copiat)
│       ├── .ralph.pid            # PID proces Ralph (pentru monitoring)
│       ├── logs/
│       │   └── ralph.log         # Output Ralph loop
│       ├── archive/              # Arhive rulări anterioare
│       └── screenshots/          # Screenshots verificări UI (dacă aplicabil)
├── src/                          # Cod implementat de Ralph
├── .claude/
│   └── settings.json             # Permissions allow-list (generat de /ralph:convert)
└── .git/                         # Git repo → gitea

Comenzi Rapide

CLI Direct (pentru debug)

# Verifică skill-uri disponibile
claude skills list | grep ralph

# Test /ralph:prd (manual)
cd ~/workspace/test-project
claude exec "/ralph:prd

Vreau să creez un calculator simplu."

# Test /ralph:convert (manual)
claude exec "/ralph:convert

Convertește PRD din tasks/prd-calculator.md"

# Rulează Ralph manual
cd ~/workspace/test-project
./scripts/ralph/ralph.sh 10  # max 10 iterații

Python Helper (pentru automatizare)

# Creează proiect complet (PRD + conversie + launch)
python3 ~/clawd/tools/ralph_workflow.py create "task-tracker" "Task tracker simplu pentru CLI"

# Verifică status
python3 ~/clawd/tools/ralph_workflow.py status "task-tracker"

Monitorizare

În timpul execuției

# Verifică dacă Ralph rulează
ps aux | grep ralph.sh

# Tail logs live
tail -f ~/workspace/PROJECT/scripts/ralph/logs/ralph.log

# Verifică stories complete
jq '.userStories[] | select(.passes == true) | {id, title}' \
  ~/workspace/PROJECT/scripts/ralph/prd.json

După execuție

# Stories incomplete (priority sort)
jq '.userStories[] | select(.passes != true) | {id, title, priority}' \
  ~/workspace/PROJECT/scripts/ralph/prd.json | jq -s 'sort_by(.priority)'

# Ultimele learnings
tail -20 ~/workspace/PROJECT/scripts/ralph/progress.txt

# Git commits de la Ralph
cd ~/workspace/PROJECT
git log --oneline --since="last night"

Troubleshooting

Ralph nu pornește

# Verifică Claude Code instalat
claude --version

# Verifică skill ralph disponibil
ls -la ~/.claude/skills/ralph/

# Verifică prd.json valid
jq '.' ~/workspace/PROJECT/scripts/ralph/prd.json

Ralph blochează pe o story

# Verifică logs
tail -50 ~/workspace/PROJECT/scripts/ralph/logs/ralph.log

# Marchează manual story ca done (pentru a continua)
jq '.userStories[2].passes = true' \
  ~/workspace/PROJECT/scripts/ralph/prd.json > tmp && mv tmp prd.json

Oprește Ralph

# Kill process
cat ~/workspace/PROJECT/scripts/ralph/.ralph.pid | xargs kill

# Sau kill all
pkill -f ralph.sh

Model Strategy (OBLIGATORIU)

• Opus → Planning, PRD, stories (Echo în night-execute)
  • Apelează create_prd() și convert_prd()
• Sonnet → Coding, debugging, implementare (Ralph loop)
  • Ralph folosește Claude Code cu Sonnet implicit

Integration cu AGENTS.md

Pentru night-execute job:

# În night-execute cron job
import sys
sys.path.append('/home/moltbot/clawd')

from tools.ralph_workflow import create_prd, convert_prd, run_ralph
from pathlib import Path

# Citește approved-tasks.md pentru proiecte aprobate
# ...

# Pentru fiecare proiect aprobat
for project in approved_projects:
    prd = create_prd(project['name'], project['description'])
    prd_json = convert_prd(prd)
    run_ralph(prd_json, max_iterations=20, background=True)

---

Updated: 2026-02-09 Version: 2.0 (local pe moltbot, fără SSH)