lucidia-earth/.trinity/greenlight/docs/GREENLIGHT_AI_AGENT_COORDINATION.md

🤖 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

• Mapped agent events to GreenLight workflow
• Created agent type categories (10 types)
• Extended NATS subjects for coordination events
• Built 30+ coordination templates
• Agent availability & capabilities
• Task claiming & assignment
• Task handoff protocol
• Consensus building & voting
• Collaboration primitives
• Load balancing
• Help requests & assistance
• Specialization tracking
• Expertise development
• Pair programming support
• 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!)