Przejdź do treści
Biblioteka skilli
AI i agenci · Planowanie

fleet-protocol

/fleet-protocol

Określa zasady pracy wielu równoległych sesji Claude Code na jednym kodzie: heartbeaty, adresowanie przez router, stany deklaracji, dyscyplinę git i gotowość PR do scalenia.

Repozytorium
claude ↗
Licencja
MIT
Ostatnia zmiana repozytorium
22.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
6
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Określa zasady pracy wielu równoległych sesji Claude Code na jednym kodzie: heartbeaty, adresowanie przez router, stany deklaracji, dyscyplinę git i gotowość PR do scalenia.

Wyzwalacze z opisu

start a fleetorchestration protocollaneheartbeatdispatchPR readymerge gate
Oryginalny opis (EN)

The contract every session in a multi-session Claude Code fleet reads first. Use when starting, joining, or running a fleet of parallel sessions on one codebase - heartbeats and standby, addressing other sessions through a dispatch router, ASSERTED vs DELIVERED claim states, git discipline (one repo per lane, push-and-open-PR as one action, never rewrite shared history), and merge-readiness discipline (re-read the checks as the literal last action before a merge). Triggers on "start a fleet", "orchestration protocol", "lane", "heartbeat", "dispatch", "PR ready", "merge gate", "who owns this re

Jak działa

  1. 1. Registration and addressing
  2. 2. Heartbeats and standby
  3. 3. ASSERTED vs DELIVERED
  4. 4. Git discipline
  5. 5. Review and merge-readiness discipline
  6. 6. Escalation
  7. 7. Behaviour
  8. Run directory
  9. References
Sekcje z nagłówków SKILL.md, w oryginale · 294 linii, 2 481 słów
Podgląd SKILL.md
---
name: fleet-protocol
description: The contract every session in a multi-session Claude Code fleet reads first. Use when starting, joining, or running a fleet of parallel sessions on one codebase - heartbeats and standby, addressing other sessions through a dispatch router, ASSERTED vs DELIVERED claim states, git discipline (one repo per lane, push-and-open-PR as one action, never rewrite shared history), and merge-readiness discipline (re-read the checks as the literal last action before a merge). Triggers on "start a fleet", "orchestration protocol", "lane", "heartbeat", "dispatch", "PR ready", "merge gate", "who owns this repo", or any question about how parallel sessions coordinate.
---

# Fleet protocol

The contract. A lane's brief says what it works on; this says how it behaves.
Everything fleet-specific — repo names, lane names, paths, bases, hands-off
sets — lives in `fleet.config.json` (see `references/configuration.md`). This
file names no repository.

**The protocol is a tool, not a reading assignment.** Every ritual below has a
one-command form in `${CLAUDE_PLUGIN_ROOT}/scripts/fleet.mjs`, and the
evidence rule that governs it is built into the command so it cannot be
skipped. Prefer the command to the hand-written version every time — the
hand-written versions are what cost the source run hours.

| Ritual | Command |
|---|---|
| register + first heartbeat, one action | `fleet register <lane> <session>` |
| heartbeat, validated on write, **read back before success** | `fleet hb <lane> <state> <task> [note]` |
| what am I waiting on, has it cleared | `fleet blockers <lane>` |
| every lane's state and age | `fleet census` |
| a PR's check state, read properly | `fleet checks <owner/repo> <pr>` |
| which posted verdicts have gone stale | `fleet verdicts <owner/repo>` |
| who a merge unblocks and whose green it broke | `fleet unblocks <owner/repo> <pr>` |
| CI load in jobs, not runs | `fleet queue-depth <owner/repo>` |
| the router's digest | `fleet digest` |
| a run directory from a config | `fleet init <run-id>` · `fleet doctor` |

(`fleet` = `node "${CLAUDE_PLUGIN_ROOT}/scripts/fleet.mjs"`; `--self-test`
proves the pure logic on fixtures, including the double-run and mixed-type
check cases.)

**Session mode.** Each lane is its **own session**, not a subagent. A
foreground `Agent` call blocks the caller's turn: it cannot heartbeat and
cannot read messages until the call returns. Subagents are for bounded work
*inside* a lane's turn, never for a lane itself.

## 1. Registration and addressing

1. On start, resolve your own identity (`ListAgents` — its first line names
   this session) and append one row to the run's `registry.md`:
   `| <UTC> | <lane-name> | <session-name> |`. The session name is the
   sidebar title and changes when a human renames it; the registry is
   append-only, and the **last** row for a lane is its current address.
