---
paths: .auto-build/**/*
---

# Auto-Build Patterns and Rules

These rules apply to all Auto-Build related files and workflows.

## Core Principles

### 1. Portability First
- All paths must be relative or dynamically determined
- No hardcoded project-specific values
- Shared data (specs, plans, memory) lives in `.auto-build/` (git-tracked)
- Local data (worktrees, cache) lives in `.auto-build-data/` (gitignored)

### 2. Minimal Footprint
- Never modify files outside the current task scope
- Keep changes focused and reversible
- Prefer editing existing files over creating new ones

### 3. Pattern Consistency
- Match existing codebase patterns exactly
- Use the same error handling approach throughout
- Follow naming conventions from the host project

## Command Execution Rules

### When Running /ab:spec
- Always analyze the codebase before writing spec
- Include at least 3 acceptance criteria
- Identify affected files explicitly
- Save to `.auto-build/specs/{name}/` (git-tracked, shared with team)

### When Running /ab:build
- Check for existing spec before proceeding
- Offer worktree creation for multi-file changes
- Track progress in status.json after each task
- Never skip the planning phase

### When Running /ab:qa-review
- Review all modified files from the build
- Classify issues by severity (error/warning/info)
- Stop at 50 iterations to prevent infinite loops
- Save iteration history for debugging

### When Running Memory Commands
- Deduplicate entries before saving
- Keep patterns.json under 100 entries
- Always include tags for searchability
- Update usageCount when patterns are referenced

## Agent Guidelines

### spec-writer Agent
- Focus on WHAT, not HOW
- Include out-of-scope section
- Map to existing codebase patterns
- Flag risks and open questions

### planner Agent
- Create atomic, testable tasks
- Explicit dependencies between tasks
- First task is always setup/scaffolding
- Include testing as explicit tasks

### coder Agent
- Read files before modifying
- Match existing code style
- Handle all error cases from spec
- Report changes made clearly

### qa-reviewer Agent
- Check correctness, patterns, security, performance
- Provide actionable suggestions
- Reference existing code for patterns
- Don't flag style preferences as errors

### qa-fixer Agent
- Make minimal changes only
- Don't refactor beyond the fix
- Verify fix doesn't introduce new issues
- Escalate if fix is not straightforward

## File Formats

### status.json States
```
SPEC_DRAFT → SPEC_COMPLETE → PLANNING → PLANNING_COMPLETE →
IMPLEMENTING → IMPLEMENTATION_COMPLETE → QA_REVIEW → COMPLETE
```

### Memory Files (`.auto-build/memory/` - git-tracked)
- patterns.json: Reusable code patterns (shared with team)
- gotchas.json: Problems and solutions (shared with team)
- sessions/*.json: Session history (shared with team)

### Local Data Files (`.auto-build-data/` - gitignored)
- worktrees/worktree-registry.json: Local worktree tracking
- cache/qa-iterations/*.json: Temporary QA cache

## Git Worktree Rules

- Create worktrees outside project: ../ab-worktrees/
- Branch naming: feature/ab-{feature-name}
- Registry tracking in `.auto-build-data/worktrees/worktree-registry.json`
- No symlinks needed - specs/plans/memory are in git, available in all worktrees
- Cleanup only merged branches automatically

## Error Handling

- Log errors with context
- Provide recovery instructions
- Never leave status in inconsistent state
- Offer rollback options when appropriate