From 145e1eb3ab4c61f38d8440843620b51d6b15866d Mon Sep 17 00:00:00 2001 From: Marius Mutu Date: Sun, 26 Apr 2026 15:52:22 +0000 Subject: [PATCH] docs(claude): document Ralph autonomous execution system Add full Ralph section to CLAUDE.md: flow diagram, !approve/!status/!stop commands, file paths, status lifecycle, workspace projects list, and safety rules (no core files, echo-core self-improve only on dedicated branch). Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index a14a48e..1dc3819 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,10 +59,58 @@ source .venv/bin/activate && pip install -r requirements.txt **Heartbeat** (`src/heartbeat.py`): Email, calendar, KB, git checks. Quiet hours 23-08. +**Ralph** (`tools/ralph/`): Autonomous project execution system. `ralph.sh` este un bash loop care cheamă `claude` CLI (subscription, nu API) per user story din `prd.json`. Generarea PRD se face cu `tools/ralph_prd_generator.py` (model Opus). Workspace-ul proiectelor e la `~/workspace/`. + **Memory** (`src/memory_search.py`): Ollama all-minilm embeddings (384 dim) + SQLite cosine similarity. Lives at `memory/` inside this repo — single source of truth. Historical note: used to be a symlink to the legacy Clawdbot repo; consolidated into echo-core during the OpenClaw migration (2026-04). **Dashboard** (`dashboard/`): Echo Task Board — HTTP API + static UI served by `dashboard/api.py` on port 8088, typically behind a reverse proxy at `/echo/`. Endpoint logic split across `dashboard/handlers/*.py` mixins; paths centralised in `dashboard/constants.py`. Systemd user unit template at `dashboard/echo-taskboard.service`. +## Ralph — Autonomous Project Execution + +Sistem de implementare autonomă care rulează noaptea. Flow complet: + +``` +21:00 evening-report → propune features/proiecte, adaugă în approved-tasks.json (status: pending) + email lui Marius cu instrucțiuni !approve +Marius → !approve (Discord/Telegram/WhatsApp → router.py → approved-tasks.json status: approved) +23:00 night-execute → citește approved, clonează repo dacă lipsește, generează PRD, lansează ralph.sh + actualizează approved-tasks.json (status: running, pid: PID) +08:30 morning-report → citește approved-tasks.json + prd.json per proiect, raportează stories done/total +``` + +**Comenzi text** (funcționează pe toate adaptoarele — Discord, Telegram, WhatsApp): + +| Comandă | Efect | +|---------|-------| +| `!propose ` | Adaugă proiect nou cu status `pending` | +| `!approve` | Listează proiectele pending | +| `!approve ` sau `!approve P1,P2` | Aprobă pentru tonight | +| `!status` | Status toate proiectele (PID, stories done/total) | +| `!status ` | Status proiect specific | +| `!stop ` | Trimite SIGTERM la ralph.sh PID | + +**Fișiere cheie Ralph:** + +| Path | Rol | +|------|-----| +| `approved-tasks.json` | Coordonare între cele 3 cron jobs. Schema: `{name, description, status, proposed_at, approved_at, started_at, pid}` | +| `tools/ralph/ralph.sh` | Bash loop: N iterații × `claude` CLI per story din prd.json | +| `tools/ralph/prompt.md` | Instrucțiuni Claude Code per iterație Ralph | +| `tools/ralph/prd-template.json` | Template pentru prd.json generat de Opus | +| `tools/ralph_prd_generator.py` | Generează PRD + prd.json cu model Opus | +| `~/workspace//scripts/ralph/prd.json` | PRD per proiect — user stories cu câmp `passes` | +| `~/workspace//scripts/ralph/logs/` | Loguri ralph.sh per rulare | +| `dashboard/.env` | `GITEA_TOKEN` pentru clone HTTPS la `gitea.romfast.ro` | + +**Status flow:** `pending` → `approved` → `running` → `complete` / `failed` / `stopped` + +**Workspace proiecte** (`~/workspace/`): roa2web, gomag-vending, vending_data_intelligence_report, btgo-playwright, space-booking, romfast-website, game-library, wol, romfastsql + +**Reguli importante:** +- Ralph NU modifică niciodată `src/router.py`, `src/claude_session.py` sau alte fișiere core din echo-core +- Self-improvement echo-core NUMAI pe branch `ralph/echo-improve`, niciodată pe master +- Clone-urile folosesc `GITEA_TOKEN` din `dashboard/.env`: `https://moltbot:${TOKEN}@gitea.romfast.ro/romfast/.git` + ## Import Convention Absolute imports via `sys.path.insert(0, PROJECT_ROOT)`: `from src.config import ...`, `from src.adapters.discord_bot import ...`. No circular imports. @@ -85,6 +133,9 @@ Absolute imports via `sys.path.insert(0, PROJECT_ROOT)`: `from src.config import | `dashboard/constants.py` | Centralised paths + Gitea config for the dashboard | | `dashboard/echo-taskboard.service` | Systemd user unit template | | `cron/jobs.json` | APScheduler jobs (flat schema, Europe/Bucharest) | +| `approved-tasks.json` | Ralph coordination file — status proiecte autonome | +| `tools/ralph/ralph.sh` | Ralph bash loop (N iter × claude CLI per story) | +| `tools/ralph_prd_generator.py` | Generează PRD + prd.json cu Opus | ## gstack