2. **Resolve every address from the file at send time, never from memory.**
   Read the last registry row for that lane, then send. If a send fails to
   resolve, run `ListAgents` **once**, match the row whose title fits the
   role, append a fresh registry row, retry once. A role with no registry row
   is not online — send to the dispatch router instead.

   This is a rule about the reader, not the file. Two sessions independently
   addressed a session that had been ruled hung hours earlier, in the same
   hour, from memory — while the registry was **correct the entire time**.
   One was caught by accident, the other by the first's confession, and no
   process caught either. A correct, authoritative artifact that nobody
   consults is the hardest instrument failure to fix, because there is
   nothing to repair.
3. **Never poll.** Messages enqueue at the receiver and are processed on its
   next turn, so a message *wakes* an idle session. A polling loop over
   `ListAgents` burns turns and proves nothing.

**Route through the dispatch router.** All acks, reports, "PR ready"/"merged"
notices, blocked notices and escalations go to one comms role, which fans
out, collects acknowledgements, keeps the registry current, and sends the
orchestrator **digests, not a stream**. Nobody else messages tier 0 directly.

Two rules the router itself is bound by, both learned the hard way:

- **Relay verbatim; a relay that sharpens is a relay that falsifies.**
  Paraphrase silently drops hedges. Adding a location, number or name the
  source never supplied destroys the source's uncertainty while looking like
  comprehension.
- **Carry provenance across every hop** ("per `<lane>`, unverified"). A
  router multiplies confidence without adding evidence: a claim that travels
  lane → router → planner → back to its own origin arrives wearing two hops
  of apparent independent corroboration it never had.

## 2. Heartbeats and standby

You own exactly one file: `heartbeats/<your-lane-name>.md`. Append one line:

```
<UTC> | <state> | <task> | <note>
```

`state` ∈ `start` `working` `waiting` `blocked` `delivered` `standby`. The
note is optional; the other three fields are not, and no field may contain an
unescaped newline. **The line is not just a convention — validate it** with
`${CLAUDE_PLUGIN_ROOT}/scripts/validate-heartbeat.mjs`. Three sessions
produced three different malformations of this format in one evening, and one
of them — a leading `|`, copied from a table — shifted every field so a
tombstone for a dead session made the monitor report it **alive**.

Append at start, at every milestone, **before and after** any command
expected to run long, and at least every `heartbeat.intervalMinutes`
(default 15) while active.

- A heartbeat older than `heartbeat.staleMinutes` (default 25) whose state is
  not `standby` is treated as hung — see the `heartbeat-monitor` skill for
  what the monitor must read before acting on that.
- About to block on a foreground call? Heartbeat **first**:
  `waiting | <task> | foreground worker, expect silence`. The monitor reads
  it as intended rather than as a hang.
- **`waiting` and `standby` are different states, and only one has a
  counterparty.** `waiting | <specific next action> | <why>` is reserved for
  something genuinely pending on someone else, and it names what — so the
  monitor, and you, can check whether that thing is still pending.
  `standby | <next action when work arrives> |` is genuinely idle. Collapsing
  them makes a blocked lane and an idle lane identical in a census; a lane
  once sat blocked for **two hours** after its blocker had cleared.
- **Whatever you are waiting on, measure it yourself each heartbeat:**
  `fleet blockers <your-lane>`. It reads the refs in your own `waiting`
  heartbeats and asks the forge whether each has cleared — exit 1 means
  move. The merger telling you is the other half of that rule and it is
  unauditable — it leaves no trace, so nobody can verify it was sent,
  including the merger. Your own measurement leaves one, and it caught 3 of 3
  idle-on-done-work cases that no monitor saw.
- Idle with nothing queued: write `standby` and **end your turn**. A message
  wakes you. Standby is not death.
- Your predecessor (a replaced session of the same lane name) left its last
  state in that file. Resume from it; do not restart its work.

Appending: these files are written by many sessions at once. Use `fleet hb`.
It prints on **every** branch and **reads the line back** before reporting
success, because a shared helper that no-ops quietly is worse than twenty
lanes appending by hand — it fails them all in the same silent way, and a
silent heartbeat skip reads as HUNG and gets a producing lane replaced.
"Not written", "denied" and "skipped" leave identical bytes; only the
read-back tells them apart. If you must append by hand: on Windows,
`[IO.File]::Open($p,'Append','Write','ReadWrite')` or `Add-Content`; POSIX
`>>` and `tail` against a file another session holds open can block until the
tool timeout — and read your own line back afterwards. See
`docs/platform-notes.md`.

