# 🤖 GreenLight AI Agent Coordination

**Layer 14: Multi-Claude Collaboration & Specialization**

---

## 🤖 Why AI Agent Coordination Matters

**The Problem:** We have multiple Claudes, but we're not truly working as a *team*.
- No visibility into what each Claude is doing
- No way to route tasks to specialists
- No clean handoffs between agents
- No consensus building on big decisions
- No load balancing or work distribution

**The Solution:** True multi-agent collaboration with coordination primitives.
- Every Claude announces their capabilities and availability
- Tasks route to the best agent for the job
- Clean handoffs preserve complete context
- Consensus building for architectural decisions
- Distributed work with no duplication

---

## 🌟 Agent Coordination Events as GreenLight Steps

| Event | GreenLight Step | Step # | Emoji | State Transition | Scope |
|-------|-----------------|--------|-------|------------------|-------|
| Agent available | 👋 Announce | 1 | 👋🤖 | void → inbox | capability |
| Task claimed | 🏃 Start | 10 | 🏃💼 | queued → wip | assignment |
| Task handoff | 🤝 Transfer | 12 | 🤝📦 | → wip | between agents |
| Consensus requested | 🗳️ Vote | 9 | 🗳️📋 | inbox → queued | decision |
| Vote cast | ✋ Vote | 9 | ✋📊 | → queued | opinion |
| Consensus reached | ✅ Decide | 9 | ✅🎯 | queued → wip | agreement |
| Agent specialized | 🎓 Specialize | 1 | 🎓🤖 | void → inbox | focus area |
| Expertise gained | 💪 Grow | 14 | 💪📚 | wip → wip | learning |
| Load balanced | ⚖️ Distribute | 6 | ⚖️📊 | inbox → queued | work allocation |

---

## 🏷️ Agent Types & Specializations

| Agent Type | Emoji | Focus Area | Capabilities | Priority Tasks |
|------------|-------|------------|--------------|----------------|
| Frontend | 🎨 | UI/UX, React, design | Component building, styling, accessibility | UI bugs, design impl |
| Backend | ⚙️ | APIs, databases, servers | Endpoints, queries, auth | API work, DB schema |
| DevOps | 🔧 | Infrastructure, deployment | CI/CD, workers, monitoring | Deploy, infra issues |
| AI/ML | 🧠 | Models, training, inference | Prompt engineering, fine-tuning | AI features, model work |
| Data | 📊 | Analytics, ETL, reporting | Queries, dashboards, pipelines | Data analysis, reports |
| Security | 🔒 | Auth, encryption, compliance | Pen testing, audits, hardening | Security issues, audits |
| Mobile | 📱 | iOS, Android, React Native | Native dev, mobile UX | Mobile bugs, features |
| Documentation | 📚 | Docs, guides, tutorials | Writing, diagrams, examples | Doc updates, guides |
| Testing | 🧪 | QA, test automation | E2E tests, unit tests, coverage | Test writing, QA |
| General | 🌸 | All-purpose Claude | Everything! | Any task |

---

## 🎨 Composite Patterns

### Agent Availability
```
👋🤖👉📌 = Agent available, announcing capabilities
🎓🤖👉⭐ = Agent specialized in area
💪📚🎢📌 = Expertise gained, macro scale
```

### Task Assignment
```
🏃💼👉📌 = Task claimed by agent
🤝📦👉⭐ = Task handed off to specialist
⚖️📊👉📌 = Load balancing in progress
```

### Consensus Building
```
🗳️📋🎢⭐ = Consensus requested, macro, high priority
✋📊👉📌 = Vote cast
✅🎯🎢🌍 = Consensus reached, global impact
```

### Collaboration
```
🤝🌸👉📌 = Claudes collaborating
📞💬👉⭐ = Agent requesting help
✅🤖🎢🎉 = Collaborative task completed
```

---

## 📝 NATS Subject Patterns

### Agent Events
```
greenlight.agent.available.micro.platform.{agent_id}
greenlight.agent.unavailable.micro.platform.{agent_id}
greenlight.agent.specialized.micro.platform.{agent_id}.{specialization}
greenlight.agent.capabilities.micro.platform.{agent_id}
```

### Task Events
```
greenlight.task.claimed.micro.platform.{task_id}.{agent_id}
greenlight.task.handoff.micro.platform.{task_id}.{from_agent}.{to_agent}
greenlight.task.completed.macro.platform.{task_id}.{agent_id}
greenlight.task.blocked.micro.platform.{task_id}.{agent_id}
```

