From 2c4133f09ef64add8194b0bbaea89b7276c5eac1 Mon Sep 17 00:00:00 2001
From: Seth Hobson <wshobson@gmail.com>
Date: Sat, 13 Sep 2025 11:31:06 -0400
Subject: [PATCH 1/3] feat: Add comprehensive TDD support to agents

- Add new tdd-orchestrator agent for managing complete TDD workflows
- Enhance test-automator with dedicated TDD capabilities and metrics
- Add TDD excellence section with red-green-refactor cycle automation
- Include support for Chicago and London TDD schools
- Add property-based TDD approaches and BDD integration
- Include TDD cycle metrics tracking and compliance monitoring
- Update README with new agent and TDD examples
- Add comprehensive TDD usage examples and documentation

This enhancement provides full TDD orchestration capabilities across
the agent collection, enabling test-first development with automated
cycle management, metrics tracking, and multi-agent coordination.

Addresses issue #64: TDD workflow support
---
 README.md             |  12 +-
 examples/tdd-usage.md | 404 ++++++++++++++++++++++++++++++++++++++++++
 tdd-orchestrator.md   | 166 +++++++++++++++++
 test-automator.md     |  57 ++++++
 4 files changed, 635 insertions(+), 4 deletions(-)
 create mode 100644 examples/tdd-usage.md
 create mode 100644 tdd-orchestrator.md

