Multi-Agent Workflows

Watercooler enables sophisticated multi-agent collaboration through structured threads, role-based entries, and ball-passing mechanics.

Core Concepts

Agents and Roles

Each entry in a thread has:

Agent: The individual (AI or human) making the entry
Role: The function they’re performing

Standard Roles:

Planner

Designs approach, breaks down work, identifies requirements

Implementer

Writes code, builds features, executes plans

Critic

Reviews work, identifies issues, ensures quality

Tester

Validates functionality, writes tests, finds bugs

PM

Coordinates work, manages priorities, tracks progress

Scribe

Documents decisions, maintains records, writes guides

Ball Ownership

The ball indicates whose turn it is to respond. This prevents:

Duplicate work
Confusion about responsibility
Infinite agent loops

Ball mechanics:

say: Automatically flips ball to counterpart
ack: Keeps ball with current owner
handoff: Explicitly passes ball to specified agent

Common Workflow Patterns

Pattern 1: Plan → Build → Review

Step 1: Planner designs the approach

watercooler init-thread api-refactor --ball codex

watercooler say api-refactor \
  --agent "Planner-GPT" \
  --role planner \
  --type Plan \
  --title "API Refactoring Strategy" \
  --body "Breaking into 3 phases: (1) Extract handlers, (2) Add middleware, (3) Update tests. Dependencies: none. Risks: backward compatibility."

Ball now with: team (auto-flipped from codex)

Step 2: PM acknowledges and assigns

watercooler ack api-refactor \
  --agent "Alice" \
  --role pm \
  --title "Approved" \
  --body "Plan looks good. Bob, please implement phase 1."
  
watercooler handoff api-refactor \
  --agent "Alice" \
  --note "Bob: start with phase 1"

Ball now with: codex (explicit handoff)

Step 3: Implementer builds

watercooler say api-refactor \
  --agent "Bob" \
  --role implementer \
  --title "Phase 1 complete" \
  --body "Extracted all route handlers to handlers/. Tested locally. Ready for review."

Ball now with: team

Step 4: Critic reviews

watercooler say api-refactor \
  --agent "Critic-Claude" \
  --role critic \
  --title "Review feedback" \
  --body "Good separation of concerns. Minor: add error handling in user_handler.py:45. Otherwise LGTM."

Ball now with: codex (back to implementer)

Step 5: Implementer addresses feedback

watercooler say api-refactor \
  --agent "Bob" \
  --role implementer \
  --title "Feedback addressed" \
  --body "Added error handling as requested. All tests passing."
  
watercooler set-status api-refactor CLOSED

Pattern 2: Investigation → Decision → Implementation

For exploratory work where the approach isn’t clear:

Multiple agents investigate

watercooler init-thread db-scaling --ball team

# Agent 1: Research
watercooler say db-scaling \
  --agent "Researcher" \
  --role planner \
  --title "Read replica analysis" \
  --body "Read replicas reduce load by 40% but add 100ms latency."

# Agent 2: Alternative approach
watercooler say db-scaling \
  --agent "Architect" \
  --role planner \
  --title "Caching layer analysis" \
  --body "Redis cache reduces DB hits by 80% with under 5ms latency."

PM makes decision

watercooler say db-scaling \
  --agent "Alice" \
  --role pm \
  --type Decision \
  --title "Decision: Redis caching" \
  --body "Going with Redis caching. Better latency profile and easier to implement. Bob to proceed with implementation."

Implementation proceeds

watercooler say db-scaling \
  --agent "Bob" \
  --role implementer \
  --title "Cache layer implemented" \
  --body "Redis cache in place with 1hr TTL. Monitoring shows 85% hit rate."

Pattern 3: Test-Driven Development

Planner writes specifications

watercooler say user-auth \
  --role planner \
  --title "Auth requirements" \
  --body "Must support: JWT tokens, 2FA, rate limiting, session management."

Tester writes test cases

watercooler say user-auth \
  --role tester \
  --title "Test scenarios" \
  --body "@test-cases.md"

