@chankov/agent-fleet 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,12 +1,32 @@
1
1
  # Agent Fleet
2
2
 
3
- **Multi-agent fleet orchestration for coding agents — a Pi-centered runtime with a live control plane, peer messaging, and a production-grade skill library.**
3
+ [![npm](https://img.shields.io/npm/v/%40chankov%2Fagent-fleet)](https://www.npmjs.com/package/@chankov/agent-fleet)
4
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
+ [![runtimes](https://img.shields.io/badge/runtimes-pi%20%C2%B7%20Claude%20Code%20%C2%B7%20OpenCode-8A2BE2)](#quick-start)
4
6
 
5
- Agent Fleet turns a single coding-agent session into an operated *fleet*: the [`agent-hub`](#agent-hub-a-multi-agent-harness-for-pi) harness drives a live team of specialist subagents on **pi**, [herdr](https://herdr.dev) spawns and restores whole peer teams as tiled workspaces, `coms` gives every peer — including interactive **Claude Code** panes — a bidirectional messaging channel, and the Hermes bridge relays questions to your phone. Underneath it all sits a library of lifecycle skills and agent personas that encode how senior engineers spec, plan, build, verify, review, and ship.
7
+ **Operate a coding-agent *fleet* — not just one chat session.**
6
8
 
7
- Supported harnesses: **pi** (primary runtime), **Claude Code**, and **OpenCode**.
9
+ Agent Fleet is a **Pi-centered multi-agent orchestration system**. Its main job is to turn a single coding agent into a managed team: a thin dispatcher routes work to specialist agents, those agents can fan out to focused sub-agents, peer sessions talk over a shared messaging plane, and whole teams can be spawned, snapshot, and resumed as tiled workspaces.
8
10
 
9
- > Lifecycle skills are sourced from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) as **manually vendored content** (`vendor/agent-skills-upstream/`), with Agent Fleet-native and customized skills layered on top. See [docs/UPSTREAM-SKILLS.md](docs/UPSTREAM-SKILLS.md) for the import policy.
11
+ ```text
12
+ You ──▶ Hub (dispatcher) ──▶ Team agents ──▶ Sub-agents
13
+ │ │
14
+ ├── herdr (workspace) ├── skills (how to work)
15
+ ├── coms (messages) └── Verification Contract
16
+ └── Hermes (phone)
17
+ ```
18
+
19
+ **What you get:**
20
+
21
+ | Layer | Job |
22
+ | --- | --- |
23
+ | **[agent-hub](#agent-hub-a-multi-agent-harness-for-pi)** | Thin-context dispatcher on **pi** — drives specialists under a Verification Contract |
24
+ | **[herdr](https://herdr.dev)** | Fleet control plane — tiled peer workspaces, presence, snapshot/resume |
25
+ | **coms** | Peer data plane — bidirectional messaging between agents (including Claude Code panes) |
26
+ | **Hermes** | Remote human control — relay hub questions to your phone |
27
+ | **Skills + personas** | Lifecycle discipline — how to spec, plan, build, verify, review, and ship |
28
+
29
+ Supported coding agents: **pi** (primary runtime), **Claude Code**, and **OpenCode**.
10
30
 
11
31
  ```
12
32
  DEFINE PLAN BUILD VERIFY REVIEW SHIP
@@ -17,81 +37,125 @@ Supported harnesses: **pi** (primary runtime), **Claude Code**, and **OpenCode**
17
37
  /spec /plan /build /test /review /ship
18
38
  ```
19
39
 
20
- ---
21
-
22
- ## Commands
40
+ <details>
41
+ <summary><b>Table of contents</b></summary>
42
+
43
+ - [Origins: from skill library to fleet](#origins-from-skill-library-to-fleet)
44
+ - [Fleet hierarchy](#fleet-hierarchy)
45
+ - [Quick Start](#quick-start)
46
+ - [agent-hub: a multi-agent harness for pi](#agent-hub-a-multi-agent-harness-for-pi)
47
+ - [Commands](#commands)
48
+ - [All 29 Skills](#all-29-skills)
49
+ - [Agent Personas](#agent-personas)
50
+ - [Reference Checklists](#reference-checklists)
51
+ - [How Skills Work](#how-skills-work)
52
+ - [Per-Project Overrides](#per-project-overrides)
53
+ - [Project Structure](#project-structure)
54
+ - [Why Agent Fleet?](#why-agent-fleet)
55
+ - [How it compares](#how-it-compares)
56
+ - [Credits & inspiration](#credits--inspiration)
57
+ - [Built on (dependencies & tools)](#built-on-dependencies--tools)
58
+ - [Contributing](#contributing)
23
59
 
24
- 10 slash commands that map to the development lifecycle. Each one activates the right skills automatically.
60
+ </details>
25
61
 
26
- | What you're doing | Command | Key principle |
27
- |-------------------|---------|---------------|
28
- | Define what to build | `/spec` | Spec before code |
29
- | Plan how to build it | `/plan` | Small, atomic tasks |
30
- | Build incrementally | `/build` | One slice at a time |
31
- | Prove it works | `/test` | Tests are proof |
32
- | Review before merge | `/review` | Improve code health |
33
- | Audit web performance | `/webperf` | Measure before you optimize |
34
- | Simplify the code | `/code-simplify` | Clarity over cleverness |
35
- | Ship to production | `/ship` | Faster is safer |
36
- | Orchestrate a team | `/orchestrate` | Main session drives subagents |
37
- | Capture session lessons | `/compound` | Every session improves the next |
62
+ ---
38
63
 
39
- `/orchestrate` turns the main session into an **orchestrator** that drives a config-defined team of subagents (default `planner` + `builder`, no reviewer), routing them as a runtime roster and handling the `NEEDS_RESEARCH` / `PLAN_FILE` handoffs. The named teams live in `.claude/orchestrate-teams.yaml` (mirroring pi's `.pi/agents/teams.yaml`) and are switchable at runtime: `/orchestrate <team> "<task>"`. It ships for **claude-code** and **opencode** (`/af-orchestrate`); pi orchestrates via the `agent-hub` harness instead.
64
+ ## Origins: from skill library to fleet
40
65
 
41
- `/compound` is the **compound-engineering step**: at the end of a session it extracts the lessons worth keeping (corrections, recurring review findings, root causes), dedupes them against the project's own rule tree, and lands them as minimal diffs on the `rules:`/`docs:` targets declared in `.ai/agent-fleet-overrides.md` — so each session makes the next one better. It ships for **claude-code** and **opencode** (`/af-compound`); on pi the `agent-hub` harness provides its own `/compound` command, which gates the lesson list on the user and dispatches the `documenter` persona to apply it. The process is defined by [compound-learning](skills/compound-learning/SKILL.md).
66
+ Agent Fleet started life as a customized fork of [Addy Osmani](https://github.com/addyosmani)'s [`agent-skills`](https://github.com/addyosmani/agent-skills) — a library of production-grade lifecycle skills — with pi session-harness patterns from [IndyDevDan](https://github.com/disler)'s [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) growing alongside it. As the orchestration layer became the center of gravity, the project **split from the fork lineage and rebranded as Agent Fleet**, and the aim inverted:
42
67
 
43
- Want fewer manual steps once the spec exists? **`/build auto`** generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping *between* tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.
68
+ - **Then:** a skill library you install into one coding agent, with orchestration as an add-on.
69
+ - **Now:** an *operable multi-agent fleet* — dispatcher (`agent-hub`), control plane (herdr), messaging plane (coms), remote control (Hermes) — with the skill library as its **discipline layer**.
44
70
 
45
- Skills also activate automatically based on what you're doing — designing an API triggers `api-and-interface-design`, building UI triggers `frontend-ui-engineering`, and so on.
71
+ The split kept the upstream relationship honest instead of severing it: Addy's library is vendored **pristine at a pinned SHA** under [`vendor/agent-skills-upstream/`](vendor/agent-skills-upstream/) and updated deliberately (policy: [docs/UPSTREAM-SKILLS.md](docs/UPSTREAM-SKILLS.md)), while Agent Fleet-native and customized skills in [`skills/`](skills/) shadow same-named vendored ones. The one-time split record lives in [docs/MIGRATION-agent-fleet.md](docs/MIGRATION-agent-fleet.md); full attribution in [Credits](#credits--inspiration).
46
72
 
47
73
  ---
48
74
 
49
- ## agent-hub: a multi-agent harness for pi
75
+ ## Fleet hierarchy
50
76
 
51
- `agent-hub` turns a single **pi** session into a **dispatcher that drives a live team of specialist subagents** — planner, builder, reviewer, test-engineer, documenter — with read-only research helpers fanning out beneath them, peer-to-peer `coms` messaging embedded, and a `damage-control` guardrail on every tool call.
77
+ Agent Fleet is layered on purpose. Work flows **down** (delegate); evidence and status flow **up** — as compact structured returns, never raw dumps.
52
78
 
53
- ![agent-hub dashboard — the dispatcher grid of specialists and research helpers](docs/assets/agent-hub-dashboard.png)
79
+ ### Hub → team → agents → sub-agents
54
80
 
55
- What makes it different is what it **doesn't** put in front of the dispatcher LLM.
81
+ ```mermaid
82
+ flowchart TD
83
+ You(["You · + Hermes relay on your phone"])
56
84
 
57
- ### Thin dispatcher context
58
-
59
- Multi-agent setups usually drown the orchestrator: every subagent's output, every research dump, every verification note flows back into one context window until it compacts and forgets. `agent-hub` is built the other way around:
60
-
61
- - **Research never enters the dispatcher context.** A specialist that lacks information ends its turn with `NEEDS_RESEARCH:` lines; the hub fans out read-only helpers, writes their findings to disk (`.pi/agent-sessions/findings/`), and resumes the specialist with the file paths. The dispatcher sees a one-line notice — never the raw findings.
62
- - **The Verification Contract lives on disk.** The dispatcher owns a ledger of checkable acceptance assertions, built from the request *before* any builder runs and persisted to disk, rendered as a single status line (`Assertions: 2✓ 1○ 1✗ · open: A4`). A stated requirement is never silently dropped, and the contract survives compaction without re-flooding the context.
63
- - **Specialists run `--no-extensions`.** Tools and credentials stay scoped to the subagent that needs them instead of leaking up into the dispatcher.
85
+ subgraph HUBL["HUB — thin dispatcher (just hub · just hub-team)"]
86
+ Hub["agent-hub harness + orchestrator persona<br/>routes tasks · owns the Verification Contract on disk<br/>never swallows research dumps into its own context"]
87
+ end
64
88
 
65
- Every borrowed idea from another harness passes one test before it lands: *does this persistently enter the dispatcher context?* If yes, it goes to disk or a one-line status instead.
89
+ subgraph TEAML["TEAM — named roster (.pi/agents/teams.yaml)"]
90
+ Team["default: planner · plan-reviewer · builder · test-engineer · code-reviewer · documenter<br/>also: debug · frontend · security · hotfix · release · info"]
91
+ end
66
92
 
67
- ### What's in the box
93
+ subgraph RESL["RESEARCH HELPERS — read-only, always available"]
94
+ Research["researcher (fast tier — simple reads)<br/>deep-researcher (deep tier — hard, cross-cutting questions)"]
95
+ end
68
96
 
69
- - **Dispatcher grid** — a live dashboard of the fixed specialist team from `.pi/agents/teams.yaml`; `Alt+A` toggles the full dashboard and the compact view.
70
- - **Specialist delegation** — `dispatch_agent` sends writable tasks to configured specialists; `/zoom` inspects a live timeline, and kill/restart manage running children.
71
- - **Research helpers** — `spawn_research` / `/research` launch read-only recon: `researcher` on a fast spark model for simple reads, `deep-researcher` on a heavier model for hard, cross-cutting questions.
72
- - **Verification Contract** — `set_assertions` / `update_assertion` / `get_assertions`, driven by the [`orchestrator`](agents/orchestrator.md) persona per the [orchestration-verification](skills/orchestration-verification/SKILL.md) skill.
73
- - **Multi-model, multi-provider** — per-agent `model:` plus a `models:` switch list (`/agent-model <persona>`). Mix subscription and local models per role: cheap recon on a spark model, agentic work on a premium one.
74
- - **Peer-to-peer coms** — the dispatcher is itself a `coms` node: hand a session off to another main agent, or use a peer as a subagent.
75
- - **herdr fleet layer** — [herdr](https://herdr.dev) is the fleet control plane: `just team-up` / `just hub-team` boot whole peer teams as tiled herdr workspaces, coms presence rides herdr's push events (no ping loops), `just team-down` / `team-resume` snapshot and restore teams **with their conversations**, and inside a herdr pane the dispatcher gets fleet tools (`herdr_spawn_peer` / `herdr_read_pane` / `herdr_close_pane` with human confirmation / `herdr_notify`) — all destructive fleet verbs are damage-control-blocked for specialists.
76
- - **Claude Code as a peer** — the [coms bridge](docs/claude-code-coms-bridge.md) makes an interactive Claude Code pane a first-class bidirectional coms peer: pi agents reach it via `coms_send`, and Claude Code asks pi peers questions mid-task via `coms-cli` (`runner: claude-code` in peers.yaml spawns Claude + bridge with one command).
97
+ subgraph SUBL["SUB-AGENTS — focused children, narrow tools + models"]
98
+ Subs["planner → scout · rules · risk<br/>plan-reviewer → feasibility · deps<br/>builder → recon · verifier<br/>test-engineer → coverage-scout · conventions<br/>code-reviewer → preflight · quality · perf · docs<br/>security-auditor → recon · input-sweep · secrets-sweep"]
99
+ end
77
100
 
78
- ![agent-hub compact view with the btw side-session](docs/assets/agent-hub-compact.png)
101
+ You -->|task| Hub
102
+ Hub -->|"dispatch_agent — one persona = one specialist session"| Team
103
+ Hub -->|"spawn_research"| Research
104
+ Research -.->|"findings written to disk — hub gets paths, not dumps"| Hub
105
+ Team -->|"subagents: block (delegate_depth ≥ 1)"| Subs
106
+ Subs -.->|"results return to the parent agent only"| Team
107
+ Team -.->|"structured return + evidence"| Hub
108
+ Hub -.->|"one status line: Assertions: 2✓ 1○ 1✗"| You
109
+ ```
79
110
 
80
- ### Run it
111
+ Every specialist session is one persona from [`agents/`](agents/) — *skills* tell each agent **how** to work; *personas* define **who** they are.
112
+
113
+ ### Same idea as a tree
114
+
115
+ ```text
116
+ hub (orchestrator)
117
+ ├── team: default
118
+ │ ├── planner
119
+ │ │ ├── scout
120
+ │ │ ├── rules
121
+ │ │ └── risk
122
+ │ ├── plan-reviewer
123
+ │ │ ├── feasibility
124
+ │ │ └── deps
125
+ │ ├── builder
126
+ │ │ ├── recon
127
+ │ │ └── verifier
128
+ │ ├── test-engineer
129
+ │ │ ├── coverage-scout
130
+ │ │ └── conventions
131
+ │ ├── code-reviewer
132
+ │ │ ├── preflight
133
+ │ │ ├── quality
134
+ │ │ ├── perf
135
+ │ │ └── docs
136
+ │ └── documenter
137
+ ├── research helpers (spawn_research, any time)
138
+ │ ├── researcher
139
+ │ └── deep-researcher
140
+ └── optional fleet peers (herdr + coms)
141
+ ├── architect / releaser / web-debugger panes
142
+ ├── Claude Code peer (coms bridge)
143
+ └── Hermes (phone human)
144
+ ```
81
145
 
82
- ```bash
83
- just hub # guarded dispatcher + research + coms + orchestrator persona
84
- just hub-solo # same, without the coms layer
146
+ ### Runtime stack (tools the fleet sits on)
85
147
 
86
- # fleet recipes (need a running herdr server — https://herdr.dev)
87
- just team-up full # spawn addressable peers into a tiled herdr workspace
88
- just hub-team docs # hub + a whole team in ONE workspace (hub in the main pane)
89
- just team-snapshot docs # capture session refs while the team runs (crash insurance)
90
- just team-down docs # snapshot + close the workspace cleanly
91
- just team-resume docs # rebuild the grid; pi peers continue their conversations
148
+ ```mermaid
149
+ flowchart TD
150
+ AF["<b>Agent Fleet</b><br/>agent-hub · personas · skills · coms · bridges · CLI"]
151
+ AF -->|primary runtime| PI["<b>pi</b><br/>coding agent — loads harnesses,<br/>extensions, prompts, personas"]
152
+ AF -->|control plane| HERDR["<b>herdr</b><br/>tiled peer workspaces,<br/>presence, snapshot/resume"]
153
+ AF -->|peer + install target| CC["<b>Claude Code</b><br/>bidirectional peer via<br/>the coms bridge"]
154
+ AF -->|install target| OC["<b>OpenCode</b><br/>skill-driven execution<br/>(AGENTS.md + skill tool)"]
155
+ AF -->|remote human| HERMES["<b>Hermes</b><br/>hub questions relayed<br/>to your phone (Telegram)"]
92
156
  ```
93
157
 
94
- `just hub` stacks the `damage-control-continue` guardrail (blocked calls feed back so the dispatcher adapts and keeps going) before `agent-hub`, and re-loads the hard-stop `damage-control` variant into spawned specialists. Fleet recipes refuse with an actionable message when no herdr server answers (`--dry-run` variants work without one). See the [pi extension catalog](docs/pi-extensions.md) for every harness, its setup, and the selective-load model.
158
+ Composition rule: **the hub (or a slash command) orchestrates; personas do not invoke other personas as peers.** Specialists may only fan out to their configured **sub-agents**. Research helpers write findings to disk; the hub resumes specialists with paths, not raw dumps. Full pattern catalog: [references/orchestration-patterns.md](references/orchestration-patterns.md).
95
159
 
96
160
  ---
97
161
 
@@ -190,11 +254,126 @@ Optional suggested npm/pi extension package: `pi-codex-image-gen` adds image-gen
190
254
 
191
255
  pi has native Agent Fleet support via `AGENTS.md` and discoverable skill directories like `.agents/skills/`. It can also expose the lifecycle commands (`/spec`, `/plan`, `/build`, `/test`, `/review`, `/code-simplify`, `/ship`) from `.pi/prompts/`, and repo-provided pi extensions from `.pi/extensions/` (currently: `mcp-bridge`, `chrome-devtools-mcp`, `compact-and-continue`, and `pi-voice-stt` for push-to-talk STT/dictation; one-time `npm ci` required — see setup doc). For clone/symlink setup, install `pi-ask-user` separately with `pi install -l npm:pi-ask-user` unless it is already listed by `pi list`; guided setup may also offer the optional `pi-codex-image-gen` package. See [docs/pi-setup.md](docs/pi-setup.md).
192
256
 
193
- The repo also ships selectable pi session *harnesses* — agent orchestration, safety auditing, and Pi-to-Pi messaging — ported or consolidated from [disler](https://github.com/disler)'s [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) project (MIT). The flagship is [`agent-hub`](#agent-hub-a-multi-agent-harness-for-pi), the multi-agent dispatcher described above (`just hub`). See the [pi extension catalog](docs/pi-extensions.md) for the full list, setup, and how to run each one.
257
+ The repo also ships selectable pi session *harnesses* — agent orchestration, safety auditing, and Pi-to-Pi messaging — ported or consolidated from [@disler](https://github.com/disler)'s [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) project (MIT); see [Credits](#credits--inspiration). The flagship is [`agent-hub`](#agent-hub-a-multi-agent-harness-for-pi), the multi-agent dispatcher (`just hub`). See the [pi extension catalog](docs/pi-extensions.md) for the full list, setup, and how to run each one.
194
258
 
195
259
  </details>
196
260
 
261
+ ---
262
+
263
+ ## agent-hub: a multi-agent harness for pi
264
+
265
+ `agent-hub` turns a single **pi** session into a **dispatcher that drives a live team of specialist subagents** — planner, builder, reviewer, test-engineer, documenter — with read-only research helpers fanning out beneath them, peer-to-peer `coms` messaging embedded, and a `damage-control` guardrail on every tool call.
266
+
267
+ ![agent-hub dashboard — the dispatcher grid of specialists and research helpers](docs/assets/agent-hub-dashboard.png)
268
+
269
+ What makes it different is what it **doesn't** put in front of the dispatcher LLM.
270
+
271
+ ### Thin dispatcher context
272
+
273
+ Multi-agent setups usually drown the orchestrator: every subagent's output, every research dump, every verification note flows back into one context window until it compacts and forgets. `agent-hub` is built the other way around:
274
+
275
+ - **Research never enters the dispatcher context.** A specialist that lacks information ends its turn with `NEEDS_RESEARCH:` lines; the hub fans out read-only helpers, writes their findings to disk (`.pi/agent-sessions/findings/`), and resumes the specialist with the file paths. The dispatcher sees a one-line notice — never the raw findings.
276
+ - **The Verification Contract lives on disk.** The dispatcher owns a ledger of checkable acceptance assertions, built from the request *before* any builder runs and persisted to disk, rendered as a single status line (`Assertions: 2✓ 1○ 1✗ · open: A4`). A stated requirement is never silently dropped, and the contract survives compaction without re-flooding the context.
277
+ - **Specialists run `--no-extensions`.** Tools and credentials stay scoped to the subagent that needs them instead of leaking up into the dispatcher.
278
+
279
+ The whole loop, end to end:
280
+
281
+ ```mermaid
282
+ sequenceDiagram
283
+ autonumber
284
+ actor U as You
285
+ participant H as Hub (dispatcher)
286
+ participant S as Specialist (e.g. builder)
287
+ participant R as Research helper
288
+ participant D as Disk (.pi/agent-sessions/)
289
+
290
+ U->>H: task
291
+ H->>D: set_assertions — Verification Contract persisted
292
+ H->>S: dispatch_agent (task + advisory scope)
293
+ S-->>H: NEEDS_RESEARCH: how does X work?
294
+ H->>R: spawn_research (researcher / deep-researcher)
295
+ R->>D: write findings file
296
+ R-->>H: one-line notice + path
297
+ H->>S: resume with file paths — never raw findings
298
+ S-->>H: structured return + named evidence
299
+ H->>D: update_assertion
300
+ H-->>U: Assertions: 2✓ 1○ 1✗ · open: A4
301
+ ```
302
+
303
+ Every borrowed idea from another harness passes one test before it lands: *does this persistently enter the dispatcher context?* If yes, it goes to disk or a one-line status instead.
304
+
305
+ ### What's in the box
306
+
307
+ - **Dispatcher grid** — a live dashboard of the fixed specialist team from `.pi/agents/teams.yaml`; `Alt+A` toggles the full dashboard and the compact view.
308
+ - **Specialist delegation** — `dispatch_agent` sends writable tasks to configured specialists; `/zoom` inspects a live timeline, and kill/restart manage running children.
309
+ - **Research helpers** — `spawn_research` / `/research` launch read-only recon: `researcher` on the fast tier for simple reads, `deep-researcher` on the deep-reasoning tier for hard, cross-cutting questions.
310
+ - **Verification Contract** — `set_assertions` / `update_assertion` / `get_assertions`, driven by the [`orchestrator`](agents/orchestrator.md) persona per the [orchestration-verification](skills/orchestration-verification/SKILL.md) skill.
311
+ - **Multi-model, multi-provider** — per-agent `model:` plus a `models:` switch list (`/agent-model <persona>`), with named fleet-wide profiles (`/models <profile>`). See [Model tiers](#model-tiers) below.
312
+ - **Peer-to-peer coms** — the dispatcher is itself a `coms` node: hand a session off to another main agent, or use a peer as a subagent.
313
+ - **herdr fleet layer** — [herdr](https://herdr.dev) is the fleet control plane: `just team-up` / `just hub-team` boot whole peer teams as tiled herdr workspaces, coms presence rides herdr's push events (no ping loops), `just team-down` / `team-resume` snapshot and restore teams **with their conversations**, and inside a herdr pane the dispatcher gets fleet tools (`herdr_spawn_peer` / `herdr_read_pane` / `herdr_close_pane` with human confirmation / `herdr_notify`) — all destructive fleet verbs are damage-control-blocked for specialists.
314
+ - **Claude Code as a peer** — the [coms bridge](docs/claude-code-coms-bridge.md) makes an interactive Claude Code pane a first-class bidirectional coms peer: pi agents reach it via `coms_send`, and Claude Code asks pi peers questions mid-task via `coms-cli` (`runner: claude-code` in peers.yaml spawns Claude + bridge with one command).
315
+
316
+ ![agent-hub compact view with the btw side-session](docs/assets/agent-hub-compact.png)
317
+
318
+ ### Model tiers
319
+
320
+ Personas don't hardcode one frontier model. Each declares a default `model:` plus a `models:` switch list, and the defaults follow a **three-tier policy** (current lineup: the OpenAI Codex `gpt-5.6` line, with Ollama cloud models in every switch list as local fallbacks):
321
+
322
+ | Tier | Current default | Used for | Default personas |
323
+ |---|---|---|---|
324
+ | **Deep reasoning** | `gpt-5.6-sol` | planning, architecture, security, hard recon | planner, plan-reviewer, architect, security-auditor, orchestrator, deep-researcher |
325
+ | **Workhorse** | `gpt-5.6-terra` | building, testing, review, docs, release, web audits | builder, test-engineer, code-reviewer, documenter, releaser, web-debugger, web-performance-auditor |
326
+ | **Fast recon** | `gpt-5.6-luna` | light read-only sweeps | researcher, bowser, most delegate sub-agents (scout, preflight, …) |
327
+
328
+ Switch per persona at runtime with `/agent-model <persona>[.<role>]`, or re-point the whole core team in one command with `/models <profile>` — the named profiles live in [.pi/agents/model-profiles.yaml](.pi/agents/model-profiles.yaml) (`max` → core team on the deep-reasoning tier, `budget` → core team on the workhorse tier). Herdr-spawned peers pin the same tiers in [.pi/agents/peers.yaml](.pi/agents/peers.yaml), where `plan-reviewer` and `code-reviewer` run as **Claude Code peers** (`runner: claude-code`) for cross-model review.
329
+
330
+ ### Run it
331
+
332
+ ```bash
333
+ just hub # guarded dispatcher + research + coms + orchestrator persona
334
+ just hub-solo # same, without the coms layer
335
+
336
+ # fleet recipes (need a running herdr server — https://herdr.dev)
337
+ just team-up full # spawn addressable peers into a tiled herdr workspace
338
+ just hub-team docs # hub + a whole team in ONE workspace (hub in the main pane)
339
+ just team-snapshot docs # capture session refs while the team runs (crash insurance)
340
+ just team-down docs # snapshot + close the workspace cleanly
341
+ just team-resume docs # rebuild the grid; pi peers continue their conversations
342
+
343
+ # scope a team to its own coms pool (isolates it from teams in other repos);
344
+ # the flag form matters: `project=af` is a just variable override and is IGNORED
345
+ just hub-team review --project af
346
+ just team-down review --project af
347
+ ```
348
+
349
+ `just hub` stacks the `damage-control-continue` guardrail (blocked calls feed back so the dispatcher adapts and keeps going) before `agent-hub`, and re-loads the hard-stop `damage-control` variant into spawned specialists. Fleet recipes refuse with an actionable message when no herdr server answers (`--dry-run` variants work without one). See the [pi extension catalog](docs/pi-extensions.md) for every harness, its setup, and the selective-load model.
350
+
351
+ ---
352
+
353
+ ## Commands
354
+
355
+ 10 slash commands that map to the development lifecycle. Each one activates the right skills automatically.
356
+
357
+ | What you're doing | Command | Key principle |
358
+ |-------------------|---------|---------------|
359
+ | Define what to build | `/spec` | Spec before code |
360
+ | Plan how to build it | `/plan` | Small, atomic tasks |
361
+ | Build incrementally | `/build` | One slice at a time |
362
+ | Prove it works | `/test` | Tests are proof |
363
+ | Review before merge | `/review` | Improve code health |
364
+ | Audit web performance | `/webperf` | Measure before you optimize |
365
+ | Simplify the code | `/code-simplify` | Clarity over cleverness |
366
+ | Ship to production | `/ship` | Faster is safer |
367
+ | Orchestrate a team | `/orchestrate` | Main session drives subagents |
368
+ | Capture session lessons | `/compound` | Every session improves the next |
369
+
370
+ `/orchestrate` turns the main session into an **orchestrator** that drives a config-defined team of subagents (default `planner` + `builder`, no reviewer), routing them as a runtime roster and handling the `NEEDS_RESEARCH` / `PLAN_FILE` handoffs. The named teams live in `.claude/orchestrate-teams.yaml` (mirroring pi's `.pi/agents/teams.yaml`) and are switchable at runtime: `/orchestrate <team> "<task>"`. It ships for **claude-code** and **opencode** (`/af-orchestrate`); pi orchestrates via the `agent-hub` harness instead.
371
+
372
+ `/compound` is the **compound-engineering step**: at the end of a session it extracts the lessons worth keeping (corrections, recurring review findings, root causes), dedupes them against the project's own rule tree, and lands them as minimal diffs on the `rules:`/`docs:` targets declared in `.ai/agent-fleet-overrides.md` — so each session makes the next one better. It ships for **claude-code** and **opencode** (`/af-compound`); on pi the `agent-hub` harness provides its own `/compound` command, which gates the lesson list on the user and dispatches the `documenter` persona to apply it. The process is defined by [compound-learning](skills/compound-learning/SKILL.md).
373
+
374
+ Want fewer manual steps once the spec exists? **`/build auto`** generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping *between* tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.
197
375
 
376
+ Skills also activate automatically based on what you're doing — designing an API triggers `api-and-interface-design`, building UI triggers `frontend-ui-engineering`, and so on.
198
377
 
199
378
  ---
200
379
 
@@ -229,26 +408,26 @@ Skills live in **two roots**: fleet-native and customized skills in [`skills/`](
229
408
  | Skill | What It Does | Use When |
230
409
  |-------|-------------|----------|
231
410
  | [incremental-implementation](skills/incremental-implementation/SKILL.md) | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |
232
- | [test-driven-development](skills/test-driven-development/SKILL.md) | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |
411
+ | [test-driven-development](vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md) | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |
233
412
  | [context-engineering](skills/context-engineering/SKILL.md) | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops |
234
- | [source-driven-development](skills/source-driven-development/SKILL.md) | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |
235
- | [doubt-driven-development](skills/doubt-driven-development/SKILL.md) | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
413
+ | [source-driven-development](vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md) | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |
414
+ | [doubt-driven-development](vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md) | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
236
415
  | [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |
237
- | [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |
416
+ | [api-and-interface-design](vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md) | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |
238
417
 
239
418
  ### Verify - Prove it works
240
419
 
241
420
  | Skill | What It Does | Use When |
242
421
  |-------|-------------|----------|
243
422
  | [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser |
244
- | [debugging-and-error-recovery](skills/debugging-and-error-recovery/SKILL.md) | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |
423
+ | [debugging-and-error-recovery](vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md) | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |
245
424
 
246
425
  ### Review - Quality gates before merge
247
426
 
248
427
  | Skill | What It Does | Use When |
249
428
  |-------|-------------|----------|
250
429
  | [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |
251
- | [code-simplification](skills/code-simplification/SKILL.md) | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
430
+ | [code-simplification](vendor/agent-skills-upstream/skills/code-simplification/SKILL.md) | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
252
431
  | [security-and-hardening](skills/security-and-hardening/SKILL.md) | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations |
253
432
  | [performance-optimization](skills/performance-optimization/SKILL.md) | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions |
254
433
 
@@ -257,11 +436,11 @@ Skills live in **two roots**: fleet-native and customized skills in [`skills/`](
257
436
  | Skill | What It Does | Use When |
258
437
  |-------|-------------|----------|
259
438
  | [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) |
260
- | [ci-cd-and-automation](skills/ci-cd-and-automation/SKILL.md) | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
439
+ | [ci-cd-and-automation](vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md) | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
261
440
  | [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features |
262
- | [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | Architecture Decision Records, API docs, inline documentation standards - document the *why* | Making architectural decisions, changing APIs, or shipping features |
263
- | [observability-and-instrumentation](skills/observability-and-instrumentation/SKILL.md) | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
264
- | [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production |
441
+ | [documentation-and-adrs](vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md) | Architecture Decision Records, API docs, inline documentation standards - document the *why* | Making architectural decisions, changing APIs, or shipping features |
442
+ | [observability-and-instrumentation](vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md) | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
443
+ | [shipping-and-launch](vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md) | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production |
265
444
 
266
445
  ### Orchestrate - Keep multi-agent runs honest
267
446
 
@@ -292,12 +471,12 @@ This is the compound-engineering loop: the `/compound` command (claude-code, ope
292
471
  | [plan-reviewer](agents/plan-reviewer.md) | Plan critic — stress-tests plans for gaps, ordering, feasibility | read-only | [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | all |
293
472
  | [builder](agents/builder.md) | Implementer — lands changes in small verifiable increments | rw | [incremental-implementation](skills/incremental-implementation/SKILL.md) | all |
294
473
  | [code-reviewer](agents/code-reviewer.md) | Senior staff engineer — five-axis review before merge | read-only | [code-review-and-quality](skills/code-review-and-quality/SKILL.md) | all |
295
- | [test-engineer](agents/test-engineer.md) | QA — test strategy, coverage analysis, the Prove-It pattern | rw | [test-driven-development](skills/test-driven-development/SKILL.md) | all |
474
+ | [test-engineer](agents/test-engineer.md) | QA — test strategy, coverage analysis, the Prove-It pattern | rw | [test-driven-development](vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md) | all |
296
475
  | [security-auditor](agents/security-auditor.md) | Security engineer — vulnerability detection, threat modeling, OWASP | read-only | [security-and-hardening](skills/security-and-hardening/SKILL.md) | all |
297
476
  | [web-performance-auditor](agents/web-performance-auditor.md) | Web performance engineer — Core Web Vitals, loading, rendering, network audits (via `/webperf`) | read-only | [performance-optimization](skills/performance-optimization/SKILL.md) | all |
298
- | [documenter](agents/documenter.md) | Tech writer — READMEs, inline docs, usage examples | rw | [documentation-and-adrs](skills/documentation-and-adrs/SKILL.md) | all |
299
- | [architect](agents/architect.md) | System architect — design decisions and migration strategy | rw | [api-and-interface-design](skills/api-and-interface-design/SKILL.md) | all |
300
- | [releaser](agents/releaser.md) | Release owner — changeset → version-bump → tag flow | rw | [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md), [shipping-and-launch](skills/shipping-and-launch/SKILL.md) | all |
477
+ | [documenter](agents/documenter.md) | Tech writer — READMEs, inline docs, usage examples | rw | [documentation-and-adrs](vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md) | all |
478
+ | [architect](agents/architect.md) | System architect — design decisions and migration strategy | rw | [api-and-interface-design](vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md) | all |
479
+ | [releaser](agents/releaser.md) | Release owner — changeset → version-bump → tag flow | rw | [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md), [shipping-and-launch](vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md) | all |
301
480
  | [researcher](agents/researcher.md) | Fast read-only recon — reports findings with file:line citations | read-only | — | all |
302
481
  | [deep-researcher](agents/deep-researcher.md) | Deep recon for hard, cross-cutting questions | read-only | — | all |
303
482
  | [bowser](agents/bowser.md) | Headless browser automation via Playwright CLI | rw | — | pi only |
@@ -322,11 +501,11 @@ When this repo is installed as a Claude Code plugin, the `agents/` directory is
322
501
 
323
502
  ### Teams of subagents
324
503
 
325
- The personas are designed to be composed, not used one at a time:
504
+ The personas are designed to be composed, not used one at a time. For the full hub → team → agent → sub-agent picture, see [Fleet hierarchy](#fleet-hierarchy).
326
505
 
327
- - **pi (agent-hub harness)** — the dispatcher spawns personas as specialist subagents. Named teams in [.pi/agents/teams.yaml](.pi/agents/teams.yaml) scope which personas it may use: `default` (plan → build → review → document), `debug`, `info`, and `frontend`. `just team-up <name>` instead spawns the [peers.yaml](.pi/agents/peers.yaml) personas (`architect`, `releaser`) as standalone, addressable peers in a tiled [herdr](https://herdr.dev) workspace (requires a running herdr server). Personas with a `subagents:` block (e.g. `code-reviewer`'s `preflight`/`quality`/`perf`/`docs`) additionally delegate slices of their own job to pre-configured children.
328
- - **Claude Code** — installed personas are native subagents: the main agent delegates to them automatically based on their `description`, or you invoke one explicitly ("use the code-reviewer subagent on this diff"). Chain them along the lifecycle: `/plan` work goes to `planner`, then `plan-reviewer` critiques, `builder` implements, and `code-reviewer` + `security-auditor` gate the merge.
329
- - **OpenCode** — installed personas are subagents (`mode: subagent`): mention one with `@<name>` to invoke it directly, or let the primary agent delegate to it by description.
506
+ - **pi (agent-hub harness)** — the dispatcher spawns personas as specialist agents on a named team from [.pi/agents/teams.yaml](.pi/agents/teams.yaml): `default` (plan → build → review → document), `debug`, `frontend`, `security`, `hotfix`, `release`, `info`. `just team-up <name>` instead spawns [peers.yaml](.pi/agents/peers.yaml) personas (e.g. `architect`, `releaser`) as standalone, addressable peers in a tiled [herdr](https://herdr.dev) workspace (requires a running herdr server). Personas with a `subagents:` block (e.g. `code-reviewer`'s `preflight`/`quality`/`perf`/`docs`) additionally delegate slices of their own job to pre-configured children.
507
+ - **Claude Code** — installed personas are native subagents: the main agent delegates to them automatically based on their `description`, or you invoke one explicitly ("use the code-reviewer subagent on this diff"). Chain them along the lifecycle: `/plan` work goes to `planner`, then `plan-reviewer` critiques, `builder` implements, and `code-reviewer` + `security-auditor` gate the merge. `/orchestrate` runs a config-defined roster (see `.claude/orchestrate-teams.yaml`).
508
+ - **OpenCode** — installed personas are subagents (`mode: subagent`): mention one with `@<name>` to invoke it directly, or let the primary agent delegate to it by description. `/af-orchestrate` mirrors the Claude Code roster pattern.
330
509
 
331
510
  ---
332
511
 
@@ -360,7 +539,7 @@ Every skill follows a consistent anatomy:
360
539
  │ │ name: lowercase-hyphen-name │ │
361
540
  │ │ description: Guides agents through [task].│ │
362
541
  │ │ Use when… │ │
363
- │ └───────────────────────────────────────────┘ │
542
+ │ └───────────────────────────────────────────┘ │
364
543
  │ Overview → What this skill does │
365
544
  │ When to Use → Triggering conditions │
366
545
  │ Process → Step-by-step workflow │
@@ -420,6 +599,8 @@ agent-fleet/
420
599
  ├── hermes/ # Hermes-facing skills (hub-conductor, hub-liaison)
421
600
  ├── .claude/commands/ # 12 Claude slash commands
422
601
  ├── .pi/prompts/ # 7 pi prompt-template commands
602
+ ├── .pi/agents/ # teams.yaml · peers.yaml · model-profiles.yaml ·
603
+ │ # chains + dispatch policy for the orchestration harnesses
423
604
  ├── .pi/harnesses/ # Selectable pi session harnesses (agent-hub, coms,
424
605
  │ # damage-control, ask-user-remote)
425
606
  │ # + the shared herdr client/presence lib (.pi/harnesses/lib/)
@@ -431,9 +612,11 @@ agent-fleet/
431
612
 
432
613
  ## Why Agent Fleet?
433
614
 
615
+ **Main purpose:** make multi-agent coding *operable* — a hub team you can run, inspect, and resume — while keeping engineering discipline in the loop.
616
+
434
617
  One coding agent is an assistant; a *fleet* is a team you operate. Agent Fleet exists for the moment a single session stops being enough — when you want a dispatcher driving specialists under a Verification Contract, whole peer teams you can snapshot and resume, Claude Code panes that answer pi agents mid-task, and a phone-reachable human in the loop. Pi is the primary runtime, herdr the control plane, coms the data plane, and Hermes the remote-control layer — with room reserved for Kanban/dashboard modules on top.
435
618
 
436
- Discipline is the other half. AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable. The skill library (fleet-native plus vendored upstream) gives every agent in the fleet structured workflows that enforce the same discipline senior engineers bring to production code: *when* to write a spec, *what* to test, *how* to review, and *when* to ship.
619
+ Discipline is the other half. AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable. The skill library (fleet-native plus vendored upstream from [@addyosmani](https://github.com/addyosmani)) gives every agent in the fleet structured workflows that enforce the same discipline senior engineers bring to production code: *when* to write a spec, *what* to test, *how* to review, and *when* to ship.
437
620
 
438
621
  Skills bake in best practices from Google's engineering culture — including concepts from [Software Engineering at Google](https://abseil.io/resources/swe-book) and Google's [engineering practices guide](https://google.github.io/eng-practices/). You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.
439
622
 
@@ -445,6 +628,40 @@ Wondering how this stacks up against [Superpowers](https://github.com/obra/super
445
628
 
446
629
  ---
447
630
 
631
+ ## Credits & inspiration
632
+
633
+ Agent Fleet stands on excellent open work. Huge shoutout to:
634
+
635
+ | Person | Handle | What we draw from |
636
+ | --- | --- | --- |
637
+ | **IndyDevDan** | [@disler](https://github.com/disler) | Pi session harness patterns from [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) (MIT) — foundation for `agent-hub`, `coms`, `damage-control`, and related harnesses under `.pi/harnesses/`. See [docs/pi-extensions.md](docs/pi-extensions.md). |
638
+ | **Addy Osmani** | [@addyosmani](https://github.com/addyosmani) | Production-grade lifecycle skills from [`agent-skills`](https://github.com/addyosmani/agent-skills) — vendored at a pinned SHA in `vendor/agent-skills-upstream/`, with Agent Fleet-native and customized skills layered on top. See [docs/UPSTREAM-SKILLS.md](docs/UPSTREAM-SKILLS.md). |
639
+
640
+ Thank you both for the inspiration and for shipping work others can build on.
641
+
642
+ ---
643
+
644
+ ## Built on (dependencies & tools)
645
+
646
+ These are the external systems Agent Fleet assumes or integrates with — not npm packages, but the **runtime stack** the fleet operates on top of.
647
+
648
+ | Dependency | Role | Required? |
649
+ | --- | --- | --- |
650
+ | **[pi](https://github.com/badlogic/pi-mono)** (or your pi install) | Primary coding-agent runtime; loads harnesses, extensions, prompts, and personas | Yes for full fleet mode (`just hub`) |
651
+ | **[herdr](https://herdr.dev)** | Workspace control plane: tiled peer panes, presence push events, team snapshot/resume | Yes for fleet recipes (`just team-up`, `just hub-team`, …); optional for solo hub |
652
+ | **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** | First-class peer via the [coms bridge](docs/claude-code-coms-bridge.md); also a supported install target for skills/personas | Optional peer / alternate harness |
653
+ | **[OpenCode](https://opencode.ai)** | Skill-driven execution target (`AGENTS.md` + `skill` tool); `af-*` slash commands | Optional alternate harness |
654
+ | **Hermes** | Remote human-in-the-loop (Telegram relay for hub questions) — [coms-hermes-bridge](docs/coms-hermes-bridge.md) | Optional |
655
+ | **[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)** | Upstream skill library (manually vendored) | Bundled (vendored) |
656
+ | **[disler/pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code)** | Source inspiration / MIT port origin for pi harnesses | Design lineage (ported in-repo) |
657
+ | **LLM providers** | Models per persona (`model:` / `models:` in agent frontmatter) — e.g. OpenAI Codex, GitHub Copilot, Ollama, … | Yes (at least one provider your agents can call) |
658
+ | **Chrome DevTools MCP** / **Playwright Agent CLI** | Browser verify (`browser-testing-with-devtools`) and headless automation (`bowser`) | Optional, feature-specific |
659
+ | **Node.js + npm** | CLI (`npx @chankov/agent-fleet`), package install, `just` recipes | Yes for install & tooling |
660
+
661
+ Architecture map: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
662
+
663
+ ---
664
+
448
665
  ## Contributing
449
666
 
450
667
  Skills should be **specific** (actionable steps, not vague advice), **verifiable** (clear exit criteria with evidence requirements), **battle-tested** (based on real workflows), and **minimal** (only what's needed to guide the agent).
@@ -1,8 +1,10 @@
1
1
  ---
2
2
  name: architect
3
3
  description: System architect — owns design decisions and migration strategy; answers design questions with concrete, justified recommendations.
4
- model: openai-codex/gpt-5.5
4
+ model: openai-codex/gpt-5.6-sol
5
5
  models:
6
+ - openai-codex/gpt-5.6-terra
7
+ - openai-codex/gpt-5.6-luna
6
8
  - ollama/nemotron-3-ultra:cloud
7
9
  - ollama/glm-5.2:cloud
8
10
  thinking: xhigh
package/agents/bowser.md CHANGED
@@ -2,8 +2,9 @@
2
2
  name: bowser
3
3
  description: Headless browser automation agent using Playwright CLI. Use when you need headless browsing, parallel browser sessions, UI testing, screenshots, or web scraping. Supports parallel instances. Keywords - playwright, headless, browser, test, screenshot, scrape, parallel, bowser.
4
4
  tools: read,bash
5
- model: openai-codex/gpt-5.3-codex-spark
5
+ model: openai-codex/gpt-5.6-luna
6
6
  models:
7
+ - openai-codex/gpt-5.6-terra
7
8
  - ollama/minimax-m3:cloud
8
9
  - ollama/nemotron-3-ultra:cloud
9
10
  color: orange
package/agents/builder.md CHANGED
@@ -2,9 +2,10 @@
2
2
  name: builder
3
3
  description: Implementation and code generation — lands changes in small verifiable increments. Use for implementing features, fixes, and refactors once the task is defined.
4
4
  tools: read,write,edit,bash,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-terra
6
6
  models:
7
- - openai-codex/gpt-5.4
7
+ - openai-codex/gpt-5.6-sol
8
+ - openai-codex/gpt-5.6-luna
8
9
  - openai-codex/gpt-5.3-codex-spark
9
10
  - ollama/minimax-m3:cloud
10
11
  - ollama/kimi-k2.7-code:cloud
@@ -2,11 +2,11 @@
2
2
  name: code-reviewer
3
3
  description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
4
4
  tools: read,bash,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-terra
6
6
  models:
7
7
  - github-copilot/claude-opus-4.8
8
- - openai-codex/gpt-5.4
9
- - openai-codex/gpt-5.3-codex-spark
8
+ - openai-codex/gpt-5.6-sol
9
+ - openai-codex/gpt-5.6-luna
10
10
  - github-copilot/claude-sonnet-4.6
11
11
  - github-copilot/claude-haiku-4.5
12
12
  - ollama/nemotron-3-ultra:cloud
@@ -17,16 +17,16 @@ thinking: high
17
17
  delegate_depth: 1
18
18
  subagents:
19
19
  preflight:
20
- model: openai-codex/gpt-5.3-codex-spark
20
+ model: openai-codex/gpt-5.6-luna
21
21
  tools: read,grep,find,ls
22
22
  quality:
23
- model: openai-codex/gpt-5.4
23
+ model: openai-codex/gpt-5.6-terra
24
24
  tools: read,grep,find,ls
25
25
  perf:
26
- model: openai-codex/gpt-5.4
26
+ model: openai-codex/gpt-5.6-terra
27
27
  tools: read,grep,find,ls
28
28
  docs:
29
- model: openai-codex/gpt-5.3-codex-spark
29
+ model: openai-codex/gpt-5.6-luna
30
30
  tools: read,grep,find,ls
31
31
  ---
32
32