worktree-multiagent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Worktree Multiagent

The step-by-step run is `docs/multiagent-protocol.md`: follow it from top to
bottom. Parallelism in Compass is **decided in Plan** (the distribution map) and
**carried out in breakdown** (the worktree orchestration). This skill covers both
halves: how to decompose work correctly, and how to run and land the multiagent
orchestration
without the parallelism costing more than it saves.

## Orchestration - what runs when

| Orchestration | Subtasks | Setup | Who integrates |
|---|---|---|---|
| **Solo** | 1 | No worktree; current branch. Breakdown is a no-op. | The builder, trivially. |
| **Pair** | 2–3 | One worktree per subtask; one `builder` each; no separate orchestrator agent. | The session that owns the issue, as orchestrator. |
| **Multiagent** | 4+ | One worktree per subtask; one `builder` each; plus one `orchestrator`. | The orchestrator. |

The assessment's size and risk values set the default orchestration; the
distribution map sets the subtask count; the multiagent settings in `compass.yml` (or `.compass/config.yml` in a
project without one) and the routing-guardrail caps bound it.

## The critical-risk cap

The standing cap: **`critical` risk pins `max_worktrees` to 1.** A
critical change runs solo even on the full approach. This is deliberate - a multiagent buys
speed but carries coordination risk, and on a critical change the coordination
risk costs more than the speed saves. The full approach being heavy *and* solo is
not a contradiction; it is the cap working. With one subtask the
`distribution-map.md` is not needed; it is owed from two subtasks.

## Decomposing work into independent subtasks (Plan)

A subtask is a unit of work that can run start-to-finish without waiting on,
colliding with, or reaching into another subtask. Independence has two tests,
and both must hold:

1. **Disjoint code.** The subtasks touch non-overlapping files and interfaces.
2. **Disjoint scenarios.** The subtasks satisfy non-overlapping scenario groups
   from `acceptance-criteria.md`.

Independence is *determined*, not guessed - you derive it from the scenario
file and the technical plan. The scenario grouping done at the define stage
(the full approach's "group scenarios by independence") is the seed; the distribution
map is where you confirm it against the plan.

Practical decomposition heuristics:

- **Cut along boundaries the architecture already has** - module boundaries,
  service boundaries, layers. Cutting across one of them creates a shared
  surface and a guaranteed collision.
- **Shared surface = shared subtask, or sequenced subtasks.** If two units both
  need to change the same interface, either fold them into one subtask or
  sequence them (one lands, then the other branches from the result). Do not
  pretend they are parallel.
- **Pull shared foundations forward.** If three subtasks all need a new shared
  type or utility, that is a subtask-zero that lands first, not a thing three
  subtasks each invent.
- **Be honest about the count.** Four shaky subtasks are worse than two clean
  ones. The map records *what could be parallel* - if the honest answer is
  "less than it looks," that is the map's job to say.

## Git worktree mechanics

A git worktree is a second working directory backed by the same repository -
its own checked-out branch, its own files, sharing one `.git`. That isolation
is what lets a builder run a full red→green TDD cycle, including a failing
suite, without destabilizing siblings.

- `scripts/multiagent.sh` creates one worktree per subtask and prints the
  launch plan; it launches nothing. The orchestrator starts one `builder`
  agent per worktree. Only the `orchestrator` runs the script.
- `scripts/integrate.sh` merges the worktrees back together. Only the
  `orchestrator` runs it.
- A builder lives inside exactly one worktree for the life of the subtask.

## The orchestrator / builder protocol

**The orchestrator** writes no feature code. Its job is coordination, collision
detection, and integration:

- Hands each builder an assignment as a file: its worktree, its scenario group,
  its slice of the plan, written to
  `docs/compass/<created>-<slug>/subtasks/<id>/briefing.md`. The dispatch names
  the path; a paste has no bound on what it drags in.
- States the model and the budget for each dispatch, scaled to the work, and
  records every step with `compass issue subtask` - `add` at dispatch,
  `set` for the report, the review and the cost, `package` for the review
  diff. A cost over the budget becomes a finding.
- Batches small same-shape work - five renames, three one-line guards - into
  one dispatch rather than five subtasks of setup each.
- Monitors subtasks during implementation for convergence on shared surface - shared
  files, shared interfaces, a scenario whose implementation reaches outside its
  group.
- Intervenes *before* a collision: re-sequences subtasks, re-cuts a boundary, or
  escalates to a re-assess if the distribution map was wrong.
- Is the **only** agent permitted to make a cross-subtask change.

**A builder** owns its subtask and nothing else:

- Works only inside its assigned worktree. Never touches a sibling's.
- Routes every cross-subtask need through the orchestrator - "I need to change <!-- vocabulary-scan: allow - route is a verb here -->
  an interface another subtask owns" is an orchestrator message, never a reach
  across.
- Runs full TDD inside its worktree (see `tdd-discipline`).
- Spawns no subagents, and writes its report to `result.md` at its
  worktree root, uncommitted; the orchestrator copies it beside the brief.
  Not `report.md`: Claude Code tells a subagent not to write a file named
  like a report.

**A new worktree has no readiness record.** The record is per checkout. On a
project that runs `autonomy: autonomous`, the brief of any worktree that will
run `compass approach evaluate --write` tells it to run `compass readiness`
first, which can take up to five minutes; without a fresh record, assess
refuses the issue.

**Review frequency follows the assessed risk.** `trivial` and `contained`:
one review of the integrated result. `cross-cutting`: a review of each
subtask's package before integration, and one after. `critical`: the same,
with a second reviewer on each subtask. The reviewer answers acceptance and

From ayeo-io/compass, Apache-2.0.

More from ayeo-io/compass