18 - Multi-Agent Orchestration with Claude

# Installation via Go
go install github.com/smtg-ai/claude-squad@latest

# Or from source
git clone https://github.com/smtg-ai/claude-squad.git
cd claude-squad
go build -o claude-squad

# Verify installation
claude-squad --version

# Start Claude Squad
claude-squad

# Create a new instance with a specific task
# In the TUI interface:
# [n] - New instance
# [d] - Describe the task
# [Enter] - Start

# Example: 3 parallel agents for a full-stack project
# Agent 1: "Implement the REST endpoint /api/v1/orders with validation"
# Agent 2: "Create the Angular OrderListComponent with pagination"
# Agent 3: "Write integration tests for the orders module"

# TUI Commands
# [Tab]   - Switch to next session
# [1-9]   - Select session by number
# [Enter] - Send input to active session
# [q]     - Exit Claude Squad

# Session 1: Order Management
Prompt: "Implement the complete CRUD for orders.
- Entity Order with fields: id, customerId, items, total, status, createdAt
- OrderRepository with queries by customer and status
- OrderService with business rules validation
- OrderController with REST endpoints
- Unit tests for service and controller"

# Session 2: Notification System
Prompt: "Create the email notification system.
- NotificationService with template engine (Thymeleaf)
- Templates for: order confirmation, shipping, payment
- Event listener for OrderCreatedEvent and OrderShippedEvent
- SMTP configuration with fallback
- Integration tests with MailHog"

# Session 3: Reporting Module
Prompt: "Implement the order reporting module.
- ReportService with sales data aggregation
- Endpoint /api/v1/reports/sales with date filters
- CSV and PDF export (with iText)
- Redis cache for frequent reports
- Tests with simulated data"

# Global installation
npm install -g task-master-ai

# Project initialization
task-master init

# This creates the structure:
# .task-master/
#   config.json       - Project configuration
#   tasks/            - Generated tasks directory
#   dependencies.json - Dependency graph
#   progress.json     - Progress status

# Generate tasks from a project description
task-master parse-prd --input=docs/requirements.md

# Example output:
# Generated 24 tasks from PRD:
#
# Task 1: Base project setup (priority: high, complexity: 3)
#   Dependencies: none
#   Subtasks: init repo, configure build, setup CI
#
# Task 2: Database schema (priority: high, complexity: 5)
#   Dependencies: Task 1
#   Subtasks: design ERD, create migrations, seed data
#
# Task 3: User authentication (priority: high, complexity: 8)
#   Dependencies: Task 1, Task 2
#   Subtasks: JWT setup, login/register endpoints, middleware
#
# ...

# Visualize the dependency graph
task-master graph

# Get the next task to work on
task-master next

# Output:
# Next recommended task: Task 4 - Orders API
# Reason: All dependencies met, highest priority among available tasks
# Estimated complexity: 5/10
# Estimated time: 2-3 hours

# 1. Generate tasks from the PRD
task-master parse-prd --input=docs/requirements.md

# 2. Get the next task with full context
task-master next --with-context

# 3. Pass the context to Claude Code
claude "Implement the following task:
$(task-master next --with-context)

Relevant files to consult:
$(task-master files --task=current)

Acceptance criteria:
$(task-master acceptance --task=current)"

# 4. Mark the task as completed
task-master complete --task=4

# 5. Regenerate dependencies for subsequent tasks
task-master update-deps

# Auto-Claude Architecture
#
# +---------------------+
# |    Orchestrator      |
# |  (Claude Instance)   |
# +---------------------+
#      |    |    |
#      v    v    v
# +------+ +------+ +------+
# |Worker| |Worker| |Worker|
# |  #1  | |  #2  | |  #3  |
# +------+ +------+ +------+
#    |        |        |
#    v        v        v
# [Files]  [Files]  [Files]
#
# The orchestrator:
# 1. Receives the objective from the user
# 2. Analyzes the codebase
# 3. Generates an execution plan
# 4. Creates a worker for each sub-task
# 5. Monitors progress
# 6. Manages conflicts between workers
# 7. Validates results
# 8. Produces the final report

# Auto-Claude loop pseudocode

while objective_not_reached:
    # 1. Evaluate current state
    state = analyze_progress(workers)

    # 2. Identify blocks
    blocks = find_blocks(state)

    # 3. If there are blocks, intervene
    for block in blocks:
        if block.type == "missing_dependency":
            reorder_tasks(block.worker)
        elif block.type == "compilation_error":
            assign_fix(block.worker, block.error)
        elif block.type == "merge_conflict":
            resolve_conflict(block.workers)
        elif block.type == "timeout":
            restart_worker(block.worker)

    # 4. Verify completed tasks
    for worker in completed_workers:
        if validate_output(worker):
            mark_completed(worker)
            release_dependencies(worker)
        else:
            reassign_task(worker, feedback="Invalid output")

    # 5. Assign new tasks if there are free workers
    for worker in free_workers:
        next_task = get_next_task()
        if next_task:
            assign_task(worker, next_task)

    # 6. Verify global objective
    if all_tasks_completed():
        execute_final_validation()
        break

    sleep(check_interval)

