f9ec2879ba
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 🌸✨
578 lines
18 KiB
Markdown
578 lines
18 KiB
Markdown
# 🧠 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)
|
||
|