romfast/echo-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(claude): consolidate Ralph + planning agent documentation post W1+W2+W3

Browse Source 
Update secțiunea Ralph cu:
- Două căi de aprobare (direct /a sau /plan conversational)
- Comenzi noi: /plan, /cancel; UX interactiv pe /l (Views/InlineKeyboardMarkup)
- Schema approved-tasks.json extinsă (planning_session_id, final_plan_path)
- Smart gates dispatcher pe story.tags (W3)
- DAG-aware execution + retry guard + rate limit detection
- Dashboard live (/echo/ralph.html, /api/ralph/status)
- Story status: passes/retries/blocked în prd.json

Adăugat în "Fișiere cheie": planning_session.py, planning_orchestrator.py,
ralph_dag.py, ralph_flow.py, discord_views.py, ralph.html, handlers/ralph.py,
prompts/planning_agent.md, tasks/spike-planning-findings.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marius Mutu
2026-04-26 18:44:30 +00:00
parent 4b494eb2f2
commit bf9380f2ad
1 changed files with 48 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
CLAUDE.md
View File

@@ -145,25 +145,41 @@ Sistem de implementare autonomă care rulează noaptea. Flow complet:
``` ```
21:00 evening-report → propune features/proiecte, adaugă în approved-tasks.json (status: pending) 21:00 evening-report → propune features/proiecte, adaugă în approved-tasks.json (status: pending)
email lui Marius cu instrucțiuni !approve email lui Marius cu instrucțiuni de aprobare
Marius → !approve <slug> (Discord/Telegram/WhatsApp → router.py → approved-tasks.json status: approved) Marius → /a <slug> (Discord/Telegram/WhatsApp → router.py → status: approved
23:00 night-execute → citește approved, clonează repo dacă lipsește, generează PRD, lansează ralph.sh SAU /plan <slug> → planning agent conversational → final-plan.md → approved)
actualizează approved-tasks.json (status: running, pid: PID) 23:00 night-execute → citește approved, clonează repo dacă lipsește, generează PRD din final-plan.md,
lansează ralph.sh; actualizează approved-tasks.json (running, pid: PID)
08:30 morning-report → citește approved-tasks.json + prd.json per proiect, raportează stories done/total 08:30 morning-report → citește approved-tasks.json + prd.json per proiect, raportează stories done/total
Live dashboard → /echo/ralph.html (polling 5s) — cards per proiect cu status, iter, ETA, log, stop
``` ```
**Două căi de aprobare**:
- **Direct**: `/a <slug>` — pentru proiecte simple unde descrierea e suficientă
- **Conversational** (W2 — `/plan <slug>` SAU buton "Planifică" pe `/l`): Echo poartă o conversație multi-fază prin skills gstack (`/office-hours` → `/plan-ceo-review` → `/plan-eng-review` → opțional `/plan-design-review` dacă tags include "ui"), produce `~/workspace/<slug>/scripts/ralph/final-plan.md` și prezintă rezumat cu butonul "✅ Dau drumul tonight". `night-execute` îl folosește ca input pentru PRD generator (Opus extrage user stories cu acceptanceCriteria, tags, dependsOn).
**Comenzi** (funcționează pe toate adaptoarele — Discord, Telegram, WhatsApp): **Comenzi** (funcționează pe toate adaptoarele — Discord, Telegram, WhatsApp):
| Comandă | Efect | | Comandă | Efect |
|---------|-------| |---------|-------|
| `/p <slug> <descriere>` | Adaugă proiect nou cu status `pending` | | `/p <slug> <descriere>` | Adaugă proiect nou cu status `pending` |
| `/a` | Listează proiectele pending | | `/a` | Listează proiectele pending |
| `/a <slug>` sau `/a P1,P2` | Aprobă pentru tonight | | `/a <slug>` sau `/a P1,P2` | Aprobă pentru tonight (path direct) |
| `/l` | Status toate proiectele (PID, stories done/total) | | `/plan <slug>` | Pornește planning agent conversational (multi-fază skills gstack) |
| `/cancel` | Anulează planning în curs (revert status → pending) |
| `/l` | **Discord/Telegram**: meniu interactiv (Views/InlineKeyboardMarkup) cu butoane per proiect; **WhatsApp**: text plain + redirect spre Discord/TG |
| `/l <slug>` | Status proiect specific | | `/l <slug>` | Status proiect specific |
| `/k <slug>` | Trimite SIGTERM la ralph.sh PID | | `/k <slug>` | Trimite SIGTERM la ralph.sh PID |
Pe **Discord** sunt slash commands native cu autocomplete dinamic: `/a <tab>` listează proiectele pending, `/k <tab>` listează proiectele running. Pe **Telegram** apar în meniul `/` cu descriere. Pe **WhatsApp** sunt parsate ca text plain. **UX interactiv** (Discord/Telegram):
- `/l` deschide `RalphRootView` (Discord) / InlineKeyboardMarkup (Telegram) cu butoane per workspace project
- Click pe proiect → submeniu cu acțiuni: ➕ Propune feature (modal/ForceReply), 🧠 Planifică (W2), 👁 Vezi PRD, 📊 Status, ✅ Aprobă tonight, 🛑 Stop, 🔙 Înapoi
- La sfârșitul planning: butoane ✅ Dau drumul tonight / ✏️ Mai gândim / 🛑 Anulează
- State per `(adapter, channel)` în `sessions/ralph_flow.json` și `sessions/planning.json` (TTL 10min/60min)
Pe **Discord**: slash commands native cu autocomplete dinamic: `/p <tab>` listează workspace, `/a <tab>` pending, `/k <tab>` running. Modal cu `TextInput` pentru descriere. Critical pattern: `await interaction.response.defer(ephemeral=True)` în orice button callback cu I/O (Discord 3s timeout).
Pe **Telegram**: `callback_ralph` cu pattern `^ralph:` rutează acțiuni; `ForceReply` pentru input text descriere.
Pe **WhatsApp**: text-only — meniu redirect la Discord/Telegram.
**Aliasuri legacy** (funcționează încă pentru backwards compat): `!propose`, `!approve`, `!status`, `!stop`. **Aliasuri legacy** (funcționează încă pentru backwards compat): `!propose`, `!approve`, `!status`, `!stop`.
@@ -171,16 +187,25 @@ Pe **Discord** sunt slash commands native cu autocomplete dinamic: `/a <tab>` li
| Path | Rol | | Path | Rol |
|------|-----| |------|-----|
| `approved-tasks.json` | Coordonare între cele 3 cron jobs. Schema: `{name, description, status, proposed_at, approved_at, started_at, pid}` | | `approved-tasks.json` | Coordonare între cron jobs + UX. Schema: `{name, description, status, planning_session_id, final_plan_path, proposed_at, approved_at, started_at, pid}` |
| `tools/ralph/ralph.sh` | Bash loop: N iterații × `claude` CLI per story din prd.json | | `prompts/planning_agent.md` | System prompt pentru `PlanningSession` (multi-fază conversational) |
| `tools/ralph/prompt.md` | Instrucțiuni Claude Code per iterație Ralph | | `src/planning_session.py` | Wrapper subprocess `claude -p` cu working dir = `~/workspace/<slug>/`, `--add-dir` skills gstack + project artifacts. `--max-turns=20` cu retry pe `error_max_turns` |
| `tools/ralph/prd-template.json` | Template pentru prd.json generat de Opus | | `src/planning_orchestrator.py` | Coordonează fazele: fresh subprocess per skill phase; coordinează prin disk artifacts gstack convention; tag detection ui-scope |
| `tools/ralph_prd_generator.py` | Generează PRD + prd.json cu model Opus | | `sessions/planning.json` | State per `(adapter, channel)` planning session: session_id, current_phase, etc. — pentru re-resume la restart |
| `~/workspace/<name>/scripts/ralph/prd.json` | PRD per proiect — user stories cu câmp `passes` | | `tools/ralph/ralph.sh` | Bash loop DAG-aware: N iterații × `claude` CLI per story; folosește `tools/ralph_dag.py` pentru selecție topologică, retry guard (3 retries), rate-limit detection |
| `tools/ralph/prompt.md` | Smart gates dispatcher pe `story.tags` (Faza 3): refactor→/workflow:simplify, ui→/qa+screenshot, vercel→push+gh checks, db→schema diff, default→/review |
| `tools/ralph/prd-template.json` | Template prd.json: stories cu `acceptanceCriteria[]`, `tags[]`, `dependsOn[]`, `passes`, `retries` |
| `tools/ralph_prd_generator.py` | Generează prd.json. Cu `final_plan_path` (de la PlanningOrchestrator) → Opus extrage stories cu acceptance criteria. Fără → backwards-compat description-only |
| `tools/ralph_dag.py` | Pure functions Python (testabile): `infer_tags_from_paths`, `force_include_tags`, `topological_eligible`, `mark_failed`, blocked propagation iterativă. CLI subcommands chemate din ralph.sh (`infer-tags`, `next-story`, `mark-failed`, `incr-retry`) |
| `~/workspace/<name>/scripts/ralph/final-plan.md` | Output planning agent — citit de PRD generator |
| `~/workspace/<name>/scripts/ralph/prd.json` | PRD per proiect cu schema extinsă |
| `~/workspace/<name>/scripts/ralph/logs/` | Loguri ralph.sh per rulare | | `~/workspace/<name>/scripts/ralph/logs/` | Loguri ralph.sh per rulare |
| `dashboard/handlers/ralph.py` | Endpoints `/api/ralph/status`, `/<slug>/log`, `/<slug>/prd`, `/<slug>/stop` |
| `dashboard/ralph.html` | UI live cards, polling 5s, status badges, ETA, butoane log/prd/stop |
| `dashboard/.env` | `GITEA_TOKEN` pentru clone HTTPS la `gitea.romfast.ro` | | `dashboard/.env` | `GITEA_TOKEN` pentru clone HTTPS la `gitea.romfast.ro` |
**Status flow:** `pending` → `approved` → `running` → `complete` / `failed` / `stopped` **Status flow:** `pending` → (`planning` →) `approved` → `running` → `complete` / `failed` / `stopped` / `blocked` (DAG)
**Story status (în prd.json):** `passes:false` + `retries:N` → `passes:true` SAU `failed:rate_limited|max_retries`
**Workspace proiecte** (`~/workspace/`): roa2web, gomag-vending, vending_data_intelligence_report, btgo-playwright, space-booking, romfast-website, game-library, wol, romfastsql **Workspace proiecte** (`~/workspace/`): roa2web, gomag-vending, vending_data_intelligence_report, btgo-playwright, space-booking, romfast-website, game-library, wol, romfastsql
@@ -211,9 +236,16 @@ Import-uri absolute via `sys.path.insert(0, PROJECT_ROOT)`: `from src.config imp
| `dashboard/constants.py` | Path-uri centralizate + config Gitea pentru dashboard | | `dashboard/constants.py` | Path-uri centralizate + config Gitea pentru dashboard |
| `dashboard/echo-taskboard.service` | Template systemd user unit | | `dashboard/echo-taskboard.service` | Template systemd user unit |
| `cron/jobs.json` | Job-uri APScheduler (schemă plată, Europe/Bucharest) | | `cron/jobs.json` | Job-uri APScheduler (schemă plată, Europe/Bucharest) |
| `approved-tasks.json` | Fișier coordonare Ralph — status proiecte autonome | | `approved-tasks.json` | Fișier coordonare Ralph — status proiecte autonome (extins cu `planning_session_id`, `final_plan_path`) |
| `tasks/lessons.md` | Lecții capturate din corectările lui Marius (citit la session start) | | `tasks/lessons.md` | Lecții capturate din corectările lui Marius (citit la session start) |
| `tools/ralph/ralph.sh` | Bash loop Ralph (N iter × claude CLI per story) | | `tasks/spike-planning-findings.md` | Validare empirică Spike Step 0 (subprocess `claude -p` + skills gstack + `--resume` round-trip) |
| `prompts/planning_agent.md` | System prompt pentru planning agent multi-fază (W2) |
| `src/ralph_flow.py` | State per `(adapter, chat, user)` pentru UX flow (TTL 10min) |
| `src/planning_session.py` | Wrapper Claude subprocess pentru planning agent |
| `src/planning_orchestrator.py` | Orchestrare faze gstack skills (W2) |
| `src/adapters/discord_views.py` | Discord Views/Modal pentru UX interactiv (W1) |
| `tools/ralph/ralph.sh` | Bash loop DAG-aware (W3): N iter × claude CLI per story |
| `tools/ralph_dag.py` | DAG helpers + CLI (W3) |
| `tools/ralph_prd_generator.py` | Generează PRD + prd.json cu Opus | | `tools/ralph_prd_generator.py` | Generează PRD + prd.json cu Opus |
## gstack ## gstack