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

# 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

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

/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)

// .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)

# .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):

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

/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:

# 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ă):

## 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):

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

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

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

# 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

# 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

# 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

# Caută pattern similar
/ab:memory-search "authentication"

# Găsești cum ai rezolvat înainte
# Aplici același pattern

Pentru Team Onboarding

# 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

# 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

# Î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. 🚀