# swarm-config.yaml
swarm:
  name: "e-commerce-project"
  max_agents: 5
  communication:
    protocol: "pub-sub"
    shared_state: true
    conflict_resolution: "last-writer-wins"

  agents:
    - name: "frontend-agent"
      role: "Frontend Developer"
      focus: ["src/app/**/*.ts", "src/app/**/*.html", "src/app/**/*.css"]
      subscribe: ["api-changes", "schema-changes"]
      publish: ["ui-updates"]

    - name: "backend-agent"
      role: "Backend Developer"
      focus: ["src/main/java/**/*.java"]
      subscribe: ["schema-changes", "ui-requirements"]
      publish: ["api-changes"]

    - name: "database-agent"
      role: "Database Engineer"
      focus: ["migrations/**", "schema/**"]
      subscribe: ["data-requirements"]
      publish: ["schema-changes"]

    - name: "test-agent"
      role: "QA Engineer"
      focus: ["src/test/**", "e2e/**"]
      subscribe: ["api-changes", "ui-updates", "schema-changes"]
      publish: ["test-results", "bug-reports"]

    - name: "devops-agent"
      role: "DevOps Engineer"
      focus: ["docker/**", ".github/**", "deploy/**"]
      subscribe: ["build-requirements"]
      publish: ["deploy-status"]

  rules:
    - "frontend-agent does not modify Java files"
    - "backend-agent does not modify Angular files"
    - "test-agent has read access to everything"
    - "Each agent commits on its own branch"
    - "Merge only after automatic review"

# Project structure with worktrees
# /projects/my-app/           (main worktree, branch main)
# /projects/my-app-feature-a/ (worktree for feature A)
# /projects/my-app-feature-b/ (worktree for feature B)
# /projects/my-app-bugfix/    (worktree for bugfix)

# Create worktree for feature A
git worktree add ../my-app-feature-a feature/user-auth
# Creating branch 'feature/user-auth'
# Preparing worktree (new branch 'feature/user-auth')

# Create worktree for feature B
git worktree add ../my-app-feature-b feature/payment-system
# Creating branch 'feature/payment-system'
# Preparing worktree (new branch 'feature/payment-system')

# Create worktree for urgent bugfix
git worktree add ../my-app-bugfix hotfix/login-timeout
# Creating branch 'hotfix/login-timeout'
# Preparing worktree (new branch 'hotfix/login-timeout')

# Verify active worktrees
git worktree list
# /projects/my-app              abc1234 [main]
# /projects/my-app-feature-a    abc1234 [feature/user-auth]
# /projects/my-app-feature-b    abc1234 [feature/payment-system]
# /projects/my-app-bugfix       abc1234 [hotfix/login-timeout]

# Terminal 1: Claude Code in feature A worktree
cd /projects/my-app-feature-a
claude "Implement the user authentication system:
- JWT with refresh token
- Login, register, logout endpoints
- Authentication middleware
- Password hashing with bcrypt
- Rate limiting on auth endpoints"

# Terminal 2: Claude Code in feature B worktree
cd /projects/my-app-feature-b
claude "Implement the payment system with Stripe:
- Stripe SDK integration
- Endpoint to create PaymentIntent
- Webhook for payment confirmation
- Error handling and retry
- Transaction logging"

# Terminal 3: Claude Code in bugfix worktree
cd /projects/my-app-bugfix
claude "Fix the timeout bug on the login page:
- Analyze the LoginComponent
- Identify the cause of the timeout after 30 seconds
- Implement the fix while maintaining security
- Add tests for the specific case"

# 1. Return to the main worktree
cd /projects/my-app

# 2. Merge the bugfix first (highest priority)
git merge hotfix/login-timeout
# No conflicts, direct merge

# 3. Merge feature A
git merge feature/user-auth
# Possible conflicts on shared files (app.module, routes)
# Resolve conflicts manually or with Claude:
# claude "Resolve merge conflicts between main and feature/user-auth"

# 4. Merge feature B
git merge feature/payment-system
# May have conflicts with routes added by feature A

# 5. Cleanup: remove completed worktrees
git worktree remove ../my-app-feature-a
git worktree remove ../my-app-feature-b
git worktree remove ../my-app-bugfix

# 6. Delete local branches
git branch -d feature/user-auth feature/payment-system hotfix/login-timeout

# Pattern: Divide-and-Conquer
#
#         [Complex Task]
#              |
#         [Decomposition]
#        /     |      \
#       v      v       v
#   [Sub-A] [Sub-B] [Sub-C]    <-- Parallel execution
#       \      |      /
#        v     v     v
#         [Combination]
#              |
#              v
#         [Result]

# Practical example: Refactoring a monolith
# Sub-A: Extract the users module
# Sub-B: Extract the orders module
# Sub-C: Extract the payments module
# Combination: Integrate the modules with defined interfaces

# When to use it:
# - Naturally parallelizable tasks
# - Minimal dependencies between sub-tasks
# - Mechanically combinable results
# - Example: generation of independent UI components

