@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/.pi/agents/model-profiles.yaml +12 -12
- package/.pi/agents/peers.yaml +22 -22
- package/.pi/harnesses/ask-user-remote/README.md +6 -0
- package/.pi/harnesses/ask-user-remote/index.ts +41 -1
- package/README.md +295 -78
- package/agents/architect.md +3 -1
- package/agents/bowser.md +2 -1
- package/agents/builder.md +3 -2
- package/agents/code-reviewer.md +7 -7
- package/agents/deep-researcher.md +3 -3
- package/agents/documenter.md +3 -1
- package/agents/orchestrator.md +5 -3
- package/agents/plan-reviewer.md +5 -5
- package/agents/planner.md +6 -6
- package/agents/releaser.md +3 -1
- package/agents/researcher.md +3 -3
- package/agents/security-auditor.md +6 -6
- package/agents/test-engineer.md +5 -5
- package/agents/web-debugger.md +3 -3
- package/agents/web-performance-auditor.md +3 -3
- package/docs/pi-extensions.md +16 -0
- package/justfile +35 -5
- package/package.json +2 -2
- package/scripts/coms-hermes-bridge.ts +6 -2
- package/scripts/lib/herdr-layout.ts +17 -4
- package/scripts/lib/spawn-stagger.ts +101 -0
- package/scripts/lib/team-project.ts +28 -3
- package/scripts/lib/team-snapshot.ts +3 -2
- package/scripts/team-snapshot.ts +23 -6
- package/scripts/team-up.ts +32 -3
package/README.md
CHANGED
|
@@ -1,12 +1,32 @@
|
|
|
1
1
|
# Agent Fleet
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@chankov/agent-fleet)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](#quick-start)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
**Operate a coding-agent *fleet* — not just one chat session.**
|
|
6
8
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
60
|
+
</details>
|
|
25
61
|
|
|
26
|
-
|
|
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
|
-
|
|
64
|
+
## Origins: from skill library to fleet
|
|
40
65
|
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
75
|
+
## Fleet hierarchy
|
|
50
76
|
|
|
51
|
-
|
|
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
|
-
|
|
79
|
+
### Hub → team → agents → sub-agents
|
|
54
80
|
|
|
55
|
-
|
|
81
|
+
```mermaid
|
|
82
|
+
flowchart TD
|
|
83
|
+
You(["You · + Hermes relay on your phone"])
|
|
56
84
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
70
|
-
-
|
|
71
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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
|
|
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
|
+

|
|
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
|
+

|
|
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
|
|
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).
|
package/agents/architect.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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
|
+
model: openai-codex/gpt-5.6-terra
|
|
6
6
|
models:
|
|
7
|
-
- openai-codex/gpt-5.
|
|
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
|
package/agents/code-reviewer.md
CHANGED
|
@@ -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
|
+
model: openai-codex/gpt-5.6-terra
|
|
6
6
|
models:
|
|
7
7
|
- github-copilot/claude-opus-4.8
|
|
8
|
-
- openai-codex/gpt-5.
|
|
9
|
-
- openai-codex/gpt-5.
|
|
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.
|
|
20
|
+
model: openai-codex/gpt-5.6-luna
|
|
21
21
|
tools: read,grep,find,ls
|
|
22
22
|
quality:
|
|
23
|
-
model: openai-codex/gpt-5.
|
|
23
|
+
model: openai-codex/gpt-5.6-terra
|
|
24
24
|
tools: read,grep,find,ls
|
|
25
25
|
perf:
|
|
26
|
-
model: openai-codex/gpt-5.
|
|
26
|
+
model: openai-codex/gpt-5.6-terra
|
|
27
27
|
tools: read,grep,find,ls
|
|
28
28
|
docs:
|
|
29
|
-
model: openai-codex/gpt-5.
|
|
29
|
+
model: openai-codex/gpt-5.6-luna
|
|
30
30
|
tools: read,grep,find,ls
|
|
31
31
|
---
|
|
32
32
|
|