diff --git a/docs/fleet/north-star.md b/docs/fleet/north-star.md index 2e6dbba..6d4a253 100644 --- a/docs/fleet/north-star.md +++ b/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,