Loop

A self-sustaining development loop with two modes: Researcher and Implementor.

Prerequisites

Full permissions required. The loop runs autonomously and needs unrestricted access.

Claude Code

claude --dangerously-skip-permissions

Codex

The script automatically uses --yolo mode (no sandbox, no prompts).

Startup Flow

When this skill is invoked, ask the user FOUR questions using AskUserQuestion, then one text prompt:

Question 1: Mode (AskUserQuestion)

Question: "Which mode would you like to run?"
Options:
1. Research - Explore, investigate, and plan. Creates specs for implementation.
2. Implement - Execute on specs. Write code, tests, and documentation.

Question 2: Git Workflow (AskUserQuestion)

Question: "What should happen after each task?"
Options:
- Push - Commit and push to current branch (default)
- Commit only - Commit locally, no push
- Open PR - Open PR, wait for CI (no merge)
- PR and merge - Open PR, wait for CI, then auto-merge

Question 3: Context Management (AskUserQuestion)

Question: "Should each iteration start with fresh context?"
Options:
- Fresh context - Clear context between iterations (default, recommended)
- Keep context - Maintain conversation history across iterations

Question 4: Directions (AskUserQuestion - optional)

Question: "Any specific directions for this run?"
Options (mode-aware, user can select "Other" for custom):
- None - No specific directions, work autonomously
- For Research mode:
  - Focus on specs - Review and improve existing implementation specs
  - Explore dependencies - Research external libraries and frameworks
- For Implement mode:
  - Fix issues first - Prioritize fixing build errors and warnings
  - Skip tests - Focus on implementation, skip test writing for now

If user selects "Other", they can provide custom directions like:

"Focus on authentication patterns"
"Search Apple developer docs for NSPanel"
"Prioritize the archive feature"
"Redo the task list with proper SwiftUI patterns"

The agent interprets directions intelligently (creating dots, modifying tasks, updating docs, changing priorities, etc.).

Question 5: Iterations (Text prompt - NOT AskUserQuestion)

After the AskUserQuestion completes, ask:

"How many iterations? Enter a number, 'inf' for infinite, or 'comp' for until complete:"

Parse the response:

Number (e.g., "2", "5", "10") → exact iteration count
"inf", "infinite", "-1" → infinite mode (-1)
"comp", "complete", "0" → until complete mode (0)

Key distinction:

Infinite / N iterations: Completion promise is IGNORED. Loop continues for re-analysis and improvement.
Until complete: Only mode where completion promise stops the loop.

After collecting answers:

Initialize loop state by running: ./scripts/setup-loop.sh <mode> --iterations <N> --git-workflow <workflow> [--fresh-context] [--directions "..."]
- Iterations: -1=infinite, 0=until complete, N=exact count
- Workflow: commit/push/pr/pr-merge
- Directions: optional user guidance for the agent
Build the prompt by combining mode-specific + shared content:
- Read <mode>-loop.md (mode-specific sections)
- Read loop-shared.md (common sections)
- Concatenate: mode-specific + shared
Begin execution based on context mode:

Fresh context mode (default): You are the orchestrator. Run this loop in the main conversation:

iteration = 0
PROMPT = contents of <mode>-loop.md + "\n\n" + contents of loop-shared.md
DIRECTIONS = user's directions (if provided)

# Exponential backoff for infinite mode
MIN_DELAY = 5        # seconds
current_delay = MIN_DELAY

# If directions were provided, append them to the prompt
if DIRECTIONS:
    PROMPT = PROMPT + "\n\n## User Directions\n\n" + DIRECTIONS

LOOP:
    iteration += 1
    print "=== Iteration {iteration} ==="

    result = Task(prompt=PROMPT, subagent_type="general-purpose")

    # Check termination conditions
    if iterations == 0:  # "until complete" mode
        if result contains "RANDROID_LOOP_COMPLETE":
            print "Loop complete (promise found after {iteration} iterations)"
            EXIT LOOP
    elif iterations > 0:  # exact N iterations mode
        if iteration >= iterations:
            print "Completed {iteration} iterations"
            EXIT LOOP
    # iterations == -1 means infinite, continues below

    # Exponential backoff for infinite mode when no work done
    if iterations == -1:  # infinite mode
        if result contains "RANDROID_LOOP_COMPLETE":
            print "No work this iteration, backing off for {current_delay}s..."
            sleep(current_delay)
            current_delay = current_delay * 2  # No max cap
        else:
            # Meaningful work done, reset backoff
            current_delay = MIN_DELAY

    GOTO LOOP

