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

docs: Add clear problem statement and value proposition to README

Browse Source
This commit is contained in:
Marius Mutu
2025-12-21 23:50:08 +02:00
parent 7e4912add2
commit e4abf090ed
1 changed files with 670 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

695
README.md
View File

@@ -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 ```bash
# 1. Adaugă marketplace-ul
/plugin marketplace add https://gitea.romfast.ro/your-org/auto-build.git /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 ```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 /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 - **README.md** (acest fișier) - Overview și concepte cheie
- `/ab:build <name>` - Build feature din spec - **plugin/README.md** - Documentație tehnică detaliată
- `/ab:worktree <action>` - Gestionare git worktrees - **plugin/commands/\*.md** - Documentație per comandă
- `/ab:qa-review` - QA validation loop - **plugin/agents/\*.md** - Documentație per agent
- `/ab:memory-save` - Salvează insights
- `/ab:memory-search <query>` - Caută patterns
- `/ab:status` - Status curent
- `/ab:help` - Ajutor detaliat
## Autentificare Gitea ---
Pentru access la Gitea privat, configurează Git credentials: ## 🚀 Workflow Recomandat
### Pentru Feature Nou
```bash ```bash
git config --global credential.helper store # 1. Specificație (context-aware!)
git clone https://gitea.romfast.ro/test-repo # Autentifică o dată /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. 🚀