docs/fleet/north-star.md

@@ -73,6 +73,37 @@ diff-sanity → squash-merge → verify), **decide-and-inform** cadence, and a d
 this model. See `mosaicstack-aiguide` whitepapers 01 (inter-agent comms) and 03
 (orchestration model) for the rationale.
 
+## Fleet roster — the two-agent floor and the role library
+
+A fleet is **never a single agent**. The minimum viable fleet is **two**:
+
+| Role             | Mandate                                                                                                                                                                                                                                                                                                                                                                 | Boundaries                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Orchestrator** | The user's **single point of contact**. Owns the general flow, keeps agentic actions on-target, and **adds/removes agents from the fleet at will** to meet goals and user needs. Exactly **one** per fleet (the existing R5 invariant).                                                                                                                                 | Delegates source work; never the sole worker.                                              |
+| **Enhancer**     | The fleet's **continuous-improvement loop**. Monitors fleet activity, analyzes for enhancements/optimizations, builds a **plan of remediation**, and — **with the orchestrator** — upgrades fleet capability: tool creation/repair, skills, harness improvements, and **bug reports filed to Mosaic Stack** for proper remediation. Recommends which agents are needed. | **Does not code, review code, or perform delivery tasks.** Improvement and diagnosis only. |
+
+> **Why two, not one:** the orchestrator drives delivery; the enhancer makes the fleet
+> _get better at delivering_ over time. The enhancer is how the fleet self-heals its tools,
+> skills, and harnesses, and how real defects flow back to Mosaic Stack as bug reports.
+> Together they are the irreducible core — every other role is added on demand.
+
+A **general** fleet starts at this floor: the orchestrator (advised by the enhancer)
+materializes whatever roles prove necessary over the mission's life. Specialized presets
+(coding, research, etc.) seed additional roles up front, but all reduce to the same two-agent
+spine plus an on-demand **role library**:
+
+| Role profile        | Purpose                                                                           |
+| ------------------- | --------------------------------------------------------------------------------- |
+| **orchestrator**    | point of contact, flow control, fleet composition (1 per fleet)                   |
+| **enhancer**        | fleet monitoring, optimization, tool/skill/harness upgrades, upstream bug reports |
+| **coder**           | implementation (worker; stops at PR-open)                                         |
+| **code review**     | independent code review gate                                                      |
+| **security review** | security/auth/secret review gate                                                  |
+| **research**        | investigation, synthesis, options analysis                                        |
+| **board**           | deliberation panel — moonshot, contrarian, technical, business, financial lenses  |
+| **operations**      | infra, deploy, health, incident response                                          |
+| _…extensible_       | new profiles added as missions demand (orchestrator + enhancer decide)            |
+
 ## Invariants — "maximal vision, incremental delivery, zero foreclosure"
 
 Every artifact, starting Phase 2, MUST:
@@ -102,7 +133,7 @@ Every artifact, starting Phase 2, MUST:
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
 | 0–1                    | tmux PoC, hardening, published CLI v0.0.34 (#565–#568)                                                                                       | ✅ done |
 | **2 — Observability**  | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts | ▶ now   |
-| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: orchestrator+reviewer; ephemeral workers per lane)          | planned |
+| 3 — Real runtimes      | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane)    | planned |
 | 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning                                 | planned |
 | 5 — Control plane      | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity                                    | planned |
 
@@ -121,6 +152,28 @@ Every artifact, starting Phase 2, MUST:
   runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
   which `fleet init` should automate.
 
+## Decisions of record (2026-06-22, with Jason)
+
+- **Two-agent floor:** every fleet has, at minimum, an **orchestrator** and an **enhancer**.
+  The orchestrator is the user's point of contact and composes the fleet; the enhancer runs the
+  continuous-improvement loop (monitor → analyze → remediate → upgrade tools/skills/harness →
+  file Mosaic Stack bug reports) and **does not code or review**.
+- **Role library:** orchestrator, enhancer, coder, code review, security review, research,
+  board (moonshot/contrarian/technical/business/financial), operations — extensible; the
+  orchestrator (advised by the enhancer) adds roles as missions demand.
+- **Orchestrator chat connector:** the orchestrator is reachable over a user-chosen connector
+  (tmux now; Telegram/Discord/Matrix/Slack configurable). Validated live: **"Mos" orchestrator
+  on Discord** via the Claude Code discord channel plugin (w-jarvis).
+
+## Future enhancements (north-star, post-MVP — not on the MVP track)
+
+- **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly
+  implements the basic Discord functions **and native Discord threads**. Threads let a user
+  separate conversation topics with the orchestrator (the pattern proven by the Hermes agent).
+  A major enhancement over the current third-party channel plugin; **not required for the MVP**,
+  but a committed north-star target. `ASSUMPTION:` ships as a Mosaic-owned plugin so the fleet
+  controls Discord UX (threads, reactions, attachments, per-thread context) end-to-end.
+
 ## Assumptions (veto-able)
 
 - `ASSUMPTION:` first-class runtimes = claude, codex, pi, opencode; a "role" (analyst,