bootstrap/tools/orchestrator-matrix/README.md

Mosaic Matrix Orchestrator Rail

Runtime-agnostic orchestration rail for delegating work to worker agents and enforcing mechanical quality gates.

Purpose

• Decouple orchestration from any single agent runtime feature set
• Persist state in repo-local .mosaic/orchestrator/ files
• Emit structured events for Matrix transport and audit trails
• Enforce rails before marking tasks complete

Components

• protocol/ - JSON schemas for task/event payloads
• dispatcher/ - MACP dispatch helpers for worktrees, command generation, results, and cleanup
• controller/mosaic_orchestrator.py - deterministic controller loop
• adapters/ - runtime adapter guidance

Repo Contract

The controller expects this layout in each bootstrapped repo:

.mosaic/orchestrator/
  config.json
  tasks.json
  state.json
  events.ndjson
  logs/
  results/

Quick Start

From a bootstrapped repo:

~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --once
~/.config/mosaic/bin/mosaic-orchestrator-drain

Continuous loop:

~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10

Sync from docs/TASKS.md to queue:

~/.config/mosaic/bin/mosaic-orchestrator-sync-tasks --apply

Set worker command when needed:

export MOSAIC_WORKER_EXEC="codex -p"
# or
export MOSAIC_WORKER_EXEC="opencode -p"

Publish new orchestrator events to Matrix:

~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish

Consume Matrix task messages into tasks.json:

~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume

Matrix Note

This rail writes canonical events to .mosaic/orchestrator/events.ndjson. The Matrix transport bridge publishes those events into the configured control room and can consume task commands from that room.

Task injection message format (room text):

!mosaic-task {"id":"TASK-123","title":"Fix bug","command":"echo run","quality_gates":["pnpm lint"]}

MACP Notes

MACP-aware tasks add dispatch metadata on top of the existing queue model:

• dispatch: exec, yolo, or acp
• type: task category used for orchestration intent
• worktree / branch: task-specific git execution context
• brief_path: markdown brief consumed by runtime-backed dispatchers
• result_path: structured result JSON written under .mosaic/orchestrator/

Controller behavior remains backward compatible:

• Tasks without dispatch continue through the legacy shell execution path.
• Tasks with dispatch use the MACP dispatcher and can emit task.gated and task.escalated.
• acp dispatch is fail-safe in Phase 1: it escalates with ACP dispatch requires OpenClaw integration (Phase 2) instead of reporting success.
• yolo dispatch stages the brief in a temporary file so the brief body does not appear in process arguments.

Manual queue operations are exposed through:

mosaic macp submit ...
mosaic macp status
mosaic macp drain
mosaic macp history --task-id TASK-001
mosaic macp watch --once
mosaic macp watch --webhook

The Phase 2A event bridge consumes .mosaic/orchestrator/events.ndjson through a polling watcher, persists cursor state in .mosaic/orchestrator/event_cursor.json, and can fan out events to Discord-formatted stdout lines or webhook callbacks.