Protocol

Roles

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.

Open, resume, or choose

start session and continue session begin the same way: your AI lists the open lanes. What happens next depends on what it finds.

No lane is open

start session opens a new one. continue session says there is nothing to resume and offers to start one.

One lane is open, or you're inside a lane's worktree

Your AI resumes that lane without asking. It opens a second lane only when you clearly ask for separate new work.

Two or more are open, and you didn't name one

Your AI doesn't guess. It shows each lane (what it's working on, when it opened, its branch or worktree, and the last line of its log) and asks which one to continue, or whether to open a new one.

You named a lane

continue session billing-plans resumes that lane. A name that isn't open stops and shows the list.

An open lane is a paused session, not a crash: resuming keeps its date and number. start-session with the id of a lane that is already open refuses and points you to continue-session.

Planning mode (optional)

Say planning mode before risky, unclear, or wide-reaching work, to agree on a plan before anything changes. Your AI reads the same context a builder does and may write the agreed scope, limits, and open questions into the lane’s wip.md.

Until you approve the plan, it doesn’t make broad code changes, record decisions, or finish the session note. If planning settles a real architectural choice, that decision is recorded before the build starts.

Answering a review

When the reviewer is done, say address review. Your AI reads the findings from the lane’s wip.md and handoff.md and treats them as advice, not orders. It sorts each one:

Accepted

Fixed as suggested.

Accepted, with a qualification

Fixed, but differently or only in part, and the AI says why.

Deferred

Real, but for later. It goes into the session note's next steps so it isn't lost.

Rejected

The AI pushes back with evidence: what the code does, an earlier decision, or the product plan.

It writes its answers back into the lane files, and the reviewer can take another pass. Close the lane once every finding is fixed or deferred on purpose.

Keeping docs current

Two prompt commands keep your architecture docs in step with the code. Most sessions need only the first.

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.

Session brief (opt-in)

When you turn the session brief on, each lane gets one more scratch file, brief.md. What a brief is, its limits, and why it’s off by default are on the Concepts page. Here is where it fits in a session and how to read it.

1. 1

   You open or resume a lane

   start-session writes the lane's brief.md right after it opens the lane. continue-session keeps a brief that is still current and rebuilds one that is missing or stale. Either way the command prints one Brief: line, and a brief that fails to build never stops the lane from opening.

2. 2

   Your AI reads it before planning

   The generated agent instructions tell it to read the brief, when there is one, after the latest session note and the lane's wip.md and handoff.md, and before it plans any work.

3. 3

   It keeps reading

   A brief is a starting point, not the whole answer, and it says so. A brief that picked anything opens with "Use this brief as a starting point, not the whole context": it shows cut excerpts and can miss the doc that matters most. It then names up to six of the task's words to search for beyond it. Your AI should open the follow-up reads, search for those words, and read the architecture docs and decisions the task actually needs.

4. 4

   It notes what it relied on (optional)

   The lane's wip.md has an optional ## Context used section for the docs and decisions the lane actually used, so you can see later whether the brief pointed the right way. brief.md is deleted with the other scratch files when the lane closes.

What the status means

The top of every brief says how much it managed to fit. Whatever it says, the follow-up reads still count.

complete

Everything the brief picked fit in it.

partial

Some lower-priority picks didn't fit. They are listed as follow-up reads.

incomplete

Something the brief treats as required didn't fit, or your memory couldn't be read (a mistake in the brief: settings, for example). The brief opens with "INCOMPLETE — read these before planning" and lists those reads. Read them first.

no-match

Nothing in your memory matched the task's distinctive words, so the brief holds only the lane's own details. When most of those words are new to your memory but the task's other words match something, the brief lists at most four nearby reads under "Nearby memory (shares task words only)". They share only the task's other words and are never presented as relevant. Either way, the brief names words to search for. A no-match doesn't prove your memory says nothing about the task, so your AI should still look.

stale

Not one of the statuses above but a separate check: brief --check reports it when something the brief was built from has changed since it was written (a doc, decision, or session note, the lane's handoff, or another open lane). Any change to your memory counts, so it happens often. continue-session rebuilds a stale brief while the setting is on, or run brief --write.

Your AI can also ask for a brief over MCP, with the opt-in get_brief tool, as a starting point for a task.

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.

# 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

vibecompass list-sessions

vibecompass continue-session
vibecompass continue-session billing-plans   # when several lanes are open

vibecompass switch-session billing-plans

Worktrees and ports

Two lanes that edit the same repo can trip over each other: one lane’s half-finished change shows up in the other’s tests. A worktree gives a lane its own checkout of the repo, on its own branch.

vibecompass start-session --id billing-plans \
  --working-on "Wire Stripe checkout into onboarding" \
  --branch feature/billing-plans --repo app --worktree

• Each repo you name gets its own checkout under worktrees/<lane-id>/<repo-id> in your workspace, on the lane’s branch. Without --worktree, --branch only creates the branch (or reuses it) in each repo you name.
• A marker file in the lane’s worktree folder ties it to the lane, so commands you run inside need no --root or --session.
• Every lane, with or without a worktree, gets its own port and temp folder. In a lane’s terminal, run eval "$(vibecompass lane-env)" before you start a dev server, so two lanes never fight over the same port. More on lane-env.
• When the lane closes, close-session removes its worktrees if they are clean. It never forces: a worktree with uncommitted changes, or one still in use, stays, with instructions. Branches are never deleted. Files Git ignores, such as .env, don’t count as changes and are deleted with a clean worktree, so copy them out first.
• Don’t delete a lane’s worktrees by hand. Let close-session do it.