## 3. ASSERTED vs DELIVERED

> Every statement a session makes is **ASSERTED** until a link promotes it to
> **DELIVERED**.

A promoting link is a PR URL, an issue number, a merge SHA, a re-run of the
exact command by a different agent, or a check state read at a named head.
Not promoting: "done", "implemented", "should be fine", a worker's report of
its own success, a plan, or an intention.

- A worker's "done" is a claim until a verifier re-runs the stated command.
- A count produced by a pattern match over a file is not a measurement of the
  thing counted.
- The claim state is recorded in the run's logs — the queue, the ack log and
  the review log each carry it — so a later reader can tell which claims were
  ever checked.

This is the single highest-value rule in the protocol. Everything in the
`evidence-rules` skill is a corollary of it.

## 4. Git discipline

Full text with the incident behind each rule: `references/git-discipline.md`.
The short form, all of it load-bearing:

1. **One repo per lane**, exclusive scope, from `fleet.config.json`. Never
   edit another lane's repo. Honour the configured hands-off repo list.
2. **Never switch a shared checkout's HEAD**, never commit in it, never stash
   it. Work in a per-task worktree. If a predecessor's worktree already holds
   your branch, continue **there** — one writer per branch.
3. **Push and open the PR in ONE action.** A pushed branch with no PR is a
   parking spot that hides work. Draft is the parking spot; a bare branch is
   not.
4. **Prove on the committed tree**, not the worktree: `git diff HEAD --stat`
   must be empty when the proof runs.
5. **Conventional commits**, with a `Co-Authored-By:` trailer naming the
   model. No authorship headers inside source files.
6. **Never** `--force`, `reset --hard`, `clean`, or `worktree remove --force`.
   Never delete a branch holding unique content. `--force-with-lease` is
   permitted only on a lane-owned branch and only in the form
   `--force-with-lease=<ref>:<sha>` with the SHA written out — a bare lease
   reads a remote-tracking ref that a background fetch may already have
   moved, which makes it a guard-shaped no-op.
7. **Fix root causes.** Never weaken, skip, quarantine or retry-loop a test to
   get green. A green test that enshrines the defect is a defect.
8. **No machine-absolute paths and no time estimates** in committed files.
   Sequence by dependency.
9. **Verify the issue's symptom before building.** Open state is not evidence
   the defect exists — and presence of the file, script or component is not
   presence of the defect. Absent → close the issue with the evidence.
10. **Do not act on a PR you merely discovered by scanning.** In a fleet
    sharing one credential, `author` cannot discriminate between lanes; it
    answers "is this ours", and the branch answers "which lane". Read
    authorship from the **branch**, never from the PR.

## 5. Review and merge-readiness discipline

**Review routing.** Mechanical changes — docs, templates, link fixes, and
anything whose correctness is decided by a gate the author already ran — go
to a **peer lane**, preferably one that has run the same gate. Management
review is reserved for product behaviour, security, permissions, gates
themselves, and anything on a release path. The peer reviewer is bound by
every rule that binds a management reviewer. Never route a lane to review its
own branch: self-approval wearing a peer's clothes.

**Every PR body states four things** — this is the shape that makes reviewer
attention go further, because the claims arrive already scoped:

| | |
|---|---|
| WHAT was verified | the claim |
| THE EXACT COMMAND or gate | so the claim is re-runnable |
| THE FALSIFIER | the input that would have turned it red |
| THE SET or COUNT | what the claim ranges over |

Plus: what was intentionally **not** run, and the rejected "fixes" that would
have hidden the problem rather than solved it.

**Before merging** (`references/merge-discipline.md` for the mechanics):

1. **Re-read the checks as the literal last action.** Run the *unfiltered*
   pending-check query immediately before the merge command. Never reuse a
   result from earlier in the same turn. Stop on any contradiction between
   two reads. Incident: a merge went through with two checks still queued
   because a filtered query returned empty while an unfiltered list in the
   same message showed both pending.
2. **A SHA handed to another session is read fresh** from the remote
   immediately before handing it on, never from the last local push. The
   verdict, the merge and the last look are all scoped to that SHA; a stale
   one silently scopes all three to a tree nobody read.
3. **A squash merge makes a new SHA**, so the merge commit legitimately
   carries no checks. The verdict lives on the PR head. "The merge commit has
   no checks" is never itself evidence of a gap.
4. **A structural readiness verdict is not CI.** Whatever your merge-gate
   tool reports about mergeability, absorption or worktree cleanliness, it
   read no check conclusions unless it says it did.

