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

Ralph Workflow - Sistem Complet

Versiune: 2.0 (finală - funcțională) Data: 2026-02-09 Locație: moltbot (LXC 110)

Prezentare Generală

Ralph este un sistem pentru crearea și execuția autonomă a proiectelor software prin Claude Code, format din două componente:

1. Echo (Opus) → Generează PRD și user stories în Python
2. Ralph loop (Sonnet) → Implementează autonom cu Claude Code

Componente

1. ralph_prd_generator.py

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

Funcție: Generează PRD markdown și prd.json fără să apeleze Claude Code.

Features:

• Detectează tech stack automat (package.json, pyproject.toml, etc.)
• Generează PRD conform template (obiective, stories, acceptance criteria)
• Creează prd.json cu user stories prioritizate
• Copiază templates (ralph.sh, prompt.md) în proiect
• Configurează comenzi tech stack (start, build, lint, typecheck, test)

Usage:

from tools.ralph_prd_generator import create_prd_and_json
from pathlib import Path

prd_file, prd_json = create_prd_and_json(
    project_name="task-tracker",  # kebab-case
    description="""
    Task tracker CLI în Python.
    Features:
    - Add/list/done tasks
    - SQLite storage
    - Export markdown
    - Tests cu pytest
    """,
    workspace_dir=Path.home() / "workspace"
)

Output:

~/workspace/PROJECT-NAME/
├── tasks/
│   └── prd-PROJECT-NAME.md        # PRD markdown
└── scripts/
    └── ralph/
        ├── prd.json                # Stories JSON
        ├── ralph.sh                # Loop autonom (din templates)
        ├── prompt.md               # Instrucțiuni Claude Code
        ├── progress.txt            # Learnings
        ├── logs/                   # Logs execuție
        ├── archive/                # Arhive rulări anterioare
        └── screenshots/            # Screenshots UI (dacă aplicabil)

2. ralph_workflow.py

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

Funcție: Wrapper simplu pentru workflow complet (PRD + lansare Ralph).

Features:

• Apelează ralph_prd_generator pentru PRD
• Lansează ralph.sh în background
• Monitorizare status proiect

Usage CLI:

# Creează proiect complet (PRD + lansare Ralph)
python3 tools/ralph_workflow.py create "project-name" "description"

# Verifică status
python3 tools/ralph_workflow.py status "project-name"

Usage Python:

from tools.ralph_workflow import run_ralph, check_status
from pathlib import Path

# Lansează Ralph (după ce ai prd.json)
run_ralph(
    prd_json=Path.home() / "workspace" / "PROJECT" / "scripts" / "ralph" / "prd.json",
    max_iterations=20,
    background=True
)

# Verifică status
status = check_status(Path.home() / "workspace" / "PROJECT")
print(f"Complete: {len(status['complete'])}")
print(f"Incomplete: {len(status['incomplete'])}")

3. ralph.sh

Locație: Copiat automat în PROJECT/scripts/ralph/ralph.sh Source: ~/clawd/skills/ralph/templates/ralph.sh

Funcție: Loop autonom care apelează Claude Code pentru implementare.

Workflow:

1. Citește prd.json
2. Selectează story cu priority minimă și passes=false
3. Rulează claude pentru implementare (folosește Sonnet implicit)
4. Quality checks: typecheck, lint, test
5. Git commit dacă toate pass
6. Marchează passes=true în prd.json
7. Update progress.txt cu learnings
8. Repetă până toate stories complete sau max iterations

Usage:

cd ~/workspace/PROJECT
./scripts/ralph/ralph.sh 20  # max 20 iterații

Workflow Complet (pentru Echo)

Seara (20:00) - evening-report

Echo propune 1-2 proiecte noi + 2-3 features pentru proiecte existente. Marius aprobă: "P pentru P1,P2" sau "F pentru F1,F3"

Noapte (23:00) - night-execute

Planning cu OPUS (Echo):

import sys
sys.path.append('/home/moltbot/clawd')

from tools.ralph_prd_generator import create_prd_and_json
from tools.ralph_workflow import run_ralph
from pathlib import Path
import subprocess

# Pentru fiecare proiect aprobat
for project in approved_projects:
    # Generează PRD și prd.json (cu Opus)
    prd_file, prd_json = create_prd_and_json(
        project_name=project['name'],
        description=project['description'],
        workspace_dir=Path.home() / "workspace"
    )
    
    if not prd_file or not prd_json:
        print(f"❌ Eroare la {project['name']}")
        continue
    
    # Git init + commit
    project_dir = prd_json.parent.parent.parent
    subprocess.run(["git", "init"], cwd=project_dir)
    subprocess.run(["git", "add", "."], cwd=project_dir)
    subprocess.run(["git", "commit", "-m", "Initial commit with PRD"], cwd=project_dir)
    subprocess.run(["git", "remote", "add", "origin", 
                   f"https://gitea.romfast.ro/romfast/{project['name']}"], 
                   cwd=project_dir)
    subprocess.run(["git", "push", "-u", "origin", "main"], cwd=project_dir)
    
    # Lansează Ralph loop (cu Sonnet)
    run_ralph(prd_json, max_iterations=20, background=True)
    
    # Marchează [x] în approved-tasks.md

