Multi-Agent Coordination System

┌─────────────────────────────────────────────────────────────────────────────┐
│                              USER ORCHESTRATION                              │
│  Human switches between Claude windows, providing "continue" prompts         │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼                                               ▼
┌─────────────────────────────────┐       ┌─────────────────────────────────┐
│     HIGHER-LEVEL AGENT          │       │     LOWER-LEVEL AGENT           │
│     (Application/Data)          │       │     (Core Infrastructure)       │
│                                 │       │                                 │
│  Domain:                        │       │  Domain:                        │
│  • Phrases, Dashboard           │       │  • cc-core-rs, LIM-RPS          │
│  • CC-Collection, Training      │       │  • CC-MCS, Equilibrium          │
│  • User-facing features         │       │  • Low-level APIs               │
│                                 │       │                                 │
│  Owns: HIGHER_LEVEL.md          │       │  Owns: LOWER_LEVEL.md           │
│  Reads: LOWER_LEVEL.md OUTBOX   │       │  Reads: HIGHER_LEVEL.md OUTBOX  │
└─────────────────────────────────┘       └─────────────────────────────────┘
              │                                               │
              └───────────────────────┬───────────────────────┘
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           FILE-BASED EVENT BUS                               │
│                                                                              │
│  .governance/agents/HIGHER_LEVEL.md  ←→  .governance/agents/LOWER_LEVEL.md  │
│                                                                              │
│  Protocol:                                                                   │
│  1. Agent A writes to own OUTBOX section                                    │
│  2. Agent B reads other's OUTBOX on next prompt                             │
│  3. Agent B copies message to own INBOX (acknowledgment)                    │
│  4. Agent B processes and responds via own OUTBOX                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           ORBIT DATABASE                                     │
│                                                                              │
│  Tables:                                                                     │
│  • projects: Agent domains as projects                                      │
│  • planned_actions: Current TODO items                                      │
│  • accomplishments: Completed work                                          │
│  • blockers: Cross-agent dependencies                                       │
│  • claude_sessions: Session tracking                                        │
│                                                                              │
│  Sync: Agent state → Orbit on significant events                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        RAG++ DECISION MEMORY                                 │
│                                                                              │
│  Structures:                                                                 │
│  • DecisionNode (extends ChainLink)                                         │
│  • DecisionRing (DualRing<DecisionNode>)                                    │
│  • Cross-session trajectory via ChainLinkEstimator                          │
│                                                                              │
│  Storage: .governance/trajectory/decisions.jsonl                            │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MESSAGE FORMAT                                     │
└─────────────────────────────────────────────────────────────────────────────┘

### [TIMESTAMP] TYPE: Subject
**From**: Agent Level
**To**: Agent Level
**Priority**: Low | Medium | High | Critical
**Status**: PENDING | ACKNOWLEDGED | PROCESSED | BLOCKED

**Body**:
<content>

**References**: [Prior message IDs or decision IDs]

---