# Pattern: Pipeline
#
# [Input] --> [Agent 1] --> [Agent 2] --> [Agent 3] --> [Output]
#             Architect      Developer      Tester
#
# Stage 1 (Architect):
#   Input: User requirements
#   Output: Design document, interfaces, DB schema
#
# Stage 2 (Developer):
#   Input: Design document from Stage 1
#   Output: Code implemented according to the design
#
# Stage 3 (Tester):
#   Input: Code from Stage 2
#   Output: Test suite, coverage report, bug fixes

# Advantages:
# - Each agent is specialized in its stage
# - Well-defined output between stages
# - Easy to debug (which stage failed?)
# - Incremental quality at each step

# Disadvantages:
# - Sequential (not parallelizable)
# - Bottleneck: the slowest stage
# - Errors in stage 1 cascade downstream

# Pattern: Swarm
#
#   [A1] <--> [A2]
#    ^  \    /  ^
#    |   \  /   |
#    v    \/    v
#   [A3] /\  [A4]
#    ^  /  \  ^
#    | /    \ |
#    v       v
#   [A5] <--> [A6]
#
# Each agent:
# 1. Observes the global project state
# 2. Autonomously identifies the next task
# 3. Communicates with relevant agents
# 4. Executes the task
# 5. Publishes results
# 6. Repeats until the objective is reached

# Swarm rules:
# - No agent is the "boss"
# - Decisions made by local consensus
# - Conflicts resolved by predefined rules
# - The objective emerges from collective behavior

# When to use it:
# - Exploratory problems (complex debugging)
# - Very large codebase to analyze
# - When it's unclear how to decompose the task
# - Searching for creative solutions

# Multi-Agent Pre-flight Checklist

## Preparation
- [ ] Tasks decomposed into independent sub-tasks
- [ ] Dependencies between tasks identified and documented
- [ ] File ownership assigned for each agent
- [ ] Interfaces between modules defined and stable
- [ ] CLAUDE.md updated with team conventions
- [ ] Branch strategy defined (one branch per agent)

## Configuration
- [ ] Token budget per agent set
- [ ] Session timeout configured
- [ ] Monitoring activated (costs, progress, errors)
- [ ] Fallback plan for individual agent failures
- [ ] Test suite ready for post-merge validation

## Execution
- [ ] Start agents in dependency order
- [ ] Monitor progress every 15-30 minutes
- [ ] Intervene manually if an agent is blocked for more than 1 hour
- [ ] Save intermediate checkpoints for each agent

## Post-Execution
- [ ] Merge in dependency order
- [ ] Resolve conflicts carefully
- [ ] Run complete test suite
- [ ] Code review of combined results
- [ ] Document lessons learned

# Project: Event Management Module
# Stack: Spring Boot + Angular + PostgreSQL
# Strategy: Divide-and-Conquer with Git Worktrees

# Step 1: Create the worktrees
git worktree add ../events-backend feature/events-backend
git worktree add ../events-frontend feature/events-frontend
git worktree add ../events-database feature/events-database
git worktree add ../events-tests feature/events-tests

# Step 2: Start the agents (4 separate terminals)

# Database Agent (starts first - others depend on the schema)
cd ../events-database
claude "Create the database schema for the events module:
- Table events (id, title, description, start_date, end_date, location, capacity, status)
- Table event_registrations (id, event_id, user_id, registered_at, status)
- Table event_categories (id, name, description)
- Table event_category_map (event_id, category_id)
- Indexes for the most frequent queries
- Numbered Flyway migrations
- Seed data for development"

# Backend Agent (after the schema is defined)
cd ../events-backend
claude "Implement the backend for the events module:
- JPA entities mapped to the existing schema in migrations/
- EventRepository with custom queries (findByDateRange, findByCategory)
- EventService with business logic (creation, registration, cancellation)
- EventController with REST CRUD endpoints
- DTOs for request/response
- Input validation with Bean Validation
- Error handling with exception handler
- OpenAPI documentation"

# Frontend Agent (after the APIs are defined)
cd ../events-frontend
claude "Implement the Angular frontend for the events module:
- EventListComponent with pagination and filters
- EventDetailComponent with registration
- EventFormComponent for creation/editing
- EventService for API calls
- Routing with lazy loading
- Responsive design (mobile-first)
- Unit tests for each component"

# Test Agent (works in parallel, writes end-to-end tests)
cd ../events-tests
claude "Write the test suite for the events module:
- Integration tests for EventController (MockMvc)
- Tests for EventService with repository mocks
- Cypress end-to-end tests for the main flows:
  - Event creation
  - Event registration
  - Registration cancellation
  - Event list viewing with filters
- Performance tests with JMeter (optional)"

# Step 3: Merge in order
# database -> backend -> frontend -> tests
git merge feature/events-database  # Schema first
git merge feature/events-backend   # API after schema
git merge feature/events-frontend  # UI after APIs
git merge feature/events-tests     # Tests at the end

# Step 4: Final validation
mvn test                    # Backend tests
npm test --prefix frontend  # Frontend tests
npm run e2e --prefix e2e    # End-to-end tests