From e4abf090ed8825251df91508265648bd6a42e3f8 Mon Sep 17 00:00:00 2001 From: Marius Mutu Date: Sun, 21 Dec 2025 23:50:08 +0200 Subject: [PATCH] docs: Add clear problem statement and value proposition to README --- README.md | 695 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 670 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index f7d8ab5..01f8f02 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,690 @@ -# ROA2WEB Auto-Build Plugin Marketplace +# Auto-Build Plugin for Claude Code -Marketplace pentru plugin-ul Auto-Build - sistem de build orchestration bazat pe specificații. +**Intelligent, spec-driven build orchestration with autonomous agents and persistent learning** -## Instalare +## 🎯 La ce te ajută? + +Când dezvolți features complexe cu Claude, te confrunți cu probleme recurente: +- **Pierderea contextului între sesiuni** - Repeți aceleași explicații despre arhitectură, patterns, gotchas +- **Inconsistență** - Fiecare feature folosește abordări diferite pentru aceleași probleme +- **Lipsă de metodologie** - De la idee la cod funcțional, fără proces clar și repetat +- **QA manual** - Review-uri incomplete, bugs descoperite târziu +- **Învățare pierdută** - Soluțiile bune din features anterioare nu se aplică automat în următoarele + +**Auto-Build rezolvă toate acestea** prin 5 agenți specializați care colaborează automat: analizează requirements → scriu specs detaliate → planifică tasks → implementează cod → fac QA și fixing. Totul respectând convențiile tale din CLAUDE.md și învățând din fiecare feature implementat. + +**Rezultat**: Transformi idei vagi în features production-ready, consistent și rapid, fără să repeți explicații sau să reinventezi soluții. + +--- + +## ✨ Ce oferă Auto-Build + +Auto-Build este un plugin oficial Claude Code care transformă modul în care dezvolți features, oferind: +- 🤖 **Autonomous Agents** - 5 agenți specializați care colaborează pentru implementare completă +- 📝 **Spec-Driven Development** - De la idee la cod prin specificații detaliate +- 🧠 **Persistent Memory** - Învățare cross-session prin bidirectional memory (JSON + Markdown) +- 🎯 **Context Awareness** - Integrare nativă cu CLAUDE.md pentru respectarea convențiilor proiectului +- 🌳 **Git Worktree Isolation** - Feature development în worktrees izolate +- ✅ **Automated QA** - Review și fixing automat cu loop de validare + +--- + +## 🚀 Quick Start + +### Instalare -### 1. Adaugă Marketplace ```bash +# 1. Adaugă marketplace-ul /plugin marketplace add https://gitea.romfast.ro/your-org/auto-build.git + +# 2. Instalează plugin-ul +/plugin install ab@roa2web-tools + +# 3. Restart Claude Code +# Post-install hook-ul generează automat: +# - CLAUDE.md (dacă nu există) +# - .claude/rules/auto-build-patterns.md +# - .claude/rules/auto-build-memory.md +# - .auto-build-data/ structure + +# 4. Verifică instalarea +/ab:help ``` -### 2. Instalează Plugin +### Primul Feature + ```bash +# 1. Creează specificație detaliată +/ab:spec "Add user dashboard with stats" + +# 2. Orchestrează implementarea +/ab:build user-dashboard + +# 3. QA review și fixing automat +/ab:qa-review + +# 4. Salvează insights pentru viitor +/ab:memory-save +``` + +**Rezultat**: Feature complet implementat, testat, și învățările salvate pentru următoarele features! + +--- + +## 🏗️ Arhitectură + +### Componente Cheie + +``` +Auto-Build Plugin +│ +├── 🎭 Agents (5) +│ ├── spec-writer → Analizează requirements → spec.md +│ ├── planner → Descompune spec → plan.md cu tasks +│ ├── coder → Implementează tasks → cod funcțional +│ ├── qa-reviewer → Identifică issues → raport QA +│ └── qa-fixer → Rezolvă issues → cod corect +│ +├── 🧠 Memory System (Bidirectional) +│ ├── JSON Files (searchable) +│ │ ├── patterns.json → /ab:memory-search +│ │ └── gotchas.json → /ab:memory-search +│ │ +│ └── Markdown (auto-loaded) +│ └── .claude/rules/auto-build-memory.md +│ → Auto-încărcat în context la fiecare sesiune! +│ +├── 📋 CLAUDE.md Integration +│ ├── Auto-generated la instalare +│ ├── @import directives → auto-build-patterns.md +│ └── Agenții citesc standards/boundaries +│ +└── 🌳 Git Worktrees (optional) + └── Izolare completă pentru features complexe +``` + +### Fluxul Complet + +``` +┌─────────────────────────────────────────────────────────────┐ +│ /ab:spec "Feature" │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ + ┌────────────────────┐ + │ spec-writer agent │ + │ ┌──────────────┐ │ + │ │ Citește: │ │ + │ │ - CLAUDE.md │ │ ← Context Awareness! + │ │ - memory.md │ │ + │ └──────────────┘ │ + └────────┬───────────┘ + │ + ▼ + 📄 spec.md creat + (respectă project conventions!) + │ +┌─────────────────▼───────────────────────────────────────────┐ +│ /ab:build feature-name │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ + ┌────────────────────┐ + │ planner agent │ + │ ┌──────────────┐ │ + │ │ Citește: │ │ + │ │ - CLAUDE.md │ │ ← Folosește patterns! + │ │ - memory.md │ │ + │ └──────────────┘ │ + └────────┬───────────┘ + │ + ▼ + 📋 plan.md cu tasks + (evită known gotchas!) + │ + ▼ + ┌────────────────────────────┐ + │ Optional: Git Worktree │ + │ Feature isolation │ + └────────────┬───────────────┘ + │ + ▼ + ┌────────────────────┐ + │ coder agent │ + │ (loop prin tasks)│ + └────────┬───────────┘ + │ + ▼ + 💻 Cod implementat + │ +┌─────────────────▼───────────────────────────────────────────┐ +│ /ab:qa-review │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ + ┌────────────────────┐ + │ qa-reviewer agent │ + │ Issues found? │ + └────────┬───────────┘ + │ + Yes │ No + ┌────────▼────────┐ + │ │ + ▼ ▼ + ┌─────────┐ ✅ Done + │qa-fixer │ + │ agent │ + └────┬────┘ + │ + └──► Loop max 50 iterations + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ /ab:memory-save │ +└─────────────────┬───────────────────────────────────────────┘ + │ + ▼ + ┌────────────────────────────┐ + │ Salvează în: │ + │ 1. patterns.json │ ← Searchable + │ 2. gotchas.json │ ← Searchable + │ 3. auto-build-memory.md │ ← Auto-loaded! + └────────────────────────────┘ + │ + ▼ + 🎉 Feature complet + învățări salvate! + + Next session → Patterns auto-loaded în context +``` + +--- + +## 🧠 Memory System: Învățare Cross-Session + +### Problema Rezolvată + +**Înainte**: Repeți aceleași explicații în fiecare sesiune +- "Folosim X pattern pentru Y" +- "Evită Z pentru că..." +- "În acest proiect facem așa..." + +**Acum**: Auto-Build învață și își amintește automat! + +### Cum Funcționează + +#### 1. Salvare Insights (`/ab:memory-save`) + +```bash +/ab:memory-save + +# Ghidat de agent: +What insights should be saved? + +[P] Pattern - API error handling approach +[G] Gotcha - Oracle pool timeout issue +> +``` + +Agent salvează în **2 locații simultan**: + +**A) JSON Files** (searchable) +```json +// .auto-build-data/memory/patterns.json +{ + "id": "pat_20250121_143000", + "title": "API Error Handling Pattern", + "description": "All API calls wrapped in try-catch with errorResponse()", + "example": { + "file": "src/api/users.ts", + "snippet": "try { ... } catch (e) { return errorResponse(e) }" + }, + "tags": ["error-handling", "api"] +} +``` + +**B) Markdown File** (auto-loaded) +```markdown +# .claude/rules/auto-build-memory.md + +# Auto-Build Learned Patterns + +Last updated: 2025-01-21T14:30:00Z + +## Patterns + +### API Error Handling Pattern +**Discovered**: 2025-01-21 (feature: user-dashboard) +**Description**: All API calls wrapped in try-catch with errorResponse() + +**Example** (`src/api/users.ts:45-52`): +\```typescript +try { ... } catch (e) { return errorResponse(e) } +\``` + +**Tags**: error-handling, api +``` + +#### 2. Auto-Loading (CRUCIAL!) + +Fișierul `.claude/rules/auto-build-memory.md` este **auto-loaded** de Claude Code la fiecare sesiune! + +**CLAUDE.md** (generat de post-install): +```markdown +# Auto-Build Integration +@./.claude/rules/auto-build-patterns.md +@./.claude/rules/auto-build-memory.md ← AUTO-LOADED! +``` + +**Rezultat**: Următoarea sesiune știe deja toate pattern-urile! + +#### 3. Search (`/ab:memory-search`) + +```bash +/ab:memory-search "error handling" + +# Caută în JSON files și returnează: +Found 3 patterns: +1. [PATTERN] API Error Handling Pattern + Tags: error-handling, api + File: src/api/users.ts + +2. [GOTCHA] Oracle Pool Timeout + Tags: database, error-handling + Solution: Increase POOL_MAX in .env +``` + +### Beneficii + +| Aspect | Fără Memory | Cu Auto-Build Memory | +|--------|-------------|----------------------| +| **Explicații** | Repeți în fiecare sesiune | Auto-loaded, nu repeți | +| **Patterns** | Uitate între sesiuni | Persistent, auto-aplicate | +| **Gotchas** | Reînvățate din greșeli | Evitate automat | +| **Onboarding** | Documentație manuală | Învățat din features anterioare | +| **Consistency** | Variază între features | Patterns consistente | + +--- + +## 🎯 CLAUDE.md Integration: Context-Aware Development + +### Problema Rezolvată + +**Înainte**: Specs și plans ignoră convențiile proiectului +- Spec sugerează arhitectură greșită +- Plan folosește tehnologii nepotrivite +- Cod nu respectă boundaries (Always/Ask/Never) + +**Acum**: Agenții citesc CLAUDE.md și respectă convențiile! + +### Cum Funcționează + +#### 1. Post-Install Hook + +La `/plugin install ab@roa2web-tools`, hook-ul: + +```bash +# 1. Generează CLAUDE.md (dacă nu există) +cp plugin/templates/CLAUDE.md.template → CLAUDE.md + +# 2. Adaugă @import directives +@./.claude/rules/auto-build-patterns.md +@./.claude/rules/auto-build-memory.md +``` + +#### 2. Agenții Citesc Context + +**spec-writer** (înainte de analiză): +```markdown +## Context Integration (PRIORITY) + +1. Read CLAUDE.md: + - Development Standards + - Boundaries (Always/Ask/Never) + - Tech Stack + - Common Commands + +2. Read auto-build-memory.md: + - Learned patterns + - Known gotchas + +3. Apply to Spec: + - Respect boundaries + - Use correct tech stack + - Reference gotchas in "Risks" +``` + +**planner** (înainte de planning): +```markdown +## Context Integration + +1. CLAUDE.md Development Standards: + - Coding standards? + - Testing framework? + - Preferred workflow? + +2. CLAUDE.md Boundaries: + - What requires confirmation? + - What should never be done? + +3. Auto-Build Memory: + - What patterns worked? + - What gotchas to avoid? +``` + +#### 3. Exemplu Real + +**CLAUDE.md**: +```markdown +## Boundaries + +✅ **Always:** +- Use SQLModel for data-entry app (NOT raw SQL) + +⚠️ **Ask First:** +- Modifying database schema + +🚫 **Never:** +- Use Oracle pool in data-entry app (uses SQLite!) +``` + +**spec-writer output**: +```markdown +# Feature Spec: User Dashboard + +## Technical Requirements + +- Backend: SQLModel models (per CLAUDE.md standards) +- Database: SQLite (data-entry app uses SQLite, not Oracle) + +## Risks + +⚠️ Schema Changes: Dashboard requires new tables + → ASK USER for approval before migration (per CLAUDE.md) +``` + +**Rezultat**: Spec corect, respectă boundaries, nu introduce arhitectură greșită! + +--- + +## 🌳 Git Worktrees: Feature Isolation + +Pentru features complexe, Auto-Build poate crea worktrees izolate: + +```bash +# Creează worktree pentru feature +/ab:worktree create user-dashboard + +# Structură: +../ab-worktrees/ + └── roa2web-user-dashboard/ ← Worktree izolat + ├── .git ← Linked to main repo + └── ... ← Feature code + +# Lucrezi în worktree +cd ../ab-worktrees/roa2web-user-dashboard +/ab:build user-dashboard + +# După merge în main +/ab:worktree cleanup user-dashboard +``` + +**Beneficii**: +- Izolare completă (no conflicts cu main) +- Poți lucra pe multiple features simultan +- Cleanup automat după merge + +--- + +## 📋 Comenzi Disponibile + +| Comandă | Descriere | +|---------|-----------| +| `/ab:spec ` | Creează specificație detaliată (via spec-writer agent) | +| `/ab:build ` | Orchestrează implementarea completă (planner + coder) | +| `/ab:worktree ` | Gestionare git worktrees (create/list/cleanup/switch) | +| `/ab:qa-review` | QA validation loop (qa-reviewer + qa-fixer, max 50 iterations) | +| `/ab:memory-save` | Salvează insights în JSON + sync to .claude/rules/ | +| `/ab:memory-search ` | Caută patterns și gotchas din sesiuni anterioare | +| `/ab:status` | Afișează status curent (active features, worktrees, memory stats) | +| `/ab:help` | Ajutor detaliat cu exemple | + +--- + +## 🤖 Agenții Specializați + +| Agent | Model | Specializare | Context Integration | +|-------|-------|--------------|---------------------| +| **spec-writer** | Sonnet | Creează specs detaliate din requirements | ✅ Citește CLAUDE.md + memory | +| **planner** | Opus | Descompune specs în tasks ordonate | ✅ Citește CLAUDE.md + memory | +| **coder** | Sonnet | Implementează tasks, respectă patterns | - | +| **qa-reviewer** | Sonnet | Review: bugs, security, pattern violations | - | +| **qa-fixer** | Sonnet | Fixing automat al issues identificate | - | + +**Context-aware agents** (spec-writer, planner) asigură că output-ul respectă: +- Development standards din CLAUDE.md +- Project boundaries (Always/Ask/Never) +- Tech stack conventions +- Learned patterns din memory + +--- + +## 📂 Structura Fișierelor + +### În Plugin Repository + +``` +auto-build/ # Repository Gitea +├── .claude-plugin/ +│ └── marketplace.json # Marketplace catalog +├── plugin/ +│ ├── .claude-plugin/ +│ │ └── plugin.json # Plugin manifest +│ ├── commands/ # 8 comenzi +│ ├── agents/ # 5 agenți +│ ├── hooks/ # Post-install hook +│ │ ├── hooks.json +│ │ └── post-install.sh ← Generează CLAUDE.md! +│ ├── rules/ +│ │ └── auto-build-patterns.md ← Copiat în .claude/rules/ +│ ├── scripts/ # Worktree management +│ ├── templates/ +│ │ ├── CLAUDE.md.template ← Template pentru CLAUDE.md +│ │ ├── spec-template.md +│ │ ├── plan-template.md +│ │ └── memory-entry-template.json +│ └── README.md +├── README.md # Acest fișier +└── LICENSE +``` + +### În Proiectul Utilizatorului (După Instalare) + +``` +user-project/ +├── CLAUDE.md ← GENERAT de post-install +│ # Auto-Build Integration +│ @./.claude/rules/auto-build-patterns.md +│ @./.claude/rules/auto-build-memory.md +│ +├── .claude/ +│ ├── rules/ +│ │ ├── auto-build-patterns.md ← Copiat din plugin +│ │ └── auto-build-memory.md ← Updated de /ab:memory-save +│ └── settings.json +│ +└── .auto-build-data/ ← Runtime data (gitignored) + ├── specs/{feature-name}/ + │ ├── spec.md + │ ├── plan.md + │ └── status.json + ├── worktrees/ + │ └── worktree-registry.json + ├── memory/ + │ ├── patterns.json ← Searchable via /ab:memory-search + │ ├── gotchas.json ← Searchable via /ab:memory-search + │ └── sessions/ + └── cache/qa-iterations/ +``` + +--- + +## 🔧 Configurare Gitea + +### Pentru Marketplace Privat + +```bash +# Configurare Git credentials (o singură dată) +git config --global credential.helper store + +# Test autentificare +git clone https://gitea.romfast.ro/test-repo +# → Introdu user/pass → salvate automat + +# Adaugă marketplace +/plugin marketplace add https://gitea.romfast.ro/your-org/auto-build.git + +# Instalează plugin /plugin install ab@roa2web-tools ``` -### 3. Inițializare în Proiect -```bash -/ab:help -# Urmează instrucțiunile pentru setup -``` +--- -## Comenzi Disponibile +## 📚 Documentație Detaliată -- `/ab:spec ` - Creează specificație feature -- `/ab:build ` - Build feature din spec -- `/ab:worktree ` - Gestionare git worktrees -- `/ab:qa-review` - QA validation loop -- `/ab:memory-save` - Salvează insights -- `/ab:memory-search ` - Caută patterns -- `/ab:status` - Status curent -- `/ab:help` - Ajutor detaliat +- **README.md** (acest fișier) - Overview și concepte cheie +- **plugin/README.md** - Documentație tehnică detaliată +- **plugin/commands/\*.md** - Documentație per comandă +- **plugin/agents/\*.md** - Documentație per agent -## Autentificare Gitea +--- -Pentru access la Gitea privat, configurează Git credentials: +## 🚀 Workflow Recomandat + +### Pentru Feature Nou ```bash -git config --global credential.helper store -git clone https://gitea.romfast.ro/test-repo # Autentifică o dată +# 1. Specificație (context-aware!) +/ab:spec "Add email notifications" + +# 2. Review spec → edit dacă necesar +# Spec-ul va respecta CLAUDE.md boundaries automat! + +# 3. Build (cu worktree dacă e complex) +/ab:build email-notifications + +# 4. QA + fixing automat +/ab:qa-review + +# 5. Test manual + +# 6. Salvează insights pentru viitor +/ab:memory-save ``` -## Documentație +### Pentru Debugging Pattern-uri -Vezi `plugin/README.md` pentru detalii despre utilizare. +```bash +# Caută pattern similar +/ab:memory-search "authentication" + +# Găsești cum ai rezolvat înainte +# Aplici același pattern +``` + +### Pentru Team Onboarding + +```bash +# 1. Instalează plugin +/plugin install ab@roa2web-tools + +# 2. Citește CLAUDE.md generat +# → Înțelegi project boundaries/standards + +# 3. Citește .claude/rules/auto-build-memory.md +# → Înțelegi patterns deja folosite + +# 4. Implementează primul feature +/ab:spec "My Feature" +/ab:build my-feature + +# → Specs și plans respectă automat convențiile! +``` + +--- + +## 🎯 De Ce Auto-Build? + +### Înainte vs Acum + +| Aspect | Fără Auto-Build | Cu Auto-Build | +|--------|----------------|---------------| +| **Specificații** | Manual, incomplete | Agent generează, context-aware | +| **Planning** | Improvizat | Descompunere ordonată în tasks | +| **Patterns** | Uitate între sesiuni | Auto-loaded, persistent | +| **QA** | Manual, inconsistent | Automat, loop până la fix | +| **Worktrees** | Setup manual complex | Un command `/ab:worktree create` | +| **Context** | Repeți explicații | CLAUDE.md auto-loaded | +| **Learning** | Pierdut între sesiuni | Bidirectional memory (JSON + MD) | +| **Consistency** | Variază între developers | Agenții respectă standards | + +### Beneficii Cheie + +1. ✅ **Autonomous**: Agenții colaborează, tu supervizezi +2. ✅ **Persistent**: Învățarea rămâne între sesiuni +3. ✅ **Context-Aware**: Respectă project conventions automat +4. ✅ **Quality**: QA loop automat până la rezolvare +5. ✅ **Isolated**: Worktrees pentru features complexe +6. ✅ **Portable**: Instalare cu un command, updates ușoare + +--- + +## 🛠️ Development & Contribuții + +### Structure Plugin + +- **Commands**: `.md` files în `plugin/commands/` +- **Agents**: `.md` files în `plugin/agents/` +- **Hooks**: `hooks.json` + `post-install.sh` +- **Templates**: În `plugin/templates/` + +### Testing Local + +```bash +# Clone repo +git clone https://gitea.romfast.ro/your-org/auto-build.git +cd auto-build + +# Test local install +/plugin marketplace add file:///path/to/auto-build/.claude-plugin/marketplace.json +/plugin install ab@roa2web-tools +``` + +### Updates + +```bash +# În plugin repo +git pull origin main + +# În projects +/plugin update ab@roa2web-tools +``` + +--- + +## 📜 License + +MIT License - Copyright (c) 2025 ROA2WEB Team + +Folosește liber în orice proiect, comercial sau open-source. + +--- + +## 🤝 Support + +- **Issues**: https://gitea.romfast.ro/your-org/auto-build/issues +- **Documentație**: Vezi `plugin/README.md` +- **Examples**: Vezi `plugin/commands/*.md` pentru exemple detaliate + +--- + +**Auto-Build**: De la idee la cod production-ready, învățând cu fiecare feature. 🚀