SuperAgent/superagent.md

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)

{
  "user_query": "string",
  "tenant_id": "string",
  "user_id": "string",
  "session_id": "string",
  "chat_history": []
}

Output Schema (SuperAgentResponse)

{
  "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
}