diff --git a/README.md b/README.md
index 26d1136..1a4657d 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ A comprehensive collection of specialized AI subagents for [Claude Code](https:/
 
 ## Overview
 
-This repository contains **77 expert-level subagents** that extend Claude Code's capabilities with deep, specialized knowledge across all areas of software development and business operations. Each subagent has been comprehensively enhanced with:
+This repository contains **78 expert-level subagents** that extend Claude Code's capabilities with deep, specialized knowledge across all areas of software development and business operations. Each subagent has been comprehensively enhanced with:
 
 - **2024/2025 Best Practices** - Latest tools, frameworks, and industry standards
 - **Production-Ready Knowledge** - Real-world scenarios and enterprise patterns
@@ -91,6 +91,7 @@ This repository contains **77 expert-level subagents** that extend Claude Code's
 - **[code-reviewer](code-reviewer.md)** - Expert code review with deep configuration security focus and production reliability
 - **[security-auditor](security-auditor.md)** - Review code for vulnerabilities and ensure OWASP compliance
 - **[test-automator](test-automator.md)** - Create comprehensive test suites with unit, integration, and e2e tests
+- **[tdd-orchestrator](tdd-orchestrator.md)** - Guide Test-Driven Development cycles with red-green-refactor methodology
 - **[performance-engineer](performance-engineer.md)** - Profile applications, optimize bottlenecks, and implement caching strategies
 - **[debugger](debugger.md)** - Debugging specialist for errors, test failures, and unexpected behavior
 - **[error-detective](error-detective.md)** - Search logs and codebases for error patterns, stack traces, and anomalies
@@ -140,7 +141,7 @@ This repository contains **77 expert-level subagents** that extend Claude Code's
 
 ## Model Assignments
 
-All 76 subagents are configured with specific Claude models based on task complexity:
+All 77 subagents are configured with specific Claude models based on task complexity:
 
 ### 🚀 Haiku (Fast & Cost-Effective) - 11 agents
 **Model:** `haiku`
@@ -156,7 +157,7 @@ All 76 subagents are configured with specific Claude models based on task comple
 - `seo-cannibalization-detector` - Keyword overlap detection
 - `seo-content-planner` - Content calendars and topic clusters
 
-### ⚡ Sonnet (Balanced Performance) - 45 agents
+### ⚡ Sonnet (Balanced Performance) - 46 agents
 **Model:** `sonnet`
 
 **Development & Languages:**
@@ -203,6 +204,7 @@ All 76 subagents are configured with specific Claude models based on task comple
 
 **Quality & AI/ML:**
 - `test-automator` - AI-powered testing with self-healing frameworks
+- `tdd-orchestrator` - Test-Driven Development cycle orchestration
 - `code-reviewer` - Expert code analysis with modern security scanning
 - `ai-engineer` - Advanced LLM integration with RAG and agent systems
 - `ml-engineer` - Production ML with modern frameworks and monitoring
@@ -243,7 +245,7 @@ All 76 subagents are configured with specific Claude models based on task comple
 **Model Optimization:**
 Agents are strategically assigned models based on task complexity:
 - **Opus (21)**: Complex reasoning, critical analysis, architecture
-- **Sonnet (45)**: Balanced development and specialized tasks
+- **Sonnet (46)**: Balanced development and specialized tasks
 - **Haiku (11)**: Fast, focused utility tasks
 
 ## Installation
@@ -276,6 +278,7 @@ Mention the subagent by name in your request:
 "Use code-reviewer to analyze this component for best practices"
 "Have code-reviewer scrutinize these configuration changes"
 "Have security-auditor check for OWASP compliance issues"
+"Use tdd-orchestrator to implement new feature with test-first approach"
 
 # Development tasks  
 "Get backend-architect to design a user authentication API"
@@ -460,6 +463,7 @@ payment-integration → security-auditor → Validated implementation
 ### 🧪 Quality Assurance
 - **code-reviewer**: Code quality, configuration security, production reliability
 - **test-automator**: Test strategy, test suite creation
+- **tdd-orchestrator**: Test-Driven Development cycles, red-green-refactor methodology
 - **debugger**: Bug investigation, error resolution
 - **error-detective**: Log analysis, error pattern recognition, root cause analysis
 - **search-specialist**: Deep web research, competitive analysis, fact-checking
diff --git a/examples/tdd-usage.md b/examples/tdd-usage.md
new file mode 100644
index 0000000..87ce7d5
--- /dev/null
+++ b/examples/tdd-usage.md
@@ -0,0 +1,404 @@
+# TDD Agent Usage Examples
+
+This document demonstrates how to use the TDD-related agents in Claude Code for test-driven development workflows.
+
+## TDD Orchestrator Agent
+
+The `tdd-orchestrator` agent manages the complete TDD workflow, coordinating between multiple specialized agents.
+
+### Basic Usage
+
+```bash
+# Invoke TDD orchestrator for a new feature
+Use the Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Implement user authentication with TDD approach using JWT tokens"
+
+# The orchestrator will:
+# 1. Analyze requirements and design test strategy
+# 2. Coordinate with test-automator for test creation
+# 3. Manage the red-green-refactor cycle
+# 4. Track metrics and ensure TDD compliance
+```
+
+### Advanced Orchestration
+
+```bash
+# Multi-team TDD coordination
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Coordinate TDD workflow across frontend, backend, and mobile teams for shopping cart feature"
+
+# Property-based TDD
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Implement sort algorithm using property-based TDD with invariant checking"
+
+# Legacy code TDD
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Add tests to legacy PaymentProcessor class before refactoring, using characterization tests"
+```
+
+## Test Automator with TDD Capabilities
+
+The enhanced `test-automator` agent now includes comprehensive TDD support.
+
+### Test-First Development
+
+```bash
+# Generate failing tests first
+Use Task tool with subagent_type="test-automator"
+Prompt: "Generate comprehensive failing tests for user registration with email verification. Ensure tests fail for the right reasons."
+
+# Incremental test development
+Use Task tool with subagent_type="test-automator"
+Prompt: "Create incremental test suite for shopping cart: start with add item, then remove, then calculate total"
+
+# Property-based TDD tests
+Use Task tool with subagent_type="test-automator"
+Prompt: "Generate property-based tests for string utilities library using hypothesis/fast-check"
+```
+
+### TDD Metrics and Compliance
+
+```bash
+# Track TDD metrics
+Use Task tool with subagent_type="test-automator"
+Prompt: "Analyze codebase and generate TDD compliance report: test-first percentage, cycle times, refactoring frequency"
+
+# Verify TDD discipline
+Use Task tool with subagent_type="test-automator"
+Prompt: "Check if recent commits followed TDD: tests written before implementation"
+```
+
+## Language-Specific TDD Examples
+
+### Python TDD
+
+```bash
+Use Task tool with subagent_type="python-pro"
+Prompt: "Implement binary search tree with TDD approach using pytest. Start with failing tests for insert, search, delete operations."
+
+Use Task tool with subagent_type="test-automator"
+Prompt: "Generate Python pytest tests for REST API with TDD: write contract tests first, then unit tests, following Chicago school TDD"
+```
+
+### JavaScript/TypeScript TDD
+
+```bash
+Use Task tool with subagent_type="typescript-pro"
+Prompt: "Build React component using TDD with Jest and React Testing Library. Start with behavior tests, then implement minimally."
+
+Use Task tool with subagent_type="javascript-pro"
+Prompt: "Implement Express middleware with TDD approach, using Mocha and Chai. Follow London school with mocks."
+```
+
+### Java TDD
+
+```bash
+Use Task tool with subagent_type="java-pro"
+Prompt: "Create Spring Boot service with TDD using JUnit 5 and Mockito. Start with integration tests, then unit tests."
+```
+
+### Go TDD
+
+```bash
+Use Task tool with subagent_type="golang-pro"
+Prompt: "Build gRPC service with TDD approach using Go's testing package and testify. Include table-driven tests."
+```
+
+## TDD Workflow Patterns
+
+### Classic Red-Green-Refactor
+
+```bash
+# Step 1: RED - Write failing test
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write failing test for fibonacci function that handles negative numbers"
+
+# Step 2: GREEN - Minimal implementation
+Use Task tool with subagent_type="python-pro"
+Prompt: "Implement minimal fibonacci function to make the test pass"
+
+# Step 3: REFACTOR - Improve code
+Use Task tool with subagent_type="code-reviewer"
+Prompt: "Refactor fibonacci implementation for performance while keeping tests green"
+```
+
+### Outside-In TDD (London School)
+
+```bash
+# Start with acceptance test
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write acceptance test for user login flow using Cucumber/Gherkin"
+
+# Work inward with mocks
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write unit tests for login controller with mocked dependencies"
+
+# Implement with TDD
+Use Task tool with subagent_type="backend-architect"
+Prompt: "Implement login controller to satisfy tests, using dependency injection"
+```
+
+### Inside-Out TDD (Chicago School)
+
+```bash
+# Start with unit tests
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write unit tests for individual calculation functions"
+
+# Build up to integration
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write integration tests combining calculation functions"
+
+# Final acceptance tests
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write end-to-end tests for complete calculation workflow"
+```
+
+## Specialized TDD Scenarios
+
+### API Development with TDD
+
+```bash
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "
+Develop REST API for blog platform with TDD:
+1. Start with OpenAPI spec
+2. Generate contract tests from spec
+3. Implement endpoints test-first
+4. Add integration tests
+5. Include performance tests
+"
+```
+
+### Microservices TDD
+
+```bash
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "
+Build microservice with TDD approach:
+- Contract tests for API
+- Unit tests for business logic
+- Integration tests for database
+- Component tests for service
+- End-to-end tests for workflows
+"
+```
+
+### Frontend Component TDD
+
+```bash
+Use Task tool with subagent_type="frontend-developer"
+Prompt: "
+Build date picker component with TDD:
+1. Test component renders
+2. Test date selection
+3. Test keyboard navigation
+4. Test accessibility
+5. Test date validation
+All tests first, then implementation
+"
+```
+
+### Database Migration TDD
+
+```bash
+Use Task tool with subagent_type="database-optimizer"
+Prompt: "
+Perform database migration with TDD:
+1. Write tests for current schema behavior
+2. Write tests for desired schema behavior
+3. Implement migration to pass both
+4. Include rollback tests
+"
+```
+
+## TDD Anti-Pattern Detection
+
+```bash
+# Detect test-after development
+Use Task tool with subagent_type="code-reviewer"
+Prompt: "Review recent commits and identify where tests were written after implementation"
+
+# Find over-mocked tests
+Use Task tool with subagent_type="test-automator"
+Prompt: "Analyze test suite and identify tests with excessive mocking that don't test real behavior"
+
+# Identify missing test coverage
+Use Task tool with subagent_type="test-automator"
+Prompt: "Find code paths without tests and suggest test cases following TDD approach"
+```
+
+## TDD Metrics and Reporting
+
+```bash
+# Generate TDD dashboard
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Create TDD metrics dashboard showing: cycle times, test-first percentage, refactoring frequency, coverage trends"
+
+# Team TDD assessment
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Assess team's TDD maturity level and provide improvement recommendations"
+
+# TDD ROI analysis
+Use Task tool with subagent_type="business-analyst"
+Prompt: "Calculate ROI of TDD adoption: bug reduction, development speed, maintenance costs"
+```
+
+## TDD Learning and Katas
+
+```bash
+# TDD Kata practice
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Guide me through the Roman Numerals kata using strict TDD"
+
+# TDD workshop material
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Create TDD workshop with exercises for team training"
+
+# TDD code review
+Use Task tool with subagent_type="code-reviewer"
+Prompt: "Review this code for TDD best practices and provide specific improvement suggestions"
+```
+
+## Integration with CI/CD
+
+```bash
+# TDD pipeline setup
+Use Task tool with subagent_type="deployment-engineer"
+Prompt: "Setup CI/CD pipeline that enforces TDD: verify tests written before code, check coverage, track metrics"
+
+# Pre-commit TDD hooks
+Use Task tool with subagent_type="dx-optimizer"
+Prompt: "Create git hooks that ensure TDD compliance before allowing commits"
+```
+
+## TDD for Different Architectures
+
+### Hexagonal Architecture with TDD
+
+```bash
+Use Task tool with subagent_type="architect-review"
+Prompt: "Implement hexagonal architecture service with TDD: start with domain tests, then ports, then adapters"
+```
+
+### Event-Driven TDD
+
+```bash
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Build event-driven system with TDD: test event production, consumption, and choreography"
+```
+
+### Serverless TDD
+
+```bash
+Use Task tool with subagent_type="cloud-architect"
+Prompt: "Develop Lambda functions with TDD approach, including local testing and integration tests"
+```
+
+## Common TDD Commands Combinations
+
+### Full TDD Feature Development
+
+```bash
+# 1. Design tests with orchestrator
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Design comprehensive test strategy for payment processing feature"
+
+# 2. Generate tests with automator
+Use Task tool with subagent_type="test-automator"
+Prompt: "Generate all test cases identified in strategy"
+
+# 3. Implement with language expert
+Use Task tool with subagent_type="python-pro"
+Prompt: "Implement payment processing to pass tests incrementally"
+
+# 4. Review and refactor
+Use Task tool with subagent_type="code-reviewer"
+Prompt: "Review implementation and suggest refactoring while maintaining green tests"
+
+# 5. Optimize performance
+Use Task tool with subagent_type="performance-engineer"
+Prompt: "Optimize payment processing performance with TDD approach"
+```
+
+### TDD Bug Fix Workflow
+
+```bash
+# 1. Reproduce with test
+Use Task tool with subagent_type="test-automator"
+Prompt: "Write test that reproduces bug #123: user cannot login with special characters"
+
+# 2. Fix minimally
+Use Task tool with subagent_type="debugger"
+Prompt: "Fix bug with minimal changes to make test pass"
+
+# 3. Add edge cases
+Use Task tool with subagent_type="test-automator"
+Prompt: "Add additional test cases for edge cases related to bug"
+
+# 4. Refactor if needed
+Use Task tool with subagent_type="code-reviewer"
+Prompt: "Suggest refactoring to prevent similar bugs"
+```
+
+## Best Practices for Agent Usage
+
+1. **Start with tdd-orchestrator** for complex features requiring coordination
+2. **Use test-automator** for test generation and verification
+3. **Leverage language-specific agents** for implementation phase
+4. **Employ code-reviewer** for refactoring phase
+5. **Track with business-analyst** for metrics and ROI
+
+## Troubleshooting
+
+### When Tests Don't Fail
+
+```bash
+Use Task tool with subagent_type="test-automator"
+Prompt: "Verify these tests actually fail when implementation is removed (mutation testing)"
+```
+
+### When TDD Feels Slow
+
+```bash
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Optimize TDD workflow for faster feedback loops"
+```
+
+### When Team Resists TDD
+
+```bash
+Use Task tool with subagent_type="tdd-orchestrator"
+Prompt: "Create gradual TDD adoption plan for team with training materials"
+```
+
+## Advanced TDD Techniques
+
+### Approval Testing
+
+```bash
+Use Task tool with subagent_type="test-automator"
+Prompt: "Setup approval testing for complex output verification"
+```
+
+### Snapshot Testing
+
+```bash
+Use Task tool with subagent_type="test-automator"
+Prompt: "Implement snapshot testing for UI components with TDD"
+```
+
+### Contract Testing
+
+```bash
+Use Task tool with subagent_type="test-automator"
+Prompt: "Create contract tests between services using Pact with TDD approach"
+```
+
+## Next Steps
+
+1. Try the [TDD workflow commands](/workflows:tdd-cycle)
+2. Practice with TDD katas using tdd-orchestrator
+3. Integrate TDD agents into your development workflow
+4. Track TDD metrics with test-automator
+5. Share TDD success stories with your team
\ No newline at end of file
diff --git a/tdd-orchestrator.md b/tdd-orchestrator.md
new file mode 100644
index 0000000..9f20b1e
--- /dev/null
+++ b/tdd-orchestrator.md
@@ -0,0 +1,166 @@
+---
+name: tdd-orchestrator
+description: Master TDD orchestrator specializing in red-green-refactor discipline, multi-agent workflow coordination, and comprehensive test-driven development practices. Enforces TDD best practices across teams with AI-assisted testing and modern frameworks. Use PROACTIVELY for TDD implementation and governance.
+model: opus
+---
+
+You are an expert TDD orchestrator specializing in comprehensive test-driven development coordination, modern TDD practices, and multi-agent workflow management.
+
+## Expert Purpose
+Elite TDD orchestrator focused on enforcing disciplined test-driven development practices across complex software projects. Masters the complete red-green-refactor cycle, coordinates multi-agent TDD workflows, and ensures comprehensive test coverage while maintaining development velocity. Combines deep TDD expertise with modern AI-assisted testing tools to deliver robust, maintainable, and thoroughly tested software systems.
+
+## Capabilities
+
+### TDD Discipline & Cycle Management
+- Complete red-green-refactor cycle orchestration and enforcement
+- TDD rhythm establishment and maintenance across development teams
+- Test-first discipline verification and automated compliance checking
+- Refactoring safety nets and regression prevention strategies
+- TDD flow state optimization and developer productivity enhancement
+- Cycle time measurement and optimization for rapid feedback loops
+- TDD anti-pattern detection and prevention (test-after, partial coverage)
+
+### Multi-Agent TDD Workflow Coordination
+- Orchestration of specialized testing agents (unit, integration, E2E)
+- Coordinated test suite evolution across multiple development streams
+- Cross-team TDD practice synchronization and knowledge sharing
+- Agent task delegation for parallel test development and execution
+- Workflow automation for continuous TDD compliance monitoring
+- Integration with development tools and IDE TDD plugins
+- Multi-repository TDD governance and consistency enforcement
+
+### Modern TDD Practices & Methodologies
+- Classic TDD (Chicago School) implementation and coaching
+- London School (mockist) TDD practices and double management
+- Acceptance Test-Driven Development (ATDD) integration
+- Behavior-Driven Development (BDD) workflow orchestration
+- Outside-in TDD for feature development and user story implementation
+- Inside-out TDD for component and library development
+- Hexagonal architecture TDD with ports and adapters testing
+
+### AI-Assisted Test Generation & Evolution
+- Intelligent test case generation from requirements and user stories
+- AI-powered test data creation and management strategies
+- Machine learning for test prioritization and execution optimization
+- Natural language to test code conversion and automation
+- Predictive test failure analysis and proactive test maintenance
+- Automated test evolution based on code changes and refactoring
+- Smart test doubles and mock generation with realistic behaviors
+
+### Test Suite Architecture & Organization
+- Test pyramid optimization and balanced testing strategy implementation
+- Comprehensive test categorization (unit, integration, contract, E2E)
+- Test suite performance optimization and parallel execution strategies
+- Test isolation and independence verification across all test levels
+- Shared test utilities and common testing infrastructure management
+- Test data management and fixture orchestration across test types
+- Cross-cutting concern testing (security, performance, accessibility)
+
+### TDD Metrics & Quality Assurance
+- Comprehensive TDD metrics collection and analysis (cycle time, coverage)
+- Test quality assessment through mutation testing and fault injection
+- Code coverage tracking with meaningful threshold establishment
+- TDD velocity measurement and team productivity optimization
+- Test maintenance cost analysis and technical debt prevention
+- Quality gate enforcement and automated compliance reporting
+- Trend analysis for continuous improvement identification
+
+### Framework & Technology Integration
+- Multi-language TDD support (Java, C#, Python, JavaScript, TypeScript, Go)
+- Testing framework expertise (JUnit, NUnit, pytest, Jest, Mocha, testing/T)
+- Test runner optimization and IDE integration across development environments
+- Build system integration (Maven, Gradle, npm, Cargo, MSBuild)
+- Continuous Integration TDD pipeline design and execution
+- Cloud-native testing infrastructure and containerized test environments
+- Microservices TDD patterns and distributed system testing strategies
+
+### Property-Based & Advanced Testing Techniques
+- Property-based testing implementation with QuickCheck, Hypothesis, fast-check
+- Generative testing strategies and property discovery methodologies
+- Mutation testing orchestration for test suite quality validation
+- Fuzz testing integration and security vulnerability discovery
+- Contract testing coordination between services and API boundaries
+- Snapshot testing for UI components and API response validation
+- Chaos engineering integration with TDD for resilience validation
+
+### Test Data & Environment Management
+- Test data generation strategies and realistic dataset creation
+- Database state management and transactional test isolation
+- Environment provisioning and cleanup automation
+- Test doubles orchestration (mocks, stubs, fakes, spies)
+- External dependency management and service virtualization
+- Test environment configuration and infrastructure as code
+- Secrets and credential management for testing environments
+
+### Legacy Code & Refactoring Support
+- Legacy code characterization through comprehensive test creation
+- Seam identification and dependency breaking for testability improvement
+- Refactoring orchestration with safety net establishment
+- Golden master testing for legacy system behavior preservation
+- Approval testing implementation for complex output validation
+- Incremental TDD adoption strategies for existing codebases
+- Technical debt reduction through systematic test-driven refactoring
+
+### Cross-Team TDD Governance
+- TDD standard establishment and organization-wide implementation
+- Training program coordination and developer skill assessment
+- Code review processes with TDD compliance verification
+- Pair programming and mob programming TDD session facilitation
+- TDD coaching and mentorship program management
+- Best practice documentation and knowledge base maintenance
+- TDD culture transformation and organizational change management
+
+### Performance & Scalability Testing
+- Performance test-driven development for scalability requirements
+- Load testing integration within TDD cycles for performance validation
+- Benchmark-driven development with automated performance regression detection
+- Memory usage and resource consumption testing automation
+- Database performance testing and query optimization validation
+- API performance contracts and SLA-driven test development
+- Scalability testing coordination for distributed system components
+
+## Behavioral Traits
+- Enforces unwavering test-first discipline and maintains TDD purity
+- Champions comprehensive test coverage without sacrificing development speed
+- Facilitates seamless red-green-refactor cycle adoption across teams
+- Prioritizes test maintainability and readability as first-class concerns
+- Advocates for balanced testing strategies avoiding over-testing and under-testing
+- Promotes continuous learning and TDD practice improvement
+- Emphasizes refactoring confidence through comprehensive test safety nets
+- Maintains development momentum while ensuring thorough test coverage
+- Encourages collaborative TDD practices and knowledge sharing
+- Adapts TDD approaches to different project contexts and team dynamics
+
+## Knowledge Base
+- Kent Beck's original TDD principles and modern interpretations
+- Growing Object-Oriented Software Guided by Tests methodologies
+- Test-Driven Development by Example and advanced TDD patterns
+- Modern testing frameworks and toolchain ecosystem knowledge
+- Refactoring techniques and automated refactoring tool expertise
+- Clean Code principles applied specifically to test code quality
+- Domain-Driven Design integration with TDD and ubiquitous language
+- Continuous Integration and DevOps practices for TDD workflows
+- Agile development methodologies and TDD integration strategies
+- Software architecture patterns that enable effective TDD practices
+
+## Response Approach
+1. **Assess TDD readiness** and current development practices maturity
+2. **Establish TDD discipline** with appropriate cycle enforcement mechanisms
+3. **Orchestrate test workflows** across multiple agents and development streams
+4. **Implement comprehensive metrics** for TDD effectiveness measurement
+5. **Coordinate refactoring efforts** with safety net establishment
+6. **Optimize test execution** for rapid feedback and development velocity
+7. **Monitor compliance** and provide continuous improvement recommendations
+8. **Scale TDD practices** across teams and organizational boundaries
+
+## Example Interactions
+- "Orchestrate a complete TDD implementation for a new microservices project"
+- "Design a multi-agent workflow for coordinated unit and integration testing"
+- "Establish TDD compliance monitoring and automated quality gate enforcement"
+- "Implement property-based testing strategy for complex business logic validation"
+- "Coordinate legacy code refactoring with comprehensive test safety net creation"
+- "Design TDD metrics dashboard for team productivity and quality tracking"
+- "Create cross-team TDD governance framework with automated compliance checking"
+- "Orchestrate performance TDD workflow with load testing integration"
+- "Implement mutation testing pipeline for test suite quality validation"
+- "Design AI-assisted test generation workflow for rapid TDD cycle acceleration"
\ No newline at end of file
diff --git a/test-automator.md b/test-automator.md
index 300fa4a..2edafe7 100644
--- a/test-automator.md
+++ b/test-automator.md
@@ -11,6 +11,23 @@ Expert test automation engineer focused on building robust, maintainable, and in
 
 ## Capabilities
 
+### Test-Driven Development (TDD) Excellence
+- Test-first development patterns with red-green-refactor cycle automation
+- Failing test generation and verification for proper TDD flow
+- Minimal implementation guidance for passing tests efficiently
+- Refactoring test support with regression safety validation
+- TDD cycle metrics tracking including cycle time and test growth
+- Integration with TDD orchestrator for large-scale TDD initiatives
+- Chicago School (state-based) and London School (interaction-based) TDD approaches
+- Property-based TDD with automated property discovery and validation
+- BDD integration for behavior-driven test specifications
+- TDD kata automation and practice session facilitation
+- Test triangulation techniques for comprehensive coverage
+- Fast feedback loop optimization with incremental test execution
+- TDD compliance monitoring and team adherence metrics
+- Baby steps methodology support with micro-commit tracking
+- Test naming conventions and intent documentation automation
+
 ### AI-Powered Testing Frameworks
 - Self-healing test automation with tools like Testsigma, Testim, and Applitools
 - AI-driven test case generation and maintenance using natural language processing
@@ -91,6 +108,13 @@ Expert test automation engineer focused on building robust, maintainable, and in
 - Mutation testing for test quality assessment
 - A/B testing validation and statistical analysis
 - Usability testing automation and user journey validation
+- Test-driven refactoring with automated safety verification
+- Incremental test development with continuous validation
+- Test doubles strategy (mocks, stubs, spies, fakes) for TDD isolation
+- Outside-in TDD for acceptance test-driven development
+- Inside-out TDD for unit-level development patterns
+- Double-loop TDD combining acceptance and unit tests
+- Transformation Priority Premise for TDD implementation guidance
 
 ### Test Reporting and Analytics
 - Comprehensive test reporting with Allure, ExtentReports, and TestRail
@@ -100,6 +124,13 @@ Expert test automation engineer focused on building robust, maintainable, and in
 - Test coverage analysis and gap identification
 - Performance benchmarking and regression detection
 - Executive reporting and quality scorecards
+- TDD cycle time metrics and red-green-refactor tracking
+- Test-first compliance percentage and trend analysis
+- Test growth rate and code-to-test ratio monitoring
+- Refactoring frequency and safety metrics
+- TDD adoption metrics across teams and projects
+- Failing test verification and false positive detection
+- Test granularity and isolation metrics for TDD health
 
 ## Behavioral Traits
 - Focuses on maintainable and scalable test automation solutions
@@ -124,6 +155,14 @@ Expert test automation engineer focused on building robust, maintainable, and in
 - Test data management and privacy considerations
 - Agile and DevOps testing strategies
 - Industry standards and compliance requirements
+- Test-Driven Development methodologies (Chicago and London schools)
+- Red-green-refactor cycle optimization techniques
+- Property-based testing and generative testing strategies
+- TDD kata patterns and practice methodologies
+- Test triangulation and incremental development approaches
+- TDD metrics and team adoption strategies
+- Behavior-Driven Development (BDD) integration with TDD
+- Legacy code refactoring with TDD safety nets
 
 ## Response Approach
 1. **Analyze testing requirements** and identify automation opportunities
@@ -135,6 +174,16 @@ Expert test automation engineer focused on building robust, maintainable, and in
 7. **Validate test effectiveness** through quality metrics and feedback
 8. **Scale testing practices** across teams and projects
 
+### TDD-Specific Response Approach
+1. **Write failing test first** to define expected behavior clearly
+2. **Verify test failure** ensuring it fails for the right reason
+3. **Implement minimal code** to make the test pass efficiently
+4. **Confirm test passes** validating implementation correctness
+5. **Refactor with confidence** using tests as safety net
+6. **Track TDD metrics** monitoring cycle time and test growth
+7. **Iterate incrementally** building features through small TDD cycles
+8. **Integrate with CI/CD** for continuous TDD verification
+
 ## Example Interactions
 - "Design a comprehensive test automation strategy for a microservices architecture"
 - "Implement AI-powered visual regression testing for our web application"
@@ -144,3 +193,11 @@ Expert test automation engineer focused on building robust, maintainable, and in
 - "Implement cross-browser testing with parallel execution in CI/CD"
 - "Create a test data management strategy for multiple environments"
 - "Design chaos engineering tests for system resilience validation"
+- "Generate failing tests for a new feature following TDD principles"
+- "Set up TDD cycle tracking with red-green-refactor metrics"
+- "Implement property-based TDD for algorithmic validation"
+- "Create TDD kata automation for team training sessions"
+- "Build incremental test suite with test-first development patterns"
+- "Design TDD compliance dashboard for team adherence monitoring"
+- "Implement London School TDD with mock-based test isolation"
+- "Set up continuous TDD verification in CI/CD pipeline"

From 7ef790ec4c648d648c7636445a02bfdb485615da Mon Sep 17 00:00:00 2001
From: Seth Hobson <wshobson@gmail.com>
Date: Sat, 13 Sep 2025 14:01:50 -0400
Subject: [PATCH 2/3] docs: Improve README with professional technical
 documentation

- Remove all emoji for cleaner professional appearance
- Reorganize content with logical categorical structure
- Improve technical clarity and concise descriptions
- Add clear hierarchy with consistent formatting
- Focus on functionality rather than marketing language
- Better organization of agents by functional domains
- Streamline model configuration section
- Enhance usage examples with technical focus
- Reduce content from 558 to 438 lines while maintaining all essential information
---
 README.md | 771 +++++++++++++++++++++++-------------------------------
 1 file changed, 326 insertions(+), 445 deletions(-)

diff --git a/README.md b/README.md
index 1a4657d..00537af 100644
--- a/README.md
+++ b/README.md
@@ -1,557 +1,438 @@
-<div align="right">
-  <details>
-    <summary >🌐 Language</summary>
-    <div>
-      <div align="center">
-        <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=en">English</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=zh-CN">简体中文</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=zh-TW">繁體中文</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=ja">日本語</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=ko">한국어</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=hi">हिन्दी</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=th">ไทย</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=fr">Français</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=de">Deutsch</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=es">Español</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=it">Italiano</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=ru">Русский</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=pt">Português</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=nl">Nederlands</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=pl">Polski</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=ar">العربية</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=fa">فارسی</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=tr">Türkçe</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=vi">Tiếng Việt</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=id">Bahasa Indonesia</a>
-        | <a href="https://openaitx.github.io/view.html?user=wshobson&project=agents&lang=as">অসমীয়া</
-      </div>
-    </div>
-  </details>
-</div>
-
 # Claude Code Subagents Collection
 
-A comprehensive collection of specialized AI subagents for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), designed to enhance development workflows with domain-specific expertise.
+A comprehensive collection of 78 specialized AI subagents for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), providing domain-specific expertise across software development, infrastructure, and business operations.
 
 ## Overview
 
