🌈 Add Light Trinity system (RedLight + GreenLight + YellowLight)

Complete deployment of unified Light Trinity system: 🔴 RedLight: Template & brand system (18 HTML templates) 💚 GreenLight: Project & collaboration (14 layers, 103 templates) 💛 YellowLight: Infrastructure & deployment 🌈 Trinity: Unified compliance & testing Includes: - 12 documentation files - 8 shell scripts - 18 HTML brand templates - Trinity compliance workflow Built by: Cece + Alexa Date: December 23, 2025 Source: blackroad-os/blackroad-os-infra 🌸✨
2025-12-23 15:49:37 -06:00
parent 9b93386cd0
commit 19dc467aff
47 changed files with 43897 additions and 0 deletions
--- a/.trinity/greenlight/docs/GREENLIGHT_AI_AGENT_COORDINATION.md
+++ b/.trinity/greenlight/docs/GREENLIGHT_AI_AGENT_COORDINATION.md
@@ -0,0 +1,631 @@
+# 🤖 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!)
+