Dotfiles

Appearance

ADR 0001: Agentic Vibe Workflow ​

Status: superseded Last reviewed: 2026-06-20 Superseded by: DECISIONS.md#retired-vibe-workflow Accepted: 2026-05-21

This ADR is a historical record. The current repo no longer owns Vibe Core, just vibe, .vibe/ workflow state, or a repo-local autonomous workflow runner.

Context ​

The repo needs a durable autonomous development workflow so future sessions do not rediscover process, queue state, and validation rules from scratch.

Decision ​

Use just vibe as the local workflow entrypoint. It runs a deterministic orchestrator that inspects Git state, previous run state, mandatory GitHub Issues, and decision-needed items, then generates the next bounded prompt from current repository state and invokes Codex non-interactively through the ultra profile. The planner phase adds read-only/no-approval behavior with explicit CLI flags and config overrides; the implementation phase uses danger-full-access sandbox mode. Plan-only operation remains available through just vibe-plan and --plan-only.

Consequences ​

  • Root NEXT_PROMPT.md is not workflow state and is ignored.
  • .vibe/runs/ and .vibe/state/current.json hold generated local run state, including an ignored per-run NEXT_PROMPT.md audit copy.
  • GitHub Issues are the mandatory durable queue. ADR 0006 records the low-gate Personal Vibe Core doctrine that supersedes the earlier fallback posture.
  • The first orchestrator can be Python and may later move into ShellKit.
  • just vibe defaults to executing the selected bounded Codex role.
  • Validated workflow work is expected to commit and push before the run ends.
  • just vibe-plan keeps prompt-only planning available for inspection.
  • Final run summaries end with either Next command: for the next autonomous command or Human action required before next run: for concrete blockers and decisions.

Alternatives considered ​

  • Continue using TODO.md only. This keeps low ceremony, but it does not carry enough structured state for autonomous planning, parallel work, or issue review.
  • Put the workflow directly into Rust immediately. That delays the workflow bootstrap without improving the first session's result.

Follow-up work ​

  • Move the orchestrator into ShellKit when the CLI exists.
  • Add finish-session automation for issue state updates and validation summaries.