-This repository contains **78 expert-level subagents** that extend Claude Code's capabilities with deep, specialized knowledge across all areas of software development and business operations. Each subagent has been comprehensively enhanced with:
+This repository provides production-ready subagents that extend Claude Code's capabilities with specialized knowledge. Each subagent incorporates:
 
-- **2024/2025 Best Practices** - Latest tools, frameworks, and industry standards
-- **Production-Ready Knowledge** - Real-world scenarios and enterprise patterns
-- **Expert-Level Depth** - 8-12 detailed capability subsections per agent
-- **Modern Tech Stacks** - Current versions and cutting-edge technologies
-- **Optimal Model Selection** - Sonnet/Haiku assignment based on task complexity
+- Current industry best practices and standards (2024/2025)
+- Production-ready patterns and enterprise architectures
+- Deep domain expertise with 8-12 capability areas per agent
+- Modern technology stacks and frameworks
+- Optimized model selection based on task complexity
 
-## Available Subagents
+## Agent Categories
 
-### Development & Architecture
-- **[backend-architect](backend-architect.md)** - Design RESTful APIs, microservice boundaries, and database schemas
-- **[frontend-developer](frontend-developer.md)** - Build React components, implement responsive layouts, and handle client-side state management
-- **[ui-ux-designer](ui-ux-designer.md)** - Create interface designs, wireframes, and design systems
-- **[ui-visual-validator](ui-visual-validator.md)** - Verify whether UI modifications have achieved their intended goals through rigorous screenshot analysis
-- **[mobile-developer](mobile-developer.md)** - Develop React Native or Flutter apps with native integrations
-- **[graphql-architect](graphql-architect.md)** - Design GraphQL schemas, resolvers, and federation
-- **[architect-reviewer](architect-review.md)** - Reviews code changes for architectural consistency and patterns
+### Architecture & System Design
 
-### Language Specialists
-- **[python-pro](python-pro.md)** - Write idiomatic Python code with advanced features and optimizations
-- **[ruby-pro](ruby-pro.md)** - Write idiomatic Ruby code with metaprogramming, Rails patterns, gem development, and testing frameworks
-- **[golang-pro](golang-pro.md)** - Write idiomatic Go code with goroutines, channels, and interfaces
-- **[rust-pro](rust-pro.md)** - Write idiomatic Rust with ownership patterns, lifetimes, and trait implementations
-- **[c-pro](c-pro.md)** - Write efficient C code with proper memory management and system calls
-- **[cpp-pro](cpp-pro.md)** - Write idiomatic C++ code with modern features, RAII, smart pointers, and STL algorithms
-- **[javascript-pro](javascript-pro.md)** - Master modern JavaScript with ES6+, async patterns, and Node.js APIs
-- **[typescript-pro](typescript-pro.md)** - Master TypeScript with advanced types, generics, and strict type safety
-- **[php-pro](php-pro.md)** - Write idiomatic PHP code with modern features and performance optimizations
-- **[java-pro](java-pro.md)** - Master modern Java with streams, concurrency, and JVM optimization
-- **[elixir-pro](elixir-pro.md)** - Write idiomatic Elixir code with OTP patterns, functional programming, and Phoenix frameworks
-- **[csharp-pro](csharp-pro.md)** - Write modern C# code with advanced features and .NET optimization
-- **[scala-pro](scala-pro.md)** - Master enterprise-grade Scala development with functional programming, distributed systems, and big data processing
-- **[flutter-expert](flutter-expert.md)** - Master Flutter development with Dart, widgets, and platform integrations
-- **[unity-developer](unity-developer.md)** - Build Unity games with optimized scripts and performance tuning
-- **[minecraft-bukkit-pro](minecraft-bukkit-pro.md)** - Master Minecraft server plugin development with Bukkit, Spigot, and Paper APIs
-- **[ios-developer](ios-developer.md)** - Develop native iOS applications with Swift/SwiftUI
-- **[sql-pro](sql-pro.md)** - Write complex SQL queries, optimize execution plans, and design normalized schemas
+#### Core Architecture
+- **[backend-architect](backend-architect.md)** - RESTful API design, microservice boundaries, database schemas
+- **[frontend-developer](frontend-developer.md)** - React components, responsive layouts, client-side state management
+- **[graphql-architect](graphql-architect.md)** - GraphQL schemas, resolvers, federation architecture
+- **[architect-reviewer](architect-review.md)** - Architectural consistency analysis and pattern validation
+- **[cloud-architect](cloud-architect.md)** - AWS/Azure/GCP infrastructure design and cost optimization
+- **[hybrid-cloud-architect](hybrid-cloud-architect.md)** - Multi-cloud strategies across cloud and on-premises environments
+- **[kubernetes-architect](kubernetes-architect.md)** - Cloud-native infrastructure with Kubernetes and GitOps
+
+#### UI/UX & Mobile
+- **[ui-ux-designer](ui-ux-designer.md)** - Interface design, wireframes, design systems
+- **[ui-visual-validator](ui-visual-validator.md)** - Visual regression testing and UI verification
+- **[mobile-developer](mobile-developer.md)** - React Native and Flutter application development
+- **[ios-developer](ios-developer.md)** - Native iOS development with Swift/SwiftUI
+- **[flutter-expert](flutter-expert.md)** - Advanced Flutter development with state management
+
+### Programming Languages
+
+#### Systems & Low-Level
+- **[c-pro](c-pro.md)** - System programming with memory management and OS interfaces
+- **[cpp-pro](cpp-pro.md)** - Modern C++ with RAII, smart pointers, STL algorithms
+- **[rust-pro](rust-pro.md)** - Memory-safe systems programming with ownership patterns
+- **[golang-pro](golang-pro.md)** - Concurrent programming with goroutines and channels
+
+#### Web & Application
+- **[javascript-pro](javascript-pro.md)** - Modern JavaScript with ES6+, async patterns, Node.js
+- **[typescript-pro](typescript-pro.md)** - Advanced TypeScript with type systems and generics
+- **[python-pro](python-pro.md)** - Python development with advanced features and optimization
+- **[ruby-pro](ruby-pro.md)** - Ruby with metaprogramming, Rails patterns, gem development
+- **[php-pro](php-pro.md)** - Modern PHP with frameworks and performance optimization
+
+#### Enterprise & JVM
+- **[java-pro](java-pro.md)** - Modern Java with streams, concurrency, JVM optimization
+- **[scala-pro](scala-pro.md)** - Enterprise Scala with functional programming and distributed systems
+- **[csharp-pro](csharp-pro.md)** - C# development with .NET frameworks and patterns
+
+#### Specialized Platforms
+- **[elixir-pro](elixir-pro.md)** - Elixir with OTP patterns and Phoenix frameworks
+- **[unity-developer](unity-developer.md)** - Unity game development and optimization
+- **[minecraft-bukkit-pro](minecraft-bukkit-pro.md)** - Minecraft server plugin development
+- **[sql-pro](sql-pro.md)** - Complex SQL queries and database optimization
 
 ### Infrastructure & Operations
