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).