Compliant Ralph Loops: From Context Rot to Context Mastery

There's a fundamental problem with AI-assisted coding that most people don't talk about: context rot.

The longer you work with an AI agent in a single session, the worse it gets. Around 100k tokens, performance starts to collapse. The model gets confused. It forgets what you told it. It contradicts itself. And if you've been "vibe coding" - just going back and forth without a clear plan - that compacted context poisons every future interaction.

Ralph loops solve this problem in an elegant way. But basic Ralph has limitations. We took the concept further and built Compliant Ralph - a hierarchical, phase-aligned, self-healing autonomous agent system with human-in-loop controls.

This is how we went from simple loops to a production-ready multi-agent system.

The Context Window Problem

Here's what actually happens when you code with AI over a long session:

The "Dumb Zone": Around 100k tokens (for Claude Opus), model performance rapidly drops. This isn't a gradual decline - it's a cliff. And once compaction happens, that summarized context carries forward, poisoning future iterations with irrelevant or contradictory information.

Most developers "solve" this by starting new sessions. But that loses all the context you've built up.

Enter Ralph Loops: Trading Tokens for Intelligence

The Ralph loop (named after Ralph Wiggum, referencing Roman Lipski's popularization of the pattern) inverts the problem:

Instead of accumulating context in one session, Ralph:

Creates a spec and plan upfront - Detailed requirements and implementation checklist
Runs each iteration with fresh context - No accumulated garbage
Updates the plan as source of truth - Not previous conversation history
Marks tasks complete via checkboxes - Simple state tracking

The key insight: Context windows are a static allocation problem. Instead of filling them with accumulated conversation, allocate context to the spec and plan every time. The model never hits the dumb zone because each iteration starts fresh.

# Simplified Ralph loop (conceptual)
while [ ! -f .complete ]; do
  claude -p "$(cat prompt.md)"
  # Prompt tells Claude to:
  # 1. Study spec.md thoroughly
  # 2. Study plan.md thoroughly
  # 3. Pick highest leverage unchecked task
  # 4. Complete task and write unit test
  # 5. Mark checkbox complete
done

The Limitations of Basic Ralph

Ralph loops are powerful, but they have constraints:

Limitation	Problem
Flat structure	Only parallel loops, no hierarchy
No coordination	Multiple loops can conflict on files
Token expensive	Every iteration re-reads the full spec
Spec size limits	Large specs cause context rot anyway
No error recovery	One bad test poisons future iterations
No human oversight	Runs until complete or fails
No scope control	Agent can go off-track without detection

For small, well-defined tasks, basic Ralph works great. But for large features spanning multiple files and requirements? You need something more.

Compliant Ralph: Hierarchical Autonomous Agent Trees

We built Compliant Ralph (also called MALS - Multi-Agent Autonomous Loop System) to address these limitations while preserving the core insight about context management.

The Architecture: Fractal Agent Trees

Every node is the same interface - a Ralph loop - but with different:

Skills (progressive disclosure of capabilities)
Spawn capabilities (what children it can create)
Worktree assignment (isolated git branches)
Duration limits (specs: minutes, epics: days)

Key Design Principles

Fractal/Recursive - Any Ralph can spawn child Ralphs; same interface at every level
Plan-Driven but Adaptive - Original epic drives work, but deviations bubble up
Phase-Aligned - Follows 12-phase SOP workflow with explicit gates
Human-in-Loop - Approval gates at critical decision points
Safe by Default - Resource, scope, time, and depth limits
Observable - Every Ralph reports to dashboard, WIP registry, compliance audit

Phase-Aligned Execution with Human Gates

Compliant Ralph respects a 12-phase workflow. Each Ralph type operates within specific phases:

Gate Types

Gate Type	Behavior	Example
Mandatory	Cannot bypass, requires human approval	Epic approval, Production deployment
Soft	Auto-approve if conditions met	Tests passing + build succeeds
Deviation	Triggered by Ralph deviation reports	Scope increase > 30%, Architecture change

No autonomous agent runs without oversight at critical decision points.

Safe Limits: Preventing Runaway Execution

Multiple layers of safety prevent agents from going off the rails:

safe_limits:
  # Depth limits - prevent infinite recursion
  tree_depth:
    max_depth: 5  # Epic -> Feature -> Requirement -> Spec -> Fix-Spec
    max_fix_spec_depth: 1  # Fix specs cannot spawn fix specs

  # Scope limits - prevent runaway work
  scope:
    max_files_per_spec: 10
    max_lines_changed_per_spec: 500
    action_on_limit: decompose_or_escalate

  # Time limits - prevent stagnation
  time:
    spec_ralph: { max_duration: 30m, max_iterations: 5 }
    feature_ralph: { max_duration: 24h }
    epic_ralph: { max_duration: 7d }

  # Cost limits - prevent bill shock
  cost:
    per_ralph_max: $5
    per_epic_max: $100
    per_day_max: $500

  # Error limits - detect failure patterns
  errors:
    same_error_threshold: 3
    total_errors_per_ralph: 10
    action_on_limit: circuit_breaker_cascade

Circuit Breaker Pattern

When errors occur, the system doesn't just retry forever:

CLOSED: Normal operation
HALF_OPEN: Monitoring after failure (1 retry allowed)
OPEN: Halted, requires human intervention

Automatic Task Decomposition

When a task is too large, Compliant Ralph automatically breaks it down:

SPEC-04 at 300 lines? May trigger secondary decomposition during execution if it approaches limits.

Decomposition Strategies

Strategy	When Used	How It Works
`by_file_groups`	Many files	Group by directory/module
`by_functionality`	Large scope	Semantic analysis finds natural boundaries
`by_criteria`	Many acceptance criteria	One child per criterion
`by_time_slices`	Long duration	Target 15min child tasks
`by_dependency_order`	Complex dependencies	Topological sort, parallelize independent

Self-Healing Patterns

Compliant Ralph doesn't just fail - it attempts recovery:

Feedback Structure

Children communicate with parents through structured feedback:

interface AgentFeedback {
  loopId: string;
  parentId: string | null;
  type: 'observation' | 'blocker' | 'question' | 'complete';
  category: 'scope' | 'dependency' | 'conflict' | 'success' | 'failure';
  severity: 'info' | 'warning' | 'error' | 'critical';
  message: string;
  suggestedAction?: string;
}

Parents aggregate feedback and decide: accept deviation, reject, escalate to grandparent, or pause for human.

Observability: Full Visibility Into Agent Execution

Every Ralph feeds into shared infrastructure:

Dashboard View

RALPH TREE VIEW                                          [Live]
-------------------------------------------------------------------
ROOT ORCHESTRATOR                                        Running

 EPIC-AUTH-001 (Authentication System)                  [65%]
   FEAT-login                                           [80%]
      REQ-AUTH-001                                       100%
      REQ-AUTH-002                                       [60%]
         SPEC-token-validation                           Running
   FEAT-logout                                           [0%]
      Blocked (waiting on login)

 OPS (Operational)                                       Continuous
   build-verify                                          Last: 2m
   cleanup                                               Last: 45m
   health-check                                          All green

-------------------------------------------------------------------
ALERTS
  SPEC-token-validation: 3rd iteration (circuit breaker: 2/5)
  FEAT-logout: Unblocked when REQ-AUTH-001 completes

Comparing Loop Approaches

Feature	Basic Ralph	Vibe Coding	Compliant Ralph (MALS)
Context Management	Fresh per iteration	Accumulates & compacts	Fresh per iteration + plan as source
Hierarchy	Flat (parallel only)	Single session	Fractal tree (depth 0-5)
Coordination	Manual merge	None	Automatic via LoopCoordinator
Error Recovery	Manual restart	Manual restart	Self-healing patterns
Scope Control	Honor spec	None	ScopeGuard + limits
Human Oversight	None	Continuous	Phase gates + deviation escalation
Observability	Logs only	Conversation	Dashboard + WIP + Compliance audit
Token Efficiency	Good	Poor	Good (per iteration)
Large Tasks	Struggles	Struggles	Auto-decomposition
Production Ready	Limited	No	Yes

The Implementation: TypeScript Agent Loop System

We built this as a TypeScript system within supernal-code-package:

supernal-code-package/src/agent-loop/
├── AgentLoop.ts           # Core loop execution
├── LoopCoordinator.ts     # Parallel loop management
├── FeedbackCollector.ts   # Aggregates child feedback
├── types.ts               # Interfaces
├── providers/
│   ├── claude.ts          # Real Claude execution
│   └── mock.ts            # Testing without API

Core Loop Interface

interface AgentLoopConfig {
  specPath: string;           // Source of truth
  planPath: string;           // Task checklist
  provider: LoopProvider;     // Claude or Mock
  maxIterations?: number;     // Circuit breaker
  onProgress?: (state: LoopState) => void;
}

interface LoopState {
  iteration: number;
  tasksTotal: number;
  tasksCompleted: number;
  status: 'running' | 'complete' | 'failed' | 'paused';
  feedback: AgentFeedback[];
}

CLI Commands (Coming)

# Start single loop
sc agent loop start spec.md --model opus

# Parallel loops
sc agent loop parallel specs-dir/ --max-concurrent 5

# Status & control
sc agent loop status [id]
sc agent loop abort [id]
sc agent loop logs [id] -f

# Decomposition
sc ralph decompose-preview REQ-AUTH-001
sc ralph decompose REQ-AUTH-001 --strategy=by_criteria

Why This Matters: Autonomous Agents That Scale

The combination of:

Fresh context per iteration (no context rot)
Plan as source of truth (no accumulated compaction)
Hierarchical decomposition (large tasks → small specs)
Phase gates with human oversight (safe autonomous execution)
Self-healing patterns (error recovery without restart)
Full observability (know what every agent is doing)

...means you can run agents for hours or days on complex features, with context integrity maintained throughout.

This is the difference between "AI assistant" and "AI teammate".

An assistant needs constant supervision. A teammate works autonomously within defined boundaries, escalates when appropriate, and coordinates with other teammates.

Getting Started with Compliant Ralph

Prerequisites

Supernal CLI installed (pnpm install)
Claude API access (or use MockProvider for testing)

Basic Usage

# 1. Create a requirement
sc requirement new "User Authentication" --epic=auth

# 2. Edit the requirement file (Gherkin format)
cursor docs/requirements/REQ-AUTH-001.md

# 3. Generate specs from requirement
sc ralph generate-specs REQ-AUTH-001

# 4. Start Ralph loop
sc agent loop start .specs/REQ-AUTH-001/ --model opus

# 5. Monitor in dashboard
sc dashboard

Configuration

# supernal.yaml
compliant_ralph:
  enabled: true

  phase_enforcement:
    enabled: true
    strict_mode: true  # Block without approval

  safe_limits:
    max_depth: 5
    max_concurrent_ralphs: 5
    cost_per_day_max: $100

  observability:
    wip_registry: true
    compliance_audit: true
    dashboard_feed: true

Conclusion: Context Is Everything

The fundamental insight of Ralph loops - treating context as static allocation rather than accumulating conversation - unlocks autonomous AI coding at scale.

Compliant Ralph takes this further:

Hierarchical trees for complex multi-requirement features
Phase gates for human oversight at critical decisions
Safe limits to prevent runaway execution
Self-healing for automatic error recovery
Full observability for production monitoring

This isn't theoretical. We're building Supernal with Supernal - using Compliant Ralph loops to implement features autonomously while maintaining code quality and compliance.

The future of software development is autonomous agents working within well-defined boundaries. Ralph loops are the foundation. Compliant Ralph is the production-ready evolution.

Want to try Ralph loops in your own projects? Check out the Supernal CLI or dive into our agent loop documentation.

Further Reading