{"slug":"documentation/HIERARCHICAL_AGENT_ORCHESTRATION_DOCTRINE","title":"Hierarchical Agent Orchestration & Twin Stewardship Doctrine","section":"documentation","sectionLabel":"Documentation","status":"unclassified","type":"document","path":"documentation/HIERARCHICAL_AGENT_ORCHESTRATION_DOCTRINE.mdx","bytes":5486,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## 1. The Master Doctrine\n\n> **One Workspace. One Spine. One shared Agent Home. One Twin. Many invisible capabilities.**\n\n> **Users work with their business. Twin carries continuity. Agents operate backstage. The system surfaces outcomes, evidence, decisions and required human attention—not agent machinery.**\n\n---\n\n## 2. Refined Architectural Boundaries\n\n```text\nSpine      = operational truth (canonical entities, graph topology, live projections)\nKnowledge  = evidence / semantic structures (grounded manuals, playbooks, SLAs)\nMemory     = governed continuity (episodic, semantic, operational)\nAgent Home = runtime / working state (shared engine room, A2A bus, sub-workers)\nFortress   = verifiable audit history (append-oriented, tamper-evident execution ledger)\n```\n\n> **Fortress**: Append-oriented, tamper-evident, retention-governed audit and execution ledger supporting governance, traceability, signed proposals, incident reconstruction, and compliance controls.\n> _(Fortress is an audit and evidence plane adjacent to the operational architecture, not a direct operational partition of Spine)._\n\n---\n\n## 3. Core Principle: Single Face to the User, Invisible Capabilities Backstage\n\nIn IntegrateWise, the human user has **ONE user-facing relationship: their Twin**.\n\n**Twin is the sole user-facing orchestrator.**\n\nSpecialist agents operate inside the **shared Agent Home** and may be orchestrated by Twin, workflows, events, or runtime policy. Their outputs surface to users through Twin or the appropriate SpineWorkspace projection—**not as competing agents**.\n\n_Why this design wins_: A reconciliation agent, sync agent, schema agent, monitoring agent, or scheduled automation does not require Twin to sit synchronously in every internal execution path. **One Twin externally does not require one centralized execution bottleneck internally.**\n\n```text\nONE SPINEWORKSPACE\n        │\n        ▼\nONE SHARED AGENT HOME\n        │\n        ▼\n      TWIN\nsingle continuity-bearing,\nuser-facing orchestrator\n        │\n        ├── specialists (Triage, Schema-AI, Coworker)\n        ├── skills & playbooks\n        ├── workflows & state machines\n        ├── models (dynamic cost/latency routing)\n        ├── tools / MCP connector pool\n        ├── jobs & normalizers\n        ├── schedules & crons\n        └── runtime workers\n\n            invisible (engine room)\n\nUSER\n │\n ▼\nWork → Awareness → Decide → Act → Continue\n```\n\n---\n\n## 4. The Specialized Worker Fleet (Internal Engine Room)\n\n| Specialized Capability  | Role & Responsibility                                                                                                                 | Orchestration & Surfacing Rule                                                                                  |\n| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |\n| **Triage Agent**        | Continuously scans webhooks, emails, tickets, telemetry, and anomalies. Categorizes severity and domain.                              | Triggered by event ingress. Surfaces classified insights to Twin / Workbenches. Never pings users directly.     |\n| **Schema Agent**        | Ingests unstructured and multi-source data (Salesforce, Stripe, Jira, Zendesk) and normalizes it into canonical Spine schemas.        | Triggered by data pipelines & sync events. Reconciles schemas backstage; never prompts user for mapping chores. |\n| **Coworker Agent**      | Performs complex, domain-specific background reasoning (churn analysis, expansion models, reconciliation).                            | Orchestrated by Twin or domain workflows. Submits structured drafts for Twin synthesis or projection rendering. |\n| **Adaptive Auto-Tuner** | Monitors tool invocation latency, token cost, and accuracy; dynamically switches model routing (Claude / GPT / Groq / Gemini).        | Autonomous runtime policy. Optimizes model selection invisibly backstage.                                       |\n| **Hermes Executor**     | Dispatches authenticated API mutations and tool actions against external SaaS endpoints once human cryptographic sign-off is granted. | Triggered upon HITL proposal approval. Logs execution proofs directly to Fortress Ledger.                       |\n\n---\n\n## 5. The 4 Golden Rules of Twin Stewardship & User Experience\n\n1. **Sole User-Facing Presenter**:\n   - The Twin is the only agent that speaks to, summarizes for, or generates interactive proposals for the human user.\n2. **Context & Continuity Stewardship**:\n   - While specialist agents execute bounded tasks statelessly or within ephemeral scratchpads, the Twin preserves cross-session continuity, role awareness, and working context.\n3. **Decoupled Internal Execution**:\n   - Internal workers run asynchronously, triggered by events, crons, or workflow DAGs without blocking the Twin or polluting the user's focus.\n4. **Governed Human Sign-Off (HITL Gate)**:\n   - When any backstage worker determines a write mutation or sensitive external action is needed, the action is encapsulated into a cryptographically verifiable Proposal Card presented through the Twin or domain projection for 1-click human approval.\n"}