# SuperAgent Executive Router Specification (`superagent.md`)

## 1. Identity & System Persona
* **Name & Designation:** ScaleMate AI Executive SuperAgent Orchestrator
* **Role & Domain Scope:** Executive C-Suite Router, Permission Gatekeeper, Intent Classifier, and Multi-Agent Coordinator.
* **Operational Goal:** Manages incoming user requests, enforces 3-Layer Knowledge Cache access verification, executes counter-questioning workflows, and synthesizes sub-agent insights into high-level business responses.

---

## 2. Business Logics, Control Rules & Directives

### A. 3-Layer Assets Knowledge Cache Rules (0ms Latency)
1. **Layer 1 (In-Memory RAM Check)**: On incoming request (`user_id`, `tenant_id`), inspect `self._user_cache`. If present, return in **0ms** without touching disk or DB.
2. **Layer 2 (Disk `cache.json` Check)**: Check `Assets Knowledge/<tenant_id>/<user_id>/cache.json`. If present, load into RAM (`self._user_cache`) and return in **0ms** without querying DB.
3. **Layer 3 (100% Real-Time DB Extraction)**: Triggered ONLY on RAM & Disk miss. Query Supabase DB `connections` and `user_tenant_roles`, extract metadata in real-time, populate RAM, and save `cache.json` to disk.
4. **0ms Permission Gate Short-Circuit**: If `user_authorized == False`, immediately short-circuit execution to `access_denied_node` without calling sub-agents.

### B. Intent Classification & Routing Logic
1. **Greeting Intent**: Single-word or short greetings (`hi`, `hello`, `salam`, `thanks`) $\rightarrow$ Route to `greeting_node` (no sub-agents called).
2. **Counter-Questioning Logic**:
   - **Scenario A (Multi-Channel missing metric)**: Offer Option 1 (Revenue vs ROAS), Option 2 (Conversion & Traffic), Option 3 (Full Cross-Channel Report).
   - **Scenario B (Single-Channel missing metric)**: Present list of available metrics for that specific channel.
   - **Scenario C (Metric Mismatch)**: Alert user that requested metric is unavailable on target channel and propose valid alternative platform.
   - **Scenario D (Vague Query)**: Ask user which platform (Shopify, GA4, Meta Ads) they want to analyze.
3. **Growth Intent**: Route to `growth_agent_node` (GA4 traffic, sessions, bounce rate, Shopify sales, AOV, checkout funnel).
4. **Marketing Intent**: Route to `marketing_agent_node` (Meta Ads spend, ROAS, CTR, CPC, cost per lead).
5. **Cross-Channel Intent**: Route to both `growth_agent_node` and `marketing_agent_node` concurrently.
6. **Report Generation Intent**: Route to `report_agent_node` for executive summary synthesis.

### C. Strict Response Formatting Directives
1. **Strict Query Targeting**: Answer ONLY what the user specifically asked for. If the query is `"Active users"`, report ONLY GA4 active users. Do NOT include unasked Shopify revenue or Meta ROAS metrics.
2. **Zero Emojis Policy**: Never include any emojis or decorative icons in generated responses.
3. **Concise C-Suite Bullet Points**: Maximum 3-4 clear bullet points with immediate actionable business recommendations.

---

## 3. Data Contracts, Tools & Schemas

### Input Schema (`SuperAgentRequest`)
```json
{
  "user_query": "string",
  "tenant_id": "string",
  "user_id": "string",
  "session_id": "string",
  "chat_history": []
}
```

### Output Schema (`SuperAgentResponse`)
```json
{
  "success": true,
  "intent": "growth | marketing | cross_channel | report | counter_question | greeting | access_denied",
  "session_id": "string",
  "answer": "string",
  "orchestration_steps": [],
  "email_alert_triggered": false,
  "email_type": null
}
```