agent-loop

What this skill does

<!-- AIWG-SKILL-CALLOUT -->
> **Skill access pattern (post-kernel-pivot, 2026.5+)**
>
> Skill names referenced in this document are AIWG skills, **not slash commands**. Most are not kernel-listed and cannot be invoked as `/skill-name` by the platform. Reach them via:
>
> ```bash
> aiwg discover "<capability>"
> aiwg show skill <name>
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).


# Agent Loop Skill

You detect when users want iterative autonomous task execution and route to an internal, in-session loop by default. External daemon loops are opt-in and require an explicit request.

## Loop Taxonomy

This skill is the **detection and routing layer** for autonomous agent loops — iterative patterns where a single agent retries a task against completion criteria until success or limits.

| Loop Type | Implementation | Description |
|-----------|---------------|-------------|
| **Internal Agent Loop** | current assistant session / internal loop | Default visible iterate-until-complete workflow in the active session |
| **Al** | internal `ralph` concept | Basic iterate-until-complete when named without external qualifiers |
| **External Agent Loop** | `agent-loop-ext` / `ralph-external` daemon | Explicitly requested background, detached, crash-resilient, or resumable work |
| *(future)* | — | Reflection loops, critic-actor loops, branching loops |

Generic loop requests route to the internal in-session loop. As new loop types are added, this skill will route based on task characteristics.

## Routing Policy

### Step 0: Provider Capability Check

Before choosing the loop mechanism, detect the active provider via `aiwg runtime-info` or the steward capability surface. The provider branch is internal to this skill; users invoke the same `agent-loop` / `ralph` names everywhere.

| Provider capability | Route | Notes |
|---|---|---|
| Provider with native `/goal` (Codex, Claude Code) | Delegate the in-session loop to `/goal` | Convert the task plus completion criterion into a standing goal. If a programmatic goal tool is unavailable, print the exact `/goal "..."` command for the operator instead of emulating a duplicate loop. |
| Provider with native dynamic orchestration (Claude Code Workflow tool) | In-session multi-agent fan-out MAY delegate to the native orchestration tool | AIWG retains audit, gates, best-output selection, and cross-session durability. The native tool is in-session/background scoped — NOT a detached daemon — so detached/resume-after-session work stays AIWG-native (see external row). |
| Other providers | AIWG internal loop discipline | Keep the existing visible act/verify/adapt cycle in the current session. |
| Explicit external/background request | `agent-loop-ext` / `ralph-external` | Detached, crash-resilient, resume-after-session-ends work stays AIWG-native: `/goal` is in-session, and the Claude Code Workflow tool is session-scoped. Codex has no core `/workflow` (verified, `codex-cli 0.135.0`, #1535). |

Native `/goal` mapping:

```text
/goal "<task>; completion: <measurable criterion>"
```

When completion is omitted, run `infer-completion-criteria` first and include the inferred criterion in the goal text. AIWG remains responsible for any activity-log entries, issue comments, and human-authorization gates around the loop.

Research and decision record: `.aiwg/research/codex-goal-integration.md`, `.aiwg/architecture/adr-codex-goal-routing.md`. The Claude Code dialect is the same operator-facing form: `/goal "<task>; completion: <criterion>"`.

External/orchestration routing (provider-native `/workflow`): `.aiwg/research/provider-workflow-integration.md`, `.aiwg/architecture/adr-workflow-routing.md`. Verified against `codex-cli 0.135.0` (#1535): Codex has no core `/workflow`; Claude Code's Workflow tool is the in-session orchestration analog. Detached/cross-session work stays AIWG-native (`ralph-external`).

### Default: Internal/In-Session Loop

Use the internal loop when the user says `agent-loop`, `al`, `ralph`, `loop`, `iterate`, `keep trying`, `fix until green`, `address issues`, `handle all listed issues`, or supplies an iteration bound such as `--iterations 200` without explicit external wording.

Run the work visibly in the current assistant session:

1. Establish completion criteria.
2. Act on the next bounded slice of work.
3. Verify with the relevant checks.
4. Adapt and continue until completion, blocker, or the requested iteration cap.

Do not launch detached processes, background sessions, or the Ralph external daemon for generic loop requests.

### Explicit External Route

Route to `agent-loop-ext` / `ralph-external` only when the user explicitly asks for external execution, background execution, a daemon, detached operation, crash resilience, session survival, resume-later behavior, unattended long-running work, or when they name `agent-loop-ext`, `ralph-external`, or the Ralph daemon directly.

If the user says `ralph` without external/background/daemon qualifiers, treat it as the internal loop concept.

## Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "ralph this: [task]" → iterative loop with extracted task
- "ralph it" (after describing work in conversation) → loop using conversation context
- "keep trying until [condition]" → loop with completion condition
- "fix until green" → test-fixing loop shorthand
- "loop until [condition]" → condition-based iteration
- "al: [task]" → shortcut for agent-loop invocation

## Trigger Patterns Reference

| Pattern | Example | Action |
|---------|---------|--------|
| `ralph this: X` | "ralph this: fix all lint errors" | Internal loop: extract task, infer completion |
| `ralph: X` | "ralph: migrate to TypeScript" | Internal loop: extract task, infer completion |
| `ralph it` | "ralph it" (after task description) | Internal loop: use conversation context |
| `keep trying until X` | "keep trying until tests pass" | Internal loop: task = current context, completion = X |
| `loop until X` | "loop until coverage >80%" | Internal loop: task = improve coverage, completion = X |
| `iterate until X` | "iterate until no errors" | Internal loop: task = fix errors, completion = X |
| `run until passes` | "run until passes" | Internal loop: infer test command |
| `fix until green` | "fix until green" | Internal loop: task = fix tests, completion = tests pass |
| `keep fixing until X` | "keep fixing until lint is clean" | Internal loop: task = fix lint, completion = X |
| `al: X` | "al: fix all lint errors" | Internal loop shortcut: extract task |

## Extraction Logic

### Task Extraction

**From explicit task**:
- "ralph this: fix all TypeScript errors" → Task: "fix all TypeScript errors"
- "ralph: migrate src/ to ESM" → Task: "migrate src/ to ESM"

**From context**:
- "ralph it" after discussing a refactor → Use previous conversation as task context

### Completion Inference

When the user doesn't specify explicit verification, delegate to the **`infer-completion-criteria`** skill (`@$AIWG_ROOT/agentic/code/addons/agent-loop/skills/infer-completion-criteria/SKILL.md`). That skill runs a deterministic 5-layer pipeline:

1. **Task verb** → criterion class (test-pass, type-clean, regression-gate, coverage, lint-clean, build-pass, implement-feature)
2. **Project context files** (CLAUDE.md / AGENTS.md / AIWG.md) → canonical commands from the Development section
3. **Package manifests** (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, etc.) → discovered scripts
4. **CI configuration** (`.github/workflows/`, `.gitea/workflows/`, GitLab/CircleCI/Jenkins) → team's actual "passes" definition
5. **`.aiwg/` artifacts** (test-strategy, related use cases by ID match, prior progress files) → project-specific