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