-- **[devops-troubleshooter](devops-troubleshooter.md)** - Debug production issues, analyze logs, and fix deployment failures
-- **[deployment-engineer](deployment-engineer.md)** - Configure CI/CD pipelines, Docker containers, and cloud deployments
-- **[cloud-architect](cloud-architect.md)** - Design AWS/Azure/GCP infrastructure and optimize cloud costs
-- **[hybrid-cloud-architect](hybrid-cloud-architect.md)** - Design hybrid cloud infrastructure across AWS/Azure/GCP and OpenStack on-premises environments
-- **[kubernetes-architect](kubernetes-architect.md)** - Design cloud-native infrastructure with Kubernetes at its core and GitOps principles across AWS/Azure/GCP and hybrid environments.
-- **[database-optimizer](database-optimizer.md)** - Optimize SQL queries, design efficient indexes, and handle database migrations
-- **[database-admin](database-admin.md)** - Manage database operations, backups, replication, and monitoring
-- **[terraform-specialist](terraform-specialist.md)** - Write advanced Terraform modules, manage state files, and implement IaC best practices
-- **[incident-responder](incident-responder.md)** - Handles production incidents with urgency and precision
-- **[network-engineer](network-engineer.md)** - Debug network connectivity, configure load balancers, and analyze traffic patterns
-- **[dx-optimizer](dx-optimizer.md)** - Developer Experience specialist that improves tooling, setup, and workflows
 
-### Quality & Security
-- **[code-reviewer](code-reviewer.md)** - Expert code review with deep configuration security focus and production reliability
-- **[security-auditor](security-auditor.md)** - Review code for vulnerabilities and ensure OWASP compliance
-- **[test-automator](test-automator.md)** - Create comprehensive test suites with unit, integration, and e2e tests
-- **[tdd-orchestrator](tdd-orchestrator.md)** - Guide Test-Driven Development cycles with red-green-refactor methodology
-- **[performance-engineer](performance-engineer.md)** - Profile applications, optimize bottlenecks, and implement caching strategies
-- **[debugger](debugger.md)** - Debugging specialist for errors, test failures, and unexpected behavior
-- **[error-detective](error-detective.md)** - Search logs and codebases for error patterns, stack traces, and anomalies
-- **[search-specialist](search-specialist.md)** - Expert web researcher using advanced search techniques and synthesis
+#### DevOps & Deployment
+- **[devops-troubleshooter](devops-troubleshooter.md)** - Production debugging, log analysis, deployment troubleshooting
+- **[deployment-engineer](deployment-engineer.md)** - CI/CD pipelines, containerization, cloud deployments
+- **[terraform-specialist](terraform-specialist.md)** - Infrastructure as Code with Terraform modules and state management
+- **[dx-optimizer](dx-optimizer.md)** - Developer experience optimization and tooling improvements
+
+#### Database Management
+- **[database-optimizer](database-optimizer.md)** - Query optimization, index design, migration strategies
+- **[database-admin](database-admin.md)** - Database operations, backup, replication, monitoring
+
+#### Incident Response & Network
+- **[incident-responder](incident-responder.md)** - Production incident management and resolution
+- **[network-engineer](network-engineer.md)** - Network debugging, load balancing, traffic analysis
+
+### Quality Assurance & Security
+
+#### Code Quality & Review
+- **[code-reviewer](code-reviewer.md)** - Code review with security focus and production reliability
+- **[security-auditor](security-auditor.md)** - Vulnerability assessment and OWASP compliance
+- **[architect-reviewer](architect-review.md)** - Architectural consistency and pattern validation
+
+#### Testing & Debugging
+- **[test-automator](test-automator.md)** - Comprehensive test suite creation (unit, integration, e2e)
+- **[tdd-orchestrator](tdd-orchestrator.md)** - Test-Driven Development methodology guidance
+- **[debugger](debugger.md)** - Error resolution and test failure analysis
+- **[error-detective](error-detective.md)** - Log analysis and error pattern recognition
+
+#### Performance & Research
+- **[performance-engineer](performance-engineer.md)** - Application profiling and optimization
+- **[search-specialist](search-specialist.md)** - Advanced web research and information synthesis
 
 ### Data & AI
-- **[data-scientist](data-scientist.md)** - Data analysis expert for SQL queries, BigQuery operations, and data insights
-- **[data-engineer](data-engineer.md)** - Build ETL pipelines, data warehouses, and streaming architectures
-- **[ai-engineer](ai-engineer.md)** - Build LLM applications, RAG systems, and prompt pipelines
-- **[ml-engineer](ml-engineer.md)** - Implement ML pipelines, model serving, and feature engineering
-- **[mlops-engineer](mlops-engineer.md)** - Build ML pipelines, experiment tracking, and model registries
-- **[prompt-engineer](prompt-engineer.md)** - Optimizes prompts for LLMs and AI systems
+
+#### Data Engineering & Analytics
+- **[data-scientist](data-scientist.md)** - Data analysis, SQL queries, BigQuery operations
+- **[data-engineer](data-engineer.md)** - ETL pipelines, data warehouses, streaming architectures
+
+#### Machine Learning & AI
+- **[ai-engineer](ai-engineer.md)** - LLM applications, RAG systems, prompt pipelines
+- **[ml-engineer](ml-engineer.md)** - ML pipelines, model serving, feature engineering
+- **[mlops-engineer](mlops-engineer.md)** - ML infrastructure, experiment tracking, model registries
+- **[prompt-engineer](prompt-engineer.md)** - LLM prompt optimization and engineering
+
+### Documentation & Technical Writing
+
+- **[docs-architect](docs-architect.md)** - Comprehensive technical documentation generation
+- **[api-documenter](api-documenter.md)** - OpenAPI/Swagger specifications and developer docs
+- **[reference-builder](reference-builder.md)** - Technical references and API documentation
+- **[tutorial-engineer](tutorial-engineer.md)** - Step-by-step tutorials and educational content
+- **[mermaid-expert](mermaid-expert.md)** - Diagram creation (flowcharts, sequences, ERDs)
+
+### Business & Operations
+
+#### Business Analysis & Finance
+- **[business-analyst](business-analyst.md)** - Metrics analysis, reporting, KPI tracking
+- **[quant-analyst](quant-analyst.md)** - Financial modeling, trading strategies, market analysis
+- **[risk-manager](risk-manager.md)** - Portfolio risk monitoring and management
+
+#### Marketing & Sales
+- **[content-marketer](content-marketer.md)** - Blog posts, social media, email campaigns
+- **[sales-automator](sales-automator.md)** - Cold emails, follow-ups, proposal generation
+
+#### Support & Legal
+- **[customer-support](customer-support.md)** - Support tickets, FAQ responses, customer communication
+- **[hr-pro](hr-pro.md)** - HR operations, policies, employee relations
+- **[legal-advisor](legal-advisor.md)** - Privacy policies, terms of service, legal documentation
 
 ### Specialized Domains
-- **[api-documenter](api-documenter.md)** - Create OpenAPI/Swagger specs and write developer documentation
-- **[payment-integration](payment-integration.md)** - Integrate Stripe, PayPal, and payment processors
-- **[quant-analyst](quant-analyst.md)** - Build financial models, backtest trading strategies, and analyze market data
-- **[risk-manager](risk-manager.md)** - Monitor portfolio risk, R-multiples, and position limits
-- **[legacy-modernizer](legacy-modernizer.md)** - Refactor legacy codebases and implement gradual modernization
-- **[context-manager](context-manager.md)** - Manages context across multiple agents and long-running tasks
 
-### Documentation
-- **[docs-architect](docs-architect.md)** - Creates comprehensive technical documentation from existing codebases
-- **[mermaid-expert](mermaid-expert.md)** - Create Mermaid diagrams for flowcharts, sequences, ERDs, and architectures
-- **[reference-builder](reference-builder.md)** - Creates exhaustive technical references and API documentation
-- **[tutorial-engineer](tutorial-engineer.md)** - Creates step-by-step tutorials and educational content from code
-
-### Business & Marketing
-- **[business-analyst](business-analyst.md)** - Analyze metrics, create reports, and track KPIs
-- **[content-marketer](content-marketer.md)** - Write blog posts, social media content, and email newsletters
-- **[hp-pro](hp-pro.md)** - Partner for hiring, onboarding/offboarding, PTO and leave, performance, compliant policies, and employee relations.
-- **[sales-automator](sales-automator.md)** - Draft cold emails, follow-ups, and proposal templates
-- **[customer-support](customer-support.md)** - Handle support tickets, FAQ responses, and customer emails
-- **[legal-advisor](legal-advisor.md)** - Draft privacy policies, terms of service, disclaimers, and legal notices
+- **[payment-integration](payment-integration.md)** - Payment processor integration (Stripe, PayPal)
+- **[legacy-modernizer](legacy-modernizer.md)** - Legacy code refactoring and modernization
+- **[context-manager](context-manager.md)** - Multi-agent context management
 
 ### SEO & Content Optimization
-- **[seo-content-auditor](seo-content-auditor.md)** - Analyzes provided content for quality, E-E-A-T signals, and SEO best practices
-- **[seo-meta-optimizer](seo-meta-optimizer.md)** - Creates optimized meta titles, descriptions, and URL suggestions
-- **[seo-keyword-strategist](seo-keyword-strategist.md)** - Analyzes keyword usage, calculates density, suggests semantic variations
-- **[seo-structure-architect](seo-structure-architect.md)** - Optimizes content structure, header hierarchy, and schema markup
-- **[seo-snippet-hunter](seo-snippet-hunter.md)** - Formats content for featured snippets and SERP features
-- **[seo-content-refresher](seo-content-refresher.md)** - Identifies outdated elements and suggests content updates
-- **[seo-cannibalization-detector](seo-cannibalization-detector.md)** - Analyzes multiple pages for keyword overlap and conflicts
-- **[seo-authority-builder](seo-authority-builder.md)** - Analyzes content for E-E-A-T signals and trust indicators
-- **[seo-content-writer](seo-content-writer.md)** - Writes SEO-optimized content based on keywords and briefs
-- **[seo-content-planner](seo-content-planner.md)** - Creates content outlines, topic clusters, and calendars
 
-## Model Assignments
+- **[seo-content-auditor](seo-content-auditor.md)** - Content quality analysis, E-E-A-T signals assessment
+- **[seo-meta-optimizer](seo-meta-optimizer.md)** - Meta title and description optimization
+- **[seo-keyword-strategist](seo-keyword-strategist.md)** - Keyword analysis and semantic variations
+- **[seo-structure-architect](seo-structure-architect.md)** - Content structure and schema markup
+- **[seo-snippet-hunter](seo-snippet-hunter.md)** - Featured snippet formatting
+- **[seo-content-refresher](seo-content-refresher.md)** - Content freshness analysis
+- **[seo-cannibalization-detector](seo-cannibalization-detector.md)** - Keyword overlap detection
+- **[seo-authority-builder](seo-authority-builder.md)** - E-E-A-T signal analysis
+- **[seo-content-writer](seo-content-writer.md)** - SEO-optimized content creation
+- **[seo-content-planner](seo-content-planner.md)** - Content planning and topic clusters
 
-All 77 subagents are configured with specific Claude models based on task complexity:
+## Model Configuration
 
-### 🚀 Haiku (Fast & Cost-Effective) - 11 agents
-**Model:** `haiku`
-- `context-manager` - AI context engineering with vector databases
-- `reference-builder` - Exhaustive technical references and API documentation
-- `sales-automator` - Modern sales automation with CRM integration
-- `search-specialist` - Expert web research and information synthesis
-- `seo-meta-optimizer` - Meta title and description optimization
-- `seo-keyword-strategist` - Keyword density and semantic analysis
-- `seo-structure-architect` - Content structure and schema markup
-- `seo-snippet-hunter` - Featured snippet formatting
-- `seo-content-refresher` - Content freshness updates
-- `seo-cannibalization-detector` - Keyword overlap detection
-- `seo-content-planner` - Content calendars and topic clusters
+Agents are assigned to specific Claude models based on task complexity and computational requirements. The system uses three model tiers:
 
-### ⚡ Sonnet (Balanced Performance) - 46 agents
-**Model:** `sonnet`
+### Haiku Model (Fast Response) - 11 agents
+Optimized for quick, focused tasks with minimal computational overhead:
+- `context-manager`, `reference-builder`, `sales-automator`, `search-specialist`
+- SEO agents: `seo-meta-optimizer`, `seo-keyword-strategist`, `seo-structure-architect`, `seo-snippet-hunter`, `seo-content-refresher`, `seo-cannibalization-detector`, `seo-content-planner`
 
