User Guide

Install

From the repository root:

uv sync

Run a safe dry-run:

uv run loopspec run specs/code-fix-loop.yaml

Launch from markdown

Create a loop file:

# 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

Launch it:

uv run loopspec launch fix-login.loop.md

Execute it only after reviewing the generated artifacts:

uv run loopspec launch fix-login.loop.md --execute

Preset modes

Mode	Generated workflow	Needs check:?
loose	worker prompt only	No
in-depth	planner -> coder -> reviewer, plus verifier when check: is set	No
deterministic	planner -> coder -> verifier	Yes

Safety notes

• Markdown loop files are trusted workflow inputs.
• Command steps run only with --execute.
• Prompt files, working directories, run roots, and custom output paths are kept inside the markdown directory boundary.
• Generated .loopspec/ files are local artifacts and ignored by Git.