Communication Layer Specification & Platform Blueprint

Document ID: DOC-2026-021 Owner: VP Product Date: 2026-02-18 Status: Draft Product: Legionis (legionis.ai) V2V Phase: Phase 3 — Strategic Commitments Related: PRD V3.0, Execution Plan V3.2, Interaction Patterns V2.0, Architecture Stack V1.4 Origin: PLT session (VP Product, Director PM, BizOps) — Communication Layer architecture + Platform Blueprint

1. Executive Summary

This document specifies two foundational elements of the Legionis platform:

The Communication Layer is the architectural realization of USP #4 (Collaborative Agent Architecture). It transforms Legionis from a collection of individually-addressable agents into a self-organizing workforce.

2. The Problem: Operator-in-the-Middle

What Happens Today (Claude Code / Product Org OS)

When a user interacts with the Product Org OS through Claude Code, the experience has two structural problems:

Problem 1: The Visible Orchestrator. There is always a "Claude" voice that mediates between the user and agents. It says things like "I'm calling the PM agent to handle this" or "Let me route this to competitive intelligence." After the agent responds, Claude summarizes or presents the output. The user never feels like they're talking TO agents — they're always talking THROUGH an intermediary.

Problem 2: Explicit Routing Required. Users must know which agent to address (@pm, @vp-product, @plt) or which skill to invoke (/prd, /decision-record). There is no mode where the user simply describes what they need and the right agents step forward autonomously.

Why This Matters

These problems prevent the "AI workforce" promise from landing. A real workforce doesn't require you to memorize org charts. You describe what you need, the right people show up, and they coordinate among themselves. The Communication Layer makes this real.

3. What the Communication Layer Is

The Communication Layer is a platform primitive — a distinct architectural layer that sits between the Workforce Layer (agents) and the user interface. It governs:

It is NOT:

• A gateway (gateways are specific entry points; the Communication Layer governs ALL entry points)
• A routing table (routing tables are a component OF the Communication Layer)
• A feature (it is infrastructure that enables features)

Relationship to Existing Architecture

The Communication Layer formalizes and unifies what Weeks 5-7 build as separate features into a coherent architectural layer.

4. Five Core Behaviors

Behavior 1: Intelligent Request Routing

What it does: Analyzes any user input and determines which agent(s) should respond, without requiring the user to specify.

Three routing modes:

Routing decision process (progressive refinement):

1. Explicit mention? (@agent or /skill)
   → Route directly to that agent/skill
Conversation context? (an agent already "in the room")
   → Continue with current agent UNLESS topic clearly shifts domains
Domain keyword match?
   → Match against routing table (weighted keywords per agent)
Context layer signal?
   → Check workspace context for active bets, decisions, feedback on the topic
   → Weight routing toward agents whose domain intersects with existing context
Team configuration?
   → Filter routing candidates to agents the user has provisioned
   → If no match in provisioned teams, suggest team addition
Complexity assessment?
   → Single-domain → route to one agent
   → Multi-domain → invoke gateway logic (SINGLE/PRIMARY+/MULTI)
   → Portfolio-level → invoke PLT
Ambiguous?
   → In Invisible mode: make best judgment, route, allow user to redirect
   → In Assisted mode: show top 2-3 options, let user pick

Contextual routing intelligence: The routing engine considers:

• Active conversation thread (who's already been talking)
• Workspace context layer (existing decisions, bets, feedback on the topic)
• User's provisioned teams (don't route to agents the user doesn't have)
• Historical routing patterns (what has this user preferred in the past)
• Request complexity (single-domain vs. cross-functional)

Behavior 2: Agent-to-Agent Tipping (Cascade)

What it does: When an agent's output changes something that affects other agents' domains, the Communication Layer detects this and notifies or triggers follow-up work.

Cascade triggers:

Cascade levels:

Initial implementation (MVP): Notify level only. The system detects cascade triggers and surfaces them as suggestions. User decides whether to act.

Post-MVP enhancement: Auto-review and auto-update levels, configurable per cascade rule in the cooperation profile.

Behavior 3: Invisible Presentation

What it does: Ensures the user never sees an "operator" voice. Agents speak directly. No mediation, no summarization, no "here's what the agent said."

Rules:

Prohibited patterns (the Communication Layer must suppress these):

Behavior 4: Cooperation Profiles

What it does: Provides configurable presets that control how agents collaborate, how aggressively the system cascades, and how visible the routing is.

Five configurable dimensions:

Preset profiles:

Storage: Cooperation profile stored as JSON in the workspaces table (cooperation_profile column). Editable in Settings > AI Configuration.

UI: A "Cooperation Style" section in AI Configuration settings, showing the presets as selectable cards, with an "Advanced" disclosure that reveals the five individual dimension sliders.

Behavior 5: Conversation Context Continuity

What it does: Maintains awareness of which agents are "in the room" within a conversation, enabling natural multi-turn interactions without re-routing.

Rules:

5. Architecture: Where the Communication Layer Sits

                    ┌─────────────────────────────────────┐
                    │            USER INTERFACE            │
                    │  (Chat, Skill Palette, Agent Picker) │
                    └──────────────────┬──────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      COMMUNICATION LAYER                            │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │   Request     │  │  Cooperation │  │   Presentation           │  │
│  │   Router      │  │  Engine      │  │   Governor               │  │
│  │              │  │              │  │                          │  │
│  │  - Intent    │  │  - Cascade   │  │  - Operator suppression  │  │
│  │    parsing   │  │    rules     │  │  - Meeting Mode trigger  │  │
│  │  - Domain    │  │  - Tipping   │  │  - Agent attribution     │  │
│  │    matching  │  │  - Conflict  │  │  - Error presentation    │  │
│  │  - Context   │  │    mgmt     │  │                          │  │
│  │    signals   │  │  - Profile   │  │                          │  │
│  │  - Room      │  │    loading   │  │                          │  │
│  │    tracking  │  │              │  │                          │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    Gateway Engine                             │   │
│  │  (@product, @plt, @design, @architecture, @marketing, etc.)  │   │
│  │  SINGLE / PRIMARY+ / MULTI agent selection                   │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    Parallel Executor                          │   │
│  │  Promise.allSettled, max 4 agents, 500ms stagger             │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    ▼                  ▼                  ▼
          ┌─────────────┐   ┌──────────────┐   ┌──────────────┐
          │  WORKFORCE   │   │   CONTEXT    │   │   COMPUTE    │
          │   LAYER      │   │    LAYER     │   │    LAYER     │
          │             │   │              │   │              │
          │ 81 agents   │   │ Decisions    │   │ BYOT keys    │
          │ 11 teams    │   │ Bets         │   │ Managed pool │
          │ 80+ skills  │   │ Feedback     │   │ Quality      │
          │ 11 gateways │   │ Learnings    │   │   toggle     │
          │ Delegation  │   │ Documents    │   │ Metering     │
          │   patterns  │   │ Cross-refs   │   │ Provider     │
          │ Knowledge   │   │ Auto-inject  │   │   factory    │
          │   packs     │   │              │   │              │
          └─────────────┘   └──────────────┘   └──────────────┘

The Communication Layer USES the other three layers:

• It reads the Context Layer for routing signals and cascade triggers
• It invokes agents from the Workforce Layer to produce responses
• It routes LLM calls through the Compute Layer for key management and model selection

6. Implementation Mapping to Execution Plan

The Communication Layer does not require a new development phase. It formalizes and extends what's already planned:

New components to build:

MVP scope (Weeks 5-7): Request Router, Presentation Governor, Cooperation Profile (presets only), Room Tracker.

Post-MVP scope (Weeks 9+): Cascade Detector, Agent-to-Agent Tipping, Advanced cooperation profile tuning, auto-review/auto-update cascade levels.

7. The Platform Blueprint

7.1 Layer Model

Legionis is a four-layer platform connected to three external resource categories.

═══════════════════════════════════════════════════════════════════════════════
                              LEGIONIS PLATFORM BLUEPRINT
═══════════════════════════════════════════════════════════════════════════════
 ╔═══════════════════════════════════════════════════════════════════════════╗
 ║                              USERS                                      ║
 ║          Web UI  |  Voice Input  |  Cmd+K Palette  |  @ / /             ║
 ╚═══════════════════════════════╤═══════════════════════════════════════════╝
                                 │
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃               LAYER 4: WORKFORCE                                       ┃
 ┃                                                                        ┃
 ┃  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    ┃
 ┃  │ Product  │ │Marketing │ │ Finance  │ │  Legal   │ │Operations│    ┃
 ┃  │ 13 agents│ │16 agents │ │ 9 agents │ │ 8 agents │ │ 8 agents │    ┃
 ┃  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘    ┃
 ┃  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    ┃
 ┃  │ Design   │ │  Arch    │ │Executive │ │Corp Dev  │ │IT Govern │    ┃
 ┃  │ 7 agents │ │ 7 agents │ │ 2 agents │ │ 5 agents │ │ 6 agents │    ┃
 ┃  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘    ┃
 ┃                                                                        ┃
 ┃  80+ Skills  |  11 Gateways  |  34 Knowledge Packs  |  4 Patterns    ┃
 ┃  (Consultation | Delegation | Review | Debate)                        ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
                                 │
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃               LAYER 3: COMMUNICATION                                   ┃
 ┃                                                                        ┃
 ┃  Request Router ──── Cooperation Engine ──── Presentation Governor     ┃
 ┃       │                     │                        │                 ┃
 ┃  Intent Parsing       Cascade Rules         Operator Suppression      ┃
 ┃  Domain Matching      Agent-to-Agent        Meeting Mode Trigger      ┃
 ┃  Context Signals      Conflict Mgmt         Agent Attribution         ┃
 ┃  Room Tracking        Profile Loading       Error Presentation        ┃
 ┃       │                     │                        │                 ┃
 ┃  ┌─────────────────────────────────────────────────────────────────┐   ┃
 ┃  │  Gateway Engine  |  Parallel Executor  |  Routing Table        │   ┃
 ┃  └─────────────────────────────────────────────────────────────────┘   ┃
 ┃                                                                        ┃
 ┃  Cooperation Profiles: Collaborative | Directed | Balanced | Auto     ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
                                 │
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃               LAYER 2: CONTEXT (Organizational Memory)                 ┃
 ┃                                                                        ┃
 ┃  Decisions ── Bets ── Feedback ── Learnings ── Documents              ┃
 ┃       │                                            │                   ┃
 ┃  Cross-Reference Graph          Auto-Context Injection                ┃
 ┃  Topic / Product / Phase Index  Session Continuity                    ┃
 ┃  Interaction Logging            Portfolio State                       ┃
 ┃                                                                        ┃
 ┃  Storage: User's Cloud Drive (stable file IDs, portable markdown)     ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
                                 │
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃               LAYER 1: COMPUTE                                         ┃
 ┃                                                                        ┃
 ┃  BYOT Key Manager ──── Managed Token Pool ──── Quality/Efficiency     ┃
 ┃       │                       │                       │                ┃
 ┃  Per-request key         30% markup              3-tier toggle        ┃
 ┃  Envelope encryption     Spend tracking          (Quality/Balanced/   ┃
 ┃  Provider factory        Usage metering           Efficiency)         ┃
 ┃  Model resolution        Billing integration     Per-agent override   ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
 ╔═══════╧═══════╗     ╔════════╧════════╗     ╔════════╧════════╗
 ║  LLM COMPUTE  ║     ║ CLOUD STORAGE   ║     ║ CLOUD SERVICES  ║
 ║  (Tokens)     ║     ║ (Context/Files) ║     ║ (Awareness)     ║
 ║               ║     ║                 ║     ║                 ║
 ║  Anthropic    ║     ║  Google Drive   ║     ║  Jira           ║
 ║  OpenAI       ║     ║  OneDrive*      ║     ║  Slack          ║
 ║  Google AI   ║     ║  Dropbox       ║     ║  GitHub         ║
 ║               ║     ║                 ║     ║  Salesforce*    ║
 ║  ( planned)  ║     ║  ( planned)    ║     ║  HubSpot*       ║
 ╚═══════════════╝     ╚═════════════════╝     ║  (* planned)    ║
                                               ╚═════════════════╝

7.2 USP-to-Layer Mapping

7.3 Revenue Model by Layer

7.4 Competitive Defensibility by Layer

8. Communication Layer Data Model

8.1 Cooperation Profile Schema

// Stored in workspaces.cooperation_profile (JSONB)
interface CooperationProfile {
  preset: 'collaborative' | 'directed' | 'balanced' | 'full_autonomy' | 'custom';
  dimensions: {
    cooperationLevel: 'low' | 'medium' | 'high';     // Agent-to-agent collaboration eagerness
    cascadeSensitivity: 'off' | 'low' | 'medium' | 'high';  // When to notify about cross-domain impact
    conflictEscalation: 'low' | 'medium' | 'high';   // How disagreements are surfaced
    routingAutonomy: 'explicit' | 'assisted' | 'invisible';  // How requests reach agents
    agentInitiative: 'low' | 'medium' | 'high';      // How proactively agents suggest follow-ups
  };
}

8.2 Room State (Conversation-Level)

// Stored in conversations.metadata (JSONB) as 'room' key
interface ConversationRoom {
  activeAgents: string[];        // Agent keys currently "in the room"
  primaryAgent: string | null;   // The agent currently "holding the floor"
  lastRoutingDecision: {
    agentKey: string;
    reason: string;              // Why this agent was selected
    mode: 'explicit' | 'assisted' | 'invisible';
    timestamp: string;
  };
  domainHistory: string[];       // Domains touched in this conversation
}

8.3 Cascade Event (Future)

// For post-MVP cascade detection
interface CascadeEvent {
  sourceAgent: string;           // Agent whose output triggered the cascade
  sourceAction: string;          // What they did (e.g., "updated PRD scope")
  affectedAgents: string[];      // Agents whose domains are impacted
  severity: 'info' | 'review' | 'update';
  message: string;               // Human-readable description
  autoAction: 'notify' | 'review' | 'update';  // Governed by cooperation profile
  status: 'pending' | 'acknowledged' | 'acted_on' | 'dismissed';
}

9. Invisible Routing: How It Works End-to-End

Here is the full flow for a message in Invisible routing mode:

User types: "How should we price the enterprise tier?"
                    │
                    ▼
  ┌─────────────────────────────────────┐
  │  COMMUNICATION LAYER: Request Router │
  │                                     │
  │  1. Explicit mention? No            │
  │  2. Agent in room? Check...         │
  │     - Conversation is new, room     │
  │       is empty                      │
  │  3. Domain keywords:                │
  │     "price" + "enterprise"          │
  │     Matches: BizOps (0.85),         │
  │              VP Product (0.60)      │
  │  4. Context signals:                │
  │     - DR-2026-001 exists (pricing)  │
  │     - SB-2026-001 (enterprise bet)  │
  │     Boosts: BizOps (0.90)           │
  │  5. Team config: User has Product   │
  │     team (BizOps included)          │
  │  6. Complexity: Single-domain       │
  │                                     │
  │  DECISION: Route to BizOps          │
  └──────────────┬──────────────────────┘
                 │
                 ▼
  ┌─────────────────────────────────────┐
  │  Assemble BizOps system prompt      │
  │  (L1 Core + L2 Persona + L3 Domain) │
  │  + Auto-Context: DR-2026-001 +      │
  │    SB-2026-001 injected             │
  └──────────────┬──────────────────────┘
                 │
                 ▼
  ┌─────────────────────────────────────┐
  │  Execute via Compute Layer          │
  │  (User's BYOT key, model per        │
  │   quality preference)               │
  └──────────────┬──────────────────────┘
                 │
                 ▼
  ┌─────────────────────────────────────┐
  │  Presentation Governor              │
  │                                     │
  │  - Format: Single agent response    │
  │  - Attribution: "🧮 BizOps:"       │
  │  - NO operator preamble             │
  │  - Update room: BizOps now active   │
  └──────────────┬──────────────────────┘
                 │
                 ▼
  User sees BizOps responding directly:
  "🧮 BizOps: Looking at enterprise
   pricing, I see two patterns worth
   considering..."

10. Relationship to Existing Documents

11. Open Questions

12. Success Criteria

13. Version History