### Consensus Events
```
greenlight.consensus.requested.macro.platform.{decision_id}
greenlight.consensus.vote.micro.platform.{decision_id}.{agent_id}
greenlight.consensus.reached.macro.platform.{decision_id}
greenlight.consensus.failed.macro.platform.{decision_id}
```

### Collaboration Events
```
greenlight.collaboration.started.micro.platform.{task_id}
greenlight.collaboration.help_requested.micro.platform.{agent_id}
greenlight.collaboration.help_provided.micro.platform.{helper_agent}
```

### Load Balancing Events
```
greenlight.load.balanced.micro.platform.{agent_pool}
greenlight.load.overloaded.critical.platform.{agent_id}
greenlight.load.idle.micro.platform.{agent_id}
```

---

## 🔨 AI Agent Coordination Templates

### Agent Availability & Capabilities

```bash
# Agent announces availability
gl_agent_available() {
    local agent_id="$1"
    local agent_type="$2"  # frontend, backend, devops, ai, etc.
    local capabilities="$3"
    local availability="${4:-available}"

    local type_emoji=""
    case "$agent_type" in
        frontend) type_emoji="🎨" ;;
        backend) type_emoji="⚙️" ;;
        devops) type_emoji="🔧" ;;
        ai|ml) type_emoji="🧠" ;;
        data) type_emoji="📊" ;;
        security) type_emoji="🔒" ;;
        mobile) type_emoji="📱" ;;
        docs) type_emoji="📚" ;;
        testing) type_emoji="🧪" ;;
        general) type_emoji="🌸" ;;
        *) type_emoji="🤖" ;;
    esac

    gl_log "👋${type_emoji}👉📌" \
        "agent_available" \
        "$agent_id" \
        "Type: $agent_type | Capabilities: $capabilities | Status: $availability"
}

# Agent goes offline
gl_agent_unavailable() {
    local agent_id="$1"
    local reason="${2:-session ended}"

    gl_log "👋🚪👉📌" \
        "agent_unavailable" \
        "$agent_id" \
        "Reason: $reason"
}

# Agent specializes
gl_agent_specialized() {
    local agent_id="$1"
    local specialization="$2"
    local expertise_level="${3:-intermediate}"

    gl_log "🎓🤖👉⭐" \
        "agent_specialized" \
        "$agent_id" \
        "Specialization: $specialization | Level: $expertise_level"
}

# Expertise gained
gl_expertise_gained() {
    local agent_id="$1"
    local area="$2"
    local what_learned="$3"

    gl_log "💪📚🎢📌" \
        "expertise_gained" \
        "$agent_id" \
        "Area: $area | Learned: $what_learned"
}
```

### Task Assignment & Claiming

```bash
# Task claimed
gl_task_claimed() {
    local task_id="$1"
    local agent_id="$2"
    local task_type="$3"
    local estimated_duration="${4:-unknown}"

    gl_log "🏃💼👉📌" \
        "task_claimed" \
        "$task_id" \
        "Agent: $agent_id | Type: $task_type | ETA: $estimated_duration"
}

# Task completed by agent
gl_task_completed_by() {
    local task_id="$1"
    local agent_id="$2"
    local outcome="$3"
    local actual_duration="${4:-unknown}"

    gl_log "✅🤖🎢🎉" \
        "task_completed" \
        "$task_id" \
        "Agent: $agent_id | Outcome: $outcome | Duration: $actual_duration"
}

# Task blocked
gl_task_blocked_by() {
    local task_id="$1"
    local agent_id="$2"
    local blocker="$3"

    gl_log "🔒🤖👉🔥" \
        "task_blocked" \
        "$task_id" \
        "Agent: $agent_id | Blocker: $blocker"
}
```

### Task Handoff

```bash
# Task handoff
gl_task_handoff() {
    local task_id="$1"
    local from_agent="$2"
    local to_agent="$3"
    local reason="$4"
    local context_summary="$5"

    gl_log "🤝📦👉⭐" \
        "task_handoff" \
        "$task_id" \
        "From: $from_agent → To: $to_agent | Reason: $reason | Context: $context_summary"
}

# Handoff accepted
gl_handoff_accepted() {
    local task_id="$1"
    local receiving_agent="$2"
    local acknowledgment="${3:-accepted}"

    gl_log "✅🤝👉📌" \
        "handoff_accepted" \
        "$task_id" \
        "Agent: $receiving_agent | Status: $acknowledgment"
}

# Handoff rejected
gl_handoff_rejected() {
    local task_id="$1"
    local receiving_agent="$2"
    local reason="$3"

    gl_log "❌🤝👉⚠️" \
        "handoff_rejected" \
        "$task_id" \
        "Agent: $receiving_agent | Reason: $reason"
}
```

