mosaicstack/stack
1
0
Fork 0
Code Issues 22 Pull Requests 7 Actions Packages Projects Releases 13 Wiki Activity
Files
5cde3a3b6de89dcf1f8c43265155de7593fd3756
stack/docs/plans/2026-05-06-hermes-mosaic-alignment.md

14 KiB
Raw Blame History

Hermes-Mosaic Alignment Plan

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: Package Mosaic's mechanical coordination primitives as a native Hermes toolset so any Hermes profile gets mission management, task decomposition, handoff, and session continuity without depending on the Mosaic gateway or OpenClaw runtime.

Architecture: Extract the coordination logic from Mosaic's packages/coord (TypeScript, file-first) into a Hermes Python toolset that wraps the same file conventions. The Mosaic Stack repo remains the canonical upstream for the file formats (TASKS.md schema, mission.json schema, handoff packet schema). Hermes implements native Python tools that read/write those same files, plus tool-calls for churn detection and handoff generation that have no Mosaic equivalent today.

Tech Stack: Python (Hermes toolset), SQLite (Hermes Kanban), JSON + Markdown (Mosaic file conventions)

Alignment Map

What Mosaic has that Hermes needs

Mosaic Component What it does Natural Hermes home Why
packages/coord (mission.ts) Mission CRUD, session tracking, milestone state Hermes toolset: mission Mission state is session-scoped, not gateway-scoped. Hermes sessions already have identity, process tracking, and context windows.
packages/coord (tasks-file.ts) Parse/write TASKS.md tables Hermes toolset: mission (same) Hermes already reads/writes files. The TASKS.md parser is ~300 lines of pure string manipulation — trivial Python port.
packages/coord (runner.ts) Spawn claude/codex workers with continuation prompts Already covered by delegate_task Hermes delegate_task already does isolated subagent spawning with restricted toolsets. The runner's "find next task and build continuation prompt" logic moves into a tool-call.
packages/coord (status.ts) Mission health, task progress, next task Hermes toolset: mission (same) Status readout fits naturally as a tool-call. No gateway needed.
packages/prdy PRD generation wizard Hermes skill: prdy PRD generation is a prompt + template problem, not infrastructure. A Hermes skill with templates is the right fit.
plugins/mosaic-framework before_agent_start + subagent_spawning hooks Hermes system prompt injection Hermes already injects system context via skills and config. The framework preamble and worktree rules become standard Hermes skills loaded by the orchestrator profile.
plugins/macp OpenClaw ACP bridge (spawn codex/claude) Already covered by delegate_task + ACP Hermes already has ACP support and delegate_task. The MACP bridge is redundant when running natively in Hermes.
Churn detection (planned) Detect compaction loops, repeated tool calls, no progress Hermes middleware This needs to live inside Hermes's turn loop where it can observe tool-call patterns. Mosaic can't see this from outside.
Handoff packet (planned) Structured context summary for session rotation Hermes toolset: mission Handoff is a serialization of mission + session state. Hermes owns the session, so it should own the handoff.

What Hermes already has that replaces Mosaic infrastructure

Mosaic concept Hermes equivalent Notes
Gateway (NestJS) Hermes gateway Hermes already has a gateway with WebSocket, Discord, Telegram, CLI. No need for a second one.
Pi SDK agent runtime Hermes agent loop Hermes IS the agent runtime. OpenClaw's Pi SDK is a different runtime that Mosaic targets.
MACP ACP bridge delegate_task + ACP tools Same capability, already native.
Session identity Hermes session IDs + process_registry Hermes already tracks session identity, PIDs, and background processes.
Task execution board Hermes Kanban Fully functional SQLite-backed Kanban with dispatcher, triage, events, comments.
Worker spawning Hermes dispatcher + cron Kanban dispatcher + cron already handle this.
Context injection Hermes skills + system prompt Skills are loaded at session start and injected into context. Exactly what mosaic-framework plugin does.
File checkpoints Hermes checkpoint_manager Already tracks file mutations with shadow git.

What Mosaic keeps as its own entity

