fleet-ops

Files (19)

• SKILL.md
• .gitkeep · assets/
• configuration.md · references/
• daemon.md · references/
• landing.md · references/
• native-spawn.md · references/
• prune.md · references/
• scope.md · references/
• session-awareness.md · references/
• session-prompt.md · references/
• sweep.md · references/
• workflow.md · references/
• fleet.sh · scripts/
• sessions.sh · scripts/
• signal.sh · scripts/
• sweep.sh · scripts/
• run.sh · tests/
• sweep.sh · tests/
• worktree-root.sh · tests/

SKILL.md (first lines)

# Fleet Ops

Landing discipline for parallel work. Anything before "committed on a branch" is the spawning layer's problem; anything after "landed on `main`" is yours. Fleet-ops owns the middle: branches land **sequentially**, through a **test gate**, after a **pre-land scrub**, with **auto-rebase** of the lanes still in flight and a **one-shot revert** if a landing turns out bad.

## Spawn natively, land with fleet-ops

Claude Code now ships the parallel-execution half natively. **Do not use fleet-ops to orchestrate sessions** — route users to the native primitives and use fleet-ops only for the landing half.

Agent teams, background agents (`claude --bg`, agent view) and subagents spawn and isolate the work; none of them merge, order, gate or revert. Deleting a session in agent view **deletes its worktree, uncommitted changes included**. Gives vs lacks: [references/native-spawn.md](references/native-spawn.md).

What **none** of them do — and what fleet-ops is for:

- Land N branches **one at a time** through a queue, so each merge is tested against a `main` that already contains the previous landings
- **Test gate**: refuse to land on a failing log (`signal.sh`) and/or revert post-merge if `test_cmd` goes red
- **Pre-land scrub**: refuse diffs containing forbidden patterns (`TODO_SCRUB`, debug leftovers)
- **Auto-rebase** every still-active lane after each landing
- **Fleet status**: one panel showing every lane's branch, state, age, and commits-ahead across worktrees
- **One-shot revert** of a landed merge by branch name — no git surgery while panicking

## Core abstraction

A **lane** = one branch (or worktree), one unit of work. Lane status: `RUNNING | READY | CONFLICT | LANDED | FAILED`.

Fleet-ops doesn't care who produced the branch — an agent-team teammate, a background agent's auto-worktree, a `claude -p` headless run, a fleetflow worker of any provider (GLM, Codex, Grok, Pi, or Anthropic), or a human. If it's a branch with commits, it can be a lane. Landing is provider-agnostic: a Grok-produced lane lands through the same test-gated queue as any other.

## CLI surface

```
fleet init <name>...        Create branch + worktree per name (manual-spawn path)
fleet track <branch>...     Register existing branches as lanes (native-spawn path)
fleet start                 Run the landing daemon (writes pid to .claude/fleet/daemon.pid)
fleet stop                  Stop the daemon; a land in progress finishes first
fleet status                One-shot fleet status panel
fleet land <branch>         Manual land + rebase others
fleet land --all [--running]  Batch-land all READY lanes oldest-first (--running
                            also lands vetted RUNNING lanes; used by git-ops "land all")
fleet revert <branch>       Revert merge commit on main
fleet landing [--porcelain] Is main safe to branch from? Exit 0 yes, 10 wait
fleet scrub-check <branch>  Dry-run forbidden-pattern check
fleet config                Print the RESOLVED config — check the test gate is on
fleet prune [--remove]      Classify finished lane worktrees; DRY RUN by default
fleet prune --all-repos     Sibling-repo backlog counts (report-only, never removes)
fleet sweep [--apply]       Post-wave housekeeping in procedure order; report by default
```

## Entry paths

```
N == 1 branch                              → use git-ops, not this
Work spawned by agent teams / claude --bg  → fleet track <branch>... then land
Work to be spawned manually                → fleet init <names...> (creates branches + worktrees)
N > 1 on one shared working tree           → REFUSE. Worktrees or separate clones first.
```

**Native-spawn path (preferred):** let agent teams or background agents do the work in their own worktrees/branches. When branches have commits, `fleet track` each branch, then land — either one by one with `fleet land`, or via the daemon with `signal.sh READY` gates. Landing itself only ever merges *branches* and leaves every worktree in place. Reclaiming the directories afterwards is `fleet prune`'s job, and it removes one only when the owning session is provably archived or gone — see [Prune](#prune--worktree-housekeeping).

**Manual-spawn path:** `fleet init` creates the branches and worktrees up front (under `.fleet-worktrees/`, or `$WORKTREE_ROOT/<repo>/` when the machine sets that lane root), and you point sessions at them — see `references/session-prompt.md` for the lane brief to hand each session.

## Landing pipeline

