# 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:
```yaml
---
description: Short description
argument-hint: <required> [optional]
---
```

### Adding Agents
Create `.md` file in `plugin/agents/` with frontmatter:
```yaml
---
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.