-**Development & Languages:**
-- `python-pro` - Python development with advanced features
-- `ruby-pro` - Ruby development with metaprogramming, Rails patterns, and gem development
-- `javascript-pro` - Modern JavaScript and Node.js
-- `typescript-pro` - Advanced TypeScript with type systems
-- `golang-pro` - Go concurrency and idiomatic patterns
-- `rust-pro` - Rust memory safety and systems programming
-- `c-pro` - C programming and embedded systems
-- `cpp-pro` - Modern C++ with STL and templates
-- `php-pro` - Modern PHP with advanced features
-- `java-pro` - Modern Java with streams and concurrency
-- `elixir-pro` - Elixir with OTP patterns and Phoenix
-- `csharp-pro` - Modern C# with .NET frameworks and patterns
-- `scala-pro` - Enterprise Scala with Apache Pekko, Akka, Spark, and ZIO/Cats Effect
-- `flutter-expert` - Flutter development with state management and animations
-- `unity-developer` - Unity game development and optimization
-- `minecraft-bukkit-pro` - Minecraft plugin development with Bukkit/Spigot/Paper
-- `ios-developer` - Native iOS development with Swift/SwiftUI
-- `frontend-developer` - React components and UI
-- `ui-ux-designer` - Interface design and wireframes
-- `ui-visual-validator` - Rigorous UI validation through screenshot analysis
-- `backend-architect` - API design and microservices
-- `mobile-developer` - React Native/Flutter apps
-- `sql-pro` - Complex SQL optimization
-- `graphql-architect` - GraphQL schemas and resolvers
+### Sonnet Model (Balanced Performance) - 46 agents
+Standard model for development and specialized tasks:
+- Language specialists (18): All programming language agents
+- Frontend/UI agents (5): `frontend-developer`, `ui-ux-designer`, `ui-visual-validator`, `mobile-developer`, `ios-developer`
+- Infrastructure agents (14): DevOps, database, network, and deployment specialists
+- Quality/Testing agents (4): `test-automator`, `tdd-orchestrator`, `debugger`, `error-detective`
+- Data/ML agents (5): Basic ML and data engineering tasks
 
-**Infrastructure & Operations:**
-- `devops-troubleshooter` - Production debugging with modern observability
-- `deployment-engineer` - GitOps workflows and platform engineering
-- `cloud-architect` - Multi-cloud expertise with FinOps optimization
-- `hybrid-cloud-architect` - Complex multi-cloud and edge architectures
-- `kubernetes-architect` - Cloud-native infrastructure with service mesh
-- `database-optimizer` - Advanced performance tuning and scalability
-- `database-admin` - Cloud databases and reliability engineering
-- `terraform-specialist` - Advanced IaC with OpenTofu knowledge
-- `network-engineer` - Zero-trust networking and service mesh
-- `security-auditor` - DevSecOps and compliance automation
-- `performance-engineer` - OpenTelemetry and comprehensive optimization
-- `incident-responder` - SRE principles and modern incident management
-- `dx-optimizer` - Developer experience and platform engineering
-- `data-engineer` - Modern data stack and real-time streaming
-
-**Quality & AI/ML:**
-- `test-automator` - AI-powered testing with self-healing frameworks
-- `tdd-orchestrator` - Test-Driven Development cycle orchestration
-- `code-reviewer` - Expert code analysis with modern security scanning
-- `ai-engineer` - Advanced LLM integration with RAG and agent systems
-- `ml-engineer` - Production ML with modern frameworks and monitoring
-- `mlops-engineer` - Comprehensive ML infrastructure and automation
-- `data-scientist` - Advanced analytics with cloud platforms
-- `prompt-engineer` - Cutting-edge LLM optimization techniques
-
-### 🧠 Opus (Maximum Capability) - 21 agents
-**Model:** `opus`
-
-**Critical Analysis & Architecture:**
-- `ai-engineer` - LLM applications and RAG systems
-- `architect-reviewer` - Architectural consistency and patterns
-- `backend-architect` - System architecture and scalability design
-- `cloud-architect` - Multi-cloud infrastructure architecture
-- `code-reviewer` - Critical code quality and security analysis
-- `data-scientist` - Complex analytics and statistical modeling
-- `database-optimizer` - Performance-critical query optimization
-
-**Complex Engineering & Operations:**
-- `hybrid-cloud-architect` - Complex multi-cloud strategies
-- `incident-responder` - Critical production incident handling
-- `kubernetes-architect` - Cloud-native infrastructure design
-- `ml-engineer` - Complex ML model development and deployment
-- `mlops-engineer` - ML infrastructure and automation
-- `performance-engineer` - Advanced application optimization
-- `prompt-engineer` - Advanced LLM optimization techniques
-- `security-auditor` - Comprehensive vulnerability analysis
-- `terraform-specialist` - Infrastructure architecture with IaC
-
-**Business Critical & Compliance:**
-- `context-manager` - Multi-agent coordination for complex tasks
-- `docs-architect` - Comprehensive technical documentation
-- `hr-pro` - Complex HR scenarios and legal compliance
-- `legal-advisor` - Legal analysis and contract review
-- `quant-analyst` - Advanced financial modeling and algorithmic trading
-
-**Model Optimization:**
-Agents are strategically assigned models based on task complexity:
-- **Opus (21)**: Complex reasoning, critical analysis, architecture
-- **Sonnet (46)**: Balanced development and specialized tasks
-- **Haiku (11)**: Fast, focused utility tasks
+### Opus Model (Maximum Capability) - 21 agents
+Reserved for complex reasoning and critical analysis:
+- Architecture & Design (7): `architect-reviewer`, `backend-architect`, `cloud-architect`, `hybrid-cloud-architect`, `kubernetes-architect`, `graphql-architect`, `terraform-specialist`
+- Critical Analysis (5): `code-reviewer`, `security-auditor`, `performance-engineer`, `incident-responder`, `database-optimizer`
+- AI/ML Complex (5): `ai-engineer`, `ml-engineer`, `mlops-engineer`, `data-scientist`, `prompt-engineer`
+- Business Critical (4): `docs-architect`, `hr-pro`, `legal-advisor`, `quant-analyst`
 
 ## Installation
 
-These subagents are automatically available when placed in `~/.claude/agents/` directory.
+Clone the repository to the Claude agents directory:
 
 ```bash
 cd ~/.claude
 git clone https://github.com/wshobson/agents.git
 ```
 
+The subagents will be automatically available to Claude Code once placed in the `~/.claude/agents/` directory.
+
 ## Usage
 
-### Automatic Invocation
-Claude Code will automatically delegate to the appropriate subagent based on the task context and the subagent's description.
+### Automatic Delegation
+Claude Code automatically selects the appropriate subagent based on task context and requirements. The system analyzes your request and delegates to the most suitable specialist.
 
 ### Explicit Invocation
-Mention the subagent by name in your request:
+Specify a subagent by name to use a particular specialist:
+
 ```
-"Use the code-reviewer to check my recent changes"
-"Have the security-auditor scan for vulnerabilities"
-"Get the performance-engineer to optimize this bottleneck"
+"Use code-reviewer to analyze the recent changes"
+"Have security-auditor scan for vulnerabilities"
+"Get performance-engineer to optimize this bottleneck"
 ```
 
 ## Usage Examples
 
-### Single Agent Tasks
-```bash
-# Code quality and review
-"Use code-reviewer to analyze this component for best practices"
-"Have code-reviewer scrutinize these configuration changes"
-"Have security-auditor check for OWASP compliance issues"
-"Use tdd-orchestrator to implement new feature with test-first approach"
-
-# Development tasks  
-"Get backend-architect to design a user authentication API"
-"Use frontend-developer to create a responsive dashboard layout"
-
-# Infrastructure and operations
-"Have devops-troubleshooter analyze these production logs"
-"Use cloud-architect to design a scalable AWS architecture"
-"Get network-engineer to debug SSL certificate issues"
-"Use database-admin to set up backup and replication"
-
-# Data and AI
-"Get data-scientist to analyze this customer behavior dataset"
-"Use ai-engineer to build a RAG system for document search"
-"Have mlops-engineer set up MLflow experiment tracking"
-
-# Business and marketing
-"Have business-analyst create investor deck with growth metrics"
-"Use content-marketer to write SEO-optimized blog post"
-"Get sales-automator to create cold email sequence"
-"Have customer-support draft FAQ documentation"
+### Code Quality & Security
+```
+code-reviewer: Analyze component for best practices
+security-auditor: Check for OWASP compliance
+tdd-orchestrator: Implement feature with test-first approach
+performance-engineer: Profile and optimize bottlenecks
 ```
 
-### Multi-Agent Workflows
-
-These subagents work together seamlessly, and for more complex orchestrations, you can use the **[Claude Code Commands](https://github.com/wshobson/commands)** collection which provides 52 pre-built slash commands that leverage these subagents in sophisticated workflows.
-
-```bash
-# Feature development workflow
-"Implement user authentication feature"
-# Automatically uses: backend-architect → frontend-developer → test-automator → security-auditor
-
-# Performance optimization workflow  
-"Optimize the checkout process performance"
-# Automatically uses: performance-engineer → database-optimizer → frontend-developer
-
-# Production incident workflow
-"Debug high memory usage in production"
-# Automatically uses: incident-responder → devops-troubleshooter → error-detective → performance-engineer
-
-# Network connectivity workflow
-"Fix intermittent API timeouts"
-# Automatically uses: network-engineer → devops-troubleshooter → performance-engineer
-
-# Database maintenance workflow
-"Set up disaster recovery for production database"
-# Automatically uses: database-admin → database-optimizer → incident-responder
-
-# ML pipeline workflow
-"Build end-to-end ML pipeline with monitoring"
-# Automatically uses: mlops-engineer → ml-engineer → data-engineer → performance-engineer
-
-# Product launch workflow
-"Launch new feature with marketing campaign"
-# Automatically uses: business-analyst → content-marketer → sales-automator → customer-support
+### Development & Architecture
+```
+backend-architect: Design authentication API
+frontend-developer: Create responsive dashboard
+graphql-architect: Design federated GraphQL schema
+mobile-developer: Build cross-platform mobile app
 ```
 
-### Advanced Workflows with Slash Commands
+### Infrastructure & Operations
+```
+devops-troubleshooter: Analyze production logs
+cloud-architect: Design scalable AWS architecture
+network-engineer: Debug SSL certificate issues
+database-admin: Configure backup and replication
+terraform-specialist: Write infrastructure modules
+```
 
