# Matrix Plugin Coordination

ZoneGaze Matrix gets its value from the combined behavior of plugins inside one shell. This page
documents how that coordination works today, which pairings are already useful now, and which
cross-plugin behaviors are still planned.

Flow is a first-party plugin in this catalog, not the Matrix shell itself. It is also not the same
kind of plugin as Open Design or Exo: Flow is ZoneGaze-owned and currently provides the main
project-context workflow, while Open Design and Exo are upstream-mounted plugins embedded by Matrix.

## Coordination Layers

- Matrix shell: Dashboard, Ports, Plugin, and Settings provide the host window, runtime controls,
  and plugin lifecycle.
- Capability registry: Matrix tracks plugin capabilities such as `dictation`, `project-context`,
  `chat`, `notes`, `file-workspace`, `git`, `design-artifact`, `local-model-runtime`, and
  `deep-research`, and `social-studio`.
- Shared project scope: current workspace/project context is already routed into Flow, Chat,
  Joplin, Open Design, Git, and Social Studio surfaces in different ways. Research uses that
  context through host plugins rather than its own left-rail surface.
- Shared agent settings: Chat, Flow, Code, Open Design, and Research can share one saved Cline
  provider/model/MCP configuration, and Social Studio reuses the same model-source setup flow.
- Shared evidence layers: Git state and Deep Research artifacts are intended to be reusable across
  multiple plugins instead of being re-created in each plugin separately.

## Current Plugin Fit

| Plugin or module | What it owns | Best current pairings | Current coordination notes |
| --- | --- | --- | --- |
| Flow | Project orchestration, task worktrees, agent sessions, review, shipping | Git, Code, Chat, Joplin, Research, Open Design | Flow is the main current `project-context` provider, but it is still one plugin inside Matrix rather than the host product. |
| Chat | Workspace AI conversations | Flow, Whispr, Research | Chat can attach Flow project context, accept Whispr dictation, and show linked Deep Research sessions and evidence cards. |
| Whispr | Dictation and transcription | Flow, Chat, Joplin, Code | Whispr already improves prompt writing, note capture, and quick text entry. Broader voice coverage across every plugin is still planned. |
| Joplin | Notes, notebooks, knowledge capture | Whispr, Flow, Research, Chat | Joplin is the durable memory surface: project-linked notes, Whispr quick notes, and saved research summaries fit here well. |
| Git | Device Git setup and repository actions | Flow, Code, Chat, Joplin, Open Design, Research | Git is the shared repository layer. It reuses Flow runtime Git helpers instead of adding a second Git engine. |
| Code | Workspace IDE surface | Flow, Whispr, Git | Code is the implementation surface. Flow picks the work, Code edits the repository, and Git/Flow close the loop. |
| Open Design | Embedded design workspace | Flow, Chat, Joplin, Research | Matrix already routes project context and shared agent settings around Open Design. Deeper artifact linking is still evolving. |
| Exo | Local AI cluster/runtime dashboard | Flow, Code, Ports | Exo is currently an adjacent local-model runtime surface. It is useful beside project and implementation workflows, but not every plugin auto-routes through it yet. |
| Research module | Deep Research sessions and cited artifacts | Chat first, then Flow, Joplin, Open Design, Code | Research is not opened directly from the left rail or Marketplace. Chat attachment exists now; downstream reuse is still partly manual today. |
| Social Studio | Modular social workflow workspace | Whispr, Research, Open Design, Exo | Social Studio already handles ingest, research, planning, publishing prep, analytics import, and automation inside Matrix, with BYO connectors and strong future cross-plugin potential. |

## Recommended Current Workflows

- Flow + Git + Code:
  Flow manages the task and worktree, Code handles editing and terminal work, and Git provides
  repository status/history/sync.
- Flow + Chat + Research:
  use Flow for project scope, Chat for reasoning and tool use, and Research for cited context and
  saved evidence bundles.
- Whispr + Chat:
  dictate long prompts or replies into Chat instead of typing them.
- Whispr + Joplin:
  capture quick notes and meeting fragments, then keep them as durable project memory in Joplin.
- Joplin + Research + Chat:
  use Research to gather evidence, Joplin to keep the durable notes/exported summaries, and Chat to
  turn those materials into decisions or next actions.
- Flow + Open Design + Joplin:
  track the task in Flow, keep the working brief or references in Joplin, then open Open Design for
  the actual design workspace.
- Social Studio + Whispr + Research:
  import voice transcripts or local assets, build campaign context, and keep research-backed social
  planning inside one plugin workspace.
- Exo + Flow or Code:
  keep a local runtime dashboard visible while doing implementation or orchestration work when you
  want private/local model infrastructure nearby.

## Confirmed Current Coordination

- Chat receives `dictationAvailable` and `projectContextAvailable` from the Matrix capability
  registry and exposes linked research sessions in the conversation surface.
- Joplin receives both project context and Whispr availability from the same capability registry.
- Open Design receives active project identity/path from Matrix when available.
- Whispr can send quick notes to the Joplin plugin and records Matrix-scoped transcript history.
- Git reuses Flow runtime Git helpers for status, history, fetch, pull, and push.
- Research can attach saved sessions to a chat and export reusable cited artifacts through host
  plugin workflows.
- Shared Cline settings are already saved once for Chat, Flow, Code, Open Design, and Research.
- Social Studio already exists as a first-party Matrix plugin with a `social-studio` capability and
  a BYO connector model for `cline-sdk`, `ollama`, `exo`, and `custom-api`.

## Planned Broader Coordination

These items are directionally documented in Matrix UI/source, but they should be treated as planned
coordination rather than universal current behavior:

- Whispr voice input everywhere across Flow, Code, Chat, Joplin, Open Design, and Research.
- Flow acting as the broader project coordination layer so tasks, notes, design work, code work,
  and decisions stay linked automatically.
- Code opening implementation context directly from Flow tasks, design specs, Joplin notes, Chat
  decisions, and Research findings.
- Git serving as the shared version-control layer for all project-facing plugins.
- Open Design turning Flow requests, Code handoffs, Chat decisions, Joplin references, and Research
  evidence into project-scoped design artifacts.
- Research acting as the reusable evidence layer for Chat, Flow planning, Joplin memory, design
  briefs, and implementation work.
- Exo providing optional local AI capacity when more plugins can make use of a shared local runtime.
- Social Studio adding deeper reuse of research, voice capture, design artifacts, and direct
  platform adapters as those integrations mature.

## Source Pointers

- Catalog and plugin metadata: [`flow/contracts/src/zonegaze-products.ts`](../../flow/contracts/src/zonegaze-products.ts)
- Capability registry: [`flow/common/src/plugin-services.ts`](../../flow/common/src/plugin-services.ts)
- Matrix plugin surface wiring: [`flow/web/src/components/plugins/matrix-plugin-surfaces.tsx`](../../flow/web/src/components/plugins/matrix-plugin-surfaces.tsx)
- Shared Cline settings surface: [`flow/web/src/components/plugins/matrix-cline-plugin-panel.tsx`](../../flow/web/src/components/plugins/matrix-cline-plugin-panel.tsx)
- Future-direction copy already in source: [`flow/web/src/components/plugins/matrix-dashboard-model.ts`](../../flow/web/src/components/plugins/matrix-dashboard-model.ts)
- Research runtime/infrastructure: [`infra/deep-research/README.md`](../../infra/deep-research/README.md)
