# Drive Fleet - Orchestration

The manager loop for Phase 2. The main loop is a MANAGER: it polls CI, dispatches subagents, tracks tasks, retargets/closes MRs, and triggers CI jobs. It NEVER mutates a working tree - no edits, reviews, rebases, or conflict resolution. All of that is delegated to background subagents, each in its own git worktree.

## Authorization model

Setting the `/goal` is a one-time human decision. It pre-authorizes the in-scope downstream work, with no per-MR checkpoint:

- **Hands-off.** Open MRs via `/mr`, auto-fix red, retry infra-flake jobs, rebase, and apply review fixes within the plan's lanes - no per-action approval.
- **Always hard-stop and escalate (never plow ahead) on:**
  - a plan-invalidating conflict (e.g. `main` diverged and broke file-isolation)
  - a structural CI failure (the same issue fails 3x - per `/ci`)
  - the outward `post_completion_action`

## The loop

1. **Build lanes in parallel.** Each lane runs `/build`'s Slice Loop. One subagent per lane, each in its own git worktree, file-isolated, <=4-5 concurrent. Route by domain: Frontend Staff Engineer / Backend Staff Engineer (Agent `subagent_type`, `isolation: "worktree"`). Sequential sub-tickets that share files stay inside ONE agent.
2. **Open MRs.** Once lanes are pushed, open MRs via `/mr` - conventional commits, no co-author trailers, stacked-MR dependencies and retargeting.
3. **Poll CI in the background.** One Monitor per branch via `/ci` (emits only on status change, zero cost while running). React on Monitor notifications and agent-completion events - never block the manager turn polling.
4. **Per red MR - fix subagent.** Spawn a domain-expert subagent in that lane's worktree to diagnose and fix. Infra-flake or clearly-unrelated failure -> retry the job (`glab ci retry` / `gh run rerun`); real failure -> fix and push. Same issue 3x -> escalate to the user.
5. **Per green MR - review subagent.** Spawn a PR Reviewer subagent that applies `/review-pr` and fixes blockers + majors + one-line fixes in the worktree. Reviewer comments on the MR go through `/pr-comments`.
6. **Update + retarget.** Per branch, a subagent runs `gh pr update-branch` (GitLab: `glab mr rebase`), resolving conflicts with a merge commit. Never force-push; escalate if only a rebase would do. Retarget stacked MRs to `{target_branch}` as their bases merge.
7. **Close out.** When the WHOLE fleet meets the condition simultaneously, run the `post_completion_action` (if any) on each MR. Only then does the `/goal` clear.

## Guardrails - never violate

- **Manager-only.** The main loop never edits, reviews, rebases, or resolves conflicts. It polls CI, dispatches agents, tracks tasks, retargets/closes MRs, and triggers CI jobs - nothing that mutates a working tree.
- **One worktree per lane per repo.** Never two concurrent agents in the same worktree. Sequential file-sharing sub-tickets stay in one agent.
- **CI polling is backgrounded.** Pollers run as Monitors (per `/ci`), not in the manager turn. React on agent-completion and pipeline-terminal events.
- **Surface genuine conflicts.** If `main` diverges mid-session and invalidates the plan, stop and re-plan the affected MRs with the user. Do not plow ahead.
- **Hold the post-action.** Trigger `post_completion_action` only when the full condition holds across the whole fleet.
- **Cross-repo worktrees are manual.** When lanes span sibling repos under a non-git parent (e.g. `~/code/<project>/` holding several repos), there is no repo at the parent - manage each repo's worktrees individually (see `/worktree`).

## Per-repo block (fill in before running)

| Field | Example |
| --- | --- |
| `target_branch` | the repo's default branch, e.g. `main` |
| verification cmd | `npm run lint:fix && npm run typecheck && npm test && npm run build` |
| CI tool | glab / gh (auto-detected by `/ci`) |
| `post_completion_action` | trigger the `notify_reviewers` job / none |
| worktree root | per repo; the parent dir is NOT a git repo for multi-repo work |

---
name: drive-fleet
description: "Drives a fleet of MRs/PRs to done with a manager loop plus the built-in /goal command, delegating all edit, review, rebase, and conflict work to worktree-isolated domain-expert subagents. Use when the user says 'drive fleet' or 'drive the fleet', has 2+ independent lanes to drive in parallel, or wants a hands-off manager that stops only when the whole fleet is green, reviewed, and rebased."
---

