Claude Skill

fleet-ops

Landing discipline for parallel work: sequential test-gated landing queue, pre-land scrub, auto-rebase of in-flight lanes, fleet status, one-shot revert. Native primitives spawn; fleet-ops lands. Triggers: landing queue, land branches, merge queue, test gate, fleet status, land a

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_fleet-ops-6aef525.zip · 235 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/fleet-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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. Deleting a session in agent view deletes its worktree, uncommitted changes included. Gives vs lacks: 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, a claude -p headless run, a fleetflow worker of any provider, or a human. Any branch with commits can be a lane, and all lanes share one test-gated queue.

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 queue <lane> <tip>... Land reviewed lanes one at a time, each merge audited first
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 merges branches only and leaves every worktree in place; fleet prune reclaims a directory once its owning session is provably archived or gone (Prune).

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.

Owning what lanes hand back

The spawning session owns each lane's result: review the diff (git diff main...<lane>), not the lane's report. Each new round goes to a fresh agent briefed with the first task, every later instruction, and the last report and branch. A missing, crashed or inconclusive result is never a pass, and a change's author never verifies it. Brief fields and the reasoning: references/session-prompt.md.

Landing pipeline

fleet land <branch> (and the daemon, per READY lane) first takes the landing marker (below), 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
  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). 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.

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.

Daemon lifecycle (experimental)

Optional automation over fleet land; manual lands are not experimental. fleet start (in the background) lands each lane as it turns READY and exits once all are terminal; fleet stop waits out a land in progress, gate included. It dies with the session. Detail: references/daemon.md.

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

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.

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). 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. /conduct runs that half as one procedure: references/conduct.md.

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.

Prune — worktree housekeeping

Landing retires the branch, not the directory. fleet prune classifies the leftover worktrees and removes only the provably finished ones.

fleet prune                  Classify and print. Changes NOTHING. (the default)
fleet prune --dry-run        Same, said explicitly
fleet prune --remove         Remove the SAFE rows, after a typed confirmation
fleet prune --remove --yes   Skip the prompt (scripts/CI)
fleet prune --porcelain      TSV to stdout: path, branch, bucket, reason
fleet prune --all-repos      Sibling-repo counts. Report-only, always

Dry run is the default, deliberately. Removing a worktree destroys its uncommitted and untracked files for good; committed lane work survives in the object store (git worktree add <path> <branch>). Telling those apart is the whole job, and every ambiguous case resolves away from deletion.

Buckets — first match wins, and the order is the safety argument

Only SAFE is ever removable: merged, clean, no open session claiming it, and for a Claude Code session tree (under .claude/worktrees/, or a hook-made worktree-* tree under $WORKTREE_ROOT) an archived session positively claiming it. A zero-commit lane is unstarted, not merged (REVIEW). A live claimant (archiving is not activity) or the invoking tree is KEEP; an unreadable store or archive flag, unproven detached HEAD, dirty, unmerged or unattributable tree is REVIEW, never touched under any flag. Removal uses git worktree remove (never rm -rf), re-verifies against a fresh scan right before each delete, and --all-repos never removes. Prune cannot see writes by absolute path, so it must never be the only guard. Table and claim rules: references/prune.md.

Landmine: removing a worktree out from under a live session

Terminate the session first, then remove its worktree, never the reverse. A session whose worktree vanishes neither exits nor errors: it spins at ~85% of a core indefinitely under a live parent, so orphan scans miss it. Detect by sustained CPU rate, check its --add-dir against git worktree list, then kill it (safe: it touches no files). Evidence and the one-liner: references/prune.md.

fleet status flags a backlog (! 3 worktree(s) prunable, 6 to review - fleet prune); off with prune_hint=off or FLEET_NO_PRUNE_HINT=1.

Sweep — after a wave