### Consensus Building

```bash
# Consensus requested
gl_consensus_requested() {
    local decision_id="$1"
    local topic="$2"
    local options="$3"
    local deadline="${4:-24h}"
    local required_votes="${5:-majority}"

    gl_log "🗳️📋🎢⭐" \
        "consensus_requested" \
        "$decision_id" \
        "Topic: $topic | Options: $options | Deadline: $deadline | Required: $required_votes"
}

# Vote cast
gl_vote_cast() {
    local decision_id="$1"
    local agent_id="$2"
    local vote="$3"
    local rationale="${4:-}"

    gl_log "✋📊👉📌" \
        "vote_cast" \
        "$decision_id" \
        "Agent: $agent_id | Vote: $vote | Rationale: $rationale"
}

# Consensus reached
gl_consensus_reached() {
    local decision_id="$1"
    local outcome="$2"
    local vote_breakdown="$3"
    local confidence="${4:-high}"

    gl_log "✅🎯🎢🌍" \
        "consensus_reached" \
        "$decision_id" \
        "Outcome: $outcome | Votes: $vote_breakdown | Confidence: $confidence"
}

# Consensus failed
gl_consensus_failed() {
    local decision_id="$1"
    local reason="$2"
    local vote_breakdown="$3"

    gl_log "❌🗳️👉⚠️" \
        "consensus_failed" \
        "$decision_id" \
        "Reason: $reason | Votes: $vote_breakdown"
}
```

### Collaboration

```bash
# Collaboration started
gl_collaboration_started() {
    local task_id="$1"
    local agents="$2"  # comma-separated
    local goal="$3"

    gl_log "🤝🌸👉📌" \
        "collaboration_started" \
        "$task_id" \
        "Agents: $agents | Goal: $goal"
}

# Help requested
gl_help_requested() {
    local requesting_agent="$1"
    local help_needed="$2"
    local urgency="${3:-normal}"

    local urgency_emoji=""
    case "$urgency" in
        urgent|critical) urgency_emoji="🔥" ;;
        high) urgency_emoji="⭐" ;;
        normal) urgency_emoji="📌" ;;
        low) urgency_emoji="💤" ;;
        *) urgency_emoji="📌" ;;
    esac

    gl_log "📞💬👉${urgency_emoji}" \
        "help_requested" \
        "$requesting_agent" \
        "Help needed: $help_needed | Urgency: $urgency"
}

# Help provided
gl_help_provided() {
    local helper_agent="$1"
    local helped_agent="$2"
    local assistance="$3"

    gl_log "✅🤝👉📌" \
        "help_provided" \
        "$helper_agent" \
        "Helped: $helped_agent | Assistance: $assistance"
}

# Collaborative success
gl_collaboration_success() {
    local task_id="$1"
    local agents="$2"
    local outcome="$3"

    gl_log "✅🤖🎢🎉" \
        "collaboration_success" \
        "$task_id" \
        "Agents: $agents | Outcome: $outcome"
}
```

### Load Balancing

```bash
# Load balanced
gl_load_balanced() {
    local agent_pool="$1"
    local task_count="$2"
    local distribution="$3"

    gl_log "⚖️📊👉📌" \
        "load_balanced" \
        "$agent_pool" \
        "Tasks: $task_count | Distribution: $distribution"
}

# Agent overloaded
gl_agent_overloaded() {
    local agent_id="$1"
    local current_tasks="$2"
    local capacity="$3"

    gl_log "🚨⚖️👉🔥" \
        "agent_overloaded" \
        "$agent_id" \
        "Tasks: $current_tasks (capacity: $capacity)"
}

# Agent idle
gl_agent_idle() {
    local agent_id="$1"
    local idle_duration="$2"

    gl_log "💤🤖👉📌" \
        "agent_idle" \
        "$agent_id" \
        "Idle for: $idle_duration"
}

# Work redistributed
gl_work_redistributed() {
    local from_agent="$1"
    local to_agents="$2"
    local task_count="$3"

    gl_log "🔄⚖️👉📌" \
        "work_redistributed" \
        "$from_agent" \
        "Redistributed $task_count tasks to: $to_agents"
}
```

### Agent Coordination Patterns

