Ariadne Loop

Use this skill to turn vague agent work into a bounded loop contract for OpenClaw, Codex, Claude Code, or another coding agent. The goal is not to make a longer prompt. The goal is to make the next agent turn verifiable.

When to Use

Use this skill when the user asks for any of these:

• a loop, agent loop, or Loop Engineering spec,
• a resumable handoff for OpenClaw, Codex, Claude Code, or another coding agent,
• a GitHub issue converted into an executable agent task,
• release, refactor, bugfix, or documentation work that needs explicit gates,
• supervision rules for repeated agent reports.

Preferred Workflow

1. Identify the source shape:

   • rough notes,
   • GitHub issue title and body,
   • release/refactor/bugfix request,
   • long thread handoff.

2. Create a snapshot JSON with:

   • title,
   • goal,
   • current_state,
   • recent_progress,
   • constraints,
   • verifiers,
   • external_effects,
   • execution_policy when the agent may perform selected external effects,
   • risk.

3. Generate or write an agent packet that includes:

   • inspect -> act -> verify -> persist -> decide cycle,
   • concrete verifiers,
   • stop rules,
   • rollback behavior,
   • durable memory updates before stop decisions,
   • policy-aware human gates for external effects,
   • JSON-only report contract.

4. If the user wants a first-run demo and the Ariadne Loop CLI is installed:

   ariadne-loop quickstart --output .ariadne/quickstart
   

   This creates a Loop Run Kit with a snapshot, loop JSON, agent packet, progress file, runbook, control prompts, report log, and supervision decision.

   To continue the loop through natural-language control, generate the next prompt from the current decision:

   ariadne-loop prompt --dir .ariadne/quickstart
   

5. For real work, prefer using the CLI:

   ariadne-loop init --preset bugfix --output loop-snapshot.json
   ariadne-loop write --input loop-snapshot.json --output loop-report.md --format markdown
   ariadne-loop make --input loop-snapshot.json --output loop.json --format json
   ariadne-loop check --input loop.json
   

6. If the work starts from a GitHub issue body:

   ariadne-loop from-issue \
     --title "Issue title" \
     --body-file issue.md \
     --output issue-loop.json
   

7. For running loops, ask the agent to append JSON reports to JSONL and use:

   ariadne-loop supervise \
     --loop loop.json \
     --reports reports.jsonl \
     --output decision.json
   ariadne-loop prompt --dir .
   

If the CLI Is Not Installed

Do not block. Produce the snapshot JSON and the agent packet directly in the response or in files. Tell the user they can use the browser builder:

https://zhangzeyu99-web.github.io/ariadne-loop/playground.html

Use this report contract:

{
  "action_id": "inspect|act|verify|persist|decide",
  "status": "continue|stop|needs_human|rollback",
  "evidence": ["specific evidence observed in this turn"],
  "next_step": "the next concrete action",
  "passed_verifiers": ["gate ids that passed in this turn"],
  "failed_verifiers": ["gate ids that failed in this turn"]
}

Verifier Rules

Prefer observable gates:

• command output,
• rendered page or screenshot readback,
• generated artifact exists and validates,
• remote GitHub issue, PR, release, or Pages output is read back,
• diff contains no unrelated churn,
• failing reproduction now passes.

Avoid weak gates:

• "looks good",
• "done",
• "agent says it completed",
• unverified screenshots,
• claims about remote state without readback.

Human Gates

By default, require human confirmation before:

• commit,
• push,
• tag or release creation,
• package publish,
• deploy,
• deletion,
• sending external messages,
• payment or billing actions.

An execution_policy may allow selected declared effects such as commit or push. Effects in human_required_effects, and undeclared effects, always require confirmation.

After any approved external effect, read back the real target before reporting success.