@chankov/agent-fleet

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)

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.

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

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"

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:

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

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.

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.