Agent Teams

AgileFlow integrates with Claude Code's native Agent Teams to coordinate multiple specialized agents working together on complex tasks. A team lead orchestrates domain experts (API, UI, testing, security) who work in parallel with shared task lists, inter-agent messaging, and quality gates.

When Agent Teams isn't available, AgileFlow falls back to its subagent orchestrator model, producing the same results through a different execution mechanism.

How It Works

AgileFlow wraps Claude Code's Agent Teams with project-aware coordination:

1. You start a team from a predefined template (or the /babysit mentor auto-detects when a team is needed)
2. A team lead spawns specialized teammates, each running as an independent Claude Code session
3. Teammates work in parallel on their assigned domain (backend, frontend, testing, etc.)
4. Quality gates enforce standards (tests pass, no lint errors, no type errors) before work is accepted
5. Task synchronization keeps AgileFlow's status.json in sync with Claude Code's native task list
6. A messaging bridge translates between AgileFlow's internal bus and Claude Code's inter-agent messaging

Dual-Mode Architecture

AgileFlow supports two execution modes. Both produce the same results:

Native Agent Teams Mode (Recommended)

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is enabled, teammates run as fully independent Claude Code sessions:

Team Lead (delegate mode - coordinates only, no direct implementation)
  |-- Teammate A (independent session, file-locked)
  |-- Teammate B (independent session, file-locked)
  |-- Teammate C (independent session, file-locked)
  |-- Shared task list (~/.claude/tasks/)

Advantages:

• Each teammate has its own context window (no context bloat)
• File-locking prevents concurrent modification conflicts
• Teammates can message each other directly
• Better for long-running, complex work

Subagent Orchestrator Mode (Fallback)

When Agent Teams is not enabled, AgileFlow uses its built-in orchestrator with subagents:

Orchestrator (coordinates via Task tool)
  |-- Task -> Expert A (within shared context)
  |-- Task -> Expert B (within shared context)
  |-- Task -> Expert C (within shared context)
  |-- AgileFlow bus messaging (docs/09-agents/bus/log.jsonl)

Advantages:

• Works in any environment (no experimental flag needed)
• Lower token cost (results summarized back to orchestrator)
• Simpler debugging (everything in one session)
• Better for short, focused tasks

Getting Started

Enable Agent Teams

Copyexport CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or add to your Claude Code settings:

Copy{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Start a Team

/agileflow:team:start fullstack

Check Available Templates

/agileflow:team:list

Monitor Team Status

/agileflow:team:status

Stop a Team

/agileflow:team:stop

Team Templates

AgileFlow includes 4 predefined team templates for common development patterns:

fullstack

Full-stack feature development with integrated testing.

Best for: Building features that span backend and frontend with automated testing.

code-review

Comprehensive code review from multiple quality perspectives.

Best for: Thorough code reviews where security, performance, and general quality are all important.

builder-validator

Paired builders and validators for high-confidence implementations.

Best for: Critical features where every implementation must be independently verified.

code-logic

Deep analysis of complex logic with multiple specialized analyzers.

Best for: Finding bugs in complex algorithms, async code, or critical business logic.

Custom Templates

Create your own templates in .agileflow/teams/<name>.json:

Copy{
  "name": "my-team",
  "description": "Custom team for my project",
  "lead": {
    "agent": "team-lead",
    "delegate_mode": true,
    "plan_approval": true
  },
  "teammates": [
    {
      "agent": "agileflow-api",
      "role": "builder",
      "domain": "backend",
      "description": "Implements API endpoints"
    },
    {
      "agent": "agileflow-testing",
      "role": "validator",
      "domain": "quality",
      "description": "Validates implementations"
    }
  ],
  "quality_gates": {
    "teammate_idle": { "tests": true, "lint": true, "types": false },
    "task_completed": { "require_validator_approval": false }
  }
}

Quality Gates

Quality gates enforce standards automatically via Claude Code hooks. They prevent incomplete or broken code from being accepted.

TeammateIdle Gate

Runs when a teammate finishes work and is about to go idle.

• Script: scripts/teammate-idle-gate.js
• Exit 0: Allow teammate to go idle (work accepted)
• Exit 2: Block idle, display failures (teammate must fix issues)

Checks: Tests passing, lint passing, type checking, code coverage threshold.

TaskCompleted Gate

Runs when a builder marks a task as complete.

• Script: scripts/task-completed-gate.js
• Exit 0: Allow task completion
• Exit 2: Block completion until validator approves

Checks: Validator approval (for builder-validator teams), test coverage threshold.

Configuration

Configure quality gates via /agileflow:configure or directly in your config:

Copyquality_gates:
  teammate_idle:
    tests: required
    lint: required
    types: optional
    coverage: 75
  task_completed:
    validator_approval: required
    test_coverage: 80

Task Synchronization

Tasks are bidirectionally synchronized between two systems:

When a teammate completes a task, the result syncs to status.json. When the team shuts down, all final states reconcile back to AgileFlow's status tracking.

Messaging Bridge

The messaging bridge (scripts/messaging-bridge.js) translates between:

• AgileFlow bus (docs/09-agents/bus/log.jsonl) - internal message logging
• Claude Code inter-agent messaging - native teammate communication

All messages flow through both systems, giving you full observability regardless of which mode you're using.

Integration with /babysit

The /babysit mentor deeply integrates with Agent Teams, automatically detecting when a team is needed and managing the full lifecycle.

Smart Detection

During its initial context gathering phase, /babysit checks for team mode signals:

When detected, babysit reports:

Smart Detection Results:
  Team Mode: ENABLED (epic has AG-API + AG-UI stories)
  Template: fullstack (auto-selected)

How Babysit Delegates to Teams

When team mode is active, /babysit changes its delegation behavior:

1. Without teams: Babysit spawns individual domain experts via the Task tool for each piece of work
2. With teams: Babysit starts a team via /team:start and the team lead coordinates all teammates in parallel

This means multi-domain stories that would normally require sequential expert spawning (API first, then UI, then testing) can run all three teammates simultaneously with file-locking preventing conflicts.

Task Registry Integration

Babysit tracks team tasks through AgileFlow's task registry:

1. Before spawning: Checks for running duplicates to avoid conflicts
2. During work: Registers tasks with story IDs for traceability
3. On completion: Marks tasks complete and triggers validator chains (for builder-validator teams)
4. Quality gates: Enforces test/lint/type checks before accepting teammate output

Override

If babysit auto-detects team mode but you prefer individual expert delegation:

Copy/agileflow:babysit TEAM=false

Or say "no teams" in your initial message to babysit.

When to Use Agent Teams vs Subagents

Related Commands