/agent-loop

namespace: aiwg
name: agent-loop
description: Detect requests for iterative autonomous agent loops and route to the appropriate loop executor
version: 3.1.0
platforms: [all]

<!-- 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:

/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. Declare any loop controls required by task criticality: budget ceilings, eval/holdout split, and exploration quota. 3. Record a hypothesis, expected failure mode, and distinguishing diagnostic before each material change. 4. Act on the next bounded slice of work. 5. Verify with the relevant checks. 6. Adapt with structural variation after flat cycles, then continue until completion, blocker, budget stop, or the requested iteration cap.

For long-running, high-criticality, budgeted, adversarial, or eval-driven loops, AIWG treats mechanical evidence as load-bearing and self-report as secondary. Relevant controls:

• **Budget stop**: declared wall-clock/token/spend/tool ceilings stop the loop

and require a best-output report.

• **Dosed entropy**: non-improving cycles cannot repeat the same tactic; every

declared `K` cycles requires a structural variant or stop.

• **Holdout isolation**: hidden fixtures or answer keys produce aggregate-only

feedback to the optimizer; detailed diagnostics stay in private audit logs.

• **Experiment log**: hypothesis, expected failure mode, diagnostic, result,

and probe/generalization signal survive compaction.

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

Explicit External Route

Route to `agent-loop-e