# Auto-Build Plugin for Claude Code

**Intelligent, spec-driven build orchestration with autonomous agents and persistent learning**

## 🎯 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

```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/ structure (specs, memory - git-tracked)
#   - .auto-build-data/ structure (worktrees, cache - local only)

# 4. Verifică instalarea
/ab:help
```

### 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, git-tracked - shared with team)
```json
// .auto-build/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/                    ← COMMITTED TO GIT - shared with team
│   ├── specs/{feature-name}/
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── status.json
│   └── memory/
│       ├── patterns.json           ← Searchable via /ab:memory-search
│       ├── gotchas.json            ← Searchable via /ab:memory-search
│       └── sessions/
│
└── .auto-build-data/               ← GITIGNORED - local only
    ├── worktrees/
    │   └── worktree-registry.json
    └── cache/qa-iterations/
```

**Beneficii noi (v1.0.6)**:
- 🤝 **Colaborare**: Alt developer poate continua planul tău
- 🧠 **Învățare partajată**: Patterns și gotchas disponibile pentru toată echipa
- 🌍 **Cross-platform**: Funcționează fără symlinks pe Windows/Linux/Mac
- 📜 **Versionare**: Istoricul specs/plans/memory vizibil în git

---

## 🔧 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
```

---

## 📚 Documentație 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

---

## 🚀 Workflow Recomandat

### Pentru Feature Nou

```bash
# 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
```

### Pentru Debugging Pattern-uri

```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. 🚀