VibeCompass/docs
HomeSign in

Session workflow · Protocol

Protocol

When two AI tools work on the same project, one builds and one reviews. This page is the playbook: who does what, where the conversation lives on disk, and how to run more than one workstream at the same time.

You can use VibeCompass solo without any of this. Come back when you want a second pair of (AI) eyes on the work.

Roles

What is a lane?

A lane is one workstream: a named slice of work you (and your AI) are focused on right now, like auth-flow or billing-plans. While a lane is open, it has its own small folder under sessions/active/<lane-id>/ holding the in-progress scratch files. When you close the lane, those scratch files get folded into one permanent note and deleted.

You usually have one lane open. You can have more — see “Multiple lanes” below.

How the handoff works
Builder and reviewer handoff flowThe builder AI writes into the lane folder, which holds wip.md, handoff.md, and session.yaml. The reviewer AI reads from the same folder, then writes findings back into it. The builder reads the findings and either accepts, rejects, or defers each one. When the builder closes the lane, the scratch files become a permanent finalized session note.writes log + handoffreviewer readswrites findingsbuilder respondsclose-sessionai roleBuilderwrites code,owns the lane lifecycleai roleReviewerread-only second pass,writes findings to diskthe lane foldersessions/active/<lane-id>/wip.mdhandoff.mdsession.yamlwhat gets keptFinalized session notesessions/YYYY-MM-DD-N-title.mdscratch files are deleted

Each lane has one builder and (optionally) one reviewer. The builder drives the work; the reviewer runs a separate read-only pass and writes findings back into the lane. The handoff is a file, not a message — so either side can pick up cold.

Builder

The AI that is actually writing code right now. Owns the whole session — opening it, working in it, closing it.

  • Opens a lane with vibecompass start-session --id <lane-id> or picks one that guided init already created.
  • Says start session to the coding tool so it switches into builder mode.
  • Reads the latest session note, any open scratch files, repo instructions, and relevant architecture docs before coding.
  • Keeps sessions/active/<lane-id>/wip.md and handoff.md up to date and owns the "Current session" marker in CLAUDE.md.
  • Says address review to read the reviewer's notes, respond inline, and keep going.
  • Says close session (or end session) when done, then runs vibecompass close-session --session <lane-id> to finalize and optionally publish.

Reviewer

A second AI that checks the work in a separate pass. Reads only — does not change code. Writes findings back into the lane files for the builder to address.

  • Joins by saying join as reviewer. The reviewer never starts or closes a lane.
  • Says review handoff to actually run a review pass against the latest scratch files and any new diffs.
  • Reads the latest finalized session note, the lane's wip.md and handoff.md, and the relevant diffs before reviewing.
  • Appends findings into the lane's wip.md review log and refreshes the reviewer half of handoff.md.
  • Stops once wip.md and handoff.md are updated — there is no separate "exit reviewer" step.
  • Focuses on bugs, regressions, risk, and missing tests; doesn't restate the whole change.
  • Does not touch the "Current session" marker or the finalized note — those belong to the builder.

Files the session uses

Two kinds of files: ones that stick around (repo instructions and finalized notes) and ones that exist only while the lane is open (the scratch files). Here is what each is for.

File
Purpose
AGENTS.md
Long-lived instructions for the repo, especially for tools (like Codex) that read AGENTS files first.
CLAUDE.md
Long-lived: the "Current session" marker, recovery rules, and the builder/reviewer protocol.
sessions/active/<lane-id>/wip.md
Lives only while the lane is open. Builder's running log, requests for reviewer input, and the review log.
sessions/active/<lane-id>/handoff.md
Lives only while the lane is open. The baton-pass file between builder and reviewer — keeps you from having to relay context by hand.
sessions/YYYY-MM-DD-N-title.md
Long-lived: the permanent session note written when the lane closes. Lists completions, decisions, blockers, and what the next session should pick up.

Multiple lanes

Most of the time you have one lane open and that’s plenty. But when two unrelated things are in flight — say, a feature and a bug fix that don’t share files — you can run them as separate lanes so their scratch files don’t collide.

Working in multiple lanes

Each lane is an independent workstream. Only the scratch files (wip.md, handoff.md, session.yaml) live under sessions/active/<lane-id>/. Decisions and finalized session notes stay global, so a decision allocated in one lane is visible to every other lane immediately.

When to open a second lane

  • Two unrelated features that don’t share files, such as auth-flow and billing-plans.
  • A long-running review pass on lane A while you keep coding on lane B.
  • A planning or design lane that does not touch code yet but needs its own scratchpad.

Declare what each lane owns

The optional --feature, --repo, and --claim flags let the package warn when a sibling lane overlaps on the same feature, repo, or path.

# Lane A: auth surface
vibecompass start-session --id auth-flow \
  --working-on "Tighten the GitHub OAuth callback" \
  --feature auth --repo app --claim app:src/app/auth

# Lane B: billing surface, no overlap
vibecompass start-session --id billing-plans \
  --working-on "Wire Stripe checkout into onboarding" \
  --feature billing-plans --repo app --claim app:src/app/billing

See active lanes

Use list-sessions when you need to see every open lane and which one is current before a builder or reviewer resumes.

vibecompass list-sessions

Change the current lane

Only one lane is current at a time. That is the one whose context the AI loads through CLAUDE.md and the rest of the generated agent files. Use switch-session to swap; generated agent files are rewritten from the selected lane’s metadata so the next AI session resumes in the right place.

vibecompass switch-session billing-plans

When you close-session a lane while siblings are still active, the current-lane pointer moves to one of the survivors instead of going blank.

Keep going

In practice: set up the notebook with init, open a builder lane with start-session --id, pick a role with start session or join as reviewer, loop through review handbacks until the work is done, then close the lane once the last finding is resolved or explicitly deferred.

CLI commandsSession workflow