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 <prompt_id> 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)

bash
1# Step 1: dispatch
2python3 .codex/skills/vibe-loop/scripts/agentctl.py --repo-root . --format json next --workflow <workflow-name>
3
4# Step 2: fetch prompt body
5python3 .codex/skills/vibe-prompts/scripts/prompt_catalog.py .codex/skills/vibe-prompts/resources/template_prompts.md get <recommended_prompt_id>
6
7# Step 4: record loop result
8python3 .codex/skills/vibe-loop/scripts/agentctl.py --repo-root . --format json loop-result --line "LOOP_RESULT: <json>"

LOOP_RESULT required fields

json
1{
2  "loop": "<loop_name>",
3  "result": "<outcome>",
4  "stage": "<current_stage>",
5  "checkpoint": "<current_checkpoint>",
6  "status": "<current_status>",
7  "next_role_hint": "<hint>",
8  "report": {
9    "acceptance_matrix": [...],
10    "top_findings": [
11      {"impact": "MAJOR|MODERATE|MINOR", "title": "...", "evidence": "...", "action": "..."}
12    ]
13  }
14}

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

bash
1# Interactive continuous mode (terminal)
2python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --show-decision
3
4# Non-interactive simulation (dry-run, no executor)
5python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --non-interactive --simulate-loop-result --max-loops 10 --show-decision
6
7# Headless executor mode (CI/agent automation)
8python3 .codex/skills/vibe-run/scripts/vibe_run.py --repo-root . --max-loops 10 --executor "python3 ./scripts/run_one_loop.py" --show-decision
9
10# Continuous workflow (e.g. refactor)
11python3 .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).