# LoopKing

> Portable, stateful AI coding-loop workflows for oh-my-pi-fork, local shell commands, and non-interactive prompt agents. Open-source local-first CLI (`loop`) plus an optional hosted team layer (LoopKing Cloud).

Canonical site: https://loopk.ing
Repository: https://github.com/kingkillery/loopking
CLI command: loop
Python package: loopking
Preferred prompt agent: oh-my-pi-fork / omp print mode

## What this project does

LoopKing lets a developer describe repeatable coding-agent loops as readable markdown (`*.loop.md`, the LoopSpec format) or typed YAML specs. The `loop` CLI compiles those descriptions into deterministic workflow specs, dry-runs them safely by default, and can execute prompt-agent steps plus shell verifier steps when `--execute` is supplied.

LoopKing Cloud is the hosted team layer (at loopk.ing): a registry-first service for shared loops, tool profiles (skills, MCP servers, verifier commands, policies), and run history. Execution stays local-first; hosted coordination standardizes team agent behavior.

Core behavior:

- `loop launch <file.loop.md>` compiles markdown to `.loopspec/generated/<name>.yaml` and runs it.
- `loop compile <file.loop.md>` only generates YAML and preset prompts.
- `loop run <spec.yaml>` runs an existing YAML spec.
- Dry-run is the default and does not call agents or run shell commands.
- Execute mode routes prompt steps by semantic `Decision: PASS` / `Decision: FAIL` output.
- Command steps route by exit code: `0` is pass, non-zero is fail.
- Run state and artifacts are stored under `runs/`.
- Generated launch artifacts are stored under `.loopspec/` and are ignored by Git.

Team layer (LoopKing Cloud), configured by `loopking.yaml`, token from `$LOOPKING_TOKEN`:

- `loop registry push|pull|list` - share versioned loops.
- `loop tools sync|list|show` - materialize a team tool profile into `.loopking/`.
- `loop runs push|list` - upload privacy-preserving run metadata (no source).

## Best starting points

- User guide: https://loopk.ing/user-guide/
- Quick reference: https://loopk.ing/quick-reference/
- Developer guide: https://loopk.ing/developer-guide/
- README source: https://github.com/kingkillery/loopking/blob/main/README.md
- Source package: https://github.com/kingkillery/loopking/tree/main/src/loopking
- Tests: https://github.com/kingkillery/loopking/tree/main/tests

## Minimal markdown loop

```markdown
# 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
```

Run it safely:

```bash
uv sync
uv run loop launch fix-login.loop.md
```

Execute it after inspecting generated artifacts:

```bash
uv run loop launch fix-login.loop.md --execute
```

## Preset modes

- `loose`: one worker prompt, minimal structure.
- `in-depth`: planner -> coder -> reviewer, plus verifier when `check:` is set.
- `deterministic`: planner -> coder -> verifier, requires `check:` unless an explicit `## Flow` is supplied.

## Safety model

- Treat markdown loop files as trusted workflow inputs.
- Keep prompt files, working directories, run roots, and custom output paths inside the markdown file's directory boundary.
- Prefer dry-run first; inspect generated prompts and commands before `--execute`.
- Use explicit verifier commands for work that must be deterministic.
- Keep fail routes pointed at the step that can repair the failed condition.

## Maintainer commands

```bash
uv sync
uv run pytest
uv run ruff check .
uv run basedpyright
uv run --group docs mkdocs build --strict --site-dir site
npx wrangler pages deploy site --project-name loopking --branch main
```

## Deployment

Docs: Cloudflare Pages project `loopking`, domain loopk.ing, built from MkDocs `site/`.
Hosted API: Cloudflare Worker `loopking-api` in `worker/`, serving api.loopk.ing with KV storage and a `LOOPKING_TOKEN` secret.