CRITICAL: After each Task returns, YOU (the orchestrator) must:

Check the result for the completion promise
Check if iteration limit reached
If neither → spawn another Task for the next iteration
Do NOT stop just because one Task finished

Keep context mode: Run the loop directly in the current conversation. The stop hook will intercept exit and continue looping with accumulated context.

Usage

Interactive (Recommended)

/loop

Prompts for mode, iterations, and optional directions.

Aliases: /randroid, /randroid-loop

Direct (Skip Questions)

/loop research - Research mode, prompts for iterations
/loop implement - Implement mode, prompts for iterations
/loop research --loop - Research mode, infinite (ignores completion)
/loop research --until-complete - Research mode, stops on completion
/loop implement --iterations 5 - Implement mode, exactly 5 iterations
/loop implement --open-pr - Open PR workflow
/loop implement --pr-and-merge - PR with auto-merge workflow
/loop implement --commit-only - Local commits only
/loop implement --keep-context - Keep conversation context (no fresh start)
/loop implement --iterations 5 --open-pr - Combine options

With Directions

You can provide guidance for the agent. When prompted for directions:

Select a preset option (mode-specific), or
Select "Other" and type custom directions like:
- "Focus on authentication patterns"
- "Prioritize the archive feature, skip tests for now"

Directions can include:

Topics to research or questions to answer
Priorities for which tasks to work on
Specific implementation guidance
Requests to redo or improve previous work
Scope changes (add/remove/modify tasks)

Codex (External Script)

# From terminal (outside Codex)
./scripts/randroid-loop.sh
# Interactive prompts for mode, iterations, and git workflow
# Note: Wrapper always uses fresh context (each iteration is a new codex exec)

# Direct invocation:
./scripts/randroid-loop.sh research -1           # infinite
./scripts/randroid-loop.sh research 0            # until complete
./scripts/randroid-loop.sh implement 5           # exactly 5 iterations
./scripts/randroid-loop.sh implement 5 pr        # 5 iterations, open PR
./scripts/randroid-loop.sh implement 0 pr-merge  # until complete, PR + merge

Modes

Research Mode

The researcher explores, investigates, and plans. It:

Creates research: prefixed dots to track its own exploration
Creates implement: prefixed dots as deliverables for the implementor
Does NOT write production code
Outputs findings, decisions, and clear implementation specs

Implementor Mode

The implementor executes. It:

Pulls from ready implement: dots
Writes code, tests, and documentation
Creates new implement: dots if scope expands
Creates research: dots if blocked by unknowns (for next research cycle)

Loop Mechanics

Fresh Context Each Iteration

Each loop iteration starts with fresh conversational context. Only the filesystem persists:

Modified files
Git history and commits
Dots system state
Research/implementation artifacts

This prevents context bloat and allows the agent to approach each iteration with clarity.

What Persists

All file changes from previous iterations
Git commits and history
.dots/ task state
Any written documentation or specs

What Resets

Conversation history
In-memory state
Token usage (fresh budget each iteration)

Loop Termination

Output <promise>RANDROID_LOOP_COMPLETE</promise> when:

No more ready tasks for your mode
All work is committed and pushed

The loop also stops when --iterations N limit is reached.

Architecture

loop/
├── SKILL.md              # This file
├── research-loop.md      # Research mode prompt
├── implement-loop.md     # Implementor mode prompt
├── loop-shared.md        # Shared sections (git, dots, termination)
├── LOOPING_DESIGN.md     # Technical design doc
├── hooks/
│   └── stop-hook.sh      # Claude Code stop hook
├── scripts/
│   ├── setup-loop.sh     # Initialize loop state
│   └── randroid-loop.sh  # Codex external wrapper
└── state/
    └── .gitignore        # Excludes local state files