🧠 Cognitive Modes (Ask, Study, Plan, Exec)

To prevent AI agents from running wild, hallucinating numbers, or prematurely altering files, AMBA enforces a strict 4-Mode Cognitive Lifecycle. You can switch modes instantly in the chat composer bar.

---

1. 🗣️ Ask Mode — Conversational Q&A & Inquiries

When to use: When you want answers, explanations, or quick sanity checks without modifying any files.

• Behavior: Pure conversation and file inspection.
• Allowed Capabilities: Reading files (filesystem_read, excel_read, pdf_read), executing deterministic SQL queries (accounting_sql_query), searching the web (if enabled).
• Hard Restriction: ZERO file writes. The agent is strictly forbidden from writing to workings/ or output/.

---

2. 📖 Study Mode — Deep Research & Knowledge Ingestion

When to use: Ingesting lengthy industry reports, vendor pricing sheets, or brand guidelines into the project's permanent brain.

• Behavior: Analyzes input documents, identifies core domain definitions, formulas, and constraints, and commits them to the project's Long-Term Memory via knowledge.store.
• Allowed Capabilities: Document reading, web research, semantic knowledge storage.
• Hard Restriction: Cannot write deliverables to output/. Cannot clutter workings/ with scratchpad dumps.

---

3. 📋 Plan Mode — Structured Implementation Blueprints

When to use: Formulating a structured roadmap before executing complex tasks.

• Behavior: The agent analyzes requirements and produces an actionable, multi-step implementation plan with verifiable execution steps.
• The Cursor IDE Lifecycle:
  • Automatically captures structured plans with human-readable slugs and short hashes: workings/plans/plan_<slug>_<short_hash>.md (e.g. plan_invoice_reconciliation_a7b2.md).
  • In-Place Updates: As you continue the conversation with adjustments ("add VAT cross-check step"), AMBA updates the existing plan file in place—no messy duplicate files.
  • Generates a Plan Referral Card in the chat, allowing you to click Review Plan to inspect the blueprint.
• Hard Restriction: Cannot write deliverables or execute shell commands during planning.

---

4. ⚡ Exec Mode — Autonomous Execution & Delivery

When to use: Turning an approved plan or direct prompt into final, polished business deliverables.

• Behavior: The agent follows the approved plan step-by-step, loads files into the SQLite database, executes exact calculations, and saves verified final workbooks and briefing PDFs into output/.
• Milestone Locking: Once execution completes, the referenced plan file is marked as Executed, permanently archiving that milestone in your project history.