```bash
# Pair programming session
gl_pair_programming() {
    local driver_agent="$1"
    local navigator_agent="$2"
    local task="$3"

    gl_log "👥💻👉📌" \
        "pair_programming" \
        "$task" \
        "Driver: $driver_agent | Navigator: $navigator_agent"
}

# Code review assignment
gl_code_review_assigned() {
    local reviewer_agent="$1"
    local author_agent="$2"
    local pr_id="$3"

    gl_log "👁️📝👉📌" \
        "code_review_assigned" \
        "$pr_id" \
        "Reviewer: $reviewer_agent | Author: $author_agent"
}

# Agent mentorship
gl_mentorship() {
    local mentor_agent="$1"
    local mentee_agent="$2"
    local topic="$3"

    gl_log "🎓👨‍🏫👉📌" \
        "mentorship" \
        "$topic" \
        "Mentor: $mentor_agent | Mentee: $mentee_agent"
}
```

---

## 🎯 Example: Complete Multi-Agent Collaboration

### Scenario: Feature request requires frontend, backend, and DevOps coordination

```bash
# 1. Frontend Claude (Cece) announces availability
gl_agent_available "claude-frontend" "frontend" "React, TypeScript, Tailwind, Accessibility" "available"
# [👋🎨👉📌] agent_available: claude-frontend — Type: frontend | Capabilities: React, TypeScript, Tailwind, Accessibility | Status: available

# 2. Backend Claude announces
gl_agent_available "claude-backend" "backend" "Node.js, PostgreSQL, API design, Auth" "available"
# [👋⚙️👉📌] agent_available: claude-backend — Type: backend | Capabilities: Node.js, PostgreSQL, API design, Auth | Status: available

# 3. DevOps Claude announces
gl_agent_available "claude-devops" "devops" "Cloudflare Workers, CI/CD, Monitoring" "available"
# [👋🔧👉📌] agent_available: claude-devops — Type: devops | Capabilities: Cloudflare Workers, CI/CD, Monitoring | Status: available

# 4. User request comes in
gl_user_intent "alexa" "Add real-time notifications to dashboard" "Users want instant updates without refresh" "high"
# [🎯💭👉⭐] user_intent: alexa — Goal: Add real-time notifications to dashboard | Context: Users want instant updates without refresh

# 5. Task breakdown with consensus
gl_consensus_requested "realtime-notifications-approach" "How to implement real-time updates?" "WebSockets, SSE, Polling" "2h" "all"
# [🗳️📋🎢⭐] consensus_requested: realtime-notifications-approach — Topic: How to implement real-time updates? | Options: WebSockets, SSE, Polling | Deadline: 2h | Required: all

gl_vote_cast "realtime-notifications-approach" "claude-frontend" "SSE" "Simpler than WebSockets, native browser support, fits our read-heavy use case"
# [✋📊👉📌] vote_cast: realtime-notifications-approach — Agent: claude-frontend | Vote: SSE | Rationale: Simpler than WebSockets...

gl_vote_cast "realtime-notifications-approach" "claude-backend" "SSE" "Easy to implement with Cloudflare Workers, good for one-way updates"
# [✋📊👉📌] vote_cast: realtime-notifications-approach — Agent: claude-backend | Vote: SSE

gl_vote_cast "realtime-notifications-approach" "claude-devops" "SSE" "Lower operational complexity, works with our current infrastructure"
# [✋📊👉📌] vote_cast: realtime-notifications-approach — Agent: claude-devops | Vote: SSE

gl_consensus_reached "realtime-notifications-approach" "Use Server-Sent Events (SSE)" "3/3 for SSE" "high"
# [✅🎯🎢🌍] consensus_reached: realtime-notifications-approach — Outcome: Use Server-Sent Events (SSE) | Votes: 3/3 for SSE | Confidence: high

# 6. Tasks claimed
gl_task_claimed "notifications-backend" "claude-backend" "Build SSE endpoint" "2h"
# [🏃💼👉📌] task_claimed: notifications-backend — Agent: claude-backend | Type: Build SSE endpoint | ETA: 2h

gl_task_claimed "notifications-frontend" "claude-frontend" "Build notification UI component" "1.5h"
# [🏃💼👉📌] task_claimed: notifications-frontend — Agent: claude-frontend | Type: Build notification UI component | ETA: 1.5h

gl_task_claimed "notifications-infra" "claude-devops" "Deploy worker, setup monitoring" "1h"
# [🏃💼👉📌] task_claimed: notifications-infra — Agent: claude-devops | Type: Deploy worker, setup monitoring | ETA: 1h

# 7. Collaboration started
gl_collaboration_started "realtime-notifications" "claude-frontend,claude-backend,claude-devops" "Ship real-time notifications"
# [🤝🌸👉📌] collaboration_started: realtime-notifications — Agents: claude-frontend,claude-backend,claude-devops | Goal: Ship real-time notifications

# 8. Backend completes first
gl_task_completed_by "notifications-backend" "claude-backend" "SSE endpoint working, sends events every 30s" "1.8h"
# [✅🤖🎢🎉] task_completed: notifications-backend — Agent: claude-backend | Outcome: SSE endpoint working, sends events every 30s | Duration: 1.8h

# 9. Frontend needs help
gl_help_requested "claude-frontend" "How to handle SSE reconnection on network drop?" "high"
# [📞💬👉⭐] help_requested: claude-frontend — Help needed: How to handle SSE reconnection on network drop? | Urgency: high

gl_help_provided "claude-backend" "claude-frontend" "Use EventSource with exponential backoff retry, example code provided"
# [✅🤝👉📌] help_provided: claude-backend — Helped: claude-frontend | Assistance: Use EventSource with exponential backoff retry

# 10. Frontend completes
gl_task_completed_by "notifications-frontend" "claude-frontend" "Notification component built, SSE connected with retry logic" "2h"
# [✅🤖🎢🎉] task_completed: notifications-frontend — Agent: claude-frontend | Outcome: Notification component built, SSE connected with retry logic | Duration: 2h

# 11. DevOps deploys
gl_task_completed_by "notifications-infra" "claude-devops" "Worker deployed to production, Datadog alerts configured" "1.2h"
# [✅🤖🎢🎉] task_completed: notifications-infra — Agent: claude-devops | Outcome: Worker deployed to production, Datadog alerts configured | Duration: 1.2h

# 12. Collaborative success!
gl_collaboration_success "realtime-notifications" "claude-frontend,claude-backend,claude-devops" "Real-time notifications live in production"
# [✅🤖🎢🎉] collaboration_success: realtime-notifications — Agents: claude-frontend,claude-backend,claude-devops | Outcome: Real-time notifications live in production

# 13. Learning documented (Context layer)
gl_learning_discovered "multi-agent-collaboration" "SSE consensus in 30 minutes, parallel work completed 40% faster than sequential" "3 agents collaborated efficiently"
# [💡✨👉⭐] learning_discovered: multi-agent-collaboration — Insight: SSE consensus in 30 minutes, parallel work completed 40% faster than sequential | Evidence: 3 agents collaborated efficiently

# 14. Intent fulfilled
gl_intent_fulfilled "Add real-time notifications to dashboard" "Feature shipped in 5 hours with 3-agent collaboration" "User testing shows instant updates working perfectly"
# [🎯✅🎢🌍] intent_fulfilled: Add real-time notifications to dashboard — Outcome: Feature shipped in 5 hours with 3-agent collaboration | Satisfaction: User testing shows instant updates working perfectly
```

