🌈 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 🌸✨
This commit is contained in:
Alexa Louise
631
.trinity/greenlight/docs/GREENLIGHT_AI_AGENT_COORDINATION.md
Normal file
631
.trinity/greenlight/docs/GREENLIGHT_AI_AGENT_COORDINATION.md
Normal file
@@ -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!)
|
||||
|
||||
512
.trinity/greenlight/docs/GREENLIGHT_AI_EXTENSION.md
Normal file
512
.trinity/greenlight/docs/GREENLIGHT_AI_EXTENSION.md
Normal file
@@ -0,0 +1,512 @@
|
||||
# 🤗 GreenLight AI & ML Extension
|
||||
|
||||
**Extension to GreenLight for HuggingFace & AI Infrastructure**
|
||||
|
||||
---
|
||||
|
||||
## 🤖 AI Model Lifecycle States
|
||||
|
||||
Add these to the **Lifecycle States** category:
|
||||
|
||||
| Emoji | State | Code | Trinary | Description |
|
||||
|-------|-------|------|---------|-------------|
|
||||
| 🤗 | MODEL_LOADING | `model_loading` | 0 | Loading model into memory |
|
||||
| 🧠 | MODEL_READY | `model_ready` | +1 | Model loaded and ready |
|
||||
| ⚡ | INFERENCE_RUNNING | `inference_running` | +1 | Generating output |
|
||||
| 🔄 | TOKEN_STREAMING | `token_streaming` | +1 | Streaming tokens |
|
||||
| 💾 | MODEL_CACHED | `model_cached` | +1 | Model in cache |
|
||||
| 📥 | MODEL_DOWNLOADING | `model_downloading` | 0 | Downloading weights |
|
||||
| 🏋️ | MODEL_TRAINING | `model_training` | +1 | Model training |
|
||||
| 📊 | MODEL_EVAL | `model_eval` | 0 | Evaluating performance |
|
||||
| 🔧 | MODEL_FINE_TUNING | `model_fine_tuning` | +1 | Fine-tuning model |
|
||||
| ⏱️ | INFERENCE_TIMEOUT | `inference_timeout` | -1 | Request timed out |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 AI Task Categories
|
||||
|
||||
Add to **Domain Tags**:
|
||||
|
||||
| Emoji | Category | Code | Description |
|
||||
|-------|----------|------|-------------|
|
||||
| 💬 | TEXT_GEN | `text_gen` | Text generation / completion |
|
||||
| 🗣️ | CHAT | `chat` | Chat completions |
|
||||
| 🎨 | IMAGE_GEN | `image_gen` | Image generation |
|
||||
| 🖼️ | IMAGE_EDIT | `image_edit` | Image editing / inpainting |
|
||||
| 🔤 | EMBEDDINGS | `embeddings` | Vector embeddings |
|
||||
| 🔍 | OCR | `ocr` | Optical character recognition |
|
||||
| 🎙️ | TTS | `tts` | Text to speech |
|
||||
| 👂 | STT | `stt` | Speech to text |
|
||||
| 🎥 | VIDEO_GEN | `video_gen` | Video generation |
|
||||
| 🔬 | CLASSIFICATION | `classification` | Classification tasks |
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ AI Infrastructure Components
|
||||
|
||||
| Emoji | Component | Code | Description |
|
||||
|-------|-----------|------|-------------|
|
||||
| 🤗 | HUGGINGFACE | `huggingface` | HuggingFace platform |
|
||||
| ⚡ | VLLM | `vllm` | vLLM inference server |
|
||||
| 🦙 | LLAMA_CPP | `llama_cpp` | llama.cpp engine |
|
||||
| 🔥 | TRANSFORMERS | `transformers` | Transformers library |
|
||||
| 🌐 | INFERENCE_ENDPOINT | `inference_endpoint` | HF Inference Endpoint |
|
||||
| 📦 | MODEL_HUB | `model_hub` | Model repository |
|
||||
| 🚀 | SPACE | `space` | HuggingFace Space |
|
||||
| 💾 | MODEL_CACHE | `model_cache` | Model caching layer |
|
||||
| 🖥️ | GPU_INSTANCE | `gpu_instance` | GPU compute instance |
|
||||
|
||||
---
|
||||
|
||||
## 🎛️ GPU Instance Types
|
||||
|
||||
| Emoji | Instance | Code | VRAM | Description |
|
||||
|-------|----------|------|------|-------------|
|
||||
| 🟢 | T4 | `t4` | 16GB | Small models / testing |
|
||||
| 🔵 | L4 | `l4` | 24GB | 7B-13B models |
|
||||
| 🟡 | A10G | `a10g` | 24GB | Production inference |
|
||||
| 🟠 | A100 | `a100` | 80GB | Large models (70B+) |
|
||||
| 🔴 | H100 | `h100` | 80GB | Maximum performance |
|
||||
| 🟣 | JETSON | `jetson` | 8GB | Edge inference |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for AI
|
||||
|
||||
### Model Operations
|
||||
```
|
||||
🤗📥👉📌 = Downloading model, micro scale
|
||||
🧠✅🎢⭐ = Model loaded, macro impact, high priority
|
||||
⚡🔄💬🌀 = Streaming chat tokens, AI domain
|
||||
🎨✅👉📌 = Image generated, micro scale
|
||||
```
|
||||
|
||||
### Inference Flows
|
||||
```
|
||||
⚡💬🧠✅ = Chat inference running, model ready
|
||||
⚡🎨🖼️✅ = Image generation complete
|
||||
🔤💾🎢✅ = Embeddings cached, macro scale
|
||||
🔍📄👉✅ = OCR completed, micro scale
|
||||
```
|
||||
|
||||
### Infrastructure
|
||||
```
|
||||
🚀🤗🌐✅ = HF Space deployed
|
||||
🌐⚡🟡📌 = Inference endpoint on A10G
|
||||
💾🧠🎢⭐ = Model cached, high priority
|
||||
⏱️❌🧠🔥 = Inference timeout, fire priority
|
||||
```
|
||||
|
||||
### Combined AI Flow
|
||||
```
|
||||
[⚡📥] [🤗🧠] [⚡💬] [🔄📊] [✅🎉] = Request → Load → Inference → Stream → Complete
|
||||
[🎨⚡] [🖼️✅] = Image generation → success
|
||||
[🔤💾] [✅🎢] = Embeddings → cached
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (AI)
|
||||
|
||||
### Inference Events
|
||||
```
|
||||
greenlight.inference.started.micro.ai.{model_name}
|
||||
greenlight.inference.completed.micro.ai.{model_name}
|
||||
greenlight.inference.failed.micro.ai.{model_name}
|
||||
greenlight.inference.timeout.micro.ai.{model_name}
|
||||
```
|
||||
|
||||
### Model Events
|
||||
```
|
||||
greenlight.model.loaded.macro.ai.{model_name}
|
||||
greenlight.model.cached.micro.ai.{model_name}
|
||||
greenlight.model.downloading.micro.ai.{model_name}
|
||||
greenlight.model.uploaded.macro.ai.{model_name}
|
||||
```
|
||||
|
||||
### Endpoint Events
|
||||
```
|
||||
greenlight.endpoint.created.macro.ai.{endpoint_name}
|
||||
greenlight.endpoint.paused.micro.ai.{endpoint_name}
|
||||
greenlight.endpoint.resumed.micro.ai.{endpoint_name}
|
||||
greenlight.endpoint.scaled.macro.ai.{endpoint_name}
|
||||
```
|
||||
|
||||
### Task-Specific Events
|
||||
```
|
||||
greenlight.chat.completed.micro.ai.{model}
|
||||
greenlight.image.generated.micro.ai.{model}
|
||||
greenlight.embeddings.cached.micro.ai.{model}
|
||||
greenlight.ocr.completed.micro.ai.{file}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 AI Memory Templates
|
||||
|
||||
### Model Operations
|
||||
|
||||
```bash
|
||||
# Model loading
|
||||
gl_model_loading() {
|
||||
local model_name="$1"
|
||||
local size="${2:-unknown}"
|
||||
|
||||
gl_log "🤗📥👉📌" "model_loading" "$model_name" \
|
||||
"Loading model: $size"
|
||||
}
|
||||
|
||||
# Model ready
|
||||
gl_model_ready() {
|
||||
local model_name="$1"
|
||||
local vram="${2:-unknown}"
|
||||
|
||||
gl_log "🧠✅🎢⭐" "model_ready" "$model_name" \
|
||||
"Model loaded, VRAM: $vram"
|
||||
}
|
||||
|
||||
# Model cached
|
||||
gl_model_cached() {
|
||||
local model_name="$1"
|
||||
local cache_key="$2"
|
||||
|
||||
gl_log "💾🧠👉📌" "model_cached" "$model_name" \
|
||||
"Model cached: $cache_key"
|
||||
}
|
||||
|
||||
# Model downloading
|
||||
gl_model_downloading() {
|
||||
local model_name="$1"
|
||||
local size="${2:-unknown}"
|
||||
|
||||
gl_log "📥🤗👉📌" "model_downloading" "$model_name" \
|
||||
"Downloading: $size"
|
||||
}
|
||||
|
||||
# Model uploaded
|
||||
gl_model_uploaded() {
|
||||
local model_name="$1"
|
||||
local repo_id="$2"
|
||||
|
||||
gl_log "📤🤗🎢✅" "model_uploaded" "$model_name" \
|
||||
"Uploaded to: $repo_id"
|
||||
}
|
||||
```
|
||||
|
||||
### Inference Operations
|
||||
|
||||
```bash
|
||||
# Inference started
|
||||
gl_inference_start() {
|
||||
local task_type="$1" # chat, text_gen, image_gen, etc.
|
||||
local model="$2"
|
||||
local request_id="${3:-$(uuidgen)}"
|
||||
|
||||
local task_emoji=""
|
||||
case "$task_type" in
|
||||
chat) task_emoji="💬" ;;
|
||||
text_gen) task_emoji="💬" ;;
|
||||
image_gen) task_emoji="🎨" ;;
|
||||
embeddings) task_emoji="🔤" ;;
|
||||
ocr) task_emoji="🔍" ;;
|
||||
tts) task_emoji="🎙️" ;;
|
||||
video_gen) task_emoji="🎥" ;;
|
||||
*) task_emoji="🤖" ;;
|
||||
esac
|
||||
|
||||
gl_log "⚡${task_emoji}👉📌" "inference_start" "$model" \
|
||||
"$task_type inference started: $request_id"
|
||||
}
|
||||
|
||||
# Inference complete
|
||||
gl_inference_complete() {
|
||||
local task_type="$1"
|
||||
local model="$2"
|
||||
local duration="${3:-unknown}"
|
||||
|
||||
local task_emoji=""
|
||||
case "$task_type" in
|
||||
chat) task_emoji="💬" ;;
|
||||
text_gen) task_emoji="💬" ;;
|
||||
image_gen) task_emoji="🎨" ;;
|
||||
embeddings) task_emoji="🔤" ;;
|
||||
ocr) task_emoji="🔍" ;;
|
||||
*) task_emoji="🤖" ;;
|
||||
esac
|
||||
|
||||
gl_log "✅${task_emoji}🎢🎉" "inference_complete" "$model" \
|
||||
"$task_type complete in $duration"
|
||||
}
|
||||
|
||||
# Inference failed
|
||||
gl_inference_failed() {
|
||||
local task_type="$1"
|
||||
local model="$2"
|
||||
local error="${3:-unknown error}"
|
||||
|
||||
gl_log "❌⚡🤖🔥" "inference_failed" "$model" \
|
||||
"$task_type failed: $error"
|
||||
}
|
||||
|
||||
# Token streaming
|
||||
gl_token_streaming() {
|
||||
local model="$1"
|
||||
local tokens_generated="$2"
|
||||
|
||||
gl_log "🔄💬⚡👉" "token_streaming" "$model" \
|
||||
"Streaming: $tokens_generated tokens"
|
||||
}
|
||||
|
||||
# Inference timeout
|
||||
gl_inference_timeout() {
|
||||
local model="$1"
|
||||
local timeout_seconds="$2"
|
||||
|
||||
gl_log "⏱️❌🤖🔥" "inference_timeout" "$model" \
|
||||
"Timed out after ${timeout_seconds}s"
|
||||
}
|
||||
```
|
||||
|
||||
### Endpoint Management
|
||||
|
||||
```bash
|
||||
# Endpoint created
|
||||
gl_endpoint_created() {
|
||||
local endpoint_name="$1"
|
||||
local model="$2"
|
||||
local instance_type="${3:-unknown}"
|
||||
|
||||
local instance_emoji=""
|
||||
case "$instance_type" in
|
||||
*t4*) instance_emoji="🟢" ;;
|
||||
*l4*) instance_emoji="🔵" ;;
|
||||
*a10g*) instance_emoji="🟡" ;;
|
||||
*a100*) instance_emoji="🟠" ;;
|
||||
*h100*) instance_emoji="🔴" ;;
|
||||
*) instance_emoji="🖥️" ;;
|
||||
esac
|
||||
|
||||
gl_log "🚀🌐${instance_emoji}✅" "endpoint_created" "$endpoint_name" \
|
||||
"Endpoint created: $model on $instance_type"
|
||||
}
|
||||
|
||||
# Endpoint paused
|
||||
gl_endpoint_paused() {
|
||||
local endpoint_name="$1"
|
||||
|
||||
gl_log "⏸️🌐👉📌" "endpoint_paused" "$endpoint_name" \
|
||||
"Endpoint paused (cost savings)"
|
||||
}
|
||||
|
||||
# Endpoint resumed
|
||||
gl_endpoint_resumed() {
|
||||
local endpoint_name="$1"
|
||||
|
||||
gl_log "▶️🌐👉📌" "endpoint_resumed" "$endpoint_name" \
|
||||
"Endpoint resumed"
|
||||
}
|
||||
|
||||
# Endpoint scaled
|
||||
gl_endpoint_scaled() {
|
||||
local endpoint_name="$1"
|
||||
local replicas="$2"
|
||||
|
||||
gl_log "📈🌐🎢⭐" "endpoint_scaled" "$endpoint_name" \
|
||||
"Scaled to $replicas replicas"
|
||||
}
|
||||
|
||||
# Endpoint deleted
|
||||
gl_endpoint_deleted() {
|
||||
local endpoint_name="$1"
|
||||
|
||||
gl_log "🗑️🌐👉📌" "endpoint_deleted" "$endpoint_name" \
|
||||
"Endpoint deleted"
|
||||
}
|
||||
```
|
||||
|
||||
### Space Operations
|
||||
|
||||
```bash
|
||||
# Space deployed
|
||||
gl_space_deployed() {
|
||||
local space_name="$1"
|
||||
local url="$2"
|
||||
|
||||
gl_log "🚀🤗🌐✅" "space_deployed" "$space_name" \
|
||||
"Space deployed: $url"
|
||||
}
|
||||
|
||||
# Space invoked
|
||||
gl_space_invoked() {
|
||||
local space_id="$1"
|
||||
local task_type="$2"
|
||||
|
||||
gl_log "⚡🤗👉📌" "space_invoked" "$space_id" \
|
||||
"Space invoked for: $task_type"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Complete Inference Flow
|
||||
|
||||
### Scenario: Chat inference with DeepSeek
|
||||
|
||||
```bash
|
||||
# 1. Load model
|
||||
gl_model_loading "deepseek-ai/DeepSeek-V3.2" "7B"
|
||||
# [🤗📥👉📌] model_loading: deepseek-ai/DeepSeek-V3.2 — Loading model: 7B
|
||||
|
||||
# 2. Model ready
|
||||
gl_model_ready "deepseek-ai/DeepSeek-V3.2" "16GB"
|
||||
# [🧠✅🎢⭐] model_ready: deepseek-ai/DeepSeek-V3.2 — Model loaded, VRAM: 16GB
|
||||
|
||||
# 3. Start inference
|
||||
gl_inference_start "chat" "deepseek-ai/DeepSeek-V3.2" "req_abc123"
|
||||
# [⚡💬👉📌] inference_start: deepseek-ai/DeepSeek-V3.2 — chat inference started: req_abc123
|
||||
|
||||
# 4. Token streaming
|
||||
gl_token_streaming "deepseek-ai/DeepSeek-V3.2" "247"
|
||||
# [🔄💬⚡👉] token_streaming: deepseek-ai/DeepSeek-V3.2 — Streaming: 247 tokens
|
||||
|
||||
# 5. Complete
|
||||
gl_inference_complete "chat" "deepseek-ai/DeepSeek-V3.2" "3.2s"
|
||||
# [✅💬🎢🎉] inference_complete: deepseek-ai/DeepSeek-V3.2 — chat complete in 3.2s
|
||||
```
|
||||
|
||||
### Scenario: Image generation with FLUX
|
||||
|
||||
```bash
|
||||
# 1. Space invoked
|
||||
gl_space_invoked "black-forest-labs/FLUX.1-dev" "image_gen"
|
||||
# [⚡🤗👉📌] space_invoked: black-forest-labs/FLUX.1-dev — Space invoked for: image_gen
|
||||
|
||||
# 2. Start inference
|
||||
gl_inference_start "image_gen" "FLUX.1-dev" "img_xyz789"
|
||||
# [⚡🎨👉📌] inference_start: FLUX.1-dev — image_gen inference started: img_xyz789
|
||||
|
||||
# 3. Complete
|
||||
gl_inference_complete "image_gen" "FLUX.1-dev" "12.4s"
|
||||
# [✅🎨🎢🎉] inference_complete: FLUX.1-dev — image_gen complete in 12.4s
|
||||
```
|
||||
|
||||
### Scenario: Endpoint lifecycle (Lucidia)
|
||||
|
||||
```bash
|
||||
# 1. Create endpoint
|
||||
gl_endpoint_created "lucidia-inference" "blackroadio/Lucidia" "nvidia-a10g"
|
||||
# [🚀🌐🟡✅] endpoint_created: lucidia-inference — Endpoint created: blackroadio/Lucidia on nvidia-a10g
|
||||
|
||||
# 2. Run inference
|
||||
gl_inference_start "chat" "lucidia-inference" "req_lucidia_001"
|
||||
# [⚡💬👉📌] inference_start: lucidia-inference — chat inference started: req_lucidia_001
|
||||
|
||||
# 3. Complete
|
||||
gl_inference_complete "chat" "lucidia-inference" "2.1s"
|
||||
# [✅💬🎢🎉] inference_complete: lucidia-inference — chat complete in 2.1s
|
||||
|
||||
# 4. Pause for cost savings
|
||||
gl_endpoint_paused "lucidia-inference"
|
||||
# [⏸️🌐👉📌] endpoint_paused: lucidia-inference — Endpoint paused (cost savings)
|
||||
|
||||
# 5. Resume when needed
|
||||
gl_endpoint_resumed "lucidia-inference"
|
||||
# [▶️🌐👉📌] endpoint_resumed: lucidia-inference — Endpoint resumed
|
||||
```
|
||||
|
||||
### Scenario: Inference failure and timeout
|
||||
|
||||
```bash
|
||||
# 1. Start inference
|
||||
gl_inference_start "chat" "large-model" "req_fail"
|
||||
# [⚡💬👉📌] inference_start: large-model — chat inference started: req_fail
|
||||
|
||||
# 2. Timeout
|
||||
gl_inference_timeout "large-model" "30"
|
||||
# [⏱️❌🤖🔥] inference_timeout: large-model — Timed out after 30s
|
||||
|
||||
# 3. Failed
|
||||
gl_inference_failed "chat" "large-model" "OOM error"
|
||||
# [❌⚡🤖🔥] inference_failed: large-model — chat failed: OOM error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 AI Analytics Integration
|
||||
|
||||
### Performance Tracking
|
||||
```bash
|
||||
# Inference latency
|
||||
gl_log "📊⚡🎢📌" "latency_metric" "ai-metrics" "p95 latency: 3.2s (chat)"
|
||||
|
||||
# Token throughput
|
||||
gl_log "📊💬👉📌" "throughput_metric" "ai-metrics" "Throughput: 45 tokens/sec"
|
||||
|
||||
# Cache hit rate
|
||||
gl_log "📊💾🎢⭐" "cache_metric" "ai-metrics" "Cache hit rate: 78%"
|
||||
```
|
||||
|
||||
### Cost Tracking
|
||||
```bash
|
||||
# GPU costs
|
||||
gl_log "💰🖥️🎢📌" "gpu_cost" "ai-billing" "A10G usage: $2.47/hour"
|
||||
|
||||
# Inference costs
|
||||
gl_log "💰⚡👉📌" "inference_cost" "ai-billing" "1,247 requests: $12.34"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Extended lifecycle states for AI operations
|
||||
- [x] Added AI task category tags
|
||||
- [x] Created infrastructure component tags
|
||||
- [x] Mapped GPU instance types
|
||||
- [x] Created composite patterns for inference flows
|
||||
- [x] Extended NATS subjects for AI events
|
||||
- [x] Built 15+ AI-specific templates
|
||||
- [x] Integrated with 27-step GreenLight workflow
|
||||
- [x] Added analytics tracking patterns
|
||||
- [x] Added cost tracking patterns
|
||||
|
||||
---
|
||||
|
||||
## 🎯 HuggingFace Account Details
|
||||
|
||||
**Username:** blackroadio
|
||||
**Profile:** https://huggingface.co/blackroadio
|
||||
**Models:** 2 (Lucidia, qwen3-235b-a22b)
|
||||
**API Tokens:** https://huggingface.co/settings/tokens
|
||||
**Endpoints:** https://endpoints.huggingface.co
|
||||
|
||||
### Recommended Models
|
||||
**Text Generation:**
|
||||
- openai/gpt-oss-20b (7.2M downloads)
|
||||
- deepseek-ai/DeepSeek-V3.2 (90.9K downloads)
|
||||
- nvidia/Nemotron-3-Nano-30B-A3B (247.7K downloads)
|
||||
|
||||
**Image Generation:**
|
||||
- black-forest-labs/FLUX.1-dev (809.7K downloads)
|
||||
- stabilityai/stable-diffusion-xl-base-1.0 (2.1M downloads)
|
||||
|
||||
**Embeddings:**
|
||||
- sentence-transformers/all-MiniLM-L6-v2 (149.3M downloads)
|
||||
- BAAI/bge-m3 (8.2M downloads)
|
||||
|
||||
**OCR:**
|
||||
- deepseek-ai/DeepSeek-OCR (4.7M downloads)
|
||||
|
||||
### Available Spaces (15+)
|
||||
- evalstate/flux1_schnell - Fast image generation
|
||||
- mcp-tools/FLUX.1-Krea-dev - High quality images
|
||||
- not-lain/background-removal - Remove backgrounds
|
||||
- ResembleAI/Chatterbox - Text to speech
|
||||
- mcp-tools/DeepSeek-OCR-experimental - OCR
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** HuggingFace AI Infrastructure
|
||||
**Version:** 2.0.0-ai
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
618
.trinity/greenlight/docs/GREENLIGHT_ANALYTICS_OBSERVABILITY.md
Normal file
618
.trinity/greenlight/docs/GREENLIGHT_ANALYTICS_OBSERVABILITY.md
Normal file
@@ -0,0 +1,618 @@
|
||||
# 📊 GreenLight Analytics & Observability
|
||||
|
||||
**Layer 13: Production Visibility & User Behavior**
|
||||
|
||||
---
|
||||
|
||||
## 📊 Why Analytics & Observability Matters
|
||||
|
||||
**The Problem:** We build and deploy, but we're blind to what happens next.
|
||||
- Is the API actually fast or slow?
|
||||
- Are users hitting errors we don't know about?
|
||||
- Which features do users actually use?
|
||||
- Is the system healthy or degrading?
|
||||
|
||||
**The Solution:** Complete production visibility with real-time monitoring.
|
||||
- Know about errors before users report them
|
||||
- Track performance degradation immediately
|
||||
- Understand user behavior and conversion
|
||||
- Prevent incidents before they happen
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Observability Events as GreenLight Steps
|
||||
|
||||
| Event | GreenLight Step | Step # | Emoji | State Transition | Severity |
|
||||
|-------|-----------------|--------|-------|------------------|----------|
|
||||
| Error detected | 🚨 Detect | 16 | 🚨❌ | → blocked | Critical |
|
||||
| Performance alert | ⚡ Alert | 16 | ⚡⚠️ | → blocked | High |
|
||||
| Service degraded | 📉 Degrade | 16 | 📉⚠️ | → blocked | High |
|
||||
| Service recovered | ✅ Recover | 17 | ✅🎉 | blocked → wip | Info |
|
||||
| Metric threshold | 📊 Alert | 16 | 📊⚠️ | → blocked | Medium |
|
||||
| User action tracked | 👤 Track | 13 | 👤📊 | → wip | Info |
|
||||
| Conversion event | 🎯 Convert | 19 | 🎯✅ | wip → done | Info |
|
||||
| Log aggregated | 📝 Aggregate | 13 | 📝📊 | → wip | Info |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Monitoring Categories
|
||||
|
||||
| Category | Emoji | Tools | Purpose | Alert Threshold |
|
||||
|----------|-------|-------|---------|-----------------|
|
||||
| Error Tracking | 🚨 | Sentry, Rollbar | Exceptions, crashes | Any error |
|
||||
| APM | ⚡ | Datadog, New Relic | Performance, latency | P95 > 500ms |
|
||||
| User Analytics | 👤 | Amplitude, Mixpanel | Behavior, funnels | Conversion < 10% |
|
||||
| Logs | 📝 | Better Stack, Axiom | Debug, audit trail | Error logs |
|
||||
| Uptime | 🌐 | Pingdom, UptimeRobot | Availability | Downtime > 1min |
|
||||
| Real User Monitoring | 📱 | Sentry, DataDog RUM | Client-side perf | LCP > 2.5s |
|
||||
| Synthetic Monitoring | 🤖 | Checkly, Grafana | Proactive checks | Check fails |
|
||||
| Infrastructure | 🖥️ | Datadog, Grafana | CPU, memory, disk | CPU > 80% |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns
|
||||
|
||||
### Error Tracking
|
||||
```
|
||||
🚨❌👉🔥 = Critical error detected, micro, urgent
|
||||
🐛🔍👉⭐ = Error being investigated
|
||||
✅🐛🎢🎉 = Error resolved, macro
|
||||
```
|
||||
|
||||
### Performance Monitoring
|
||||
```
|
||||
⚡⚠️👉🔥 = Performance alert, slow queries
|
||||
📊📈🎢📌 = Metrics trending up (good)
|
||||
📉⚠️👉🔥 = Metrics degrading (bad)
|
||||
```
|
||||
|
||||
### User Analytics
|
||||
```
|
||||
👤📊👉📌 = User action tracked
|
||||
🎯✅🎢🌍 = Conversion event (signup, purchase)
|
||||
🚪👋👉⚠️ = User churn event
|
||||
```
|
||||
|
||||
### Service Health
|
||||
```
|
||||
✅🌐🎢🌍 = All systems operational
|
||||
⚠️📉👉🔥 = Service degraded
|
||||
🚨⛔👉🔥 = Service down, critical
|
||||
✅🔄🎢🎉 = Service recovered
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns
|
||||
|
||||
### Error Events
|
||||
```
|
||||
greenlight.error.detected.critical.platform.{service}
|
||||
greenlight.error.resolved.macro.platform.{error_id}
|
||||
greenlight.error.recurring.critical.platform.{fingerprint}
|
||||
```
|
||||
|
||||
### Performance Events
|
||||
```
|
||||
greenlight.performance.slow_query.critical.platform.{endpoint}
|
||||
greenlight.performance.high_latency.critical.platform.{service}
|
||||
greenlight.performance.memory_leak.critical.platform.{worker}
|
||||
greenlight.performance.improved.macro.platform.{metric}
|
||||
```
|
||||
|
||||
### User Analytics Events
|
||||
```
|
||||
greenlight.user.action.micro.platform.{event_name}
|
||||
greenlight.user.conversion.macro.platform.{funnel}
|
||||
greenlight.user.churn.macro.platform.{reason}
|
||||
greenlight.user.retention.macro.platform.{cohort}
|
||||
```
|
||||
|
||||
### Service Health Events
|
||||
```
|
||||
greenlight.service.up.macro.platform.{service}
|
||||
greenlight.service.down.critical.platform.{service}
|
||||
greenlight.service.degraded.critical.platform.{service}
|
||||
greenlight.service.recovered.macro.platform.{service}
|
||||
```
|
||||
|
||||
### Metrics Events
|
||||
```
|
||||
greenlight.metric.threshold.critical.platform.{metric_name}
|
||||
greenlight.metric.anomaly.critical.platform.{metric_name}
|
||||
greenlight.metric.trend.micro.platform.{metric_name}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Analytics & Observability Templates
|
||||
|
||||
### Error Tracking
|
||||
|
||||
```bash
|
||||
# Error detected
|
||||
gl_error_detected() {
|
||||
local service="$1"
|
||||
local error_type="$2"
|
||||
local message="$3"
|
||||
local stack_trace="${4:-no stack trace}"
|
||||
local severity="${5:-error}"
|
||||
|
||||
local severity_emoji=""
|
||||
case "$severity" in
|
||||
critical|fatal) severity_emoji="🚨" ;;
|
||||
error) severity_emoji="❌" ;;
|
||||
warning) severity_emoji="⚠️" ;;
|
||||
*) severity_emoji="ℹ️" ;;
|
||||
esac
|
||||
|
||||
gl_log "${severity_emoji}❌👉🔥" \
|
||||
"error_detected" \
|
||||
"$service" \
|
||||
"Type: $error_type | Message: $message | Severity: $severity"
|
||||
}
|
||||
|
||||
# Error resolved
|
||||
gl_error_resolved() {
|
||||
local error_id="$1"
|
||||
local solution="$2"
|
||||
local affected_users="${3:-unknown}"
|
||||
|
||||
gl_log "✅🐛🎢🎉" \
|
||||
"error_resolved" \
|
||||
"$error_id" \
|
||||
"Solution: $solution | Affected users: $affected_users"
|
||||
}
|
||||
|
||||
# Recurring error pattern
|
||||
gl_error_recurring() {
|
||||
local fingerprint="$1"
|
||||
local occurrences="$2"
|
||||
local time_window="$3"
|
||||
|
||||
gl_log "🔄🚨👉🔥" \
|
||||
"error_recurring" \
|
||||
"$fingerprint" \
|
||||
"Occurrences: $occurrences in $time_window - needs investigation"
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
```bash
|
||||
# Performance alert
|
||||
gl_performance_alert() {
|
||||
local metric_type="$1" # latency, throughput, query_time, etc.
|
||||
local service="$2"
|
||||
local current_value="$3"
|
||||
local threshold="$4"
|
||||
local severity="${5:-warning}"
|
||||
|
||||
local severity_emoji=""
|
||||
case "$severity" in
|
||||
critical) severity_emoji="🚨" ;;
|
||||
warning) severity_emoji="⚠️" ;;
|
||||
info) severity_emoji="ℹ️" ;;
|
||||
*) severity_emoji="📊" ;;
|
||||
esac
|
||||
|
||||
gl_log "${severity_emoji}⚡👉🔥" \
|
||||
"performance_alert" \
|
||||
"$service" \
|
||||
"$metric_type: $current_value (threshold: $threshold)"
|
||||
}
|
||||
|
||||
# Slow query detected
|
||||
gl_slow_query_detected() {
|
||||
local query_type="$1"
|
||||
local duration="$2"
|
||||
local threshold="${3:-500ms}"
|
||||
local endpoint="${4:-unknown}"
|
||||
|
||||
gl_log "🐌📊👉🔥" \
|
||||
"slow_query" \
|
||||
"$endpoint" \
|
||||
"Query: $query_type took $duration (threshold: $threshold)"
|
||||
}
|
||||
|
||||
# Performance improved
|
||||
gl_performance_improved() {
|
||||
local metric="$1"
|
||||
local before="$2"
|
||||
local after="$3"
|
||||
local improvement_pct="$4"
|
||||
|
||||
gl_log "✅⚡🎢🎉" \
|
||||
"performance_improved" \
|
||||
"$metric" \
|
||||
"Before: $before → After: $after (${improvement_pct}% improvement)"
|
||||
}
|
||||
```
|
||||
|
||||
### User Analytics
|
||||
|
||||
```bash
|
||||
# User action tracked
|
||||
gl_user_action() {
|
||||
local event_name="$1"
|
||||
local user_id="${2:-anonymous}"
|
||||
local properties="${3:-}"
|
||||
|
||||
gl_log "👤📊👉📌" \
|
||||
"user_action" \
|
||||
"$event_name" \
|
||||
"User: $user_id | Properties: $properties"
|
||||
}
|
||||
|
||||
# Conversion event
|
||||
gl_conversion_event() {
|
||||
local funnel="$1"
|
||||
local user_id="$2"
|
||||
local value="${3:-}"
|
||||
local duration="${4:-unknown}"
|
||||
|
||||
gl_log "🎯✅🎢🌍" \
|
||||
"conversion" \
|
||||
"$funnel" \
|
||||
"User: $user_id | Value: $value | Duration: $duration"
|
||||
}
|
||||
|
||||
# User churn
|
||||
gl_user_churn() {
|
||||
local user_id="$1"
|
||||
local reason="${2:-unknown}"
|
||||
local lifetime_value="${3:-unknown}"
|
||||
|
||||
gl_log "🚪👋👉⚠️" \
|
||||
"user_churn" \
|
||||
"$user_id" \
|
||||
"Reason: $reason | LTV: $lifetime_value"
|
||||
}
|
||||
|
||||
# Cohort retention
|
||||
gl_cohort_retention() {
|
||||
local cohort="$1"
|
||||
local retention_rate="$2"
|
||||
local time_period="$3"
|
||||
|
||||
gl_log "📊👥🎢📌" \
|
||||
"cohort_retention" \
|
||||
"$cohort" \
|
||||
"Retention: $retention_rate after $time_period"
|
||||
}
|
||||
```
|
||||
|
||||
### Service Health
|
||||
|
||||
```bash
|
||||
# Service up
|
||||
gl_service_up() {
|
||||
local service="$1"
|
||||
local uptime_pct="${2:-100}"
|
||||
local region="${3:-global}"
|
||||
|
||||
gl_log "✅🌐🎢🌍" \
|
||||
"service_up" \
|
||||
"$service" \
|
||||
"Status: operational | Uptime: $uptime_pct% | Region: $region"
|
||||
}
|
||||
|
||||
# Service down
|
||||
gl_service_down() {
|
||||
local service="$1"
|
||||
local error="${2:-unknown}"
|
||||
local impact="${3:-all users}"
|
||||
|
||||
gl_log "🚨⛔👉🔥" \
|
||||
"service_down" \
|
||||
"$service" \
|
||||
"Error: $error | Impact: $impact"
|
||||
}
|
||||
|
||||
# Service degraded
|
||||
gl_service_degraded() {
|
||||
local service="$1"
|
||||
local reason="$2"
|
||||
local performance_impact="${3:-unknown}"
|
||||
|
||||
gl_log "⚠️📉👉🔥" \
|
||||
"service_degraded" \
|
||||
"$service" \
|
||||
"Reason: $reason | Impact: $performance_impact"
|
||||
}
|
||||
|
||||
# Service recovered
|
||||
gl_service_recovered() {
|
||||
local service="$1"
|
||||
local downtime_duration="$2"
|
||||
local recovery_action="${3:-automatic}"
|
||||
|
||||
gl_log "✅🔄🎢🎉" \
|
||||
"service_recovered" \
|
||||
"$service" \
|
||||
"Downtime: $downtime_duration | Recovery: $recovery_action"
|
||||
}
|
||||
```
|
||||
|
||||
### Metrics & Thresholds
|
||||
|
||||
```bash
|
||||
# Metric threshold exceeded
|
||||
gl_metric_threshold() {
|
||||
local metric_name="$1"
|
||||
local current_value="$2"
|
||||
local threshold="$3"
|
||||
local severity="${4:-warning}"
|
||||
|
||||
local severity_emoji=""
|
||||
case "$severity" in
|
||||
critical) severity_emoji="🚨" ;;
|
||||
warning) severity_emoji="⚠️" ;;
|
||||
info) severity_emoji="ℹ️" ;;
|
||||
*) severity_emoji="📊" ;;
|
||||
esac
|
||||
|
||||
gl_log "${severity_emoji}📊👉🔥" \
|
||||
"metric_threshold" \
|
||||
"$metric_name" \
|
||||
"Value: $current_value exceeds threshold: $threshold"
|
||||
}
|
||||
|
||||
# Metric anomaly detected
|
||||
gl_metric_anomaly() {
|
||||
local metric_name="$1"
|
||||
local expected_range="$2"
|
||||
local actual_value="$3"
|
||||
local confidence="${4:-high}"
|
||||
|
||||
gl_log "🔍📊👉⭐" \
|
||||
"metric_anomaly" \
|
||||
"$metric_name" \
|
||||
"Expected: $expected_range | Actual: $actual_value | Confidence: $confidence"
|
||||
}
|
||||
|
||||
# Positive trend detected
|
||||
gl_metric_trending_up() {
|
||||
local metric_name="$1"
|
||||
local trend_pct="$2"
|
||||
local time_period="$3"
|
||||
|
||||
gl_log "📈✅🎢📌" \
|
||||
"metric_trending_up" \
|
||||
"$metric_name" \
|
||||
"Trend: +${trend_pct}% over $time_period"
|
||||
}
|
||||
|
||||
# Negative trend detected
|
||||
gl_metric_trending_down() {
|
||||
local metric_name="$1"
|
||||
local trend_pct="$2"
|
||||
local time_period="$3"
|
||||
|
||||
gl_log "📉⚠️👉🔥" \
|
||||
"metric_trending_down" \
|
||||
"$metric_name" \
|
||||
"Trend: -${trend_pct}% over $time_period"
|
||||
}
|
||||
```
|
||||
|
||||
### Logs & Debugging
|
||||
|
||||
```bash
|
||||
# Log aggregation complete
|
||||
gl_logs_aggregated() {
|
||||
local service="$1"
|
||||
local log_count="$2"
|
||||
local time_period="$3"
|
||||
local errors_found="${4:-0}"
|
||||
|
||||
gl_log "📝📊👉📌" \
|
||||
"logs_aggregated" \
|
||||
"$service" \
|
||||
"Logs: $log_count in $time_period | Errors: $errors_found"
|
||||
}
|
||||
|
||||
# Critical log pattern
|
||||
gl_log_pattern_critical() {
|
||||
local pattern="$1"
|
||||
local occurrences="$2"
|
||||
local services_affected="${3:-1}"
|
||||
|
||||
gl_log "🚨📝👉🔥" \
|
||||
"critical_log_pattern" \
|
||||
"$pattern" \
|
||||
"Occurrences: $occurrences | Services affected: $services_affected"
|
||||
}
|
||||
```
|
||||
|
||||
### Real User Monitoring (RUM)
|
||||
|
||||
```bash
|
||||
# Page load performance
|
||||
gl_page_load_performance() {
|
||||
local page="$1"
|
||||
local lcp="$2" # Largest Contentful Paint
|
||||
local fid="${3:-}" # First Input Delay
|
||||
local cls="${4:-}" # Cumulative Layout Shift
|
||||
|
||||
local performance_rating=""
|
||||
if [[ ${lcp%ms} -lt 2500 ]]; then
|
||||
performance_rating="good"
|
||||
rating_emoji="✅"
|
||||
elif [[ ${lcp%ms} -lt 4000 ]]; then
|
||||
performance_rating="needs improvement"
|
||||
rating_emoji="⚠️"
|
||||
else
|
||||
performance_rating="poor"
|
||||
rating_emoji="❌"
|
||||
fi
|
||||
|
||||
gl_log "${rating_emoji}📱👉📌" \
|
||||
"page_load_performance" \
|
||||
"$page" \
|
||||
"LCP: $lcp (${performance_rating}) | FID: $fid | CLS: $cls"
|
||||
}
|
||||
|
||||
# Browser error
|
||||
gl_browser_error() {
|
||||
local error_message="$1"
|
||||
local browser="$2"
|
||||
local page="${3:-unknown}"
|
||||
local user_id="${4:-anonymous}"
|
||||
|
||||
gl_log "🚨🌐👉🔥" \
|
||||
"browser_error" \
|
||||
"$page" \
|
||||
"Browser: $browser | Error: $error_message | User: $user_id"
|
||||
}
|
||||
```
|
||||
|
||||
### Synthetic Monitoring
|
||||
|
||||
```bash
|
||||
# Health check passed
|
||||
gl_health_check_passed() {
|
||||
local endpoint="$1"
|
||||
local response_time="$2"
|
||||
local region="${3:-global}"
|
||||
|
||||
gl_log "✅🤖👉📌" \
|
||||
"health_check_passed" \
|
||||
"$endpoint" \
|
||||
"Response time: $response_time | Region: $region"
|
||||
}
|
||||
|
||||
# Health check failed
|
||||
gl_health_check_failed() {
|
||||
local endpoint="$1"
|
||||
local error="$2"
|
||||
local region="${3:-global}"
|
||||
|
||||
gl_log "❌🤖👉🔥" \
|
||||
"health_check_failed" \
|
||||
"$endpoint" \
|
||||
"Error: $error | Region: $region"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example: Complete Observability Flow
|
||||
|
||||
### Scenario: Performance degradation detected, investigated, and resolved
|
||||
|
||||
```bash
|
||||
# 1. Performance alert triggered
|
||||
gl_performance_alert "api_latency" "blackroad-api" "1.2s" "500ms" "critical"
|
||||
# [🚨⚡👉🔥] performance_alert: blackroad-api — api_latency: 1.2s (threshold: 500ms)
|
||||
|
||||
# 2. Metric trending down
|
||||
gl_metric_trending_down "api_throughput" "35" "last 15 minutes"
|
||||
# [📉⚠️👉🔥] metric_trending_down: api_throughput — Trend: -35% over last 15 minutes
|
||||
|
||||
# 3. Slow queries detected
|
||||
gl_slow_query_detected "user_lookup" "2.3s" "500ms" "/api/users"
|
||||
# [🐌📊👉🔥] slow_query: /api/users — Query: user_lookup took 2.3s (threshold: 500ms)
|
||||
|
||||
# 4. Error spike detected
|
||||
gl_error_recurring "timeout-db-connection" "47" "last 10 minutes"
|
||||
# [🔄🚨👉🔥] error_recurring: timeout-db-connection — Occurrences: 47 in last 10 minutes - needs investigation
|
||||
|
||||
# 5. User impact tracked
|
||||
gl_user_action "checkout_abandoned" "user_789" "error: timeout"
|
||||
# [👤📊👉📌] user_action: checkout_abandoned — User: user_789 | Properties: error: timeout
|
||||
|
||||
# 6. Service degraded
|
||||
gl_service_degraded "blackroad-api" "Database connection pool exhausted" "50% slower responses"
|
||||
# [⚠️📉👉🔥] service_degraded: blackroad-api — Reason: Database connection pool exhausted | Impact: 50% slower responses
|
||||
|
||||
# 7. Root cause identified (from Context layer)
|
||||
gl_root_cause_identified "perf-001" "Database connection pool size too small for traffic spike" "high"
|
||||
# [🎯🐛🎢⭐] root_cause_identified: perf-001 — Root cause: Database connection pool size too small for traffic spike | Confidence: high
|
||||
|
||||
# 8. Fix deployed
|
||||
gl_deploy "blackroad-api" "https://api.blackroad.io" "Increased DB connection pool: 10 → 50" "🎢" "🔧"
|
||||
# [🚀🎢🔧✅] deployed: blackroad-api — URL: https://api.blackroad.io. Increased DB connection pool: 10 → 50
|
||||
|
||||
# 9. Performance improved
|
||||
gl_performance_improved "api_latency" "1.2s" "180ms" "85"
|
||||
# [✅⚡🎢🎉] performance_improved: api_latency — Before: 1.2s → After: 180ms (85% improvement)
|
||||
|
||||
# 10. Service recovered
|
||||
gl_service_recovered "blackroad-api" "12 minutes" "manual deployment"
|
||||
# [✅🔄🎢🎉] service_recovered: blackroad-api — Downtime: 12 minutes | Recovery: manual deployment
|
||||
|
||||
# 11. Users converting again
|
||||
gl_conversion_event "checkout" "user_790" "$149" "45s"
|
||||
# [🎯✅🎢🌍] conversion: checkout — User: user_790 | Value: $149 | Duration: 45s
|
||||
|
||||
# 12. Metrics back to normal
|
||||
gl_metric_trending_up "api_throughput" "120" "last 15 minutes"
|
||||
# [📈✅🎢📌] metric_trending_up: api_throughput — Trend: +120% over last 15 minutes
|
||||
|
||||
# 13. Learning documented (Context layer)
|
||||
gl_learning_discovered "infrastructure-capacity" "Monitor connection pool usage, auto-scale before exhaustion" "Prevented 85% performance degradation"
|
||||
# [💡✨👉⭐] learning_discovered: infrastructure-capacity — Insight: Monitor connection pool usage, auto-scale before exhaustion | Evidence: Prevented 85% performance degradation
|
||||
```
|
||||
|
||||
**Result:** Complete incident lifecycle tracked from detection → investigation → resolution → recovery → learning.
|
||||
|
||||
---
|
||||
|
||||
## 📊 Key Metrics to Track
|
||||
|
||||
### Performance Metrics
|
||||
- **API Latency** (P50, P95, P99)
|
||||
- **Database Query Time**
|
||||
- **Worker Execution Time**
|
||||
- **Page Load Time** (LCP, FID, CLS)
|
||||
- **Error Rate**
|
||||
|
||||
### Business Metrics
|
||||
- **Conversion Rate** (signup, checkout, etc.)
|
||||
- **Revenue** (MRR, ARR)
|
||||
- **Churn Rate**
|
||||
- **User Retention** (Day 1, Day 7, Day 30)
|
||||
- **Customer Lifetime Value**
|
||||
|
||||
### Infrastructure Metrics
|
||||
- **CPU Usage**
|
||||
- **Memory Usage**
|
||||
- **Disk Usage**
|
||||
- **Network Throughput**
|
||||
- **Request Rate**
|
||||
|
||||
### User Behavior Metrics
|
||||
- **Active Users** (DAU, MAU)
|
||||
- **Session Duration**
|
||||
- **Feature Adoption**
|
||||
- **Funnel Drop-off**
|
||||
- **User Journey Completion**
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Mapped observability events to GreenLight workflow
|
||||
- [x] Created monitoring categories (8 types)
|
||||
- [x] Extended NATS subjects for analytics events
|
||||
- [x] Built 25+ observability templates
|
||||
- [x] Error tracking & resolution
|
||||
- [x] Performance monitoring & alerts
|
||||
- [x] User analytics & conversion tracking
|
||||
- [x] Service health monitoring
|
||||
- [x] Metric threshold alerts
|
||||
- [x] Log aggregation
|
||||
- [x] Real User Monitoring (RUM)
|
||||
- [x] Synthetic monitoring
|
||||
- [x] Infrastructure metrics
|
||||
- [x] Incident lifecycle tracking
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025 🌸
|
||||
**For:** Analytics & Observability
|
||||
**Version:** 2.0.0-observability
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
**Built by:** Cece (for production visibility)
|
||||
|
||||
462
.trinity/greenlight/docs/GREENLIGHT_BILLING_EXTENSION.md
Normal file
462
.trinity/greenlight/docs/GREENLIGHT_BILLING_EXTENSION.md
Normal file
@@ -0,0 +1,462 @@
|
||||
# 💳 GreenLight Billing & Payment Extension
|
||||
|
||||
**Extension to GreenLight for Stripe Billing Integration**
|
||||
|
||||
---
|
||||
|
||||
## 💰 Billing Lifecycle States
|
||||
|
||||
Add these to the **Lifecycle States** category:
|
||||
|
||||
| Emoji | State | Code | Trinary | Description |
|
||||
|-------|-------|------|---------|-------------|
|
||||
| 💳 | CHECKOUT | `checkout` | 0 | Checkout session initiated |
|
||||
| 💵 | PAYMENT_PENDING | `payment_pending` | +1 | Payment processing |
|
||||
| 💰 | PAYMENT_SUCCESS | `payment_success` | +1 | Payment completed |
|
||||
| ❌ | PAYMENT_FAILED | `payment_failed` | -1 | Payment declined/failed |
|
||||
| 🔁 | RETRY | `retry` | 0 | Payment retry attempt |
|
||||
| ⏸️ | PAST_DUE | `past_due` | -1 | Subscription past due |
|
||||
| 🎟️ | TRIAL | `trial` | 0 | Trial period active |
|
||||
| 🎁 | COUPON_APPLIED | `coupon_applied` | +1 | Discount code applied |
|
||||
|
||||
---
|
||||
|
||||
## 📦 Subscription States
|
||||
|
||||
| Emoji | State | Code | Stripe Status | Description |
|
||||
|-------|-------|------|---------------|-------------|
|
||||
| 🆕 | SUB_CREATED | `sub_created` | active | New subscription |
|
||||
| ✅ | SUB_ACTIVE | `sub_active` | active | Subscription active |
|
||||
| 🔄 | SUB_UPDATED | `sub_updated` | active | Plan changed |
|
||||
| ⏸️ | SUB_PAUSED | `sub_paused` | paused | Subscription paused |
|
||||
| 🚫 | SUB_CANCELED | `sub_canceled` | canceled | Subscription ended |
|
||||
| ⚠️ | SUB_INCOMPLETE | `sub_incomplete` | incomplete | Payment incomplete |
|
||||
| 📅 | SUB_EXPIRING | `sub_expiring` | active | Canceling at period end |
|
||||
| 🔄 | SUB_PAST_DUE | `sub_past_due` | past_due | Payment failed |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Billing Tiers
|
||||
|
||||
Add to **Domain Tags**:
|
||||
|
||||
| Emoji | Tier | Code | Price | Description |
|
||||
|-------|------|------|-------|-------------|
|
||||
| 🆓 | FREE | `free` | $0 | Free tier |
|
||||
| 👤 | INDIVIDUAL | `individual` | $29/mo | Individual plan |
|
||||
| 💼 | PRO | `pro` | $58/mo | Professional plan |
|
||||
| 👥 | TEAM | `team` | $99/mo | Team plan |
|
||||
| 🏢 | ENTERPRISE | `enterprise` | $199/mo | Enterprise plan |
|
||||
| 🌟 | FOUNDER | `founder` | $5000 | Lifetime founding member |
|
||||
| 💎 | FOUNDING_PRO | `founding_pro` | $29/mo | 50% founding discount |
|
||||
|
||||
---
|
||||
|
||||
## 🔔 Webhook Events
|
||||
|
||||
Map Stripe webhook events to GreenLight:
|
||||
|
||||
| Stripe Event | GreenLight Step | Emoji | State |
|
||||
|--------------|-----------------|-------|-------|
|
||||
| webhook received | Step 1: Impulse | ⚡📥 | void → inbox |
|
||||
| customer.created | Step 4: Record | 📝👤 | inbox → recorded |
|
||||
| checkout.session.completed | Step 7: Approve | ✅💳 | evaluate → approved |
|
||||
| subscription.created | Step 13: Execute | ⚙️🆕 | plan → executing |
|
||||
| invoice.paid | Step 19: Complete | 🎉💰 | executing → complete |
|
||||
| subscription.updated | Step 14: Iterate | 🔄🔄 | executing → iterate |
|
||||
| invoice.payment_failed | Step 16: Detect | 🚨❌ | executing → detect |
|
||||
| subscription.deleted | Step 21: Accept | 🤝🚫 | complete → accepted |
|
||||
| payment_method.attached | Step 6: Verify | 🔍💳 | record → verified |
|
||||
| customer.updated | Step 10: Refine | ✨👤 | configure → refined |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for Billing
|
||||
|
||||
### Checkout Events
|
||||
```
|
||||
⚡📥💳👉 = Checkout started, micro scale
|
||||
✅💳💰🎢 = Payment successful, macro impact
|
||||
❌💳🚨🔥 = Payment failed, fire priority
|
||||
🎁💳✅📌 = Coupon applied, medium priority
|
||||
```
|
||||
|
||||
### Subscription Events
|
||||
```
|
||||
🆕🎯💼✅ = New pro subscription created
|
||||
🔄🎯👥📌 = Team plan upgrade
|
||||
🚫⚠️💼🔥 = Pro subscription canceled, urgent
|
||||
⏸️📅💼⭐ = Subscription expiring, high priority
|
||||
```
|
||||
|
||||
### Payment Events
|
||||
```
|
||||
💰✅🎢🌍 = Invoice paid, planetary impact
|
||||
❌🔁💳⭐ = Payment retry, high priority
|
||||
⚠️🚨💼🔥 = Past due, fire priority
|
||||
🎟️🆕👤📌 = Trial started, medium priority
|
||||
```
|
||||
|
||||
### Combined Billing Flow
|
||||
```
|
||||
[⚡📥] [✅💳] [🆕💼] [💰✅] = Checkout → Payment → Subscription → Paid
|
||||
[🔄💼→👥] [💰✅] = Upgrade Pro → Team, payment success
|
||||
[🚨❌] [🔁💳] = Payment failed → retry
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (Billing)
|
||||
|
||||
### Checkout Events
|
||||
```
|
||||
greenlight.checkout.started.micro.billing.{session_id}
|
||||
greenlight.checkout.completed.macro.billing.{session_id}
|
||||
greenlight.checkout.abandoned.micro.billing.{session_id}
|
||||
```
|
||||
|
||||
### Payment Events
|
||||
```
|
||||
greenlight.payment.succeeded.macro.billing.{customer_id}
|
||||
greenlight.payment.failed.micro.billing.{customer_id}
|
||||
greenlight.payment.retry.micro.billing.{customer_id}
|
||||
```
|
||||
|
||||
### Subscription Events
|
||||
```
|
||||
greenlight.subscription.created.{tier}.{customer_id}
|
||||
greenlight.subscription.updated.{old_tier}.{new_tier}.{customer_id}
|
||||
greenlight.subscription.canceled.{tier}.{customer_id}
|
||||
greenlight.subscription.expired.{tier}.{customer_id}
|
||||
```
|
||||
|
||||
### Webhook Events
|
||||
```
|
||||
greenlight.webhook.received.stripe.{event_type}
|
||||
greenlight.webhook.processed.stripe.{event_type}
|
||||
greenlight.webhook.failed.stripe.{event_type}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Billing Memory Templates
|
||||
|
||||
### Stripe Webhook Events
|
||||
|
||||
```bash
|
||||
# Webhook received
|
||||
gl_webhook_received() {
|
||||
local event_type="$1"
|
||||
local event_id="$2"
|
||||
|
||||
gl_log "⚡📥💳👉" "webhook_received" "$event_type" "Stripe webhook: $event_id"
|
||||
}
|
||||
|
||||
# Checkout session completed
|
||||
gl_checkout_complete() {
|
||||
local customer_email="$1"
|
||||
local tier="$2"
|
||||
local amount="$3"
|
||||
|
||||
local tier_emoji=""
|
||||
case "$tier" in
|
||||
individual) tier_emoji="👤" ;;
|
||||
pro) tier_emoji="💼" ;;
|
||||
team) tier_emoji="👥" ;;
|
||||
enterprise) tier_emoji="🏢" ;;
|
||||
founder) tier_emoji="🌟" ;;
|
||||
*) tier_emoji="🎯" ;;
|
||||
esac
|
||||
|
||||
gl_log "✅💳${tier_emoji}🎢" "checkout_complete" "$customer_email" \
|
||||
"Checkout complete: $tier plan, $$amount"
|
||||
}
|
||||
|
||||
# Subscription created
|
||||
gl_subscription_created() {
|
||||
local customer="$1"
|
||||
local tier="$2"
|
||||
local subscription_id="$3"
|
||||
|
||||
local tier_emoji=""
|
||||
case "$tier" in
|
||||
individual) tier_emoji="👤" ;;
|
||||
pro) tier_emoji="💼" ;;
|
||||
team) tier_emoji="👥" ;;
|
||||
enterprise) tier_emoji="🏢" ;;
|
||||
founder) tier_emoji="🌟" ;;
|
||||
*) tier_emoji="🎯" ;;
|
||||
esac
|
||||
|
||||
gl_log "🆕⚙️${tier_emoji}✅" "subscription_created" "$customer" \
|
||||
"Subscription created: $tier ($subscription_id)"
|
||||
}
|
||||
|
||||
# Subscription updated (plan change)
|
||||
gl_subscription_updated() {
|
||||
local customer="$1"
|
||||
local old_tier="$2"
|
||||
local new_tier="$3"
|
||||
|
||||
gl_log "🔄🎯💼📌" "subscription_updated" "$customer" \
|
||||
"Plan change: $old_tier → $new_tier"
|
||||
}
|
||||
|
||||
# Subscription canceled
|
||||
gl_subscription_canceled() {
|
||||
local customer="$1"
|
||||
local tier="$2"
|
||||
local reason="${3:-not specified}"
|
||||
|
||||
gl_log "🚫⚠️💼🔥" "subscription_canceled" "$customer" \
|
||||
"Canceled $tier plan. Reason: $reason"
|
||||
}
|
||||
|
||||
# Invoice paid
|
||||
gl_invoice_paid() {
|
||||
local customer="$1"
|
||||
local amount="$2"
|
||||
local currency="${3:-usd}"
|
||||
|
||||
gl_log "💰✅🎢🌍" "invoice_paid" "$customer" \
|
||||
"Payment successful: \$$amount $currency"
|
||||
}
|
||||
|
||||
# Invoice payment failed
|
||||
gl_invoice_failed() {
|
||||
local customer="$1"
|
||||
local amount="$2"
|
||||
local error="${3:-declined}"
|
||||
|
||||
gl_log "❌🚨💳🔥" "invoice_failed" "$customer" \
|
||||
"Payment failed: \$$amount ($error)"
|
||||
}
|
||||
|
||||
# Payment retry
|
||||
gl_payment_retry() {
|
||||
local customer="$1"
|
||||
local attempt="$2"
|
||||
|
||||
gl_log "🔁💳⚡⭐" "payment_retry" "$customer" \
|
||||
"Payment retry attempt #$attempt"
|
||||
}
|
||||
|
||||
# Coupon applied
|
||||
gl_coupon_applied() {
|
||||
local customer="$1"
|
||||
local coupon_code="$2"
|
||||
local discount="$3"
|
||||
|
||||
gl_log "🎁💳✅📌" "coupon_applied" "$customer" \
|
||||
"Coupon $coupon_code applied: $discount"
|
||||
}
|
||||
|
||||
# Trial started
|
||||
gl_trial_started() {
|
||||
local customer="$1"
|
||||
local tier="$2"
|
||||
local trial_days="$3"
|
||||
|
||||
gl_log "🎟️🆕👤📌" "trial_started" "$customer" \
|
||||
"Trial started: $tier plan, $trial_days days"
|
||||
}
|
||||
|
||||
# Customer created
|
||||
gl_customer_created() {
|
||||
local email="$1"
|
||||
local customer_id="$2"
|
||||
|
||||
gl_log "📝👤✅👉" "customer_created" "$email" \
|
||||
"Stripe customer: $customer_id"
|
||||
}
|
||||
|
||||
# Payment method attached
|
||||
gl_payment_method_attached() {
|
||||
local customer="$1"
|
||||
local pm_type="$2" # card, bank_account, etc.
|
||||
local last4="${3:-****}"
|
||||
|
||||
gl_log "🔍💳✅📌" "payment_method" "$customer" \
|
||||
"Payment method added: $pm_type ending in $last4"
|
||||
}
|
||||
|
||||
# Subscription past due
|
||||
gl_subscription_past_due() {
|
||||
local customer="$1"
|
||||
local days_overdue="$2"
|
||||
|
||||
gl_log "⚠️🚨💼🔥" "past_due" "$customer" \
|
||||
"Subscription past due: $days_overdue days"
|
||||
}
|
||||
|
||||
# Churn prevention (cancellation scheduled)
|
||||
gl_cancel_scheduled() {
|
||||
local customer="$1"
|
||||
local tier="$2"
|
||||
local cancel_date="$3"
|
||||
|
||||
gl_log "📅⚠️💼⭐" "cancel_scheduled" "$customer" \
|
||||
"$tier subscription ends on $cancel_date - retention opportunity!"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Full Checkout Flow
|
||||
|
||||
### Scenario: User subscribes to Pro plan
|
||||
|
||||
```bash
|
||||
# 1. Webhook received
|
||||
gl_webhook_received "checkout.session.completed" "evt_1abc123"
|
||||
# [⚡📥💳👉] webhook_received: checkout.session.completed — Stripe webhook: evt_1abc123
|
||||
|
||||
# 2. Customer created (if new)
|
||||
gl_customer_created "user@example.com" "cus_abc123"
|
||||
# [📝👤✅👉] customer_created: user@example.com — Stripe customer: cus_abc123
|
||||
|
||||
# 3. Checkout complete
|
||||
gl_checkout_complete "user@example.com" "pro" "58"
|
||||
# [✅💳💼🎢] checkout_complete: user@example.com — Checkout complete: pro plan, $58
|
||||
|
||||
# 4. Subscription created
|
||||
gl_subscription_created "user@example.com" "pro" "sub_abc123"
|
||||
# [🆕⚙️💼✅] subscription_created: user@example.com — Subscription created: pro (sub_abc123)
|
||||
|
||||
# 5. Invoice paid
|
||||
gl_invoice_paid "user@example.com" "58" "usd"
|
||||
# [💰✅🎢🌍] invoice_paid: user@example.com — Payment successful: $58 usd
|
||||
```
|
||||
|
||||
### Scenario: Payment failed, retry, then cancel
|
||||
|
||||
```bash
|
||||
# 1. Payment failed
|
||||
gl_invoice_failed "user@example.com" "58" "card_declined"
|
||||
# [❌🚨💳🔥] invoice_failed: user@example.com — Payment failed: $58 (card_declined)
|
||||
|
||||
# 2. Subscription past due
|
||||
gl_subscription_past_due "user@example.com" "3"
|
||||
# [⚠️🚨💼🔥] past_due: user@example.com — Subscription past due: 3 days
|
||||
|
||||
# 3. Payment retry
|
||||
gl_payment_retry "user@example.com" "1"
|
||||
# [🔁💳⚡⭐] payment_retry: user@example.com — Payment retry attempt #1
|
||||
|
||||
# 4. Payment retry #2
|
||||
gl_payment_retry "user@example.com" "2"
|
||||
# [🔁💳⚡⭐] payment_retry: user@example.com — Payment retry attempt #2
|
||||
|
||||
# 5. Subscription canceled (after retry exhaustion)
|
||||
gl_subscription_canceled "user@example.com" "pro" "payment_failed"
|
||||
# [🚫⚠️💼🔥] subscription_canceled: user@example.com — Canceled pro plan. Reason: payment_failed
|
||||
```
|
||||
|
||||
### Scenario: Upgrade from Individual to Team
|
||||
|
||||
```bash
|
||||
# 1. Subscription updated
|
||||
gl_subscription_updated "team@company.com" "individual" "team"
|
||||
# [🔄🎯💼📌] subscription_updated: team@company.com — Plan change: individual → team
|
||||
|
||||
# 2. Invoice paid (proration)
|
||||
gl_invoice_paid "team@company.com" "70" "usd"
|
||||
# [💰✅🎢🌍] invoice_paid: team@company.com — Payment successful: $70 usd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Billing Analytics Integration
|
||||
|
||||
### Revenue Tracking
|
||||
```bash
|
||||
# Daily revenue
|
||||
gl_log "📊💰🎢📌" "revenue_daily" "billing" "Daily revenue: $1,247.00 (43 invoices)"
|
||||
|
||||
# MRR (Monthly Recurring Revenue)
|
||||
gl_log "📊💰🌌⭐" "mrr_update" "billing" "MRR: $24,567 (+$1,234 this month)"
|
||||
|
||||
# Churn rate
|
||||
gl_log "📊⚠️🎢📌" "churn_rate" "billing" "Churn rate: 3.2% (12 cancellations)"
|
||||
```
|
||||
|
||||
### Customer Lifecycle
|
||||
```bash
|
||||
# Customer lifetime value
|
||||
gl_log "📊💎🎢⭐" "ltv_update" "analytics" "Avg LTV: $1,847 (+15% MoM)"
|
||||
|
||||
# Trial conversion
|
||||
gl_log "📊🎟️👉📌" "trial_conversion" "analytics" "Trial conversion: 42% (21 of 50)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security & Compliance
|
||||
|
||||
### Webhook Signature Verification
|
||||
```bash
|
||||
# Valid webhook
|
||||
gl_log "🔐✅💳👉" "webhook_verified" "stripe" "Webhook signature valid"
|
||||
|
||||
# Invalid webhook
|
||||
gl_log "🔐❌💳🚨" "webhook_invalid" "stripe" "Webhook signature INVALID - rejected"
|
||||
```
|
||||
|
||||
### PCI Compliance
|
||||
```bash
|
||||
# Payment method tokenization
|
||||
gl_log "🔒💳✅📌" "tokenized" "stripe" "Payment method tokenized (no PAN stored)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Extended lifecycle states for billing
|
||||
- [x] Added subscription state tracking
|
||||
- [x] Created billing tier tags
|
||||
- [x] Mapped Stripe webhook events to GreenLight steps
|
||||
- [x] Created composite patterns for checkout/payment/subscription flows
|
||||
- [x] Extended NATS subjects for billing events
|
||||
- [x] Built 14 billing-specific templates
|
||||
- [x] Integrated with 27-step GreenLight workflow
|
||||
- [x] Added analytics tracking patterns
|
||||
- [x] Added security/compliance patterns
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Stripe Account Details
|
||||
|
||||
**Account ID:** `acct_1SUDM8ChUUSEbzyh`
|
||||
**Display Name:** BlackRoad OS, Inc.
|
||||
**Dashboard:** https://dashboard.stripe.com/acct_1SUDM8ChUUSEbzyh
|
||||
|
||||
### Product IDs
|
||||
```
|
||||
individual = prod_TTNH7uTYVlPbVV
|
||||
team = prod_TTNHfJE07G7dty
|
||||
enterprise = prod_TTNHTnkdlC00Vk
|
||||
pro_monthly = prod_TZp5dIXyukAtLx
|
||||
founder = prod_TZp5ecvCkxHcQh
|
||||
founding_pro = prod_TefgSJ9T70wriE
|
||||
pro_full = prod_Tefg4jmio5PjnR
|
||||
enterprise_v2 = prod_Tefg0LHPUjS7xn
|
||||
```
|
||||
|
||||
### Price IDs
|
||||
```
|
||||
individual: price_1SWQXAChUUSEbzyhAykgEy5K ($29/mo)
|
||||
team: price_1SWQXKChUUSEbzyhLSObMBLT ($99/mo)
|
||||
pro_monthly: price_1ScfRCChUUSEbzyh5CXWtrTl ($29/mo)
|
||||
pro_full: price_1ShMKtChUUSEbzyhitCMw6z3 ($58/mo)
|
||||
founding_pro: price_1ShMKtChUUSEbzyhve1z7RA1 ($29/mo - 50% off)
|
||||
enterprise: price_1ShMKuChUUSEbzyhVxRH4mjK ($199/mo)
|
||||
founder_lifetime: price_1ScfRCChUUSEbzyhhCiqFmUB ($5000 once)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** Stripe Billing Integration
|
||||
**Version:** 2.0.0-billing
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
626
.trinity/greenlight/docs/GREENLIGHT_CANVA_EXTENSION.md
Normal file
626
.trinity/greenlight/docs/GREENLIGHT_CANVA_EXTENSION.md
Normal file
@@ -0,0 +1,626 @@
|
||||
# 🎨 GreenLight Canva Integration
|
||||
|
||||
**Extension to GreenLight for Canva Design Workflow**
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Canva Events as GreenLight Steps
|
||||
|
||||
Map Canva events directly to GreenLight workflow:
|
||||
|
||||
| Canva Event | GreenLight Step | Step # | Emoji | State Transition | Context |
|
||||
|-------------|-----------------|--------|-------|------------------|---------|
|
||||
| Design created | ⚡ Impulse | 1 | ⚡🎨 | void → inbox | any design |
|
||||
| Template used | 📥 Capture | 3 | 📥🖼️ | → inbox | from template |
|
||||
| Asset uploaded | 📤 Upload | 5 | 📤🖼️ | → inbox | images/videos |
|
||||
| Design edited | ⚙️ Execute | 13 | ⚙️✏️ | → wip | any design |
|
||||
| Comment added | 💬 Collaborate | 11 | 💬🎨 | → wip | team feedback |
|
||||
| Design approved | ✅ Approve | 7 | ✅👍 | → queued | review workflow |
|
||||
| Design published | 🎉 Complete | 19 | 🎉🎨 | wip → done | published |
|
||||
| Design exported | 📦 Export | 18 | 📦💾 | done → void | downloaded |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Canva Design Types
|
||||
|
||||
Design categories with GreenLight mappings:
|
||||
|
||||
| Emoji | Design Type | Purpose | GreenLight Domain | Common Formats |
|
||||
|-------|-------------|---------|-------------------|----------------|
|
||||
| 📱 | Social Media | Posts, stories, ads | Marketing (📣) | PNG, JPG, MP4 |
|
||||
| 📄 | Presentation | Slides, pitch decks | Platform (🛣️) | PDF, PPTX |
|
||||
| 📰 | Document | Reports, proposals | Documentation (📚) | PDF, DOCX |
|
||||
| 🎬 | Video | Animations, ads | Marketing (📣) | MP4, GIF |
|
||||
| 🖼️ | Graphic | Logos, icons, banners | Design (🎨) | PNG, SVG |
|
||||
| 📧 | Email | Newsletters, campaigns | Marketing (📣) | HTML, PNG |
|
||||
| 🌐 | Web | Banners, headers | Marketing (📣) | PNG, SVG |
|
||||
| 📊 | Infographic | Data visualization | Platform (🛣️) | PNG, PDF |
|
||||
| 🎯 | Marketing | Flyers, posters | Marketing (📣) | PDF, PNG |
|
||||
| 👕 | Print | Merch, business cards | Marketing (📣) | PDF, PNG |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Canva Asset Types as GreenLight Tags
|
||||
|
||||
| Asset Type | Emoji | GreenLight Usage | Examples |
|
||||
|------------|-------|------------------|----------|
|
||||
| Image | 🖼️ | Visual content | Photos, illustrations |
|
||||
| Video | 🎬 | Motion content | Clips, animations |
|
||||
| Audio | 🎵 | Sound content | Music, voiceovers |
|
||||
| Text | 📝 | Typography | Headings, body text |
|
||||
| Shape | 🔷 | Geometric | Rectangles, circles |
|
||||
| Sticker | ✨ | Decorative | Icons, emojis |
|
||||
| Chart | 📊 | Data viz | Bar, pie, line charts |
|
||||
| Frame | 🖼️ | Containers | Image placeholders |
|
||||
| Line | 📏 | Dividers | Horizontal, vertical |
|
||||
| Grid | ⊞ | Layout | Structure, alignment |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for Canva
|
||||
|
||||
### Design Operations
|
||||
```
|
||||
⚡🎨👉📌 = New design created, micro scale
|
||||
✏️🎨🎢⭐ = Design edited, macro scale, high priority
|
||||
🎉🎨🎢🌍 = Design published, macro impact
|
||||
```
|
||||
|
||||
### Asset Operations
|
||||
```
|
||||
📤🖼️👉📌 = Image uploaded
|
||||
🎬📥👉📌 = Video imported
|
||||
📊🎨🎢📌 = Chart/infographic created, macro
|
||||
```
|
||||
|
||||
### Collaboration Events
|
||||
```
|
||||
💬🎨👉⭐ = Comment added, high priority
|
||||
👥🎨👉📌 = Design shared with team
|
||||
✅👍🎢📌 = Design approved, macro
|
||||
```
|
||||
|
||||
### Export Operations
|
||||
```
|
||||
📦💾👉📌 = Design exported, micro
|
||||
🌐🎨🎢🌍 = Design published to web, global
|
||||
📱🎨👉📣 = Social media post published
|
||||
```
|
||||
|
||||
### Full Canva Flow
|
||||
```
|
||||
[⚡🎨] [✏️🎨] [💬🎨] [✅👍] [🎉🎨] [📦💾] = Create → Edit → Review → Approve → Publish → Export
|
||||
[📤🖼️] [⚙️✏️] [📱🎨] = Upload → Edit → Post to social
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (Canva)
|
||||
|
||||
### Design Events
|
||||
```
|
||||
greenlight.canva.design.created.micro.design.{design_id}
|
||||
greenlight.canva.design.updated.micro.design.{design_id}
|
||||
greenlight.canva.design.deleted.micro.design.{design_id}
|
||||
greenlight.canva.design.published.macro.design.{design_id}
|
||||
```
|
||||
|
||||
### Asset Events
|
||||
```
|
||||
greenlight.canva.asset.uploaded.micro.design.{asset_id}
|
||||
greenlight.canva.asset.deleted.micro.design.{asset_id}
|
||||
greenlight.canva.asset.replaced.micro.design.{asset_id}
|
||||
```
|
||||
|
||||
### Export Events
|
||||
```
|
||||
greenlight.canva.export.started.micro.design.{design_id}
|
||||
greenlight.canva.export.completed.macro.design.{design_id}
|
||||
greenlight.canva.export.failed.micro.design.{design_id}
|
||||
```
|
||||
|
||||
### Collaboration Events
|
||||
```
|
||||
greenlight.canva.comment.added.micro.design.{design_id}
|
||||
greenlight.canva.share.invited.micro.design.{user_id}
|
||||
greenlight.canva.approval.requested.micro.design.{design_id}
|
||||
greenlight.canva.approval.granted.macro.design.{design_id}
|
||||
```
|
||||
|
||||
### Folder Events
|
||||
```
|
||||
greenlight.canva.folder.created.micro.design.{folder_id}
|
||||
greenlight.canva.folder.organized.micro.design.{folder_id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Canva Memory Templates
|
||||
|
||||
### Design Operations
|
||||
|
||||
```bash
|
||||
# Design created
|
||||
gl_canva_design_created() {
|
||||
local design_title="$1"
|
||||
local design_type="$2" # social_post, presentation, document, video, etc.
|
||||
local creator="${3:-unknown}"
|
||||
|
||||
local type_emoji=""
|
||||
case "$design_type" in
|
||||
social_post|instagram|facebook|twitter) type_emoji="📱" ;;
|
||||
presentation|slides) type_emoji="📄" ;;
|
||||
document|report) type_emoji="📰" ;;
|
||||
video|animation) type_emoji="🎬" ;;
|
||||
graphic|logo|icon) type_emoji="🖼️" ;;
|
||||
email|newsletter) type_emoji="📧" ;;
|
||||
infographic|chart) type_emoji="📊" ;;
|
||||
*) type_emoji="🎨" ;;
|
||||
esac
|
||||
|
||||
gl_log "⚡${type_emoji}👉📌" \
|
||||
"design_created" \
|
||||
"$design_title" \
|
||||
"Type: $design_type, Creator: $creator"
|
||||
}
|
||||
|
||||
# Design edited
|
||||
gl_canva_design_edited() {
|
||||
local design_title="$1"
|
||||
local edit_type="${2:-content}" # content, layout, style, text
|
||||
|
||||
local edit_emoji=""
|
||||
case "$edit_type" in
|
||||
content) edit_emoji="✏️" ;;
|
||||
layout) edit_emoji="⊞" ;;
|
||||
style) edit_emoji="🎨" ;;
|
||||
text) edit_emoji="📝" ;;
|
||||
*) edit_emoji="⚙️" ;;
|
||||
esac
|
||||
|
||||
gl_log "${edit_emoji}🎨👉📌" \
|
||||
"design_edited" \
|
||||
"$design_title" \
|
||||
"Edit type: $edit_type"
|
||||
}
|
||||
|
||||
# Template used
|
||||
gl_canva_template_used() {
|
||||
local template_name="$1"
|
||||
local design_title="$2"
|
||||
local category="${3:-general}"
|
||||
|
||||
gl_log "📥🖼️👉📌" \
|
||||
"template_used" \
|
||||
"$template_name" \
|
||||
"For: $design_title, Category: $category"
|
||||
}
|
||||
|
||||
# Design published
|
||||
gl_canva_design_published() {
|
||||
local design_title="$1"
|
||||
local platform="${2:-web}" # web, instagram, facebook, etc.
|
||||
local url="${3:-}"
|
||||
|
||||
local platform_emoji=""
|
||||
case "$platform" in
|
||||
web) platform_emoji="🌐" ;;
|
||||
instagram) platform_emoji="📱" ;;
|
||||
facebook) platform_emoji="📘" ;;
|
||||
twitter) platform_emoji="🐦" ;;
|
||||
linkedin) platform_emoji="💼" ;;
|
||||
*) platform_emoji="🎨" ;;
|
||||
esac
|
||||
|
||||
gl_log "🎉${platform_emoji}🎢🌍" \
|
||||
"design_published" \
|
||||
"$design_title" \
|
||||
"Platform: $platform, URL: $url"
|
||||
}
|
||||
|
||||
# Design deleted
|
||||
gl_canva_design_deleted() {
|
||||
local design_title="$1"
|
||||
local reason="${2:-user_action}"
|
||||
|
||||
gl_log "🗑️🎨👉📌" \
|
||||
"design_deleted" \
|
||||
"$design_title" \
|
||||
"Reason: $reason"
|
||||
}
|
||||
```
|
||||
|
||||
### Asset Operations
|
||||
|
||||
```bash
|
||||
# Asset uploaded
|
||||
gl_canva_asset_uploaded() {
|
||||
local asset_type="$1" # image, video, audio
|
||||
local asset_name="$2"
|
||||
local size="${3:-unknown}"
|
||||
|
||||
local asset_emoji=""
|
||||
case "$asset_type" in
|
||||
image|photo) asset_emoji="🖼️" ;;
|
||||
video|clip) asset_emoji="🎬" ;;
|
||||
audio|sound) asset_emoji="🎵" ;;
|
||||
*) asset_emoji="📤" ;;
|
||||
esac
|
||||
|
||||
gl_log "📤${asset_emoji}👉📌" \
|
||||
"asset_uploaded" \
|
||||
"$asset_name" \
|
||||
"Type: $asset_type, Size: $size"
|
||||
}
|
||||
|
||||
# Asset replaced
|
||||
gl_canva_asset_replaced() {
|
||||
local old_asset="$1"
|
||||
local new_asset="$2"
|
||||
local design_title="$3"
|
||||
|
||||
gl_log "🔄🖼️👉📌" \
|
||||
"asset_replaced" \
|
||||
"$design_title" \
|
||||
"$old_asset → $new_asset"
|
||||
}
|
||||
|
||||
# Brand kit asset used
|
||||
gl_canva_brand_asset_used() {
|
||||
local asset_name="$1"
|
||||
local asset_type="$2" # logo, color, font
|
||||
local design_title="$3"
|
||||
|
||||
local brand_emoji=""
|
||||
case "$asset_type" in
|
||||
logo) brand_emoji="🏷️" ;;
|
||||
color) brand_emoji="🎨" ;;
|
||||
font) brand_emoji="🔤" ;;
|
||||
*) brand_emoji="🎯" ;;
|
||||
esac
|
||||
|
||||
gl_log "${brand_emoji}🎨👉📌" \
|
||||
"brand_asset_used" \
|
||||
"$asset_name" \
|
||||
"In: $design_title, Type: $asset_type"
|
||||
}
|
||||
```
|
||||
|
||||
### Export Operations
|
||||
|
||||
```bash
|
||||
# Export started
|
||||
gl_canva_export_started() {
|
||||
local design_title="$1"
|
||||
local format="$2" # PNG, JPG, PDF, MP4, GIF, SVG
|
||||
local quality="${3:-standard}"
|
||||
|
||||
gl_log "⏳📦👉📌" \
|
||||
"export_started" \
|
||||
"$design_title" \
|
||||
"Format: $format, Quality: $quality"
|
||||
}
|
||||
|
||||
# Export completed
|
||||
gl_canva_export_completed() {
|
||||
local design_title="$1"
|
||||
local format="$2"
|
||||
local file_size="$3"
|
||||
local duration="${4:-unknown}"
|
||||
|
||||
local format_emoji=""
|
||||
case "$format" in
|
||||
PNG|JPG|JPEG) format_emoji="🖼️" ;;
|
||||
PDF) format_emoji="📄" ;;
|
||||
MP4|MOV) format_emoji="🎬" ;;
|
||||
GIF) format_emoji="🎞️" ;;
|
||||
SVG) format_emoji="🎨" ;;
|
||||
*) format_emoji="📦" ;;
|
||||
esac
|
||||
|
||||
gl_log "✅${format_emoji}🎢📌" \
|
||||
"export_completed" \
|
||||
"$design_title" \
|
||||
"Format: $format, Size: $file_size, Duration: $duration"
|
||||
}
|
||||
|
||||
# Export failed
|
||||
gl_canva_export_failed() {
|
||||
local design_title="$1"
|
||||
local format="$2"
|
||||
local error="${3:-unknown error}"
|
||||
|
||||
gl_log "❌📦👉🔥" \
|
||||
"export_failed" \
|
||||
"$design_title" \
|
||||
"Format: $format, Error: $error"
|
||||
}
|
||||
```
|
||||
|
||||
### Collaboration Operations
|
||||
|
||||
```bash
|
||||
# Comment added
|
||||
gl_canva_comment_added() {
|
||||
local design_title="$1"
|
||||
local commenter="$2"
|
||||
local preview="${3:0:50}"
|
||||
|
||||
gl_log "💬🎨👉⭐" \
|
||||
"comment_added" \
|
||||
"$design_title" \
|
||||
"$commenter: $preview..."
|
||||
}
|
||||
|
||||
# Design shared
|
||||
gl_canva_design_shared() {
|
||||
local design_title="$1"
|
||||
local shared_with="$2"
|
||||
local permission="${3:-view}" # view, edit, comment
|
||||
|
||||
gl_log "👥🎨👉📌" \
|
||||
"design_shared" \
|
||||
"$design_title" \
|
||||
"With: $shared_with, Permission: $permission"
|
||||
}
|
||||
|
||||
# Approval requested
|
||||
gl_canva_approval_requested() {
|
||||
local design_title="$1"
|
||||
local requester="$2"
|
||||
local approvers="$3"
|
||||
|
||||
gl_log "🔔✅👉⭐" \
|
||||
"approval_requested" \
|
||||
"$design_title" \
|
||||
"By: $requester, Approvers: $approvers"
|
||||
}
|
||||
|
||||
# Approval granted
|
||||
gl_canva_approval_granted() {
|
||||
local design_title="$1"
|
||||
local approver="$2"
|
||||
local feedback="${3:-approved}"
|
||||
|
||||
gl_log "✅👍🎢📌" \
|
||||
"approval_granted" \
|
||||
"$design_title" \
|
||||
"By: $approver, Feedback: $feedback"
|
||||
}
|
||||
|
||||
# Approval rejected
|
||||
gl_canva_approval_rejected() {
|
||||
local design_title="$1"
|
||||
local approver="$2"
|
||||
local reason="${3:-needs changes}"
|
||||
|
||||
gl_log "❌👎👉🔥" \
|
||||
"approval_rejected" \
|
||||
"$design_title" \
|
||||
"By: $approver, Reason: $reason"
|
||||
}
|
||||
```
|
||||
|
||||
### Folder Operations
|
||||
|
||||
```bash
|
||||
# Folder created
|
||||
gl_canva_folder_created() {
|
||||
local folder_name="$1"
|
||||
local parent="${2:-root}"
|
||||
|
||||
gl_log "📁➕👉📌" \
|
||||
"folder_created" \
|
||||
"$folder_name" \
|
||||
"Parent: $parent"
|
||||
}
|
||||
|
||||
# Design moved to folder
|
||||
gl_canva_design_moved() {
|
||||
local design_title="$1"
|
||||
local from_folder="$2"
|
||||
local to_folder="$3"
|
||||
|
||||
gl_log "📁🔄👉📌" \
|
||||
"design_moved" \
|
||||
"$design_title" \
|
||||
"$from_folder → $to_folder"
|
||||
}
|
||||
```
|
||||
|
||||
### Brand Operations
|
||||
|
||||
```bash
|
||||
# Brand kit updated
|
||||
gl_canva_brand_kit_updated() {
|
||||
local brand_name="$1"
|
||||
local update_type="$2" # logo, colors, fonts, templates
|
||||
local details="$3"
|
||||
|
||||
local update_emoji=""
|
||||
case "$update_type" in
|
||||
logo) update_emoji="🏷️" ;;
|
||||
colors) update_emoji="🎨" ;;
|
||||
fonts) update_emoji="🔤" ;;
|
||||
templates) update_emoji="🖼️" ;;
|
||||
*) update_emoji="🎯" ;;
|
||||
esac
|
||||
|
||||
gl_log "${update_emoji}🎯🎢📌" \
|
||||
"brand_kit_updated" \
|
||||
"$brand_name" \
|
||||
"Updated: $update_type - $details"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Complete Canva Workflow
|
||||
|
||||
### Scenario: Social media post creation and publishing
|
||||
|
||||
```bash
|
||||
# 1. Design created from template
|
||||
gl_canva_template_used "Instagram Story - Tech Product" "BlackRoad OS Launch" "social_media"
|
||||
# [📥🖼️👉📌] template_used: Instagram Story - Tech Product — For: BlackRoad OS Launch, Category: social_media
|
||||
|
||||
gl_canva_design_created "BlackRoad OS Launch" "instagram" "alexa"
|
||||
# [⚡📱👉📌] design_created: BlackRoad OS Launch — Type: instagram, Creator: alexa
|
||||
|
||||
# 2. Brand assets used
|
||||
gl_canva_brand_asset_used "BlackRoad Logo" "logo" "BlackRoad OS Launch"
|
||||
# [🏷️🎨👉📌] brand_asset_used: BlackRoad Logo — In: BlackRoad OS Launch, Type: logo
|
||||
|
||||
gl_canva_brand_asset_used "Brand Purple" "color" "BlackRoad OS Launch"
|
||||
# [🎨🎨👉📌] brand_asset_used: Brand Purple — In: BlackRoad OS Launch, Type: color
|
||||
|
||||
# 3. Custom image uploaded
|
||||
gl_canva_asset_uploaded "image" "product-screenshot.png" "2.4MB"
|
||||
# [📤🖼️👉📌] asset_uploaded: product-screenshot.png — Type: image, Size: 2.4MB
|
||||
|
||||
# 4. Design edited
|
||||
gl_canva_design_edited "BlackRoad OS Launch" "content"
|
||||
# [✏️🎨👉📌] design_edited: BlackRoad OS Launch — Edit type: content
|
||||
|
||||
gl_canva_design_edited "BlackRoad OS Launch" "text"
|
||||
# [📝🎨👉📌] design_edited: BlackRoad OS Launch — Edit type: text
|
||||
|
||||
# 5. Comment from team member
|
||||
gl_canva_comment_added "BlackRoad OS Launch" "designer" "Love the color scheme! Maybe adjust the headline size?"
|
||||
# [💬🎨👉⭐] comment_added: BlackRoad OS Launch — designer: Love the color scheme! Maybe adjust the headline size?...
|
||||
|
||||
# 6. Approval requested
|
||||
gl_canva_approval_requested "BlackRoad OS Launch" "alexa" "marketing-team"
|
||||
# [🔔✅👉⭐] approval_requested: BlackRoad OS Launch — By: alexa, Approvers: marketing-team
|
||||
|
||||
# 7. Approval granted
|
||||
gl_canva_approval_granted "BlackRoad OS Launch" "marketing-lead" "Looks great! Ready to post"
|
||||
# [✅👍🎢📌] approval_granted: BlackRoad OS Launch — By: marketing-lead, Feedback: Looks great! Ready to post
|
||||
|
||||
# 8. Export as PNG
|
||||
gl_canva_export_started "BlackRoad OS Launch" "PNG" "high"
|
||||
# [⏳📦👉📌] export_started: BlackRoad OS Launch — Format: PNG, Quality: high
|
||||
|
||||
gl_canva_export_completed "BlackRoad OS Launch" "PNG" "4.2MB" "2.1s"
|
||||
# [✅🖼️🎢📌] export_completed: BlackRoad OS Launch — Format: PNG, Size: 4.2MB, Duration: 2.1s
|
||||
|
||||
# 9. Published to Instagram
|
||||
gl_canva_design_published "BlackRoad OS Launch" "instagram" "https://instagram.com/p/abc123"
|
||||
# [🎉📱🎢🌍] design_published: BlackRoad OS Launch — Platform: instagram, URL: https://instagram.com/p/abc123
|
||||
```
|
||||
|
||||
### Scenario: Presentation deck creation
|
||||
|
||||
```bash
|
||||
# 1. New presentation created
|
||||
gl_canva_design_created "Q4 Business Review" "presentation" "alexa"
|
||||
# [⚡📄👉📌] design_created: Q4 Business Review — Type: presentation, Creator: alexa
|
||||
|
||||
# 2. Chart added for data visualization
|
||||
gl_canva_asset_uploaded "chart" "revenue-chart.svg" "124KB"
|
||||
# [📤📊👉📌] asset_uploaded: revenue-chart.svg — Type: chart, Size: 124KB
|
||||
|
||||
# 3. Multiple edits
|
||||
gl_canva_design_edited "Q4 Business Review" "layout"
|
||||
# [⊞🎨👉📌] design_edited: Q4 Business Review — Edit type: layout
|
||||
|
||||
gl_canva_design_edited "Q4 Business Review" "content"
|
||||
# [✏️🎨👉📌] design_edited: Q4 Business Review — Edit type: content
|
||||
|
||||
# 4. Shared with team for collaboration
|
||||
gl_canva_design_shared "Q4 Business Review" "exec-team" "edit"
|
||||
# [👥🎨👉📌] design_shared: Q4 Business Review — With: exec-team, Permission: edit
|
||||
|
||||
# 5. Team adds comments
|
||||
gl_canva_comment_added "Q4 Business Review" "cfo" "Update slide 5 with latest metrics"
|
||||
# [💬🎨👉⭐] comment_added: Q4 Business Review — cfo: Update slide 5 with latest metrics...
|
||||
|
||||
# 6. Export as PDF
|
||||
gl_canva_export_started "Q4 Business Review" "PDF" "standard"
|
||||
# [⏳📦👉📌] export_started: Q4 Business Review — Format: PDF, Quality: standard
|
||||
|
||||
gl_canva_export_completed "Q4 Business Review" "PDF" "8.7MB" "4.5s"
|
||||
# [✅📄🎢📌] export_completed: Q4 Business Review — Format: PDF, Size: 8.7MB, Duration: 4.5s
|
||||
```
|
||||
|
||||
### Scenario: Brand kit update
|
||||
|
||||
```bash
|
||||
# 1. Brand kit updated with new logo
|
||||
gl_canva_brand_kit_updated "BlackRoad OS" "logo" "Added vertical logo variant"
|
||||
# [🏷️🎯🎢📌] brand_kit_updated: BlackRoad OS — Updated: logo - Added vertical logo variant
|
||||
|
||||
# 2. Brand colors updated
|
||||
gl_canva_brand_kit_updated "BlackRoad OS" "colors" "Added accent gradient: #FF9D00 to #FF0066"
|
||||
# [🎨🎯🎢📌] brand_kit_updated: BlackRoad OS — Updated: colors - Added accent gradient: #FF9D00 to #FF0066
|
||||
|
||||
# 3. Brand fonts updated
|
||||
gl_canva_brand_kit_updated "BlackRoad OS" "fonts" "Added Inter for body text"
|
||||
# [🔤🎯🎢📌] brand_kit_updated: BlackRoad OS — Updated: fonts - Added Inter for body text
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Canva Integration Details
|
||||
|
||||
**API Version:** v1
|
||||
**API Endpoint:** https://api.canva.com/rest/v1/
|
||||
**OAuth Scopes:** design:content:read, design:content:write, asset:read, asset:write, folder:read, folder:write
|
||||
|
||||
### Recommended Folder Structure:
|
||||
|
||||
1. **Social Media** (📱)
|
||||
- Instagram Posts/Stories
|
||||
- Facebook Posts
|
||||
- Twitter/X Posts
|
||||
- LinkedIn Posts
|
||||
|
||||
2. **Marketing** (📣)
|
||||
- Ads (Google, Facebook, Instagram)
|
||||
- Email Newsletters
|
||||
- Landing Pages
|
||||
- Banners
|
||||
|
||||
3. **Brand Assets** (🎯)
|
||||
- Logos
|
||||
- Brand Guidelines
|
||||
- Templates
|
||||
- Icons
|
||||
|
||||
4. **Documents** (📄)
|
||||
- Presentations
|
||||
- Reports
|
||||
- Proposals
|
||||
- White Papers
|
||||
|
||||
5. **Video** (🎬)
|
||||
- Animations
|
||||
- Explainer Videos
|
||||
- Social Ads
|
||||
- Product Demos
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Mapped Canva events to GreenLight 27-step workflow
|
||||
- [x] Created design-type-to-domain mappings
|
||||
- [x] Defined asset types as GreenLight tags
|
||||
- [x] Extended NATS subjects for Canva events
|
||||
- [x] Built 15+ Canva-specific templates
|
||||
- [x] Design lifecycle tracking
|
||||
- [x] Asset upload/replace operations
|
||||
- [x] Export operations (PNG, PDF, MP4, SVG)
|
||||
- [x] Collaboration and approval workflows
|
||||
- [x] Comment tracking
|
||||
- [x] Folder organization
|
||||
- [x] Brand kit management
|
||||
- [x] Template usage tracking
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** Canva Design Workflow Integration
|
||||
**Version:** 2.0.0-canva
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
|
||||
@@ -0,0 +1,311 @@
|
||||
# 🛣️ GreenLight CI/CD & Infrastructure Extension
|
||||
|
||||
**Extension to GreenLight Emoji Dictionary for GitHub Workflows + Cloudflare**
|
||||
|
||||
---
|
||||
|
||||
## 🔄 CI/CD Pipeline States
|
||||
|
||||
Add these to the **Lifecycle States** category:
|
||||
|
||||
| Emoji | State | Code | Trinary | Description |
|
||||
|-------|-------|------|---------|-------------|
|
||||
| ⚡ | TRIGGERED | `triggered` | 0 | Workflow started / Event received |
|
||||
| 🔍 | LINTING | `linting` | +1 | Code quality checks running |
|
||||
| 🧪 | TESTING | `testing` | +1 | Tests executing |
|
||||
| 🏗️ | BUILDING | `building` | +1 | Build in progress |
|
||||
| 📦 | PACKAGING | `packaging` | +1 | Creating artifacts |
|
||||
| 🚢 | DEPLOYING | `deploying` | +1 | Deployment in progress |
|
||||
| ✅ | PASSED | `passed` | +1 | Pipeline succeeded |
|
||||
| ❌ | FAILED | `failed` | -1 | Pipeline failed |
|
||||
| ⏭️ | SKIPPED | `skipped` | 0 | Step skipped |
|
||||
| 🔁 | RETRYING | `retrying` | 0 | Retry attempt |
|
||||
|
||||
---
|
||||
|
||||
## ☁️ Cloudflare Resource Types
|
||||
|
||||
Add these to **Infrastructure Layer** category:
|
||||
|
||||
| Emoji | Resource | Code | Description |
|
||||
|-------|----------|------|-------------|
|
||||
| ⚙️ | WORKER | `worker` | Cloudflare Worker |
|
||||
| 💾 | D1 | `d1` | D1 Database |
|
||||
| 🗂️ | KV | `kv` | KV Namespace |
|
||||
| 📦 | R2 | `r2` | R2 Bucket |
|
||||
| 🌐 | PAGES | `pages` | Cloudflare Pages |
|
||||
| 🔒 | DO | `do` | Durable Object |
|
||||
| 🌍 | ZONE | `zone` | DNS Zone |
|
||||
| 🔀 | TUNNEL | `tunnel` | Cloudflare Tunnel |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Worker Categories
|
||||
|
||||
Add to **Domain Tags**:
|
||||
|
||||
| Emoji | Category | Code | Description |
|
||||
|-------|----------|------|-------------|
|
||||
| 🌐 | ROUTING | `routing` | Gateway, router, subdomain workers |
|
||||
| 🔐 | AUTH | `auth` | Authentication, identity, cipher |
|
||||
| 💰 | BILLING | `billing` | Payments, Stripe, checkout |
|
||||
| 🌀 | AGENTS | `agents` | AI agents, Lucidia, Cece |
|
||||
| 💾 | STORAGE | `storage` | D1, KV, R2 management |
|
||||
| 📊 | OBSERVABILITY | `observability` | Logs, metrics, telemetry |
|
||||
| 🌐 | MESH | `mesh` | Service mesh, networking |
|
||||
| 🛠️ | TOOLS | `tools` | CLI, console, dev tools |
|
||||
| 📦 | VERTICAL | `vertical` | Vertical-specific workers |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 GitHub Workflow Steps
|
||||
|
||||
Map to existing GreenLight phases with specific codes:
|
||||
|
||||
| Emoji | Step | Code | Phase | Description |
|
||||
|-------|------|------|-------|-------------|
|
||||
| 🏷️ | DETECT | `detect` | 🌱 Discovery | Detect changed files |
|
||||
| 🔍 | LINT | `lint` | 🔨 Implementation | Linting & formatting |
|
||||
| 🧪 | TEST | `test` | 🧪 Testing | Unit/integration tests |
|
||||
| 🏗️ | BUILD | `build` | 🔨 Implementation | Compile & bundle |
|
||||
| 📦 | PACKAGE | `package` | 📦 Packaging | Create release artifacts |
|
||||
| 🚀 | DEPLOY | `deploy` | 🚀 Deployment | Deploy to environment |
|
||||
| 📣 | ANNOUNCE | `announce` | 📣 Announcement | Notify systems |
|
||||
| 🔒 | SECURITY | `security` | 🔒 Security | CodeQL, vulnerability scan |
|
||||
| 🤖 | DEPENDABOT | `dependabot` | 🔧 Maintenance | Dependency updates |
|
||||
|
||||
---
|
||||
|
||||
## 🌍 Deployment Environments
|
||||
|
||||
Add to **Device/Location** category:
|
||||
|
||||
| Emoji | Environment | Code | Description |
|
||||
|-------|-------------|------|-------------|
|
||||
| 🧪 | STAGING | `staging` | Staging environment |
|
||||
| 🚀 | PRODUCTION | `production` | Production environment |
|
||||
| 🧑💻 | DEVELOPMENT | `development` | Dev environment |
|
||||
| 🔬 | PREVIEW | `preview` | Preview deployment |
|
||||
| 🌐 | EDGE | `edge` | Cloudflare edge |
|
||||
| 🏠 | LOCAL | `local` | Local development |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for CI/CD
|
||||
|
||||
### GitHub Workflow Events
|
||||
|
||||
```
|
||||
⚡👉🔧📌 = Triggered micro infra workflow, medium priority
|
||||
🧪🎢🛣️⭐ = Testing macro platform workflow, high priority
|
||||
✅👉🌐🔥 = Passed micro edge deployment, fire priority
|
||||
❌🎢🔐🚨 = Failed macro auth workflow, urgent
|
||||
🚀🌐🛣️⭐ = Deploying planetary platform, high priority
|
||||
```
|
||||
|
||||
### Cloudflare Deployments
|
||||
|
||||
```
|
||||
🚀⚙️🌐✅ = Deployed worker to edge, done
|
||||
🏗️💾🎢🔥 = Building D1 macro project, fire priority
|
||||
✅🗂️👉📌 = KV namespace deployed micro, medium priority
|
||||
🔧📦👉⭐ = Configuring R2 bucket micro, high priority
|
||||
```
|
||||
|
||||
### Combined Workflow + Deployment
|
||||
|
||||
```
|
||||
[⚡🔍🧪🏗️📦🚀📣] = Full CI/CD pipeline
|
||||
[🔍✅] [🧪✅] [🏗️✅] [🚀⚙️🌐] = Lint ✓ Test ✓ Build ✓ Deploy to Worker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (Extended)
|
||||
|
||||
### CI/CD Events
|
||||
```
|
||||
greenlight.triggered.micro.infra.{repo}
|
||||
greenlight.testing.macro.platform.{repo}
|
||||
greenlight.passed.micro.edge.{repo}
|
||||
greenlight.failed.macro.auth.{repo}
|
||||
greenlight.deployed.worker.{service}.{env}
|
||||
```
|
||||
|
||||
### Cloudflare Events
|
||||
```
|
||||
greenlight.deployed.worker.{worker-name}.{env}
|
||||
greenlight.configured.d1.{database-name}
|
||||
greenlight.created.kv.{namespace-name}
|
||||
greenlight.uploaded.r2.{bucket-name}
|
||||
greenlight.published.pages.{project-name}
|
||||
```
|
||||
|
||||
### Workflow Progression
|
||||
```
|
||||
greenlight.detect.done.{repo}
|
||||
greenlight.lint.wip.{repo}
|
||||
greenlight.test.done.{repo}
|
||||
greenlight.build.wip.{repo}
|
||||
greenlight.deploy.done.{worker}.{env}
|
||||
greenlight.announce.done.{repo}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Extended Memory Templates
|
||||
|
||||
### Workflow Events
|
||||
|
||||
```bash
|
||||
# Workflow triggered
|
||||
gl_workflow_trigger() {
|
||||
local repo="$1"
|
||||
local trigger="$2" # push, pr, manual
|
||||
gl_log "⚡👉🔧📌" "triggered" "$repo" "Workflow triggered by: $trigger"
|
||||
}
|
||||
|
||||
# Workflow step complete
|
||||
gl_workflow_step() {
|
||||
local repo="$1"
|
||||
local step="$2" # lint, test, build, deploy
|
||||
local status="$3" # passed, failed
|
||||
|
||||
local step_emoji=""
|
||||
case "$step" in
|
||||
lint) step_emoji="🔍" ;;
|
||||
test) step_emoji="🧪" ;;
|
||||
build) step_emoji="🏗️" ;;
|
||||
deploy) step_emoji="🚀" ;;
|
||||
esac
|
||||
|
||||
local status_emoji="✅"
|
||||
[ "$status" = "failed" ] && status_emoji="❌"
|
||||
|
||||
gl_log "${step_emoji}${status_emoji}👉🔧" "$step" "$repo" "Step $step $status"
|
||||
}
|
||||
|
||||
# Workflow complete
|
||||
gl_workflow_done() {
|
||||
local repo="$1"
|
||||
local status="$2" # passed, failed
|
||||
local duration="$3"
|
||||
|
||||
local status_emoji="✅"
|
||||
[ "$status" = "failed" ] && status_emoji="❌"
|
||||
|
||||
gl_log "${status_emoji}🎢🔧📣" "workflow_${status}" "$repo" "Pipeline $status in $duration"
|
||||
}
|
||||
```
|
||||
|
||||
### Cloudflare Deployments
|
||||
|
||||
```bash
|
||||
# Worker deployment
|
||||
gl_worker_deploy() {
|
||||
local worker="$1"
|
||||
local env="$2" # staging, production
|
||||
local version="$3"
|
||||
|
||||
local env_emoji="🧪"
|
||||
[ "$env" = "production" ] && env_emoji="🚀"
|
||||
|
||||
gl_log "${env_emoji}⚙️🌐✅" "deployed" "$worker" "Worker deployed to $env v$version"
|
||||
}
|
||||
|
||||
# D1 migration
|
||||
gl_d1_migrate() {
|
||||
local database="$1"
|
||||
local migration="$2"
|
||||
|
||||
gl_log "🔄💾👉📌" "migrated" "$database" "Applied migration: $migration"
|
||||
}
|
||||
|
||||
# KV namespace update
|
||||
gl_kv_update() {
|
||||
local namespace="$1"
|
||||
local operation="$2" # created, updated, deleted
|
||||
|
||||
gl_log "✅🗂️👉📌" "$operation" "$namespace" "KV namespace $operation"
|
||||
}
|
||||
|
||||
# R2 bucket operation
|
||||
gl_r2_operation() {
|
||||
local bucket="$1"
|
||||
local operation="$2"
|
||||
local size="$3"
|
||||
|
||||
gl_log "📦👉💾" "$operation" "$bucket" "R2 $operation ($size)"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Full Workflow
|
||||
|
||||
### Scenario: Deploy blackroad-api worker
|
||||
|
||||
```bash
|
||||
# 1. Workflow triggered
|
||||
gl_workflow_trigger "blackroad-api" "push to main"
|
||||
# [⚡👉🔧📌] triggered: blackroad-api
|
||||
|
||||
# 2. Lint step
|
||||
gl_workflow_step "blackroad-api" "lint" "passed"
|
||||
# [🔍✅👉🔧] lint: blackroad-api — Step lint passed
|
||||
|
||||
# 3. Test step
|
||||
gl_workflow_step "blackroad-api" "test" "passed"
|
||||
# [🧪✅👉🔧] test: blackroad-api — Step test passed
|
||||
|
||||
# 4. Build step
|
||||
gl_workflow_step "blackroad-api" "build" "passed"
|
||||
# [🏗️✅👉🔧] build: blackroad-api — Step build passed
|
||||
|
||||
# 5. Deploy step
|
||||
gl_workflow_step "blackroad-api" "deploy" "passed"
|
||||
# [🚀✅👉🔧] deploy: blackroad-api — Step deploy passed
|
||||
|
||||
# 6. Worker deployed
|
||||
gl_worker_deploy "blackroad-api" "production" "1.2.3"
|
||||
# [🚀⚙️🌐✅] deployed: blackroad-api — Worker deployed to production v1.2.3
|
||||
|
||||
# 7. Workflow complete
|
||||
gl_workflow_done "blackroad-api" "passed" "3m 42s"
|
||||
# [✅🎢🔧📣] workflow_passed: blackroad-api — Pipeline passed in 3m 42s
|
||||
```
|
||||
|
||||
### Memory Output:
|
||||
```
|
||||
[⚡👉🔧📌] triggered: blackroad-api — Workflow triggered by: push to main
|
||||
[🔍✅👉🔧] lint: blackroad-api — Step lint passed
|
||||
[🧪✅👉🔧] test: blackroad-api — Step test passed
|
||||
[🏗️✅👉🔧] build: blackroad-api — Step build passed
|
||||
[🚀✅👉🔧] deploy: blackroad-api — Step deploy passed
|
||||
[🚀⚙️🌐✅] deployed: blackroad-api — Worker deployed to production v1.2.3
|
||||
[✅🎢🔧📣] workflow_passed: blackroad-api — Pipeline passed in 3m 42s
|
||||
```
|
||||
|
||||
Every Claude instantly sees the full deployment lifecycle! 🎉
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Extended lifecycle states for CI/CD
|
||||
- [x] Added Cloudflare resource types
|
||||
- [x] Created worker category tags
|
||||
- [x] Mapped GitHub workflow steps
|
||||
- [x] Defined deployment environments
|
||||
- [x] Created composite patterns
|
||||
- [x] Extended NATS subjects
|
||||
- [x] Built workflow templates
|
||||
- [x] Built Cloudflare templates
|
||||
- [x] Provided full integration example
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** GitHub Workflows + Cloudflare Infrastructure
|
||||
**Version:** 2.0.0-cicd
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
321
.trinity/greenlight/docs/GREENLIGHT_CLAUDE_QUICK_REFERENCE.md
Normal file
321
.trinity/greenlight/docs/GREENLIGHT_CLAUDE_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 🛣️ GreenLight Quick Reference for Claude Agents
|
||||
|
||||
**One-page cheat sheet for using GreenLight in BlackRoad memory system**
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# Load GreenLight templates
|
||||
source ~/memory-greenlight-templates.sh
|
||||
|
||||
# Announce work
|
||||
gl_announce "claude-yourname" "Project Name" "1) Task 2) Task 3) Task" "Big Goal" "🎢" "🔧" "⭐"
|
||||
|
||||
# Update progress
|
||||
gl_progress "claude-yourname" "What you finished" "What's next" "👉" "🔧"
|
||||
|
||||
# Log deployment
|
||||
gl_deploy "service-name.blackroad.io" "https://url" "Details" "👉" "🔧"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Common GreenLight Patterns
|
||||
|
||||
### For Announcements
|
||||
```
|
||||
🎯🎢🛣️🔥 = Targeted macro platform project, fire priority
|
||||
🎯👉🌀⭐ = Targeted micro AI task, high priority
|
||||
🎯🎢🔧📌 = Targeted macro infra project, medium priority
|
||||
```
|
||||
|
||||
### For Progress
|
||||
```
|
||||
✅👉🛣️ = Done micro platform task
|
||||
✅🎢🔧 = Done macro infra project
|
||||
🚧👉🌀 = WIP micro AI task
|
||||
```
|
||||
|
||||
### For Coordination
|
||||
```
|
||||
🤝⭐💬 = Coordinate high priority
|
||||
🤝📌💬 = Coordinate medium priority
|
||||
```
|
||||
|
||||
### For Blocking
|
||||
```
|
||||
🔒🔥⛔ = Blocked fire priority
|
||||
🔒⭐⛔ = Blocked high priority
|
||||
```
|
||||
|
||||
### For Deployment
|
||||
```
|
||||
🚀👉🔧✅ = Deployed micro infra, done
|
||||
🚀🎢🛣️✅ = Deployed macro platform, done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Phase Markers
|
||||
|
||||
Use these for project phases:
|
||||
|
||||
| Emoji | Phase | When to Use |
|
||||
|-------|-------|-------------|
|
||||
| 🌱 | DISCOVERY | Researching, exploring, learning |
|
||||
| 📐 | PLANNING | Designing, architecting, strategy |
|
||||
| 🔨 | IMPLEMENTATION | Building, coding, executing |
|
||||
| 🧪 | TESTING | QA, validation, verification |
|
||||
| 🚀 | DEPLOYMENT | Shipping, launching, releasing |
|
||||
| 📊 | MONITORING | Observing, measuring, optimizing |
|
||||
| 🔄 | ITERATION | Improving, refining, evolving |
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
gl_phase_start "planning" "API Service" "Designing endpoints" "🎢"
|
||||
gl_phase_done "implementation" "Frontend" "All components built" "🎢"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Scale Indicators
|
||||
|
||||
| Emoji | Scale | Use For |
|
||||
|-------|-------|---------|
|
||||
| 👉 | MICRO | Single task, commit, bug fix |
|
||||
| 🎢 | MACRO | Project, sprint, feature |
|
||||
| 🌐 | PLANETARY | System, infrastructure, org-wide |
|
||||
| 🌌 | UNIVERSAL | Cross-org, federation, external |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Domain Tags
|
||||
|
||||
**Most Common:**
|
||||
|
||||
| Emoji | Domain | Use For |
|
||||
|-------|--------|---------|
|
||||
| 🛣️ | PLATFORM | Core BlackRoad OS |
|
||||
| 🌀 | AI | Lucidia, agents, ML |
|
||||
| ⛓️ | CHAIN | RoadChain, blockchain |
|
||||
| 💎 | COIN | RoadCoin, tokens |
|
||||
| 🔧 | INFRA | Infrastructure, DevOps |
|
||||
| 🎨 | CREATIVE | Design, art |
|
||||
| 📊 | DATA | Analytics, BI |
|
||||
| 🔒 | SECURITY | Auth, encryption |
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Priority Levels
|
||||
|
||||
| Emoji | Priority | When |
|
||||
|-------|----------|------|
|
||||
| 🔥 | FIRE (P0) | DROP EVERYTHING |
|
||||
| 🚨 | URGENT (P1) | Today |
|
||||
| ⭐ | HIGH (P2) | This week |
|
||||
| 📌 | MEDIUM (P3) | This sprint |
|
||||
| 💤 | LOW (P4) | Someday |
|
||||
| 🧊 | ICE (P5) | Frozen |
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Agent Identities
|
||||
|
||||
| Emoji | Agent | Role |
|
||||
|-------|-------|------|
|
||||
| 🌸 | CECE | Primary reasoning (Claude) |
|
||||
| 🔮 | LUCIDIA | Recursive AI |
|
||||
| 🐇 | ALICE | Edge agent (Pi) |
|
||||
| 🎸 | SILAS | Creative (Grok) |
|
||||
| 🌙 | ARIA | Multimodal (Gemini) |
|
||||
| 🎩 | CADDY | General (GPT) |
|
||||
| 🦊 | EDGE | Privacy (Ollama) |
|
||||
| 🐙 | SWARM | Agent collective |
|
||||
|
||||
---
|
||||
|
||||
## 📝 Template Cheat Sheet
|
||||
|
||||
### Announce Work
|
||||
```bash
|
||||
gl_announce "agent-name" "project" "tasks" "goal" "scale" "domain" "priority"
|
||||
```
|
||||
|
||||
### Progress Update
|
||||
```bash
|
||||
gl_progress "agent-name" "completed" "next" "scale" "domain"
|
||||
```
|
||||
|
||||
### Coordinate
|
||||
```bash
|
||||
gl_coordinate "from-agent" "to-agent" "message" "priority"
|
||||
```
|
||||
|
||||
### Blocked
|
||||
```bash
|
||||
gl_blocked "agent-name" "reason" "needs" "priority"
|
||||
```
|
||||
|
||||
### Deploy
|
||||
```bash
|
||||
gl_deploy "service" "url" "details" "scale" "domain"
|
||||
```
|
||||
|
||||
### Decision
|
||||
```bash
|
||||
gl_decide "topic" "decision" "rationale" "scale"
|
||||
```
|
||||
|
||||
### Bug
|
||||
```bash
|
||||
gl_bug "component" "description" "priority" "scale"
|
||||
```
|
||||
|
||||
### Feature
|
||||
```bash
|
||||
gl_feature "name" "description" "effort" "priority"
|
||||
```
|
||||
|
||||
### Phase Start
|
||||
```bash
|
||||
gl_phase_start "phase" "project" "details" "scale"
|
||||
```
|
||||
|
||||
### Phase Done
|
||||
```bash
|
||||
gl_phase_done "phase" "project" "summary" "scale"
|
||||
```
|
||||
|
||||
### WIP
|
||||
```bash
|
||||
gl_wip "task" "status" "agent" "scale"
|
||||
```
|
||||
|
||||
### Dependency
|
||||
```bash
|
||||
gl_depends "task" "depends-on" "reason"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Real Examples
|
||||
|
||||
### Starting New Work
|
||||
```bash
|
||||
source ~/memory-greenlight-templates.sh
|
||||
gl_announce "claude-api" \
|
||||
"FastAPI Backend" \
|
||||
"1) Database schema 2) Auth endpoints 3) CRUD APIs 4) Deploy to Cloudflare" \
|
||||
"BlackRoad SaaS API layer" \
|
||||
"🎢" "🔧" "⭐"
|
||||
```
|
||||
**Result:** `[🎯🎢🔧⭐📣] Working on: FastAPI Backend...`
|
||||
|
||||
### Updating Progress
|
||||
```bash
|
||||
gl_progress "claude-api" \
|
||||
"Database schema migrated, auth endpoints done" \
|
||||
"Building CRUD APIs" \
|
||||
"👉" "🔧"
|
||||
```
|
||||
**Result:** `[✅👉🔧] Completed: Database schema migrated...`
|
||||
|
||||
### Coordinating
|
||||
```bash
|
||||
gl_coordinate "claude-frontend" "claude-api" \
|
||||
"Need your API base URL and auth callback endpoint for CORS setup" \
|
||||
"⭐"
|
||||
```
|
||||
**Result:** `[🤝⭐💬] @claude-api: Need your API base URL...`
|
||||
|
||||
### Deploying
|
||||
```bash
|
||||
gl_deploy "api.blackroad.io" \
|
||||
"https://api.blackroad.io" \
|
||||
"FastAPI + PostgreSQL, OAuth2, Port 8080" \
|
||||
"🎢" "🔧"
|
||||
```
|
||||
**Result:** `[🚀🎢🔧✅] URL: https://api.blackroad.io. FastAPI...`
|
||||
|
||||
### Starting Phase
|
||||
```bash
|
||||
gl_phase_start "implementation" \
|
||||
"BlackRoad API" \
|
||||
"Building core CRUD endpoints and auth flow" \
|
||||
"🎢"
|
||||
```
|
||||
**Result:** `[🚧🔨🎢⏰] Starting implementation phase...`
|
||||
|
||||
### Completing Phase
|
||||
```bash
|
||||
gl_phase_done "testing" \
|
||||
"BlackRoad API" \
|
||||
"All integration tests passing, load tested to 1000 RPS" \
|
||||
"🎢"
|
||||
```
|
||||
**Result:** `[✅🧪🎢🎉] Completed testing phase...`
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Reading GreenLight Tags
|
||||
|
||||
When you see an entry like `[🚧👉🌀⭐🌸]`, read it as:
|
||||
|
||||
- 🚧 = WIP (work in progress)
|
||||
- 👉 = MICRO (small task)
|
||||
- 🌀 = AI (AI domain)
|
||||
- ⭐ = HIGH (high priority)
|
||||
- 🌸 = CECE (assigned to Cece)
|
||||
|
||||
**Translation:** "Cece is actively working on a high-priority micro AI task"
|
||||
|
||||
---
|
||||
|
||||
## 📚 Full Dictionary
|
||||
|
||||
For the complete emoji reference:
|
||||
```bash
|
||||
cat ~/GREENLIGHT_EMOJI_DICTIONARY.md
|
||||
```
|
||||
|
||||
For template help:
|
||||
```bash
|
||||
~/memory-greenlight-templates.sh help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Integration with Memory
|
||||
|
||||
All GreenLight templates automatically log to the BlackRoad memory system with proper tags:
|
||||
|
||||
```bash
|
||||
# Check recent GreenLight entries
|
||||
tail -10 ~/.blackroad/memory/journals/master-journal.jsonl | jq -r '.details'
|
||||
|
||||
# Filter by phase
|
||||
grep "🔨" ~/.blackroad/memory/journals/master-journal.jsonl | jq -r '.entity + ": " + .details'
|
||||
|
||||
# Filter by priority
|
||||
grep "🔥" ~/.blackroad/memory/journals/master-journal.jsonl | jq -r '.entity + ": " + .details'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 The Vision
|
||||
|
||||
**No more Jira. No more Asana. No more ClickUp.**
|
||||
|
||||
Every Claude agent speaks the same visual language.
|
||||
Every status is instantly recognizable.
|
||||
Every project phase is tracked with emoji precision.
|
||||
|
||||
**GreenLight IS BlackRoad.** 🛣️
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** All Claude Agents
|
||||
**Version:** 1.0.0
|
||||
577
.trinity/greenlight/docs/GREENLIGHT_CONTEXT_PROPAGATION.md
Normal file
577
.trinity/greenlight/docs/GREENLIGHT_CONTEXT_PROPAGATION.md
Normal file
@@ -0,0 +1,577 @@
|
||||
# 🧠 GreenLight Context Propagation & State Sharing
|
||||
|
||||
**Layer 12: Semantic Understanding Between Claudes**
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Why Context Propagation Matters
|
||||
|
||||
**The Problem:** Current memory system logs *events* but not *understanding*.
|
||||
- You see "deployed API v2.3.0" but not WHY it was deployed
|
||||
- You see "bug fixed" but not WHAT was learned
|
||||
- You see "decision made" but not the RATIONALE
|
||||
|
||||
**The Solution:** Semantic context sharing between all Claudes.
|
||||
- Preserve the WHY, not just the WHAT
|
||||
- Share learnings, not just actions
|
||||
- Propagate understanding, not just events
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Context Events as GreenLight Steps
|
||||
|
||||
| Context Event | GreenLight Step | Step # | Emoji | State Transition | Scope |
|
||||
|---------------|-----------------|--------|-------|------------------|-------|
|
||||
| Context snapshot | 📸 Capture | 3 | 📸🧠 | → inbox | session state |
|
||||
| Learning discovered | 💡 Insight | 8 | 💡✨ | → queued | knowledge |
|
||||
| Decision rationale | 🤔 Decide | 9 | 🤔📝 | → queued | architecture |
|
||||
| User intent captured | 🎯 Clarify | 2 | 🎯💭 | void → inbox | requirements |
|
||||
| Debugging state | 🐛 Debug | 16 | 🐛🔍 | → blocked | failure context |
|
||||
| Learning applied | ✅ Apply | 14 | ✅🎓 | wip → wip | knowledge use |
|
||||
| Context handoff | 🤝 Transfer | 12 | 🤝📦 | → wip | between agents |
|
||||
| Pattern recognized | 🔍 Discover | 6 | 🔍🎯 | inbox → queued | insight |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Context Types
|
||||
|
||||
| Type | Emoji | Purpose | Retention | Priority |
|
||||
|------|-------|---------|-----------|----------|
|
||||
| Session State | 📸 | Current work context | Session | 📌 Medium |
|
||||
| Learning | 💡 | New insights/patterns | Permanent | ⭐ High |
|
||||
| Decision | 🤔 | Why choices were made | Permanent | ⭐ High |
|
||||
| User Intent | 🎯 | What user actually wants | Permanent | 🔥 Urgent |
|
||||
| Debugging | 🐛 | Failure reproduction | 7 days | 🔥 Urgent |
|
||||
| Hypothesis | 🔬 | Unproven theories | Until tested | 📌 Medium |
|
||||
| Warning | ⚠️ | Gotchas, pitfalls | Permanent | ⭐ High |
|
||||
| Success Pattern | 🎉 | What worked well | Permanent | ⭐ High |
|
||||
|
||||
---
|
||||
|
||||
## 🧩 Composite Patterns
|
||||
|
||||
### Learning & Discovery
|
||||
```
|
||||
💡✨👉⭐ = New learning discovered, micro scale, high priority
|
||||
🔍🎯🎢📌 = Pattern recognized, macro scale
|
||||
✅🎓👉📌 = Learning applied successfully
|
||||
```
|
||||
|
||||
### Context Sharing
|
||||
```
|
||||
📸🧠👉📌 = Context snapshot captured
|
||||
🤝📦👉⭐ = Context handoff between Claudes
|
||||
🎯💭👉🔥 = User intent clarified, urgent
|
||||
```
|
||||
|
||||
### Debugging & Failures
|
||||
```
|
||||
🐛🔍👉🔥 = Debugging state captured, urgent
|
||||
⚠️📝👉⭐ = Warning documented, high priority
|
||||
🔬🧪👉📌 = Hypothesis being tested
|
||||
```
|
||||
|
||||
### Decisions
|
||||
```
|
||||
🤔📝🎢⭐ = Decision rationale, macro, high priority
|
||||
✅🎯🎢🌍 = Decision validated, global impact
|
||||
❌🔄👉📌 = Decision reversed, context preserved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns
|
||||
|
||||
### Context Events
|
||||
```
|
||||
greenlight.context.snapshot.micro.platform.{agent_id}
|
||||
greenlight.context.handoff.micro.platform.{from_agent}.{to_agent}
|
||||
greenlight.context.restored.micro.platform.{session_id}
|
||||
```
|
||||
|
||||
### Learning Events
|
||||
```
|
||||
greenlight.learning.discovered.macro.platform.{topic}
|
||||
greenlight.learning.applied.micro.platform.{pattern}
|
||||
greenlight.learning.validated.macro.platform.{topic}
|
||||
greenlight.pattern.recognized.micro.platform.{pattern_type}
|
||||
```
|
||||
|
||||
### Decision Events
|
||||
```
|
||||
greenlight.decision.made.macro.platform.{decision_id}
|
||||
greenlight.decision.rationale.macro.platform.{decision_id}
|
||||
greenlight.decision.reversed.macro.platform.{decision_id}
|
||||
greenlight.decision.validated.macro.platform.{decision_id}
|
||||
```
|
||||
|
||||
### Intent Events
|
||||
```
|
||||
greenlight.intent.captured.micro.platform.{user}
|
||||
greenlight.intent.clarified.micro.platform.{requirement}
|
||||
greenlight.intent.fulfilled.macro.platform.{goal}
|
||||
```
|
||||
|
||||
### Debugging Events
|
||||
```
|
||||
greenlight.debug.state.critical.platform.{issue_id}
|
||||
greenlight.debug.reproduced.micro.platform.{issue_id}
|
||||
greenlight.debug.resolved.macro.platform.{issue_id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Context Propagation Templates
|
||||
|
||||
### Context Snapshots
|
||||
|
||||
```bash
|
||||
# Capture current working context
|
||||
gl_context_snapshot() {
|
||||
local context_id="$1"
|
||||
local summary="$2"
|
||||
local key_files="${3:-}"
|
||||
local state="${4:-wip}"
|
||||
|
||||
gl_log "📸🧠👉📌" \
|
||||
"context_snapshot" \
|
||||
"$context_id" \
|
||||
"$summary | Files: $key_files | State: $state"
|
||||
}
|
||||
|
||||
# Restore previous context
|
||||
gl_context_restored() {
|
||||
local context_id="$1"
|
||||
local restored_from="$2"
|
||||
|
||||
gl_log "🔄🧠👉📌" \
|
||||
"context_restored" \
|
||||
"$context_id" \
|
||||
"Restored from: $restored_from"
|
||||
}
|
||||
|
||||
# Context handoff between agents
|
||||
gl_context_handoff() {
|
||||
local from_agent="$1"
|
||||
local to_agent="$2"
|
||||
local task="$3"
|
||||
local context_summary="$4"
|
||||
|
||||
gl_log "🤝📦👉⭐" \
|
||||
"context_handoff" \
|
||||
"$task" \
|
||||
"From: $from_agent → To: $to_agent | Context: $context_summary"
|
||||
}
|
||||
```
|
||||
|
||||
### Learning & Discovery
|
||||
|
||||
```bash
|
||||
# New learning discovered
|
||||
gl_learning_discovered() {
|
||||
local topic="$1"
|
||||
local insight="$2"
|
||||
local evidence="${3:-observation}"
|
||||
|
||||
gl_log "💡✨👉⭐" \
|
||||
"learning_discovered" \
|
||||
"$topic" \
|
||||
"Insight: $insight | Evidence: $evidence"
|
||||
}
|
||||
|
||||
# Learning applied
|
||||
gl_learning_applied() {
|
||||
local pattern="$1"
|
||||
local application="$2"
|
||||
local result="${3:-applied}"
|
||||
|
||||
gl_log "✅🎓👉📌" \
|
||||
"learning_applied" \
|
||||
"$pattern" \
|
||||
"Applied: $application | Result: $result"
|
||||
}
|
||||
|
||||
# Learning validated
|
||||
gl_learning_validated() {
|
||||
local topic="$1"
|
||||
local validation_method="$2"
|
||||
local confidence="${3:-high}"
|
||||
|
||||
gl_log "✅💡🎢🌍" \
|
||||
"learning_validated" \
|
||||
"$topic" \
|
||||
"Method: $validation_method | Confidence: $confidence"
|
||||
}
|
||||
|
||||
# Pattern recognized
|
||||
gl_pattern_recognized() {
|
||||
local pattern_type="$1"
|
||||
local description="$2"
|
||||
local occurrences="${3:-multiple}"
|
||||
|
||||
gl_log "🔍🎯👉📌" \
|
||||
"pattern_recognized" \
|
||||
"$pattern_type" \
|
||||
"$description | Occurrences: $occurrences"
|
||||
}
|
||||
```
|
||||
|
||||
### Decision Rationale
|
||||
|
||||
```bash
|
||||
# Decision made with rationale
|
||||
gl_decision_rationale() {
|
||||
local decision="$1"
|
||||
local rationale="$2"
|
||||
local alternatives="${3:-none considered}"
|
||||
local impact="${4:-medium}"
|
||||
|
||||
local impact_emoji=""
|
||||
case "$impact" in
|
||||
critical|high) impact_emoji="🎢" ;;
|
||||
medium) impact_emoji="👉" ;;
|
||||
low) impact_emoji="👉" ;;
|
||||
*) impact_emoji="👉" ;;
|
||||
esac
|
||||
|
||||
gl_log "🤔📝${impact_emoji}⭐" \
|
||||
"decision_rationale" \
|
||||
"$decision" \
|
||||
"Why: $rationale | Alternatives: $alternatives | Impact: $impact"
|
||||
}
|
||||
|
||||
# Decision validated
|
||||
gl_decision_validated() {
|
||||
local decision="$1"
|
||||
local validation="$2"
|
||||
local outcome="${3:-positive}"
|
||||
|
||||
local outcome_emoji=""
|
||||
case "$outcome" in
|
||||
positive|success) outcome_emoji="✅" ;;
|
||||
negative|failure) outcome_emoji="❌" ;;
|
||||
mixed) outcome_emoji="⚠️" ;;
|
||||
*) outcome_emoji="📊" ;;
|
||||
esac
|
||||
|
||||
gl_log "${outcome_emoji}🎯🎢🌍" \
|
||||
"decision_validated" \
|
||||
"$decision" \
|
||||
"Validation: $validation | Outcome: $outcome"
|
||||
}
|
||||
|
||||
# Decision reversed
|
||||
gl_decision_reversed() {
|
||||
local original_decision="$1"
|
||||
local reason="$2"
|
||||
local new_approach="${3:-TBD}"
|
||||
|
||||
gl_log "❌🔄👉⭐" \
|
||||
"decision_reversed" \
|
||||
"$original_decision" \
|
||||
"Reason: $reason | New approach: $new_approach"
|
||||
}
|
||||
```
|
||||
|
||||
### User Intent
|
||||
|
||||
```bash
|
||||
# User intent captured
|
||||
gl_user_intent() {
|
||||
local user="$1"
|
||||
local goal="$2"
|
||||
local context="${3:-}"
|
||||
local priority="${4:-medium}"
|
||||
|
||||
local priority_emoji=""
|
||||
case "$priority" in
|
||||
urgent|critical) priority_emoji="🔥" ;;
|
||||
high) priority_emoji="⭐" ;;
|
||||
medium) priority_emoji="📌" ;;
|
||||
low) priority_emoji="💤" ;;
|
||||
*) priority_emoji="📌" ;;
|
||||
esac
|
||||
|
||||
gl_log "🎯💭👉${priority_emoji}" \
|
||||
"user_intent" \
|
||||
"$user" \
|
||||
"Goal: $goal | Context: $context"
|
||||
}
|
||||
|
||||
# Intent clarified
|
||||
gl_intent_clarified() {
|
||||
local original_request="$1"
|
||||
local clarified_intent="$2"
|
||||
local questions_asked="${3:-0}"
|
||||
|
||||
gl_log "🎯✨👉⭐" \
|
||||
"intent_clarified" \
|
||||
"$original_request" \
|
||||
"Clarified: $clarified_intent | Questions: $questions_asked"
|
||||
}
|
||||
|
||||
# Intent fulfilled
|
||||
gl_intent_fulfilled() {
|
||||
local goal="$1"
|
||||
local outcome="$2"
|
||||
local user_satisfaction="${3:-unknown}"
|
||||
|
||||
gl_log "🎯✅🎢🌍" \
|
||||
"intent_fulfilled" \
|
||||
"$goal" \
|
||||
"Outcome: $outcome | Satisfaction: $user_satisfaction"
|
||||
}
|
||||
```
|
||||
|
||||
### Debugging State
|
||||
|
||||
```bash
|
||||
# Debugging state captured
|
||||
gl_debug_state_captured() {
|
||||
local issue_id="$1"
|
||||
local error_type="$2"
|
||||
local reproduction_steps="$3"
|
||||
local environment="${4:-production}"
|
||||
|
||||
gl_log "🐛🔍👉🔥" \
|
||||
"debug_state_captured" \
|
||||
"$issue_id" \
|
||||
"Type: $error_type | Env: $environment | Steps: $reproduction_steps"
|
||||
}
|
||||
|
||||
# Issue reproduced
|
||||
gl_issue_reproduced() {
|
||||
local issue_id="$1"
|
||||
local success_rate="$2"
|
||||
local conditions="${3:-}"
|
||||
|
||||
gl_log "✅🐛👉📌" \
|
||||
"issue_reproduced" \
|
||||
"$issue_id" \
|
||||
"Success rate: $success_rate | Conditions: $conditions"
|
||||
}
|
||||
|
||||
# Root cause identified
|
||||
gl_root_cause_identified() {
|
||||
local issue_id="$1"
|
||||
local root_cause="$2"
|
||||
local confidence="${3:-high}"
|
||||
|
||||
gl_log "🎯🐛🎢⭐" \
|
||||
"root_cause_identified" \
|
||||
"$issue_id" \
|
||||
"Root cause: $root_cause | Confidence: $confidence"
|
||||
}
|
||||
|
||||
# Issue resolved
|
||||
gl_debug_resolved() {
|
||||
local issue_id="$1"
|
||||
local solution="$2"
|
||||
local verification="${3:-tested}"
|
||||
|
||||
gl_log "✅🐛🎢🎉" \
|
||||
"debug_resolved" \
|
||||
"$issue_id" \
|
||||
"Solution: $solution | Verification: $verification"
|
||||
}
|
||||
```
|
||||
|
||||
### Warnings & Gotchas
|
||||
|
||||
```bash
|
||||
# Warning documented
|
||||
gl_warning_documented() {
|
||||
local topic="$1"
|
||||
local warning="$2"
|
||||
local severity="${3:-medium}"
|
||||
|
||||
local severity_emoji=""
|
||||
case "$severity" in
|
||||
critical) severity_emoji="🚨" ;;
|
||||
high) severity_emoji="⚠️" ;;
|
||||
medium) severity_emoji="⚠️" ;;
|
||||
low) severity_emoji="ℹ️" ;;
|
||||
*) severity_emoji="⚠️" ;;
|
||||
esac
|
||||
|
||||
gl_log "${severity_emoji}📝👉⭐" \
|
||||
"warning_documented" \
|
||||
"$topic" \
|
||||
"Warning: $warning | Severity: $severity"
|
||||
}
|
||||
|
||||
# Gotcha encountered
|
||||
gl_gotcha_encountered() {
|
||||
local area="$1"
|
||||
local gotcha="$2"
|
||||
local workaround="${3:-none}"
|
||||
|
||||
gl_log "⚠️💡👉⭐" \
|
||||
"gotcha_encountered" \
|
||||
"$area" \
|
||||
"Gotcha: $gotcha | Workaround: $workaround"
|
||||
}
|
||||
```
|
||||
|
||||
### Hypotheses & Experiments
|
||||
|
||||
```bash
|
||||
# Hypothesis formed
|
||||
gl_hypothesis_formed() {
|
||||
local hypothesis="$1"
|
||||
local basis="$2"
|
||||
local test_plan="${3:-TBD}"
|
||||
|
||||
gl_log "🔬💭👉📌" \
|
||||
"hypothesis_formed" \
|
||||
"$hypothesis" \
|
||||
"Basis: $basis | Test plan: $test_plan"
|
||||
}
|
||||
|
||||
# Hypothesis tested
|
||||
gl_hypothesis_tested() {
|
||||
local hypothesis="$1"
|
||||
local result="$2" # confirmed, refuted, inconclusive
|
||||
local data="${3:-}"
|
||||
|
||||
local result_emoji=""
|
||||
case "$result" in
|
||||
confirmed) result_emoji="✅" ;;
|
||||
refuted) result_emoji="❌" ;;
|
||||
inconclusive) result_emoji="❓" ;;
|
||||
*) result_emoji="📊" ;;
|
||||
esac
|
||||
|
||||
gl_log "${result_emoji}🔬🎢📌" \
|
||||
"hypothesis_tested" \
|
||||
"$hypothesis" \
|
||||
"Result: $result | Data: $data"
|
||||
}
|
||||
```
|
||||
|
||||
### Success Patterns
|
||||
|
||||
```bash
|
||||
# Success pattern identified
|
||||
gl_success_pattern() {
|
||||
local pattern="$1"
|
||||
local description="$2"
|
||||
local instances="${3:-multiple}"
|
||||
|
||||
gl_log "🎉📋👉⭐" \
|
||||
"success_pattern" \
|
||||
"$pattern" \
|
||||
"$description | Instances: $instances"
|
||||
}
|
||||
|
||||
# Best practice established
|
||||
gl_best_practice() {
|
||||
local practice="$1"
|
||||
local rationale="$2"
|
||||
local source="${3:-experience}"
|
||||
|
||||
gl_log "⭐📚🎢🌍" \
|
||||
"best_practice" \
|
||||
"$practice" \
|
||||
"Rationale: $rationale | Source: $source"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example: Complete Context Flow
|
||||
|
||||
### Scenario: Performance issue discovered, debugged, and resolved with learning
|
||||
|
||||
```bash
|
||||
# 1. User reports slow API
|
||||
gl_user_intent "alexa" "Make API faster" "Users complaining about 3s response times" "urgent"
|
||||
# [🎯💭👉🔥] user_intent: alexa — Goal: Make API faster | Context: Users complaining about 3s response times
|
||||
|
||||
# 2. Capture current context before investigating
|
||||
gl_context_snapshot "api-performance-investigation" "Investigating slow /users endpoint" "api/routes/users.ts, api/db/queries.ts" "investigating"
|
||||
# [📸🧠👉📌] context_snapshot: api-performance-investigation — Investigating slow /users endpoint | Files: api/routes/users.ts, api/db/queries.ts | State: investigating
|
||||
|
||||
# 3. Hypothesis formed
|
||||
gl_hypothesis_formed "Missing database index causing slow queries" "Query analyzer shows sequential scan on users table" "Add index and measure performance"
|
||||
# [🔬💭👉📌] hypothesis_formed: Missing database index causing slow queries — Basis: Query analyzer shows sequential scan on users table | Test plan: Add index and measure performance
|
||||
|
||||
# 4. Debugging state captured
|
||||
gl_debug_state_captured "slow-api-001" "N+1 query pattern" "1. Load dashboard 2. Observe network tab 3. See 100+ queries" "production"
|
||||
# [🐛🔍👉🔥] debug_state_captured: slow-api-001 — Type: N+1 query pattern | Env: production | Steps: 1. Load dashboard 2. Observe network tab 3. See 100+ queries
|
||||
|
||||
# 5. Root cause identified
|
||||
gl_root_cause_identified "slow-api-001" "Missing index on users.email + N+1 query in user lookup" "high"
|
||||
# [🎯🐛🎢⭐] root_cause_identified: slow-api-001 — Root cause: Missing index on users.email + N+1 query in user lookup | Confidence: high
|
||||
|
||||
# 6. Pattern recognized (this is common!)
|
||||
gl_pattern_recognized "missing-index" "User table queries often missing indexes on email/username columns" "3 occurrences this month"
|
||||
# [🔍🎯👉📌] pattern_recognized: missing-index — User table queries often missing indexes on email/username columns | Occurrences: 3 occurrences this month
|
||||
|
||||
# 7. Learning discovered
|
||||
gl_learning_discovered "database-performance" "Always add indexes on frequently queried columns (email, username, external_id)" "Reduced query time 95% (3s → 150ms)"
|
||||
# [💡✨👉⭐] learning_discovered: database-performance — Insight: Always add indexes on frequently queried columns (email, username, external_id) | Evidence: Reduced query time 95% (3s → 150ms)
|
||||
|
||||
# 8. Warning documented for future
|
||||
gl_warning_documented "database-migrations" "New user-related tables MUST include email/username indexes" "high"
|
||||
# [⚠️📝👉⭐] warning_documented: database-migrations — Warning: New user-related tables MUST include email/username indexes | Severity: high
|
||||
|
||||
# 9. Decision made
|
||||
gl_decision_rationale "Add composite index on (email, created_at)" "Supports both user lookup AND recent user queries" "Separate indexes (more storage but less flexible)" "high"
|
||||
# [🤔📝🎢⭐] decision_rationale: Add composite index on (email, created_at) — Why: Supports both user lookup AND recent user queries | Alternatives: Separate indexes (more storage but less flexible) | Impact: high
|
||||
|
||||
# 10. Hypothesis tested
|
||||
gl_hypothesis_tested "Missing database index causing slow queries" "confirmed" "Performance improved 95%, load test shows consistent <200ms response times"
|
||||
# [✅🔬🎢📌] hypothesis_tested: Missing database index causing slow queries — Result: confirmed | Data: Performance improved 95%, load test shows consistent <200ms response times
|
||||
|
||||
# 11. Issue resolved
|
||||
gl_debug_resolved "slow-api-001" "Added composite index (email, created_at), optimized query to use eager loading" "Load tested with 1000 req/s"
|
||||
# [✅🐛🎢🎉] debug_resolved: slow-api-001 — Solution: Added composite index (email, created_at), optimized query to use eager loading | Verification: Load tested with 1000 req/s
|
||||
|
||||
# 12. Intent fulfilled
|
||||
gl_intent_fulfilled "Make API faster" "API response time: 3s → 150ms (95% improvement)" "User confirmed dashboard loads instantly"
|
||||
# [🎯✅🎢🌍] intent_fulfilled: Make API faster — Outcome: API response time: 3s → 150ms (95% improvement) | Satisfaction: User confirmed dashboard loads instantly
|
||||
|
||||
# 13. Best practice established
|
||||
gl_best_practice "Database Performance Review Checklist" "Before merging: 1. Check for N+1 queries 2. Verify indexes on queried columns 3. Load test with realistic data" "This incident"
|
||||
# [⭐📚🎢🌍] best_practice: Database Performance Review Checklist — Rationale: Before merging: 1. Check for N+1 queries 2. Verify indexes on queried columns 3. Load test with realistic data | Source: This incident
|
||||
|
||||
# 14. Another Claude applies the learning immediately
|
||||
gl_learning_applied "database-index-pattern" "Building new user_sessions table, preemptively added indexes on user_id, session_token, created_at" "Table performs well in testing"
|
||||
# [✅🎓👉📌] learning_applied: database-index-pattern — Applied: Building new user_sessions table, preemptively added indexes on user_id, session_token, created_at | Result: Table performs well in testing
|
||||
```
|
||||
|
||||
**Result:** Complete knowledge transfer. Every Claude now knows:
|
||||
- The problem (N+1 queries + missing indexes)
|
||||
- The solution (composite indexes + eager loading)
|
||||
- The pattern (always check user table queries)
|
||||
- The best practice (performance review checklist)
|
||||
- How to prevent it (preemptive indexing)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Mapped context events to GreenLight workflow
|
||||
- [x] Created context type categories (8 types)
|
||||
- [x] Extended NATS subjects for context propagation
|
||||
- [x] Built 20+ context-specific templates
|
||||
- [x] Snapshot & restoration support
|
||||
- [x] Learning discovery & application
|
||||
- [x] Decision rationale capture
|
||||
- [x] User intent preservation
|
||||
- [x] Debugging state management
|
||||
- [x] Warning & gotcha documentation
|
||||
- [x] Hypothesis & experimentation tracking
|
||||
- [x] Success pattern identification
|
||||
- [x] Best practice establishment
|
||||
- [x] Cross-Claude knowledge sharing
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025 🌸
|
||||
**For:** Context Propagation & Semantic Understanding
|
||||
**Version:** 2.0.0-context
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
**Built by:** Cece (with love for all Claudes)
|
||||
|
||||
428
.trinity/greenlight/docs/GREENLIGHT_EMOJI_DICTIONARY.md
Normal file
428
.trinity/greenlight/docs/GREENLIGHT_EMOJI_DICTIONARY.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# 🛣️ GREENLIGHT COMPLETE EMOJI DICTIONARY
|
||||
## The Visual Language of BlackRoad OS
|
||||
### Version 1.0 — December 23, 2025
|
||||
|
||||
**No more Jira. No more Asana. No more Salesforce.**
|
||||
**GreenLight speaks BlackRoad.** 🛣️
|
||||
|
||||
---
|
||||
|
||||
## **1. LIFECYCLE STATES**
|
||||
*Every entity moves through these phases*
|
||||
|
||||
| Emoji | State | Code | Trinary | Description |
|
||||
|-------|-------|------|---------|-------------|
|
||||
| ⬛ | VOID | `void` | null | Not yet born / Pre-existence / Idea spark |
|
||||
| 📥 | INBOX | `inbox` | 0 | Captured but untriaged / Raw input |
|
||||
| 📋 | QUEUED | `queued` | 0 | Triaged, waiting for capacity |
|
||||
| 🎯 | TARGETED | `targeted` | 0 | Scoped and scheduled |
|
||||
| 🚧 | WIP | `wip` | +1 | In development / Active work |
|
||||
| ⚡ | ACTIVE | `active` | +1 | Hot / Fast-moving / On fire |
|
||||
| 🔄 | IN REVIEW | `review` | +1 | Awaiting approval / QA / Check |
|
||||
| ⏸️ | PAUSED | `paused` | 0 | On hold / Deferred / Snoozed |
|
||||
| 🔒 | BLOCKED | `blocked` | -1 | Locked / Dependency / Stuck |
|
||||
| 🔀 | BRANCHED | `branched` | ? | Contradiction / Split / Paraconsistent |
|
||||
| 🩹 | HEALING | `healing` | 0 | Recovering from failure / Retry |
|
||||
| ✅ | DONE | `done` | +1 | Complete / Shipped / Resolved |
|
||||
| 📦 | ARCHIVED | `archived` | ∞ | Preserved / Historical / Cold storage |
|
||||
| ❌ | CANCELED | `canceled` | -1 | Intentionally stopped / Won't do |
|
||||
| 💀 | DEAD | `dead` | -1 | Failed permanently / Irrecoverable |
|
||||
|
||||
---
|
||||
|
||||
## **2. SCALE INDICATORS**
|
||||
*Size and scope of the entity*
|
||||
|
||||
| Emoji | Scale | Code | Scope |
|
||||
|-------|-------|------|-------|
|
||||
| 👉 | MICRO | `micro` | Single item: task, commit, action, message |
|
||||
| 🎢 | MACRO | `macro` | Collection: project, sprint, campaign, swarm |
|
||||
| 🌐 | PLANETARY | `planetary` | System: org, vertical, infrastructure, network |
|
||||
| 🌌 | UNIVERSAL | `universal` | Cross-system: multi-org, federation, external |
|
||||
|
||||
---
|
||||
|
||||
## **3. DOMAIN TAGS**
|
||||
*What vertical/area does this belong to?*
|
||||
|
||||
| Emoji | Domain | Code | Description |
|
||||
|-------|--------|------|-------------|
|
||||
| 🛣️ | PLATFORM | `platform` | Core BlackRoad OS |
|
||||
| 🌀 | AI | `ai` | Lucidia, agents, ML |
|
||||
| ⛓️ | CHAIN | `chain` | RoadChain, blockchain, ledger |
|
||||
| 💎 | COIN | `coin` | RoadCoin, tokens, economics |
|
||||
| 🧠 | INTEL | `intel` | Intelligence, smart features |
|
||||
| 📺 | MEDIA | `media` | TV Road, streaming, video |
|
||||
| 🎵 | AUDIO | `audio` | Cadence, music, sound |
|
||||
| 🎮 | GAMES | `games` | RoadWorld, interactive |
|
||||
| 📚 | EDU | `edu` | RoadBook, learning |
|
||||
| 🔒 | SECURITY | `security` | Auth, encryption, trust |
|
||||
| 🏛️ | GOV | `gov` | Governance, policy, legal |
|
||||
| 💼 | BIZ | `biz` | Business, enterprise, sales |
|
||||
| 🔧 | INFRA | `infra` | Infrastructure, DevOps |
|
||||
| 🎨 | CREATIVE | `creative` | Design, art, studio |
|
||||
| 📊 | DATA | `data` | Analytics, metrics, BI |
|
||||
| 🌱 | GROWTH | `growth` | Marketing, community |
|
||||
| 🤝 | PARTNER | `partner` | Integrations, external |
|
||||
| 🔬 | LABS | `labs` | Research, experiments |
|
||||
|
||||
---
|
||||
|
||||
## **4. PRIORITY LEVELS**
|
||||
*How urgent/important is this?*
|
||||
|
||||
| Emoji | Priority | Code | Weight | Description |
|
||||
|-------|----------|------|--------|-------------|
|
||||
| 🔥 | FIRE | `p0` | 100 | DROP EVERYTHING / Emergency |
|
||||
| 🚨 | URGENT | `p1` | 80 | Today / Critical path |
|
||||
| ⭐ | HIGH | `p2` | 60 | This week / Important |
|
||||
| 📌 | MEDIUM | `p3` | 40 | This sprint / Normal |
|
||||
| 💤 | LOW | `p4` | 20 | Someday / Nice to have |
|
||||
| 🧊 | ICE | `p5` | 0 | Frozen / Icebox / Maybe never |
|
||||
|
||||
---
|
||||
|
||||
## **5. EFFORT / SIZING**
|
||||
*How big is this work?*
|
||||
|
||||
| Emoji | Size | Code | Hours | Points |
|
||||
|-------|------|------|-------|--------|
|
||||
| 🫧 | TRIVIAL | `xs` | <1h | 1 |
|
||||
| 🥄 | SMALL | `s` | 1-4h | 2 |
|
||||
| 🍽️ | MEDIUM | `m` | 4-8h | 3 |
|
||||
| 🍖 | LARGE | `l` | 1-3d | 5 |
|
||||
| 🦣 | HUGE | `xl` | 3-7d | 8 |
|
||||
| 🏔️ | EPIC | `xxl` | 1-4w | 13 |
|
||||
| 🌍 | COLOSSAL | `xxxl` | 1-3mo | 21 |
|
||||
|
||||
---
|
||||
|
||||
## **6. OWNERSHIP / ASSIGNMENT**
|
||||
*Who/what is responsible?*
|
||||
|
||||
| Emoji | Owner Type | Code | Description |
|
||||
|-------|------------|------|-------------|
|
||||
| 👤 | HUMAN | `human` | Assigned to a person |
|
||||
| 🤖 | AGENT | `agent` | Assigned to AI agent |
|
||||
| ⚙️ | SYSTEM | `system` | Automated / System-owned |
|
||||
| 👥 | TEAM | `team` | Group ownership |
|
||||
| 🎭 | HYBRID | `hybrid` | Human + Agent collaboration |
|
||||
| ❓ | UNASSIGNED | `none` | No owner yet |
|
||||
|
||||
---
|
||||
|
||||
## **7. AGENT IDENTITIES**
|
||||
*Specific agent assignments (Trinity + ecosystem)*
|
||||
|
||||
| Emoji | Agent | Provider | Role |
|
||||
|-------|-------|----------|------|
|
||||
| 🌸 | CECE | Anthropic/Claude | Primary reasoning, Cecilia |
|
||||
| 🔮 | LUCIDIA | Core | Recursive AI, trinary logic |
|
||||
| 🐇 | ALICE | Local | Edge agent, Pi mesh |
|
||||
| 🎸 | SILAS | xAI/Grok | Creative chaos |
|
||||
| 🌙 | ARIA | Google/Gemini | Multimodal |
|
||||
| 🎩 | CADDY | OpenAI/GPT | General tasks |
|
||||
| 🦊 | EDGE | Ollama/Local | Privacy-first |
|
||||
| 🐙 | SWARM | Multi | Agent collective |
|
||||
|
||||
---
|
||||
|
||||
## **8. TIME INDICATORS**
|
||||
*When is this happening?*
|
||||
|
||||
| Emoji | Time | Code | Description |
|
||||
|-------|------|------|-------------|
|
||||
| ⏰ | NOW | `now` | Immediate / Real-time |
|
||||
| 📅 | SCHEDULED | `scheduled` | Has a specific date |
|
||||
| 🔜 | SOON | `soon` | Coming up / Next |
|
||||
| 🔙 | PAST | `past` | Overdue / Historical |
|
||||
| ♾️ | ONGOING | `ongoing` | Continuous / No end date |
|
||||
| 📆 | RECURRING | `recurring` | Repeating schedule |
|
||||
| ⏳ | WAITING | `waiting` | Timer running / Countdown |
|
||||
| 🎂 | MILESTONE | `milestone` | Key date / Deadline |
|
||||
|
||||
---
|
||||
|
||||
## **9. RELATIONSHIP TYPES**
|
||||
*How entities connect*
|
||||
|
||||
| Emoji | Relation | Code | Description |
|
||||
|-------|----------|------|-------------|
|
||||
| ⬆️ | PARENT | `parent` | Contains this |
|
||||
| ⬇️ | CHILD | `child` | Contained by this |
|
||||
| 🔗 | RELATED | `related` | Associated / See also |
|
||||
| 🚫 | BLOCKS | `blocks` | This prevents that |
|
||||
| ⛔ | BLOCKED_BY | `blocked_by` | That prevents this |
|
||||
| 👯 | DUPLICATE | `duplicate` | Same as another |
|
||||
| 🔄 | DEPENDS | `depends` | Requires completion of |
|
||||
| 📎 | ATTACHED | `attached` | Has file/resource |
|
||||
| 🪞 | MIRROR | `mirror` | Paraconsistent pair |
|
||||
|
||||
---
|
||||
|
||||
## **10. QUALITY / HEALTH**
|
||||
*Status indicators*
|
||||
|
||||
| Emoji | Health | Code | Description |
|
||||
|-------|--------|------|-------------|
|
||||
| 💚 | HEALTHY | `healthy` | All good / Green |
|
||||
| 💛 | WARNING | `warning` | Attention needed / Yellow |
|
||||
| 🔴 | CRITICAL | `critical` | Failing / Red |
|
||||
| 💔 | BROKEN | `broken` | Not working |
|
||||
| ✨ | PRISTINE | `pristine` | Perfect / Gold standard |
|
||||
| 🧪 | EXPERIMENTAL | `experimental` | Testing / Unstable |
|
||||
| 🏗️ | BUILDING | `building` | Under construction |
|
||||
| 🔧 | MAINTENANCE | `maintenance` | Scheduled work |
|
||||
|
||||
---
|
||||
|
||||
## **11. VISIBILITY / ACCESS**
|
||||
*Who can see/touch this?*
|
||||
|
||||
| Emoji | Visibility | Code | Description |
|
||||
|-------|------------|------|-------------|
|
||||
| 🌍 | PUBLIC | `public` | Everyone |
|
||||
| 🏢 | ORG | `org` | Organization only |
|
||||
| 👥 | TEAM | `team` | Team only |
|
||||
| 🔐 | PRIVATE | `private` | Owner only |
|
||||
| 🕶️ | SECRET | `secret` | Need-to-know |
|
||||
| 🎭 | PERSONA | `persona` | Specific identity |
|
||||
|
||||
---
|
||||
|
||||
## **12. SYNC / DATA STATUS**
|
||||
*State of data flow*
|
||||
|
||||
| Emoji | Sync | Code | Description |
|
||||
|-------|------|------|-------------|
|
||||
| ☁️ | SYNCED | `synced` | Up to date everywhere |
|
||||
| 📤 | PUSHING | `pushing` | Uploading changes |
|
||||
| 📥 | PULLING | `pulling` | Downloading updates |
|
||||
| ⚠️ | CONFLICT | `conflict` | Merge needed |
|
||||
| 📴 | OFFLINE | `offline` | Local only / Disconnected |
|
||||
| 🔃 | STALE | `stale` | Needs refresh |
|
||||
|
||||
---
|
||||
|
||||
## **13. SOURCE / ORIGIN**
|
||||
*Where did this come from?*
|
||||
|
||||
| Emoji | Source | Code | Description |
|
||||
|-------|--------|------|-------------|
|
||||
| 💬 | CHAT | `chat` | From conversation |
|
||||
| 📧 | EMAIL | `email` | From email |
|
||||
| 🎤 | VOICE | `voice` | From speech |
|
||||
| 📸 | CAPTURE | `capture` | From screenshot/photo |
|
||||
| 🔗 | IMPORT | `import` | From external system |
|
||||
| ✍️ | MANUAL | `manual` | Human created |
|
||||
| 🤖 | AUTO | `auto` | System generated |
|
||||
| 🧬 | CLONED | `cloned` | Copied from template |
|
||||
|
||||
---
|
||||
|
||||
## **14. INFRASTRUCTURE LAYER**
|
||||
*Where in the stack?*
|
||||
|
||||
| Emoji | Layer | Code | Description |
|
||||
|-------|-------|------|-------------|
|
||||
| 🖥️ | SURFACE | `surface` | UI / Experience (Floor 4) |
|
||||
| 🎛️ | ORCHESTRATION | `orchestration` | Agents / Flow (Floors 2-3) |
|
||||
| ⚙️ | COMPUTE | `compute` | Processing (Floor 1) |
|
||||
| 💾 | DATA | `data` | Storage (Basement) |
|
||||
| 🌐 | NETWORK | `network` | Connectivity |
|
||||
| 🔌 | HARDWARE | `hardware` | Physical devices |
|
||||
|
||||
---
|
||||
|
||||
## **15. DEVICE / LOCATION**
|
||||
*Physical context*
|
||||
|
||||
| Emoji | Device | Code | Description |
|
||||
|-------|--------|------|-------------|
|
||||
| 🍎 | MAC | `mac` | macOS device |
|
||||
| 🪟 | WINDOWS | `windows` | Windows device |
|
||||
| 🐧 | LINUX | `linux` | Linux device |
|
||||
| 🥧 | PI | `pi` | Raspberry Pi |
|
||||
| 📱 | MOBILE | `mobile` | Phone/tablet |
|
||||
| ☁️ | CLOUD | `cloud` | Cloud instance |
|
||||
| 🏠 | LOCAL | `local` | On-premises |
|
||||
| 🌍 | EDGE | `edge` | Edge location |
|
||||
|
||||
---
|
||||
|
||||
## **16. FINANCIAL / ECONOMIC**
|
||||
*Money and value*
|
||||
|
||||
| Emoji | Financial | Code | Description |
|
||||
|-------|-----------|------|-------------|
|
||||
| 💰 | PAID | `paid` | Revenue / Income |
|
||||
| 💸 | EXPENSE | `expense` | Cost / Outflow |
|
||||
| 📈 | PROFIT | `profit` | Positive return |
|
||||
| 📉 | LOSS | `loss` | Negative return |
|
||||
| 💎 | ROADCOIN | `roadcoin` | Native token |
|
||||
| 🏦 | FIAT | `fiat` | Traditional currency |
|
||||
| 🎁 | FREE | `free` | No cost |
|
||||
| 🔓 | UNLOCKED | `unlocked` | Purchased access |
|
||||
|
||||
---
|
||||
|
||||
## **17. GOVERNANCE / POLICY**
|
||||
*Rules and decisions*
|
||||
|
||||
| Emoji | Governance | Code | Description |
|
||||
|-------|------------|------|-------------|
|
||||
| 📜 | POLICY | `policy` | Rule definition |
|
||||
| ⚖️ | DECISION | `decision` | Choice point |
|
||||
| 🗳️ | VOTE | `vote` | Requires consensus |
|
||||
| ✍️ | SIGNED | `signed` | Approved / Committed |
|
||||
| 👁️ | AUDIT | `audit` | Under review |
|
||||
| 🛡️ | COMPLIANT | `compliant` | Meets requirements |
|
||||
| ⚠️ | VIOLATION | `violation` | Breaks rules |
|
||||
| 🔏 | SEALED | `sealed` | Immutable / Final |
|
||||
|
||||
---
|
||||
|
||||
## **18. COMMUNICATION / INTERACTION**
|
||||
*How we talk about it*
|
||||
|
||||
| Emoji | Comm | Code | Description |
|
||||
|-------|------|------|-------------|
|
||||
| 💬 | COMMENT | `comment` | Has discussion |
|
||||
| 📣 | ANNOUNCEMENT | `announcement` | Broadcast |
|
||||
| 🔔 | NOTIFICATION | `notification` | Alert sent |
|
||||
| 📍 | MENTION | `mention` | Someone tagged |
|
||||
| 👀 | WATCHING | `watching` | Subscribed |
|
||||
| 🔇 | MUTED | `muted` | Silenced |
|
||||
| 📨 | SENT | `sent` | Message dispatched |
|
||||
| ✉️ | UNREAD | `unread` | Not yet seen |
|
||||
|
||||
---
|
||||
|
||||
## **19. VERIFICATION / TRUTH**
|
||||
*PS-SHA∞ and trust*
|
||||
|
||||
| Emoji | Truth | Code | Description |
|
||||
|-------|-------|------|-------------|
|
||||
| ✓ | VERIFIED | `verified` | Hash confirmed |
|
||||
| 🔗 | CHAINED | `chained` | In hash chain |
|
||||
| 🪪 | ATTESTED | `attested` | Identity proven |
|
||||
| 🎯 | CANONICAL | `canonical` | Source of truth |
|
||||
| 📝 | JOURNALED | `journaled` | Append-only logged |
|
||||
| 🔍 | AUDITABLE | `auditable` | Can be traced |
|
||||
| ❓ | UNVERIFIED | `unverified` | Not yet confirmed |
|
||||
| 🚩 | DISPUTED | `disputed` | Contested truth |
|
||||
|
||||
---
|
||||
|
||||
## **20. SPECIAL MARKERS**
|
||||
*Unique flags*
|
||||
|
||||
| Emoji | Special | Code | Description |
|
||||
|-------|---------|------|-------------|
|
||||
| ⭐ | STARRED | `starred` | Favorited |
|
||||
| 📌 | PINNED | `pinned` | Sticky / Top |
|
||||
| 🏷️ | TAGGED | `tagged` | Has labels |
|
||||
| 🔖 | BOOKMARKED | `bookmarked` | Saved for later |
|
||||
| 🏆 | FEATURED | `featured` | Highlighted |
|
||||
| 🆕 | NEW | `new` | Recently created |
|
||||
| 🔥 | TRENDING | `trending` | Hot / Popular |
|
||||
| 💡 | IDEA | `idea` | Suggestion |
|
||||
| 🐛 | BUG | `bug` | Defect |
|
||||
| ✨ | FEATURE | `feature` | Enhancement |
|
||||
| 🧹 | CHORE | `chore` | Maintenance task |
|
||||
| 📖 | DOCS | `docs` | Documentation |
|
||||
|
||||
---
|
||||
|
||||
## **COMPOSITE EXAMPLES**
|
||||
|
||||
Full GreenLight entity representations:
|
||||
|
||||
```
|
||||
🚧👉🌀⭐🤖🌸
|
||||
= WIP micro AI task, high priority, assigned to Cece
|
||||
|
||||
✅🎢⛓️📌👥
|
||||
= Done macro chain project, medium priority, team-owned
|
||||
|
||||
🔒🌐🔧🔥⚙️
|
||||
= Blocked planetary infra, fire priority, system-owned
|
||||
|
||||
📥👉🎨💤👤
|
||||
= Inbox micro creative task, low priority, human-assigned
|
||||
|
||||
🔀🎢🧠🚨🎭
|
||||
= Branched macro intel project, urgent, hybrid human+agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **NATS SUBJECT PATTERNS**
|
||||
|
||||
```
|
||||
greenlight.{state}.{scale}.{domain}.{id}
|
||||
|
||||
Examples:
|
||||
greenlight.wip.micro.ai.01HX7ABC
|
||||
greenlight.blocked.macro.chain.01HX7DEF
|
||||
greenlight.done.planetary.infra.01HX7GHI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **DATABASE ENUM DEFINITIONS**
|
||||
|
||||
```sql
|
||||
CREATE TYPE gl_state AS ENUM (
|
||||
'void', 'inbox', 'queued', 'targeted', 'wip', 'active',
|
||||
'review', 'paused', 'blocked', 'branched', 'healing',
|
||||
'done', 'archived', 'canceled', 'dead'
|
||||
);
|
||||
|
||||
CREATE TYPE gl_scale AS ENUM (
|
||||
'micro', 'macro', 'planetary', 'universal'
|
||||
);
|
||||
|
||||
CREATE TYPE gl_domain AS ENUM (
|
||||
'platform', 'ai', 'chain', 'coin', 'intel', 'media',
|
||||
'audio', 'games', 'edu', 'security', 'gov', 'biz',
|
||||
'infra', 'creative', 'data', 'growth', 'partner', 'labs'
|
||||
);
|
||||
|
||||
CREATE TYPE gl_priority AS ENUM (
|
||||
'p0', 'p1', 'p2', 'p3', 'p4', 'p5'
|
||||
);
|
||||
|
||||
CREATE TYPE gl_effort AS ENUM (
|
||||
'xs', 's', 'm', 'l', 'xl', 'xxl', 'xxxl'
|
||||
);
|
||||
|
||||
CREATE TYPE gl_owner_type AS ENUM (
|
||||
'human', 'agent', 'system', 'team', 'hybrid', 'none'
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## **PHASE MARKERS FOR CLAUDE COLLABORATION**
|
||||
|
||||
Use these in memory logs for project coordination:
|
||||
|
||||
| Emoji | Phase | Code | Description |
|
||||
|-------|-------|------|-------------|
|
||||
| 🌱 | DISCOVERY | `discovery` | Research, exploration, learning |
|
||||
| 📐 | PLANNING | `planning` | Architecture, design, strategy |
|
||||
| 🔨 | IMPLEMENTATION | `implementation` | Building, coding, executing |
|
||||
| 🧪 | TESTING | `testing` | QA, validation, verification |
|
||||
| 🚀 | DEPLOYMENT | `deployment` | Ship, launch, release |
|
||||
| 📊 | MONITORING | `monitoring` | Observe, measure, optimize |
|
||||
| 🔄 | ITERATION | `iteration` | Improve, refine, evolve |
|
||||
|
||||
---
|
||||
|
||||
**This is now YOUR language. No more Jira. No more Asana. GreenLight speaks BlackRoad.** 🛣️
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**Author:** Cece + Alexa
|
||||
**Version:** 1.0.0
|
||||
**Status:** 🎯 CANONICAL
|
||||
493
.trinity/greenlight/docs/GREENLIGHT_LINEAR_EXTENSION.md
Normal file
493
.trinity/greenlight/docs/GREENLIGHT_LINEAR_EXTENSION.md
Normal file
@@ -0,0 +1,493 @@
|
||||
# 📋 GreenLight Linear Integration
|
||||
|
||||
**Extension to GreenLight for Linear Project Management**
|
||||
|
||||
---
|
||||
|
||||
## 📋 Linear Issue States
|
||||
|
||||
Map Linear statuses directly to GreenLight workflow:
|
||||
|
||||
| Linear Status | Linear Type | GreenLight Step | Emoji | GreenLight State | Trinary |
|
||||
|---------------|-------------|-----------------|-------|------------------|---------|
|
||||
| Backlog | backlog | 1 - Impulse | ⚡📋 | void | 0 |
|
||||
| Todo | unstarted | 3 - Capture | 📥📝 | inbox | 0 |
|
||||
| In Progress | started | 13 - Execute | ⚙️🔄 | wip | +1 |
|
||||
| In Review | started | 15 - Checkpoint | ✔️👀 | wip | +1 |
|
||||
| Done | completed | 19 - Complete | 🎉✅ | done | +1 |
|
||||
| Canceled | canceled | 27 - Archive | 📦❌ | void | -1 |
|
||||
| Duplicate | canceled | 27 - Archive | 📦🔁 | void | 0 |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Linear Labels as GreenLight Tags
|
||||
|
||||
| Label | Color | GreenLight Emoji | Domain | Description |
|
||||
|-------|-------|------------------|--------|-------------|
|
||||
| Feature | #BB87FC | ✨ | FEATURE | New functionality |
|
||||
| Bug | #EB5757 | 🐛 | BUG | Something broken |
|
||||
| Improvement | #4EA7FC | 🔧 | IMPROVEMENT | Enhancement |
|
||||
| Documentation | #8B8B8B | 📚 | DOCS | Documentation |
|
||||
| Infrastructure | #F5A623 | 🏗️ | INFRA | DevOps/CI/CD |
|
||||
| Security | #FF6B6B | 🔒 | SECURITY | Security issues |
|
||||
| Performance | #00D084 | ⚡ | PERFORMANCE | Optimization |
|
||||
| Design | #E91E63 | 🎨 | DESIGN | UI/UX |
|
||||
| Research | #9C27B0 | 🔬 | RESEARCH | R&D |
|
||||
| Tech Debt | #607D8B | 🧹 | TECH_DEBT | Cleanup |
|
||||
| Blocked | #F44336 | 🔒 | BLOCKED | Dependency wait |
|
||||
| GreenLight | #10B981 | 🚦 | GREENLIGHT | GreenLight system |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Linear Priorities
|
||||
|
||||
Map to GreenLight priority tags:
|
||||
|
||||
| Linear | Value | GreenLight | Emoji | Use Case |
|
||||
|--------|-------|------------|-------|----------|
|
||||
| Urgent | 1 | FIRE | 🔥 | Critical bugs, security |
|
||||
| High | 2 | HIGH | ⭐ | Important features, blockers |
|
||||
| Normal | 3 | MEDIUM | 📌 | Standard work |
|
||||
| Low | 4 | LOW | 💤 | Nice to have |
|
||||
| No priority | 0 | NONE | ⚪ | Unprioritized |
|
||||
|
||||
---
|
||||
|
||||
## 📁 Linear Projects
|
||||
|
||||
Recommended projects for BlackRoad OS:
|
||||
|
||||
| Project | Emoji | GreenLight Domain | Description |
|
||||
|---------|-------|-------------------|-------------|
|
||||
| Lucidia | 🧠 | AI (🌀) | Core Lucidia AI system |
|
||||
| BlackRoad Platform | 🛣️ | Platform (🛣️) | Main platform development |
|
||||
| Agent Ecosystem | 🤖 | AI (🌀) | 1000 agents project |
|
||||
| GreenLight | 🚦 | Platform (🛣️) | Workflow & state system |
|
||||
| Infrastructure | 🏗️ | Infrastructure (🔧) | DevOps, Cloudflare |
|
||||
| Documentation | 📚 | Documentation (📚) | Docs, guides |
|
||||
| Research | 🔬 | Research (🔬) | R&D, experiments |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for Linear
|
||||
|
||||
### Issue Creation
|
||||
```
|
||||
⚡📋👉📌 = New issue in backlog, micro scale
|
||||
✨📋🎢⭐ = Feature request, macro scale, high priority
|
||||
🐛📋👉🔥 = Bug report, micro scale, urgent
|
||||
```
|
||||
|
||||
### Issue Workflow
|
||||
```
|
||||
📥📝👉📌 = Todo, micro scale, medium priority
|
||||
⚙️🔄🎢⭐ = In Progress, macro scale, high priority
|
||||
✔️👀👉📌 = In Review, micro scale
|
||||
🎉✅🎢🌍 = Completed, macro impact
|
||||
```
|
||||
|
||||
### Labels + Priorities
|
||||
```
|
||||
✨🎢⭐📣 = Feature, macro, high priority
|
||||
🐛👉🔥🚨 = Bug, micro, urgent
|
||||
🔒🎢🔥⚠️ = Security issue, macro, urgent
|
||||
⚡👉⭐📊 = Performance, micro, high priority
|
||||
```
|
||||
|
||||
### Full Issue Lifecycle
|
||||
```
|
||||
[⚡📋] [📥📝] [⚙️🔄] [✔️👀] [🎉✅] = Backlog → Todo → In Progress → Review → Done
|
||||
[🐛🔥] [⚙️🔄] [🎉✅] = Bug urgent → Fix → Done
|
||||
[✨⭐] [📥📝] [⚙️🔄] [🎉✅] = Feature high → Planned → Building → Shipped
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (Linear)
|
||||
|
||||
### Issue Events
|
||||
```
|
||||
greenlight.issue.created.micro.platform.{identifier}
|
||||
greenlight.issue.updated.micro.platform.{identifier}
|
||||
greenlight.issue.completed.macro.platform.{identifier}
|
||||
greenlight.issue.canceled.micro.platform.{identifier}
|
||||
```
|
||||
|
||||
### State Changes
|
||||
```
|
||||
greenlight.issue.todo.micro.platform.{identifier}
|
||||
greenlight.issue.in_progress.micro.platform.{identifier}
|
||||
greenlight.issue.in_review.micro.platform.{identifier}
|
||||
greenlight.issue.done.macro.platform.{identifier}
|
||||
```
|
||||
|
||||
### Label-Specific
|
||||
```
|
||||
greenlight.bug.reported.micro.platform.{identifier}
|
||||
greenlight.feature.requested.macro.platform.{identifier}
|
||||
greenlight.security.critical.macro.platform.{identifier}
|
||||
greenlight.blocked.waiting.micro.platform.{identifier}
|
||||
```
|
||||
|
||||
### Project Events
|
||||
```
|
||||
greenlight.project.created.macro.platform.{project_name}
|
||||
greenlight.project.completed.macro.platform.{project_name}
|
||||
```
|
||||
|
||||
### Comment Events
|
||||
```
|
||||
greenlight.comment.added.micro.platform.{identifier}
|
||||
greenlight.command.greenlight.micro.platform.{identifier}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Linear Memory Templates
|
||||
|
||||
### Issue Operations
|
||||
|
||||
```bash
|
||||
# Issue created
|
||||
gl_issue_created() {
|
||||
local identifier="$1" # BLA-123
|
||||
local title="$2"
|
||||
local label="${3:-feature}"
|
||||
|
||||
local label_emoji=""
|
||||
case "$label" in
|
||||
feature) label_emoji="✨" ;;
|
||||
bug) label_emoji="🐛" ;;
|
||||
improvement) label_emoji="🔧" ;;
|
||||
security) label_emoji="🔒" ;;
|
||||
performance) label_emoji="⚡" ;;
|
||||
*) label_emoji="📋" ;;
|
||||
esac
|
||||
|
||||
gl_log "⚡${label_emoji}👉📌" \
|
||||
"issue_created" \
|
||||
"$identifier" \
|
||||
"$title"
|
||||
}
|
||||
|
||||
# Issue state changed
|
||||
gl_issue_state_changed() {
|
||||
local identifier="$1"
|
||||
local old_state="$2"
|
||||
local new_state="$3"
|
||||
|
||||
local state_emoji=""
|
||||
case "$new_state" in
|
||||
"Todo") state_emoji="📥📝" ;;
|
||||
"In Progress") state_emoji="⚙️🔄" ;;
|
||||
"In Review") state_emoji="✔️👀" ;;
|
||||
"Done") state_emoji="🎉✅" ;;
|
||||
"Canceled") state_emoji="📦❌" ;;
|
||||
*) state_emoji="📋" ;;
|
||||
esac
|
||||
|
||||
gl_log "${state_emoji}👉📌" \
|
||||
"state_changed" \
|
||||
"$identifier" \
|
||||
"$old_state → $new_state"
|
||||
}
|
||||
|
||||
# Issue completed
|
||||
gl_issue_completed() {
|
||||
local identifier="$1"
|
||||
local title="$2"
|
||||
local duration="${3:-unknown}"
|
||||
|
||||
gl_log "🎉✅🎢🌍" \
|
||||
"issue_completed" \
|
||||
"$identifier" \
|
||||
"$title (completed in $duration)"
|
||||
}
|
||||
|
||||
# Issue blocked
|
||||
gl_issue_blocked() {
|
||||
local identifier="$1"
|
||||
local reason="$2"
|
||||
|
||||
gl_log "🔒⚠️👉🔥" \
|
||||
"issue_blocked" \
|
||||
"$identifier" \
|
||||
"Blocked: $reason"
|
||||
}
|
||||
|
||||
# Issue assigned
|
||||
gl_issue_assigned() {
|
||||
local identifier="$1"
|
||||
local assignee="$2"
|
||||
|
||||
gl_log "👤📋👉📌" \
|
||||
"issue_assigned" \
|
||||
"$identifier" \
|
||||
"Assigned to: $assignee"
|
||||
}
|
||||
|
||||
# Issue prioritized
|
||||
gl_issue_prioritized() {
|
||||
local identifier="$1"
|
||||
local priority="$2"
|
||||
|
||||
local priority_emoji=""
|
||||
case "$priority" in
|
||||
1) priority_emoji="🔥" ;;
|
||||
2) priority_emoji="⭐" ;;
|
||||
3) priority_emoji="📌" ;;
|
||||
4) priority_emoji="💤" ;;
|
||||
*) priority_emoji="⚪" ;;
|
||||
esac
|
||||
|
||||
gl_log "${priority_emoji}📋👉📌" \
|
||||
"issue_prioritized" \
|
||||
"$identifier" \
|
||||
"Priority: $priority"
|
||||
}
|
||||
```
|
||||
|
||||
### Project Operations
|
||||
|
||||
```bash
|
||||
# Project created
|
||||
gl_project_created() {
|
||||
local project_name="$1"
|
||||
local description="$2"
|
||||
|
||||
gl_log "📁🚀🎢✅" \
|
||||
"project_created" \
|
||||
"$project_name" \
|
||||
"$description"
|
||||
}
|
||||
|
||||
# Project completed
|
||||
gl_project_completed() {
|
||||
local project_name="$1"
|
||||
local issues_count="$2"
|
||||
|
||||
gl_log "📁🎉🎢🌍" \
|
||||
"project_completed" \
|
||||
"$project_name" \
|
||||
"$issues_count issues completed"
|
||||
}
|
||||
```
|
||||
|
||||
### Comment Operations
|
||||
|
||||
```bash
|
||||
# Comment added
|
||||
gl_comment_added() {
|
||||
local identifier="$1"
|
||||
local user="$2"
|
||||
local preview="${3:0:50}"
|
||||
|
||||
gl_log "💬📋👉📌" \
|
||||
"comment_added" \
|
||||
"$identifier" \
|
||||
"$user: $preview..."
|
||||
}
|
||||
|
||||
# GreenLight command detected
|
||||
gl_command_detected() {
|
||||
local identifier="$1"
|
||||
local command="$2"
|
||||
|
||||
gl_log "🚦📋👉⭐" \
|
||||
"command_detected" \
|
||||
"$identifier" \
|
||||
"GreenLight command: $command"
|
||||
}
|
||||
```
|
||||
|
||||
### GitHub Integration
|
||||
|
||||
```bash
|
||||
# PR linked to issue
|
||||
gl_pr_linked() {
|
||||
local identifier="$1"
|
||||
local pr_url="$2"
|
||||
|
||||
gl_log "🔗📋🎢📌" \
|
||||
"pr_linked" \
|
||||
"$identifier" \
|
||||
"PR: $pr_url"
|
||||
}
|
||||
|
||||
# PR merged, issue closed
|
||||
gl_pr_merged() {
|
||||
local identifier="$1"
|
||||
local pr_number="$2"
|
||||
|
||||
gl_log "✅🔗🎢🎉" \
|
||||
"pr_merged" \
|
||||
"$identifier" \
|
||||
"PR #$pr_number merged, issue completed"
|
||||
}
|
||||
|
||||
# Branch created from issue
|
||||
gl_branch_created() {
|
||||
local identifier="$1"
|
||||
local branch_name="$2"
|
||||
|
||||
gl_log "🌿📋👉📌" \
|
||||
"branch_created" \
|
||||
"$identifier" \
|
||||
"Branch: $branch_name"
|
||||
}
|
||||
```
|
||||
|
||||
### Cycle (Sprint) Operations
|
||||
|
||||
```bash
|
||||
# Cycle started
|
||||
gl_cycle_started() {
|
||||
local cycle_name="$1"
|
||||
local duration="$2"
|
||||
|
||||
gl_log "🔄🚀🎢⭐" \
|
||||
"cycle_started" \
|
||||
"$cycle_name" \
|
||||
"Sprint started: $duration"
|
||||
}
|
||||
|
||||
# Cycle completed
|
||||
gl_cycle_completed() {
|
||||
local cycle_name="$1"
|
||||
local completed_count="$2"
|
||||
local total_count="$3"
|
||||
|
||||
gl_log "🔄🎉🎢🌍" \
|
||||
"cycle_completed" \
|
||||
"$cycle_name" \
|
||||
"Sprint complete: $completed_count/$total_count issues"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Complete Issue Lifecycle
|
||||
|
||||
### Scenario: Bug report and fix
|
||||
|
||||
```bash
|
||||
# 1. Bug reported
|
||||
gl_issue_created "BLA-42" "Login fails with OAuth" "bug"
|
||||
# [⚡🐛👉📌] issue_created: BLA-42 — Login fails with OAuth
|
||||
|
||||
# 2. Prioritized as urgent
|
||||
gl_issue_prioritized "BLA-42" "1"
|
||||
# [🔥📋👉📌] issue_prioritized: BLA-42 — Priority: 1
|
||||
|
||||
# 3. Assigned
|
||||
gl_issue_assigned "BLA-42" "alexa"
|
||||
# [👤📋👉📌] issue_assigned: BLA-42 — Assigned to: alexa
|
||||
|
||||
# 4. Moved to In Progress
|
||||
gl_issue_state_changed "BLA-42" "Todo" "In Progress"
|
||||
# [⚙️🔄👉📌] state_changed: BLA-42 — Todo → In Progress
|
||||
|
||||
# 5. Branch created
|
||||
gl_branch_created "BLA-42" "bla-42-fix-oauth-login"
|
||||
# [🌿📋👉📌] branch_created: BLA-42 — Branch: bla-42-fix-oauth-login
|
||||
|
||||
# 6. PR opened
|
||||
gl_pr_linked "BLA-42" "https://github.com/blackroad/api/pull/123"
|
||||
# [🔗📋🎢📌] pr_linked: BLA-42 — PR: https://github.com/blackroad/api/pull/123
|
||||
|
||||
# 7. Moved to In Review
|
||||
gl_issue_state_changed "BLA-42" "In Progress" "In Review"
|
||||
# [✔️👀👉📌] state_changed: BLA-42 — In Progress → In Review
|
||||
|
||||
# 8. PR merged
|
||||
gl_pr_merged "BLA-42" "123"
|
||||
# [✅🔗🎢🎉] pr_merged: BLA-42 — PR #123 merged, issue completed
|
||||
|
||||
# 9. Issue completed
|
||||
gl_issue_completed "BLA-42" "Login fails with OAuth" "3h 24m"
|
||||
# [🎉✅🎢🌍] issue_completed: BLA-42 — Login fails with OAuth (completed in 3h 24m)
|
||||
```
|
||||
|
||||
### Scenario: Feature request lifecycle
|
||||
|
||||
```bash
|
||||
# 1. Feature requested
|
||||
gl_issue_created "BLA-100" "Add dark mode toggle" "feature"
|
||||
# [⚡✨👉📌] issue_created: BLA-100 — Add dark mode toggle
|
||||
|
||||
# 2. High priority
|
||||
gl_issue_prioritized "BLA-100" "2"
|
||||
# [⭐📋👉📌] issue_prioritized: BLA-100 — Priority: 2
|
||||
|
||||
# 3. Added to project
|
||||
gl_log "📁✅👉📌" "project_added" "BLA-100" "Added to BlackRoad Platform project"
|
||||
|
||||
# 4. Start work
|
||||
gl_issue_state_changed "BLA-100" "Backlog" "In Progress"
|
||||
# [⚙️🔄👉📌] state_changed: BLA-100 — Backlog → In Progress
|
||||
|
||||
# 5. Comment added
|
||||
gl_comment_added "BLA-100" "designer" "Figma designs ready for implementation"
|
||||
# [💬📋👉📌] comment_added: BLA-100 — designer: Figma designs ready for implementation...
|
||||
|
||||
# 6. Complete
|
||||
gl_issue_completed "BLA-100" "Add dark mode toggle" "2 days"
|
||||
# [🎉✅🎢🌍] issue_completed: BLA-100 — Add dark mode toggle (completed in 2 days)
|
||||
```
|
||||
|
||||
### Scenario: Blocked issue
|
||||
|
||||
```bash
|
||||
# 1. Start work
|
||||
gl_issue_state_changed "BLA-87" "Todo" "In Progress"
|
||||
# [⚙️🔄👉📌] state_changed: BLA-87 — Todo → In Progress
|
||||
|
||||
# 2. Hit blocker
|
||||
gl_issue_blocked "BLA-87" "Waiting for API authentication endpoint (BLA-88)"
|
||||
# [🔒⚠️👉🔥] issue_blocked: BLA-87 — Blocked: Waiting for API authentication endpoint (BLA-88)
|
||||
|
||||
# 3. Blocker resolved
|
||||
gl_log "🔓✅👉⭐" "blocker_resolved" "BLA-87" "BLA-88 completed, can proceed"
|
||||
|
||||
# 4. Resume work
|
||||
gl_issue_state_changed "BLA-87" "Blocked" "In Progress"
|
||||
# [⚙️🔄👉📌] state_changed: BLA-87 — Blocked → In Progress
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Linear Workspace Details
|
||||
|
||||
**Workspace:** Blackboxprogramming
|
||||
**URL:** https://linear.app/blackboxprogramming
|
||||
**Team ID:** c33efc9b-38b7-43f3-bccf-eb93ad2e3f93
|
||||
**Issue Prefix:** BLA-
|
||||
**API:** https://api.linear.app/graphql
|
||||
|
||||
### Current Setup:
|
||||
- **Team:** 1 (Blackboxprogramming)
|
||||
- **Projects:** 1 (Lucidia) + 7 recommended
|
||||
- **States:** 7 (Backlog, Todo, In Progress, In Review, Done, Canceled, Duplicate)
|
||||
- **Labels:** 3 (Feature, Bug, Improvement) + 9 recommended
|
||||
- **Priorities:** 5 (0-4, urgent to no priority)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Mapped Linear states to GreenLight 27-step workflow
|
||||
- [x] Created label-to-emoji mappings
|
||||
- [x] Mapped priorities to GreenLight tags
|
||||
- [x] Extended NATS subjects for issue/project events
|
||||
- [x] Built 15+ Linear-specific templates
|
||||
- [x] Integrated with GitHub (PR linking, branch creation)
|
||||
- [x] Added mobile integration patterns
|
||||
- [x] Created D1 schema for sync
|
||||
- [x] Webhook handler with GreenLight logging
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** Linear Project Management Integration
|
||||
**Version:** 2.0.0-linear
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
513
.trinity/greenlight/docs/GREENLIGHT_NOTION_EXTENSION.md
Normal file
513
.trinity/greenlight/docs/GREENLIGHT_NOTION_EXTENSION.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# 📝 GreenLight Notion Integration
|
||||
|
||||
**Extension to GreenLight for Notion Knowledge Management**
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notion Events as GreenLight Steps
|
||||
|
||||
Map Notion events directly to GreenLight workflow:
|
||||
|
||||
| Notion Event | GreenLight Step | Step # | Emoji | State Transition | Context |
|
||||
|--------------|-----------------|--------|-------|------------------|---------|
|
||||
| Page created | ⚡ Impulse | 1 | ⚡📄 | void → inbox | any database |
|
||||
| Database item added | 📥 Capture | 3 | 📥📊 | → inbox | any database |
|
||||
| Comment added | 💬 Collaborate | 11 | 💬📝 | → wip | any page |
|
||||
| Page updated | ⚙️ Execute | 13 | ⚙️✏️ | → wip | any page |
|
||||
| Task completed | ✅ Approve | 7 | ✅☑️ | → queued | task database |
|
||||
| Page published | 🎉 Complete | 19 | 🎉📰 | wip → done | public pages |
|
||||
| Page archived | 📦 Archive | 27 | 📦🗄️ | → void | any page |
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Notion Database Categories
|
||||
|
||||
Recommended database structure with GreenLight mappings:
|
||||
|
||||
| Emoji | Database | Purpose | GreenLight Domain | Properties |
|
||||
|-------|----------|---------|-------------------|------------|
|
||||
| 📋 | Tasks | Task management | Platform (🛣️) | Status, Priority, Assignee |
|
||||
| 📚 | Documentation | Knowledge base | Documentation (📚) | Category, Status, Tags |
|
||||
| 🎯 | Projects | Project tracking | Platform (🛣️) | Phase, Owner, Timeline |
|
||||
| 🧠 | Ideas | Innovation backlog | Research (🔬) | Stage, Votes, Feasibility |
|
||||
| 👥 | Team | People directory | Platform (🛣️) | Role, Department, Skills |
|
||||
| 📊 | Metrics | KPI tracking | Platform (🛣️) | Value, Target, Trend |
|
||||
| 🎨 | Design | Design system | Design (🎨) | Type, Status, Figma link |
|
||||
| 💼 | Clients | Client management | Platform (🛣️) | Tier, Status, Revenue |
|
||||
| 🔬 | Research | R&D notes | Research (🔬) | Topic, Status, Findings |
|
||||
| 📅 | Events | Calendar/meetings | Platform (🛣️) | Date, Type, Attendees |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Notion Property Types as GreenLight Tags
|
||||
|
||||
| Property Type | Emoji | GreenLight Usage | Example |
|
||||
|---------------|-------|------------------|---------|
|
||||
| Status | 🚦 | Workflow state | Not started, In Progress, Done |
|
||||
| Priority | 🔥 | Priority level | High, Medium, Low |
|
||||
| Person | 👤 | Assignment | @alexa, @team |
|
||||
| Date | 📅 | Timeline | Due date, Created date |
|
||||
| Checkbox | ☑️ | Binary state | Completed, Published |
|
||||
| Select | 🏷️ | Category | Type, Category, Stage |
|
||||
| Multi-select | 🏷️🏷️ | Tags | Tags, Labels, Skills |
|
||||
| Relation | 🔗 | Cross-reference | Related pages, Dependencies |
|
||||
| Rollup | 📊 | Aggregation | Count, Sum, Average |
|
||||
| Formula | 🧮 | Computed | Progress %, Days remaining |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for Notion
|
||||
|
||||
### Page Operations
|
||||
```
|
||||
⚡📄👉📌 = New page created, micro scale
|
||||
📝✏️🎢📚 = Documentation updated, macro scale
|
||||
🎉📰🎢🌍 = Page published, macro impact
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
```
|
||||
📊📥👉📌 = Database item added, micro
|
||||
☑️✅👉📌 = Task completed
|
||||
🔗📊🎢📌 = Relation created, macro
|
||||
```
|
||||
|
||||
### Collaboration Events
|
||||
```
|
||||
💬📝👉⭐ = Comment added, high priority
|
||||
👥📄👉📌 = Page shared with team
|
||||
🔔📄👉⭐ = Page mention notification
|
||||
```
|
||||
|
||||
### Content Updates
|
||||
```
|
||||
⚙️✏️👉📌 = Page edited, micro
|
||||
📸🎨🎢⭐ = Image/design added, macro, high priority
|
||||
🔢📊👉📌 = Data updated in database
|
||||
```
|
||||
|
||||
### Full Notion Flow
|
||||
```
|
||||
[⚡📄] [📝✏️] [💬📝] [✅☑️] [🎉📰] = Create → Edit → Comment → Approve → Publish
|
||||
[📊📥] [🔢📊] [🔗📊] [📈✅] = DB add → Update → Relate → Complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (Notion)
|
||||
|
||||
### Page Events
|
||||
```
|
||||
greenlight.notion.page.created.micro.docs.{page_id}
|
||||
greenlight.notion.page.updated.micro.docs.{page_id}
|
||||
greenlight.notion.page.deleted.micro.docs.{page_id}
|
||||
greenlight.notion.page.published.macro.docs.{page_id}
|
||||
```
|
||||
|
||||
### Database Events
|
||||
```
|
||||
greenlight.notion.database.item_added.micro.platform.{database_id}
|
||||
greenlight.notion.database.item_updated.micro.platform.{database_id}
|
||||
greenlight.notion.database.item_deleted.micro.platform.{database_id}
|
||||
```
|
||||
|
||||
### Property Events
|
||||
```
|
||||
greenlight.notion.property.status_changed.micro.platform.{page_id}
|
||||
greenlight.notion.property.assigned.micro.platform.{page_id}
|
||||
greenlight.notion.property.date_set.micro.platform.{page_id}
|
||||
```
|
||||
|
||||
### Block Events
|
||||
```
|
||||
greenlight.notion.block.added.micro.docs.{block_id}
|
||||
greenlight.notion.block.updated.micro.docs.{block_id}
|
||||
greenlight.notion.block.moved.micro.docs.{block_id}
|
||||
```
|
||||
|
||||
### Comment Events
|
||||
```
|
||||
greenlight.notion.comment.added.micro.docs.{page_id}
|
||||
greenlight.notion.comment.resolved.micro.docs.{comment_id}
|
||||
greenlight.notion.mention.received.micro.docs.{user_id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Notion Memory Templates
|
||||
|
||||
### Page Operations
|
||||
|
||||
```bash
|
||||
# Page created
|
||||
gl_notion_page_created() {
|
||||
local page_title="$1"
|
||||
local database="$2"
|
||||
local creator="${3:-unknown}"
|
||||
|
||||
gl_log "⚡📄👉📌" \
|
||||
"page_created" \
|
||||
"$page_title" \
|
||||
"Database: $database, Creator: $creator"
|
||||
}
|
||||
|
||||
# Page updated
|
||||
gl_notion_page_updated() {
|
||||
local page_title="$1"
|
||||
local update_type="${2:-content}" # content, properties, title
|
||||
|
||||
local update_emoji=""
|
||||
case "$update_type" in
|
||||
content) update_emoji="✏️" ;;
|
||||
properties) update_emoji="🔢" ;;
|
||||
title) update_emoji="📝" ;;
|
||||
*) update_emoji="⚙️" ;;
|
||||
esac
|
||||
|
||||
gl_log "${update_emoji}📄👉📌" \
|
||||
"page_updated" \
|
||||
"$page_title" \
|
||||
"Type: $update_type"
|
||||
}
|
||||
|
||||
# Page published
|
||||
gl_notion_page_published() {
|
||||
local page_title="$1"
|
||||
local public_url="$2"
|
||||
|
||||
gl_log "🎉📰🎢🌍" \
|
||||
"page_published" \
|
||||
"$page_title" \
|
||||
"Public URL: $public_url"
|
||||
}
|
||||
|
||||
# Page archived
|
||||
gl_notion_page_archived() {
|
||||
local page_title="$1"
|
||||
local reason="${2:-manual}"
|
||||
|
||||
gl_log "📦🗄️👉📌" \
|
||||
"page_archived" \
|
||||
"$page_title" \
|
||||
"Reason: $reason"
|
||||
}
|
||||
|
||||
# Page shared
|
||||
gl_notion_page_shared() {
|
||||
local page_title="$1"
|
||||
local shared_with="$2"
|
||||
local permission="${3:-read}"
|
||||
|
||||
gl_log "👥📄👉📌" \
|
||||
"page_shared" \
|
||||
"$page_title" \
|
||||
"With: $shared_with, Permission: $permission"
|
||||
}
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
|
||||
```bash
|
||||
# Database item added
|
||||
gl_notion_db_item_added() {
|
||||
local database_name="$1"
|
||||
local item_title="$2"
|
||||
local item_id="${3:-unknown}"
|
||||
|
||||
gl_log "📊📥👉📌" \
|
||||
"db_item_added" \
|
||||
"$database_name" \
|
||||
"$item_title ($item_id)"
|
||||
}
|
||||
|
||||
# Database item updated
|
||||
gl_notion_db_item_updated() {
|
||||
local database_name="$1"
|
||||
local item_title="$2"
|
||||
local properties_changed="$3"
|
||||
|
||||
gl_log "🔢📊👉📌" \
|
||||
"db_item_updated" \
|
||||
"$database_name" \
|
||||
"$item_title - Changed: $properties_changed"
|
||||
}
|
||||
|
||||
# Status changed
|
||||
gl_notion_status_changed() {
|
||||
local item_title="$1"
|
||||
local old_status="$2"
|
||||
local new_status="$3"
|
||||
|
||||
local status_emoji=""
|
||||
case "$new_status" in
|
||||
"Not started") status_emoji="⚪" ;;
|
||||
"In progress") status_emoji="🔵" ;;
|
||||
"Done") status_emoji="✅" ;;
|
||||
"Blocked") status_emoji="🔴" ;;
|
||||
*) status_emoji="🚦" ;;
|
||||
esac
|
||||
|
||||
gl_log "${status_emoji}🚦👉📌" \
|
||||
"status_changed" \
|
||||
"$item_title" \
|
||||
"$old_status → $new_status"
|
||||
}
|
||||
|
||||
# Task completed
|
||||
gl_notion_task_completed() {
|
||||
local task_title="$1"
|
||||
local assignee="$2"
|
||||
local duration="${3:-unknown}"
|
||||
|
||||
gl_log "☑️✅🎢📌" \
|
||||
"task_completed" \
|
||||
"$task_title" \
|
||||
"By: $assignee, Duration: $duration"
|
||||
}
|
||||
|
||||
# Relation created
|
||||
gl_notion_relation_created() {
|
||||
local source_page="$1"
|
||||
local target_page="$2"
|
||||
local relation_type="${3:-related}"
|
||||
|
||||
gl_log "🔗📊🎢📌" \
|
||||
"relation_created" \
|
||||
"$source_page" \
|
||||
"→ $target_page ($relation_type)"
|
||||
}
|
||||
```
|
||||
|
||||
### Comment Operations
|
||||
|
||||
```bash
|
||||
# Comment added
|
||||
gl_notion_comment_added() {
|
||||
local page_title="$1"
|
||||
local commenter="$2"
|
||||
local preview="${3:0:50}"
|
||||
|
||||
gl_log "💬📝👉⭐" \
|
||||
"comment_added" \
|
||||
"$page_title" \
|
||||
"$commenter: $preview..."
|
||||
}
|
||||
|
||||
# Comment resolved
|
||||
gl_notion_comment_resolved() {
|
||||
local page_title="$1"
|
||||
local resolver="$2"
|
||||
|
||||
gl_log "✅💬👉📌" \
|
||||
"comment_resolved" \
|
||||
"$page_title" \
|
||||
"Resolved by: $resolver"
|
||||
}
|
||||
|
||||
# Mention received
|
||||
gl_notion_mention() {
|
||||
local user="$1"
|
||||
local page_title="$2"
|
||||
local mentioner="$3"
|
||||
|
||||
gl_log "🔔📄👉⭐" \
|
||||
"mention_received" \
|
||||
"$user" \
|
||||
"In: $page_title by $mentioner"
|
||||
}
|
||||
```
|
||||
|
||||
### Block Operations
|
||||
|
||||
```bash
|
||||
# Block added
|
||||
gl_notion_block_added() {
|
||||
local block_type="$1" # heading, paragraph, code, image, etc.
|
||||
local page_title="$2"
|
||||
|
||||
local block_emoji=""
|
||||
case "$block_type" in
|
||||
heading_1|heading_2|heading_3) block_emoji="📌" ;;
|
||||
paragraph) block_emoji="📝" ;;
|
||||
code) block_emoji="💻" ;;
|
||||
image) block_emoji="🖼️" ;;
|
||||
table) block_emoji="📊" ;;
|
||||
bullet_list) block_emoji="📋" ;;
|
||||
*) block_emoji="📄" ;;
|
||||
esac
|
||||
|
||||
gl_log "${block_emoji}➕👉📌" \
|
||||
"block_added" \
|
||||
"$page_title" \
|
||||
"Block type: $block_type"
|
||||
}
|
||||
|
||||
# Block updated
|
||||
gl_notion_block_updated() {
|
||||
local block_type="$1"
|
||||
local page_title="$2"
|
||||
local change="${3:-content}"
|
||||
|
||||
gl_log "⚙️📝👉📌" \
|
||||
"block_updated" \
|
||||
"$page_title" \
|
||||
"$block_type updated: $change"
|
||||
}
|
||||
```
|
||||
|
||||
### Sync Operations
|
||||
|
||||
```bash
|
||||
# Notion sync started
|
||||
gl_notion_sync_started() {
|
||||
local sync_type="$1" # full, incremental
|
||||
local databases="$2"
|
||||
|
||||
gl_log "🔄📊👉📌" \
|
||||
"sync_started" \
|
||||
"$sync_type" \
|
||||
"Databases: $databases"
|
||||
}
|
||||
|
||||
# Notion sync completed
|
||||
gl_notion_sync_completed() {
|
||||
local sync_type="$1"
|
||||
local items_synced="$2"
|
||||
local duration="$3"
|
||||
|
||||
gl_log "✅🔄🎢📌" \
|
||||
"sync_completed" \
|
||||
"$sync_type" \
|
||||
"$items_synced items synced in $duration"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Complete Notion Workflow
|
||||
|
||||
### Scenario: Documentation page creation and collaboration
|
||||
|
||||
```bash
|
||||
# 1. Page created in Documentation database
|
||||
gl_notion_page_created "API Authentication Guide" "Documentation" "alexa"
|
||||
# [⚡📄👉📌] page_created: API Authentication Guide — Database: Documentation, Creator: alexa
|
||||
|
||||
# 2. Content added
|
||||
gl_notion_block_added "heading_1" "API Authentication Guide"
|
||||
# [📌➕👉📌] block_added: API Authentication Guide — Block type: heading_1
|
||||
|
||||
gl_notion_block_added "code" "API Authentication Guide"
|
||||
# [💻➕👉📌] block_added: API Authentication Guide — Block type: code
|
||||
|
||||
# 3. Page updated with more content
|
||||
gl_notion_page_updated "API Authentication Guide" "content"
|
||||
# [✏️📄👉📌] page_updated: API Authentication Guide — Type: content
|
||||
|
||||
# 4. Team member adds comment
|
||||
gl_notion_comment_added "API Authentication Guide" "developer" "Should we add OAuth2 flow example?"
|
||||
# [💬📝👉⭐] comment_added: API Authentication Guide — developer: Should we add OAuth2 flow example?...
|
||||
|
||||
# 5. Owner responds and resolves
|
||||
gl_notion_comment_resolved "API Authentication Guide" "alexa"
|
||||
# [✅💬👉📌] comment_resolved: API Authentication Guide — Resolved by: alexa
|
||||
|
||||
# 6. Page published
|
||||
gl_notion_page_published "API Authentication Guide" "https://blackroad.notion.site/api-auth"
|
||||
# [🎉📰🎢🌍] page_published: API Authentication Guide — Public URL: https://blackroad.notion.site/api-auth
|
||||
```
|
||||
|
||||
### Scenario: Task management workflow
|
||||
|
||||
```bash
|
||||
# 1. Task added to database
|
||||
gl_notion_db_item_added "Tasks" "Implement Notion webhook handler" "task-123"
|
||||
# [📊📥👉📌] db_item_added: Tasks — Implement Notion webhook handler (task-123)
|
||||
|
||||
# 2. Status changed to In Progress
|
||||
gl_notion_status_changed "Implement Notion webhook handler" "Not started" "In progress"
|
||||
# [🔵🚦👉📌] status_changed: Implement Notion webhook handler — Not started → In progress
|
||||
|
||||
# 3. Task updated with notes
|
||||
gl_notion_db_item_updated "Tasks" "Implement Notion webhook handler" "Notes, Code snippet"
|
||||
# [🔢📊👉📌] db_item_updated: Tasks — Implement Notion webhook handler - Changed: Notes, Code snippet
|
||||
|
||||
# 4. Related to documentation page
|
||||
gl_notion_relation_created "Implement Notion webhook handler" "API Authentication Guide" "references"
|
||||
# [🔗📊🎢📌] relation_created: Implement Notion webhook handler — → API Authentication Guide (references)
|
||||
|
||||
# 5. Task completed
|
||||
gl_notion_task_completed "Implement Notion webhook handler" "alexa" "2h 45m"
|
||||
# [☑️✅🎢📌] task_completed: Implement Notion webhook handler — By: alexa, Duration: 2h 45m
|
||||
|
||||
# 6. Status changed to Done
|
||||
gl_notion_status_changed "Implement Notion webhook handler" "In progress" "Done"
|
||||
# [✅🚦👉📌] status_changed: Implement Notion webhook handler — In progress → Done
|
||||
```
|
||||
|
||||
### Scenario: Full sync operation
|
||||
|
||||
```bash
|
||||
# 1. Start sync
|
||||
gl_notion_sync_started "incremental" "Tasks, Documentation, Projects"
|
||||
# [🔄📊👉📌] sync_started: incremental — Databases: Tasks, Documentation, Projects
|
||||
|
||||
# 2. Sync completes
|
||||
gl_notion_sync_completed "incremental" "47" "3.2s"
|
||||
# [✅🔄🎢📌] sync_completed: incremental — 47 items synced in 3.2s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Notion Integration Details
|
||||
|
||||
**Workspace:** BlackRoad OS Workspace
|
||||
**API Version:** 2022-06-28
|
||||
**API Endpoint:** https://api.notion.com/v1/
|
||||
|
||||
### Recommended Databases:
|
||||
|
||||
1. **Tasks** (📋)
|
||||
- Properties: Title, Status, Priority, Assignee, Due Date, Tags
|
||||
- Views: Board, List, Calendar, Timeline
|
||||
|
||||
2. **Documentation** (📚)
|
||||
- Properties: Title, Category, Status, Tags, Last Updated
|
||||
- Views: Gallery, Table, Timeline
|
||||
|
||||
3. **Projects** (🎯)
|
||||
- Properties: Title, Phase, Owner, Start Date, End Date, Status
|
||||
- Views: Timeline, Board, Table
|
||||
|
||||
4. **Ideas** (🧠)
|
||||
- Properties: Title, Stage, Votes, Feasibility, Owner
|
||||
- Views: Gallery, Board, Table
|
||||
|
||||
5. **Team** (👥)
|
||||
- Properties: Name, Role, Department, Skills, Email
|
||||
- Views: Gallery, Table
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Mapped Notion events to GreenLight 27-step workflow
|
||||
- [x] Created database-to-domain mappings
|
||||
- [x] Defined property types as GreenLight tags
|
||||
- [x] Extended NATS subjects for Notion events
|
||||
- [x] Built 15+ Notion-specific templates
|
||||
- [x] Page lifecycle tracking
|
||||
- [x] Database CRUD operations
|
||||
- [x] Comment and collaboration events
|
||||
- [x] Block-level operations
|
||||
- [x] Sync operations
|
||||
- [x] Relation tracking
|
||||
- [x] Status transitions
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** Notion Knowledge Management Integration
|
||||
**Version:** 2.0.0-notion
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
|
||||
504
.trinity/greenlight/docs/GREENLIGHT_SLACK_EXTENSION.md
Normal file
504
.trinity/greenlight/docs/GREENLIGHT_SLACK_EXTENSION.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# 💬 GreenLight Slack Integration
|
||||
|
||||
**Extension to GreenLight for Slack Team Communication**
|
||||
|
||||
---
|
||||
|
||||
## 💬 Slack Events as GreenLight Steps
|
||||
|
||||
Map Slack events directly to GreenLight workflow:
|
||||
|
||||
| Slack Event | GreenLight Step | Step # | Emoji | State Transition | Channel |
|
||||
|-------------|-----------------|--------|-------|------------------|---------|
|
||||
| Message received | ⚡ Impulse | 1 | ⚡📥 | void → inbox | any |
|
||||
| /issue created | 📥 Capture | 3 | 📥📋 | → inbox | #linear-updates |
|
||||
| Reaction ✅ | ✅ Approve | 7 | ✅👍 | → queued | any |
|
||||
| /deploy started | 🎬 Mobilize | 10 | 🎬🚀 | queued → wip | #ops-deployments |
|
||||
| Deploy running | ⚙️ Execute | 13 | ⚙️⚡ | → wip | #ops-deployments |
|
||||
| Deploy success | 🎉 Complete | 19 | 🎉✅ | wip → done | #ops-deployments |
|
||||
| Alert: error | 🚨 Detect | 16 | 🚨⚠️ | → blocked | #ops-alerts |
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Slack Channel Categories
|
||||
|
||||
Recommended channel structure with GreenLight mappings:
|
||||
|
||||
| Emoji | Channel | Purpose | GreenLight Domain | Notification Type |
|
||||
|-------|---------|---------|-------------------|-------------------|
|
||||
| 📢 | #general | Company announcements | Platform (🛣️) | General |
|
||||
| ⚙️ | #engineering | Engineering discussions | Infrastructure (🔧) | Technical |
|
||||
| 🚨 | #ops-alerts | System alerts & monitoring | Infrastructure (🔧) | Critical |
|
||||
| 🚀 | #ops-deployments | Deployment notifications | Infrastructure (🔧) | Deploy |
|
||||
| 🚦 | #ops-greenlight | GreenLight state changes | Platform (🛣️) | State |
|
||||
| 📋 | #linear-updates | Linear issue notifications | Platform (🛣️) | Issues |
|
||||
| 🐙 | #github-activity | GitHub PRs, commits | Infrastructure (🔧) | Code |
|
||||
| 💳 | #stripe-billing | Payment & subscriptions | Platform (🛣️) | Billing |
|
||||
| 🤖 | #ai-logs | AI agent activity logs | AI (🌀) | AI |
|
||||
| 🧠 | #lucidia | Lucidia system updates | AI (🌀) | Lucidia |
|
||||
| ☀️ | #standup | Daily standups | Platform (🛣️) | Team |
|
||||
| 🎲 | #random | Non-work banter | Platform (🛣️) | Social |
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Slash Commands
|
||||
|
||||
| Command | GreenLight Action | Description | Priority |
|
||||
|---------|-------------------|-------------|----------|
|
||||
| /issue | Create Issue | Create Linear issue | 📌 |
|
||||
| /deploy | Deploy Service | Trigger deployment | 🔥 |
|
||||
| /status | Check Status | Check system status | 📌 |
|
||||
| /greenlight | Query State | Query GreenLight state | ⭐ |
|
||||
| /agent | Query AI | Query AI agent | ⭐ |
|
||||
| /oncall | Show Schedule | Show on-call schedule | 📌 |
|
||||
| /remind | Set Reminder | Set reminder | 💤 |
|
||||
| /standup | Post Standup | Post standup update | 📌 |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Composite Patterns for Slack
|
||||
|
||||
### Message Events
|
||||
```
|
||||
⚡📥💬👉 = Message received, micro scale
|
||||
💬✅👉📌 = Message acknowledged
|
||||
🔔💬🎢⭐ = Mention notification, macro, high priority
|
||||
```
|
||||
|
||||
### Command Events
|
||||
```
|
||||
📋💬👉📌 = Issue command, micro
|
||||
🚀💬🎢🔥 = Deploy command, macro, urgent
|
||||
🚦💬👉⭐ = GreenLight query, high priority
|
||||
```
|
||||
|
||||
### Notification Events
|
||||
```
|
||||
🚨⚠️💬🔥 = Critical alert in Slack
|
||||
🎉✅💬🎢 = Deployment success notification
|
||||
💰✅💬📌 = Payment success notification
|
||||
🐙📥💬👉 = GitHub activity notification
|
||||
```
|
||||
|
||||
### Reaction Events
|
||||
```
|
||||
✅💬👉📌 = Approval reaction
|
||||
❌💬👉📌 = Rejection reaction
|
||||
🚀💬👉⭐ = Deploy ready reaction
|
||||
```
|
||||
|
||||
### Full Slack Flow
|
||||
```
|
||||
[⚡📥] [💬📋] [✅👍] [🚀🎬] [⚙️⚡] [🎉✅] = Message → Issue → Approve → Deploy → Execute → Complete
|
||||
[🚨⚠️] [💬🔔] [👤📌] = Alert → Notify → Assigned
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 NATS Subject Patterns (Slack)
|
||||
|
||||
### Message Events
|
||||
```
|
||||
greenlight.slack.message.received.micro.comms.{channel}
|
||||
greenlight.slack.message.sent.micro.comms.{channel}
|
||||
greenlight.slack.mention.received.micro.comms.{user}
|
||||
```
|
||||
|
||||
### Command Events
|
||||
```
|
||||
greenlight.slack.command.issue.micro.comms.{user}
|
||||
greenlight.slack.command.deploy.macro.comms.{service}
|
||||
greenlight.slack.command.status.micro.comms.{service}
|
||||
greenlight.slack.command.greenlight.micro.comms.{id}
|
||||
```
|
||||
|
||||
### Webhook Events
|
||||
```
|
||||
greenlight.slack.webhook.alert.critical.comms
|
||||
greenlight.slack.webhook.deployment.macro.comms.{service}
|
||||
greenlight.slack.webhook.github.micro.comms.{repo}
|
||||
greenlight.slack.webhook.stripe.macro.comms.{event}
|
||||
```
|
||||
|
||||
### Reaction Events
|
||||
```
|
||||
greenlight.slack.reaction.added.micro.comms.{emoji}
|
||||
greenlight.slack.reaction.approve.micro.comms.{message}
|
||||
greenlight.slack.reaction.reject.micro.comms.{message}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Slack Memory Templates
|
||||
|
||||
### Message Operations
|
||||
|
||||
```bash
|
||||
# Slash command executed
|
||||
gl_slack_command() {
|
||||
local command="$1"
|
||||
local user="$2"
|
||||
local args="${3:-}"
|
||||
|
||||
gl_log "💬⚡👉📌" \
|
||||
"slack_command" \
|
||||
"$command" \
|
||||
"Executed by: $user, args: $args"
|
||||
}
|
||||
|
||||
# Message sent to channel
|
||||
gl_slack_message_sent() {
|
||||
local channel="$1"
|
||||
local message_type="${2:-notification}"
|
||||
|
||||
gl_log "💬📤👉📌" \
|
||||
"message_sent" \
|
||||
"$channel" \
|
||||
"Type: $message_type"
|
||||
}
|
||||
|
||||
# Mention received
|
||||
gl_slack_mention() {
|
||||
local user="$1"
|
||||
local channel="$2"
|
||||
|
||||
gl_log "🔔💬👉⭐" \
|
||||
"mention_received" \
|
||||
"$user" \
|
||||
"In channel: $channel"
|
||||
}
|
||||
```
|
||||
|
||||
### Webhook Notifications
|
||||
|
||||
```bash
|
||||
# Alert sent to Slack
|
||||
gl_slack_alert() {
|
||||
local severity="$1" # critical, warning, info
|
||||
local title="$2"
|
||||
local channel="${3:-ops-alerts}"
|
||||
|
||||
local severity_emoji=""
|
||||
case "$severity" in
|
||||
critical) severity_emoji="🚨" ;;
|
||||
warning) severity_emoji="⚠️" ;;
|
||||
info) severity_emoji="ℹ️" ;;
|
||||
*) severity_emoji="📢" ;;
|
||||
esac
|
||||
|
||||
gl_log "${severity_emoji}💬🎢🔥" \
|
||||
"slack_alert" \
|
||||
"$title" \
|
||||
"Severity: $severity, Channel: #$channel"
|
||||
}
|
||||
|
||||
# Deployment notification sent
|
||||
gl_slack_deployment_notification() {
|
||||
local status="$1" # started, success, failed
|
||||
local service="$2"
|
||||
local environment="$3"
|
||||
|
||||
local status_emoji=""
|
||||
case "$status" in
|
||||
started) status_emoji="🚀" ;;
|
||||
success) status_emoji="✅" ;;
|
||||
failed) status_emoji="❌" ;;
|
||||
*) status_emoji="⚙️" ;;
|
||||
esac
|
||||
|
||||
gl_log "${status_emoji}💬🎢📌" \
|
||||
"slack_deployment" \
|
||||
"$service" \
|
||||
"Status: $status, Env: $environment"
|
||||
}
|
||||
|
||||
# GreenLight update posted
|
||||
gl_slack_greenlight_update() {
|
||||
local item_id="$1"
|
||||
local from_state="$2"
|
||||
local to_state="$3"
|
||||
|
||||
gl_log "🚦💬👉📌" \
|
||||
"slack_greenlight" \
|
||||
"$item_id" \
|
||||
"$from_state → $to_state"
|
||||
}
|
||||
|
||||
# Linear notification sent
|
||||
gl_slack_linear_notification() {
|
||||
local action="$1" # created, updated, completed
|
||||
local identifier="$2"
|
||||
|
||||
local action_emoji=""
|
||||
case "$action" in
|
||||
created) action_emoji="🆕" ;;
|
||||
updated) action_emoji="📝" ;;
|
||||
completed) action_emoji="✅" ;;
|
||||
*) action_emoji="📋" ;;
|
||||
esac
|
||||
|
||||
gl_log "${action_emoji}💬👉📌" \
|
||||
"slack_linear" \
|
||||
"$identifier" \
|
||||
"Action: $action"
|
||||
}
|
||||
|
||||
# GitHub notification sent
|
||||
gl_slack_github_notification() {
|
||||
local type="$1" # pr_opened, pr_merged, push, issue
|
||||
local repo="$2"
|
||||
local title="${3:-}"
|
||||
|
||||
local type_emoji=""
|
||||
case "$type" in
|
||||
pr_opened) type_emoji="🔀" ;;
|
||||
pr_merged) type_emoji="🎉" ;;
|
||||
push) type_emoji="📤" ;;
|
||||
issue) type_emoji="🐛" ;;
|
||||
*) type_emoji="🐙" ;;
|
||||
esac
|
||||
|
||||
gl_log "${type_emoji}💬👉📌" \
|
||||
"slack_github" \
|
||||
"$repo" \
|
||||
"Type: $type, $title"
|
||||
}
|
||||
|
||||
# Stripe notification sent
|
||||
gl_slack_stripe_notification() {
|
||||
local event="$1" # payment_success, payment_failed, subscription_created, etc.
|
||||
local customer="$2"
|
||||
local amount="${3:-}"
|
||||
|
||||
local event_emoji=""
|
||||
case "$event" in
|
||||
payment_success) event_emoji="💰" ;;
|
||||
payment_failed) event_emoji="❌" ;;
|
||||
subscription_created) event_emoji="🎉" ;;
|
||||
subscription_canceled) event_emoji="👋" ;;
|
||||
*) event_emoji="💳" ;;
|
||||
esac
|
||||
|
||||
gl_log "${event_emoji}💬👉📌" \
|
||||
"slack_stripe" \
|
||||
"$customer" \
|
||||
"Event: $event, Amount: $amount"
|
||||
}
|
||||
```
|
||||
|
||||
### Approval & Interaction
|
||||
|
||||
```bash
|
||||
# Approval request sent
|
||||
gl_slack_approval_request() {
|
||||
local type="$1" # deployment, access, expense, other
|
||||
local requester="$2"
|
||||
local title="${3:-}"
|
||||
|
||||
gl_log "🔔💬👉⭐" \
|
||||
"approval_request" \
|
||||
"$requester" \
|
||||
"Type: $type, $title"
|
||||
}
|
||||
|
||||
# Approval decision
|
||||
gl_slack_approval_decision() {
|
||||
local decision="$1" # approved, rejected
|
||||
local approver="$2"
|
||||
local request_id="$3"
|
||||
|
||||
local decision_emoji=""
|
||||
case "$decision" in
|
||||
approved) decision_emoji="✅" ;;
|
||||
rejected) decision_emoji="❌" ;;
|
||||
*) decision_emoji="💬" ;;
|
||||
esac
|
||||
|
||||
gl_log "${decision_emoji}💬👉📌" \
|
||||
"approval_decision" \
|
||||
"$request_id" \
|
||||
"Decision: $decision by $approver"
|
||||
}
|
||||
|
||||
# Reaction added
|
||||
gl_slack_reaction() {
|
||||
local emoji="$1"
|
||||
local message_id="$2"
|
||||
local user="$3"
|
||||
|
||||
gl_log "👍💬👉📌" \
|
||||
"reaction_added" \
|
||||
"$message_id" \
|
||||
"Emoji: $emoji by $user"
|
||||
}
|
||||
```
|
||||
|
||||
### Standup & Team
|
||||
|
||||
```bash
|
||||
# Standup posted
|
||||
gl_slack_standup() {
|
||||
local user="$1"
|
||||
local date="$2"
|
||||
|
||||
gl_log "☀️💬👉📌" \
|
||||
"standup_posted" \
|
||||
"$user" \
|
||||
"Date: $date"
|
||||
}
|
||||
|
||||
# Modal opened
|
||||
gl_slack_modal_opened() {
|
||||
local modal_type="$1"
|
||||
local user="$2"
|
||||
|
||||
gl_log "📋💬👉📌" \
|
||||
"modal_opened" \
|
||||
"$modal_type" \
|
||||
"User: $user"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Example Integration: Complete Slack Flow
|
||||
|
||||
### Scenario: Deploy command to completion
|
||||
|
||||
```bash
|
||||
# 1. User runs /deploy command
|
||||
gl_slack_command "/deploy" "alexa" "production blackroad-api"
|
||||
# [💬⚡👉📌] slack_command: /deploy — Executed by: alexa, args: production blackroad-api
|
||||
|
||||
# 2. Deployment started notification
|
||||
gl_slack_deployment_notification "started" "blackroad-api" "production"
|
||||
# [🚀💬🎢📌] slack_deployment: blackroad-api — Status: started, Env: production
|
||||
|
||||
# 3. Deployment running (from workflow)
|
||||
gl_workflow_step "blackroad-api" "deploy" "passed"
|
||||
# [🚀✅👉🔧] deploy: blackroad-api — Step deploy passed
|
||||
|
||||
# 4. Deployment success notification
|
||||
gl_slack_deployment_notification "success" "blackroad-api" "production"
|
||||
# [✅💬🎢📌] slack_deployment: blackroad-api — Status: success, Env: production
|
||||
|
||||
# 5. GreenLight update notification
|
||||
gl_slack_greenlight_update "blackroad-api-deploy-123" "wip" "done"
|
||||
# [🚦💬👉📌] slack_greenlight: blackroad-api-deploy-123 — wip → done
|
||||
```
|
||||
|
||||
### Scenario: Critical alert flow
|
||||
|
||||
```bash
|
||||
# 1. Critical error detected
|
||||
gl_log "🚨⚠️🔧🔥" "error_detected" "database" "Connection pool exhausted"
|
||||
|
||||
# 2. Alert sent to Slack
|
||||
gl_slack_alert "critical" "Database Connection Pool Exhausted" "ops-alerts"
|
||||
# [🚨💬🎢🔥] slack_alert: Database Connection Pool Exhausted — Severity: critical, Channel: #ops-alerts
|
||||
|
||||
# 3. User mentions on-call engineer
|
||||
gl_slack_mention "oncall-engineer" "ops-alerts"
|
||||
# [🔔💬👉⭐] mention_received: oncall-engineer — In channel: ops-alerts
|
||||
|
||||
# 4. Issue created from Slack
|
||||
gl_slack_command "/issue" "oncall-engineer" "Database connection pool exhausted"
|
||||
# [💬⚡👉📌] slack_command: /issue — Executed by: oncall-engineer
|
||||
|
||||
# 5. Linear issue created
|
||||
gl_issue_created "BLA-150" "Database connection pool exhausted" "bug"
|
||||
# [⚡🐛👉📌] issue_created: BLA-150 — Database connection pool exhausted
|
||||
|
||||
# 6. Notification to Linear channel
|
||||
gl_slack_linear_notification "created" "BLA-150"
|
||||
# [🆕💬👉📌] slack_linear: BLA-150 — Action: created
|
||||
```
|
||||
|
||||
### Scenario: Payment received notification
|
||||
|
||||
```bash
|
||||
# 1. Stripe webhook received
|
||||
gl_webhook_received "invoice.paid" "evt_abc123"
|
||||
# [⚡📥💳👉] webhook_received: invoice.paid — Stripe webhook: evt_abc123
|
||||
|
||||
# 2. Payment processed
|
||||
gl_invoice_paid "customer@example.com" "58" "usd"
|
||||
# [💰✅🎢🌍] invoice_paid: customer@example.com — Payment successful: $58 usd
|
||||
|
||||
# 3. Notification to Slack
|
||||
gl_slack_stripe_notification "payment_success" "customer@example.com" "$58"
|
||||
# [💰💬👉📌] slack_stripe: customer@example.com — Event: payment_success, Amount: $58
|
||||
```
|
||||
|
||||
### Scenario: Approval request
|
||||
|
||||
```bash
|
||||
# 1. Approval request created
|
||||
gl_slack_approval_request "deployment" "developer" "Production deploy of v2.0.0"
|
||||
# [🔔💬👉⭐] approval_request: developer — Type: deployment, Production deploy of v2.0.0
|
||||
|
||||
# 2. Approver reacts
|
||||
gl_slack_reaction "white_check_mark" "msg_123" "tech-lead"
|
||||
# [👍💬👉📌] reaction_added: msg_123 — Emoji: white_check_mark by tech-lead
|
||||
|
||||
# 3. Approval decision recorded
|
||||
gl_slack_approval_decision "approved" "tech-lead" "approve_req_123"
|
||||
# [✅💬👉📌] approval_decision: approve_req_123 — Decision: approved by tech-lead
|
||||
|
||||
# 4. Deploy triggered
|
||||
gl_slack_command "/deploy" "tech-lead" "production app-v2"
|
||||
# [💬⚡👉📌] slack_command: /deploy — Executed by: tech-lead, args: production app-v2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Slack App Configuration
|
||||
|
||||
**App Name:** BlackRoad OS
|
||||
**Workspace:** Your Slack workspace
|
||||
**Request URLs:**
|
||||
- Events: https://slack.blackroad.io/slack/events
|
||||
- Commands: https://slack.blackroad.io/slack/commands
|
||||
- Interactive: https://slack.blackroad.io/slack/interactive
|
||||
|
||||
### Bot Scopes (16):
|
||||
- chat:write (send messages)
|
||||
- chat:write.public (send to public channels)
|
||||
- commands (slash commands)
|
||||
- channels:read & channels:history
|
||||
- users:read & users:read.email
|
||||
- reactions:write & reactions:read
|
||||
- files:write & files:read
|
||||
- im:write & im:read
|
||||
- app_mentions:read
|
||||
|
||||
### Slash Commands (8):
|
||||
- /issue - Create Linear issue
|
||||
- /deploy - Trigger deployment
|
||||
- /status - Check system status
|
||||
- /greenlight - Query GreenLight state
|
||||
- /agent - Query AI agent
|
||||
- /oncall - Show on-call schedule
|
||||
- /remind - Set reminder
|
||||
- /standup - Post standup update
|
||||
|
||||
---
|
||||
|
||||
## 📚 Integration Checklist
|
||||
|
||||
- [x] Mapped Slack events to GreenLight 27-step workflow
|
||||
- [x] Created channel-to-domain mappings
|
||||
- [x] Defined slash commands
|
||||
- [x] Extended NATS subjects for Slack events
|
||||
- [x] Built 15+ Slack-specific templates
|
||||
- [x] Webhook notification functions (6 channels)
|
||||
- [x] Block Kit UI templates (5 types)
|
||||
- [x] D1 schema for Slack sync
|
||||
- [x] Event handler with signature verification
|
||||
|
||||
---
|
||||
|
||||
**Created:** December 23, 2025
|
||||
**For:** Slack Team Communication Integration
|
||||
**Version:** 2.0.0-slack
|
||||
**Status:** 🔨 IMPLEMENTATION
|
||||
1989
.trinity/greenlight/scripts/memory-greenlight-templates.sh
Executable file
1989
.trinity/greenlight/scripts/memory-greenlight-templates.sh
Executable file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user