worktree-lane-orchestrator

name	worktree-lane-orchestrator
description	Use when a ticket will execute with parallel mutating lanes and needs explicit git worktree and branch isolation before multi-agent execution starts.

Worktree Lane Orchestrator

Use this skill after the seam is locked and the lane map exists, but before RED-first implementation begins.

This skill turns “target worktree/branch alignment” from an implied requirement into one explicit artifact.

Do not use this skill when:

• the ticket is staying single-lane in one clean checkout
• no mutating parallel lanes are planned
• the work is still broad enough that the lane map is unstable

Inputs to gather first

• ticket id
• ticket title or short seam slug
• base ref for the ticket start, defaulting to main
• lane map with lane names, owners, and file surfaces
• which lanes are mutating, runtime-booting, or read-only
• any reserved ports or env collisions that need lane isolation
• any serialized runtime resources, especially ui_automation_driver verification
• receipt destination

Start by reading:

• references/worktree-conventions.md
• the lane map produced by the parent workflow

Use the helper only when needed:

• plugins/ticket-swarm-workflow/scripts/ticket_worktree.py

Workflow

1. Confirm the base checkout is safe

• confirm the root checkout is on the intended base ref
• confirm the root checkout is clean before spawning mutating lane worktrees
• stop if the ticket is trying to start from a dirty root checkout without an explicit reason

The root checkout stays the operator and integration surface. Do not use it as a mutating lane workspace once parallel execution starts.

2. Create the integration worktree first

Create one integration branch and one integration worktree for the ticket.

Default convention:

• branch: ticket/<ticket-id>/integration
• path: .worktrees/<ticket-id>/integration

This is the only branch/worktree that should survive the lane fan-out by default.

3. Create lane worktrees only where they buy isolation

For each mutating lane, create a dedicated lane branch and lane worktree.

Default convention:

• branch: ticket/<ticket-id>/<lane-slug>
• path: .worktrees/<ticket-id>/<lane-slug>

Rules:

• mutating lanes always get their own worktree
• a review lane gets its own worktree only if it needs to boot the app, run code, or patch
• canon extraction and closeout lanes stay read-only and do not need dedicated worktrees
• if two lanes want the same file surface, do not create competing worktrees for that overlap; serialize the surface instead

4. Reserve runtime collisions up front

Record any lane-local runtime constraints in the worktree matrix:

• dev server ports
• debug ports
• output directories
• environment variables that must differ per lane
• exclusive runtime resources such as ui_automation_driver verification

If two lanes would collide at runtime, stop and re-scope before implementation starts.

Rules:

• installs, tests, builds, and local runtime commands for a ticket run from that ticket's worktree
• ui_automation_driver verification is serialized even when tickets otherwise execute in parallel
• if multiple tickets need ui_automation_driver proof, queue those verifier lanes instead of running them together

5. Emit the worktree matrix receipt

Produce one receipt that becomes a required input to multi-agent-workflow.

The worktree matrix must include:

• root checkout path and current branch
• integration worktree path and branch
• one row per lane with:
  • lane name
  • owner
  • lane type: mutating / runtime review / read-only
  • branch
  • worktree path if any
  • owned file surfaces
  • reserved ports or env notes
  • serialized runtime notes, if any
• unresolved collisions or serialization notes

Default output

• one integration worktree
• zero or more lane worktrees
• one worktree matrix receipt

Close rule

This skill is complete only when:

• every mutating lane has a dedicated branch/worktree or an explicit serialization note
• the root checkout is no longer carrying mutating lane work
• the worktree matrix receipt exists