Fleet Commander adoption for autonomous agent teams¶
- Date: 2026-03-26
- Status: Accepted
- Tags:
toolingworkflow
Context¶
As the number of documentation tasks, ADRs, and config updates grew across
ai_tooling_foundations and related repos, single-agent Claude Code sessions
became a bottleneck. Each task required a human to drive the session — reading
the issue, planning the approach, writing code, and reviewing the output.
Fleet Commander (FC) is an MCP-based orchestration tool that spawns autonomous multi-agent teams (planner, developer, reviewer) on GitHub issues. It promised to parallelize work across issues while maintaining quality through built-in code review.
Decision¶
We will adopt Fleet Commander v0.0.8 for autonomous agent teams with a human-in-the-loop PR workflow:
- Install FC on
ai_tooling_foundationsandcyrusrepos, adding lifecycle hooks to.claude/settings.jsonand agent definitions to.claude/agents/ - Disable auto-merge on all FC-enabled repos — PRs require human review and manual merge. CLAUDE.md explicitly prohibits agents from running merge commands
- Gitignore worktrees — FC creates working copies at
.claude/worktrees/{team-name}/; these are ephemeral and should not be committed - Exclude
.claude/from linting — FC-generated agent/hook files are third-party content not subject to repo markdown standards - Document FC configuration in
claude/fleet-commander/README.mdas the operational reference for how FC is set up, what tools are available, and known issues
FC teams are launched via fleet_launch_team with a GitHub issue number.
The planner reads the issue and codebase, produces a plan, the developer
executes it, and the reviewer performs a two-pass code review. The team
lead orchestrates the lifecycle and monitors CI.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Continue single-agent sessions only | Does not scale — human must drive each task individually |
| Cyrus (Linear-triggered single agent) | Already in use for simpler tasks but lacks multi-agent review loop |
| Custom multi-agent orchestration | High effort to build; FC provides hooks, dashboards, idle detection, CI integration out of the box |
| Full autonomy with auto-merge | Too risky — FC v0.0.8 has lifecycle bugs and agents can produce incorrect changes that need human review |
Consequences¶
Positive:
- Multiple issues can be worked in parallel without human supervision
- Built-in planner/reviewer loop catches issues before human review
- FC dashboard provides visibility into team status and agent activity
- Lifecycle hooks enable monitoring and automation
Negative / Trade-offs:
- Uses Claude Max subscription capacity (no separate API key)
- FC v0.0.8 has a known TL lifecycle bug where teams don't transition to "done" (issue #47)
.claude/directory contains ~25 FC-generated files that must be excluded from repo linting and pre-commit hooks- FC worktrees can consume significant disk space (~380MB per team with node_modules)
Ongoing obligations:
- Monitor FC version updates and re-evaluate lifecycle bug status
- Clean up stale worktrees after issues are merged/closed
- Maintain
claude/fleet-commander/README.mdas operational reference - Keep CLAUDE.md merge prohibition in sync with FC agent definitions
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.