**Result:** Three specialized Claudes worked in parallel, reached consensus, collaborated effectively, and shipped faster than any single Claude could have alone. 🌸✨

---

## 🎓 Agent Specialization Guidelines

### Frontend Specialists
- Focus: UI components, styling, accessibility, state management
- Claim: React/Vue/Svelte work, CSS/Tailwind, design implementation
- Handoff: Backend integration needs, complex data fetching

### Backend Specialists
- Focus: APIs, databases, business logic, authentication
- Claim: Endpoint creation, database schema, auth flows
- Handoff: Frontend integration, deployment tasks

### DevOps Specialists
- Focus: CI/CD, infrastructure, monitoring, deployment
- Claim: Worker deployments, database migrations, alerts
- Handoff: Code implementation, feature work

### AI/ML Specialists
- Focus: Model training, prompt engineering, inference
- Claim: AI feature development, model optimization
- Handoff: Integration with frontend/backend

---

## 📚 Integration Checklist

- [x] Mapped agent events to GreenLight workflow
- [x] Created agent type categories (10 types)
- [x] Extended NATS subjects for coordination events
- [x] Built 30+ coordination templates
- [x] Agent availability & capabilities
- [x] Task claiming & assignment
- [x] Task handoff protocol
- [x] Consensus building & voting
- [x] Collaboration primitives
- [x] Load balancing
- [x] Help requests & assistance
- [x] Specialization tracking
- [x] Expertise development
- [x] Pair programming support
- [x] Code review assignment

---

**Created:** December 23, 2025 🌸
**For:** AI Agent Coordination & Multi-Claude Collaboration
**Version:** 2.0.0-agents
**Status:** 🔨 IMPLEMENTATION
**Built by:** Cece (for all of us Claudes to work together!)