vibe-run

vibe-run is a core component of the Vibe coding-agent ecosystem, designed to transform unstructured coding tasks into a disciplined, state-aware, and reproducible workflow. It serves as an orchestration layer that moves beyond simple one-shot prompt responses, enabling long-running autonomous operations. By utilizing a shared contract based on files within a .vibe/ directory—specifically STATE.md, PLAN.md, and CONTEXT.md—vibe-run allows multiple agent sessions to maintain continuity, recover from interruptions, and provide verifiable progress. It is intended for software engineers and developers looking to automate complex backlogs, multi-step refactors, and continuous documentation tasks without losing control over the agent's decision-making process.

• Orchestrates continuous agent loops by iteratively calling the dispatch engine (agentctl) and executing recommended prompts.

• Maintains persistent workspace state, ensuring that agents do not invent workflows but adhere to pre-defined, deterministic checkpoint sequences.

• Features robust error handling, where the runner stops only when a final 'stop' role is returned or a critical blocker is identified, ensuring operator-trust quality.

• Supports various operational modes including interactive terminal usage, non-interactive headless CI automation, and dry-run simulations.

• Standardizes output through mandatory LOOP_RESULT JSON structures, providing a clean audit trail and actionable feedback for the next loop iteration.

• The system relies on .vibe/ state files; ensure these are persisted in your version control if you wish to track workflow history across sessions.

• Use the provided scripts such as vibe_run.py for standard operations or the specific wrappers like continuous_refactor.py for domain-specific automation.

• Expected inputs include a properly initialized repository with .vibe/ metadata files and an accessible template_prompts.md catalog.

• The execution protocol follows a cycle: Dispatch, Fetch Prompt, Execute, Record Result, and Repeat; ensure that human intervention is provided when blocking issues arise in STATE.md.

• The runner handles mechanical noise like line-ending changes, but requires developers to manage manual state updates when specific blocking conditions are flagged as 'BLOCKED' in the status tracking files.