auto-build/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Auto-Build is a Claude Code plugin that provides spec-driven build orchestration with autonomous agents. It enables structured feature development through 5 specialized agents, git worktree isolation, and persistent cross-session memory.

Repository Structure

This is a plugin repository with two levels:

• Root level: Marketplace configuration (.claude-plugin/marketplace.json)
• plugin/ directory: The actual plugin that gets installed

auto-build-plugin/
├── .claude-plugin/marketplace.json   # Marketplace catalog
├── plugin/                           # Plugin source (copied on install)
│   ├── .claude-plugin/plugin.json    # Plugin manifest (prefix: "ab")
│   ├── commands/                     # 8 slash commands (/ab:*)
│   ├── agents/                       # 5 specialized agents
│   ├── hooks/hooks.json              # Lifecycle hooks config
│   ├── hooks/post-install.sh         # Runs after plugin install
│   ├── scripts/                      # Bash scripts for worktree ops
│   ├── rules/                        # Auto-build patterns (copied to .claude/rules/)
│   └── templates/                    # Templates for CLAUDE.md, specs, plans
└── README.md                         # User-facing documentation

Key Architecture Concepts

Plugin Installation Flow

1. User runs /plugin install ab@roa2web-tools
2. Plugin is copied to Claude Code cache at ${CLAUDE_PLUGIN_ROOT}
3. post-install.sh hook executes and creates:
   • .auto-build-data/ directory structure
   • .claude/rules/auto-build-patterns.md
   • .claude/rules/auto-build-memory.md
   • CLAUDE.md (if missing)

Script Path Resolution

Scripts in plugin/scripts/ are called via ${CLAUDE_PLUGIN_ROOT}/scripts/ but operate on the current working directory (user's project). Scripts must use $(pwd) for project root, not relative paths from script location.

Memory System (Bidirectional)

• JSON files (.auto-build-data/memory/*.json): Searchable via /ab:memory-search
• Markdown (.claude/rules/auto-build-memory.md): Auto-loaded by Claude Code

Agent Context Awareness

spec-writer and planner agents read CLAUDE.md and auto-build-memory.md to respect project conventions.

Commands Reference

Command	Implementation
/ab:spec <name>	commands/spec.md → launches agents/spec-writer.md
/ab:build <name>	commands/build.md → launches agents/planner.md then agents/coder.md
/ab:qa-review	commands/qa-review.md → loops agents/qa-reviewer.md + agents/qa-fixer.md
/ab:worktree <action>	commands/worktree.md → calls scripts/worktree-*.sh
/ab:memory-save	commands/memory-save.md → saves to JSON + syncs to markdown
/ab:memory-search	commands/memory-search.md → searches JSON files
/ab:status	commands/status.md
/ab:help	commands/help.md

Development Guidelines

Modifying Scripts

When editing plugin/scripts/*.sh:

• Use PROJECT_ROOT="$(pwd)" - never calculate from BASH_SOURCE
• Scripts execute from plugin cache but operate on user's project
• Reference plugin files via relative paths from script location

Adding Commands

Create .md file in plugin/commands/ with frontmatter:

---
description: Short description
argument-hint: <required> [optional]
---

Adding Agents

Create .md file in plugin/agents/ with frontmatter:

---
name: agent-name
description: What it does
model: sonnet|opus|haiku
color: blue|green|red
---

Version Updates

IMPORTANT: When making any changes to the plugin, bump the version in BOTH files so users can update:

• .claude-plugin/marketplace.json → plugins[0].version
• plugin/.claude-plugin/plugin.json → version

Also update CHANGELOG.md with the changes.