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

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

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

/plugin update ab@roa2web-tools

All projects using the plugin will automatically get updates.

---

License

MIT - Use freely in any project.