Skip to content

Fleet Commander adoption for autonomous agent teams

  • Date: 2026-03-26
  • Status: Accepted
  • Tags: tooling workflow

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_foundations and cyrus repos, adding lifecycle hooks to .claude/settings.json and 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.md as 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.md as 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.