fleetd/plans/fleet-plugin/plan.md

Fleet as a Claude Code plugin — plan

Status: draft for architect review. Not implemented. Author: primary (lead opus, Mac fleet). Date: 2026-09-05.

0. Correction — this already exists, and that changes the plan

I wrote sections below as if the plugin were new work. It is not. This repo is already a Claude Code marketplace and already ships a plugin, added in ef1e014 (CB-527) and last touched in 2e138a1 (CB-634):

.claude-plugin/marketplace.json          -> name "claude-bridge", plugins: [ ./plugin ]
plugin/.claude-plugin/plugin.json        -> name "claude-bridge", version 0.1.0
plugin/.mcp.json                         -> mounts "fleetd" at http://127.0.0.1:8765/mcp
plugin/skills/setup/SKILL.md             -> a full onboarding skill
plugin/README.md

The setup skill is good and covers most of what section 5 proposes: preflight, merge-not-clobber into .mcp.json, read-only permissions only, credentials by env-var name, and a verify step that insists on a real spawn because a green /healthz proves nothing.

So the operator's question — "can we pack things into plugins?" — is already answered yes, and it was built. The real question is why it did nothing for the kb session. The answer is drift plus invisibility.

The drift, measured

#	Finding	Evidence
1	Mount name mismatch. The plugin mounts the server as fleetd; the daemon's own constant is fleet	plugin/.mcp.json vs PeerLauncher.java:34 String MCP_MOUNT_NAME = "fleet"
2	URL hardcoded, no env indirection, so one plugin cannot serve two hosts or ports	plugin/.mcp.json
3	Ships no worker skills and no agents	plugin/ has 1 skill (setup); .claude/skills/ has 5 and .claude/agents/ has 3, none of them in plugin/
4	Stale identity advice. setup §5 tells the operator to pin primary.terminal:	CB-579 replaced that with fleet.leaders.*.tab. record Primary still exists (FleetConfig.java:954), so the advice is not dead — but it is no longer the mechanism
5	Stale install path. README says /plugin marketplace add ltms/claude-bridge	the repo is fleet/fleetd since CB-623
6	Stale names. Plugin and marketplace are both claude-bridge	the project renamed to fleetd in CB-634
7	Nothing references it. grep -rn "plugin/" CLAUDE.md docs/*.md returns nothing	so no session is ever told the plugin exists — which is exactly why I planned it from scratch

Finding 7 is the root cause of the other six. A shipped capability that no instruction file mentions gets no maintenance, and the next person rebuilds it. That is the same failure the CLAUDE.md "Features" rule was written to stop.

Finding 3 is the one that matters most for the operator's actual problem. A worker spawned into a kb worktree has no implementer skill, because only claude-bridge carries one in .claude/skills/. Every brief that says "Load the implementer skill" is a no-op outside this repo. The plugin is the right home for those skills and does not carry them yet.

1. The problem, restated

A project is "fleet-enabled" today by hand-edits nobody wrote down in one place:

• a fleet.leaders.<name> entry in a host's gitignored fleetd.yaml;
• the repo must carry .claude/skills/* for a worker to load implementer or reviewer;
• the repo must carry the canonical bridge block in its CLAUDE.md;
• the MCP mount arrives only because LeadLauncher and ClaudeCodeLauncher add --mcp-config to the argv they build.

Shown live on 2026-09-05: an operator opened claude by hand in /home/ltms/LTMS/kb on fleet01 and the session had no fleet_* tools at all, because a hand-started agent never gets the launcher's --mcp-config. The plugin would have fixed that — if it had been installed, and if it had been mentioned anywhere.

2. What was verified, and how

Claim	Evidence
A plugin can install globally	~/.claude/plugins/installed_plugins.json — scopes in use are project (5), local (4), user (1)
A plugin can mount an MCP server	~/.claude/plugins/marketplaces/kb-alms/.mcp.json mounts memory at "url": "${KB_MEMORY_URL}"
A plugin can carry skills, agents, commands, hooks	kb-alms ships skills/ + hooks/hooks.json; umputun-cc-thingz/plugins/planning ships agents/ + skills/
Env vars interpolate in a plugin's .mcp.json	same kb-alms file: ${KB_MEMORY_URL}, ${MEMORY_MCP_TOKEN}
A marketplace can be a plain git repo	known_marketplaces.json — mgnl-code-review has "source": "git", "url": "https://..."
This repo is already such a marketplace	.claude-plugin/marketplace.json, committed in ef1e014
A lead already binds to a project directory	FleetConfig.java:1017 record Leader(..., String workspace, String cwd); used at LeadLauncher.java:193-199
The lead's mount comes from argv, not config	LeadLauncher.java:253 adds --mcp-config

2b. Architect review + one measurement changed the design

The architect verified the plan against the code and returned build it with these changes. Two of its findings are load-bearing. I checked both myself.

A plugin cannot carry the agent definitions — confirmed

ClaudeCodeLauncher.java:371 calls agentDefinitionFile(spec.cwd(), spec.role(), ".claude", "agents"), and HerdrPeerLauncher.java:359-365 returns a path only when <cwd>/.claude/agents/<role>.md Files.isRegularFile. ClaudeCodeLauncher.java:391-393 adds --agent only when that returns non-null. OpenCodeLauncher does the same for .opencode/agent.

So the file must exist in the member's worktree. Moving .claude/agents/*.md into the plugin would silently stop every member getting --agent. The agents stay in the repo. My plan had this wrong.

The plugin does not reach members at all — confirmed, and worse than the architect could see

ClaudeCodeLauncher.java:285 does putIfPresent(workerEnv, "CLAUDE_CONFIG_DIR", cfg.configDir()). A member with configDir set reads that directory, not the operator's ~/.claude.

The architect could not check how far that goes, because fleetd.yaml is gitignored. I measured it:

• All four Claude profiles on the live fleet set configDir — local, local-direct, opus, sonnet (grep -c configDir fleetd/fleetd.yaml = 4).
• Each ccs instance has its own plugins/ directory: gx10 (8 entries), ltms (11), ollama (9), work (9).
• Those directories are four separate real directories with four separate inodes, and installed_plugins.json in each is a separate inode with an identical md5 (51c6e1c853e32e656b817e123fbbfcc5). They are copies made once, not links.

So a plugin installed at user scope lands in exactly one instance's store. It would have to be installed once per CLAUDE_CONFIG_DIR, and each copy would then drift. The plugin is not a delivery mechanism for member-facing assets on this host.

A side effect worth recording: my own session's CLAUDE_CONFIG_DIR is set, so the ~/.claude/plugins/* evidence in section 2 is not even this session's store. The claims about what a plugin can do still hold — they were read from real manifests — but the directory I read them from is the wrong one for any conclusion about this session.

The design that follows

Split by audience, not by mechanism:

Audience	Delivered by	Carries
operator / lead (a human opening any project)	the plugin, per config dir	the MCP mount, setup, the bridge charter
member (a worker in a provisioned worktree)	worktree provisioning	.claude/skills/*, .claude/agents/*

The second row is not a new idea — it is what the code already does for agents, and it is why agentDefinitionFile looks in the worktree. Extending worktree provisioning to seed .claude/skills/ from a fleetd-owned source is the consistent move, and it is what actually fixes "a worker in kb has no implementer skill". The plugin never could.

Other review findings I accepted

• Mount-name collision is real. PeerLauncher.java:34 is fleet; the plugin mounts fleetd. A lead with both gets two mounts of one daemon and duplicate fleet_* tools. Rename the plugin's server to fleet.
• Keep --mcp-config in LeadLauncher. It is config→argv from profile.mcpUrl(), not drift, and it is the only path that works for a member with its own configDir.
• I overstated #359. LeadCoordLoop.java:174-197 returns null and logs a warning that names the fix; tick() leaves the message unacked, so the broker holds it and delivers once a lead is named. It stalls loudly and recovers — it is not silent, and it is not data loss. My wording in issue #361 needs the same correction.
• Stage 1 ends with tools that mostly cannot be used until stage 3, because authority still comes from the tab. Section 3 already said this; the stage table did not.

3. What a plugin can and cannot do

This is the part that decides the design, so it is stated before the design.

A plugin gives tools. It does not give authority.

fleet_whoami resolves a caller's role from the connection, not from what is mounted. A hand-started session in kb that mounts fleet_* through a plugin will be resolved as a worker and refused on every orchestration call, because its pane is not in a tab matching fleet.leaders.*.tab.

So the plugin alone does not make a project fleet-enabled. It makes it tool-enabled. Registering the lead stays fleetd's job. Any plan that forgets this ships a plugin that looks installed and does nothing.

flowchart TB
    P["fleet plugin<br/>(user scope, every session)"] --> T["fleet_* tools mounted"]
    D["fleetd.yaml<br/>leaders.kb {tab, cwd}"] --> A["role = primary"]
    T --> W["can call fleet_*"]
    A --> W2["calls are authorized"]
    W --> OK["working lead"]
    W2 --> OK
    T --> NO["tools mounted, every call refused"]
    classDef good fill:#2f855a,stroke:#22543d,color:#ffffff;
    classDef bad fill:#9b2c2c,stroke:#63171b,color:#ffffff;
    class OK good
    class NO bad

Both halves are needed. The plugin is the left half only.

4. Proposed architecture — three layers

Layer 1: the plugin — lead-side only, fix the one that exists

Keep it at plugin/, keep the marketplace at .claude-plugin/marketplace.json. Do not create a second one, and do not put member-facing assets in it (see 2b).

.claude-plugin/marketplace.json   -> rename to "fleetd"; keep source ./plugin
plugin/
  .claude-plugin/plugin.json      -> rename to "fleet"; bump version
  .mcp.json                       -> mount name "fleet" (match PeerLauncher.MCP_MOUNT_NAME),
                                     url "${FLEETD_MCP_URL}", 8765 default documented
  skills/setup/SKILL.md           -> EXISTS. fix the stale primary.terminal advice (§5)
  skills/bridge-charter/SKILL.md  -> NEW: the canonical CLAUDE.md block
  README.md                       -> fix the install path (fleet/fleetd, not ltms/claude-bridge)

Not in the plugin: agents/*.md (the launcher requires them in the member's worktree — ClaudeCodeLauncher.java:371,391) and the three worker skills (a member with configDir set never reads the operator's plugin store — measured in 2b). Those belong to layer 1b.

A rename is a breaking change for anyone who installed 0.1.0. The mount name goes fleetd -> fleet, so a project whose .claude/settings.json pre-allows mcp__fleetd__fleet_whoami stops matching. Only this fleet has it installed today, so the cost is small now and grows. Decide once.

This solves propagation of the charter. CLAUDE.md says the bridge block "must stay byte-identical with the template in the wiki" and that "other projects carrying the block need the same edit" — a hand-copy the file itself admits is fragile, with a python snippet to check it. A plugin skill turns that into a version bump.

Layer 1b: worker skills reach members through the worktree, not the plugin

This is the change that actually fixes "a worker in kb cannot load implementer".

Worktree provisioning already writes into the member's tree — the parity overlay, the neutralised .mcp.json, the IDE overlay. Add one more: seed <worktree>/.claude/skills/ from a fleetd-owned source directory, so every member gets implementer, reviewer and hunter whatever repo it is working in. .claude/agents/ is already required there by the launcher, so this follows the grain of the design rather than cutting across it.

Open question for implementation: copy or symlink, and where the source lives (a config key such as memberSkills:, or the plugin's own directory read by the daemon). A symlink is one source of truth but breaks if the member's tree is archived; a copy drifts but is self-contained.

Layer 2: host-global fleet settings

~/.fleet/fleetd.yaml — the things that are true for the machine, not the project:

• broker: and coordinator: (URIs come from env, no secrets in the file)
• profiles: — backends, models, credentials, weights
• memberCredentials: policy
• worktreeRoot, worktreeGroup

Layer 3: per-project settings, committable

<project>/.fleet/project.yaml — the things that are true for the repo:

lead:
  tab: "lead: kb"
  profile: opus
ide:
  projectDir: ""          # kb is a Python repo, everything at the root
worktree: true

This split fixes a contradiction that exists today. ideProjectDir is a property of a repo (fleetd's Maven module is a subdirectory; kb's code is at the root) but the config key is per-profile. One profile therefore cannot serve both repos — measured on fleet01 on 2026-09-05, where the key had to be commented out to make kb work. Moving it to a project file removes the contradiction rather than working around it.

It is also committable, because it holds no secrets. A project that has been fleet-enabled once stays fleet-enabled for everyone who clones it.

5. The fleet-setup skill

What the operator actually asked for: one command that makes any project fleet-compatible.

sequenceDiagram
    participant Op as Operator
    participant Sk as fleet-setup skill
    participant Fs as project files
    participant Fd as fleetd
    Op->>Sk: /fleet-setup (in any project)
    Sk->>Fs: write .fleet/project.yaml
    Sk->>Fs: add the bridge block to CLAUDE.md (if absent)
    Sk->>Fd: register the lead (tab + cwd)
    Fd-->>Sk: tab created, lead launched
    Sk-->>Op: report what changed, and what is still manual

The skill writes the project half and asks the daemon for the host half.

The registration step needs something that does not exist yet: an MCP tool such as fleet_workspace_add{path, tab, profile}, or a fleetd config include so a project file is picked up without hand-editing the host file. This is the one genuinely new piece of daemon work.

6. Does this reduce fleetd's complexity?

Honestly: partly. Claiming more than this would be wrong.

Yes, in three places.

1. Skill and agent delivery leaves the daemon and the repos entirely.
2. Worktree config neutralisation (fleetd #134) gets safer. It blanks .mcp.json so the primary's IDE and forge servers do not leak into a worker. Today the fleet mount survives only because the launcher re-adds it by argv. With a user-scope plugin the fleet mount is outside the file being neutralised, so the two concerns stop fighting.
3. The ideProjectDir per-profile/per-repo contradiction disappears.

No, in the places that matter most. fleetd still owns spawn, authorization, worktrees, herdr, the broker, tickets, and identity. A plugin cannot do any of those. The plugin is a distribution mechanism, not a replacement for the daemon.

And it adds one new risk. The mount URL becomes a second source of truth. fleetd.yaml has the port; the plugin has the URL. Mitigation: the plugin reads ${FLEETD_MCP_URL} only, and the host env is the single place it is set.

7. Rollout stages

Stage	Content	Ends with
0	Make it visible. One CLAUDE.md line and one Features entry saying the plugin exists and where	nobody re-plans it a third time
1	Fix the plugin's drift: mount name fleet, ${FLEETD_MCP_URL}, names, README, stale primary.terminal advice	a lead in any project can install one plugin and get the mount
1b	Seed .claude/skills/ into provisioned worktrees	a worker in kb can load implementer
2	.fleet/project.yaml schema + FleetConfig reads it; ideProjectDir moves there	kb and fleetd both work off one profile
3	Fix #359, then config-include for lead registration, wired into the existing setup skill	/fleet:setup in a fresh project produces a working lead
4	Roll out to fleet01; retire the hand-copied CLAUDE.md block in favour of the skill	one git pull propagates the charter

Stage 0 is minutes of work and is the one that stops this happening again, so it goes first. Stage 1b carries most of the value and is independent of the plugin — it could ship first if the plugin rename needs more thought. Stage 1 alone ends with tools a hand-started session mostly cannot use, because authority still comes from the tab; that is fixed in stage 3, not stage 1. #359 moves ahead of stage 3 on the architect's advice, because stage 3 is what creates the second lead.

8. Questions for the architect

1. Is the layer-2 / layer-3 split right? Specifically: should profiles: stay host-global, or should a project be able to pin which profiles it uses? Cost of getting this wrong is a config that has to be re-split later.
2. Config include, or a new MCP tool, for registering a project's lead? An include is passive and survives a restart; a tool is live but writes to a gitignored file the daemon owns.
3. What happens when the plugin is absent? Should LeadLauncher keep its --mcp-config belt-and-braces, or is that the drift risk we should remove? Note opencode members cannot use Claude plugins at all, so OpenCodeLauncher keeps its ephemeral config either way.
4. Does a user-scope plugin mount leak into members in a way we do not want? Members already inherit user-scope MCP servers (--mcp-config adds, it does not replace). A worker getting fleet_* is correct and already happens. Confirm nothing else in the plugin should be worker-invisible.
5. Two leads on one host both hold a subscription seat. Is per-project leads the right unit, or should one lead serve several projects by changing cwd?
6. Blocking defect to fix first or alongside: LeadCoordLoop.resolveLocalLead() (lines 174-190) routes a peer message to "the sole lead" when no lead is named after coordinator.selfId. The moment a host has two leads — exactly what this plan encourages — cross-host coordination silently stops. Tracked as #359.