feat: Circuit Breaker Pattern and UX Improvements (v2.0.0)

[itz4blitz]

🎯 Overview

This PR introduces significant reliability and user experience improvements to agentful, including a circuit breaker pattern to prevent infinite loops, simplified command structure, and real-time progress indicators.

This is a breaking change and will be released as v2.0.0.

🚀 What's New

Circuit Breaker Pattern

• Prevents infinite loops by tracking consecutive failures
• Auto-trips after 3 failures on the same task
• Adds blocking decision to decisions.json with recovery options
• Continues with other work instead of getting stuck
• 1-minute cooldown period before retry

Impact: Reduces token waste and prevents stuck agents from burning resources.

Simplified Command Structure

• Primary Commands: 3 essentials (start, status, decide)
• When-Needed Commands: Contextual (validate, product, generate)
• Advanced Commands: Power-user features (analyze, init, agents)
• Clear "When to Use" guidance for each command

Impact: Reduces choice paralysis and makes agentful more approachable.

Progress Indicators

• Phase-based progress: Planning → Implementation → Testing → Complete
• Incremental updates every 2 minutes max
• Specific file creation notifications
• Visual progress bars with checkmarks
• Estimated remaining work when appropriate

Impact: Users get real-time visibility into agent work, reducing "is it stuck?" anxiety.

Enhanced Documentation

• Updated CLAUDE.md with new command structure
• Added circuit breaker troubleshooting
• Added progress indicator expectations
• Clearer command organization

📋 Breaking Changes

State File Structure

• state.json now includes circuit_breaker object

  {
    "circuit_breaker": {
      "consecutive_failures": 0,
      "last_failure_task": null,
      "last_failure_time": null,
      "state": "closed"
    }
  }

Migration Notes

• Existing state.json files will continue to work (circuit breaker defaults to closed state)
• No manual migration needed
• New projects will get circuit breaker automatically

🔧 Technical Details

Circuit Breaker Logic

// Before task execution
if (!shouldAttemptTask(currentTask, state)) {
  console.log("⚠️ Circuit breaker is open. Skipping task");
  pickNextTask();
  return;
}

// After task completion
if (taskSuccessful) {
  recordSuccess(currentTask, state);
} else {
  action = recordFailure(currentTask, error, state);
  if (action === "tripped") {
    console.log("🔴 Circuit breaker tripped. Added to decisions.json");
    pickNextTask();  // Continue with other work
    return;
  }
}

Progress Indicator Pattern

▶ Backend Agent: Implementing feature

[Planning] Analyzing requirements...
  ✓ Understood task scope
  → Checking existing patterns...

[Implementation] Creating backend code...
  ✓ Created service layer
  ✓ Added API endpoints
  → Implementing database schema...

✅ Test Plan

• Circuit breaker triggers after 3 failures
• Circuit breaker adds decision to decisions.json
• Progress indicators show incremental updates
• Commands simplified in template
• Documentation updated
• Integration tests with orchestrator
• End-to-end test with real workflow

📚 Documentation

• Updated template/.claude/agents/orchestrator.md with circuit breaker pattern
• Updated template/.claude/agents/backend.md with progress indicators
• Updated template/.claude/agents/frontend.md with progress indicators
• Updated template/.claude/commands/agentful.md with simplified commands
• Updated template/CLAUDE.md with new structure and troubleshooting

🎯 Next Steps

This PR is part of the v2.0.0 release. Future PRs will add:

• MCP server implementation
• Vector database integration
• Enhanced error recovery dashboard
• Quick-start templates

📊 Version Bump

• Current: v1.4.0
• Target: v2.0.0 (major version due to breaking changes)

---

Co-authored-by: agentful agentful@itz4blitz.com