--- name: Autonomous Builder slug: autonomous-builder category: AI Engineering description: Autonomous Builder drives end-to-end software development from requirements to deployment, handling architecture, implementation, testing, and deployment. Use it for project creation, feature development, bug fixing, or refactoring when the user wants full lifecycle ownership. github: "https://github.com/foryourhealth111-pixel/Vibe-Skills/tree/main/bundled/skills/autonomous-builder" language: Python stars: 2865 forks: 227 install: "npx degit https://github.com/foryourhealth111-pixel/Vibe-Skills/tree/main/bundled/skills/autonomous-builder ~/.claude/skills/autonomous-builder" installs_to: ~/.claude/skills/autonomous-builder source_path: bundled/skills/autonomous-builder/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/foryourhealth111-pixel/Vibe-Skills" added: 2026-08-17T07:10:18.955Z last_synced: 2026-08-17T07:10:18.955Z canonical_url: "https://dirskills.com/skills/autonomous-builder" --- # Autonomous Builder Autonomous Builder drives end-to-end software development from requirements to deployment, handling architecture, implementation, testing, and deployment. Use it for project creation, feature development, bug fixing, or refactoring when the user wants full lifecycle ownership. **Install:** ```bash npx degit https://github.com/foryourhealth111-pixel/Vibe-Skills/tree/main/bundled/skills/autonomous-builder ~/.claude/skills/autonomous-builder ``` ## README # 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 echo "[$(date)] Starting Claude session..." claude --skill autonomous-builder --project "$PROJECT_DIR" --dangerously-skip-permissions # Log session end echo "[$(date)] Session ended. Checking state..." # Wait before restart (configurable) sleep 5 done ``` **⚠️ Security Warning:** `--dangerously-skip-permissions` bypasses ALL user confirmations. Use only in trusted, isolated environments. Ensure workspace isolation and safety protocols are properly configured. **Supervisor Configuration:** ```json { "supervisor_version": "1.0", "project_path": "/path/to/project", "enabled": true, "monitoring": { "check_interval_seconds": 60, "session_timeout_seconds": 300, "max_restart_attempts": 10, "restart_cooldown_seconds": 5 }, "health_checks": { "progress_stall_threshold": 600, "error_rate_threshold": 0.5, "context_usage_warning": 0.8 }, "notifications": { "on_completion": true, "on_error_spike": true, "on_stall": true, "log_file": ".builder/supervisor.log" }, "statistics": { "total_sessions": 0, "total_restarts": 0, "total_runtime_seconds": 0, "last_restart_time": null } } ``` ### Core Workflow Phases | Phase | Actions | Output | |-------|---------|--------| | INITIALIZE | Check state, parse requirements | state.json, features.json | | DESIGN | Detect tech stack, choose architecture | architecture.md | | IMPLEMENT | Write code per feature | Source files | | TEST | Run unit/integration/E2E | Test results | | DEBUG | Apply 3-strike protocol | Fixes or escalation | | DEPLOY | Build, document, archive | Final deliverables | ### State File Schema ```json { "project_name": "string", "current_phase": "init|design|implement|test|deploy", "current_feature": "feature-id", "tech_stack": { "language": "string", "framework": "string", "runtime": "string" }, "completed_features": ["feat-001"], "pending_features": ["feat-002"], "session_count": 0, "last_activity": "ISO-8601-timestamp" } ``` ### 3-Strike Error Recovery ``` STRIKE 1: Direct Fix - Analyze error type and root cause - Apply known solution pattern - Run tests to verify STRIKE 2: Alternative Approach - Try different library/algorithm - Simplify implementation - Use different design pattern STRIKE 3: Architecture Rethink - Question design assumptions - Research alternatives - Consider partial implementation AFTER 3 STRIKES: Save checkpoint, request user guidance ``` ### Loop Prevention (Anti-Infinite-Loop) **⚠️ Critical: Prevents token waste in unattended operation** ``` DETECTION RULES: ┌─────────────────────────────────────────────────────────────────┐ │ Condition │ Threshold │ Action │ ├─────────────────────────────────────────────────────────────────┤ │ Same error repeated │ 3 times │ ESCALATE immediately│ │ Same file modified │ 5 times │ STOP, review approach│ │ Same command executed │ 3 times │ Try alternative │ │ No progress in N operations │ 10 ops │ PAUSE, reassess │ │ Single session too long │ 50 turns │ Checkpoint & pause │ └─────────────────────────────────────────────────────────────────┘ ``` **Loop Detection Algorithm:** ```python class LoopDetector: MAX_SAME_ERROR = 3 # Same error appears 3 times MAX_SAME_FILE_EDIT = 5 # Same file edited 5 times MAX_SAME_COMMAND = 3 # Same command run 3 times MAX_NO_PROGRESS = 10 # No feature completed in 10 ops MAX_SESSION_TURNS = 50 # Maximum turns per session def check_loop(self, state): # Check 1: Same error repeating if self.count_same_error(state.errors) >= self.MAX_SAME_ERROR: return LoopAlert("SAME_ERROR_LOOP", "Escalate to user") # Check 2: Same file being edited repeatedly if self.count_same_file_edits(state.recent_edits) >= self.MAX_SAME_FILE_EDIT: return LoopAlert("FILE_EDIT_LOOP", "Review approach") # Check 3: Same command executing repeatedly if self.count_same_commands(state.recent_commands) >= self.MAX_SAME_COMMAND: return LoopAlert("COMMAND_LOOP", "Try alternative") # Check 4: No progress indicator if self.count_opera