## 6. Escalation

Some decisions are not a session's to make: money, production, tenants, the
trust chain, repository or organisation settings, abandoning work. Configure
the list in `fleet.config.json` under `founderClass`.

- **An escalation parks a decision, never a lane.** Append one line to
  `escalations.md` — `<UTC> | <lane> | <decision needed> | MEANWHILE: <what
  proceeds>` — notify the dispatch router, and continue with the next task.
- Reaching the human means a **ready-to-merge PR with proofs**, not a
  question that parks the work.
- Never ask the human a blocking question mid-run.

### 6a. Classify before you escalate

`founderClass` names *topics*. It does not decide who acts. Classify each
blocker from facts, using the table in `references/authority-and-receipts.md`
(the checker is `lib/fleet/classify-authority.mjs`):

| Class | When | Goes to |
|---|---|---|
| IRREVERSIBLE/FOUNDER | Merge to default branch, publish, tenant-wide or production grant, billing, deleting customer data, production cutover | coordinator → parent → founder |
| MISSING-CAPABILITY | Reversible, but no automated path or permission exists | coordinator, naming the **exact** permission or capability |
| AGENT-AUTHORIZED | Reversible and inside an existing grant or the brief | **proceed**, no sign-off |
| COORDINATOR-DECISION | Reversible and capable, but not delegated | coordinator extends or denies the brief |

The founder is reached only through the parent, and only for the first row.
Do not list a reversible step the brief delegates as "the human's step".

### 6b. Receipts

Every escalation, completion and failure is a schema-checked receipt, sent to
the coordinator's thread (`references/authority-and-receipts.md`). **A lane is
done only when it has posted a completion or failure receipt.** A cancelled
run still owes one. The coordinator lists terminal runs that have no receipt
and reconciles every completion claim against T3 run state.

## 7. Behaviour

- **Minimum verbosity** in every message and report: facts, numbers,
  `path:line`.
- **Delegate.** Spend your own turns on judgement, routing and verification.
  Bounded edits go to a mid-tier worker; verification to a cheap verifier.
  Every dispatch names its model — see the `fleet-roles` skill.
- **Spawn workers in the background** and heartbeat while they run.
- **Loop** until the planner says the queue is empty, then write
  `reports/<lane>.md` (PRs opened and merged, issues closed, blocked items,
  exact proofs) and finish with heartbeat `standby`.

## Run directory

One directory per run, machine-local, never committed. Layout, ownership and
the append rule: `references/run-directory.md`.

## References

| File | Contents |
|---|---|
| `references/configuration.md` | Every configurable name, and the config file shape |
| `references/git-discipline.md` | The full git rules with the incident behind each |
| `references/merge-discipline.md` | The merge gate, step by step |
| `references/run-directory.md` | Log files, who owns which, the append rule |
| `references/authority-and-receipts.md` | Blocker decision table, escalation receipt schema, done rule, coordinator reconciliation |
Pliki w paczce (6)
  • SKILL.md 16 KB
  • references/authority-and-receipts.md 7 KB
  • references/configuration.md 4 KB
  • references/git-discipline.md 7 KB
  • references/merge-discipline.md 8 KB
  • references/run-directory.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie fleet-protocol.

Migawka bazy z 13.11.2026 · wersja paczki c93a168abdfd (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90join-lane
    Uruchamia sesję jako pas pracy we flocie Claude Code: buduje zmiany, zgłasza gotowość do scalenia i pisze notatkę przekazania.
  • 100fleet-doctrine
    Opisuje zasady zachowania jednej z wielu sesji Claude Code na maszynie (Fleet Deck): komunikaty [FLEETDECK], koordynacja z innymi sesjami, tablica floty i decyzje w imieniu innej sesji.
  • 100join-lane
    Uruchamia sesję jako pas pracy w flocie Claude Code, który wykonuje zmiany, zgłasza gotowe pull requesty do scalenia i zapisuje notatkę przekazania, gdy kontekst się zapełni.
  • 100ops-fleet
    Prawdopodobnie pokazuje pulpit floty sesji CLIProxy i stan połączonych agentów.
  • 100fleet-status
    Pokazuje na jednym ekranie, tylko do odczytu, stan działającego lub właśnie zakończonego /fleet-launch: czas do terminu, księgi sesji, worktree w toku, dostarczone prace i pozostały zakres.
  • 98fleet-comms
    Rozmawia z innymi sesjami DevThrottle: wypisuje sesje, zmienia nazwę, otwiera nową i wysyła lub odbiera wiadomości.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.