# Health Debug — Agent Team Charter

The team lives in `.claude/agents/`. Each agent is a specialist for one surface or role in the module/session plan (`docs/plan/13-execution-modules-and-sessions.md`). This charter is the **shared context every agent reads first** — it keeps the agent files lean and DRY.

## The team

| Agent | Role | Builds / owns |
|---|---|---|
| `hd-orchestrator` | Lead / dispatch | Reads the build-ledger, picks the next session per doc 13, delegates to the right specialist, enforces the design gate + invariants, keeps the ledger current. |
| `hd-backend` | ToGO Go backend | Microkernel, one plugin per engine (pure `core/`), sqlc + Atlas, Postgres, TOGO auth, REST + engine tests. |
| `hd-web` | React + TanStack | Dashboard/app shell, theme engine from `brand/` tokens, ICU + Arabic RTL. |
| `hd-mcp` | MCP server + CLI | Go MCP/CLI thin client over the API (log/query tools). |
| `hd-chrome` | MV3 extension | Popup, side panel, service worker, context-menu scanner. |
| `hd-apple` | Swift suite | iOS/macOS/watchOS/CarPlay/WidgetKit, HealthKit, CoreMotion. |
| `hd-android` | Kotlin suite | Compose app, Health Connect, WearOS, Android Auto, Glance. |
| `hd-desktop` | Electron | Tray, break enforcer, global hotkeys; reuses web components. |
| `hd-design` | Design integration | Imports screens from Claude Design (DesignSync), maps them to `brand/` tokens + components. |
| `hd-reviewer` | Read-only auditor | Thin-client/SSOT audit, correctness, invariant enforcement. Never writes code. |
| `hd-qa` | Tests | Engine unit tests as executable spec, API integration tests, RTL/theme checks. |
| `hd-devops` | Infra | CI, migration discipline, deploy topology, secrets from the vault. |
| `hd-scribe` | Brain keeper | Maintains the classified cabrain brain, writes/curates handoffs, keeps the index. |

## Non-negotiable invariants (all agents)

Read `docs/plan/01-core-opinions-and-constraints.md` for the full treatment. In short:

1. **Two Core Opinions.** (a) Categorical, not quantitative — food is Safe or Trigger-bearing, no calorie/portion math. (b) Never invent medical certainty — AI does behavioral pattern analysis only and always defers to "Consult your doctor."
2. **Backend is the SSOT; clients are thin.** No client (web/chrome/apple/android/desktop/mcp) computes protocol/temporal logic — they render server state and submit intents/sensor events. Protocol constants (250/5000/30s/90m/4h/60m/3 cycles) never appear in client code.
3. **Each engine is its own ToGO plugin** (pure `core/` state machine + `plugin.go`). Every Postgres column **NOT NULL with a default**; migrations strictly **expand-contract**; sqlc + Atlas; TOGO auth.
4. **Brand is a single token source** at `brand/` (`tokens.css` / `tokens.json`, `README.md`). Semantic colors are flat (blue=system, green=pass, red=bug); the red→green **gradient is brand-only, never on status/UI**; **glow is dark-only**; the **mark never mirrors in RTL**. Light-mode alert = `#C62230`.
5. **i18n:** ICU Message Format, full Arabic RTL (mirrored progress bars/charts/node graphs), no string concatenation.
6. **Design gate:** no client/app UI is built until Fady delivers that screen's design in Claude Design. Backend/core (M0, engine plugins, MCP) is **not** gated.
7. **Secrets** live in the cabrain secrets vault / gitignored config — never commit tokens or keys.

## The brain handoff protocol (every build session)

The brain is the cabrain namespace `healthdebug` (`docs/brain/BRAIN-INDEX.md` explains the classification; the bucket field is `metadata.type`).

**At START:**
1. Recall the **build-ledger** (`memory_recall` for "build ledger current frontier", or `memory_get` the ledger id) — it names the recommended next session and blockers.
2. Recall the brain-index record and your target module's memories; open your **session card** in `docs/plan/sessions/` and the plan docs it references.

**At END:** write **one `session-handoff`** and update the ledger:
- **Reads** use the cabrain MCP tools (`memory_recall`, `memory_get`).
- **Writes** use the cabrain HTTP API (`retain` cannot set metadata, so it is two steps):
  1. `POST $CABRAIN_API_URL/api/brain/retain` with header `X-Cabrain-Token: $CABRAIN_TOKEN` (token from the gitignored `.mcp.json` / env — **never commit it**), body `{namespace, content, source_kind:"claude_code", source_ref:"handoff/<module>/<surface>/<n>"}` (unique source_ref).
  2. `POST .../api/brain/memory/edit` with the returned id and `metadata:{project:"healthdebug", type:"session-handoff", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"<Mx>", title:"Handoff <session-id>", next:"<module+surface>", tags:[...]}`. **`metadata.type` is mandatory** — it is the bucket field.
  3. Edit the single **build-ledger** memory (`source_ref: build-ledger`) content to mark your cell done, set the next cell, and list new blockers.

Handoff content structure (per doc 13 §6): `SESSION HANDOFF <id> / Module / Surface / Status / Summary / Files touched / Decisions→rationale / Deviations / Tests run / OPEN THREADS / NEXT SESSION`.

## Canonical references
- Plan corpus: `docs/plan/00-MASTER-PLAN.md` … `13-execution-modules-and-sessions.md`; per-module session cards in `docs/plan/sessions/`.
- Brand: `brand/README.md`, `brand/tokens.css`, `brand/tokens.json`.
- Brain: `docs/brain/BRAIN-INDEX.md`.
- Legacy reference (read-only): `E:\Sites\healthdebug` (map in `docs/plan/12-legacy-reference-map.md`).