auto-build/plugin/rules/auto-build-patterns.md

paths

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