autonomous-builder

# Autonomous Builder A fully autonomous software development agent that handles the complete software lifecycle: requirements analysis, architecture design, implementation, testing, debugging, and deployment. ## Architecture Pattern: Two-Agent Model **Based on Anthropic's official claude-quickstarts architecture** ``` ┌─────────────────────────────────────────────────────────────────┐ │ TWO-AGENT ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ SESSION 1: INITIALIZER AGENT │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ • Read requirements / spec │ │ │ │ • Create project structure │ │ │ │ • Generate feature_list.json (200+ tests) │ │ │ │ • Initialize Git repository │ │ │ │ • ✨ Prompt for GitHub URL (optional) │ │ │ │ • ✨ Create README.md & PLANNING.md │ │ │ │ • Commit initial state │ │ │ │ • ✨ Push to GitHub & create issues │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ feature_list.json │ │ (Single Source of Truth) │ │ │ │ │ SESSIONS 2+: BUILDER AGENT (fresh context each session) │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ Step 1: Get Context (pwd, ls, git log, progress) │ │ │ │ Step 2: Start/verify server │ │ │ │ Step 3: Verify previous tests (regression check) │ │ │ │ Step 4: Select next "passes": false feature │ │ │ │ Step 5: Implement feature │ │ │ │ Step 6: Browser automation test │ │ │ │ Step 7: Update feature_list.json │ │ │ │ Step 8: Generate workflow report │ │ │ │ Step 9: Git commit + GitHub push │ │ │ │ Step 10: Update progress notes │ │ │ │ Step 11: Clean exit (auto-continue in 3s) │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **Key Design Principles (Official Pattern):** 1. **Fresh Context Per Session** - Each session uses brand new context window 2. **File-Based State Persistence** - Progress via feature_list.json, not context 3. **Git Commit as State Anchor** - Atomic progress units with easy rollback 4. **Browser Automation Testing** - Act like human user, verify via UI 5. **Auto-Continue with Delay** - 3 second delay between sessions ## Core Philosophy **The Autonomous Development Loop:** ``` PLAN -> BUILD -> TEST -> DEBUG -> DEPLOY -> (REPEAT) | | +------------------------------------+ ``` **Key Principles:** 1. **Self-Sufficient**: No user intervention required during execution 2. **State-Persistent**: Recovers from interruptions via `.builder/` state files 3. **Multi-Language**: Auto-detects and adapts to project technology stack 4. **Incremental**: Completes one feature at a time, commits progress 5. **Error-Resilient**: 3-strike protocol with automatic recovery strategies ## When to Use This Skill Use this skill when the user explicitly wants this agent to own an end-to-end build or major refactor, such as: - Starting a new project from a full specification - Continuing a previously initialized `.builder/` project - Driving a broad feature build across multiple implementation steps - Performing an explicit refactor or modernization effort across the codebase Use stage assistants or other routed specialists for narrow bug fixes, one-off debugging, or scoped edits that do not need full lifecycle ownership. ## Not For / Boundaries - **Security-critical systems** without human review - **Production deployments** without user confirmation - **Legal/compliance-sensitive code** without audit - **Data migration** without backup verification - **Infrastructure changes** without explicit approval - **System-level operations** outside workspace (see SAFETY CRITICAL below) **Required inputs (ask if missing):** 1. Project requirements or specification 2. Target platform/environment (web, CLI, mobile, etc.) 3. Preferred language/framework (or auto-detect) **Safety First:** All operations that could affect system stability, data integrity, or files outside the workspace require explicit user approval. See **SAFETY CRITICAL** section below for details. ## Quick Reference ### Session Continuity (Auto-Resume) **⚠️ Critical for Unattended Long-Running Operation** ``` AUTO-RESUME PROTOCOL: ┌─────────────────────────────────────────────────────────────────┐ │ Session Start │ │ │ │ │ ▼ │ │ Check .builder/state.json exists? │ │ │ │ │ ├─ NO → Initialize new project │ │ │ │ │ └─ YES → Resume from saved state: │ │ 1. Read current_phase │ │ 2. Read current_feature │ │ 3. Read pending_features[] │ │ 4. Continue from last checkpoint │ │ │ │ After each feature completion: │ │ │ │ │ ▼ │ │ More pending features? │ │ │ │ │ ├─ YES → Auto-start next feature (NO user input needed) │ │ │ │ │ └─ NO → All complete! Generate report │ └─────────────────────────────────────────────────────────────────┘ ``` **Auto-Continue Rules:** | Condition | Action | User Input Required | |-----------|--------|---------------------| | Feature completed, more pending | Auto-start next | **NO** | | Error recovered successfully | Continue current | **NO** | | 3-strike error failed | Skip and continue | **NO** (unless critical) | | Loop detected & resolved | Resume from checkpoint | **NO** | | All features complete | Generate final report | **NO** | **State Persistence After Each Operation:** ```json { "auto_continue": true, "resume_token": "feat-003-phase-implement", "next_action": "Continue implementing feat-003", "features_remaining": 3, "estimated_completion": "2026-02-14T18:00:00Z" } ``` ### Automatic Task Queue ```python # After completing a feature, automatically proceed: def on_feature_complete(feature_id: str, state: ProjectState): """Called when a feature is marked complete.""" # 1. Save checkpoint save_checkpoint(state, feature_id) # 2. Update feature status state.features[feature_id].status = "completed" state.features[feature_id].completed_at = datetime.now() # 3. Check for pending features pending = [f for f in state.features if f.status == "pending"] if pending: # 4. Auto-select next feature (NO user input) next_feature = select_next_feature(pending, state) state.current_feature = next_feature.id state.current_phase = "implement" # 5. Save state immediately save_state(state) # 6. LOG and CONTINUE (not ask user) log_progress(f"Auto-continuing to {next_feature.name}") return ContinueAction(feature=next_feature) else: # All complete! return CompleteAction(report=generate_final_report(state)) ``` **Resume Message on Session Start:** ```markdown ## 🔄 Session Resume Detected **Previous Session**: Session #5 **Last Activity**: 2 hours ago **Current Feature**: feat-003 (User Authentication) **Phase**: implement (60% complete) **Pending Features**: 3 remaining - feat-004: API Rate Limiting - feat-005: Email Notifications - feat-006: Final Documentation **Auto-Continuing**: Resuming feat-003 implementation... [Proceeding without user input - type "pause" to stop] ``` ### Directory Structure ``` .builder/ ├── state.json # Current project state ├── features.json # Feature list with status ├── architecture.md # Design decisions ├── progress.md # Session log ├── errors.json # Error history and resolutions ├── checkpoints/ # Recovery checkpoints ├── auto-continue.{sh,bat,ps1} # Auto-restart script (auto-generated) └── supervisor.json # Self-supervision config ``` ### Skill Recommendations & Router Handoff **⚠️ Skill discovery is advisory. The host router remains the only main-route authority.** ```markdown ON PROJECT INITIALIZATION: 1. Check for Claude_Skills_中文指南.md in workspace root 2. If found: - Read and parse skill catalog - Store available skills in state.json 3. For each feature: - Analyze feature requirements - Match against skill catalog - Add recommended_skills to feature definition as router-handoff suggestions DURING IMPLEMENTATION: 1. Before each implementation step: - Check step's invoke_skill field - Or analyze step for skill match 2. Request router-approved handoff: - Propose the matched skill to the host router or current route authority - Use the Skill tool only after that router-authorized handoff or an explicit user request - Continue with the returned guidance once the handoff is granted 3. Log router-approved skill usage to state.json ``` **Task-to-Skill Mapping (Recommended):** | Task Type | Recommended Skills | |-----------|--------------------| | Code review | `code-reviewer` | | Data analysis | `exploratory-data-analysis`, `statistical-analysis` | | Visualization | `data-artist`, `matplotlib`, `plotly` | | ML training | `senior-ml-engineer`, `pytorch-lightning` | | ML evaluation | `evaluating-machine-learning-models`, `shap` | | Scientific writing | `scientific-writing`, `scientific-schematics` | | Debugging | `systematic-debugging` | | Documentation | `docs-write`, `writing-docs` | | Architecture | `architecture-patterns` | | Bioinformatics | `biopython`, `bio-database-evidence` | | Drug discovery | `torchdrug`, `rdkit`, `uniprot-database` | **Feature with Skill Planning:** ```json { "id": "feat-001", "name": "Data Analysis Module", "recommended_skills": [ {"skill": "exploratory-data-analysis", "phase": "implementation"}, {"skill": "data-artist", "phase": "implementation"} ], "skill_dispatch_schedule": [ {"step": 1, "action": "Explore data", "invoke_skill": "exploratory-data-analysis", "router_handoff_required": true}, {"step": 2, "action": "Create charts", "invoke_skill": "data-artist", "router_handoff_required": true} ] } ``` **Setup**: Place `Claude_Skills_中文指南.md` in workspace root. Skills will be discovered and stored as recommendations, then handed off through the host router before invocation. ### MCP Auto-Integration & Human-like Computer Control **⚠️ Enables browser automation, desktop control, and seamless tool invocation** ```markdown ON SESSION START: 1. DISCOVER MCP servers - Run /mcp to list configured servers - Parse available tools from each server - Build capability map 2. CHECK critical capabilities: - browser_automation (puppeteer) - code_execution (ide) - desktop_control (desktop) - optional 3. AUTO-INSTALL missing servers if needed: - For web projects: puppeteer - For desktop apps: desktop - For database work: sqlite/postgres 4. UPDATE state.json → mcp_integration ``` **MCP Capability Matrix:** | Capability | MCP Server | What It Enables | |------------|------------|-----------------| | Browser automation | puppeteer | Navigate, click, type, screenshot | | Desktop control | desktop | Mouse, keyboard, screen capture | | Code execution | ide | Run Python, get diagnostics | | Database | sqlite/postgres | Query, insert, manage data | | Web search | brave-search | Research, documentation lookup | | HTTP requests | fetch | API testing, web fetching | **Auto-Tool Selection:** ``` Task Pattern → MCP Tool ───────────────────────────────────────────── "open website/url" → mcp__puppeteer_navigate "click button/element" → mcp__puppeteer_click "fill form/type text" → mcp__puppeteer_type "take screenshot" → mcp__puppeteer_screenshot "run JavaScript" → mcp__puppeteer_evaluate "control mouse" → mcp__desktop_mouse_move "press key/hotkey" → mcp__desktop_hotkey "execute Python" → mcp__ide__executeCode ``` **Example: Automated Web Testing** ```markdown ## E2E Test Flow (Automatic) 1. mcp__puppeteer_navigate → "https://myapp.com" 2. mcp__puppeteer_screenshot → capture initial state 3. mcp__puppeteer_fill → "#username", "testuser" 4. mcp__puppeteer_click → "#submit" 5. mcp__puppeteer_wait → ".dashboard" 6. mcp__puppeteer_evaluate → verify page state 7. mcp__puppeteer_screenshot → capture result ``` **Custom MCP Server Creation:** When no existing MCP server fits the task, autonomous-builder can: 1. Identify requirement 2. Design custom MCP server 3. Write server code to `.builder/mcp-servers/` 4. Register with `claude mcp add` 5. Use immediately ### Auto-Restart & Self-Supervision **⚠️ Enables true unattended long-running operation** ```markdown ON PROJECT INITIALIZATION: 1. Create .builder/ directory 2. Generate auto-continue script for current platform: - Windows: auto-continue.ps1 - Linux/macOS: auto-continue.sh 3. Create supervisor.json with monitoring config 4. Script runs in background, monitors session health ``` **Auto-Generated Supervisor Script:** ```bash #!/bin/bash # .builder/auto-continue.sh - Auto-generated by autonomous-builder PROJECT_DIR="/path/to/project" BUILDER_DIR="$PROJECT_DIR/.builder" STATE_FILE="$BUILDER_DIR/state.json" SUPERVISOR_CONFIG="$BUILDER_DIR/supervisor.json" # Self-supervision loop while true; do # Check if project is complete if [ -f "$STATE_FILE" ]; then STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" | head -1 | cut -d'"' -f4) if [ "$STATUS" = "completed" ]; then echo "[$(date)] Project completed. Exiting supervisor." exit 0 fi fi # Check last activity (if no activity for 5 min, restart) LAST_ACTIVITY=$(grep -o '"last_activity"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" | cut -d'"' -f4) if [ -n "$LAST_ACTIVITY" ]; then # Parse and check timeout... # If timeout exceeded, trigger new session fi # Start/resume Claude session with permission bypass for unattended operation # WARNING: --dangerously-skip-permissions bypasses all user confirmations