Implementare cu SONNET (Ralph loop automat):

• ralph.sh rulează autonom în background
• Apelează Claude Code (Sonnet) pentru fiecare story
• Quality checks + git commits automate
• Toate commit-urile push-uite automat

Dimineața (08:30) - morning-report

Verifică status:

from tools.ralph_workflow import check_status
from pathlib import Path

for project_name in active_projects:
    status = check_status(Path.home() / "workspace" / project_name)
    
    # Raportează în Discord
    print(f"""
## 🔄 Proiecte Ralph

### {project_name}
- ✅ Complete: {len(status['complete'])} stories
- 🔄 Incomplete: {len(status['incomplete'])} stories
- 🔄 Running: {'DA (PID: ' + str(status.get('pid', '')) + ')' if status['running'] else 'NU'}

**Stories complete:**
{chr(10).join(f"  - {s['id']}: {s['title']}" for s in status['complete'][:5])}

**Learnings:**
{chr(10).join(f"  {l}" for l in status['learnings'][-3:])}

🔗 https://gitea.romfast.ro/romfast/{project_name}
""")

Structură Proiect

După workflow complet:

~/workspace/PROJECT-NAME/
├── tasks/
│   └── prd-PROJECT-NAME.md      # PRD markdown (generat de Opus)
├── scripts/
│   └── ralph/
│       ├── prd.json              # Stories (generat de Opus)
│       ├── progress.txt          # Learnings (generat de Ralph)
│       ├── ralph.sh              # Loop autonom
│       ├── prompt.md             # Instrucțiuni Claude Code
│       ├── .ralph.pid            # PID proces Ralph
│       ├── logs/
│       │   └── ralph.log         # Output Ralph loop
│       ├── archive/              # Arhive rulări anterioare
│       └── screenshots/          # Screenshots UI
├── src/                          # Cod implementat de Ralph (Sonnet)
└── .git/                         # Git repo → gitea

Format prd.json

{
  "projectName": "feature-name",
  "branchName": "ralph/feature-name",
  "description": "Descriere scurtă",
  "techStack": {
    "type": "python",
    "commands": {
      "start": "python main.py",
      "build": "",
      "lint": "ruff check .",
      "typecheck": "mypy .",
      "test": "pytest"
    },
    "port": 8000
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "Titlu story",
      "description": "Ca utilizator, vreau...",
      "priority": 10,
      "acceptanceCriteria": [
        "Criteriu specific",
        "pytest passes"
      ],
      "requiresBrowserCheck": false,
      "passes": false,
      "notes": ""
    }
  ]
}

Model Strategy (OBLIGATORIU)

Componentă	Model	Rulează pe
PRD generation	Opus	Echo session (moltbot)
User stories creation	Opus	Echo session (moltbot)
prd.json generation	Opus	Echo session (moltbot)
Code implementation	Sonnet	Claude Code (via ralph.sh)
Quality checks	Sonnet	Claude Code (via ralph.sh)
Git commits	Sonnet	Claude Code (via ralph.sh)

Regula:

• Opus (strategic) = Planning, PRD, stories, decizie ce se implementează
• Sonnet (tactical) = Coding, debugging, testing, implementare efectivă

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

Status Python

from tools.ralph_workflow import check_status
from pathlib import Path

status = check_status(Path.home() / "workspace" / "PROJECT")

print(f"Running: {status['running']}")
print(f"Complete: {len(status['complete'])}")
print(f"Incomplete: {len(status['incomplete'])}")

Troubleshooting

Ralph nu pornește

# Verifică că ralph.sh există
ls -la ~/workspace/PROJECT/scripts/ralph/ralph.sh

# 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[0].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

Templates Source

Locație: ~/clawd/skills/ralph/templates/

Fișiere:

• ralph.sh - Script principal loop
• prompt.md - Instrucțiuni pentru Claude Code per iterație
• prd-template.json - Template prd.json (opțional)

NU edita template-urile - sunt copiate automat în fiecare proiect.

Diferențe față de sistemul vechi

Înainte	Acum
SSH către claude-agent	Local pe moltbot
Claude Code prin tmux/pexpect	ralph.sh apelează claude direct
Skills /ralph:prd interactive	Python generator în ralph_prd_generator.py
Control manual sesiuni	Complet automat background
Greu de debuguit	Logs clare, status checkable

---

Status: ✅ PRODUCTION READY Testat: 2026-02-09 Version: 2.0 (finală) Next: Integrare night-execute