adaptationio/auto-claude-build

Auto-Claude Build System

Deep dive into the autonomous build pipeline and agent orchestration.

Build Architecture

Agent Pipeline

Spec → Planner Agent → Coder Agent → QA Reviewer → QA Fixer → Complete
         │                 │              │            │
         ▼                 ▼              ▼            ▼
    impl_plan.json    Code Changes    QA Report    Fixed Code

Agent Roles

| Agent | Purpose | Model | Thinking Tokens | |-------|---------|-------|-----------------| | Planner | Creates subtask-based implementation plan | Claude | 5000 | | Coder | Implements subtasks, can spawn subagents | Claude | None | | QA Reviewer | Validates acceptance criteria | Claude | 10000 | | QA Fixer | Fixes QA-reported issues | Claude | None |

Running Builds

Basic Build

cd apps/backend
source .venv/bin/activate

# Run build for spec
python run.py --spec 001

# With iteration limit (for testing)
python run.py --spec 001 --max-iterations 5

Build Options

| Option | Description | |--------|-------------| | --spec SPEC | Spec to build (number or full name) | | --max-iterations N | Limit build iterations | | --skip-qa | Skip automatic QA validation | | --qa | Run QA validation only |

Build Flow

1. Initialization

   • Creates git worktree for isolation
   • Loads spec and implementation plan
   • Sets up security sandbox

2. Planning Phase

   • Planner agent analyzes spec
   • Creates subtask breakdown
   • Assigns dependencies

3. Implementation Phase

   • Coder agent implements subtasks
   • Can spawn subagents for parallel work
   • Updates progress in real-time

4. QA Phase

   • QA Reviewer validates each acceptance criterion
   • Creates QA report
   • If issues found, QA Fixer applies fixes
   • Loop until approved (max 50 iterations)

Agent Configuration

Claude SDK Client

All agents use the Claude Agent SDK configured in core/client.py:

from core.client import create_client

client = create_client(
    project_dir=project_dir,
    spec_dir=spec_dir,
    model="claude-opus-4-5-20251101",
    agent_type="coder",  # or "planner", "qa_reviewer", "qa_fixer"
    max_thinking_tokens=None  # or 5000, 10000, 16000
)

Security Layers

1. Sandbox - OS-level bash isolation
2. Filesystem Permissions - Restricted to project directory
3. Command Allowlist - Only approved commands (see security.py)

Available Tools

| Tool | Description | Agents | |------|-------------|--------| | Read, Write, Edit | File operations | All | | Glob, Grep | File search | All | | Bash | Shell commands (allowlisted) | All | | Context7 | Documentation lookup | All | | Linear | Project management | All (if enabled) | | Graphiti | Memory system | All (if enabled) | | Electron/Puppeteer | Browser testing | QA only |

Parallel Execution

Subagent Spawning

The Coder agent can spawn subagents for parallel work:

Main Coder Agent
├── Subagent 1: Frontend work
├── Subagent 2: Backend work
└── Subagent 3: Tests

Configuration:

• Up to 12 agent terminals
• Each runs in isolated context
• Results merged automatically

Git Worktree Strategy

main (your branch)
└── auto-claude/{spec-name}  ← isolated worktree

Key principles:

• ONE branch per spec
• All work in isolated worktree
• No automatic pushes
• User controls merge timing

Monitoring Builds

Real-time Progress

# Watch build progress
tail -f .auto-claude/specs/001-feature/build-progress.txt

# Check implementation plan status
cat .auto-claude/specs/001-feature/implementation_plan.json | jq '.subtasks[] | {id, title, status}'

Interactive Controls

During build:

• Ctrl+C (once) - Pause and add instructions
• Ctrl+C (twice) - Exit immediately

File-based control:

# Pause after current session
touch .auto-claude/specs/001-feature/PAUSE

# Add instructions
echo "Focus on the login flow" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

# Resume
rm .auto-claude/specs/001-feature/PAUSE

Build Artifacts

Directory Structure

.auto-claude/specs/001-feature/
├── spec.md                    # Specification
├── implementation_plan.json   # Subtask plan with status
├── build-progress.txt         # Real-time progress log
├── qa_report.md              # QA validation results
├── QA_FIX_REQUEST.md         # Issues to fix (if rejected)
├── graphiti/                  # Memory data (if enabled)
└── worktree/                  # Git worktree info

Implementation Plan Status

{
  "subtasks": [
    {
      "id": 1,
      "title": "Create data model",
      "status": "complete",  // pending, in_progress, complete, blocked
      "started_at": "2024-01-01T10:00:00Z",
      "completed_at": "2024-01-01T10:05:00Z"
    }
  ]
}

QA Validation

QA Reviewer

Validates each acceptance criterion:

## QA Report

### Acceptance Criteria

- [x] User can log in with email → PASS
- [x] Error shown for invalid credentials → PASS
- [ ] Session persists across page refresh → FAIL: Session not being saved

### Issues Found
1. Session cookie not being set correctly in AuthProvider

QA Fixer

Automatically fixes issues:

1. Reads QA_FIX_REQUEST.md
2. Analyzes root cause
3. Implements fix
4. Triggers re-validation

QA Loop

QA Reviewer → Issues? → No → Complete
                ↓
               Yes
                ↓
           QA Fixer
                ↓
           Re-validate
                ↓
           (Max 50 loops)

Troubleshooting Builds

Build Stuck

# Check what's happening
tail -100 .auto-claude/specs/001-feature/build-progress.txt

# Check for errors
grep -i error .auto-claude/specs/001-feature/build-progress.txt

# Force restart
rm .auto-claude/specs/001-feature/PAUSE
python run.py --spec 001

Agent Recovery

If an agent gets stuck:

1. Recovery Mode

   • Coder has recovery prompt (coder_recovery.md)
   • Activated when subtask fails multiple times

2. Manual Intervention

   # Add human input
   echo "Skip the failing test for now" > .auto-claude/specs/001-feature/HUMAN_INPUT.md
   

Common Issues

| Issue | Solution | |-------|----------| | Timeout errors | Increase API_TIMEOUT_MS in .env | | Memory errors | Reduce max_thinking_tokens | | Tool failures | Check security allowlist | | Git conflicts | Run --review and resolve manually |

Advanced Configuration

Model Override

# Use different model
AUTO_BUILD_MODEL=claude-sonnet-4-5-20250929 python run.py --spec 001

Extended Thinking

Configure in agent creation:

• ultrathink: 16000 tokens (spec creation)
• high: 10000 tokens (QA review)
• medium: 5000 tokens (planning)
• None: disabled (coding)

Debug Mode

DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001

Related Skills

• auto-claude-spec: Spec creation
• auto-claude-workspace: Workspace management
• auto-claude-memory: Memory system
• auto-claude-optimization: Performance tuning