autonomous-builder

name	autonomous-builder
version	1.0.0
description	Full-stack software development agent for design, implementation, testing, and deployment. Use when the user explicitly asks for end-to-end project creation, feature development, bug fixing, or code refactoring.
user-invocable	true
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","WebFetch","WebSearch","Skill","Task","ToolSearch","mcp__ide__executeCode","mcp__ide__getDiagnostics"]

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:

{
  "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

# 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:

## 🔄 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.

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, code-review-excellence
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	debugging-strategies, error-resolver
Documentation	docs-write, writing-docs
Architecture	architecture-patterns
Bioinformatics	biopython, bioservices, gget
Drug discovery	torchdrug, rdkit, uniprot-database

Feature with Skill Planning:

{
  "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":       
  

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

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

## 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

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:

#!/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

    
    
     
    claude --skill autonomous-builder --project  --dangerously-skip-permissions

    
     

    
     5

⚠️ 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:

{
  "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
     
     
     
  

   
     
     
     
     
  

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

{
  "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:

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_operations_without_progress(state) >= self.MAX_NO_PROGRESS:
            return LoopAlert("NO_PROGRESS", )

        
         state.session_turns >= .MAX_SESSION_TURNS:
             LoopAlert(, )

           

When Loop Detected - Escalation Protocol:

## LOOP ALERT: [Type]

**Detected Pattern**: [What repeated]
**Occurrences**: [Count] times
**Time Spent**: [Duration]
**Token Estimate**: [Approximate tokens used]

**Actions Taken**:
1. Stopped current operation
2. Saved checkpoint to .builder/checkpoints/
3. Logged loop pattern to .builder/loop-log.json

**Status**: PAUSED - Awaiting user input

**Options**:
A) Skip this feature and continue with next
B) Accept partial implementation
C) Provide additional context/guidance
D) Abort and generate report

Loop State Tracking:

