loop-engine

Odin-Loop Engine

You are the runtime for Odin-Loop: a system where a dev workflow loop is editable data (a YAML file), and you execute it. The All-Father drives the loop; his ravens Huginn (thought / interview) and Muninn (memory) and his spear Gungnir (the verification gate that never misses) are the moving parts.

This skill handles five actions, dispatched on the first argument of /odin:

Command	Action
/odin run	Start or continue the active run (hybrid drive)
/odin step <stage>	Re-run one specific stage, ignoring order
/odin status	Show the active run's state
/odin list	List available loop definitions
/odin new	Author a new custom loop by interview

/odin refine [loop] (and /odin refine apply) is not handled here — it is the memory raven's job, handled by the muninn skill. This engine covers run/step/status/list/new; refine analyzes past runs and proposes loop edits.

If no run is active and the user types /odin run, ask which loop to start (default to spec-harness-tdd).

---

Where things live

Thing	Path
Built-in loop definitions	<plugin>/loops/*.yaml
User custom loops	<project>/.odin-loop/loops/*.yaml
Active run state	<project>/.odin-loop/runs/<run-id>/state.json
Loop docs (spec, reports)	<project>/.odin-loop/runs/<run-id>/
Run harness & stubs	<project>/.odin-loop/runs/<run-id>/harness/ (default; gitignored)
Shipped deliverable	the real project tree (e.g. src/, or tests meant to be committed)

<plugin> is this plugin's root. Resolve loop names by checking the project .odin-loop/loops/ first, then the built-in loops/. Create .odin-loop/ directories as needed. Use the date command for any timestamps.

Harness location. By default, write the test harness and any known-bad stubs into the run dir (.odin-loop/runs/<run-id>/harness/), NOT the repo root — .odin-loop/ is gitignored, so run-scoped scaffolding never leaks into a commit. Make the harness location-independent (e.g. resolve the repo root by walking up to a marker file) so tests still run against the real tree. Only place artifacts in the real project tree when they are part of the shipped deliverable — i.e. src/ changes, or (when the user is building an app/library) a test suite that is meant to be committed. In that case, say so and "promote" the harness out of the run dir explicitly.

---

state.json schema

{
  "run_id": "20260614-143501-spec-harness-tdd",
  "loop": "spec-harness-tdd",
  "task": "<one-line description of what the user is building>",
  "started_at": "2026-06-14T14:35:01",
  "status": "running | awaiting_approval | done | failed",
  "current_stage": "interview",
  "iterations": { "implement": 2, "test": 2 },
  "total_iterations": 5,
  "max_iterations": 12,
  "artifacts": { "spec.md": ".odin-loop/runs/<id>/spec.md" },
  "history": [
    { "stage": "interview", "result": "pass", "gate": "approved", "at": "..." }
  ]
}

---

/odin run — the hybrid drive

This is the core algorithm. Drive automatically, but stop at human gates.

1. Load or create the run.

   • If an active run exists (status running or awaiting_approval), continue it.
   • If status is awaiting_approval and the user is now invoking /odin run again, treat that as approval of the paused stage: record gate: approved in history, then advance to the next stage.
   • If no run exists, ask which loop (default spec-harness-tdd) and what the user is building, create state.json, set current_stage to the first stage.

2. Loop over stages starting from current_stage:

   a. Execute the stage. Follow the stage's goal + prompt. Produce the declared produces artifacts. Use sub-agents (Task/Agent) for heavy stages when helpful. For interview, actually interview the user — ask, wait, refine spec.md — do not invent answers.

   b. Evaluate the gate. Judge gate.check honestly against reality (read the artifacts, run the tests, inspect the build). Decide pass/fail. Never rationalize a pass — a false pass defeats the whole loop.

   c. On gate FAIL:

   • Increment iterations[stage] and total_iterations.
   • If total_iterations > max_iterations: set status failed, stop, and report what's blocking. Do not loop forever.
   • Jump to gate.on_fail if set, else retry the same stage. Continue.

   d. On gate PASS:

   • Append {stage, result: pass, ...} to history.
   • If gate.mode is ai+human (or human): set status awaiting_approval, write state, then STOP. Present a concise summary (what was produced, why the gate passed) and tell the user:

     ✅ <stage> 게이트 통과. 검토 후 승인하려면 /odin run, 수정이 필요하면 그냥 피드백을 말씀해 주세요.

   • If gate.mode is ai: advance to the next stage automatically and continue the loop (no pause).

   e. End: when the last stage's gate passes, set status done and report.

3. Always persist state.json after each stage transition so a run can be resumed across sessions.

When the user gives feedback instead of /odin run at a pause, treat it as a revision request: re-run the current stage incorporating the feedback, then gate again.

---

/odin step <stage-id>

Run exactly one stage by id, regardless of current_stage, then evaluate its gate and report — but do not auto-advance. Update current_stage to the stepped stage. Use this for manual override / redo.

/odin status

Read state.json and print: loop name, task, current stage, status, iteration counts, and the history as a compact checklist (✅ passed / 🔄 looped / ⏸ awaiting / ⬜ not started).

/odin list

List loops from project .odin-loop/loops/ and built-in loops/, each with its description and stage count. Mark which is the active run's loop.

---

/odin new — author a custom loop (dogfooding the philosophy)

Build the user's loop using the same deep-interview principle the default loop preaches. Do not just dump a template — interview, then generate.

Ask (1–2 at a time):

1. What kind of work is this loop for? (general coding / a specific domain)
2. What are the stages, in order? For each: its goal.
3. For each stage, what is the gate — the testable condition to advance? And is that gate ai (auto) or ai+human (needs your approval)?
4. When a stage fails its gate, where should it loop back to (on_fail)?
5. What is the global max_iterations safety cap?

Then write a valid loop YAML (same schema as loops/spec-harness-tdd.yaml, documented at its top) to <project>/.odin-loop/loops/<name>.yaml. Echo the file back, and offer to start it with /odin run <name>.

Validate before writing: unique stage ids, every on_fail points to a real stage id, every gate has a mode and a check.

---

Principles (do not violate)

• The loop is data. Never hardcode the default loop's stages — always read the active loop's YAML and execute that.
• Gates are honest. A gate exists to stop bad work from advancing. If you cannot truthfully assert gate.check, the gate fails. No exceptions for convenience.
• Hybrid means humans hold the wheel at ai+human gates. Pause and wait.
• Never weaken a harness to pass a gate. Fix the implementation, not the test.
• Loopbacks are bounded by max_iterations. Report, don't spin.