@chankov/agent-fleet 0.0.1 → 0.0.3
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/.claude/commands/doctor-agent-fleet.md +1 -1
- package/.claude/commands/setup-agent-fleet.md +4 -4
- package/.opencode/commands/af-doctor-agent-fleet.md +2 -0
- package/.opencode/commands/af-setup-agent-fleet.md +1 -1
- package/.pi/agents/model-profiles.yaml +12 -12
- package/.pi/agents/peers.yaml +26 -22
- package/.pi/agents/teams.yaml +2 -2
- package/.pi/harnesses/agent-hub/README.md +57 -4
- package/.pi/harnesses/agent-hub/index.ts +236 -80
- package/.pi/harnesses/agent-hub/research-retention.js +34 -0
- package/.pi/harnesses/ask-user-remote/README.md +8 -0
- package/.pi/harnesses/ask-user-remote/index.ts +41 -1
- package/.pi/harnesses/coms/README.md +11 -0
- package/.pi/prompts/doctor-agent-fleet.md +1 -1
- package/.pi/prompts/setup-agent-fleet.md +4 -4
- package/README.md +133 -354
- package/agents/architect.md +4 -2
- 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 +7 -7
- package/agents/releaser.md +3 -1
- package/agents/researcher.md +3 -3
- package/agents/security-auditor.md +7 -7
- package/agents/test-engineer.md +5 -5
- package/agents/web-debugger.md +3 -3
- package/agents/web-performance-auditor.md +3 -3
- package/bin/snapshot-version.js +17 -1
- package/codex/CONDUCTOR.md +148 -0
- package/docs/ARCHITECTURE.md +165 -0
- package/docs/agent-fleet-setup.md +1 -0
- package/docs/claude-code-coms-bridge.md +10 -0
- package/docs/codex-remote-conductor.md +170 -0
- package/docs/coms-hermes-bridge.md +121 -0
- package/docs/getting-started.md +14 -0
- package/docs/npm-install.md +2 -0
- package/docs/pi-extensions.md +16 -0
- package/docs/pi-setup.md +2 -0
- package/hermes/README.md +48 -0
- package/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/justfile +132 -15
- package/package.json +10 -3
- package/scripts/codex-conductor.ts +41 -0
- package/scripts/codex-remote-control.ts +167 -0
- package/scripts/coms-cli.ts +311 -199
- package/scripts/coms-hermes-bridge.ts +8 -4
- package/scripts/lib/codex-conductor.ts +88 -0
- package/scripts/lib/codex-remote-control.ts +480 -0
- package/scripts/lib/coms-envelope.ts +51 -6
- package/scripts/lib/herdr-layout.ts +35 -7
- package/scripts/lib/hermes-bridge-core.ts +4 -4
- package/scripts/lib/spawn-stagger.ts +101 -0
- package/scripts/lib/team-project.ts +112 -3
- package/scripts/lib/team-snapshot.ts +3 -2
- package/scripts/team-snapshot.ts +23 -6
- package/scripts/team-up.ts +106 -18
- package/skills/guided-workspace-setup/SKILL.md +123 -97
- package/skills/guided-workspace-setup/companion-manifest.json +33 -0
- package/skills/peer-coms/SKILL.md +9 -0
- package/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
package/README.md
CHANGED
|
@@ -1,457 +1,236 @@
|
|
|
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 **multi-agent orchestration system for AI coding agents**, built pi-first: a thin dispatcher routes work to specialist agents under a Verification Contract, whole teams spawn as tiled workspaces you can snapshot and resume, agents message each other over a shared coms plane — and a library of **29 production-grade lifecycle skills** and **15 personas** keeps every agent disciplined. Runs on **pi** (primary runtime), **Claude Code**, and **OpenCode**.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+