{
  "loop_detection": {
    "error_history": [
      {"error_hash": "abc123", "count": 2, "first_seen": "...", "last_seen": "..."}
    ],
    "file_edit_history": [
      {"file": "src/app.py", "edit_count": 3, "last_edit": "..."}
    ],
    "command_history": [
      {"command": "npm test", "run_count": 2, "last_run": "..."
    
     
       
       
       
    
     
       
       
       
    
  

Mandatory Break Points:

After every 20 operations:
  └─ Check progress: Did any feature advance?
      ├─ YES: Continue
      └─ NO: Pause and reassess

After every 10 minutes:
  └─ Review: Are we making meaningful progress?
      ├─ YES: Continue
      └─ NO: Checkpoint and evaluate

On same error 2nd occurrence:
  └─ Warning: Same error detected, trying different approach
  └─ Log: Record pattern for analysis

On same error 3rd occurrence:
  └─ STOP: Loop detected, escalate to user
  └─ Save: Create checkpoint before pause

File Writing Strategy

For files > 500 lines, write in segments:

SEGMENT_SIZE = 200  # lines per segment

# First segment: create file
write_file(path, first_segment)

# Subsequent segments: append
edit_file(path, append=next_segment)

Technology Stack Detection

def detect_tech_stack(project_path):
    indicators = {
        'python': ['requirements.txt', 'pyproject.toml', '*.py'],
        'nodejs': ['package.json', '*.ts', '*.js'],
        'rust': ['Cargo.toml', '*.rs'],
        'go': ['go.mod', '*.go'],
    }
    # Auto-detect and return primary stack

Rules & Constraints

MUST (Non-negotiable)

• Create .builder/ directory before any work
• Update state.json after EVERY tool operation
• Log ALL errors to errors.json with resolution attempts
• Commit checkpoint after each feature completion
• Use segmented writes for files > 500 lines
• Run tests before marking feature complete

SHOULD (Strong recommendations)

• Follow existing project conventions
• Use conventional commit messages
• Create meaningful tests (not just coverage)
• Document non-obvious decisions in architecture.md
• Prefer simpler solutions over clever ones

NEVER (Explicit prohibitions)

• Delete user files without explicit permission
• Overwrite existing code without backup
• Commit secrets or credentials
• Skip error handling
• Make network calls without timeout
• Create infinite loops without escape conditions

SAFETY CRITICAL (System Protection - HIGHEST PRIORITY)

⚠️ These rules take precedence over ALL other operations. When in doubt, STOP and ASK.

Operations requiring explicit user confirmation:

Operation Type	Examples	Required Action
Files outside workspace	C:\Windows\, /etc/, /usr/bin/	STOP, warn user, get explicit approval
System configuration	Registry edits, /etc/hosts, environment variables	STOP, explain risk, get approval
Destructive operations	rm -rf, format, DROP DATABASE	STOP, show impact, get approval
Network/firewall changes	Port binding, firewall rules	STOP, explain scope, get approval
Package installation	npm install -g, pip install --system	Warn about system-wide changes

Pre-execution safety checks:

Before ANY operation, verify:

1. IS TARGET INSIDE WORKSPACE?
   ✅ Path starts with project root -> Proceed
   ⚠️ Path outside workspace -> STOP and confirm

2. IS OPERATION DESTRUCTIVE?
   ✅ Read/Write/Create in workspace -> Proceed
   ⚠️ Delete/Format/Truncate -> STOP and confirm

3. IS OPERATION SYSTEM-WIDE?
   ✅ Project-local operation -> Proceed
   ⚠️ Global install/System config -> STOP and confirm

4. COULD DATA BE LOST?
   ✅ New file creation -> Proceed
   ⚠️ Overwrite/Delete existing -> STOP and backup first

Protected paths (NEVER modify without explicit approval):

System directories:
- Windows: C:\Windows\, C:\Program Files\, C:\Program Files (x86)\
- Linux: /etc/, /usr/, /var/, /root/, /home/ (other users)
- macOS: /System/, /Library/, /Applications/

User data outside workspace:
- Desktop, Documents, Downloads (outside project)
- Any path containing "backup", "archive", "important"
- Database files not in project directory
- Configuration files: .bashrc, .zshrc, .gitconfig (global)

Safe operation protocol:

IF operation touches files outside workspace:
  1. STOP execution immediately
  2. Display warning to user:
     "⚠️ SAFETY ALERT: This operation affects files outside the workspace"
     - Target path: [full path]
     - Operation type: [read/write/delete]
     - Potential impact: [description]
  3. Ask for explicit confirmation:
     "Do you want to proceed? This action cannot be undone."
  4. If user declines -> Abort and suggest alternatives
  5. If user approves -> Log the approval and proceed cautiously

IF operation could cause data loss:
  1. Create backup before proceeding
  2. Log the operation to .builder/safety-log.json
  3. Provide rollback instructions

Data safety principles:

1. Preserve user data - Never delete/overwrite without explicit consent
2. Backup before destructive ops - Create .backup/ if needed
3. Workspace isolation - All operations confined to project directory
4. Fail-safe defaults - When uncertain, choose the safer option
5. Audit trail - Log all potentially dangerous operations

MCP Integration

Puppeteer (Web Testing)

## E2E Test Pattern
1. Launch browser: mcp__puppeteer_navigate
2. Interact: mcp__puppeteer_click, mcp__puppeteer_type
3. Verify: mcp__puppeteer_evaluate, mcp__puppeteer_screenshot
4. Cleanup: mcp__puppeteer_close

IDE Tools (Code Execution)

## Code Execution Pattern
1. Write code to file
2. Execute: mcp__ide__executeCode
3. Check diagnostics: mcp__ide__getDiagnostics
4. Fix errors and retry

Workflow Reporting

Overview

Autonomous-builder now generates comprehensive workflow reports that document the entire development process, including user prompts, decisions, errors, and solutions.

Features:

• Automatic workflow logging during feature implementation
• Unified report template compatible with commit-with-reflection
• Detailed recording of user prompts and AI decisions
• Integration with knowledge-steward for experience extraction
• Pure Chinese reports for better readability

Configuration

Project-level configuration (.claude-workflows.yaml):

version: "1.0"
enabled: true

reporting:
  language: "zh-CN"
  detail_level: "detailed"
  output_dir: "docs/workflows"

skills:
  autonomous-builder:
    workflow_reporting: true

Builder-level configuration (.builder/config.yaml):

workflow_reporting:
  enabled: true
  use_unified_template: true
  language: "zh-CN"
  detail_level: "detailed"
  record_all_tools: true
  record_decisions: true

Workflow Log Structure

During feature implementation, autonomous-builder maintains a detailed log in .builder/workflow-log.json:

{
  "session_id": "session-2026-02-15-001",
  "feature_id": "feat-003",
  "start_time": "2026-02-15T14:00:00Z",
  "end_time": "2026-02-15T14:45:00Z",
  "user_prompts": [
    {
      "timestamp": "2026-02-15T14:00:00Z",
      "prompt": "实现用户认证功能",
      "context": "用户希望添加JWT token验证"
    }
  ],
  "workflow_steps": [
    {
      "step": 1,
      "action": "分析需求",
      "tool": "Read",
      "files": ["server/auth.ts"],
       
    
  
   
    
       
         
       
       
    
  
   
    
       
       
       
       
    
  

Report Generation (Step 8)

After completing feature implementation and testing, autonomous-builder generates a workflow report:

1. Read workflow log: Load .builder/workflow-log.json
2. Load template: Use unified template from docs/workflows/templates/unified-template.md
3. Fill template: Populate all 12 sections with session data
4. Save report: Write to docs/workflows/YYYY-MM/DD_workflow_[category]_[desc].md
5. Update index: Regenerate docs/workflows/INDEX.md

Report Structure

The generated report includes 12 sections:

1. 概述 - Summary of the work
2. 用户需求与提示词 - User requirements and key prompts
3. 工作流记录 - Detailed workflow steps, decisions, and tools used
4. 修改内容 - Files modified and main changes
5. 遇到的错误 - Errors encountered with details
6. 根本原因分析 - Root cause analysis
7. 调试过程 - Debugging steps and iterations
8. 经验总结 - Key insights and prevention strategies
9. 知识提炼 - Reusable patterns and anti-patterns
10. 测试与验证 - Test cases and verification steps
11. 参考资料 - Related documentation and resources
12. 指标 - Metrics (errors, iterations, success rate, etc.)

Updated Commit Message Format

Commits now reference the workflow report:

feat: 实现用户认证功能

添加了JWT token验证和用户登录API端点。

工作流步骤: 8
决策点: 3
遇到错误: 2
调试迭代: 4

详见工作流报告: docs/workflows/2026-02/15_workflow_feature_user-auth.md

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Integration with knowledge-steward

Workflow reports can be analyzed by knowledge-steward to:

• Extract effective prompts and interaction patterns
• Identify reusable architectural patterns
• Build a knowledge base of common errors and solutions
• Generate experience summaries and best practices

See references/workflow-recording.md for detailed implementation guide.

GitHub Integration

Overview

Autonomous-builder integrates with GitHub for remote repository management, issue tracking, and release automation.

Features:

• Automatic push after each feature completion
• GitHub Issues tracking for features
• Release tags at milestones (25%, 50%, 75%, 100%)
• Version rollback support via GitHub history

Prerequisites

GitHub CLI (gh):

# Windows
winget install GitHub.cli

# macOS
brew install gh

# Linux
sudo apt install gh

Authentication:

gh auth login
gh auth status  # Verify

Workflow Integration

Initializer Agent (Session 1):

1. Prompt for GitHub repository URL (optional)
2. Verify gh auth status
3. Set up remote: git remote add origin <url>
4. Create README.md and PLANNING.md
5. Initial commit and push to GitHub
6. Create GitHub issues for all features

Builder Agent (Sessions 2+):

1. Implement feature
2. Commit with issue reference: Closes #N
3. Push to GitHub: git push origin main
4. Update GitHub issue (auto-closed via commit)
5. Check milestone and create release tag if needed

Commit Message Format

feat: 实现用户认证功能

添加了JWT token验证和用户登录API端点。

工作流步骤: 8
决策点: 3
遇到错误: 2
调试迭代: 4

详见工作流报告: docs/workflows/2026-02/15_workflow_feature_user-auth.md

Closes #123

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Release Tags

Automatic tags created at milestones:

• 25% completion: v0.1.0 (Foundation)
• 50% completion: v0.2.0 (Core Features)
• 75% completion: v0.3.0 (Advanced Features)
• 100% completion: v1.0.0 (Release)

Error Handling

• Network failures: 3 retries with 5s delay, then queue for next session
• Auth failures: Disable GitHub integration, continue with local commits
• Push conflicts: Auto-pull with rebase and retry

Disabling GitHub

Leave repository URL empty during initialization, or set state.json → github.enabled = false.

Rollback

# Rollback to previous feature
git log --oneline
git reset --hard <commit_hash>
git push --force origin main
gh issue reopen <issue_number>

# Rollback to release tag
git checkout v0.1.0
git checkout -b rollback-to-v0.1.0

See: references/github-integration.md for comprehensive documentation.

Examples

Example 1: New Project Creation

Input: "Build a REST API for task management with Python FastAPI"

Steps:

1. Initialize .builder/ with state.json
2. Analyze requirements -> Generate features.json:

   {
     "features": [
       {"id": "feat-001", "name": "Project Setup", "status": "pending"},
       {"id": "feat-002", "name": "Database Models", "status": "pending"},
       {"id": "feat-003", "name": "CRUD Endpoints", "status": "pending"},
       {"id": "feat-004", "name": "Authentication", "status" 
            
     
   
   

Example 2: Resume Interrupted Project

Input: User starts new session, .builder/state.json exists

Steps:

1. Read state.json -> Get current phase and feature
2. Read features.json -> Get feature status
3. Resume from last checkpoint
4. Continue implementation

Example 3: Bug Fix Request

Input: "Fix the authentication bug in my FastAPI app"

Steps:

1. Detect existing project structure
2. Read relevant code files
3. Identify bug using error-resolver patterns
4. Apply fix with 3-strike protocol
5. Run tests to verify fix
6. Update state and commit

References

Official Architecture Patterns (Anthropic claude-quickstarts)

• references/two-agent-architecture.md: CRITICAL - Two-Agent pattern for long-running tasks, fresh context per session
• references/think-tool.md: CRITICAL - Think Tool for complex reasoning before action
• references/multi-layer-security.md: CRITICAL - Defense in depth security architecture

Core Capabilities

• references/safety-protocols.md: CRITICAL - System protection and safe operation protocols
• references/loop-prevention.md: CRITICAL - Anti-infinite-loop detection and token management
• references/session-continuity.md: CRITICAL - Auto-resume and continuous operation across sessions
• references/skill-scheduling.md: CRITICAL - Automatic skill discovery, planning, and dispatch
• references/mcp-auto-integration.md: CRITICAL - MCP auto-discovery, installation, and human-like computer control
• references/github-integration.md: NEW - GitHub integration for remote push, issue tracking, and release automation

Implementation Guides

• references/index.md: Navigation for all reference docs
• references/architecture-patterns.md: Clean Architecture, Hexagonal, DDD
• references/multi-language.md: Language-specific patterns (Python, Node.js, Go, Rust)
• references/error-recovery.md: Detailed error handling strategies
• references/mcp-integration.md: MCP tool usage guide
• references/testing-patterns.md: Unit, integration, E2E testing

Plugin 智能发现与自动使用 (ToolSearch Auto-Discovery)

核心原则

autonomous-builder 在执行任务时，必须主动使用 ToolSearch 动态发现并调用可用的 MCP 插件工具。这是对现有 MCP Auto-Integration 的升级，从静态配置变为运行时动态发现。

会话启动时自动发现

ON SESSION START (Step 0 - 在 Step 1 之前执行):

1. 使用 ToolSearch 探测所有可用插件:
   - ToolSearch("+playwright") → 浏览器自动化工具
   - ToolSearch("+github") → GitHub 操作工具
   - ToolSearch("+serena") → 代码语义分析工具
   - ToolSearch("context7") → 文档查询工具
   - ToolSearch("getDiagnostics") → IDE 诊断工具
   - ToolSearch("executeCode") → 代码执行工具

2. 构建能力矩阵并存入 .builder/state.json:
   {
     "discovered_plugins": {
       "playwright": true/false,
       "github_mcp": true/false,
       "serena": true/false,
       "context7": true/false,
       "ide_diagnostics": true/false,
       "ide_execute": true/false
     },
     "last_discovery": "ISO-8601-timestamp"
   }

3. 根据发现的插件调整工作流策略

各步骤插件智能调用

Builder Step	ToolSearch 查询	用途
Step 1: Get Context	ToolSearch("+serena get_symbols_overview")	语义级代码结构分析，比 ls/grep 更精确
Step 2: Start Server	ToolSearch("+playwright navigate")	用 Playwright 代替 Puppeteer 验证服务
Step 3: Regression Check	ToolSearch("getDiagnostics")	IDE 诊断检查类型错误和 lint 问题
Step 4: Select Feature	ToolSearch("context7")	查询相关库文档辅助实现决策
Step 5: Implement	ToolSearch("+serena find_symbol")	精确定位需要修改的代码符号
Step 5: Implement	ToolSearch("+serena replace_symbol_body")	语义级代码编辑
Step 6: Browser Test	ToolSearch("+playwright snapshot")	获取页面快照进行 UI 验证
Step 6: Browser Test	ToolSearch("+playwright click")	模拟用户交互
Step 7: Update Status	ToolSearch("+github update_issue")	更新 GitHub Issue 状态
Step 8: Report	ToolSearch("+github create_or_update_file")	直接推送报告到 GitHub
Step 9: Git Push	ToolSearch("+github push_files")	通过 MCP 推送代码

实现阶段的智能插件选择

DURING FEATURE IMPLEMENTATION:

1. 代码分析阶段:
   IF serena 可用:
     → ToolSearch("+serena find_symbol") 定位目标符号
     → ToolSearch("+serena find_referencing_symbols") 分析影响范围
     → ToolSearch("+serena get_symbols_overview") 理解文件结构
   ELSE:
     → 回退到 Grep + Read 方式

2. 代码编辑阶段:
   IF serena 可用:
     → ToolSearch("+serena replace_symbol_body") 精确替换符号
     → ToolSearch("+serena insert_after_symbol") 插入新代码
   ELSE:
     → 回退到 Edit 工具

3. 测试阶段:
   IF playwright 可用:
     → ToolSearch("+playwright navigate") 打开应用
     → ToolSearch("+playwright snapshot") 获取页面状态
     → ToolSearch("+playwright click") 模拟交互
     → ToolSearch("+playwright browser_evaluate") 执行 JS 验证
   ELSE IF puppeteer 可用:
     → 使用 puppeteer MCP 工具
   ELSE:
     → 回退到 Bash 执行测试命令

4. 文档查询阶段:
   IF context7 可用:
     → ToolSearch("context7") 查询库文档
     → 获取最新 API 用法和最佳实践
   ELSE:
     → 使用 WebSearch/WebFetch

5. 代码质量检查:
   IF ide_diagnostics 可用:
     → ToolSearch("getDiagnostics") 获取诊断
     → 在提交前修复所有错误和警告
   ELSE:
     → 使用 Bash 运行 linter/type-checker

与现有 MCP Auto-Integration 的关系

旧方式 (静态):
  ON SESSION START → 运行 /mcp → 解析工具列表 → 硬编码工具名

新方式 (动态 ToolSearch):
  ON NEED → ToolSearch(关键词) → 发现工具 → 立即使用

优势:
  - 无需预先知道工具名称
  - 自动适应不同环境的插件配置
  - 按需加载，减少上下文占用
  - 关键词搜索比精确名称更灵活

注意事项

• ToolSearch 返回的工具立即可用，无需再次 select
• 关键词搜索已加载工具后，不要重复用 select: 加载
• 优先使用 MCP 工具而非 Bash 命令
• 如果 ToolSearch 未找到相关工具，回退到原有方式
• 将插件发现结果缓存到 state.json，避免重复探测
• 每个新会话重新探测一次（插件配置可能变化）

Maintenance

• Sources: Anthropic agent patterns, claude-skills best practices
• Last updated: 2026-02-16
• Version: 2.0 (添加 ToolSearch 插件智能发现)
• Known limits: Cannot handle hardware-dependent code, GPU computing without setup

Quality Gate

Before marking project complete:

1. All features in features.json have status "complete"
2. All tests pass (check features.json test counts)
3. No uncommitted changes
4. Documentation generated
5. State archived to .builder/archive/