Vibe Run

vibe-run

Purpose

Provide a continuous loop runner that repeats workflow selection until the dispatcher returns recommended_role == "stop" or a real blocker requires human input. The bar is operator-trust quality, not shallow completion.

Agent execution protocol

Each loop iteration follows this sequence:

1. Dispatch — call agentctl next (with --workflow if running a continuous workflow)
2. Fetch prompt — call prompt_catalog get using the recommended_prompt_id from step 1
3. Execute — perform the work described by the prompt body
4. Record — emit a LOOP_RESULT: {...} JSON line and record it via agentctl loop-result
5. Repeat — go to step 1; do not stop after one completed checkpoint, review pass, or

auto-advance. Stop only when recommended_role == "stop" or a real blocker must be surfaced to the user. Do not sign off weak, brittle, or placeholder behavior as success.

Operating contract

• $vibe-run is for end-to-end backlog execution, not one-checkpoint convenience.

When the user delegates ongoing work, keep looping through implement, review, consolidation, context_capture, and the next checkpoint selection until the dispatcher stops you.

• Returning a normal status update after one successful checkpoint is not a stop

condition for $vibe-run.

• A dirty worktree is not automatically a blocker. If unrelated files are dirty

only because of CRLF/line-ending churn or other mechanical noise, reconcile or stash them and continue.

Direct commands (from repo root)

# Step 1: dispatch
python3 .codex/skills/vibe-loop/scripts/agentctl.py --repo-root . --format json next --workflow 

# Step 2: fetch prompt body
python3 .codex/skills/vibe-prompts/scripts/prompt_catalog.py .codex/skills/vibe-prompts/resources/template_prompts.md get 

# Step 4: record loop result
python3 .codex/skills/vibe-loop/scripts/agentctl.py --repo-root . --format json loop-result --line "LOOP_RESULT: "

LOOP_RESULT required fields

{
  "loop": "",
  "result": "",
  "stage": "",
  "checkpoint": "",
  "status": "",
  "next_role_hint": "",
  "report": {
    "acceptance_matrix": [...],
    "top_findings": [
      {"impact": "MAJOR|MODERATE|MINOR", "title": "...", "evidence": "...", "action": "..."}
    ]
  }
}

Cold start handling

The dispatcher and workflow engine handle cold starts automatically:

• Missing .vibe/LOOP_RESULT.json → protocol is initialised on first next call
• Missing workflow_runtime.json entry → rotation starts at step 1
• No manual initialisation or seeding is needed

Requires-loop-result gate

If the dispatcher returns requires_loop_result: true, a previous loop's LOOP_RESULT has not been acknowledged. Record the pending result before calling next again.

Scripts

• scripts/vibe_run.py

Terminal and headless usage

# Interactive continuous mode (terminal)
python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --show-decision

# Non-interactive simulation (dry-run, no executor)
python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --non-interactive --simulate-loop-result --max-loops 10 --show-decision

# Headless executor mode (CI/agent automation)
python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --max-loops 10 --executor "python3 ./scripts/run_one_loop.py" --show-decision

# Continuous workflow (e.g. refactor)
python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --workflow continuous-refactor --show-decision

Notes

• Interactive mode prints one prompt body per loop, then waits for Enter so you

can execute that loop in your agent session before continuing.

• After each interactive loop, the runner asks for the emitted LOOP_RESULT: {...}

line and records it through agentctl loop-result before selecting the next loop.

• Interactive users should press on to the next dispatched loop after recording a

result; the session should not end just because one checkpoint reached IN_REVIEW, DONE, or auto-advanced.

• In executor mode, the command is run after each prompt and must print a

LOOP_RESULT: {...} line; the runner records it automatically.

• The runner stops automatically when agentctl returns recommended_role: stop.
• In non-interactive environments without an executor, use --simulate-loop-result

to auto-acknowledge LOOP_RESULT and keep cycling (dry-run semantics).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: brifl
• Source: brifl/coding-agent-orchestration
• License: MIT

Install and usage instructions live in the source repository linked above.