LoopKing Quick Reference

A one-page reference for LoopKing. LoopKing ships the loop CLI (Python package loopking) 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 and service home: https://loopk.ing.

Run a loop

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

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

# Resume: reopen the latest run folder and continue from saved state.
loop 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.
loop launch fix-login.loop.md

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

# Only generate YAML/preset prompts.
loop 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

Minimal 5-line verifier template

The smallest viable loop. Copy, paste, change the echo line to your real gate (test, build, lint, type-check, contract check, profile). Pass = exit 0.

# Fix Login Bug
goal: Fix the login regression and prove it.
max_iterations: 3
check: ./scripts/check.bash

Or with two explicit steps and a recoverable fix path:

# Fix Login Bug
goal: Fix the login regression and prove it.
max_iterations: 3
## Flow
- coder: prompt prd/02_coder.md -> pass: test, fail: failed
- test: command `./scripts/check.bash` -> pass: success, fail: coder

Modes (canonical 3 + beginner aliases):

Alias	Canonical	Topology	check:	Use when
ask	loose	one worker	optional	one-shot prompt + answer
build	in-depth	planner/coder/reviewer	optional	full feature work
fix	deterministic	planner/coder/verifier	required	test/repair loop
loose/simple	loose	one worker	optional	rawest loop
in-depth/deep	in-depth	planner/coder/reviewer	optional	deeper feature work
deterministic/strict	deterministic	planner/coder/verifier	required	test-driven loop

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

Team layer (LoopKing Cloud)

Optional hosted commands, configured by loopking.yaml (token from $LOOPKING_TOKEN):

loop registry push <file.loop.md> [--version V] [--owner O]
loop registry pull <name> [--version latest] [--dest DIR]
loop registry list

loop tools sync [--profile P] [--dest DIR]
loop tools list
loop tools show <profile>

loop runs push <run_dir>
loop runs list <spec>

loop doctor
loop auth-status

loopking.yaml shape:

team: acme
registry:
  backend: http              # or: filesystem (location: <dir>)
  base_url: https://api.loopk.ing
profiles:
  default:
    skills: [code-review, debugging]
    mcp:
      github: { command: npx, args: ["-y", "@modelcontextprotocol/server-github"] }
    commands: [uv run pytest]
    policies:
      require_approval: [deploy, database_write]

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.
• Override the agent command with $LOOPKING_AGENT_COMMAND (template: {prompt}, {run_dir}, {step}, {iteration}).

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.