# Knowledge Item: SuiteX Agnostic Agent Memory & Team Orchestration

## 1. Executive Summary
This document defines the architectural standard for AI agent collaboration within the SuiteX project. It transitions from monolithic agent workflows to a **Granulated Specialist** model centered around an **Agnostic SQLite Blackboard** for persistent, low-overhead context management.

## 2. Core Infrastructure: The Agent Memory Board

### 2.1 Storage Layer
- **File:** `.agent/memory.sqlite` (Project root).
- **Driver:** SQLite (Strictly agnostic of the application's MySQL/GCP environment).
- **Rationale:** Prevents context loss during `migrate:fresh` or local DB resets. Ensures agent "forensic discovery" survives across development sessions.

### 2.2 Schema (`agent_memory` table)
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary identifier for a memory entry. |
| `task_slug` | String | Groups memories by task/branch (e.g. `feat-auth`). |
| `type` | String | Compound identifier using `domain:subtype` format (e.g., `observation:exploration`, `design:technical`, `spec:implementation`, `observation:audit`, `bug:root-cause`, `bug:impact`, `bug:qa-plan`). |
| `content` | LongText | The distilled technical reasoning or specification. |
| `metadata` | JSON | Includes branch name, actor, and timestamp. |

### 2.3 CLI commands
- `php artisan agent:mem:init`: Bootstraps the SQLite schema.
- `php artisan agent:mem:put`: Upserts a memory entry.
- `php artisan agent:mem:get`: Retrieves memory by slug, type, or ID.

---

## 3. Team Granulation Model

To preserve the **Context Window**, complex orchestrators are subdivided into specialized personas.

### Orchestration Models

Two invocation models exist. Choose based on whether specialists need to correlate findings:

| Model | Mechanism | Use When | Examples |
| :--- | :--- | :--- | :--- |
| **A — Task Tool (Multi-Agent)** | Parent spawns sub-agents via `Task(subagent_type=..., prompt="slug=[id]. Read .agent/workflows/X.md")`. Each runs with a fresh context window. Blackboard is the only handoff. | Phases are independent. Each agent's output is the next agent's full input. | `task-architect` → `explorer` → `architect` → `planner` → `feature-implementer` |
| **B — Persona Inline (Monolithic)** | Orchestrator reads specialist workflow files and adopts each persona within its own context. No Task tool call. | Specialists must correlate findings in real-time (a security issue changes impact score, etc.). | `bug-coordinator` adopting `bug-inspector`, `impact-analyst`, `qa-engineer` personas |

> **Rule:** Thinker/Doer chains (feature development) always use **Model A**. Bug review chains always use **Model B**.

### 3.1 The "Thinkers" (Specification Phase)
1.  **Explorer:** Forensic researcher. Searches for logic in raw files. Saves `observation:exploration`.
2.  **Architect:** Designer. Consumes the Explorer's summary to define DDD patterns and contracts. Saves `design:technical`.
3.  **Planner (Spec-Writer):** Quality officer. Consumes the Design to create a step-by-step Technical Plan. Saves `spec:implementation`.

### 3.2 The "Doers" (Code Phase)
1.  **Implementer (Fixer/Feature):** Executes the task. It **only** loads the `spec:implementation` from the Blackboard. It does NOT perform research.
2.  **Auditor:** Verification agent. Compares the final code (Diff) against the original `spec:implementation` stored in the memory board.

---

## 4. Operational Handoff Pattern (The Protocol)

Every orchestrated task MUST follow this sequential flow:
1.  **Initialize:** `agent:mem:init` (if first run).
2.  **Handoff:** Sub-agents load the previous output via `agent:mem:get --slug=[task-id] --type=[relevant-type]`.
3.  **Distillation:** Sub-agents MUST NOT output raw file contents to the memory. They must output **summarized conclusions** to keep the blackboard efficient.

## 5. Directory Structure Standards
- `.agent/workflows/`: Contains the definitive markdown logic for each sub-agent.
- `.cursor/agents/`: Contains the `.md` pointers that link the user-facing command (e.g. `/task-architect`) to the underlying `.agent` workflow.

## 6. Business & Security Rationale
- **Context Sanity:** Reduces LLM hallucinations by never saturating the prompt with irrelevant file noise.
- **Traceability:** Every architectural decision made by an agent is saved in the SQLite DB, searchable across the entire project history.
- **Efficiency:** Drastic reduction in token costs for "Doer" agents who only consume the distilled Spec instead of the entire codebase context.

---

## 7. Swarm Lifecycle Example (Step-by-Step)
To understand how these agents collaborate, here is a breakdown of a typical feature implementation.

### Task: "Implement NetSuite Sync for Projects"

#### Step 1: Orchestration Ready
The user invokes `/task-architect`.
- **Command:** `php artisan agent:mem:init` (Blackboard initialized).
- **Setup:** Creates `feature/netsuite-sync` branch and tracker.
- **Handoff:** Calls `/explorer`.

#### Step 2: Discovery (The Explorer)
- **Action:** Forensic research on `Project` model and NetSuite API docs.
- **Save Finding:**
  ```bash
  php artisan agent:mem:put observation:exploration "Project table uses MySQL 'start_date', but NetSuite needs 'startdate'. Column mapping required." --slug=sync-projects
  ```

#### Step 3: Design (The Architect)
- **Command:** `php artisan agent:mem:get --type=observation:exploration --slug=sync-projects`
- **Logic:** Designs the `ProjectSyncData` DTO.
- **Save Design:**
  ```bash
  php artisan agent:mem:put design:technical "Create ProjectSyncData in src/Domain/Projects/DataTransferObjects. Suffix with 'Data' per Rule 104." --slug=sync-projects
  ```

#### Step 4: Execution (The Implementer)
- **Command:** `php artisan agent:mem:get --type=spec:implementation --slug=sync-projects`
- **Action:** Writes the TDD tests and the DTO as specified in the "Digital Contract".

#### Step 5: The Final Gate (The Auditor)
- **Audit:** Compares `ProjectSyncData.php` against the `design:technical`.
- **Verdict:** If the Implementer added extra fields not in the spec, the Auditor **Rejects** the work for 100% compliance.