/// A decision made by an agent, extending ChainLink for trajectory tracking.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DecisionNode {
    // === ChainLink base fields ===
    /// Position in decision trajectory
    pub coordinate: TrajectoryCoordinate5D,
    /// Semantic embedding of the decision description
    pub embedding: Vec<f32>,
    /// Type of decision (maps to LinkType)
    pub decision_type: DecisionType,
    /// Influence weight (0-1)
    pub influence: f32,

    // === Agent-specific fields ===
    /// Unique decision ID
    pub id: String,
    /// Which agent made this decision
    pub agent: AgentLevel,
    /// Timestamp (ISO 8601)
    pub timestamp: String,
    /// Human-readable description
    pub description: String,
    /// Related file paths affected
    pub files_affected: Vec<String>,
    /// References to prior decisions
    pub references: Vec<String>,
    /// Rationale for the decision
    pub rationale: String,
    /// Confidence level (Low/Medium/High)
    pub confidence: Confidence,
    /// Whether this decision is reversible
    pub reversible: bool,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub enum AgentLevel {
    Higher,
    Lower,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub enum DecisionType {
    /// Implementing a feature or fix
    Implementation,
    /// Designing architecture or API
    Design,
    /// Requesting action from other agent
    Request,
    /// Responding to a request
    Response,
    /// Reporting a blocker
    Blocker,
    /// Resolving a blocker
    Resolution,
    /// Sharing context or information
    Context,
    /// Confirming completion
    Confirmation,
    /// Investigating or researching
    Investigation,
    /// Deferring a decision
    Deferral,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub enum Confidence {
    Low,
    Medium,
    High,
}

/// A ring of decisions with dual traversal (temporal and influence).
pub type DecisionRing = DualRing<DecisionNode>;

/// Build a decision ring from a sequence of decisions.
pub fn build_decision_ring(decisions: Vec<DecisionNode>) -> DecisionRing {
    let influences: Vec<f32> = decisions.iter().map(|d| d.influence).collect();
    build_dual_ring(decisions, &influences)
}

/// Query related decisions using ChainLinkEstimator.
pub fn find_related_decisions(
    current: &DecisionNode,
    ring: &DecisionRing,
    estimator: &ChainLinkEstimator,
    k: usize,
) -> Vec<(&DecisionNode, f32)> {
    // Convert DecisionNode to ChainLink for estimation
    let current_link = current.to_chain_link();

    let mut scored: Vec<_> = ring.iter_temporal()
        .filter(|d| d.id != current.id)
        .map(|d| {
            let link = d.to_chain_link();
            let score = estimator.estimate(&current_link, &link);
            (d, score)
        })
        .collect();

    scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
    scored.truncate(k);
    scored
}

# {Level}-Level Agent Status
## Domain: {Domain Description}
### Last Updated: {ISO Timestamp}

---

## CURRENT STATE: {State}

### Completed Work
{List of completed items with status}

### Active Work
{Current focus and progress}

---

## IMPLEMENTATION PLAN
{Phased plan with checkboxes}

---

## INTER-AGENT COMMUNICATION

### INBOX (From {Other} Agent):
{Messages received - append only}

### OUTBOX (To {Other} Agent):
{Messages sent - append only}

### Waiting For:
{List of pending items from other agent}

---

## NEXT STEPS
{Numbered list with status emojis}

---

## BLOCKED BY
{List of blockers}

---

## BLOCKING
{What this agent's work blocks}

# .claude/hooks.yaml (proposed)

hooks:
  # Log all prompts to Orbit
  prompt-submit:
    - name: "orbit-log"
      command: |
        python3 -c "
        import json, sys, os
        from datetime import datetime

        # Log prompt to local file (Orbit sync later)
        log_entry = {
            'timestamp': datetime.utcnow().isoformat(),
            'type': 'prompt',
            'agent': os.environ.get('AGENT_LEVEL', 'unknown'),
        }

        log_path = '.governance/trajectory/prompt_log.jsonl'
        with open(log_path, 'a') as f:
            f.write(json.dumps(log_entry) + '\\n')

        print(f'[Logged] {log_entry[\"timestamp\"][:19]}')
        "

  # Detect agent state file modifications
  post-tool-call:
    - name: "agent-message-detect"
      matcher:
        tool: Edit
        path_pattern: ".governance/agents/*.md"
      command: |
        echo "[Agent Message] File modified: $TOOL_PATH"
        # Could trigger notification to other agent's terminal

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Agent A        │     │  File System    │     │  Agent B        │
│  (Higher)       │     │                 │     │  (Lower)        │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  Edit HIGHER_LEVEL.md │                       │
         │  (add to OUTBOX)      │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │  [Hook: file-edit]    │                       │
         │<──────────────────────│                       │
         │  "Message pending"    │                       │
         │                       │                       │
         │                       │  Read HIGHER_LEVEL.md │
         │                       │<──────────────────────│
         │                       │                       │
         │                       │  Edit LOWER_LEVEL.md  │
         │                       │  (copy to INBOX,      │
         │                       │   add to OUTBOX)      │
         │                       │<──────────────────────│
         │                       │                       │
         │  Read LOWER_LEVEL.md  │                       │
         │<──────────────────────│                       │
         │                       │                       │

CONTINUATION ANCHOR
-------------------
Agent: {Higher | Lower}
Phase: {Current phase}
Last Completed: {Most recent completed item}
Next Active: {Next pending item}
Confidence: {Low | Medium | High}
Open Uncertainties: {List}
Blocked By: {List or "None"}
Unprocessed Messages: {Count from other agent's OUTBOX}
Related Decisions: {IDs of similar past decisions}

// Circular topology with O(1) neighbor access
let ring = Ring::new(vec![decision_1, decision_2, decision_3]);
ring.ring_distance(0, 2);  // Shortest path: 1
ring.neighbors(0, 1);       // Adjacent decisions
ring.iter_from(1);          // Iterate starting from decision_2

// Dual traversal: temporal (RCP) and influence (IRCP)
let dual = DualRing::new(nodes);

// Temporal order (chronological)
dual.iter_temporal();

// Influence order (most impactful first)
dual.iter_by_influence();
dual.top_influential(3);

// Cross-ring analysis
dual.influence_temporal_spread();  // How spread out is influence?

// 4-component relationship strength
let estimator = ChainLinkEstimator::default();
let strength = estimator.estimate(&link_a, &link_b);

// Components:
// - Baseline (0.20): semantic similarity
// - Relationship (0.30): coordinate + attention
// - Type-based (0.20): compatibility matrix
// - Context-weighted (0.30): temporal proximity