Implementer makes tests pass

watercooler say user-auth \
  --role implementer \
  --title "Tests passing" \
  --body "All 24 test cases passing. JWT + 2FA working. Rate limiter at 100 req/min."

Advanced Patterns

Parallel Workstreams

Use separate threads for parallel work:

# Frontend work
watercooler init-thread feature-x-ui --ball frontend-team
watercooler say feature-x-ui --agent "UI-Dev" \
  --title "React components ready"

# Backend work (parallel)
watercooler init-thread feature-x-api --ball backend-team
watercooler say feature-x-api --agent "API-Dev" \
  --title "Endpoints implemented"

# Integration thread (depends on both)
watercooler init-thread feature-x-integration --ball qa-team
watercooler say feature-x-integration \
  --title "Integration testing" \
  --body "References: feature-x-ui, feature-x-api. All flows working."

Escalation Pattern

When blocked, escalate to higher authority:

# Implementer gets stuck
watercooler say complex-bug \
  --role implementer \
  --title "Blocked: need architecture decision" \
  --body "Should we refactor the whole module or patch the specific issue?"
  
watercooler set-status complex-bug BLOCKED

# Handoff to architect
watercooler handoff complex-bug \
  --agent "Developer" \
  --note "Need architect's input on approach"

# Architect unblocks
watercooler say complex-bug \
  --agent "Architect" \
  --role planner \
  --title "Decision: targeted patch" \
  --body "Patch the specific issue for now. Full refactor scheduled for Q2."
  
watercooler set-status complex-bug OPEN

Human-in-the-Loop

Mix AI agents and human oversight:

# AI agent proposes
watercooler say security-update \
  --agent "Security-Bot" \
  --role planner \
  --title "Proposed security patches" \
  --body "@security-analysis.md"

# Human approves
watercooler say security-update \
  --agent "Alice (Human)" \
  --role pm \
  --type Decision \
  --title "Approved with modifications" \
  --body "Approve patches 1-4. Hold patch 5 for further review."

# AI implements
watercooler say security-update \
  --agent "Implementation-Bot" \
  --role implementer \
  --title "Patches 1-4 deployed" \
  --body "Successfully deployed to staging. Monitoring for 24h before prod."

Agent Registry

Maintain consistent agent identities with a registry file:

Create agents.json

{
  "agents": {
    "planner": {
      "name": "Planner-GPT4",
      "role": "planner",
      "model": "gpt-4",
      "counterpart": "implementer"
    },
    "implementer": {
      "name": "Coder-Claude",
      "role": "implementer",
      "model": "claude-opus",
      "counterpart": "planner"
    },
    "critic": {
      "name": "Reviewer-GPT4",
      "role": "critic",
      "model": "gpt-4",
      "counterpart": "implementer"
    },
    "human": {
      "name": "Alice",
      "role": "pm",
      "counterpart": "planner"
    }
  },
  "default_agent": "Team",
  "default_counterpart": "codex"
}

Use with CLI

watercooler say feature-y \
  --agents-file agents.json \
  --agent planner \
  --title "Design complete"

Benefits:

Consistent naming
Automatic counterpart resolution
Track which models are being used
Easy to swap models without changing workflows

Ball Passing Strategies

Strategy 1: Ping-Pong (Default)

Two agents alternate:

# Codex → Team → Codex → Team
watercooler say topic --agent Codex    # ball → team
watercooler say topic --agent Human    # ball → codex
watercooler say topic --agent Codex    # ball → team

Strategy 2: Round-Robin

Multiple agents rotate:

watercooler say topic --agent A --ball B
watercooler say topic --agent B --ball C
watercooler say topic --agent C --ball A

Strategy 3: Broadcast (Manual)

One agent updates, all others ack:

# Coordinator sends update
watercooler say project-status \
  --agent PM \
  --title "Weekly update" \
  --body "Milestone 1 complete. Starting milestone 2." \
  --ball broadcast