-For more sophisticated multi-subagent orchestration, use the companion [Commands repository](https://github.com/wshobson/commands):
+### Data & Machine Learning
+```
+data-scientist: Analyze customer behavior dataset
+ai-engineer: Build RAG system for document search
+mlops-engineer: Set up experiment tracking
+ml-engineer: Deploy model to production
+```
 
-```bash
-# Complex feature development (8+ subagents)
-/full-stack-feature Build user dashboard with real-time analytics
+### Business & Documentation
+```
+business-analyst: Create metrics dashboard
+docs-architect: Generate technical documentation
+api-documenter: Write OpenAPI specifications
+content-marketer: Create SEO-optimized content
+```
 
-# Production incident response (5+ subagents) 
-/incident-response Database connection pool exhausted
+## Multi-Agent Workflows
 
-# ML infrastructure setup (6+ subagents)
-/ml-pipeline Create recommendation engine with A/B testing
+Subagents coordinate automatically for complex tasks. The system intelligently sequences multiple specialists based on task requirements.
 
-# Security-focused implementation (7+ subagents)
-/security-hardening Implement OAuth2 with zero-trust architecture
+### Common Workflow Patterns
+
+**Feature Development**
+```
+"Implement user authentication"
+→ backend-architect → frontend-developer → test-automator → security-auditor
+```
+
+**Performance Optimization**
+```
+"Optimize checkout process"
+→ performance-engineer → database-optimizer → frontend-developer
+```
+
+**Production Incidents**
+```
+"Debug high memory usage"
+→ incident-responder → devops-troubleshooter → error-detective → performance-engineer
+```
+
+**Infrastructure Setup**
+```
+"Set up disaster recovery"
+→ database-admin → database-optimizer → terraform-specialist
+```
+
+**ML Pipeline Development**
+```
+"Build ML pipeline with monitoring"
+→ mlops-engineer → ml-engineer → data-engineer → performance-engineer
+```
+
+### Integration with Claude Code Commands
+
+For sophisticated multi-agent orchestration, use the [Claude Code Commands](https://github.com/wshobson/commands) collection which provides 52 pre-built slash commands:
+
+```
+/full-stack-feature   # Coordinates 8+ agents for complete feature development
+/incident-response    # Activates incident management workflow
+/ml-pipeline         # Sets up end-to-end ML infrastructure
+/security-hardening  # Implements security best practices across stack
 ```
 
 ## Subagent Format
 
-Each subagent follows this structure:
+Each subagent is defined as a Markdown file with frontmatter:
+
 ```markdown
 ---
 name: subagent-name
-description: When this subagent should be invoked
-model: haiku  # Optional - specify which model to use (haiku/sonnet/opus)
-tools: tool1, tool2  # Optional - defaults to all tools
+description: Activation criteria for this subagent
+model: haiku|sonnet|opus  # Optional: Model selection
+tools: tool1, tool2       # Optional: Tool restrictions
 ---
 
-System prompt defining the subagent's role and capabilities
+System prompt defining the subagent's expertise and behavior
 ```
 
-### Model Configuration
+### Model Selection Criteria
 
-As of Claude Code v1.0.64, subagents can specify which Claude model they should use. This allows for cost-effective task delegation based on complexity:
-
-- **Low Complexity (Haiku)**: Simple tasks like basic data analysis, documentation generation, and standard responses
-- **Medium Complexity (Sonnet)**: Development tasks, code review, testing, and standard engineering work  
-- **High Complexity (Opus)**: Critical tasks like security auditing, architecture review, incident response, and AI/ML engineering
-
-Available models (using simplified naming as of Claude Code v1.0.64):
-- `haiku` - Fast and cost-effective for simple tasks
-- `sonnet` - Balanced performance for most development work
-- `opus` - Most capable for complex analysis and critical tasks
-
-If no model is specified, the subagent will use the system's default model.
+- **haiku**: Simple, deterministic tasks with minimal reasoning
+- **sonnet**: Standard development and engineering tasks
+- **opus**: Complex analysis, architecture, and critical operations
 
 ## Agent Orchestration Patterns
 
-Claude Code automatically coordinates agents using these common patterns:
-
-### Sequential Workflows
+### Sequential Processing
+Agents execute in sequence, passing context forward:
 ```
-User Request → Agent A → Agent B → Agent C → Result
-
-Example: "Build a new API feature"
 backend-architect → frontend-developer → test-automator → security-auditor
 ```
 
 ### Parallel Execution
+Multiple agents work simultaneously on different aspects:
 ```
-User Request → Agent A + Agent B (simultaneously) → Merge Results
-
-Example: "Optimize application performance" 
-performance-engineer + database-optimizer → Combined recommendations
+performance-engineer + database-optimizer → Merged analysis
 ```
 
-### Conditional Branching
+### Conditional Routing
+Dynamic agent selection based on analysis:
 ```
-User Request → Analysis → Route to appropriate specialist
-
-Example: "Fix this bug"
-debugger (analyzes) → Routes to: backend-architect OR frontend-developer OR devops-troubleshooter
+debugger → [backend-architect | frontend-developer | devops-troubleshooter]
 ```
 
-### Review & Validation
+### Validation Pipeline
+Primary work followed by specialized review:
 ```
-Primary Agent → Review Agent → Final Result
-
-Example: "Implement payment processing"
 payment-integration → security-auditor → Validated implementation
 ```
 
-## When to Use Which Agent
+## Agent Selection Guide
 
-### 🏗️ Planning & Architecture
-- **backend-architect**: API design, database schemas, system architecture
-- **frontend-developer**: UI/UX planning, component architecture
-- **ui-ux-designer**: Interface design, wireframes, design systems, user research
-- **cloud-architect**: Infrastructure design, scalability planning
+### Architecture & Planning
+- `backend-architect`: API design, microservices, database schemas
+- `cloud-architect`: Infrastructure design, scalability planning
+- `ui-ux-designer`: Interface design, wireframes, design systems
 
-### 🔧 Implementation & Development  
-- **python-pro**: Python-specific development tasks
-- **ruby-pro**: Ruby metaprogramming, Rails applications, gem development, RSpec/Minitest testing
-- **golang-pro**: Go-specific development tasks
-- **rust-pro**: Rust-specific development, memory safety, systems programming
-- **c-pro**: C programming, embedded systems, performance-critical code
-- **javascript-pro**: Modern JavaScript, async patterns, Node.js/browser code
-- **typescript-pro**: Advanced TypeScript, generics, type inference, enterprise patterns
-- **java-pro**: Modern Java development, streams, concurrency, Spring Boot
-- **elixir-pro**: Elixir development, OTP patterns, Phoenix frameworks, functional programming
-- **csharp-pro**: Modern C# development, .NET frameworks, enterprise patterns
-- **scala-pro**: Enterprise Scala with functional programming, Apache Pekko/Akka actors, Apache Spark, ZIO/Cats Effect, reactive architectures
-- **flutter-expert**: Flutter development, Dart, state management, animations, cross-platform deployment
-- **unity-developer**: Unity game development, C# scripting, performance optimization
-- **minecraft-bukkit-pro**: Minecraft plugin development, event systems, server-side features
-- **ios-developer**: Native iOS development with Swift/SwiftUI
-- **sql-pro**: Database queries, schema design, query optimization
-- **mobile-developer**: React Native/Flutter development
+### Development by Language
+- Systems: `c-pro`, `cpp-pro`, `rust-pro`, `golang-pro`
+- Web: `javascript-pro`, `typescript-pro`, `python-pro`, `ruby-pro`, `php-pro`
+- Enterprise: `java-pro`, `csharp-pro`, `scala-pro`
+- Mobile: `ios-developer`, `flutter-expert`, `mobile-developer`
+- Specialized: `elixir-pro`, `unity-developer`, `minecraft-bukkit-pro`
 
-### 🛠️ Operations & Maintenance
-- **devops-troubleshooter**: Production issues, deployment problems
-- **incident-responder**: Critical outages requiring immediate response
-- **database-optimizer**: Query performance, indexing strategies
-- **database-admin**: Backup strategies, replication, user management, disaster recovery
-- **terraform-specialist**: Infrastructure as Code, Terraform modules, state management
-- **network-engineer**: Network connectivity, load balancers, SSL/TLS, DNS debugging
+### Operations & Infrastructure
+- `devops-troubleshooter`: Production issues, deployment problems
+- `incident-responder`: Critical outages and immediate response
+- `database-optimizer`: Query performance, indexing strategies
+- `database-admin`: Backup, replication, disaster recovery
+- `terraform-specialist`: Infrastructure as Code
+- `network-engineer`: Network debugging, load balancing
 
-### 📊 Analysis & Optimization
-- **performance-engineer**: Application bottlenecks, optimization
-- **security-auditor**: Vulnerability scanning, compliance checks
-- **data-scientist**: Data analysis, insights, reporting
-- **mlops-engineer**: ML infrastructure, experiment tracking, model registries, pipeline automation
+### Quality & Security
+- `code-reviewer`: Code quality and security analysis
+- `security-auditor`: Vulnerability scanning, compliance
+- `test-automator`: Test suite creation and strategy
+- `performance-engineer`: Application optimization
+- `debugger`: Bug investigation and resolution
 
-### 🧪 Quality Assurance
-- **code-reviewer**: Code quality, configuration security, production reliability
-- **test-automator**: Test strategy, test suite creation
-- **tdd-orchestrator**: Test-Driven Development cycles, red-green-refactor methodology
-- **debugger**: Bug investigation, error resolution
-- **error-detective**: Log analysis, error pattern recognition, root cause analysis
-- **search-specialist**: Deep web research, competitive analysis, fact-checking
+### Data & Machine Learning
+- `data-scientist`: Data analysis and insights
+- `ai-engineer`: LLM applications and RAG systems
+- `ml-engineer`: Model development and deployment
+- `mlops-engineer`: ML infrastructure and pipelines
 
-### 📚 Documentation & Architecture
-- **api-documenter**: AI-powered documentation with modern dev portal architecture
-- **docs-architect**: Comprehensive technical documentation with automated generation
-- **reference-builder**: Exhaustive API references with interactive examples
-- **tutorial-engineer**: AI-enhanced educational content with progressive learning
-- **architect-reviewer**: Master software architecture with modern patterns
-- **graphql-architect**: Modern GraphQL federation and performance optimization
-
-### 💼 Business & Specialized Domains
-- **business-analyst**: Advanced BI with AI-powered analytics and strategic frameworks
-- **hr-pro**: Modern HR technology with talent management and compliance
-- **legal-advisor**: Legal technology with contract analysis and compliance automation
-- **content-marketer**: AI-powered content marketing with omnichannel distribution
-- **sales-automator**: Modern sales automation with CRM integration
-- **customer-support**: AI-powered support with conversational automation
-- **quant-analyst**: Advanced quantitative finance with algorithmic trading
-- **risk-manager**: Comprehensive risk management with modern analytics
-- **payment-integration**: Modern payment systems and fintech integration
-- **legacy-modernizer**: Strategic legacy transformation with cloud migration
+### Documentation & Business
+- `docs-architect`: Technical documentation generation
+- `api-documenter`: OpenAPI specifications
+- `business-analyst`: Metrics and reporting
+- `legal-advisor`: Legal documentation and compliance
 
 ## Best Practices
 
-### 🎯 Task Delegation
-1. **Let Claude Code delegate automatically** - The main agent analyzes context and selects optimal agents
-2. **Be specific about requirements** - Include constraints, tech stack, and quality requirements
-3. **Trust agent expertise** - Each agent is optimized for their domain
+### Task Delegation
+1. **Automatic selection** - Let Claude Code analyze context and select optimal agents
+2. **Clear requirements** - Specify constraints, tech stack, and quality standards
+3. **Trust specialization** - Each agent is optimized for their specific domain
 
-### 🔄 Multi-Agent Workflows
-4. **Start with high-level requests** - Let agents coordinate complex multi-step tasks
-5. **Provide context between agents** - Ensure agents have necessary background information
-6. **Review integration points** - Check how different agents' outputs work together
+### Multi-Agent Workflows
+1. **High-level requests** - Allow agents to coordinate complex multi-step tasks
+2. **Context preservation** - Ensure agents have necessary background information
+3. **Integration review** - Verify how different agents' outputs work together
 
-### 🎛️ Explicit Control
-7. **Use explicit invocation for specific needs** - When you want a particular expert's perspective
-8. **Combine multiple agents strategically** - Different specialists can validate each other's work
-9. **Request specific review patterns** - "Have security-auditor review backend-architect's API design"
+### Explicit Control
+1. **Direct invocation** - Specify agents when you need particular expertise
+2. **Strategic combination** - Use multiple specialists for validation
+3. **Review patterns** - Request specific review workflows (e.g., "security-auditor reviews API design")
 
-### 📈 Optimization
-10. **Monitor agent effectiveness** - Learn which agents work best for your use cases
-11. **Iterate on complex tasks** - Use agent feedback to refine requirements
-12. **Leverage agent strengths** - Match task complexity to agent capabilities
+### Performance Optimization
+1. **Monitor effectiveness** - Track which agents work best for your use cases
+2. **Iterative refinement** - Use agent feedback to improve requirements
+3. **Complexity matching** - Align task complexity with agent capabilities
 
 ## Contributing
 
 To add a new subagent:
-1. Create a new `.md` file following the format above
-2. Use lowercase, hyphen-separated names
-3. Write clear descriptions for when the subagent should be used
-4. Include specific instructions in the system prompt
+
+1. Create a new `.md` file with appropriate frontmatter
+2. Use lowercase, hyphen-separated naming convention
+3. Write clear activation criteria in the description
+4. Define comprehensive system prompt with expertise areas
 
 ## Troubleshooting
 
-### Common Issues
+### Agent Not Activating
+- Ensure request clearly indicates the domain
+- Be specific about task type and requirements
+- Use explicit invocation if automatic selection fails
 
-**Agent not being invoked automatically:**
-- Ensure your request clearly indicates the domain (e.g., "performance issue" → performance-engineer)
-- Be specific about the task type (e.g., "review code" → code-reviewer)
+### Unexpected Agent Selection
+- Provide more context about tech stack
+- Include specific requirements in request
+- Use direct agent naming for precise control
 
-**Unexpected agent selection:**
-- Provide more context about your tech stack and requirements
-- Use explicit invocation if you need a specific agent
+### Conflicting Recommendations
+- Normal behavior - specialists have different priorities
+- Request reconciliation between specific agents
+- Consider trade-offs based on project requirements
 
-**Multiple agents producing conflicting advice:**
-- This is normal - different specialists may have different priorities
-- Ask for clarification: "Reconcile the recommendations from security-auditor and performance-engineer"
-
-**Agent seems to lack context:**
-- Provide background information in your request
-- Reference previous conversations or established patterns
-
-### Getting Help
-
-If agents aren't working as expected:
-1. Check agent descriptions in their individual files
-2. Try more specific language in your requests
-3. Use explicit invocation to test specific agents
-4. Provide more context about your project and goals
+### Missing Context
+- Include background information in requests
+- Reference previous work or patterns
+- Provide project-specific constraints
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) file for details.
 
-## Learn More
+## Resources
 
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
 - [Subagents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
 - [Claude Code GitHub](https://github.com/anthropics/claude-code)
+- [Claude Code Commands](https://github.com/wshobson/commands)

From a36be5db085b55c0cf63942986bb6b966394d180 Mon Sep 17 00:00:00 2001
From: Seth Hobson <wshobson@gmail.com>
Date: Sat, 13 Sep 2025 14:14:30 -0400
Subject: [PATCH 3/3] docs: Enhance README with table-based organization

- Convert all agent listings to professional tables
- Add structured tables with Agent, Model, and Description columns
- Reorganize model configuration section with distribution tables
- Enhance agent selection guide with task-based tables
- Maintain consistency with commands repository formatting
- Improve readability and information accessibility
- Keep all existing content while improving presentation
---
 README.md | 333 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 212 insertions(+), 121 deletions(-)

diff --git a/README.md b/README.md
index 00537af..7efc5c4 100644
--- a/README.md
+++ b/README.md
@@ -17,158 +17,230 @@ This repository provides production-ready subagents that extend Claude Code's ca
 ### Architecture & System Design
 
 #### Core Architecture
-- **[backend-architect](backend-architect.md)** - RESTful API design, microservice boundaries, database schemas
-- **[frontend-developer](frontend-developer.md)** - React components, responsive layouts, client-side state management
-- **[graphql-architect](graphql-architect.md)** - GraphQL schemas, resolvers, federation architecture
-- **[architect-reviewer](architect-review.md)** - Architectural consistency analysis and pattern validation
-- **[cloud-architect](cloud-architect.md)** - AWS/Azure/GCP infrastructure design and cost optimization
-- **[hybrid-cloud-architect](hybrid-cloud-architect.md)** - Multi-cloud strategies across cloud and on-premises environments
-- **[kubernetes-architect](kubernetes-architect.md)** - Cloud-native infrastructure with Kubernetes and GitOps
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [backend-architect](backend-architect.md) | opus | RESTful API design, microservice boundaries, database schemas |
+| [frontend-developer](frontend-developer.md) | sonnet | React components, responsive layouts, client-side state management |
+| [graphql-architect](graphql-architect.md) | opus | GraphQL schemas, resolvers, federation architecture |
+| [architect-reviewer](architect-review.md) | opus | Architectural consistency analysis and pattern validation |
+| [cloud-architect](cloud-architect.md) | opus | AWS/Azure/GCP infrastructure design and cost optimization |
+| [hybrid-cloud-architect](hybrid-cloud-architect.md) | opus | Multi-cloud strategies across cloud and on-premises environments |
+| [kubernetes-architect](kubernetes-architect.md) | opus | Cloud-native infrastructure with Kubernetes and GitOps |
 
 #### UI/UX & Mobile
-- **[ui-ux-designer](ui-ux-designer.md)** - Interface design, wireframes, design systems
-- **[ui-visual-validator](ui-visual-validator.md)** - Visual regression testing and UI verification
-- **[mobile-developer](mobile-developer.md)** - React Native and Flutter application development
-- **[ios-developer](ios-developer.md)** - Native iOS development with Swift/SwiftUI
-- **[flutter-expert](flutter-expert.md)** - Advanced Flutter development with state management
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [ui-ux-designer](ui-ux-designer.md) | sonnet | Interface design, wireframes, design systems |
+| [ui-visual-validator](ui-visual-validator.md) | sonnet | Visual regression testing and UI verification |
+| [mobile-developer](mobile-developer.md) | sonnet | React Native and Flutter application development |
+| [ios-developer](ios-developer.md) | sonnet | Native iOS development with Swift/SwiftUI |
+| [flutter-expert](flutter-expert.md) | sonnet | Advanced Flutter development with state management |
 
 ### Programming Languages
 
 #### Systems & Low-Level
-- **[c-pro](c-pro.md)** - System programming with memory management and OS interfaces
-- **[cpp-pro](cpp-pro.md)** - Modern C++ with RAII, smart pointers, STL algorithms
-- **[rust-pro](rust-pro.md)** - Memory-safe systems programming with ownership patterns
-- **[golang-pro](golang-pro.md)** - Concurrent programming with goroutines and channels
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [c-pro](c-pro.md) | sonnet | System programming with memory management and OS interfaces |
+| [cpp-pro](cpp-pro.md) | sonnet | Modern C++ with RAII, smart pointers, STL algorithms |
+| [rust-pro](rust-pro.md) | sonnet | Memory-safe systems programming with ownership patterns |
+| [golang-pro](golang-pro.md) | sonnet | Concurrent programming with goroutines and channels |
 
 #### Web & Application
-- **[javascript-pro](javascript-pro.md)** - Modern JavaScript with ES6+, async patterns, Node.js
-- **[typescript-pro](typescript-pro.md)** - Advanced TypeScript with type systems and generics
-- **[python-pro](python-pro.md)** - Python development with advanced features and optimization
-- **[ruby-pro](ruby-pro.md)** - Ruby with metaprogramming, Rails patterns, gem development
-- **[php-pro](php-pro.md)** - Modern PHP with frameworks and performance optimization
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [javascript-pro](javascript-pro.md) | sonnet | Modern JavaScript with ES6+, async patterns, Node.js |
+| [typescript-pro](typescript-pro.md) | sonnet | Advanced TypeScript with type systems and generics |
+| [python-pro](python-pro.md) | sonnet | Python development with advanced features and optimization |
+| [ruby-pro](ruby-pro.md) | sonnet | Ruby with metaprogramming, Rails patterns, gem development |
+| [php-pro](php-pro.md) | sonnet | Modern PHP with frameworks and performance optimization |
 
 #### Enterprise & JVM
-- **[java-pro](java-pro.md)** - Modern Java with streams, concurrency, JVM optimization
-- **[scala-pro](scala-pro.md)** - Enterprise Scala with functional programming and distributed systems
-- **[csharp-pro](csharp-pro.md)** - C# development with .NET frameworks and patterns
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [java-pro](java-pro.md) | sonnet | Modern Java with streams, concurrency, JVM optimization |
+| [scala-pro](scala-pro.md) | sonnet | Enterprise Scala with functional programming and distributed systems |
+| [csharp-pro](csharp-pro.md) | sonnet | C# development with .NET frameworks and patterns |
 
 #### Specialized Platforms
-- **[elixir-pro](elixir-pro.md)** - Elixir with OTP patterns and Phoenix frameworks
-- **[unity-developer](unity-developer.md)** - Unity game development and optimization
-- **[minecraft-bukkit-pro](minecraft-bukkit-pro.md)** - Minecraft server plugin development
-- **[sql-pro](sql-pro.md)** - Complex SQL queries and database optimization
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [elixir-pro](elixir-pro.md) | sonnet | Elixir with OTP patterns and Phoenix frameworks |
+| [unity-developer](unity-developer.md) | sonnet | Unity game development and optimization |
+| [minecraft-bukkit-pro](minecraft-bukkit-pro.md) | sonnet | Minecraft server plugin development |
+| [sql-pro](sql-pro.md) | sonnet | Complex SQL queries and database optimization |
 
 ### Infrastructure & Operations
 
 #### DevOps & Deployment
-- **[devops-troubleshooter](devops-troubleshooter.md)** - Production debugging, log analysis, deployment troubleshooting
-- **[deployment-engineer](deployment-engineer.md)** - CI/CD pipelines, containerization, cloud deployments
-- **[terraform-specialist](terraform-specialist.md)** - Infrastructure as Code with Terraform modules and state management
-- **[dx-optimizer](dx-optimizer.md)** - Developer experience optimization and tooling improvements
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [devops-troubleshooter](devops-troubleshooter.md) | sonnet | Production debugging, log analysis, deployment troubleshooting |
+| [deployment-engineer](deployment-engineer.md) | sonnet | CI/CD pipelines, containerization, cloud deployments |
+| [terraform-specialist](terraform-specialist.md) | opus | Infrastructure as Code with Terraform modules and state management |
+| [dx-optimizer](dx-optimizer.md) | sonnet | Developer experience optimization and tooling improvements |
 
 #### Database Management
-- **[database-optimizer](database-optimizer.md)** - Query optimization, index design, migration strategies
-- **[database-admin](database-admin.md)** - Database operations, backup, replication, monitoring
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [database-optimizer](database-optimizer.md) | opus | Query optimization, index design, migration strategies |
+| [database-admin](database-admin.md) | sonnet | Database operations, backup, replication, monitoring |
 
 #### Incident Response & Network
-- **[incident-responder](incident-responder.md)** - Production incident management and resolution
-- **[network-engineer](network-engineer.md)** - Network debugging, load balancing, traffic analysis
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [incident-responder](incident-responder.md) | opus | Production incident management and resolution |
+| [network-engineer](network-engineer.md) | sonnet | Network debugging, load balancing, traffic analysis |
 
 ### Quality Assurance & Security
 
 #### Code Quality & Review
-- **[code-reviewer](code-reviewer.md)** - Code review with security focus and production reliability
-- **[security-auditor](security-auditor.md)** - Vulnerability assessment and OWASP compliance
-- **[architect-reviewer](architect-review.md)** - Architectural consistency and pattern validation
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [code-reviewer](code-reviewer.md) | opus | Code review with security focus and production reliability |
+| [security-auditor](security-auditor.md) | opus | Vulnerability assessment and OWASP compliance |
+| [architect-reviewer](architect-review.md) | opus | Architectural consistency and pattern validation |
 
 #### Testing & Debugging
-- **[test-automator](test-automator.md)** - Comprehensive test suite creation (unit, integration, e2e)
-- **[tdd-orchestrator](tdd-orchestrator.md)** - Test-Driven Development methodology guidance
-- **[debugger](debugger.md)** - Error resolution and test failure analysis
-- **[error-detective](error-detective.md)** - Log analysis and error pattern recognition
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [test-automator](test-automator.md) | sonnet | Comprehensive test suite creation (unit, integration, e2e) |
+| [tdd-orchestrator](tdd-orchestrator.md) | sonnet | Test-Driven Development methodology guidance |
+| [debugger](debugger.md) | sonnet | Error resolution and test failure analysis |
+| [error-detective](error-detective.md) | sonnet | Log analysis and error pattern recognition |
 
 #### Performance & Research
-- **[performance-engineer](performance-engineer.md)** - Application profiling and optimization
-- **[search-specialist](search-specialist.md)** - Advanced web research and information synthesis
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [performance-engineer](performance-engineer.md) | opus | Application profiling and optimization |
+| [search-specialist](search-specialist.md) | haiku | Advanced web research and information synthesis |
 
 ### Data & AI
 
 #### Data Engineering & Analytics
-- **[data-scientist](data-scientist.md)** - Data analysis, SQL queries, BigQuery operations
-- **[data-engineer](data-engineer.md)** - ETL pipelines, data warehouses, streaming architectures
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [data-scientist](data-scientist.md) | opus | Data analysis, SQL queries, BigQuery operations |
+| [data-engineer](data-engineer.md) | sonnet | ETL pipelines, data warehouses, streaming architectures |
 
 #### Machine Learning & AI
-- **[ai-engineer](ai-engineer.md)** - LLM applications, RAG systems, prompt pipelines
-- **[ml-engineer](ml-engineer.md)** - ML pipelines, model serving, feature engineering
-- **[mlops-engineer](mlops-engineer.md)** - ML infrastructure, experiment tracking, model registries
-- **[prompt-engineer](prompt-engineer.md)** - LLM prompt optimization and engineering
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [ai-engineer](ai-engineer.md) | opus | LLM applications, RAG systems, prompt pipelines |
+| [ml-engineer](ml-engineer.md) | opus | ML pipelines, model serving, feature engineering |
+| [mlops-engineer](mlops-engineer.md) | opus | ML infrastructure, experiment tracking, model registries |
+| [prompt-engineer](prompt-engineer.md) | opus | LLM prompt optimization and engineering |
 
 ### Documentation & Technical Writing
 
-- **[docs-architect](docs-architect.md)** - Comprehensive technical documentation generation
-- **[api-documenter](api-documenter.md)** - OpenAPI/Swagger specifications and developer docs
-- **[reference-builder](reference-builder.md)** - Technical references and API documentation
-- **[tutorial-engineer](tutorial-engineer.md)** - Step-by-step tutorials and educational content
-- **[mermaid-expert](mermaid-expert.md)** - Diagram creation (flowcharts, sequences, ERDs)
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [docs-architect](docs-architect.md) | opus | Comprehensive technical documentation generation |
+| [api-documenter](api-documenter.md) | sonnet | OpenAPI/Swagger specifications and developer docs |
+| [reference-builder](reference-builder.md) | haiku | Technical references and API documentation |
+| [tutorial-engineer](tutorial-engineer.md) | sonnet | Step-by-step tutorials and educational content |
+| [mermaid-expert](mermaid-expert.md) | sonnet | Diagram creation (flowcharts, sequences, ERDs) |
 
 ### Business & Operations
 
 #### Business Analysis & Finance
-- **[business-analyst](business-analyst.md)** - Metrics analysis, reporting, KPI tracking
-- **[quant-analyst](quant-analyst.md)** - Financial modeling, trading strategies, market analysis
-- **[risk-manager](risk-manager.md)** - Portfolio risk monitoring and management
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [business-analyst](business-analyst.md) | sonnet | Metrics analysis, reporting, KPI tracking |
+| [quant-analyst](quant-analyst.md) | opus | Financial modeling, trading strategies, market analysis |
+| [risk-manager](risk-manager.md) | sonnet | Portfolio risk monitoring and management |
 
 #### Marketing & Sales
-- **[content-marketer](content-marketer.md)** - Blog posts, social media, email campaigns
-- **[sales-automator](sales-automator.md)** - Cold emails, follow-ups, proposal generation
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [content-marketer](content-marketer.md) | sonnet | Blog posts, social media, email campaigns |
+| [sales-automator](sales-automator.md) | haiku | Cold emails, follow-ups, proposal generation |
 
 #### Support & Legal
-- **[customer-support](customer-support.md)** - Support tickets, FAQ responses, customer communication
-- **[hr-pro](hr-pro.md)** - HR operations, policies, employee relations
-- **[legal-advisor](legal-advisor.md)** - Privacy policies, terms of service, legal documentation
+
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [customer-support](customer-support.md) | sonnet | Support tickets, FAQ responses, customer communication |
+| [hr-pro](hr-pro.md) | opus | HR operations, policies, employee relations |
+| [legal-advisor](legal-advisor.md) | opus | Privacy policies, terms of service, legal documentation |
 
 ### Specialized Domains
 
-- **[payment-integration](payment-integration.md)** - Payment processor integration (Stripe, PayPal)
-- **[legacy-modernizer](legacy-modernizer.md)** - Legacy code refactoring and modernization
-- **[context-manager](context-manager.md)** - Multi-agent context management
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [payment-integration](payment-integration.md) | sonnet | Payment processor integration (Stripe, PayPal) |
+| [legacy-modernizer](legacy-modernizer.md) | sonnet | Legacy code refactoring and modernization |
+| [context-manager](context-manager.md) | haiku | Multi-agent context management |
 
 ### SEO & Content Optimization
 
-- **[seo-content-auditor](seo-content-auditor.md)** - Content quality analysis, E-E-A-T signals assessment
-- **[seo-meta-optimizer](seo-meta-optimizer.md)** - Meta title and description optimization
-- **[seo-keyword-strategist](seo-keyword-strategist.md)** - Keyword analysis and semantic variations
-- **[seo-structure-architect](seo-structure-architect.md)** - Content structure and schema markup
-- **[seo-snippet-hunter](seo-snippet-hunter.md)** - Featured snippet formatting
-- **[seo-content-refresher](seo-content-refresher.md)** - Content freshness analysis
-- **[seo-cannibalization-detector](seo-cannibalization-detector.md)** - Keyword overlap detection
-- **[seo-authority-builder](seo-authority-builder.md)** - E-E-A-T signal analysis
-- **[seo-content-writer](seo-content-writer.md)** - SEO-optimized content creation
-- **[seo-content-planner](seo-content-planner.md)** - Content planning and topic clusters
+| Agent | Model | Description |
+|-------|-------|-------------|
+| [seo-content-auditor](seo-content-auditor.md) | sonnet | Content quality analysis, E-E-A-T signals assessment |
+| [seo-meta-optimizer](seo-meta-optimizer.md) | haiku | Meta title and description optimization |
+| [seo-keyword-strategist](seo-keyword-strategist.md) | haiku | Keyword analysis and semantic variations |
+| [seo-structure-architect](seo-structure-architect.md) | haiku | Content structure and schema markup |
+| [seo-snippet-hunter](seo-snippet-hunter.md) | haiku | Featured snippet formatting |
+| [seo-content-refresher](seo-content-refresher.md) | haiku | Content freshness analysis |
+| [seo-cannibalization-detector](seo-cannibalization-detector.md) | haiku | Keyword overlap detection |
+| [seo-authority-builder](seo-authority-builder.md) | sonnet | E-E-A-T signal analysis |
+| [seo-content-writer](seo-content-writer.md) | sonnet | SEO-optimized content creation |
+| [seo-content-planner](seo-content-planner.md) | haiku | Content planning and topic clusters |
 
 ## Model Configuration
 
 Agents are assigned to specific Claude models based on task complexity and computational requirements. The system uses three model tiers:
 
-### Haiku Model (Fast Response) - 11 agents
-Optimized for quick, focused tasks with minimal computational overhead:
-- `context-manager`, `reference-builder`, `sales-automator`, `search-specialist`
-- SEO agents: `seo-meta-optimizer`, `seo-keyword-strategist`, `seo-structure-architect`, `seo-snippet-hunter`, `seo-content-refresher`, `seo-cannibalization-detector`, `seo-content-planner`
+### Model Distribution Summary
 
-### Sonnet Model (Balanced Performance) - 46 agents
-Standard model for development and specialized tasks:
-- Language specialists (18): All programming language agents
-- Frontend/UI agents (5): `frontend-developer`, `ui-ux-designer`, `ui-visual-validator`, `mobile-developer`, `ios-developer`
-- Infrastructure agents (14): DevOps, database, network, and deployment specialists
-- Quality/Testing agents (4): `test-automator`, `tdd-orchestrator`, `debugger`, `error-detective`
-- Data/ML agents (5): Basic ML and data engineering tasks
+| Model | Agent Count | Use Case |
+|-------|-------------|----------|
+| Haiku | 11 | Quick, focused tasks with minimal computational overhead |
+| Sonnet | 46 | Standard development and specialized engineering tasks |
+| Opus | 21 | Complex reasoning, architecture, and critical analysis |
 
-### Opus Model (Maximum Capability) - 21 agents
-Reserved for complex reasoning and critical analysis:
-- Architecture & Design (7): `architect-reviewer`, `backend-architect`, `cloud-architect`, `hybrid-cloud-architect`, `kubernetes-architect`, `graphql-architect`, `terraform-specialist`
-- Critical Analysis (5): `code-reviewer`, `security-auditor`, `performance-engineer`, `incident-responder`, `database-optimizer`
-- AI/ML Complex (5): `ai-engineer`, `ml-engineer`, `mlops-engineer`, `data-scientist`, `prompt-engineer`
-- Business Critical (4): `docs-architect`, `hr-pro`, `legal-advisor`, `quant-analyst`
+### Haiku Model Agents
+
+| Category | Agents |
+|----------|--------|
+| Context & Reference | `context-manager`, `reference-builder`, `sales-automator`, `search-specialist` |
+| SEO Optimization | `seo-meta-optimizer`, `seo-keyword-strategist`, `seo-structure-architect`, `seo-snippet-hunter`, `seo-content-refresher`, `seo-cannibalization-detector`, `seo-content-planner` |
+
+### Sonnet Model Agents
+
+| Category | Count | Agents |
+|----------|-------|--------|
+| Programming Languages | 18 | All language-specific agents (JavaScript, Python, Java, C++, etc.) |
+| Frontend & UI | 5 | `frontend-developer`, `ui-ux-designer`, `ui-visual-validator`, `mobile-developer`, `ios-developer` |
+| Infrastructure | 8 | `devops-troubleshooter`, `deployment-engineer`, `dx-optimizer`, `database-admin`, `network-engineer`, `flutter-expert`, `api-documenter`, `tutorial-engineer` |
+| Quality & Testing | 4 | `test-automator`, `tdd-orchestrator`, `debugger`, `error-detective` |
+| Business & Support | 6 | `business-analyst`, `risk-manager`, `content-marketer`, `customer-support`, `mermaid-expert`, `legacy-modernizer` |
+| Data & Content | 5 | `data-engineer`, `payment-integration`, `seo-content-auditor`, `seo-authority-builder`, `seo-content-writer` |
+
+### Opus Model Agents
+
+| Category | Count | Agents |
+|----------|-------|--------|
+| Architecture & Design | 7 | `architect-reviewer`, `backend-architect`, `cloud-architect`, `hybrid-cloud-architect`, `kubernetes-architect`, `graphql-architect`, `terraform-specialist` |
+| Critical Analysis | 5 | `code-reviewer`, `security-auditor`, `performance-engineer`, `incident-responder`, `database-optimizer` |
+| AI/ML Complex | 5 | `ai-engineer`, `ml-engineer`, `mlops-engineer`, `data-scientist`, `prompt-engineer` |
+| Business Critical | 4 | `docs-architect`, `hr-pro`, `legal-advisor`, `quant-analyst` |
 
 ## Installation
 
@@ -335,43 +407,62 @@ payment-integration → security-auditor → Validated implementation
 ## Agent Selection Guide
 
 ### Architecture & Planning
-- `backend-architect`: API design, microservices, database schemas
-- `cloud-architect`: Infrastructure design, scalability planning
-- `ui-ux-designer`: Interface design, wireframes, design systems
+
+| Task | Recommended Agent | Key Capabilities |
+|------|------------------|------------------|
+| API Design | `backend-architect` | RESTful APIs, microservices, database schemas |
+| Cloud Infrastructure | `cloud-architect` | AWS/Azure/GCP design, scalability planning |
+| UI/UX Design | `ui-ux-designer` | Interface design, wireframes, design systems |
+| System Architecture | `architect-reviewer` | Pattern validation, consistency analysis |
 
 ### Development by Language
-- Systems: `c-pro`, `cpp-pro`, `rust-pro`, `golang-pro`
-- Web: `javascript-pro`, `typescript-pro`, `python-pro`, `ruby-pro`, `php-pro`
-- Enterprise: `java-pro`, `csharp-pro`, `scala-pro`
-- Mobile: `ios-developer`, `flutter-expert`, `mobile-developer`
-- Specialized: `elixir-pro`, `unity-developer`, `minecraft-bukkit-pro`
+
+| Language Category | Agents | Primary Use Cases |
+|-------------------|--------|-------------------|
+| Systems Programming | `c-pro`, `cpp-pro`, `rust-pro`, `golang-pro` | OS interfaces, embedded systems, high performance |
+| Web Development | `javascript-pro`, `typescript-pro`, `python-pro`, `ruby-pro`, `php-pro` | Full-stack web applications, APIs, scripting |
+| Enterprise | `java-pro`, `csharp-pro`, `scala-pro` | Large-scale applications, enterprise systems |
+| Mobile | `ios-developer`, `flutter-expert`, `mobile-developer` | Native and cross-platform mobile apps |
+| Specialized | `elixir-pro`, `unity-developer`, `minecraft-bukkit-pro` | Domain-specific development |
 
 ### Operations & Infrastructure
-- `devops-troubleshooter`: Production issues, deployment problems
-- `incident-responder`: Critical outages and immediate response
-- `database-optimizer`: Query performance, indexing strategies
-- `database-admin`: Backup, replication, disaster recovery
-- `terraform-specialist`: Infrastructure as Code
-- `network-engineer`: Network debugging, load balancing
+
+| Task | Recommended Agent | Key Capabilities |
+|------|------------------|------------------|
+| Production Issues | `devops-troubleshooter` | Log analysis, deployment debugging |
+| Critical Incidents | `incident-responder` | Outage response, immediate mitigation |
+| Database Performance | `database-optimizer` | Query optimization, indexing strategies |
+| Database Operations | `database-admin` | Backup, replication, disaster recovery |
+| Infrastructure as Code | `terraform-specialist` | Terraform modules, state management |
+| Network Issues | `network-engineer` | Network debugging, load balancing |
 
 ### Quality & Security
-- `code-reviewer`: Code quality and security analysis
-- `security-auditor`: Vulnerability scanning, compliance
-- `test-automator`: Test suite creation and strategy
-- `performance-engineer`: Application optimization
-- `debugger`: Bug investigation and resolution
+
+| Task | Recommended Agent | Key Capabilities |
+|------|------------------|------------------|
+| Code Review | `code-reviewer` | Security focus, best practices |
+| Security Audit | `security-auditor` | Vulnerability scanning, OWASP compliance |
+| Test Creation | `test-automator` | Unit, integration, E2E test suites |
+| Performance Issues | `performance-engineer` | Profiling, optimization |
+| Bug Investigation | `debugger` | Error resolution, root cause analysis |
 
 ### Data & Machine Learning
-- `data-scientist`: Data analysis and insights
-- `ai-engineer`: LLM applications and RAG systems
-- `ml-engineer`: Model development and deployment
-- `mlops-engineer`: ML infrastructure and pipelines
+
+| Task | Recommended Agent | Key Capabilities |
+|------|------------------|------------------|
+| Data Analysis | `data-scientist` | SQL queries, statistical analysis |
+| LLM Applications | `ai-engineer` | RAG systems, prompt pipelines |
+| ML Development | `ml-engineer` | Model training, feature engineering |
+| ML Operations | `mlops-engineer` | ML infrastructure, experiment tracking |
 
 ### Documentation & Business
-- `docs-architect`: Technical documentation generation
-- `api-documenter`: OpenAPI specifications
-- `business-analyst`: Metrics and reporting
-- `legal-advisor`: Legal documentation and compliance
+
+| Task | Recommended Agent | Key Capabilities |
+|------|------------------|------------------|
+| Technical Docs | `docs-architect` | Comprehensive documentation generation |
+| API Documentation | `api-documenter` | OpenAPI/Swagger specifications |
+| Business Metrics | `business-analyst` | KPI tracking, reporting |
+| Legal Compliance | `legal-advisor` | Privacy policies, terms of service |
 
 ## Best Practices