Component Why it stays in Mosaic
apps/gateway NestJS API surface — Mosaic's web platform offering
apps/web Next.js dashboard — Mosaic's UI offering
packages/types Shared TS contracts for Mosaic gateway plugins
packages/db Drizzle ORM + PG — Mosaic's data layer
packages/auth BetterAuth — Mosaic's auth system
packages/brain PG-backed data layer for Mosaic web app
packages/queue Valkey task queue for Mosaic gateway
plugins/discord OpenClaw Discord plugin
plugins/telegram OpenClaw Telegram plugin
packages/mosaic CLI The mosaic CLI — Mosaic's own command surface

Architecture: mission Toolset for Hermes

New files under /opt/hermes/tools/

mission_tools.py      — Tool-call surface (mission_create, mission_status, 
                         mission_next_task, mission_update_task, mission_handoff,
                         mission_resume)
mission_state.py       — State management (read/write mission.json, parse TASKS.md,
                         parse MISSION-MANIFEST.md)
mission_churn.py       — Churn detection (tool-loop counter, compaction counter,
                         progress scorer)
mission_handoff.py     — Handoff packet generation and loading

Tool-calls exposed to the agent

Tool What it does When the agent calls it
mission_create Initialize mission.json + TASKS.md + MISSION-MANIFEST.md in a project dir When starting a new mission
mission_status Read current mission state, milestone progress, next task, active session At session start, or when checking progress
mission_next_task Find the next not-started task whose dependencies are met, return its full spec When the agent needs work to do
mission_update_task Update a task row status in TASKS.md When completing or blocking a task
mission_handoff Generate a handoff packet from current session context + mission state Before session rotation or at session end
mission_resume Load a handoff packet and inject it as context for the new session At session start after rotation

Toolset registration

The mission toolset follows the same pattern as kanban:

  1. Gating: Tools are available when:

    • The profile has mission in its toolsets config, OR
    • A HERMES_MISSION_DIR env var is set (cron/dispatcher spawned workers)

  2. File conventions: The toolset reads/writes the same file formats as Mosaic packages/coord:

    • .mosaic/orchestrator/mission.json — mission state
    • docs/TASKS.md — task table
    • docs/MISSION-MANIFEST.md — mission manifest
    • docs/scratchpads/<id>.md — session scratchpad

  3. Kanban bridge: Optional bidirectional sync between mission TASKS.md rows and Kanban task cards, so the dashboard sees mission tasks.

Churn detection (middleware)

Churn detection lives in Hermes's turn loop, NOT as a tool-call. It observes:

  • Repeated compaction events (context window pressure)
  • Identical tool-call sequences (loop detection)
  • No file state changes across N turns
  • Repeated permission denials

When churn score exceeds threshold:

  1. mission_handoff is called automatically
  2. Session is rotated (fresh context window)
  3. mission_resume is called in the new session

This is new infrastructure that only Hermes can provide (Mosaic runs outside the agent loop).

Implementation Tasks

Phase 1: Core state management (Python port of coord)

Task Files Estimate
1.1 Port mission.json read/write to Python mission_state.py 2h
1.2 Port TASKS.md parser to Python mission_state.py 2h
1.3 Port MISSION-MANIFEST.md reader to Python mission_state.py 1h
1.4 Implement mission_create tool-call mission_tools.py 1h
1.5 Implement mission_status tool-call mission_tools.py 1h
1.6 Implement mission_next_task tool-call mission_tools.py 1h
1.7 Implement mission_update_task tool-call mission_tools.py 1h
1.8 Register mission toolset in Hermes registry tools/registry.py 30m
1.9 Add mission to orchestrator profile toolsets config.yaml 10m
1.10 Write unit tests for mission_state tests/test_mission_state.py 2h
1.11 Write unit tests for TASKS.md parser tests/test_tasks_parser.py 1h

Phase 1 estimate: ~13h

Phase 2: Handoff and session continuity

Task Files Estimate
2.1 Define handoff packet schema (JSON) mission_handoff.py 1h
2.2 Implement mission_handoff tool-call mission_handoff.py, mission_tools.py 2h
2.3 Implement mission_resume tool-call mission_handoff.py, mission_tools.py 2h
2.4 Wire handoff into session start (auto-resume) agent loop hook 2h
2.5 Write tests for handoff round-trip tests/test_mission_handoff.py 1h

Phase 2 estimate: ~8h

Phase 3: Churn detection

