Personal Vibe Core Target

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

This page is historical context for the retired Vibe workflow. It does not describe current repo direction and should not be used as an implementation blueprint for this dotfiles repo.

Personal Vibe Core was the portable autonomous development workflow this repo incubated through just vibe. It was for trusted personal repositories where the right default was momentum with receipts, not approval-heavy process.

Doctrine

1. Common sense over procedure.
2. Act by default.
3. Stop hard, do not limp.
4. One source of truth.
5. Autonomy with receipts.
6. Low gates.
7. Operational stops are cheap and correct.
8. No compatibility soup.
9. Planner thinks, orchestrator decides, worker executes.
10. Delivery mode is explicit.
11. Parallelism requires isolation.
12. Validation is part of done.

Core contract

just vibe is the public command. A repo that adopts Vibe Core provides:

• a just vibe entrypoint;
• .vibe/runs/<UTC timestamp>/ for per-run prompts, logs, and state;
• .vibe/state/current.json for latest local state;
• .vibe/schemas/ for structured planner and worker contracts;
• GitHub Issues as the mandatory durable queue;
• ADRs for accepted durable decisions;
• a repo-specific policy overlay for protected surfaces and validation.

GitHub is required. Missing gh, broken auth, missing GitHub remote, failed issue reads, or missing labels block the run. Vibe must not fall back to local markdown queues or root prompt batons.

Implementation runtime

Issue #46 adopted Bun-first TypeScript as the Vibe Core implementation direction after the Bun runner, native Windows, and mutation-executor spikes. Bun is therefore a required Vibe Core development and execution tool on the repo's supported lanes: native Windows, Ubuntu WSL, and CachyOS. The shared mise inventory owns that Bun installation.

This does not make Bun the default runtime for unrelated dotfiles workflows. Node and pnpm remain managed for the docs site, npm-distributed CLIs, and ordinary JavaScript/TypeScript projects that declare them. The active Vibe runner is .vibe/src/cli.ts; the previous Python runner has been removed.

Roles

The target split is:

Claude planner/reviewer/strategist
  - read-only planning
  - deep review
  - issue capture
  - decision briefs
  - council turns

Codex worker/fixup implementer
  - code changes
  - tests
  - focused refactors
  - validation repair

Deterministic orchestrator
  - state gathering
  - mode routing
  - structured-output validation
  - worktree/sandbox setup
  - Git and GitHub mutations
  - final report validation

The configured per-mode role profile is a hard dependency. Routine implementation planning defaults to Codex, while review, policy, council, and strategy paths can prefer Claude where their selected profiles say so. Explicit forced backend overrides block when that backend cannot run and do not silently fall back. Automatic fallback is profile-scoped: it happens only when the selected profile permits it, prints a disclaimer, and records both attempts in run state.

The starter orchestrator resolves planner/reviewer/strategist overrides from --planner-backend auto|claude|codex, --reviewer-backend auto|claude|codex, --strategist-backend auto|claude|codex, VIBE_PLANNER_BACKEND, VIBE_REVIEWER_BACKEND, and VIBE_STRATEGIST_BACKEND. --model-profile and VIBE_MODEL_PROFILE select the configured model tier. The Claude backend uses VIBE_CLAUDE_COMMAND or claude and runs Claude Code print mode with explicit model, effort, permission mode, read-only tools, --output-format json, --json-schema, explicit setting-source isolation, strict empty MCP config, disabled slash commands, and --no-session-persistence. Claude bare mode stays profile-controlled because enabling it changes auth behavior; the default keeps OAuth/keychain auth inherited deliberately. The Codex backend uses VIBE_CODEX_COMMAND or the managed Codex launcher and passes explicit model/provider/reasoning/verbosity, sandbox, approval, schema, output-path, ephemeral, ignored user-config/rules, strict-config, disabled feature, and empty MCP settings.

Modes

Core modes:

• review-current-state: dirty-tree review and finishing work.
• resume-or-repair: continue or repair an interrupted/failed run.
• human-decision: produce the smallest useful decision brief.
• triage: create/update GitHub Issues when no ready issue exists.
• strategic-self-review: review workflow direction and create issues.
• implement-next-task: work one ready issue end to end.
• parallel-implement: coordinate disjoint ready issues.
• finish-session: validate, update issues, commit, push, and summarize.
• deep-review: inspect broadly and create issues.
• policy-review: propose workflow/policy changes.
• council: run a mediated Claude/Codex architecture or roadmap dialogue.

Explicit issue selection is part of the command surface:

just vibe --issue 42
just vibe --review
just vibe --policy-review
just vibe --council

If a requested issue is not status:ready or status:decision-needed, the run blocks instead of choosing different work. Explicit review, policy-review, and council requests keep dirty-tree, resume/repair, and decision-needed routing as hard priority; after that, the requested non-implementation mode runs or the run fails instead of falling through to unrelated triage.

GitHub queue

Required labels:

status:ready
status:active
status:blocked
status:decision-needed
status:review
type:feature
type:bug
type:refactor
type:docs
type:chore
type:research
scope:runtime
scope:bootstrap
scope:windows
scope:wsl
scope:cachyos
scope:agent
scope:docs
risk:low
risk:medium
risk:high

Agents may autonomously create issues, update labels/comments, and close issues when policy and validation allow it. Durable decisions become status:decision-needed. Operational blockers become status:blocked unless they also imply a durable decision.

Delivery

Default delivery is direct commit/push to the current branch after validation. This is the first-class Personal Vibe Core lane.

A future branch/PR lane may be added for larger personal repos:

delivery = direct
delivery = pr

Delivery mode is explicit. Vibe must not silently switch from direct to PR or PR to direct when one path fails.

Release, deploy, publish, destructive Git, force-push, branch deletion, credential handling, and secret migration remain explicit-only operations.

Worker isolation

The target worker model uses isolated worktrees and the narrowest useful sandbox:

1. The orchestrator creates a worktree for the job.
2. The worker edits only inside that worktree.
3. The worker returns a validated structured result and requested mutations.
4. The orchestrator verifies the diff.
5. The orchestrator performs Git/GitHub mutations from the trusted control path.

Parallel work requires disjoint ownership and isolated worktrees. If isolation cannot be created, the run blocks or falls back to serial only when the user explicitly requested that mode.

The starter implementation keeps main as the default worker lane while the isolated path is proven. --worker-lane worktree, VIBE_WORKER_LANE=worktree, or just vibe-worktree opts into the first worktree-backed lane. The orchestrator creates a deterministic issue-scoped branch such as vibe/issue-21-20260522T010203Z and a repo-adjacent worktree such as ../dotfiles-vibe-worktrees/issue-21-20260522T010203Z; VIBE_WORKTREE_ROOT may override the root but must not point inside the main checkout. Worktree mode must never silently fall back to main if isolation fails.

Worktree worker output is still the same structured worker result. The orchestrator stores worker stdout/stderr logs and the canonical worker result in the main run directory, captures worktree git status --short, git diff --stat, git diff --binary, untracked files, and validation records, then integrates reported changed files into the control checkout only after a valid done result with passed validation requests a Git commit. Git and GitHub mutations remain orchestrator-owned. Failed, interrupted, invalid, or non-integrated worktrees are preserved for inspection; successful worktrees are marked safe for future explicit pruning rather than deleted automatically.

Structured contracts

Planner output must be structured JSON. Worker output is structured JSON with:

• status;
• changed files;
• validation commands, intent, coverage, and results;
• acceptance evidence mapping issue criteria or desired outcomes to concrete evidence and recorded validation commands;
• requested Git commit message;
• requested GitHub issue updates;
• blockers;
• follow-up issue drafts.

The worker result schema lives at .vibe/schemas/vibe-worker-result.schema.json. The orchestrator validates the schema-shaped result before accepting a worker run and before Git or GitHub mutation execution. Done results require passed required validation and complete acceptance evidence. Reviewer receipts separately record whether the worker says the task is done, required validation passed, acceptance evidence is complete, and read-only verification confirms the result. Mutation requests are structured data, not prose instructions. In the direct delivery lane, the orchestrator stages only requested safe repo paths, runs git diff --cached --check, commits, pushes, and verifies remote success if a push reports a local tracking-ref update failure. GitHub mutations are limited to gh issue comments, label add/remove, closure, and issue creation, with label existence checked before mutation.

Failure handling

Hard failures produce Status: blocked or Status: partial with the exact next human action. Examples:

• gh auth status fails;
• required labels are missing;
• configured planner or worker cannot run;
• worktree creation fails;
• validation cannot run;
• the worker returns invalid JSON;
• the worker requests a mutation from an invalid or unsafe result;
• a requested Git or GitHub mutation fails;
• push fails and remote verification cannot prove success.

Do not replace required validation with weaker checks and call the run done.

Dotfiles overlay

This repo's overlay adds:

• ShellKit runtime coordinator first;
• the managed shell contract;
• two binaries: shellkit and shellkit-shim;
• lanes: Windows, Ubuntu WSL, and CachyOS;
• profiles: desktop and headless;
• chezmoi source editing under home/;
• source-only smoke validation across fixture profiles;
• local secrets/auth/session/history exclusions.

These are repo-specific constraints. They are not required for Vibe Core in other personal repos.

Implementation path

1. Record doctrine and mandatory GitHub policy.
2. Require GitHub setup and labels in the runner.
3. Add explicit issue selection.
4. Add vibe doctor.
5. Add Claude planner/reviewer backend.
6. Add structured worker result schema and validation.
7. Move Git/GitHub mutation requests from worker JSON into orchestrator-owned structured execution. (Implemented in the Bun runner.)
8. Add worktree worker execution.
9. Add review/fixup loop.
10. Add deep-review, policy-review, and council modes.
11. Define the optional branch/PR delivery lane.
12. Export a Vibe Core bootstrap template for other repos.