🧠 Cognitive Modes (Research, Plan, Agent)

To keep the assistant disciplined—no invented numbers, no premature file changes, no silent deliverable claims—AMBA enforces the Lean Triad cognitive model (Research, Plan, Agent). Switch modes instantly from the segmented control in the chat composer, or let Agent handle end-to-end execution.

The Lean Triad Cognitive Model /
├── 💬 1. Research (Conversational Q&A) ➔ Pure read-only inspection, exploration & calculation (Zero disk writes)
├── 📋 2. Plan (Hard-Locked Blueprint) ➔ Rigorous strategic roadmap saved to workings/plans/YYYYMMDD_<slug>.md
└── ⚡ 3. Agent (Autonomous Execution) ➔ Compiles native Office (Excel, Word, PowerPoint) and vector PDF deliverables

READ-ONLY

💬 Research Mode

Pure Read-Only Inspection

Exploration, formula verification & analytical calculation. Zero disk writes.

1-Click Knowledge Ingest

HARD-LOCKED

📋 Plan Mode

Hard-Locked Strategic Blueprint

Rigorous strategic blueprint saved to workings/plans/YYYYMMDD_<slug>.md.

Review & Approve

🚀 Approve & Execute Plan

AUTONOMOUS

⚡ Agent Mode

Autonomous Delivery to reports/

Autonomous multi-step runtime compiling verified board-ready deliverables.

📦Native Excel (.xlsx)

📦Word Briefings (.docx)

📦16:9 Slides (.pptx)

📦Vector PDF

---

⚡ TypeSafe AI (Jev — System 1 Decision Engine) Auto-Routing

Rather than manually toggling modes for every prompt, AMBA supports TypeSafe AI (Jev — System 1 Decision Engine) as an experimental auto-routing engine:

• Sub-Second Intent Classification: Evaluates incoming prompts in milliseconds to classify the optimal operational mode (Research, Plan, or Agent).
• Real-Time Latency Badge: When active, AMBA displays a real-time badge in the chat composer (e.g., Jev · 68ms) confirming sub-second classification.
• Configured in Step 3 of Model Settings: Easily enabled with your TypeSafe API key in Model Settings > Step 3 (Advanced & Experimental Routing).

---

1. 💬 Research Mode — Conversational Q&A & Exploration

When to use: Exploring documents, asking complex domain questions, or checking formulas with zero disk modifications.

• Behavior: Pure conversation, document inspection, and analytical calculation.
• Allowed Capabilities: Reading workspace files (filesystem_read, excel_read, pdf_read), deterministic analytical SQL queries (accounting_sql_query, accounting_load_file), and web search (when enabled).
• Persistent Knowledge Ingest: When the agent discovers critical business rules, tax codes, or definitions, you can ingest them into persistent local SQLite memory with 1 click using the message action button.
• Hard Restriction: Strictly Read-Only. The assistant is physically prevented by the Rust Policy Engine from writing anywhere in the project (workspace or Sources). Every tool declares whether it writes: editing workbooks, decks or Word documents, Office scripts, shell commands and connected MCP tools are refused too, before any permission prompt. Previewing a deck or Word edit without saving it is allowed.

---

2. 📋 Plan Mode — Hard-Locked Strategic Blueprint

When to use: Formulating a multi-step execution roadmap, reviewing analytical assumptions, and agreeing deliverables before touching output files.

• The Sovereign Executive Contract: In top-tier agent architectures, Plan Mode provides an uncompromising contract: hard-locked read-only inspection. The agent analyzes raw source documents in Sources, establishes calculation formulas, specifies expected file layouts, and outlines execution steps—stopping completely without modifying production files.
• Chronological Dated Plan Convention (workings/plans/YYYYMMDD_<slug>.md):
  • Every plan is saved directly to disk as a dated Markdown artifact: workings/plans/YYYYMMDD_<short_slug>.md (e.g. workings/plans/20260917_q3_financial_reconciliation.md).
  • Traceable Business Audit History: Business users and finance controllers maintain a clean, chronological record of strategic roadmaps over time. Plans never overwrite each other blindly; same-day variants gracefully increment (_v2.md).
  • Interactive Plan Inspector Card: The chat UI renders a dedicated interactive card with the plan title, timestamp, planned deliverables checklist chips, and two buttons: [ Review Plan ] opens the plan file; [ Generate Drafts ] builds the deliverables into workings/drafts/ for review. When the drafts are right, ask the agent in chat for the final version (for example "finalize the report"); it writes the final deliverables to reports/.
