/lanes build and orchestrate

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill lanes   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill lanes   # Windows PowerShell

Needs: consult-plan, divide, handoff-auto, kanban-setup, meta-orchestrator, next, pair, progress-report, session-handoff, update-progress, implementer, manager, planner, verifier, the guard-git hook (installed with it).

What it does

Sets how many issues a meta-orchestrator run works on at once. It predicts which files each queued issue will touch, groups issues that share files into the same lane, proposes a lane count with a cost line, and on your yes writes the lanes into the run's scope.md.

When to use

• Starting a meta-orchestrator run: setup calls it when it reaches parallel:.
• "Run 3 at a time", "go faster", "more lanes" mid-run (/lanes increase).
• "Too many conflicts", "slow down", "fewer lanes" (/lanes decrease).
• Not for one task or a session without an orchestrator: there is no merge gate to keep parallel work safe, so it says so and offers to start a run.

How to invoke

/lanes <n> | increase | decrease

• /lanes 3: regroup the queue into 3 lanes.
• /lanes increase: usually one more lane. /lanes decrease: one fewer. Claude picks which lanes change and explains why.

Also model-invocable: meta-orchestrator's setup calls it for parallel:.

How it works

1. Checks for a run. No skilleddocs/orchestrator/scope.md → explains that lanes only exist inside a meta-orchestrator run and offers to start one.
2. Predicts file sets. For each queued issue:
   • paths named in the issue
   • its area labels (only when it names no paths)
   • a quick git grep for what it mentions
   • Guesses are flagged as uncertain.
3. Groups.
   • Issues whose file sets overlap share a lane, in queue order; the groups left are the independent streams.
   • Lanes get area names (site, hooks), not numbers.
4. Picks the count.
   • Ask for more lanes than there are independent streams, or more than 4, and it asks you first: it shows a best-guess grouping and the options. It never caps the count silently.
   • increase usually adds one by splitting the longest lane on file-disjoint issues.
   • decrease merges two colliding lanes, or folds the shortest into the nearest.
5. Proposes.
   • Lanes, their issues and areas, why, and a cost line ("3 lanes ≈ 3× tokens/hour, about the same per issue", plus a number when the ledger has token counts).
   • You can pin an issue to a lane, rename a lane, or move an issue before you say yes.
6. Writes. parallel: and a named lanes: map into scope.md, plus a ledger entry.
7. Takes effect at the orchestrator's next loop.
   • Running agents are never killed.
   • A removed lane finishes its current issue and its remaining issues move to other lanes.

Design principles

• Lanes are file-disjoint or they are one lane. Two agents editing one file in parallel produce a merge conflict the gate has to unpick; grouping by predicted files avoids it up front.
• Ask, don't cap. Past the number of independent streams, or past 4, more lanes mostly add idle or colliding agents; the skill says so and lets you choose.
• Changes are gentle. A new count applies at the next loop and never throws away in-flight work.

Tradeoffs

• Tokens and rate limits grow linearly. N lanes burn about N× tokens per hour and hit rate limits N× sooner; cost per issue stays about the same.
• Needs file-disjoint work. A queue where most issues touch the same few files has one real stream, however many lanes you ask for.
• Faster context fill. The orchestrator tracks every lane's agents and reports, so its context fills faster and it hands off to a fresh orchestrator sooner.
• The merge gate is serial. Every lane's work passes through one orchestrator's tests and merges; past about 3 lanes, lanes queue at the gate instead of going faster.

Shared context for these principles: Matt Pocock's video.

Use cases

• A mixed backlog (site, hooks, docs) cleared three streams at a time.
• Dropping to one lane when two lanes keep colliding on a shared file.
• Adding a lane mid-run after a batch of new, unrelated issues lands.

Tips

• Area labels on issues make the predictions much sharper; unlabeled issues with no named paths are flagged uncertain.
• Pin an issue you know touches a shared file to the lane that owns that file.
• New issues filed mid-run join a lane by the same overlap rule; the lane count only changes through /lanes.
• Start with 2 on a new repo, watch the ledger for conflicts, then /lanes increase.

Example

Three lanes from a mixed queue:

Asking for more lanes than the queue supports:

Mid-run, after two collisions:

Related

• Configures meta-orchestrator, whose setup calls it for parallel:.
• Each lane runs pair's worktree pattern with its own manager agent.
• session-bridge checks overlap between separate sessions, not lanes of one run.

Prereqs

A meta-orchestrator run (skilleddocs/orchestrator/scope.md); gh to read issues.

Sample workflows

• Run the backlog unattended
  you → lanes → you → meta-orchestrator → planner → manager → implementer → verifier → you → switch → remind → progress-report → you
  Install just this one: ./scripts/install-skills.sh --workflow unattended-backlog or .\scripts\install-skills.ps1 -Workflow unattended-backlog

Source

• lanes/SKILL.md
• lanes/README.md