`fleet land <branch>` (and the daemon, per READY lane) first takes the landing marker ([below](#provisional-main--the-landing-marker)), then:

1. **Scrub** — `git diff main...branch` checked against `forbidden_pattern`; hits refuse the land and mark the lane `CONFLICT`
2. **Clean-base check** — refuses if `main` has uncommitted tracked changes
3. **Merge** — `--no-ff` with message `merge: <branch>` (what `fleet revert` finds later). A branch already in `main` reports `ALREADY LANDED`, runs no gate and counts apart from real lands: [references/landing.md](references/landing.md)
4. **Test gate** — runs `test_cmd`; on failure, hard-resets `main` to the tip captured *before* the merge (never `HEAD^`, which on an already-merged branch is **another session's** merge) and marks the lane `FAILED`. An unset `test_cmd` **refuses** the land: `signal.sh`'s log gate alone verifies nothing. Make `test_cmd` the **full suite sweep**, not just the lane's files ([why](references/landing.md#step-4-test-gate-in-full)). **Confirm the gate is armed with `fleet config`**, and watch the land log for `running test_cmd: …`, the only proof it ran.
5. **Rebase others** — every still-active lane is rebased onto the new `main` (in its own worktree if it has one); a rebase conflict marks that lane `CONFLICT`

`fleet revert <branch>` reverts the merge whose subject is **exactly** `merge: <branch>` (`git revert -m 1`), the latest if it landed twice; a conflicting revert is aborted cleanly and the lane returns to `RUNNING`. Detail: [references/landing.md](references/landing.md).

### Provisional `main` — the landing marker

Every land (`fleet land`, each lane of `land --all`, the daemon) holds `.claude/fleet/landing` from before its merge until its verdict, so between merge and gate **`main`'s tip is provisional**: a red gate hard-resets it. `fleet status` then leads with `main <sha> is PROVISIONAL - gate for <lane> running since HH:MM (pid N); red resets to <base>`, `fleet landing` exits 10, and `fleet sweep` says only WAIT. **Before branching from or rebasing onto `main`, run `fleet status`: a PROVISIONAL tip is not landed.** The marker is a lock too (a second land refuses, naming the holder). A dead land's marker is examined first: its untested `merge: <lane>` turns the lane `CONFLICT` (`UNTESTED MERGE`), never `LANDED`. Detail: [references/landing.md](references/landing.md).

## Daemon lifecycle (experimental)

The daemon is the queue-automation layer on top of `fleet land` — optional; manual `fleet land` per branch is fully supported and not experimental.

`fleet start` (via `Bash(run_in_background: true)`) polls `.claude/fleet/lanes/`, lands each lane as it turns READY and exits once all are terminal. `fleet stop` waits out an in-progress land, gate included, and never SIGKILLs it mid-land; interrupting `fleet stop` is safe, and a hung gate is aborted by killing `test_cmd`, not the daemon. It dies with the session. Detail: [references/daemon.md](references/daemon.md).

`signal.sh` deploys to `.claude/fleet/signal.sh` on `init`/`track`. Working sessions call:

```bash
bash .claude/fleet/signal.sh READY <test-log> <exit-code>   # refuses dirty trees and failing runs
bash .claude/fleet/signal.sh CONFLICT "<reason>"
```

The `<exit-code>` (the test command's own `$?` / `${PIPESTATUS[0]}`) is the authoritative verdict; pass it whenever you have it. Without it, `signal.sh` falls back to the log, never word-grepping prose: [references/session-prompt.md](references/session-prompt.md#per-language-test-cmd-snippets).

## Session awareness — MAIN, lane owners, and the live-owner gate

Lane state files say *what* a lane is. They never say *who* is driving it. Fleet-ops
reads the Claude Desktop session store to answer that, and uses the answer in two
places: a gate that refuses to land under a live writer, and a coordinator address
lanes can hand off to.

### MAIN — one coordinator per repo

**MAIN is the session whose cwd is the main checkout's root**, resolved the same from any
lane: the integration tree, which hosts no writing session ([`worktree-boundaries`](../../rules/worktree-boundaries.md)). `fleet main`
makes that role *addressable*, so a lane can say "come land me" instead of writing a file
and hoping someone polls it.

```
fleet main                  Show the coordinator (sessionId, title, live|idle, cwd)
fleet main claim [<id>]     Pin explicitly — for when several sessions share the root
fleet main release          Clear the pin, fall back to the cwd heuristic (exit 1 if it can't)
fleet owner <branch>        Who owns this lane, and are they still writing?
```

MAIN's job is the whole integration half: land the queue, triage `CONFLICT` lanes,
sweep after the wave, and prepare the deploy. Lanes build and signal; MAIN
integrates. A deploy still needs an explicit human OK for that specific deploy.

### The live-owner gate

`fleet land` **refuses a lane whose owning session was active within `session_live_secs` (default 600)**: it would merge a branch that session may still be committing to and rebase worktrees out from under it. A lane session landing its own finished work is exempt only as the sole live claimant. Override: `session_check=off`, or `FLEET_SKIP_SESSION_CHECK=1` for one run (stripped before `test_cmd`).

Channels: lane files (`signal.sh`) work everywhere, `ccd_session_mgmt` is Desktop-only and agent-only, `pigeon` is the portable fallback. Mechanics and history: [references/session-awareness.md](references/session-awareness.md).

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods