auto-build/plugin/README.md

# Auto-Build

**Portable, spec-driven build orchestration for Claude Code**

Auto-Build is a Claude Code plugin that provides autonomous feature implementation with git worktree isolation, persistent session memory, and CLAUDE.md integration.

---

## 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 pentru a încărca CLAUDE.md
# Post-install hook-ul va genera automat CLAUDE.md și .claude/rules/

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

### Workflow

```
/ab:spec "Feature Name"
       ↓
   spec-writer agent
       ↓
   spec.md created in .auto-build/specs/ (git-tracked!)
       ↓
/ab:build feature-name
       ↓
   planner agent → plan.md with subtasks
       ↓
   (optional) create git worktree
       ↓
   coder agent loop → implementation
       ↓
/ab:qa-review
       ↓
   qa-reviewer agent → issues found
       ↓
   qa-fixer agent → fixes applied
       ↓
/ab:memory-save
       ↓
   patterns.json, gotchas.json in .auto-build/memory/ (git-tracked!)
   + .claude/rules/auto-build-memory.md synced (auto-loaded!)
```

**New in v1.0.6**: Specs, plans, and memory are now git-tracked, enabling multi-developer collaboration!

---

## Commands

| Command | Description |
|---------|-------------|
| `/ab:help` | Show detailed help and examples |
| `/ab:status` | Show current build status |
| `/ab:spec <name>` | Create detailed feature specification |
| `/ab:build <name>` | Orchestrate feature implementation |
| `/ab:worktree <action>` | Manage git worktrees (create/list/cleanup) |
| `/ab:qa-review` | Run QA validation loop (max 50 iterations) |
| `/ab:memory-save` | Save session insights to memory + sync to .claude/rules/ |
| `/ab:memory-search <query>` | Search patterns from past sessions |

---

## Plugin Structure

```
auto-build/                         # Plugin repository
├── .claude-plugin/
│   └── marketplace.json            # Marketplace catalog
│
├── plugin/                         # Plugin root
│   ├── .claude-plugin/
│   │   └── plugin.json             # Plugin manifest (enables /ab: prefix)
│   ├── commands/                   # 8 skill commands
│   │   ├── spec.md
│   │   ├── build.md
│   │   ├── worktree.md
│   │   ├── qa-review.md
│   │   ├── memory-save.md          # ⭐ Syncs to .claude/rules/
│   │   ├── memory-search.md
│   │   ├── status.md
│   │   └── help.md
│   ├── agents/                     # 5 specialized agents
│   │   ├── spec-writer.md          # ⭐ Context-aware (reads CLAUDE.md)
│   │   ├── planner.md              # ⭐ Context-aware (reads CLAUDE.md)
│   │   ├── coder.md
│   │   ├── qa-reviewer.md
│   │   └── qa-fixer.md
│   ├── hooks/                      # ⭐ NEW - Lifecycle hooks
│   │   ├── hooks.json
│   │   └── post-install.sh         # Auto-generates CLAUDE.md
│   ├── rules/
│   │   └── auto-build-patterns.md  # Copied to .claude/rules/ on install
│   ├── scripts/                    # Worktree management
│   │   ├── worktree-create.sh
│   │   ├── worktree-list.sh
│   │   ├── worktree-cleanup.sh
│   │   └── worktree-switch.sh
│   ├── templates/
│   │   ├── CLAUDE.md.template      # ⭐ NEW - CLAUDE.md template
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── memory-entry-template.json
│   └── README.md
│
└── README.md                       # Marketplace documentation
```

### Project Structure (After Installation)

```
user-project/                       # Your project
├── CLAUDE.md                       # ⭐ Auto-generated by post-install hook
│   # Contains @import directives:
│   # @./.claude/rules/auto-build-patterns.md
│   # @./.claude/rules/auto-build-memory.md
│
├── .claude/
│   ├── rules/
│   │   ├── auto-build-patterns.md  # Copied from plugin
│   │   └── auto-build-memory.md    # Updated by /ab:memory-save
│   └── settings.json
│
├── .auto-build/                    # ⭐ COMMITTED TO GIT - shared with team
│   ├── specs/{feature-name}/
│   │   ├── spec.md                 # Feature specification
│   │   ├── plan.md                 # Implementation plan
│   │   └── status.json             # Build status
│   └── memory/
│       ├── patterns.json           # Searchable via /ab:memory-search
│       ├── gotchas.json            # Searchable via /ab:memory-search
│       └── sessions/               # Session history
│
└── .auto-build-data/               # GITIGNORED - local only
    ├── worktrees/
    │   └── worktree-registry.json  # Local worktree tracking
    └── cache/qa-iterations/        # Temporary QA cache
```

**Data Separation (v1.0.6)**:
- `.auto-build/` - Git-tracked: specs, plans, memory (shared with team)
- `.auto-build-data/` - Gitignored: worktrees, cache (local only)

---

## Agents

| Agent | Model | Purpose | Context Integration |
|-------|-------|---------|---------------------|
| **spec-writer** | sonnet | Analyzes requirements and creates detailed specifications | ✅ Reads CLAUDE.md + auto-build-memory.md |
| **planner** | opus | Breaks specs into ordered implementation tasks | ✅ Reads CLAUDE.md + auto-build-memory.md |
| **coder** | sonnet | Implements code following patterns and spec | - |
| **qa-reviewer** | sonnet | Reviews code for bugs, patterns violations, security | - |
| **qa-fixer** | sonnet | Fixes identified issues automatically | - |

---

## Memory System (Bidirectional)

Auto-Build maintains **bidirectional memory** for cross-session learning:

### Searchable (JSON)
- **patterns.json** - Reusable code patterns discovered
- **gotchas.json** - Known issues and their solutions
- **sessions/*.json** - Individual session insights

Use `/ab:memory-search <query>` to find relevant patterns.

### Auto-Loaded (Markdown)
- **.claude/rules/auto-build-memory.md** - Auto-synced from JSON files
- Automatically loaded by Claude Code at session start
- Patterns become part of project context permanently

**Workflow**:
```
/ab:memory-save
    ↓
patterns.json updated (searchable)
    ↓
.claude/rules/auto-build-memory.md synced (auto-loaded)
    ↓
Next session: Claude knows these patterns automatically!
```

---

## CLAUDE.md Integration

Auto-Build integrates with Claude Code's **CLAUDE.md auto-loading**:

1. **Post-install hook** generates CLAUDE.md from template
2. **@import directives** reference `.claude/rules/auto-build-*.md`
3. **spec-writer** and **planner** agents read CLAUDE.md for:
   - Development Standards
   - Project Boundaries (Always/Ask/Never)
   - Tech Stack conventions
   - Learned patterns from past features

**Result**: Specs and plans respect project conventions automatically.

---

## Git Worktrees

For larger features, Auto-Build can create isolated git worktrees:

```bash
/ab:worktree create feature-name   # Create isolated worktree
/ab:worktree list                  # List active worktrees
/ab:worktree cleanup               # Remove merged worktrees
```

Worktrees are created at `../ab-worktrees/{project}-{feature}/` to avoid nesting issues.

---

## Configuration

No configuration required! Auto-Build uses sensible defaults:

- QA iteration limit: 50
- Default planner model: opus
- Default coder model: sonnet
- Memory format: JSON files + Markdown (auto-loaded)
- CLAUDE.md: Auto-generated from template

---

## Portability

Auto-Build is designed to be portable:

1. **Plugin-based**: Installs via official Claude Code plugin system
2. **Self-contained**: Everything lives in plugin directory
3. **No external dependencies**: Uses only Claude Code agents and Bash scripts
4. **Clean separation**: Shared data in `.auto-build/` (git), local data in `.auto-build-data/` (gitignored)
5. **Cross-platform**: Uses @import (git-friendly), not symlinks
6. **Team sharing**: Specs, plans, and memory are git-tracked for multi-developer collaboration

---

## Updates

Update the plugin using Claude Code's plugin system:

```bash
/plugin update ab@roa2web-tools
```

All projects using the plugin will automatically get updates.

---

## License

MIT - Use freely in any project.