• Hard Restriction: Hard-locked against direct deliverables. The agent can only draft plans under workings/plans/. Writing deliverables in the workspace is strictly blocked by the runtime until the plan is approved.

---

3. ⚡ Agent Mode — Autonomous Execution & Delivery

When to use: Turning an approved plan or a direct executive request into verified, board-ready deliverables.

• Behavior: Executes multi-step workflows, loads data tables into embedded SQLite, evaluates exact formulas, and writes verified deliverables directly into the workspace (by default the report folder reports/).
• Approved Plan Execution: Generate Drafts hands Agent mode the dated blueprint ([EXECUTE PLAN DRAFT: workings/plans/YYYYMMDD_<slug>.md]); it verifies prerequisites, executes each milestone step, writes the drafts to workings/drafts/ and marks the plan status as Executed. Once you have reviewed the drafts, ask for the final version in chat and the agent writes it to reports/.
• In-Tree Artifact Factory (No Python, LibreOffice, Node, or cloud sidecars):
  • Native Excel workbooks (.xlsx) via excel_write / accounting_export_table_to_xlsx with dynamic XML formulas.
  • Native Word executive briefings (.docx) via docx_write.
  • Native 16:9 widescreen PowerPoint decks (.pptx) via pptx_write.
  • Vector-rendered PDFs (.pdf) via pdf_generate.
  • Markdown briefs (.md) via filesystem_write with automatic synchronized PDF compilation.
• 1+1 Deliverable Pack Standard: Business playbooks require one structured analytical model (.xlsx) plus one narrative strategy document (.docx, .pptx, .md, or .pdf).

---

🌐 Cross-Lingual Reasoning Boundary (ADR-020)

Across all three cognitive modes, AMBA enforces the Strict Cross-Lingual Reasoning Boundary:

1. Reasoning stays out of the answer (ADR-074): The model reasons in its provider's own reasoning channel; AMBA never asks it to write reasoning or plans into the answer. Multi-step work shows its plan as a checklist next to the answer (recorded through the plan tool), and tool parameters (paths, sheet names, formulas) stay exactly as the files define them.
2. Native Localized Output: All conversational replies, interactive UI cards, and finalized Office/PDF files are compiled directly in the active project locale (en, vi, ja, ko).

---

👁️ What an Agent Turn Shows (ADR-074)

Every answer comes with three things you can open, kept apart from the answer itself:

• Thinking: a short summary of how the model reasoned, written by the model provider. It is folded by default; open it to read it, with the time spent. While the agent works it streams live, and short progress notes appear under the running step. AMBA never shows raw reasoning, and older answers without a summary show none.
• Plan: for multi-step work the agent keeps a checklist of its steps and ticks them off as it goes. When it kept no plan, the turn lists Steps taken instead, built from the actions it actually ran (shown lighter).
• Result: work that runs on its own (processes) hands in its result with the files it produced; they appear as chips under the answer and open with one click. If an answer had no text at all, the turn simply says the task was completed, in your language.

---

Cognitive Modes Comparison

Mode	Primary Intent	Sandbox Disk Policy	Output Deliverables
💬 Research	Read-only Q&A, source inspection & calculation assistance	Read-only (filesystem_read, excel_read, pdf_read, sql)	None (Chat answers + 1-Click Knowledge Ingest)
📋 Plan	Strategic roadmap, requirements breakdown & formula design	Read-only + Plan drafting under workings/plans/	workings/plans/YYYYMMDD_<slug>.md
⚡ Agent	Autonomous end-to-end execution & deliverable production	Full tool access (excel_write, docx_write, pptx_write, pdf_generate)	Verified files in reports/ (or where you ask) & working papers

---

Choosing the Right Mode

Business Goal	Recommended Mode
"Explain the revenue variance between these two CSV files"	Research
"Read this rate card and understand our pricing tiers"	Research (+ Ingest to Knowledge)
"Break down the steps and assumptions before building the 3-year model"	Plan
"I reviewed the blueprint, go build the financial model"	Agent (via [ Generate Drafts ], then ask for the final version)
"Produce the complete Q3 Board Briefing and Excel workbook"	Agent