Skip to content

LoopSpec v3 Quick Reference

A one-page reference for the LoopSpec v3 workflow. LoopSpec ships a loopspec package whose run command drives a spec end to end. A compatibility script (runner/run_loop.py) mirrors it exactly, so either form works.

Canonical hosted docs: https://loops.artificalgarden.org.

Run a loop

# Dry-run (default): renders prompt artifacts, lists commands, runs nothing.
loopspec run specs/code-fix-loop.yaml

# Execute: actually run prompt steps + command steps.
loopspec run specs/code-fix-loop.yaml --execute

# Resume: reopen the latest run folder and continue from saved state.
loopspec run specs/code-fix-loop.yaml --execute --resume

The same calls work through the compatibility script:

python runner/run_loop.py specs/code-fix-loop.yaml
python runner/run_loop.py specs/code-fix-loop.yaml --execute
python runner/run_loop.py specs/code-fix-loop.yaml --execute --resume
  • Dry-run is the default. Without --execute, prompt steps only write the rendered prompt artifact and command steps record what they would run. It is always safe to dry-run.
  • --execute runs prompt steps through your agent harness and command steps through the shell. Command steps use exit code 0 as pass; prompt steps require semantic output (Decision: PASS or Decision: FAIL) and fail closed when the verdict is missing.
  • --resume reopens the most recent run folder for the spec, reloads state.json, and continues from the saved current_step.

Launch a markdown loop

# Compile .loop.md to .loopspec/generated/<name>.yaml and dry-run it.
loopspec launch fix-login.loop.md

# Execute through oh-my-pi-fork/omp.
loopspec launch fix-login.loop.md --execute

# Only generate YAML/preset prompts.
loopspec compile fix-login.loop.md

Minimal explicit flow:

# Fix Login Bug
mode: deterministic
goal: Fix the login regression and prove it with tests.
max_iterations: 3

## Flow
- coder: prompt prd/02_coder.md -> pass: verifier, fail: failed
- verifier: command `uv run pytest tests/test_login.py` -> pass: success, fail: coder

Preset flow:

# Deep Feature Loop
mode: in-depth
goal: Build the requested feature and verify it.
check: uv run pytest

Modes: loose creates one worker prompt; in-depth creates planner/coder/reviewer and optionally a verifier from check:; deterministic creates planner/coder/verifier and requires check: unless ## Flow is explicit.

Generated .loopspec/ files are local launch artifacts and are ignored by Git.

Prompt agent

Prompt steps (in --execute mode) hand each rendered prompt artifact to an agent harness. The preferred harness is oh-my-pi-fork (C:/dev/Desktop-Projects/oh-my-pi-fork), run in print mode so it answers the single rendered prompt and exits:

omp -p "@runs/<stamp>-<name>/01-planner.prompt.md"
  • omp -p is print mode — non-interactive, one prompt in / one answer out, exit.
  • The leading @ inline-references the rendered prompt artifact so its full text becomes the prompt.
  • The artifact is the NN-<step>.prompt.md file the runner writes (see Run output files); the agent's answer is captured to NN-<step>.out.md.
  • Missing prompt agent in execute mode is a step failure, not a simulated pass.

omp is the oh-my-pi-fork build — install it globally or ensure the omp binary from the repo above is on your PATH. The compatibility runner (runner/run_loop.py) shells out to the same omp binary in execute mode.

Spec shape

name: code-fix-loop
title: Code Fix Loop
version: 3
goal: Write, fix, verify, repeat.
max_iterations: 6

context:
  working_directory: .
  run_root: runs
  agent:
    runner: omp                      # oh-my-pi-fork, print mode, @artifact
    source: C:/dev/Desktop-Projects/oh-my-pi-fork

steps:
  - name: coder
    type: prompt
    prompt_file: prd/02_coder.md
    routes:
      pass: verifier
      fail: stop_failed

Required keys: name, goal, max_iterations, steps. Optional: title, version, context (working_directory, run_root, agent), success_criteria, failure_criteria. The agent block names the preferred prompt harness — see Prompt agent.

Step types

Prompt step

Renders prompt_file and writes it into the run folder. In execute mode it hands the rendered artifact to the prompt agent (see Prompt agent) and routes by the agent's semantic Decision: PASS / Decision: FAIL output. In dry-run it only writes the artifact and records a safe pass.

- name: coder
  type: prompt
  prompt_file: prd/02_coder.md

Command step

Runs a shell command. Exit code 0 is pass; anything else is fail.

- name: verifier
  type: command
  command: python tools/example_verifier.py

Routes & stop routes

Every step declares where to go on pass and fail:

routes:
  pass: <next step | stop_success | stop_failed>
  fail: <next step | stop_success | stop_failed>

Two stop routes end the loop:

  • stop_success — goal met; status success; report written.
  • stop_failed — unrecoverable; status failed; report written.

A fail that routes back to a real step (e.g. verifier fail → coder) counts as a new iteration. Once max_iterations is exceeded the loop stops with status failed_max_iterations and writes the report. Forward pass routing does not consume iteration budget.

Run output files

Each run writes everything under one timestamped folder:

runs/<YYYYMMDD-HHMMSS>-<spec-name>/
  state.json            # status, iteration, current_step, last_error, history
  01-planner.prompt.md  # rendered prompt artifact (prompt step)
  01-planner.out.md     # agent harness output (prompt step, --execute only)
  01-verifier.log       # command stdout/stderr (command step, --execute only)
  final_report.md       # written when the loop stops

state.json is what --resume reads, so keep it for any run you intend to resume. In dry-run, prompt steps still produce .prompt.md artifacts, but no .out.md or .log files are written.