romfast/clawd
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Cleanup Ralph workflow: remove old attempts, update docs for final Python-based system

Browse Source
This commit is contained in:
Echo
2026-02-09 10:21:37 +00:00
parent 4cbf8bfe1e
commit 46db3a6722
5 changed files with 465 additions and 386 deletions
Download Patch File Download Diff File Expand all files Collapse all files

417
memory/kb/tools/ralph-workflow.md
View File

@@ -1,86 +1,183 @@
# Ralph Workflow - Sistem Complet
**Locație:** moltbot (LXC 110) - Claude Code instalat local
**Workspace:** `~/workspace/`
**Helper:** `~/clawd/tools/ralph_workflow.py`
**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. Skill Ralph (Claude Code)
**Locație:** `~/.claude/skills/ralph/`
### 1. ralph_prd_generator.py
**Comenzi disponibile:**
- `/ralph:prd` - Generează PRD structurat cu întrebări adaptive
- `/ralph:convert` - Convertește PRD markdown în prd.json + configurare proiect
**Locație:** `~/clawd/tools/ralph_prd_generator.py`
**Funcție:** Generează PRD markdown și prd.json fără să apeleze Claude Code.
**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)**
- 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:**
```python
from tools.ralph_workflow import create_prd, convert_prd, run_ralph
from tools.ralph_prd_generator import create_prd_and_json
from pathlib import Path
# Creează PRD
prd_file = create_prd(
prd_file, prd_json = create_prd_and_json(
project_name="task-tracker", # kebab-case
description="""
Vreau un task tracker simplu pentru CLI.
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:**
```bash
# 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:**
```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
)
# Convertește în prd.json
prd_json = convert_prd(prd_file)
# Lansează Ralph în background
run_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'])}")
```
**Pas 2: Git init + push**
### 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:**
```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
cd ~/workspace/PROJECT
./scripts/ralph/ralph.sh 20 # max 20 iterații
```
### Morning Report (08:30)
## 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):**
```python
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:**
@@ -88,36 +185,26 @@ git push -u origin main
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
for project_name in active_projects:
status = check_status(Path.home() / "workspace" / project_name)
# Raportează în Discord
print(f"""
## 🔄 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
### {project_name}
- ✅ Complete: {len(status['complete'])} stories
- 🔄 Incomplete: {len(status['incomplete'])} stories
- 🔄 Running: {'DA (PID: ' + str(status.get('pid', '')) + ')' if status['running'] else 'NU'}
📚 Learnings:
- SQLite migrations best practices
- Click CLI argument parsing
- Pytest fixtures for DB testing
**Stories complete:**
{chr(10).join(f" - {s['id']}: {s['title']}" for s in status['complete'][:5])}
🔗 Link: https://gitea.romfast.ro/romfast/task-tracker
**Learnings:**
{chr(10).join(f" {l}" for l in status['learnings'][-3:])}
🔗 https://gitea.romfast.ro/romfast/{project_name}
""")
```
## Structură Proiect
@@ -127,57 +214,72 @@ După workflow complet:
```
~/workspace/PROJECT-NAME/
├── tasks/
│ └── prd-PROJECT-NAME.md # PRD markdown (generat de /ralph:prd)
│ └── prd-PROJECT-NAME.md # PRD markdown (generat de Opus)
├── 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)
│ ├── 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 verificări UI (dacă aplicabil)
├── src/ # Cod implementat de Ralph
├── .claude/
│ └── settings.json # Permissions allow-list (generat de /ralph:convert)
│ └── screenshots/ # Screenshots UI
├── src/ # Cod implementat de Ralph (Sonnet)
└── .git/ # Git repo → gitea
```
## Comenzi Rapide
## Format prd.json
### 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
```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": ""
}
]
}
```
### Python Helper (pentru automatizare)
## Model Strategy (OBLIGATORIU)
```bash
# Creează proiect complet (PRD + conversie + launch)
python3 ~/clawd/tools/ralph_workflow.py create "task-tracker" "Task tracker simplu pentru CLI"
| 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) |
# Verifică status
python3 ~/clawd/tools/ralph_workflow.py status "task-tracker"
```
**Regula:**
- **Opus (strategic)** = Planning, PRD, stories, decizie ce se implementează
- **Sonnet (tactical)** = Coding, debugging, testing, implementare efectivă
## Monitorizare
@@ -195,19 +297,17 @@ jq '.userStories[] | select(.passes == true) | {id, title}' \
~/workspace/PROJECT/scripts/ralph/prd.json
```
### După execuție
### Status Python
```bash
# Stories incomplete (priority sort)
jq '.userStories[] | select(.passes != true) | {id, title, priority}' \
~/workspace/PROJECT/scripts/ralph/prd.json | jq -s 'sort_by(.priority)'
```python
from tools.ralph_workflow import check_status
from pathlib import Path
# Ultimele learnings
tail -20 ~/workspace/PROJECT/scripts/ralph/progress.txt
status = check_status(Path.home() / "workspace" / "PROJECT")
# Git commits de la Ralph
cd ~/workspace/PROJECT
git log --oneline --since="last night"
print(f"Running: {status['running']}")
print(f"Complete: {len(status['complete'])}")
print(f"Incomplete: {len(status['incomplete'])}")
```
## Troubleshooting
@@ -215,11 +315,8 @@ git log --oneline --since="last night"
### Ralph nu pornește
```bash
# Verifică Claude Code instalat
claude --version
# Verifică skill ralph disponibil
ls -la ~/.claude/skills/ralph/
# Verifică că ralph.sh există
ls -la ~/workspace/PROJECT/scripts/ralph/ralph.sh
# Verifică prd.json valid
jq '.' ~/workspace/PROJECT/scripts/ralph/prd.json
@@ -232,7 +329,7 @@ jq '.' ~/workspace/PROJECT/scripts/ralph/prd.json
tail -50 ~/workspace/PROJECT/scripts/ralph/logs/ralph.log
# Marchează manual story ca done (pentru a continua)
jq '.userStories[2].passes = true' \
jq '.userStories[0].passes = true' \
~/workspace/PROJECT/scripts/ralph/prd.json > tmp && mv tmp prd.json
```
@@ -246,36 +343,30 @@ cat ~/workspace/PROJECT/scripts/ralph/.ralph.pid | xargs kill
pkill -f ralph.sh
```
## Model Strategy (OBLIGATORIU)
## Templates Source
- **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
**Locație:** `~/clawd/skills/ralph/templates/`
## Integration cu AGENTS.md
**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)
**Pentru night-execute job:**
**NU edita template-urile** - sunt copiate automat în fiecare proiect.
```python
# În night-execute cron job
import sys
sys.path.append('/home/moltbot/clawd')
## Diferențe față de sistemul vechi
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)
```
| Î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 |
---
**Updated:** 2026-02-09
**Version:** 2.0 (local pe moltbot, fără SSH)
**Status:** ✅ PRODUCTION READY
**Testat:** 2026-02-09
**Version:** 2.0 (finală)
**Next:** Integrare night-execute