Prune refuses well but cannot drain REVIEW. fleet sweep (from MAIN) prints the backlog as next actions in procedure order: worktrees, competing lanes (same files, committed in one and uncommitted in another), worktree-less branches, ghosts/dirs/stashes, sessions to archive. It also sees lanes landed by content (squash, cherry-pick) and owners whose lane dir is gone. Work the list, re-running the sweep after each step; nothing is cached, so it resumes. --apply is zero-loss only (ghost entries, merged unheld branches, unclaimed empty dirs); removal stays fleet prune --remove. Sessions are the agent's job, one gated call each: ARCHIVE-REQUEST → send_message, ARCHIVE-DIRECT → archive_session, never a message, which would resume it into a dead tree. Detail: references/sweep.md.

First-class user interaction (HARD RULE)

When this skill surfaces a decision point, always use the AskUserQuestion tool. Plain markdown numbered lists are not acceptable for these branches.

Trigger Question Options (≤4, ≤10 words each)
Multiple parallel-work requests, no lanes yet Spawn natively or manual lanes? Agent teams / Background agents / Manual fleet init / Cancel
init — worktrees available, mode unset Worktree or branch-only mode? Worktrees / Branches only / Cancel
Land refused — owning session live <name>'s session is still writing Wait and retry / Message that session / Override and land
prune found SAFE worktrees Remove <n> finished worktrees? Remove them / Show the table again / Leave as-is
sweep lists sessions to archive Archive <n> finished sessions? Send the requests / Show the rows / Skip
Lane → CONFLICT (rebase fail) Lane <name> has rebase conflict Resolve in lane / Skip & continue / Revert lane / Untrack
Lane → FAILED (post-merge tests red) Tests broke after <name> merged Auto-revert / Investigate first / Accept failure
Pre-land scrub hits Forbidden patterns in <name> diff Block landing / Override (note reason) / Open to edit
fleet shows mixed states How to proceed with the fleet? Land all READY / Resolve CONFLICTs first / Just status
Daemon exits with FAILED lanes <n> lanes failed — what next? Retry all / Revert and report / Leave as-is

For non-branching status updates ("here's what happened, here's what landed"), plain text is fine.

What it handles vs what it does not

A dirty main is refused. Out of scope: spawning or monitoring sessions, several sessions on one working tree (refused), uncommitted work at signal time, cross-lane external state like migrations (order lands by hand). Full table: references/scope.md.

Compatibility

Runs on Linux and macOS (bash 3.2+), Git Bash, and PowerShell 7 calling bash; needs git 2.5+ and standard tools. Platform table and Windows notes (held files, long paths): references/scope.md.

Mojibake status icons: export FLEET_ASCII=1 (or icons=ascii in .claude/fleet/config). Panels follow docs/TERMINAL-DESIGN.md via skills/_lib/term.sh.

Headless agent compatibility

Don't put manually-created fleet worktrees under .claude/: headless lane sessions (claude -p) fail every Write/Edit there, whatever their permission flags. Why: references/scope.md.

Configuration

Optional .claude/fleet/config, one key=value per line, parsed, never sourced: keys are case-insensitive, values need no quotes, unknown keys are warned about on stderr. Keys: mode, worktree_root, test_cmd, forbidden_pattern, base_branch, poll_interval, icons, session_check, session_live_secs, prune_hint. test_cmd is the test gate; unset, landing is refused. Never add a contiguous scrub-marker token to a diff (build it by concatenation) or the scrub refuses the branch. Grammar, defaults, the shipped pattern: references/configuration.md.

References

  • references/workflow.md — end-to-end walkthroughs (native and manual spawn) and recovery scenarios
  • references/session-prompt.md — the lane brief for any spawned session, and the rules for owning what it returns
  • One topic each, linked above: configuration, session-awareness, prune, sweep, landing, daemon, native-spawn, scope (all .md under references/)

