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)**

```python
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**

```bash
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:**

```python
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:**

```markdown
## 🔄 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)

```bash
# 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)

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

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

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

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

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

```bash
# 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:**

```python
# Î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)