Evolve Agentic Development: Integrate Claude Agent Teams with BMAD Workflow

[don-petry]

Summary

Analysis of how to improve our specification-driven development approach by integrating the new Claude Agent Teams capability with our existing BMAD Method workflow. Goal: highest-quality design, implementation, and testing across all petry-projects repos.

Current State (Working Well)

• BMAD installed across 8 repos with structured planning artifacts (PRD, Architecture, UX, Epics/Stories)
• Org-wide standards in AGENTS.md enforcing TDD, SOLID, DDD, CLEAN, DRY, KISS, YAGNI
• CI quality gates: CodeQL, SonarCloud, CodeRabbit, Copilot, lint, type-check, test + coverage
• Git worktree-based multi-agent isolation (3-5 parallel agents per repo)
• Pre-commit checks enforced on all repos

Proposed Improvements

1. Adopt Claude Agent Teams (Experimental)

Agent Teams adds real-time peer collaboration on top of our worktree isolation model:

• Peer-to-peer messaging between teammates (vs current report-back-to-lead only)
• Shared task list with automatic dependency tracking and unblocking
• Full 1M context per teammate with shared CLAUDE.md inheritance
• Lifecycle hooks (TeammateIdle, TaskCreated, TaskCompleted) for automated quality enforcement

Enable with:

// settings.json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

2. Wire Lifecycle Hooks to Quality Gates

• TaskCompleted → run lint + type-check + test suite before accepting task as done
• TeammateIdle → trigger bmad-code-review (adversarial review) automatically
• TaskCreated → validate task has corresponding BMAD story with acceptance criteria

3. Map BMAD Stories to Agent Team Tasks

• Each BMAD story → one Agent Team task
• Story dependencies from epics.md → task dependency chains
• Story acceptance criteria → TaskCompleted hook validation
• Create a task template that bridges BMAD story format to Agent Team task format

4. Strengthen Non-Code Quality Coverage

• Run bmad-testarch-trace for traceability matrices (FR → tests → code)
• Run bmad-testarch-nfr for systematic NFR assessment (performance, security)
• Add bmad-review-edge-case-hunter as a post-implementation gate
• Automate these as part of the sprint completion workflow

5. Cross-Repo Consistency

• Create shared subagent definition library (e.g., security-reviewer, test-architect) reusable across all repos
• Pin BMAD version across all repos to prevent drift
• Ensure npx bmad-method install runs with a consistent version

Proposed Workflow Evolution

BMAD Planning Phase (unchanged)
  ├── Product Brief → PRD → Architecture → UX → Epics/Stories
  └── bmad-check-implementation-readiness

Sprint Execution (enhanced with Agent Teams)
  ├── Lead: bmad-sprint-planning → creates Agent Team tasks from stories
  ├── Teammate A: Story S-x.1 (frontend component)
  ├── Teammate B: Story S-x.2 (API endpoint)
  ├── Teammate C: Story S-x.3 (E2E tests) [blocked on A+B]
  └── Hooks: TaskCompleted → pre-commit + bmad-code-review

Quality Gates (strengthened)
  ├── Per-task: lint/type/test via lifecycle hooks
  ├── Per-PR: CI pipeline (CodeQL, SonarCloud, CodeRabbit, coverage)
  ├── Per-epic: bmad-testarch-trace for FR coverage
  └── Per-sprint: bmad-retrospective for process improvement

Implementation Steps

1. Trial: Enable Agent Teams on one repo (markets or broodly) and run a single sprint
2. Task template: Create a mapping from BMAD story files to Agent Team task format
3. Hooks: Wire TaskCompleted hooks to pre-commit and code review checks
4. Traceability: Run bmad-testarch-trace on most mature repo to assess FR-to-test gaps
5. Version pin: Lock BMAD version across all repos
6. Evaluate: Run bmad-retrospective after trial sprint to assess impact

Key Considerations

• Agent Teams is experimental — requires Claude Code v2.1.32+
• Token usage scales linearly (3-agent team ≈ 3x tokens)
• No session resumption with in-process teammates yet
• Split panes only work in tmux or iTerm2
• Max one team per session; no nested teams