# Ulc Loop

> Start a Unified Loop Controller session via Ralph Wiggum. Autonomously works through backlog, dispatches agents, and explores via QD when idle. Use when this capability is needed.

- Skill: `tomevault-io/ulc-loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ulc-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ulc-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ulc-loop

---


# ULC Loop

Start an autonomous improvement loop powered by Ralph Wiggum.

## Setup

Parse arguments from: $ARGUMENTS

Defaults:
- `--budget`: 5 (USD)
- `--max-iterations`: 20

## Workflow

### Step 1: Pre-flight Checks

1. Verify Ralph Wiggum plugin is installed:
   ```bash
   ls .claude/plugins/cache/claude-code-plugins/ralph-wiggum/ 2>/dev/null || echo "NOT INSTALLED"
   ```
   If not installed, tell the user to run: `claude plugin install ralph-wiggum@claude-code-plugins`

2. Check for existing Ralph loop:
   ```bash
   cat .claude/ralph-loop.local.md 2>/dev/null && echo "ACTIVE" || echo "INACTIVE"
   ```
   If ACTIVE, warn: "A Ralph loop is already running. Run `/cancel-ralph` first."

3. Check git state is clean:
   ```bash
   git status --porcelain
   ```
   If dirty, warn and suggest committing first.

### Step 2: Read the ULC Prompt

Read the ULC decision procedure from `.claude/skills/ulc-loop/ulc-prompt.md`.

### Step 3: Initialize ULC State

Create the initial ULC state file if it doesn't exist:

```bash
cat > .claude/ulc-state.local.json << 'EOF'
{
  "iteration": 0,
  "cumulative_cost_usd": 0,
  "budget_usd": <BUDGET>,
  "actions": [],
  "exploration_misses": 0,
  "started_at": "<ISO timestamp>"
}
EOF
```

Replace `<BUDGET>` with the parsed budget value.

### Step 4: Create Ralph State File

Write `.claude/ralph-loop.local.md` with YAML frontmatter and the ULC prompt as the body:

```
---
active: true
iteration: 1
max_iterations: <MAX_ITERATIONS>
completion_promise: "BUDGET EXHAUSTED OR ALL WORK COMPLETE"
started_at: "<ISO timestamp>"
---

<contents of ulc-prompt.md>
```

### Step 5: Confirm and Start

Output:
```
ULC Loop activated via Ralph Wiggum.

Budget: $<budget> USD
Max iterations: <max_iterations>
Completion promise: "BUDGET EXHAUSTED OR ALL WORK COMPLETE"

The loop will:
1. Check backlog for ready work
2. Dispatch sub-agents for substantial tasks
3. Explore via QD when backlog is empty
4. Stop when budget is exhausted or all work is complete

State file: .claude/ulc-state.local.json
Ralph state: .claude/ralph-loop.local.md

Starting first OODA cycle...
```

Then immediately begin executing the ULC prompt — perform the first OODA cycle (Observe → Orient → Decide → Act).

## Notes

- The ULC prompt is re-fed by Ralph's stop hook on each iteration
- Inter-iteration continuity is via `.claude/ulc-state.local.json` and git
- Sub-agents are dispatched via Task tool with `subagent_type: "general-purpose"`
- Cost tracking is approximate — the agent estimates based on model and turns
- The loop does NOT push to remote — human reviews and pushes

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kastalien-research) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->