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

Initialization
- Creates git worktree for isolation
- Loads spec and implementation plan
- Sets up security sandbox
Planning Phase
- Planner agent analyzes spec
- Creates subtask breakdown
- Assigns dependencies
Implementation Phase
- Coder agent implements subtasks
- Can spawn subagents for parallel work
- Updates progress in real-time
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

Sandbox - OS-level bash isolation
Filesystem Permissions - Restricted to project directory
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:

Reads QA_FIX_REQUEST.md
Analyzes root cause
Implements fix
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:

Recovery Mode
- Coder has recovery prompt (coder_recovery.md)
- Activated when subtask fails multiple times

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

auto-claude-build