Task Files Estimate
3.1 Define churn signal weights and thresholds mission_churn.py 1h
3.2 Implement tool-loop detector (consecutive identical calls) mission_churn.py 2h
3.3 Implement compaction pressure detector mission_churn.py 1h
3.4 Implement progress scorer (file state delta) mission_churn.py 2h
3.5 Wire churn scoring into agent turn loop agent loop middleware 2h
3.6 Implement auto-rotation trigger agent loop + handoff 2h
3.7 Write tests for churn scoring tests/test_mission_churn.py 1h

Phase 3 estimate: ~11h

Phase 4: Kanban bridge + CLI surface

Task Files Estimate
4.1 Implement TASKS.md → Kanban sync (one-way first) mission_kanban_sync.py 2h
4.2 Add hermes mission CLI subcommand mission_cli.py 2h
4.3 Add hermes mission status command mission_cli.py 1h
4.4 Add hermes mission init command mission_cli.py 1h
4.5 Add hermes mission handoff command mission_cli.py 1h
4.6 Add hermes mission resume command mission_cli.py 1h

Phase 4 estimate: ~8h

File Format Compatibility

The Python implementation MUST read and write the exact same file formats as Mosaic's TypeScript packages/coord. This means:

  1. mission.json schema is identical to Mission type in packages/coord/src/types.ts
  2. TASKS.md table format is identical to what packages/coord/src/tasks-file.ts parses
  3. MISSION-MANIFEST.md is free-form markdown (no parser needed — just read the file)
  4. Handoff packets are a new JSON format defined in this toolset (Mosaic doesn't have them yet)

This way a project can use Hermes mission tools OR Mosaic mosaic coord commands interchangeably. The files are the contract.

Relationship Diagram

Mosaic Stack (TypeScript)          Hermes Agent (Python)
┌─────────────────────────┐        ┌─────────────────────────┐
│  packages/coord          │        │  tools/mission_tools.py  │
│  ├─ mission.ts           │◄──────►│  ├─ mission_state.py     │
│  ├─ tasks-file.ts        │  same  │  ├─ mission_handoff.py   │
│  ├─ status.ts            │  files │  ├─ mission_churn.py     │
│  └─ runner.ts            │        │  └─ mission_tools.py     │
│                          │        │                          │
│  packages/prdy           │        │  skills/prdy/            │
│  └─ templates, wizard    │◄──────►│  └─ SKILL.md + templates │
│                          │        │                          │
│  plugins/mosaic-framework│        │  skills/ (existing)      │
│  └─ context injection    │◄──────►│  └─ kanban-orchestrator  │
│                          │        │     + mosaic-coding-*     │
│  plugins/macp            │        │  tools/delegate_task.py  │
│  └─ ACP bridge           │◄──────►│  └─ already covers this  │
│                          │        │                          │
│  (stays in Mosaic)       │        │  tools/kanban_tools.py   │
│  apps/gateway            │        │  └─ Hermes Kanban DB     │
│  apps/web                │        │                          │
│  packages/db             │        │  tools/cronjob_tools.py  │
│  packages/queue          │        │  └─ already covers cron  │
└─────────────────────────┘        └─────────────────────────┘

Open Questions

  1. Should the mission toolset ship with Hermes core, or as a plugin?

    • Recommendation: ship as a built-in toolset (like kanban) since mission coordination is a core agent capability, not an optional integration. The file formats are stable and the code is small.

  2. Should churn detection be per-profile configurable?

    • Recommendation: yes. Add mission.churn_threshold and mission.churn_weights to profile config.yaml. Default threshold = 5 consecutive no-progress turns.

  3. Should handoff packets live in the project dir or in Hermes home?

    • Recommendation: project dir (.mosaic/handoffs/<session-id>.json). This keeps them version-controlled and accessible regardless of which agent runtime picks up the project.

  4. Bidirectional Kanban sync?

    • Recommendation: one-way first (TASKS.md → Kanban). Bidirectional adds conflict resolution complexity. Ship one-way, add reverse sync in v2 if needed.

  5. PRD generation — skill or tool-call?

    • Recommendation: skill (prdy). PRD generation is a prompt engineering problem with templates. Skills already handle this pattern perfectly.
Reference in New Issue View Git Blame Copy Permalink