agent-fleet: Instructions file for Claude Code

agent-fleet

This is the Agent Fleet project — a Pi-centered multi-agent orchestration system (agent-hub dispatcher, herdr fleet control plane, coms peer messaging, Hermes remote control) plus a library of production-grade engineering skills for AI coding agents. Lifecycle skills are partly vendored from upstream addyosmani/agent-skills — see docs/UPSTREAM-SKILLS.md.

Project Philosophy

Read docs/PHILOSOPHY.md before proposing or revising Agent Fleet plans, architecture, or process changes. Plans and design reviews must include a proportionate alignment note, distinguish current guarantees from proposals, and surface conflicts for a maintainer decision. Keep the principles in that canonical document rather than duplicating them here.

Project Structure

bin/          → npm CLI: cli.js (agent-fleet entrypoint) + the deterministic installer engine in lib/ — manifest.js (catalogue), state.js (record + hashing), verify.js (evaluation), plan.js (decision), apply.js (the ONLY module that writes to a workspace), merge-forms.js (justfile region + settings.json keys); plus doctor/detect-agent/personas, build-manifest.js, snapshot-version.js, test/ (node --test)
install-manifest.json → GENERATED catalogue of every installable artifact — never hand-edit; run `node bin/build-manifest.js`
manifest-meta.json    → the hand-edited half: groups, profiles, recommendations, consent classes, companion/requires/pinnedBy wiring, operator steps
skills/       → Agent Fleet-native + customized skills (SKILL.md per directory); shadows same-named vendored skills
vendor/agent-skills-upstream/ → Pristine upstream skill import at a pinned SHA — NEVER edit in place; policy + update procedure in docs/UPSTREAM-SKILLS.md
agents/       → 15 reusable agent personas, canonical pi frontmatter; installed as verbatim copies into a workspace's `.pi/agents/personas/` (no per-agent translation — pi is the only install target)
.pi/agent-fleet/ → THE FLEET RUNTIME, mirrored verbatim into a workspace. Source layout == installed layout, which is what lets the installer copy it with `preserveLayout`. Sub-trees:
.pi/agent-fleet/scripts/      → Standalone scripts (team-up herdr launcher for reusable coms peers; peer-launch single-peer `just fleet peer` launcher; .pi/agent-fleet/scripts/lib/ pure fleet modules under node --test)
.pi/agent-fleet/scripts/workflows/ → Headless `just flow` graphs and their code-owned phase, envelope, gate, permission, quality, change-capture, trace, and scoped TypeScript runtime
.pi/agent-fleet/hermes/       → Hermes-facing skills (hub-conductor, hub-liaison) for remote conduction — see docs/coms-hermes-bridge.md
.pi/agent-fleet/hooks/        → Session lifecycle hooks (the Claude Code bridge Stop hook; registering it in `.claude/settings.json` stays the user's step)
                 (a workspace also gets .pi/agent-fleet/docs/workflows.md — the one doc that installs)
justfile      → Recipes to launch pi with each harness plus the single public `flow` entry point
.changeset/   → Pending changesets; rolled into CHANGELOG.md + version bump by `changeset version`
.versions/    → Per-version artifact snapshots used by the version-aware update flow (snapshot-version.js)
.github/workflows/release.yml → On merge to main: opens "Version Packages" PR or runs `changeset publish`
.pi/prompts/  → pi-native lifecycle prompt templates
.pi/extensions/ → always-on pi utility extensions, auto-discovered by pi (mcp-bridge, chrome-devtools-mcp, compact-and-continue, btw, pi-voice-stt). pi-voice-stt is gated/optional — it binds its Alt+S hotkey only when an STT provider is configured, otherwise it is a no-op. The package update check is a Fleet Core helper (`.pi/harnesses/lib/update-check.ts`) scheduled by damage-control-continue, not an auto-discovered extension.
.pi/harnesses/ → selectable pi session harnesses — NOT auto-discovered; loaded explicitly via the justfile or `pi -e` (`just fleet hub` loads Fleet Core before agent-hub; every native child gets damage-control-continue)
.pi/agents/   → pi YAML configs (teams, chains, peers, dispatch-policy) used by the orchestration harnesses, plus `personas/` where the installer writes the 15 personas; dispatch-policy.yaml routes dispatch_agent calls to same-name coms peers (e.g. the `runner: claude-code` reviewers) with native fallback
.pi/skills/   → pi-runtime skills (e.g. bowser browser automation)
.pi/damage-control-rules.yaml → rule set for the damage-control harness
references/   → Supplementary checklists (testing, performance, security, accessibility, observability); each installs as a companion of the skills that cite it
docs/         → ARCHITECTURE.md (runtime layers + module map), UPSTREAM-SKILLS.md (vendoring policy — update it when touching vendor/ or shadowed skills), MIGRATION-agent-fleet.md (major-release migration matrix), setup guides, agent-fleet-setup.md (per-project overrides + ownership), npm-install.md (deterministic lifecycle reference), claude-code-coms-bridge.md and coms-hermes-bridge.md (bridge references), plus pi-extensions.md and pi-specs/ for the pi extensions