- namespace
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jmagly/aiwg --skill agent-loop -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jmagly/aiwg --skill agent-loop -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jmagly/aiwg --skill agent-loop -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jmagly/aiwg --skill agent-loop -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/jmagly/aiwg/tree/HEAD/agentic/code/addons/agent-loop/skills/agent-loopFrom the publisher
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-nameby the platform. Reach them via:aiwg discover "<capability>" aiwg show skill <name> --bodyOnly kernel-listed skills (
aiwg-doctor,aiwg-refresh,aiwg-status,aiwg-help,use,steward) are directly invokable as slash commands. See skill-discovery rule.
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.
Before any confirmation below, read and apply
agent-loop authorization checkpoints.
Call aiwg config authorization check --action-file "$ACTION_FILE" --target "$TARGET_REPO"
for host-classified effects. Only auto-authorized with a signed receipt skips
that workflow prompt; retain existing prompts/refusals otherwise. Platform
prompts are never bypassed. Limits, regression and threat overrides still require review.
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.
Generic loop requests route to the internal in-session loop. As new loop types are added, this skill will route based on task characteristics.
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.
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).
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:
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:
K cycles requires a structural variant or stop.Do not launch detached processes, background sessions, or the Ralph external daemon for generic loop requests.
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.
Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):
From explicit task:
From context:
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:
package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, etc.) → discovered scripts.github/workflows/, .gitea/workflows/, GitLab/CircleCI/Jenkins) → team's actual "passes" definition.aiwg/ artifacts (test-strategy, related use cases by ID match, prior progress files) → project-specific gatesSynthesis is validated against the vague-discretion rule and emits a structured YAML proposal with criterion, verification command, rationale chain, confidence level, and alternatives considered.
Use the inline table below ONLY as a last-resort fallback when the inference skill is unavailable (degraded environment, missing skill deployment). It is intentionally narrow — JavaScript/Node-centric — and represents prior state before infer-completion-criteria was added.
Legacy fallback table:
When the inference skill IS available, prefer it. The skill handles multi-language projects, monorepos, CI-defined gates, use-case acceptance criteria, and the refusal case (truly vague tasks like "make it better" that have no measurable criterion).
User: "ralph this: migrate all files in lib/ to ESM" Extraction:
Action: Run an internal loop in the current session for migrate all files in lib/ to ESM until the inferred completion command succeeds
User: "keep fixing until the tests are green" Extraction:
Action: Run an internal loop in the current session until npm test passes
User: "ralph it" (after discussing adding auth validation) Extraction:
Action: Run an internal loop in the current session using the context-based task and inferred criteria
User: "loop until coverage is above 80%" Extraction:
Action: Run an internal loop in the current session until the coverage report shows more than 80%
User: "Run this in the background with crash recovery and let me attach later" Extraction:
Action: Route to agent-loop-ext / ralph-external because the user explicitly requested background crash-resilient execution
If extraction is ambiguous, ask the user:
I'll start an iterative loop for: {extracted task}
What command verifies completion?
1. npm test (Recommended for test fixes)
2. npx tsc --noEmit (For type errors)
3. npm run lint (For lint errors)
4. npm run build (For build issues)
5. Custom command...
Or if task is unclear:
I detected an iterative loop request. To start iterating:
What task should I repeat until success?
What command tells me when it's done?
Version 2.0 added concurrent loop execution with registry tracking. This applies to explicit external daemon loops, not ordinary internal agent-loop requests.
All loops have unique identifiers:
ralph-{slug}-{uuid8}ralph-fix-tests-a1b2c3d4Users can optionally specify a loop ID for external daemon loops:
/ralph "fix tests" --completion "npm test passes" --loop-id ralph-my-fixes-12345678
If not provided, ID is auto-generated from task description.
External active loops are tracked in .aiwg/ralph/registry.json:
{
"version": "2.0.0",
"max_concurrent_loops": 4,
"active_loops": [
{
"loop_id": "ralph-fix-tests-a1b2c3d4",
"status": "running",
"iteration": 5,
"task": "fix all TypeScript errors",
"started_at": "2026-02-02T21:00:00Z",
"pid": 12345
}
]
}
When starting a new external loop:
active_loops.length < 4User sees:
Error: Maximum concurrent loops (4) reached
Active loops:
1. ralph-fix-tests-a1b2c3d4 (iteration 5) - fix TypeScript errors
2. ralph-add-docs-b2c3d4e5 (iteration 3) - add JSDoc comments
3. ralph-refactor-c3d4e5f6 (iteration 8) - refactor API module
4. ralph-migrate-d4e5f6a7 (iteration 2) - migrate to ESM
Abort one with: aiwg ralph-abort {loop_id}
Check all active loops:
aiwg ralph-status --all
Check specific loop:
aiwg ralph-status ralph-fix-tests-a1b2c3d4
Abort a loop:
aiwg ralph-abort ralph-fix-tests-a1b2c3d4
Resume a paused loop:
aiwg ralph-resume ralph-fix-tests-a1b2c3d4
Multi-loop structure per loop:
.aiwg/ralph/
├── registry.json # Multi-loop registry
└── loops/
├── ralph-fix-tests-a1b2c3d4/
│ ├── state.json
│ ├── checkpoints/
│ │ ├── iteration-001.json.gz
│ │ └── iteration-002.json.gz
│ └── analytics/
│ └── analytics.json
└── ralph-add-docs-b2c3d4e5/
├── state.json
└── ...
Once task and completion are extracted/confirmed, use the default internal route unless explicit external wording is present.
For the default internal route:
For explicit external daemon routes:
agent-loop-ext / ralph-external, then surface status, log, attach, and abort commandsParallel bug fixes:
User: "run an external ralph loop to fix TypeScript errors in src/"
→ Loop 1: ralph-fix-ts-errors-a1b2c3d4
User: "also run an external ralph loop to add missing tests in lib/"
→ Loop 2: ralph-add-tests-b2c3d4e5
Both running in parallel until completion criteria met.
Sequential with manual abort:
User: "run an external ralph loop to refactor the entire auth module"
→ Loop 1: ralph-refactor-auth-c3d4e5f6 (running)
User: "actually, abort that and just fix the login bug"
→ aiwg ralph-abort ralph-refactor-auth-c3d4e5f6
→ Loop 2: ralph-fix-login-d4e5f6a7 (running)
ralph-external, detached daemons, or background aiwg ralph processes unless the user explicitly asks for theminfer-completion-criteria skill - derives measurable --completion from project state when the user doesn't supply oneralph skill - legacy name for the iterative loop concept; agent-loop is canonical and defaults to in-session executionagent-loop-ext skill - crash-resilient external loop with state persistenceralph-status skill - check loop progressralph-resume skill - continue interrupted loopsralph-abort skill - abort active loops@$AIWG_ROOT/agentic/code/addons/agent-loop/schemas/loop-registry.yaml - Registry schema@$AIWG_ROOT/agentic/code/addons/agent-loop/schemas/loop-state.yaml - Loop state schema@.aiwg/research/findings/REF-086-cognitive-load-limits.md - Concurrency researchagent-loop routing to internal in-session loops; require explicit wording for external daemon loopsralph-loop to agent-loop; added loop taxonomy (Issue #558)Detect requests for iterative autonomous agent loops and route to the appropriate loop executor
---name: agent-loopdescription: Detect requests for iterative autonomous agent loops and route to the appropriate loop executor---# agentic/code/addons/agent-loop/skills/agent-loop/SKILL.mdFAQ
Download agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/jmagly/aiwg.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.