docs: Add clear problem statement and value proposition to README

2025-12-21 23:50:08 +02:00
parent 7e4912add2
commit e4abf090ed
1 changed files with 670 additions and 25 deletions
--- 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 <name>` | Creează specificație detaliată (via spec-writer agent) |
+| `/ab:build <name>` | Orchestrează implementarea completă (planner + coder) |
+| `/ab:worktree <action>` | 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 <query>` | 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 <name>` - Creează specificație feature
- `/ab:build <name>` - Build feature din spec
- `/ab:worktree <action>` - Gestionare git worktrees
- `/ab:qa-review` - QA validation loop
- `/ab:memory-save` - Salvează insights
- `/ab:memory-search <query>` - 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. 🚀