ulc-loop - SKILL.md Agent Skill

name: ulc-loop description: Start a Unified Loop Controller session via Ralph Wiggum. Autonomously works through backlog, dispatches agents, and explores via QD when idle. argument-hint: "[--budget N] [--max-iterations N]" user-invocable: true allowed-tools: Read, Bash, Write

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

Verify Ralph Wiggum plugin is installed:
```
ls .Codex/plugins/cache/Codex-plugins/ralph-wiggum/ 2>/dev/null || echo "NOT INSTALLED"
```
If not installed, tell the user to run: Codex plugin install ralph-wiggum@Codex-plugins
Check for existing Ralph loop:
```
cat .Codex/ralph-loop.local.md 2>/dev/null && echo "ACTIVE" || echo "INACTIVE"
```
If ACTIVE, warn: "A Ralph loop is already running. Run /cancel-ralph first."
Check git state is clean:
```
git status --porcelain
```
If dirty, warn and suggest committing first.

Step 2: Read the ULC Prompt

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

Step 3: Initialize ULC State

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

cat > .Codex/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 .Codex/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: .Codex/ulc-state.local.json
Ralph state: .Codex/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 .Codex/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