How to Set Up Autonomous Loop Execution in ECC

ECC provides a built-in autonomous loop system where the loop-operator agent executes repetitive workflows until quality gates pass or stop conditions trigger, controlled via the /loop-start command.

Autonomous loop execution in ECC enables AI agents to iterate independently on development tasks, monitoring their own progress and handling failures without manual intervention. This system, implemented in the affaan-m/ECC repository, combines a user-facing command interface with a dedicated agent that enforces quality standards and manages execution flow. Setting up these loops requires understanding the two core components—the /loop-start command and the loop-operator agent—and how they interact through generated run-books.

Core Architecture

The autonomous loop system consists of two primary components working in tandem.

loop-operator agent – Located at agents/loop-operator.md, this agent serves as the execution engine. It launches loops, tracks checkpoints, detects stalls, coordinates retries, and manages rollbacks when failures occur.

/loop-start command – Defined in commands/loop-start.md, this entry point validates repository state, selects execution patterns, applies safety modes, and generates the run-books that guide the operator.

When invoked, /loop-start creates a structured plan in .claude/plans/ containing checkpoint definitions, stop conditions, and recovery actions. The loop-operator then consumes this plan to drive the actual execution cycle.

Step-by-Step Setup

1. Validate Repository State

Before initiating a loop, ensure your repository meets baseline requirements. The /loop-start command automatically checks for uncommitted changes, validates branch strategy, and confirms the test suite passes.

Run the validation and initialization:

/loop-start sequential

This command performs five critical actions:

• Verifies clean git status and running npm test
• Selects the loop pattern and appropriate model tier (e.g., sonnet for standard work, opus for intensive reviews)
• Activates required hook profiles via ECC_HOOK_PROFILE environment variables
• Writes a YAML/markdown run-book to .claude/plans/sequential-runbook.md
• Outputs specific execution commands for the next steps

2. Configure the Run-Book

The generated run-book at .claude/plans/<pattern>-runbook.md defines:

• Checkpoints – Validated milestones like "test suite passed" or "PR merged"
• Stop conditions – Targets such as coverage thresholds or maximum iteration counts
• Recovery actions – Rollback procedures and retry limits

Review this file to ensure stop conditions align with your goals before launching the loop.

3. Launch the Loop Operator

Execute the autonomous loop by passing the generated plan to the operator:

claude run-agent loop-operator --plan .claude/plans/sequential-runbook.md

According to lines 22-30 of the agents/loop-operator.md implementation, the agent follows this workflow:

1. Initialize the loop using the specified pattern and safety mode
2. Track progress at each defined checkpoint
3. Detect stalls – If two consecutive checkpoints show no progress, trigger retry logic
4. Pause and reduce scope when repeated failures occur to prevent runaway costs
5. Resume only after verification – Quality gates must pass before next iteration begins

If the operator detects a stall, it may invoke a rollback path using branch isolation before retrying, ensuring failed iterations never corrupt the main codebase.

4. Monitor Execution

Track loop health and progress using the status command:

/loop-status

This reports the current iteration number, last checkpoint result, and any pending recovery actions. For detailed implementation of status reporting, see commands/loop-status.md.

Loop Patterns and Safety Modes

ECC supports multiple execution patterns via the /loop-start command, each suited to different development workflows.

Sequential – Executes tasks in strict order, waiting for each checkpoint before proceeding. Ideal for refactoring or feature development requiring linear progression.

Continuous-PR – Automates the cycle of branching, committing, and merging pull requests. Use this for ongoing maintenance or documentation updates.

RFC-DAG – Executes tasks defined in a directed acyclic graph structure, allowing parallel paths where dependencies permit. Suitable for complex architectural changes.

Infinite – Runs until manually stopped or until a specific quality metric reaches threshold. Use with caution and definite stop conditions.

Safety Mode Configuration

Safe mode (default) – Enforces full quality gates including lint, type-check, security scans, and comprehensive test suites. The operator pauses iterations on any failure until manual verification.

Fast mode – Relaxes non-critical checks to accelerate iteration cycles. While still requiring test passage, it skips full lint runs and some security validations. Activate this mode for rapid prototyping:

/loop-start continuous-pr --mode fast

Handling Stops and Rollbacks

The loop automatically terminates when:

• An explicit stop condition in the run-book is met (e.g., target coverage achieved)
• Maximum iteration count is reached (configurable per pattern)
• Fatal errors occur that cannot be auto-recovered

On repeated failures, the loop-operator pauses execution and may perform branch isolation before retrying, preventing corrupted states from persisting in the main branch.

Summary

• Autonomous loop execution in ECC relies on the loop-operator agent and the /loop-start command working through generated run-books in .claude/plans/
• Setup requires validating repository state, selecting a pattern (sequential, continuous-pr, rfc-dag, or infinite), and choosing a safety mode (safe or fast)
• Execution workflow involves checkpoint tracking, stall detection, automatic retries, and branch-isolated rollbacks as implemented in lines 22-30 of agents/loop-operator.md
• Monitoring occurs via /loop-status, while stop conditions trigger automatically based on run-book definitions or iteration limits

Frequently Asked Questions

What is the difference between safe mode and fast mode in ECC autonomous loops?

Safe mode enforces comprehensive quality gates including full lint, type-check, and security scans before allowing each iteration to complete, while fast mode relaxes these checks to speed up iteration cycles while maintaining minimum test passage requirements. According to the commands/loop-start.md specification, safe mode is the default for production work, whereas fast mode suits rapid prototyping where immediate feedback outweighs comprehensive validation.

How does the loop-operator detect and handle failures?

The loop-operator agent, as defined in agents/loop-operator.md, implements a stall detection mechanism that triggers when two consecutive checkpoints show no progress. Upon detection, the operator either retries the current step with adjusted parameters or pauses execution to reduce scope. For critical failures, it invokes rollback paths that isolate changes to temporary branches, ensuring the main codebase remains uncorrupted before attempting recovery.

Where are loop execution plans stored in ECC?

Loop plans, or run-books, are stored as YAML/markdown files in the .claude/plans/ directory at your repository root. The /loop-start command writes these files (e.g., sequential-runbook.md) containing checkpoint definitions, stop conditions, and recovery actions. The loop-operator agent reads from this location when launched with the --plan flag to determine execution flow.

Can I run multiple autonomous loops simultaneously?

While ECC supports various loop patterns (sequential, continuous-pr, rfc-dag, infinite), each executing loop requires a dedicated loop-operator instance with its own run-book. Running multiple loops against the same working directory simultaneously is not recommended, as the stall detection and rollback mechanisms assume exclusive control over repository state. For parallel workflows, use separate branches or clones with distinct .claude/plans/ directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}