Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Plan: Vibe-Loop Supervisor Pilot

Overview

Pilot an external vibe-loop supervisor for capOS without moving capOS workflow authority into the generic supervisor. capOS remains the source of truth for milestone selection, worktree policy, review gates, hazard trailers, QEMU evidence, and mainline integration discipline. Generic supervisor code should learn through configuration, command-backed task sources, and read-only diagnostics, not hard-coded capOS workflow rules.

This is normal-priority workflow/tooling work. It does not replace the selected Device Driver Foundation milestone and must not jump ahead of open REVIEW_FINDINGS.md remediation governed by WORKPLAN.md. Run single-worker only until task-source discovery, workspace ownership checks, and conflict-domain mapping are mechanically validated.

Conflict Surface

Owned by this plan:

  • tools/vibe-loop-capos-tasks plus narrow tests or fixtures for that command
  • .vibe-loop.toml, if added, and .vibe-loop/ runtime state, kept untracked
  • WORKPLAN.md, docs/SUMMARY.md, docs/plans/README.md, and this plan
  • CLAUDE.md, REVIEW.md, and tools/check-workflow-hygiene.sh only after the pilot proves a hook should become mandatory

Do not touch from this plan:

  • Kernel, scheduler, runtime capability behavior, or selected-milestone authority
  • schema/capos.capnp or checked-in generated bindings under tools/generated/
  • QEMU behavior smoke scripts, except read-only pilot evidence capture, or active plan task bodies outside narrow task-source references

Validation Commands

  • git diff --check
  • make workflow-check
  • make docs
  • tools/vibe-loop-capos-tasks --json after the adapter exists
  • vibe-loop doctor --repo . and vibe-loop tasks list --repo . after config exists

Success Criteria

The pilot is successful when capOS exposes selected-milestone work, relevant ad-hoc tasks, and REVIEW_FINDINGS.md remediation through a stable task-source adapter; workspace diagnostics catch mismatched or foreign-dirty branch/worktree state before edits or final integration; and one supervised slice completes without changing capOS branch, review, merge, or cleanup rules.

Task 1: Add the task-source adapter

  • Add tools/vibe-loop-capos-tasks to emit stable JSON tasks from WORKPLAN.md, selected/ad-hoc docs/plans/ files, and REVIEW_FINDINGS.md.
  • Preserve selected-milestone and review-finding priority from WORKPLAN.md, including non-blocked review findings before unrelated serial feature work.
  • Avoid reading every backlog by default; read only selected/ad-hoc plan files and review findings needed for dispatch.
  • Include resource and path conflict domains from docs/plans/README.md.
  • Validate with git diff --check, make workflow-check, make docs, and tools/vibe-loop-capos-tasks --json.

Task 2: Add repository-local supervisor config

  • Add .vibe-loop.toml only after the adapter contract is stable.
  • Configure Codex-only worker/selection commands for this repository.
  • Keep .vibe-loop/ untracked and leave branch/worktree creation, review, merge, and cleanup in capOS worker instructions.
  • Validate with vibe-loop doctor --repo ., vibe-loop tasks list --repo ., git diff --check, make workflow-check, and make docs.

Task 3: Add workspace-owner preflight

  • Stop before edits or final integration when task lock, branch, worktree path, ancestry, dirty state, or duplicate-branch state mismatches.
  • Treat unknown ownership as blocking for final integration; do not auto-delete, reset, steal, or merge another worker’s branch/worktree.
  • Record actionable diagnostics naming branch, worktree, base, HEAD, dirty state, and active lock owner when available.

Task 4: Run a single-worker pilot

  • Run vibe-loop doctor --repo . and resolve only diagnostics inside this plan’s conflict surface.
  • Run vibe-loop tasks list --repo . and confirm selected-milestone tasks, review findings, resources, and paths are ordered correctly.
  • Run exactly one supervised run-next slice before unattended loops.
  • Record whether the worker respected branch/worktree policy, review gates, workflow trailers, mainline integration discipline, and cleanup.
  • Do not enable run-until-done --jobs N until shared surfaces are serialized by explicit resource/path metadata.

Task 5: Promote proven hooks

  • Update CLAUDE.md, REVIEW.md, and tools/check-workflow-hygiene.sh only for supervisor hooks proven by the single-worker pilot.
  • Keep hooks narrow: they may enforce task-source, workspace-owner, or integration-lock evidence, but not centralize workspace creation/cleanup.
  • Update this plan and WORKPLAN.md with closeout evidence before marking the pilot complete.