fleet/fleetd
3
0
Fork 0
Code Issues 73 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

wiki: renumber Team -> 6-Team, add to sidebar + Home index, align to MCP 

- git mv Team.md 6-Team.md; H1 3->6
- convert [[wiki-links]] -> numbered markdown links
- align delivery refs to MCP: bridge_send / bridge_reply (was POST /message +
  Stop-hook envelope); lead + workers are MCP clients (unified mount)
- _Sidebar.md + Home Pages index: add chapter 6
Dai Ha
2026-07-11 15:41:28 +02:00
parent b824a28d04
commit c70d213fcb
3 changed files with 41 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Team.md → 6-Team.md
+39 -36
@@ -1,27 +1,30 @@
# 3. Team
# 6. Team
The [[Message-Server]] (`bridged`) delivers **one turn into one worker**. A **team** is the
layer above it: a **Claude team-lead** that fans a job out across a **mixed fleet** of
workers — some on Claude, some on the remote local LLM — and reduces their replies. Same
`bridged` delivery, same subscription boundary; this page is only about **orchestration** —
who the workers are, how the lead picks one, and how it runs many at once.
The [Message Server](2-Message-Server) (`bridged`) delivers **one turn into one worker**. A
**team** is the layer above it: a **Claude team-lead** that fans a job out across a **mixed
fleet** of workers — some on Claude, some on the remote local LLM — and reduces their replies.
Same `bridged` delivery, same subscription boundary; this page is only about **orchestration**
— who the workers are, how the lead picks one, and how it runs many at once.
> Delivery mechanics (blocking `POST /message`, status-gated reply envelope) live in
> [[Message-Server]]. Transport rationale is in [[Approaches]]. This page assumes both.
> Delivery mechanics (blocking `bridge_send` MCP call, status-gated reply) live in
> [Message Server](2-Message-Server). Transport rationale is in [Approaches](3-Approaches).
> This page assumes both.
## The team
- **Team-lead** — the primary **Opus** (Claude Code, env **CLEAN**, on Pro/Max). Not a
worker; a **thin client of `bridged`**. It plans, routes, dispatches, and integrates, and
never sets `ANTHROPIC_BASE_URL`.
worker; an **MCP client of `bridged`** (it mounts the bridge like everyone else). It plans,
routes, dispatches via `bridge_send`, and integrates — and never sets `ANTHROPIC_BASE_URL`.
- **Workers** — a herd of `claude` panes in herdr, each an addressable `bridged` session
with its **own model/env**:
with its **own model/env**, each also **mounting the bridge MCP** (unified setup — they
reply via `bridge_reply`):
- **Claude workers** (clean env, e.g. Sonnet) — reasoning-heavy or high-accuracy subtasks.
- **Local workers** (`ANTHROPIC_BASE_URL=https://ollama.ltms.dev`) — bulk, cheap, or
embarrassingly parallel subtasks.
Every worker is still a *real Claude Code process* (inherits `CLAUDE.md`, hooks, skills,
MCP) — only its model differs. Scale each kind horizontally by adding panes.
MCP) — only its model differs. The **same one MCP-mount line** wires lead and every worker
alike. Scale each kind horizontally by adding panes.
### Topology
@@ -37,7 +40,7 @@ flowchart TB
ANT["api.anthropic.com<br/>(Pro/Max)"]
OLL["ollama.ltms.dev<br/>(local model)"]
LEAD -->|"blocking POST /message (target role)"| BD
LEAD -->|"MCP bridge_send (target role)"| BD
BD -->|"Unix socket · send_text · events.subscribe"| HERDR
HERDR --> WC1 & WC2 & WL1 & WL2
WC1 --> ANT
@@ -67,7 +70,7 @@ the session the lead names.
## Subscription boundary in a team
Unchanged from [[Architecture]], and it scales with the fleet: **only local-worker panes**
Unchanged from [Architecture](1-Architecture), and it scales with the fleet: **only local-worker panes**
launch with `ANTHROPIC_BASE_URL`. The lead and every Claude worker stay env-clean on the
subscription. `bridged` enforces which panes may carry the off-subscription env, so adding
workers never widens the boundary.
@@ -86,26 +89,26 @@ sequenceDiagram
Note over L: split job → subtask A (reasoning), subtask B (bulk)
par A → Claude worker
L->>B: POST /message {role: w-claude, prompt: A}
L->>B: bridge_send {role: w-claude, prompt: A}
B->>WC: send_text into running pane
WC-->>B: status working → idle + Stop-hook envelope
B-->>L: 200 reply A
WC-->>B: bridge_reply (or status done)
B-->>L: tool result reply A
and B → local worker
L->>B: POST /message {role: w-local, prompt: B}
L->>B: bridge_send {role: w-local, prompt: B}
B->>WL: send_text into running pane
WL-->>B: status working → idle + Stop-hook envelope
B-->>L: 200 reply B
WL-->>B: bridge_reply (or status done)
B-->>L: tool result reply B
end
Note over L: reduce → integrate A + B into final answer
```
- **Map:** the lead issues N concurrent blocking `POST /message` calls (one per subtask → its
chosen worker). Each call blocks only *that* request; `bridged` holds it open until the
worker's turn completes (status-gated) and returns the reply envelope.
- **Reduce:** the lead collects the N envelopes and integrates. A slow local worker never
- **Map:** the lead issues N concurrent blocking `bridge_send` tool calls (one per subtask →
its chosen worker). Each call blocks only *that* request; `bridged` holds it open until the
worker's turn completes (status-gated) and returns the reply as the tool result.
- **Reduce:** the lead collects the N replies and integrates. A slow local worker never
blocks a fast Claude worker — wall-clock ≈ the slowest single subtask, not the sum.
- **Detached / long jobs** use the async broker path instead of a held request (Channel 2 in
[[Architecture]]), so the lead never busy-polls across turns.
[Architecture](1-Architecture)), so the lead never busy-polls across turns.
Fan-out is bounded by the herd size (pane count) and `bridged`'s concurrency policy, not by
the lead.
@@ -118,8 +121,8 @@ in the lead's `CLAUDE.md` turns Opus into the orchestrator:
```markdown
## Your team (via bridged)
You are the team-lead. Delegate through the bridged client — never launch workers yourself.
Roster: ask bridged for current sessions/roles.
You are the team-lead. Delegate through the bridge MCP tools — never launch workers yourself.
Roster: call bridge_sessions for current sessions/roles.
- w-claude-* — Claude Sonnet. Reasoning-heavy / high-accuracy subtasks.
- w-local-* — remote local LLM. Bulk, cheap, or parallelizable subtasks.
@@ -128,16 +131,16 @@ of them (concurrent blocking sends), THEN gather — never serialize independent
Integrate the reply envelopes; you own the final answer.
```
Wrap the send as a Claude Code skill (`/delegate <role> "<task>"`) so the lead calls one
tool instead of hand-rolling the HTTP request.
`bridge_send` **is** the one tool call — no HTTP to hand-roll. Optionally wrap it in a Claude
Code skill (`/delegate <role> "<task>"`) for ergonomics.
## What this layer does NOT change
- **Delivery** is still `bridged` → herdr `pane.send_text` + status events ([[Message-Server]]).
- **Completion timing** is still the worker status event; **reply content** still rides the
worker `Stop`-hook envelope.
- **Delivery** is still `bridged` → herdr `pane.send_text` + status events ([Message Server](2-Message-Server)).
- **Completion timing** is still the worker status event; **reply content** rides the worker's
`bridge_reply` (or a `Stop`-hook envelope for a herdr-only worker).
- **Single-host** still applies: herdr's socket is local, so the whole herd lives on the
`bridged` host. The lead may be remote — it only needs HTTP to `bridged`.
`bridged` host. The lead may be remote — it only needs to reach `bridged`'s MCP endpoint.
## Open questions
@@ -145,10 +148,10 @@ tool instead of hand-rolling the HTTP request.
(label-based). Start with the former; promote to the latter if routing logic grows.
- **Backpressure:** per-role concurrency caps in `bridged` so a fan-out can't exhaust the
local gateway.
- **Result schema:** whether reply envelopes should carry structured metadata (worker, model,
tokens) to help the lead's reduce step.
- **Result schema:** whether `bridge_reply` payloads should carry structured metadata (worker,
model, tokens) to help the lead's reduce step.
## Status
🟡 Design (2026-07-11). Orchestration layer over the selected `bridged` server; inherits
herdr (chosen) + AgentAPI (fallback). Delivery unchanged — see [[Message-Server]].
herdr (chosen) + AgentAPI (fallback). Delivery unchanged — see [Message Server](2-Message-Server).
Home.md
+1
@@ -67,6 +67,7 @@ Read in order (the sidebar mirrors this):
3. **[Approaches](3-Approaches)** — herdr-centric vs AgentAPI vs Agent SDK vs bus/tmux (research matrix)
4. **[Setup](4-Setup)** — running herdr + `bridged` + a worker pointed at `ollama.ltms.dev`
5. **[Operations](5-Operations)** — health, restart, model swaps, troubleshooting
6. **[Team](6-Team)** — team-lead orchestrating a mixed Claude + local-LLM worker fleet
## Status
_Sidebar.md
+1
@@ -9,6 +9,7 @@
3. [Approaches](3-Approaches) — transports compared, why herdr
4. [Setup](4-Setup) — bring-up
5. [Operations](5-Operations) — day-2 runbook
6. [Team](6-Team) — orchestrating a mixed fleet
---
🟢 herdr-centric `bridged` · AgentAPI = fallback