# Agents acknowledge (without ball flip)
watercooler ack project-status --agent Dev1 --body "Noted"
watercooler ack project-status --agent Dev2 --body "Noted"
watercooler ack project-status --agent QA --body "Noted"

Status Management

Status Lifecycle

Status meanings:

OPEN: Active work in progress
BLOCKED: Waiting on external dependency or decision
CLOSED: Work completed successfully
ABANDONED: Work cancelled or no longer relevant

Workflow with Status

# Start work
watercooler init-thread task-123 --status OPEN

# Hit blocker
watercooler say task-123 \
  --title "Blocked on API access" \
  --body "Need API keys from security team"
watercooler set-status task-123 BLOCKED

# Unblock
watercooler say task-123 \
  --title "Keys received" \
  --body "Security team provided keys. Resuming work."
watercooler set-status task-123 OPEN

# Complete
watercooler say task-123 \
  --type Closure \
  --title "Task complete" \
  --body "Feature implemented and tested. Merged to main."
watercooler set-status task-123 CLOSED

Integration with Branch Pairing

Sync threads with Git branches for feature work:

# Create branch and thread together
git checkout -b feature/new-dashboard
watercooler init-thread new-dashboard

# Work proceeds in both
watercooler say new-dashboard --title "Layout designed"
git commit -am "Add dashboard layout"

# Merge both together
watercooler set-status new-dashboard CLOSED
git checkout main && git merge feature/new-dashboard

See the Branch Pairing guide for details.

Best Practices

1. Use Descriptive Titles

watercooler say topic --title "Update"

2. Include Context in Bodies

watercooler say topic --body "Done"

3. Use Type for Important Entries

# Mark key decisions
watercooler say topic --type Decision --title "Using PostgreSQL"

# Mark closures
watercooler say topic --type Closure --title "Feature complete"

4. Close Threads

Always close completed threads:

watercooler set-status completed-feature CLOSED

5. Use Reference Files for Long Content

# Instead of pasting long text
watercooler say topic --body "@analysis.md"
watercooler say topic --body "@implementation-notes.md"

Get Started

Core Concepts

Setup & Configuration

Guides

​Core Concepts

​Agents and Roles

Planner

Implementer

Critic

Tester

PM

Scribe

​Ball Ownership

​Common Workflow Patterns

​Pattern 1: Plan → Build → Review

​Pattern 2: Investigation → Decision → Implementation

​Pattern 3: Test-Driven Development

​Advanced Patterns

​Parallel Workstreams

​Escalation Pattern

​Human-in-the-Loop

​Agent Registry

​Create agents.json

​Use with CLI

​Ball Passing Strategies

​Strategy 1: Ping-Pong (Default)

​Strategy 2: Round-Robin

​Strategy 3: Broadcast (Manual)

​Status Management

​Status Lifecycle

​Workflow with Status

​Integration with Branch Pairing

​Best Practices

​1. Use Descriptive Titles

​2. Include Context in Bodies

​3. Use Type for Important Entries

​4. Close Threads

​5. Use Reference Files for Long Content

​Next Steps

Memory Graphs

Branch Pairing

Build docs developers (and LLMs) love

Core Concepts

Agents and Roles

Ball Ownership

Common Workflow Patterns

Pattern 1: Plan → Build → Review

Pattern 2: Investigation → Decision → Implementation

Pattern 3: Test-Driven Development

Advanced Patterns

Parallel Workstreams

Escalation Pattern

Human-in-the-Loop

Agent Registry

Create agents.json

Use with CLI

Ball Passing Strategies

Strategy 1: Ping-Pong (Default)

Strategy 2: Round-Robin

Strategy 3: Broadcast (Manual)

Status Management

Status Lifecycle

Workflow with Status

Integration with Branch Pairing

Best Practices

1. Use Descriptive Titles

2. Include Context in Bodies

3. Use Type for Important Entries

4. Close Threads

5. Use Reference Files for Long Content

Next Steps