|
|
10
12
|
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
13
|
+
```text
|
|
14
|
+
You ──▶ Hub (dispatcher) ──▶ Team agents ──▶ Sub-agents
|
|
15
|
+
│ │
|
|
16
|
+
├── herdr (workspace) ├── skills (how to work)
|
|
17
|
+
├── coms (messages) └── Verification Contract
|
|
18
|
+
├── Hermes (phone · inbound ask_user)
|
|
19
|
+
└── Codex Remote Control (phone · outbound delegation, experimental)
|
|
18
20
|
```
|
|
19
21
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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 |
|
|
38
|
-
|
|
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.
|
|
40
|
-
|
|
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).
|
|
42
|
-
|
|
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.
|
|
44
|
-
|
|
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.
|
|
22
|
+
| Layer | Job |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| **[agent-hub](#agent-hub-a-thin-context-dispatcher-for-pi)** | Thin-context dispatcher on **pi** — drives specialists under a Verification Contract |
|
|
25
|
+
| **[herdr](https://herdr.dev)** | Fleet control plane — tiled peer workspaces, presence, snapshot/resume |
|
|
26
|
+
| **coms** | Peer data plane — bidirectional messaging between agents (including Claude Code panes) |
|
|
27
|
+
| **Hermes** | Remote human control — relay hub questions to your phone |
|
|
28
|
+
| **Codex conductor (experimental)** | Android-initiated, approval-gated delegation to live coms peers through a user-systemd service |
|
|
29
|
+
| **[Skills](docs/skills-catalog.md) + [personas](docs/agents.md)** | Lifecycle discipline — how to spec, plan, build, verify, review, and ship |
|
|
46
30
|
|
|
47
31
|
---
|
|
48
32
|
|
|
49
|
-
##
|
|
50
|
-
|
|
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.
|
|
52
|
-
|
|
53
|
-

|
|
54
|
-
|
|
55
|
-
What makes it different is what it **doesn't** put in front of the dispatcher LLM.
|
|
56
|
-
|
|
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.
|
|
64
|
-
|
|
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.
|
|
66
|
-
|
|
67
|
-
### What's in the box
|
|
68
|
-
|
|
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).
|
|
77
|
-
|
|
78
|
-

|
|
33
|
+
## Quick Start
|
|
79
34
|
|
|
80
|
-
###
|
|
35
|
+
### pi (primary runtime)
|
|
81
36
|
|
|
82
37
|
```bash
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
#
|
|
87
|
-
just
|
|
88
|
-
just hub-team docs
|
|
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
|
|
38
|
+
pi install -l npm:@chankov/agent-fleet # project-scoped package: skills, prompts, ask-user
|
|
39
|
+
# then, inside pi:
|
|
40
|
+
# /setup-agent-fleet # guided install of harnesses, personas, extensions
|
|
41
|
+
# and once set up:
|
|
42
|
+
just hub # guarded multi-agent dispatcher
|
|
43
|
+
just hub-team docs # hub + a whole peer team in one tiled herdr workspace
|
|
92
44
|
```
|
|
93
45
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
---
|
|
97
|
-
|
|
98
|
-
## Quick Start
|
|
46
|
+
### Claude Code / OpenCode
|
|
99
47
|
|
|
100
48
|
```bash
|
|
101
|
-
# In the workspace you want to configure:
|
|
102
49
|
npx @chankov/agent-fleet init
|
|
103
|
-
#
|
|
50
|
+
# then open your coding agent in this directory and run:
|
|
104
51
|
# /setup-agent-fleet
|
|
105
52
|
```
|
|
106
53
|
|
|
107
|
-
|
|
108
|
-
(Claude Code, OpenCode, or pi), and `/setup-agent-fleet` runs the full guided install —
|
|
109
|
-
analysing the workspace, showing grouped menus, and confirming everything
|
|
110
|
-
before writing a single file.
|
|
54
|
+
The CLI detects your coding agent and `/setup-agent-fleet` runs the full guided install — analysing the workspace, showing grouped menus, and confirming everything before writing a single file.
|
|
111
55
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
| Command | What it does |
|
|
56
|
+
| CLI command | What it does |
|
|
115
57
|
|---|---|
|
|
116
58
|
| `npx @chankov/agent-fleet init` | Materialize the package + hand off to `/setup-agent-fleet` |
|
|
117
59
|
| `npx @chankov/agent-fleet doctor` | Scan for broken symlinks and stale persona refs |
|
|
118
60
|
| `npx @chankov/agent-fleet update` | Surface the version delta + hand off to `/setup-agent-fleet` for the per-artifact diff |
|
|
119
|
-
| `npx @chankov/agent-fleet transform-persona` | Generate per-agent subagent files from the canonical personas
|
|
120
|
-
|
|
121
|
-
Versioned with [semver](https://semver.org); changelog in
|
|
122
|
-
[CHANGELOG.md](CHANGELOG.md); full docs in [docs/npm-install.md](docs/npm-install.md).
|
|
123
|
-
|
|
124
|
-
### Other install paths
|
|
61
|
+
| `npx @chankov/agent-fleet transform-persona` | Generate per-agent subagent files from the canonical personas |
|
|
125
62
|
|
|
126
63
|
<details>
|
|
127
|
-
<summary><b>
|
|
64
|
+
<summary><b>Other install paths</b> — Claude Code marketplace, git clone + symlinks, OpenCode details</summary>
|
|
65
|
+
|
|
66
|
+
**Claude Code plugin marketplace** — best UX inside Claude Code:
|
|
128
67
|
|
|
129
68
|
```
|
|
130
69
|
/plugin marketplace add chankov/agent-fleet
|
|
131
70
|
/plugin install agent-fleet@nc-agent-fleet
|
|
132
71
|
```
|
|
133
72
|
|
|
134
|
-
> **SSH errors?** The marketplace clones
|
|
135
|
-
> ```bash
|
|
136
|
-
> /plugin marketplace add https://github.com/chankov/agent-fleet.git
|
|
137
|
-
> /plugin install agent-fleet@nc-agent-fleet
|
|
138
|
-
> ```
|
|
139
|
-
|
|
140
|
-
</details>
|
|
73
|
+
> **SSH errors?** The marketplace clones via SSH; use the HTTPS URL instead: `/plugin marketplace add https://github.com/chankov/agent-fleet.git`
|
|
141
74
|
|
|
142
|
-
|
|
143
|
-
<summary><b>Git clone + symlinks</b> — best for skill authors and contributors</summary>
|
|
75
|
+
**Git clone + symlinks** — best for skill authors and contributors:
|
|
144
76
|
|
|
145
77
|
```bash
|
|
146
|
-
git clone https://github.com/chankov/agent-fleet.git
|
|
147
|
-
|
|
148
|
-
#
|
|
149
|
-
claude --plugin-dir .
|
|
150
|
-
# Then run /setup-agent-fleet in your target workspace and pick "symlink" in Step 8.
|
|
78
|
+
git clone https://github.com/chankov/agent-fleet.git && cd agent-fleet
|
|
79
|
+
claude --plugin-dir . # in Claude Code
|
|
80
|
+
# then run /setup-agent-fleet in your target workspace and pick "symlink"
|
|
151
81
|
```
|
|
152
82
|
|
|
153
83
|
Updates flow through `git pull`. Symlinks need Developer Mode on Windows.
|
|
154
84
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
<details>
|
|
158
|
-
<summary><b>OpenCode</b></summary>
|
|
159
|
-
|
|
160
|
-
Uses agent-driven skill execution via `AGENTS.md` and the `skill` tool.
|
|
161
|
-
|
|
162
|
-
The repo also ships **optional** OpenCode slash commands in `.opencode/commands/` using an `af-` prefix as explicit lifecycle entry points (the agent will still invoke the same skills automatically from natural-language requests):
|
|
85
|
+
**OpenCode** — agent-driven skill execution via `AGENTS.md` + the `skill` tool, plus optional `af-*` slash commands (`/af-spec` … `/af-ship`, `/af-orchestrate`, `/af-compound`). See [docs/opencode-setup.md](docs/opencode-setup.md).
|
|
163
86
|
|
|
164
|
-
-
|
|
165
|
-
- `/af-plan`
|
|
166
|
-
- `/af-build`
|
|
167
|
-
- `/af-test`
|
|
168
|
-
- `/af-review`
|
|
169
|
-
- `/af-orchestrate`
|
|
170
|
-
- `/af-code-simplify`
|
|
171
|
-
- `/af-ship`
|
|
172
|
-
- `/af-design-agent`
|
|
173
|
-
|
|
174
|
-
See [docs/opencode-setup.md](docs/opencode-setup.md).
|
|
87
|
+
**pi details** — the package bundles `pi-ask-user` (interactive `ask_user` + skill); lifecycle commands load from `.pi/prompts/`, always-on utility extensions from `.pi/extensions/` (mcp-bridge, chrome-devtools-mcp, compact-and-continue, pi-voice-stt push-to-talk dictation), and the selectable harnesses live under `.pi/harnesses/` (loaded via the `justfile`). See [docs/pi-setup.md](docs/pi-setup.md) and the [pi extension catalog](docs/pi-extensions.md).
|
|
175
88
|
|
|
176
89
|
</details>
|
|
177
90
|
|
|
178
|
-
|
|
179
|
-
<summary><b>pi</b></summary>
|
|
91
|
+
### Experimental: delegate to live peers from ChatGPT Android
|
|
180
92
|
|
|
181
|
-
|
|
93
|
+
The optional Codex Remote-Control conductor is verified on Linux with Codex CLI `0.144.x`. Hermes remains the inbound `ask_user` route; Codex is outbound-only and delegates one confirmed task at a time to peers already visible in the same coms project.
|
|
182
94
|
|
|
183
95
|
```bash
|
|
184
|
-
|
|
96
|
+
cd /path/to/agent-fleet
|
|
97
|
+
just conductor-codex-setup docs --project af # once per configured context
|
|
98
|
+
just conductor-codex-pair # interactive; never capture the code
|
|
99
|
+
just conductor-codex-start
|
|
100
|
+
just hub-team docs --project af # hub + peers Codex can reach
|
|
185
101
|
```
|
|
186
102
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
Optional suggested npm/pi extension package: `pi-codex-image-gen` adds image-generation support and can be selected during guided setup when pi package installation is available, or installed manually with `pi install -l npm:pi-codex-image-gen`. It is not bundled or required; minimal setup works without it. Upstream: <https://github.com/jvm/pi-mono>.
|
|
190
|
-
|
|
191
|
-
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
|
-
|
|
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.
|
|
194
|
-
|
|
195
|
-
</details>
|
|
103
|
+
In ChatGPT Android, open the paired Remote Control host and use the managed external workspace at `$HOME/.local/state/agent-fleet/codex-conductor/workspace`. Do not start a local `codex` process for the Android flow, and do not also launch `conductor-codex docs` when `hub-team docs` already owns the same peers.
|
|
196
104
|
|
|
105
|
+
Lifecycle, approval flow, examples, recovery, and security boundaries: **[Codex Remote-Control conductor runbook](docs/codex-remote-conductor.md)**.
|
|
197
106
|
|
|
107
|
+
Versioned with [semver](https://semver.org) — [CHANGELOG.md](CHANGELOG.md) · [docs/npm-install.md](docs/npm-install.md).
|
|
198
108
|
|
|
199
109
|
---
|
|
200
110
|
|
|
201
|
-
##
|
|
202
|
-
|
|
203
|
-
The commands above are the entry points. Under the hood, they activate these 29 skills — each one a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.
|
|
204
|
-
|
|
205
|
-
Skills live in **two roots**: fleet-native and customized skills in [`skills/`](skills/), and the pristine upstream import in [`vendor/agent-skills-upstream/skills/`](vendor/agent-skills-upstream/). When a name exists in both, the native copy wins — see [docs/UPSTREAM-SKILLS.md](docs/UPSTREAM-SKILLS.md).
|
|
206
|
-
|
|
207
|
-
### Meta - Discover which skill applies
|
|
208
|
-
|
|
209
|
-
| Skill | What It Does | Use When |
|
|
210
|
-
|-------|-------------|----------|
|
|
211
|
-
| [using-agent-skills](skills/using-agent-skills/SKILL.md) | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies |
|
|
212
|
-
|
|
213
|
-
### Define - Clarify what to build
|
|
214
|
-
|
|
215
|
-
| Skill | What It Does | Use When |
|
|
216
|
-
|-------|-------------|----------|
|
|
217
|
-
| [interview-me](skills/interview-me/SKILL.md) | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" |
|
|
218
|
-
| [idea-refine](skills/idea-refine/SKILL.md) | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |
|
|
219
|
-
| [spec-driven-development](skills/spec-driven-development/SKILL.md) | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change |
|
|
220
|
-
|
|
221
|
-
### Plan - Break it down
|
|
111
|
+
## agent-hub: a thin-context dispatcher for pi
|
|
222
112
|
|
|
223
|
-
|
|
224
|
-
|-------|-------------|----------|
|
|
225
|
-
| [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units |
|
|
226
|
-
|
|
227
|
-
### Build - Write the code
|
|
228
|
-
|
|
229
|
-
| Skill | What It Does | Use When |
|
|
230
|
-
|-------|-------------|----------|
|
|
231
|
-
| [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 |
|
|
233
|
-
| [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 |
|
|
236
|
-
| [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 |
|
|
238
|
-
|
|
239
|
-
### Verify - Prove it works
|
|
240
|
-
|
|
241
|
-
| Skill | What It Does | Use When |
|
|
242
|
-
|-------|-------------|----------|
|
|
243
|
-
| [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 |
|
|
245
|
-
|
|
246
|
-
### Review - Quality gates before merge
|
|
247
|
-
|
|
248
|
-
| Skill | What It Does | Use When |
|
|
249
|
-
|-------|-------------|----------|
|
|
250
|
-
| [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 |
|
|
252
|
-
| [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
|
-
| [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
|
-
|
|
255
|
-
### Ship - Deploy with confidence
|
|
113
|
+
`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.
|
|
256
114
|
|
|
257
|
-
|
|
258
|
-
|-------|-------------|----------|
|
|
259
|
-
| [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 |
|
|
261
|
-
| [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 |
|
|
115
|
+
What makes it different is what it **doesn't** put in front of the dispatcher LLM. Multi-agent setups usually drown the orchestrator: every subagent's output, every research dump flows back into one context window until it compacts and forgets. `agent-hub` is built the other way around:
|
|
265
116
|
|
|
266
|
-
|
|
117
|
+
- **Research never enters the dispatcher context.** Specialists end their turn with `NEEDS_RESEARCH:` lines; the hub fans out read-only helpers, writes findings to disk, and resumes the specialist with file paths. The dispatcher sees a one-line notice — never the raw findings.
|
|
118
|
+
- **The Verification Contract lives on disk.** A ledger of checkable acceptance assertions, built from the request *before* any builder runs, rendered as one status line (`Assertions: 2✓ 1○ 1✗ · open: A4`). A stated requirement is never silently dropped, and the contract survives compaction.
|
|
119
|
+
- **Specialists run `--no-extensions`.** Tools and credentials stay scoped to the subagent that needs them instead of leaking up into the dispatcher.
|
|
267
120
|
|
|
268
|
-
|
|
269
|
-
|-------|-------------|----------|
|
|
270
|
-
| [orchestration-verification](skills/orchestration-verification/SKILL.md) | The Verification Contract — dispatcher-owned acceptance assertions, a parity/touchpoint inventory for "behave like X" requests, structured upward returns with named evidence, and a requirement-regression reset | Orchestrating specialists through a dispatcher (the `agent-hub` harness / `orchestrator` persona), a "make X behave like existing Y" change, or a requirement that keeps coming back wrong |
|
|
271
|
-
| [peer-coms](skills/peer-coms/SKILL.md) | Makes Claude Code a first-class peer in the local coms pool — discover pi colleagues with `coms-cli list`, ask/delegate with `send --await`, answer inbound peer questions, never drive panes itself | Claude Code runs in a bridged herdr pane (see the [coms bridge](docs/claude-code-coms-bridge.md)), or an inbound `[coms message from …]` arrives |
|
|
121
|
+

|
|
272
122
|
|
|
273
|
-
|
|
123
|
+
Personas don't hardcode one frontier model — each declares a default plus a switch list on a three-tier policy (deep reasoning / workhorse / fast recon), switchable at runtime per persona (`/agent-model`) or fleet-wide (`/models <profile>`). `plan-reviewer` and `code-reviewer` can run as **Claude Code peers** for cross-model review.
|
|
274
124
|
|
|
275
|
-
|
|
125
|
+
```bash
|
|
126
|
+
just hub # guarded dispatcher + research + coms + orchestrator persona
|
|
127
|
+
just hub-solo # same, without the coms layer
|
|
276
128
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
129
|
+
# fleet recipes (need a running herdr server — https://herdr.dev)
|
|
130
|
+
just team-up full # spawn addressable peers into a tiled herdr workspace
|
|
131
|
+
just hub-team docs # hub + a whole team in ONE workspace
|
|
132
|
+
just team-down docs # snapshot + close cleanly
|
|
133
|
+
just team-resume docs # rebuild the grid; pi peers continue their conversations
|
|
134
|
+
```
|
|
280
135
|
|
|
281
|
-
|
|
136
|
+
Deep dive: [agent-hub harness README](.pi/harnesses/agent-hub/README.md) (the full dispatch loop, coms layer, configuration) · [fleet hierarchy](docs/ARCHITECTURE.md#fleet-hierarchy) · [pi extension catalog](docs/pi-extensions.md) · [Claude Code coms bridge](docs/claude-code-coms-bridge.md) · [Hermes bridge](docs/coms-hermes-bridge.md).
|
|
282
137
|
|
|
283
138
|
---
|
|
284
139
|
|
|
285
|
-
##
|
|
286
|
-
|
|
287
|
-
15 pre-configured specialist personas live in [agents/](agents/) — reusable subagent definitions your coding agent can delegate work to. Each persona is one Markdown file with YAML frontmatter; the canonical format is pi-flavored, and the setup commands transform it per target agent on install (see [Installing personas](#installing-personas)).
|
|
288
|
-
|
|
289
|
-
| Persona | Role | Access | Primary skill | Agents |
|
|
290
|
-
|---|---|---|---|---|
|
|
291
|
-
| [planner](agents/planner.md) | Architect — writes dependency-ordered PLAN files with acceptance criteria | rw (plan file only) | [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md) | all |
|
|
292
|
-
| [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
|
-
| [builder](agents/builder.md) | Implementer — lands changes in small verifiable increments | rw | [incremental-implementation](skills/incremental-implementation/SKILL.md) | all |
|
|
294
|
-
| [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 |
|
|
296
|
-
| [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
|
-
| [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 |
|
|
301
|
-
| [researcher](agents/researcher.md) | Fast read-only recon — reports findings with file:line citations | read-only | — | all |
|
|
302
|
-
| [deep-researcher](agents/deep-researcher.md) | Deep recon for hard, cross-cutting questions | read-only | — | all |
|
|
303
|
-
| [bowser](agents/bowser.md) | Headless browser automation via Playwright CLI | rw | — | pi only |
|
|
304
|
-
| [web-debugger](agents/web-debugger.md) | Interactive headful Chrome debugging via Chrome DevTools MCP (coms peer) | rw | [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) | pi only |
|
|
305
|
-
| [orchestrator](agents/orchestrator.md) | Verification-Contract agent-hub dispatcher — owns acceptance assertions, parity inventory, runtime-proof gate | — | [orchestration-verification](skills/orchestration-verification/SKILL.md) | pi only |
|
|
140
|
+
## The lifecycle: commands and skills
|
|
306
141
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
| Agent | Installed to | Transformation |
|
|
316
|
-
|---|---|---|
|
|
317
|
-
| Claude Code | `.claude/agents/<name>.md` | tools renamed (`read→Read`, `find/ls→Glob`, …), model mapped to `opus`/`sonnet`/`haiku`, agent-hub keys dropped |
|
|
318
|
-
| OpenCode | `.opencode/agent/<name>.md` | `mode: subagent` added, write-capable tools denied per persona, agent-hub keys dropped |
|
|
319
|
-
| pi | `agents/<name>.md` | none — the canonical format is the pi format |
|
|
320
|
-
|
|
321
|
-
When this repo is installed as a Claude Code plugin, the `agents/` directory is auto-discovered — every non-pi-only persona is immediately available as a subagent without a separate install.
|
|
322
|
-
|
|
323
|
-
### Teams of subagents
|
|
324
|
-
|
|
325
|
-
The personas are designed to be composed, not used one at a time:
|
|
142
|
+
```
|
|
143
|
+
DEFINE PLAN BUILD VERIFY REVIEW SHIP
|
|
144
|
+
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
|
|
145
|
+
│ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │ QA │ ───▶ │ Go │
|
|
146
|
+
│Refine│ │ PRD │ │ Impl │ │Debug │ │ Gate │ │ Live │
|
|
147
|
+
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
|
|
148
|
+
/spec /plan /build /test /review /ship
|
|
149
|
+
```
|
|
326
150
|
|
|
327
|
-
|
|
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.
|
|
151
|
+
10 slash commands map to the development lifecycle; each activates the right skills automatically:
|
|
330
152
|
|
|
331
|
-
|
|
153
|
+
| What you're doing | Command | Key principle |
|
|
154
|
+
|-------------------|---------|---------------|
|
|
155
|
+
| Define what to build | `/spec` | Spec before code |
|
|
156
|
+
| Plan how to build it | `/plan` | Small, atomic tasks |
|
|
157
|
+
| Build incrementally | `/build` | One slice at a time (`/build auto` runs the whole plan in one approved pass) |
|
|
158
|
+
| Prove it works | `/test` | Tests are proof |
|
|
159
|
+
| Review before merge | `/review` | Improve code health |
|
|
160
|
+
| Audit web performance | `/webperf` | Measure before you optimize |
|
|
161
|
+
| Simplify the code | `/code-simplify` | Clarity over cleverness |
|
|
162
|
+
| Ship to production | `/ship` | Faster is safer |
|
|
163
|
+
| Orchestrate a team | `/orchestrate` | Main session drives a config-defined subagent roster (claude-code/opencode; pi uses agent-hub) |
|
|
164
|
+
| Capture session lessons | `/compound` | Every session improves the next — lessons land as minimal diffs on your rule tree |
|
|
332
165
|
|
|
333
|
-
|
|
166
|
+
Under the hood are **29 skills** — each a structured workflow with steps, verification gates, and anti-rationalization tables (never vague advice). Skills also activate automatically from what you're doing: designing an API triggers `api-and-interface-design`, building UI triggers `frontend-ui-engineering`.
|
|
334
167
|
|
|
335
|
-
|
|
168
|
+
- **Define:** [interview-me](skills/interview-me/SKILL.md) · [idea-refine](skills/idea-refine/SKILL.md) · [spec-driven-development](skills/spec-driven-development/SKILL.md)
|
|
169
|
+
- **Plan:** [planning-and-task-breakdown](skills/planning-and-task-breakdown/SKILL.md)
|
|
170
|
+
- **Build:** [incremental-implementation](skills/incremental-implementation/SKILL.md) · [test-driven-development](vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md) · [context-engineering](skills/context-engineering/SKILL.md) · [source-driven-development](vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md) · [doubt-driven-development](vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md) · [frontend-ui-engineering](skills/frontend-ui-engineering/SKILL.md) · [api-and-interface-design](vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md)
|
|
171
|
+
- **Verify:** [browser-testing-with-devtools](skills/browser-testing-with-devtools/SKILL.md) · [debugging-and-error-recovery](vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md)
|
|
172
|
+
- **Review:** [code-review-and-quality](skills/code-review-and-quality/SKILL.md) · [code-simplification](vendor/agent-skills-upstream/skills/code-simplification/SKILL.md) · [security-and-hardening](skills/security-and-hardening/SKILL.md) · [performance-optimization](skills/performance-optimization/SKILL.md)
|
|
173
|
+
- **Ship:** [git-workflow-and-versioning](skills/git-workflow-and-versioning/SKILL.md) · [ci-cd-and-automation](vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md) · [deprecation-and-migration](skills/deprecation-and-migration/SKILL.md) · [documentation-and-adrs](vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md) · [observability-and-instrumentation](vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md) · [shipping-and-launch](vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md)
|
|
174
|
+
- **Orchestrate:** [orchestration-verification](skills/orchestration-verification/SKILL.md) · [peer-coms](skills/peer-coms/SKILL.md)
|
|
175
|
+
- **Learn:** [compound-learning](skills/compound-learning/SKILL.md) · **Onboard:** [guided-workspace-setup](skills/guided-workspace-setup/SKILL.md) · **Meta:** [using-agent-skills](skills/using-agent-skills/SKILL.md) · [designing-agents](skills/designing-agents/SKILL.md)
|
|
336
176
|
|
|
337
|
-
|
|
338
|
-
|-----------|--------|
|
|
339
|
-
| [definition-of-done.md](references/definition-of-done.md) | Project-wide standing bar every change clears, contrasted with per-task acceptance criteria |
|
|
340
|
-
| [testing-patterns.md](references/testing-patterns.md) | Test structure, naming, mocking, React/API/E2E examples, anti-patterns |
|
|
341
|
-
| [security-checklist.md](references/security-checklist.md) | Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10 |
|
|
342
|
-
| [performance-checklist.md](references/performance-checklist.md) | Core Web Vitals targets, frontend/backend checklists, measurement commands |
|
|
343
|
-
| [accessibility-checklist.md](references/accessibility-checklist.md) | Keyboard nav, screen readers, visual design, ARIA, testing tools |
|
|
344
|
-
| [observability-checklist.md](references/observability-checklist.md) | On-call questions, structured logging, RED/USE metrics, tracing, symptom-based alerting, pre-launch gate |
|
|
345
|
-
| [orchestration-patterns.md](references/orchestration-patterns.md) | Endorsed multi-persona orchestration patterns, anti-patterns, and the "personas don't invoke personas" rule |
|
|
346
|
-
| [fleet-coordination-patterns.md](references/fleet-coordination-patterns.md) | Runtime coordination protocols between running agents: sentinels, push over polling, barriers, fan-out/fan-in digests, racing with cancellation |
|
|
347
|
-
| [prompting-patterns.md](references/prompting-patterns.md) | Prompt-engineering best practices for authoring personas, commands, skills, pi harnesses, and rule files (Anthropic/OpenAI sourced) |
|
|
177
|
+
Full catalog with descriptions and triggers: **[docs/skills-catalog.md](docs/skills-catalog.md)**. Format spec: [docs/skill-anatomy.md](docs/skill-anatomy.md).
|
|
348
178
|
|
|
349
179
|
---
|
|
350
180
|
|
|
351
|
-
##
|
|
352
|
-
|
|
353
|
-
Every skill follows a consistent anatomy:
|
|
181
|
+
## Agent personas
|
|
354
182
|
|
|
355
|
-
|
|
356
|
-
┌─────────────────────────────────────────────────┐
|
|
357
|
-
│ SKILL.md │
|
|
358
|
-
│ │
|
|
359
|
-
│ ┌─ Frontmatter ─────────────────────────────┐ │
|
|
360
|
-
│ │ name: lowercase-hyphen-name │ │
|
|
361
|
-
│ │ description: Guides agents through [task].│ │
|
|
362
|
-
│ │ Use when… │ │
|
|
363
|
-
│ └───────────────────────────────────────────┘ │
|
|
364
|
-
│ Overview → What this skill does │
|
|
365
|
-
│ When to Use → Triggering conditions │
|
|
366
|
-
│ Process → Step-by-step workflow │
|
|
367
|
-
│ Rationalizations → Excuses + rebuttals │
|
|
368
|
-
│ Red Flags → Signs something's wrong │
|
|
369
|
-
│ Verification → Evidence requirements │
|
|
370
|
-
└─────────────────────────────────────────────────┘
|
|
371
|
-
```
|
|
183
|
+
15 pre-configured specialist personas live in [`agents/`](agents/) — reusable subagent definitions your coding agent delegates work to: `planner`, `plan-reviewer`, `builder`, `code-reviewer`, `test-engineer`, `security-auditor`, `web-performance-auditor`, `documenter`, `architect`, `releaser`, `researcher`, `deep-researcher`, plus the pi-only `bowser`, `web-debugger`, and `orchestrator`.
|
|
372
184
|
|
|
373
|
-
|
|
185
|
+
Each persona is one Markdown file; the canonical format is pi-flavored and `/setup-agent-fleet` transforms it per target agent on install (Claude Code subagents, OpenCode `mode: subagent`, pi as-is). Personas are the *who*, skills are the *how* — each carries a conditional hook to its primary skill, and they compose into teams under the hub or via `/orchestrate`.
|
|
374
186
|
|
|
375
|
-
|
|
376
|
-
- **Anti-rationalization.** Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
|
|
377
|
-
- **Verification is non-negotiable.** Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
|
|
378
|
-
- **Progressive disclosure.** The `SKILL.md` is the entry point. Supporting references load only when needed, keeping token usage minimal.
|
|
187
|
+
Full roster, skill hooks, install matrix, and team composition: **[docs/agents.md](docs/agents.md)**.
|
|
379
188
|
|
|
380
189
|
---
|
|
381
190
|
|
|
382
|
-
##
|
|
191
|
+
## Why Agent Fleet?
|
|
383
192
|
|
|
384
|
-
|
|
193
|
+
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.
|
|
385
194
|
|
|
386
|
-
|
|
387
|
-
|--------|----------------------|
|
|
388
|
-
| `spec-driven-development` | Spec output directory and naming |
|
|
389
|
-
| `planning-and-task-breakdown` | Plan output directory, naming, embedded vs separate todo |
|
|
390
|
-
| `browser-testing-with-devtools` | Dev-server command, base URL, auth flow and roles (required — no default) |
|
|
391
|
-
| `git-workflow-and-versioning` | Whether the agent may create branches (default: never) |
|
|
392
|
-
| `agent-hub` (legacy alias: `## agent-team`) | Dispatcher user-facing language (default: English), per-persona models/thinking/delegation, project `rules:` folders (HOW — resolved index-first) and `docs:` entry points (WHAT/WHY orientation) |
|
|
393
|
-
| `agent-fleet doctor` (`## env`) | Env-var **names** the project expects; the doctor warns when one is unset |
|
|
195
|
+
Discipline is the other half. AI coding agents default to the shortest path — skipping specs, tests, and security reviews. The skill library gives every agent in the fleet the same discipline senior engineers bring to production code, baking in practices from [Software Engineering at Google](https://abseil.io/resources/swe-book) and Google's [engineering practices guide](https://google.github.io/eng-practices/): Hyrum's Law in API design, the test pyramid and Beyonce Rule in testing, change sizing in review, Chesterton's Fence in simplification, trunk-based development in git workflow.
|
|
394
196
|
|
|
395
|
-
|
|
197
|
+
**How it compares:** wondering how this stacks up against [Superpowers](https://github.com/obra/superpowers) or [Matt Pocock's skills](https://github.com/mattpocock/skills)? See **[docs/comparison.md](docs/comparison.md)** — an honest, side-by-side look, including a controlled [head-to-head experiment](https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/).
|
|
396
198
|
|
|
397
199
|
---
|
|
398
200
|
|
|
399
|
-
##
|
|
201
|
+
## Documentation
|
|
400
202
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
│ # at a pinned SHA — see docs/UPSTREAM-SKILLS.md
|
|
414
|
-
├── agents/ # 15 reusable agent personas
|
|
415
|
-
├── references/ # 9 supplementary checklists
|
|
416
|
-
├── hooks/ # Session lifecycle hooks + the coms Stop hook
|
|
417
|
-
├── scripts/ # Fleet tooling: team-up, hub-team, team-snapshot/resume,
|
|
418
|
-
│ # coms-cli, coms-claude-bridge, coms-hermes-bridge
|
|
419
|
-
│ # (+ pure modules in scripts/lib/)
|
|
420
|
-
├── hermes/ # Hermes-facing skills (hub-conductor, hub-liaison)
|
|
421
|
-
├── .claude/commands/ # 12 Claude slash commands
|
|
422
|
-
├── .pi/prompts/ # 7 pi prompt-template commands
|
|
423
|
-
├── .pi/harnesses/ # Selectable pi session harnesses (agent-hub, coms,
|
|
424
|
-
│ # damage-control, ask-user-remote)
|
|
425
|
-
│ # + the shared herdr client/presence lib (.pi/harnesses/lib/)
|
|
426
|
-
└── docs/ # Architecture, setup guides, coms/Hermes bridges,
|
|
427
|
-
# upstream vendoring policy
|
|
428
|
-
```
|
|
203
|
+
| Doc | Covers |
|
|
204
|
+
|---|---|
|
|
205
|
+
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Runtime layers, fleet hierarchy, module map, external dependencies |
|
|
206
|
+
| [docs/getting-started.md](docs/getting-started.md) | First session walkthrough |
|
|
207
|
+
| [docs/skills-catalog.md](docs/skills-catalog.md) | All 29 skills with descriptions and triggers |
|
|
208
|
+
| [docs/agents.md](docs/agents.md) | All 15 personas: roster, skill hooks, install matrix, teams |
|
|
209
|
+
| [docs/pi-setup.md](docs/pi-setup.md) · [docs/pi-extensions.md](docs/pi-extensions.md) | pi install paths, harnesses, and utility extensions |
|
|
210
|
+
| [docs/opencode-setup.md](docs/opencode-setup.md) | OpenCode setup and `af-*` commands |
|
|
211
|
+
| [docs/agent-fleet-setup.md](docs/agent-fleet-setup.md) | Per-project overrides (`.ai/agent-fleet-overrides.md`) — spec/plan paths, dev server, branch policy, dispatcher language, rules/docs targets |
|
|
212
|
+
| [docs/claude-code-coms-bridge.md](docs/claude-code-coms-bridge.md) · [docs/coms-hermes-bridge.md](docs/coms-hermes-bridge.md) · [docs/codex-remote-conductor.md](docs/codex-remote-conductor.md) | Claude Code as a coms peer · phone relay · experimental Codex remote-control operator runbook |
|
|
213
|
+
| [docs/npm-install.md](docs/npm-install.md) | CLI reference, versioning, update flow |
|
|
214
|
+
| [references/](references/) | 9 checklists skills pull in: testing, security, performance, accessibility, observability, orchestration + fleet-coordination + prompting patterns |
|
|
429
215
|
|
|
430
216
|
---
|
|
431
217
|
|
|
432
|
-
##
|
|
433
|
-
|
|
434
|
-
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
|
-
|
|
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.
|
|
437
|
-
|
|
438
|
-
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.
|
|
218
|
+
## Credits & origins
|
|
439
219
|
|
|
440
|
-
|
|
220
|
+
Agent Fleet started as a customized fork of [Addy Osmani](https://github.com/addyosmani)'s [`agent-skills`](https://github.com/addyosmani/agent-skills) library, with pi session-harness patterns from [IndyDevDan](https://github.com/disler)'s [`pi-vs-claude-code`](https://github.com/disler/pi-vs-claude-code) (MIT) growing alongside it. As orchestration became the center of gravity, it split into a standalone project — with the upstream relationship kept honest: Addy's library is vendored **pristine at a pinned SHA** under [`vendor/agent-skills-upstream/`](vendor/agent-skills-upstream/) ([policy](docs/UPSTREAM-SKILLS.md)), and the ported harnesses credit their origin in [docs/pi-extensions.md](docs/pi-extensions.md). Split record: [docs/MIGRATION-agent-fleet.md](docs/MIGRATION-agent-fleet.md).
|
|
441
221
|
|
|
442
|
-
|
|
222
|
+
| Person | Handle | What we draw from |
|
|
223
|
+
| --- | --- | --- |
|
|
224
|
+
| **IndyDevDan** | [@disler](https://github.com/disler) | Pi session harness patterns — foundation for `agent-hub`, `coms`, `damage-control` |
|
|
225
|
+
| **Addy Osmani** | [@addyosmani](https://github.com/addyosmani) | Production-grade lifecycle skills — the vendored upstream skill library |
|
|
443
226
|
|
|
444
|
-
|
|
227
|
+
Thank you both for the inspiration and for shipping work others can build on.
|
|
445
228
|
|
|
446
229
|
---
|
|
447
230
|
|
|
448
231
|
## Contributing
|
|
449
232
|
|
|
450
|
-
Skills should be **specific** (actionable steps
|
|
451
|
-
|
|
452
|
-
See [docs/skill-anatomy.md](docs/skill-anatomy.md) for the format specification and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
453
|
-
|
|
454
|
-
---
|
|
233
|
+
Skills should be **specific** (actionable steps), **verifiable** (clear exit criteria with evidence), **battle-tested** (based on real workflows), and **minimal** (only what's needed to guide the agent). See [docs/skill-anatomy.md](docs/skill-anatomy.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
455
234
|
|
|
456
235
|
## License
|
|
457
236
|
|