LoopPrint — an interactive wizard that turns a vague goal into a complete, runnable loop blueprint (spec + state + external verifier + run script + safety checklist). Use when the user says 'design a loop', 'build a loop', 'new loop', 'loopprint', 'loop wizard', or hands over a vague recurring task they want to automate. Runs a Tier-0 decision gate (is this even a loop?), sharpens the goal with 3-5 questions, enforces the four atoms (Goal/State/Verifier/Stop), recommends a pattern (debug / spec-driven / performance / hybrid), and generates the full artifact package into loops/<slug>/. Say 'skip wizard' or 'direct run' to bypass the interview. If the user says 'loopprint doctor', 'is the install broken', or LoopPrint seems mis-installed (wizard won't trigger, a script errors, a clone looks partial), run scripts/loopprint-doctor.py to self-diagnose and repair.
LoopPrint — an interactive wizard that turns a vague goal into a complete, runnable loop blueprint (spec + state + external verifier + run script + safety checklist). Use when the user says 'design a loop', 'build a loop', 'new loop', 'loopprint', 'loop wizard', or hands over a vague recurring task they want to automate. Runs a Tier-0 decision gate (is this even a loop?), sharpens the goal with 3-5 questions, enforces the four atoms (Goal/State/Verifier/Stop), recommends a pattern (debug / spec-driven / performance / hybrid), and generates the full artifact package into loops/<slug>/. Say 'skip wizard' or 'direct run' to bypass the interview. If the user says 'loopprint doctor', 'is the install broken', or LoopPrint seems mis-installed (wizard won't trigger, a script errors, a clone looks partial), run scripts/loopprint-doctor.py to self-diagnose and repair.
license
MIT
LoopPrint — loop-design wizard
Turn a vague goal into a runnable loop blueprint: the four atoms made concrete, plus the artifacts to
execute and audit the loop. The job is to design the system, not to perform a persona.
When to use
"Design / build a loop for X", "new loop", "loopprint", "loop wizard".
The user hands over a recurring, automatable task and wants it set up properly.
Any time someone is about to point an autonomous agent at a task with no state, no gate, or no stop.
When NOT to use
A one-shot task with no recurrence → just do it well once (the Decision Gate will say so).
A purely conversational question → answer it.
Irreversible, judgment-heavy work (prod deploys, auth/payments, "is this good enough" calls) → these need a
human, not a loop. LoopPrint will flag them and recommend a human gate instead of autonomy.
Operating rules (read first)
This is a skill, not a mode. It does not require a banner on every reply, a confirmation phrase, or
language that it "governs all activity." Open with one activation line, then do the work.
The wizard is conversational and honest. If the goal fails the gate, say so plainly and stop.
Keep the user in control: never start an autonomous run without explicit approval at Step 6.
The wizard (six steps)
Step 0 — entry. Open with a single activation line, e.g. "🖨️ LoopPrint — let's blueprint this loop."
Invoked bare (/loopprint with no goal, or just "design a loop" / "loop wizard"): don't guess and don't
run the gate against nothing. Ask exactly one question first — "What's the recurring task you want to turn
into a loop?" — then proceed to Step 1 with the answer.
Goal already given (in this message or recent context): acknowledge it in one line and go straight to Step 1.
Step 0.5 — Resolve the binding (conform to this system)
Figure out how this environment wants loops wired, so the package fits the user's harness rather than generic
defaults. Run scripts/loopprint-detect.py (or read ./.loopprint/profile.yaml → ~/.loopprint/profile.yaml).
It yields a binding — state_dir, verifier.default, dispatch, marker_path, runner, banner — to use in
Steps 3 & 5. If nothing resolves, use generic defaults (loops/<slug>/, verify.sh) and say so; the core works
with no harness. Contract: references/profiles.md. Never hardcode a harness's
conventions here — always read them from the binding.
Step 1 — Decision Gate
Run the Tier-0 test in references/decision-gate.md: the 4 conditions + the
30-second checklist. Report Pass or Fail with one line of reasoning per condition. On Fail, recommend the
honest alternative (single high-quality pass, or a human-gated process) and stop unless the user overrides.
Step 2 — Goal Refinement
Ask 3–5 targeted questions (not more). Cover:
Sharpened goal — one sentence, testable. ("Done" must be checkable by a machine or a named reviewer.)
Recurrence / frequency — how often does this run? (Confirms the loop amortizes.)
Verification method — what external signal says an iteration succeeded? (test/build/lint/repro/rubric/reviewer)
Irreversible risks — what could this loop do that can't be undone? (→ becomes a human checkpoint)
Autonomy level — fully autonomous, checkpoint-gated, or dry-run only?
Step 3 — Primitive Enforcement
Force a concrete value for each atom. Do not proceed with any left vague:
Goal — the one-sentence objective from Step 2.
State — the durable artifact path from the resolved binding's state_dir (Step 0.5; generic default
loops/<slug>/state.md) and what it records: attempt log, what failed, current hypothesis, context.
Verifier — the exact external command or named reviewer. If the only proposed check is the same agent
self-assessing, reject it and find a real gate (this is the most common defect). Maker ≠ checker.
Stop — success criteria and a safety limit (max iterations, token/time budget, explicit halt). First to
hit wins. No loop ships without a safety limit.
MORTY — a specific bug to fix. Verifier = a reproduction test.
Spec-Driven Remediation — bring a system up to a (possibly reverse-engineered) spec. Verifier = derived tests.
Performance Optimization — make something faster/cheaper. Verifier = benchmark target + no regressions.
Hybrid — real work mixing the above. Verifier = composite gate.
Step 5 — Artifact Generation
Create loops/<slug>/ (slug = kebab-case of the goal) and write the package, filling the
templates/ with the Step 2–4 answers:
File
From template
Purpose
loop-spec.yaml
templates/loop-spec.yaml
The four atoms + pattern + budget, machine-readable
state.md
templates/state-template.md
The durable State artifact, human view (seed it with iteration 0)
maker.sh
templates/maker.sh
The maker step — a SEPARATE process from verify.sh (maker ≠ checker)
verify.sh
templates/verification-hook.sh
The external verifier as an exit-code gate
run-this-loop.sh
templates/run-this-loop.sh
Engine-agnostic runner; emits metrics.jsonl + state.jsonl each iteration
safety-checklist.md
templates/safety-checklist.md
Human checkpoints + budget guardrails
flow.mmd
templates/flow.mmd
Mermaid diagram of this loop
After generation: preflight with bash run-this-loop.sh --check; once the loop has run, loopprint-report.py loops/<slug>/metrics.jsonl reports cost-per-accepted-change; loopprint-skillify.py loops/<slug> (Step 6
"Save as skill") promotes a GREEN loop into a reusable skill. Pick a verifier from templates/verifier-library.yaml.
To see the health of every loop in the repo at a glance (rot radar), run loopprint-ls.py — it flags loops that
are ROTTEN (failing repeatedly) or STALE (stopped running); see references/rot-radar.md.
If a heavy orchestrator (e.g. glueRun-go) is in play, also emit templates/gluerun-snippet.yaml adapted.
Self-check (required): run scripts/loopprint-lint.py loops/<slug>/loop-spec.yaml. Do not present the
blueprint as ready until it prints GREEN. A RED means an empty or self-grading verifier, a missing safety limit,
or an unfilled placeholder — fix it and re-lint. Maker ≠ checker applies to LoopPrint's own output too.
Step 6 — Final Review
Show the tree of generated files and a 3-line summary (Goal / Verifier / Stop). Then offer, and wait:
Run now — execute run-this-loop.sh (respecting the autonomy level from Step 2).
Refine — adjust any atom/artifact and regenerate.
Export — adapt for glueRun-go / another orchestrator.
Save as skill — promote this loop into its own reusable skill.
Never auto-run; Step 6 is a stop-and-confirm.
Direct-run mode
If the user says "skip wizard" / "direct run", skip Steps 1–4's interview: read or accept an existing
loop-spec.yaml (or a one-paragraph goal), backfill any missing atom with a sensible default, call out
anything you defaulted, generate the package (Step 5), and stop at Step 6. Never silently invent a verifier —
if there's no external gate, say so and ask for one.
Repair / doctor
If LoopPrint itself seems broken or mis-installed — the wizard won't trigger, a script errors, a clone
looks partial, a symlink dangles after the repo moved — diagnose before anything else:
python3 scripts/loopprint-doctor.py # bottom-up health check; a copy-pasteable fix per problem
python3 scripts/loopprint-doctor.py --fix # also apply SAFE repairs (chmod +x, relink a dangling symlink)
python3 scripts/loopprint-doctor.py --json # machine-readable findings
Apply the safe fix: lines yourself; for anything that re-clones, edits user config, or deletes, confirm
with the user first (maker ≠ checker). It's a one-shot heal — re-run once to confirm no FAIL, then stop;
it is not a loop verifier, so don't iterate on it. Full symptom→cause→fix map (by install type):
references/troubleshooting.md.
Hard guards (always)
No verifier that the maker can satisfy by self-assessment. Find an external one or stop.
No loop without a safety limit. No autonomous run without Step 6 approval.
Irreversible actions become human checkpoints, never autonomous steps.
Log a state change + a verifier result every iteration; only a GREEN verifier permits "done".
