Agent Fleet

Operate a coding-agent fleet — not just one chat session.

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.

  You  ──▶  Hub (dispatcher)  ──▶  Team agents  ──▶  Sub-agents
                │                      │
                ├── herdr (workspace)  ├── skills (how to work)
                ├── coms (messages)    └── Verification Contract
                ├── Hermes (phone · inbound ask_user)
                └── Codex Remote Control (phone · outbound delegation, experimental)

Layer	Job
agent-hub	Thin-context dispatcher on pi — drives specialists under a Verification Contract
herdr	Fleet control plane — tiled peer workspaces, presence, snapshot/resume
coms	Peer data plane — bidirectional messaging between agents (including Claude Code panes)
Hermes	Remote human control — relay hub questions to your phone
Codex conductor (experimental)	Android-initiated, approval-gated delegation to live coms peers through a user-systemd service
Skills + personas	Lifecycle discipline — how to spec, plan, build, verify, review, and ship

---

Quick Start

pi (primary runtime)

pi install -l npm:@chankov/agent-fleet   # project-scoped package: skills, prompts, ask-user
# then, inside pi:
#   /setup-agent-fleet                    # guided install of harnesses, personas, extensions
# and once set up:
just hub          # guarded multi-agent dispatcher
just hub-team docs  # hub + a whole peer team in one tiled herdr workspace

Claude Code / OpenCode

npx @chankov/agent-fleet init
# then open your coding agent in this directory and run:
#   /setup-agent-fleet

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.

CLI command	What it does
npx @chankov/agent-fleet init	Materialize the package + hand off to /setup-agent-fleet
npx @chankov/agent-fleet doctor	Scan for broken symlinks and stale persona refs
npx @chankov/agent-fleet update	Surface the version delta + hand off to /setup-agent-fleet for the per-artifact diff
npx @chankov/agent-fleet transform-persona	Generate per-agent subagent files from the canonical personas

Claude Code plugin marketplace — best UX inside Claude Code:

/plugin marketplace add chankov/agent-fleet
/plugin install agent-fleet@nc-agent-fleet

SSH errors? The marketplace clones via SSH; use the HTTPS URL instead: /plugin marketplace add https://github.com/chankov/agent-fleet.git

Git clone + symlinks — best for skill authors and contributors:

git clone https://github.com/chankov/agent-fleet.git && cd agent-fleet
claude --plugin-dir .    # in Claude Code
# then run /setup-agent-fleet in your target workspace and pick "symlink"

Updates flow through git pull. Symlinks need Developer Mode on Windows.

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.

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 and the pi extension catalog.

Experimental: delegate to live peers from ChatGPT Android

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.

cd /path/to/agent-fleet
just conductor-codex-setup docs --project af   # once per configured context
just conductor-codex-pair                       # interactive; never capture the code
just conductor-codex-start
just hub-team docs --project af                 # hub + peers Codex can reach

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.

Lifecycle, approval flow, examples, recovery, and security boundaries: Codex Remote-Control conductor runbook.

Versioned with semver — CHANGELOG.md · docs/npm-install.md.

---

agent-hub: a thin-context dispatcher for pi

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.

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:

• 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.
• 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.
• Specialists run --no-extensions. Tools and credentials stay scoped to the subagent that needs them instead of leaking up into the dispatcher.

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.

just hub              # guarded dispatcher + research + coms + orchestrator persona
just hub-solo         # same, without the coms layer

# fleet recipes (need a running herdr server — https://herdr.dev)
just team-up full     # spawn addressable peers into a tiled herdr workspace
just hub-team docs    # hub + a whole team in ONE workspace
just team-down docs   # snapshot + close cleanly
just team-resume docs # rebuild the grid; pi peers continue their conversations

Deep dive: agent-hub harness README (the full dispatch loop, coms layer, configuration) · fleet hierarchy · pi extension catalog · Claude Code coms bridge · Hermes bridge.

---

The lifecycle: commands and skills

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

10 slash commands map to the development lifecycle; each activates the right skills automatically:

What you're doing	Command	Key principle
Define what to build	/spec	Spec before code
Plan how to build it	/plan	Small, atomic tasks
Build incrementally	/build	One slice at a time (/build auto runs the whole plan in one approved pass)
Prove it works	/test	Tests are proof
Review before merge	/review	Improve code health
Audit web performance	/webperf	Measure before you optimize
Simplify the code	/code-simplify	Clarity over cleverness
Ship to production	/ship	Faster is safer
Orchestrate a team	/orchestrate	Main session drives a config-defined subagent roster (claude-code/opencode; pi uses agent-hub)
Capture session lessons	/compound	Every session improves the next — lessons land as minimal diffs on your rule tree

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.

• Define: interview-me · idea-refine · spec-driven-development
• Plan: planning-and-task-breakdown
• Build: incremental-implementation · test-driven-development · context-engineering · source-driven-development · doubt-driven-development · frontend-ui-engineering · api-and-interface-design
• Verify: browser-testing-with-devtools · debugging-and-error-recovery
• Review: code-review-and-quality · code-simplification · security-and-hardening · performance-optimization
• Ship: git-workflow-and-versioning · ci-cd-and-automation · deprecation-and-migration · documentation-and-adrs · observability-and-instrumentation · shipping-and-launch
• Orchestrate: orchestration-verification · peer-coms
• Learn: compound-learning · Onboard: guided-workspace-setup · Meta: using-agent-skills · designing-agents

Full catalog with descriptions and triggers: docs/skills-catalog.md. Format spec: docs/skill-anatomy.md.

---

Agent personas

15 pre-configured specialist personas live in 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.

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.

Full roster, skill hooks, install matrix, and team composition: docs/agents.md.

---

Why Agent Fleet?

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.

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 and Google's engineering practices guide: 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.

How it compares: wondering how this stacks up against Superpowers or Matt Pocock's skills? See docs/comparison.md — an honest, side-by-side look, including a controlled head-to-head experiment.

---

Documentation

Doc	Covers
docs/ARCHITECTURE.md	Runtime layers, fleet hierarchy, module map, external dependencies
docs/getting-started.md	First session walkthrough
docs/skills-catalog.md	All 29 skills with descriptions and triggers
docs/agents.md	All 15 personas: roster, skill hooks, install matrix, teams
docs/pi-setup.md · docs/pi-extensions.md	pi install paths, harnesses, and utility extensions
docs/opencode-setup.md	OpenCode setup and af-* commands
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
docs/claude-code-coms-bridge.md · docs/coms-hermes-bridge.md · docs/codex-remote-conductor.md	Claude Code as a coms peer · phone relay · experimental Codex remote-control operator runbook
docs/npm-install.md	CLI reference, versioning, update flow
references/	9 checklists skills pull in: testing, security, performance, accessibility, observability, orchestration + fleet-coordination + prompting patterns

---

Credits & origins

Agent Fleet started as a customized fork of Addy Osmani's agent-skills library, with pi session-harness patterns from IndyDevDan's 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/ (policy), and the ported harnesses credit their origin in docs/pi-extensions.md. Split record: docs/MIGRATION-agent-fleet.md.

Person	Handle	What we draw from
IndyDevDan	@disler	Pi session harness patterns — foundation for agent-hub, coms, damage-control
Addy Osmani	@addyosmani	Production-grade lifecycle skills — the vendored upstream skill library

Thank you both for the inspiration and for shipping work others can build on.

---

Contributing

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 and CONTRIBUTING.md.

License

MIT - use these skills in your projects, teams, and tools.