Scripts

  • scripts/fleet.sh — main CLI (init, track, start/stop, status, land, revert, scrub-check, prune, sweep, config, main, owner)
  • scripts/signal.sh — branch-aware signaler (deployed to .claude/fleet/signal.sh); prints the MAIN handoff after READY/CONFLICT
  • scripts/sessions.sh — resolves a branch or directory to its owning session across every Desktop store and the CLI transcripts; exits 3 silently without the store or jq. Detail: references/session-awareness.md
  • scripts/sweep.sh — fleet sweep: the post-wave pass. --porcelain/--json rows (phase, subject, verdict, detail, action); exit 10 on findings. E.g. fleet sweep --porcelain | awk -F'\t' '$3=="ARCHIVE-REQUEST"'. Detail: references/sweep.md
  • scripts/queue.sh — fleet queue, the audited landing chain; exit codes in --help
Files (claude-mods)
  • assets
    • .gitkeep 0 B · in bundle
  • references
    • conduct.md 19.3 KB
      Loading…
    • configuration.md 5.7 KB
      Loading…
    • daemon.md 2.8 KB
      Loading…
    • landing.md 9.5 KB
      Loading…
    • native-spawn.md 1.6 KB
      Loading…
    • prune.md 12.8 KB
      Loading…
    • scope.md 4.1 KB
      Loading…
    • session-awareness.md 11.8 KB
      Loading…
    • session-prompt.md 10.2 KB
      Loading…
    • sweep.md 18.9 KB
      Loading…
    • workflow.md 8.7 KB
      Loading…
  • scripts
    • fleet.sh 159.2 KB
      Loading…
    • queue.sh 31.4 KB
      Loading…
    • sessions.sh 77.9 KB
      Loading…
    • signal.sh 8.4 KB
      Loading…
    • sweep.sh 67.2 KB
      Loading…
  • tests
    • queue.sh 17.3 KB
      Loading…
    • run.sh 136 KB
      Loading…
    • sweep.sh 22.5 KB
      Loading…
    • unstarted.sh 8.4 KB
      Loading…
    • worktree-root.sh 5 KB
      Loading…
  • SKILL.md 18.3 KB
    ---
    name: fleet-ops
    description: "Landing discipline for parallel work: sequential test-gated landing queue, pre-land scrub, auto-rebase of in-flight lanes, fleet status, one-shot revert, post-wave sweep. Native primitives spawn; fleet-ops lands and cleans up. Triggers: landing queue, land branches, merge queue, test gate, fleet status, land agent-team/background-agent branches, clean up after a wave, stale worktrees, archive finished sessions."
    license: MIT
    allowed-tools: "Read Bash Glob Grep AskUserQuestion"
    metadata:
      author: claude-mods
      status: stable
      experimental-parts: daemon (in-session background polling)
      related-skills: git-ops, push-preflight, claude-code-ops
    ---
    
    # 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. 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, a `claude -p` headless run, a fleetflow worker of any provider, or a human. Any branch with commits can be a lane, and all lanes share one test-gated queue.
    
    ## 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 queue <lane> <tip>... Land reviewed lanes one at a time, each merge audited first
    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 merges *branches* only and leaves every worktree in place; `fleet prune` reclaims a directory once its owning session is provably archived or gone ([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.
    
    ## Owning what lanes hand back
    
    The spawning session owns each lane's result: **review the diff (`git diff main...<lane>`), not the lane's report.** Each new round goes to a fresh agent briefed with the first task, every later instruction, and the last report and branch. A missing, crashed or inconclusive result is never a pass, and a change's author never verifies it. Brief fields and the reasoning: [references/session-prompt.md](references/session-prompt.md#owning-what-comes-back).
    
    ## 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)
    
    Optional automation over `fleet land`; manual lands are not experimental. `fleet start` (in the background) lands each lane as it turns READY and exits once all are terminal; `fleet stop` waits out a land in progress, gate included. 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.
    `/conduct` runs that half as one procedure: [references/conduct.md](references/conduct.md).
    
    ### 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).
    
    ## Prune — worktree housekeeping
    
    Landing retires the *branch*, not the *directory*. `fleet prune` classifies the
    leftover worktrees and removes only the provably finished ones.
    
    ```
    fleet prune                  Classify and print. Changes NOTHING. (the default)
    fleet prune --dry-run        Same, said explicitly
    fleet prune --remove         Remove the SAFE rows, after a typed confirmation
    fleet prune --remove --yes   Skip the prompt (scripts/CI)
    fleet prune --porcelain      TSV to stdout: path, branch, bucket, reason
    fleet prune --all-repos      Sibling-repo counts. Report-only, always
    ```
    
    **Dry run is the default, deliberately.** Removing a worktree destroys its
    uncommitted and untracked files for good; committed lane work survives in the
    object store (`git worktree add <path> <branch>`). Telling those apart is the
    whole job, and every ambiguous case resolves away from deletion.
    
    ### Buckets — first match wins, and the order is the safety argument
    
    Only **SAFE** is ever removable: merged, clean, no open session claiming it, and for a Claude Code session tree (under `.claude/worktrees/`, or a hook-made `worktree-*` tree under `$WORKTREE_ROOT`) an archived session positively claiming it. A zero-commit lane is *unstarted*, not merged (REVIEW). A live claimant (archiving is not activity) or the invoking tree is **KEEP**; an unreadable store or archive flag, unproven detached HEAD, dirty, unmerged or unattributable tree is **REVIEW**, never touched under any flag. Removal uses `git worktree remove` (never `rm -rf`), re-verifies against a fresh scan right before each delete, and `--all-repos` never removes. Prune cannot see writes by absolute path, so it must never be the only guard. Table and claim rules: [references/prune.md](references/prune.md).
    
    ### Landmine: removing a worktree out from under a live session
    
    **Terminate the session first, then remove its worktree, never the reverse.** A session whose worktree vanishes neither exits nor errors: it spins at ~85% of a core indefinitely under a live parent, so orphan scans miss it. Detect by sustained CPU rate, check its `--add-dir` against `git worktree list`, then kill it (safe: it touches no files). Evidence and the one-liner: [references/prune.md](references/prune.md).
    
    `fleet status` flags a backlog (`! 3 worktree(s) prunable, 6 to review - fleet prune`); off with `prune_hint=off` or `FLEET_NO_PRUNE_HINT=1`.
    
    ## Sweep — after a wave
    
    Prune refuses well but cannot drain REVIEW. `fleet sweep` (from MAIN) prints the backlog as next actions in procedure order: worktrees, competing lanes (same files, committed in one and uncommitted in another), worktree-less branches, ghosts/dirs/stashes, sessions to archive. It also sees lanes **landed by content** (squash, cherry-pick) and owners whose lane dir is gone. **Work the list, re-running the sweep after each step**; nothing is cached, so it resumes. `--apply` is zero-loss only (ghost entries, merged unheld branches, unclaimed empty dirs); removal stays `fleet prune --remove`. Sessions are the agent's job, one gated call each: `ARCHIVE-REQUEST` → `send_message`, `ARCHIVE-DIRECT` → `archive_session`, **never** a message, which would resume it into a dead tree. Detail: [references/sweep.md](references/sweep.md).
    
    ## First-class user interaction (HARD RULE)
    
    When this skill surfaces a decision point, **always use the `AskUserQuestion` tool**. Plain markdown numbered lists are not acceptable for these branches.
    
    | Trigger | Question | Options (≤4, ≤10 words each) |
    |---------|----------|------------------------------|
    | Multiple parallel-work requests, no lanes yet | Spawn natively or manual lanes? | Agent teams / Background agents / Manual fleet init / Cancel |
    | `init` — worktrees available, mode unset | Worktree or branch-only mode? | Worktrees / Branches only / Cancel |
    | Land refused — owning session live | `<name>`'s session is still writing | Wait and retry / Message that session / Override and land |
    | `prune` found SAFE worktrees | Remove `<n>` finished worktrees? | Remove them / Show the table again / Leave as-is |
    | `sweep` lists sessions to archive | Archive `<n>` finished sessions? | Send the requests / Show the rows / Skip |
    | Lane → `CONFLICT` (rebase fail) | Lane `<name>` has rebase conflict | Resolve in lane / Skip & continue / Revert lane / Untrack |
    | Lane → `FAILED` (post-merge tests red) | Tests broke after `<name>` merged | Auto-revert / Investigate first / Accept failure |
    | Pre-land scrub hits | Forbidden patterns in `<name>` diff | Block landing / Override (note reason) / Open to edit |
    | `fleet` shows mixed states | How to proceed with the fleet? | Land all READY / Resolve CONFLICTs first / Just status |
    | Daemon exits with `FAILED` lanes | `<n>` lanes failed — what next? | Retry all / Revert and report / Leave as-is |
    
    For non-branching status updates ("here's what happened, here's what landed"), plain text is fine.
    
    ## What it handles vs what it does not
    
    A dirty `main` is refused. Out of scope: spawning or monitoring sessions, several sessions on one working tree (refused), uncommitted work at signal time, cross-lane external state like migrations (order lands by hand). Full table: [references/scope.md](references/scope.md).
    
    ## Compatibility
    
    Runs on Linux and macOS (bash 3.2+), Git Bash, and PowerShell 7 calling `bash`; needs `git 2.5+` and standard tools. Platform table and Windows notes (held files, long paths): [references/scope.md](references/scope.md).
    
    Mojibake status icons: `export FLEET_ASCII=1` (or `icons=ascii` in `.claude/fleet/config`). Panels follow `docs/TERMINAL-DESIGN.md` via `skills/_lib/term.sh`.
    
    ## Headless agent compatibility
    
    **Don't put manually-created fleet worktrees under `.claude/`**: headless lane sessions (`claude -p`) fail every Write/Edit there, whatever their permission flags. Why: [references/scope.md](references/scope.md).
    
    ## Configuration
    
    Optional `.claude/fleet/config`, one `key=value` per line, **parsed, never sourced**: keys are case-insensitive, values need no quotes, unknown keys are warned about on stderr. Keys: `mode`, `worktree_root`, `test_cmd`, `forbidden_pattern`, `base_branch`, `poll_interval`, `icons`, `session_check`, `session_live_secs`, `prune_hint`. **`test_cmd` is the test gate; unset, landing is refused.** Never add a contiguous scrub-marker token to a diff (build it by concatenation) or the scrub refuses the branch. Grammar, defaults, the shipped pattern: [references/configuration.md](references/configuration.md).
    
    ## References
    
    - `references/workflow.md` — end-to-end walkthroughs (native and manual spawn) and recovery scenarios
    - `references/session-prompt.md` — the lane brief for any spawned session, and the rules for owning what it returns
    - One topic each, linked above: `configuration`, `session-awareness`, `prune`, `sweep`, `landing`, `daemon`, `native-spawn`, `scope` (all `.md` under `references/`)
    
    ## Scripts
    
    - `scripts/fleet.sh` — main CLI (init, track, start/stop, status, land, revert, scrub-check, prune, sweep, config, main, owner)
    - `scripts/signal.sh` — branch-aware signaler (deployed to `.claude/fleet/signal.sh`); prints the MAIN handoff after READY/CONFLICT
    - `scripts/sessions.sh` — resolves a branch or directory to its owning session across every Desktop store and the CLI transcripts; exits 3 silently without the store or `jq`. Detail: [references/session-awareness.md](references/session-awareness.md)
    - `scripts/sweep.sh` — `fleet sweep`: the post-wave pass. `--porcelain`/`--json` rows (phase, subject, verdict, detail, action); exit 10 on findings. E.g. `fleet sweep --porcelain | awk -F'\t' '$3=="ARCHIVE-REQUEST"'`. Detail: [references/sweep.md](references/sweep.md)
    - `scripts/queue.sh` — `fleet queue`, the audited landing chain; exit codes in `--help`
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.