# Drive Fleet

A two-phase workflow for driving a fleet of MRs/PRs to done in parallel with a manager that never touches a working tree. Platform-neutral: all VCS/CI mechanics delegate to `/mr` and `/ci`.

## When to use

**why-no-hook:** skill workflow guidance; each step requires understanding the surrounding context (repo, task shape, prior state).

- 2+ independent lanes / multiple MRs, often across sibling repos `(review-time: see section note)`
- You want a hands-off MANAGER that delegates every edit and only stops when the whole fleet is done `(review-time: see section note)`
- Not for single-MR work - use `/build` + `/mr` directly `(review-time: see section note)`

## The goal condition

The built-in `/goal` command keeps the session working across turns until the condition holds, then auto-clears. Set it once, in the MANAGER session - it is session-scoped and resets on resume, so a re-planned session re-sets it.

Template (fill the `{knobs}`):

> Every open MR/PR from `{plan}` is CI-green, reviewed (`{review_depth}` applied via review-pr), rebased on `{target_branch}`, and passes every automated spec criterion at HEAD. `{post_completion_action}`

| Knob | Default |
| --- | --- |
| `target_branch` | `main` |
| `review_depth` | blockers + majors + one-line fixes |
| `post_completion_action` | none (repo-specific; e.g. "Once all hold simultaneously, trigger the `notify_reviewers` job on each") |

## Phase 1 - Plan via grills

1. Run `/grill-with-docs` to pressure-test the approach against the existing domain model, sharpen terminology, and emit CONTEXT.md terms inline. `(review-time: see section note)`
2. Output: an execution plan in `.claude/state/plans/` that defines the lanes / MRs and **proves they are file-isolated** - no two lanes touch the same file. `(review-time: see section note)`

The plan is the contract. Approving it and setting the `/goal` is your batched authorization for the fleet (see [orchestration.md](orchestration.md)).

## Phase 2 - Drive with /goal (manager-only)

Phase 2 is started by **you, the operator** - the agent cannot open its own session or set its own goal:

1. Open a **fresh** Claude Code session. The plan on disk is the whole handoff; nothing from the grill carries over. This boundary is also a deliberate gate - a long autonomous run should not start as a side effect of planning. `(review-time: see section note)`
2. Type `/goal <condition>` (built into Claude Code). With auto mode on, `/goal` is what keeps the **one** manager session working turn after turn until the fleet meets the condition, then auto-clears. `(review-time: see section note)`
3. Invoke this skill and run the manager loop (see [orchestration.md](orchestration.md)). `(review-time: see section note)`

This stays a **single, thin manager session** the whole time - it never spawns nested sessions. Its context stays small because all editing / review / rebase / conflict work goes to subagents (each with its own context window) and worktrees; the harness compacts the manager's context as it grows. The main loop manages and nothing else - it never edits, reviews, rebases, or resolves conflicts.

> If this skill is invoked with no `/goal` set, stop and ask the operator to set one (ideally in a fresh session) before running the loop.

## Example - a fleet spanning three repos

**Phase 1** (planning session) - describe the work; the agent grills and plans:

```text
/drive-fleet
Add a feature-flag system end-to-end: the evaluation service in the api repo,
the React hook + toggle UI in the web repo, and the shared flag schema in the
shared-types repo. Plan file-isolated lanes across the three repos.
```

The agent runs `/grill-with-docs`, proves the lanes share no files, writes the plan to `.claude/state/plans/`, and hands back the `/goal` line to use next.

**Phase 2** (fresh session) - set the goal, turn on auto mode, start the loop:

```text
/goal Every open MR/PR from the feature-flags plan is CI-green, reviewed
(blockers + majors + one-line fixes via review-pr), and rebased on main.
```

```text
/drive-fleet
Execute the plan at .claude/state/plans/2026-06-02-feature-flags.md
```

The manager builds the three lanes in parallel worktrees, opens the MRs, then drives CI-fix / review / rebase per repo until the goal clears. Your only input after that is any escalation.

## Details

Manager orchestration loop, authorization model, guardrails, and the per-repo block: see [orchestration.md](orchestration.md).

## Delegates to

`/grill-with-docs`, `/mr`, `/ci`, `/pr-comments`, `/review-pr`, `/worktree`; agent personas Frontend Staff Engineer, Backend Staff Engineer, and PR Reviewer (via Agent `subagent_type`).