Hermes Org Mode

Matrix-first publish/subscribe operating mode for Hermes — channels as topics, local subscribers as launchers, Hermes workers as bounded executors, and durable state split across Forgejo and Hindsight.

Fast implementation, visible coordination, bounded execution without a central orchestrator.

Architecture (14 components)

#	Component	Role
1	Matrix bus	Shared event and conversation substrate
2	Room topology	Room naming and event class conventions
3	Subscriber-launcher	Local channel observer that launches workers
4	Worker pack	Bounded executable worker library
5	Contract files	Worker input/output/timeout contracts
6	Forgejo bridge	Webhook → Matrix event publisher
7	Status bot	Run/failure reporting into Matrix
8	Run ledger	SQLite local run audit trail
9	Policy layer	Guardrails: allowlists, cooldowns, concurrency
10	Cron layer	Time-based scheduled work from same worker pack
11	Reconciliation jobs	Low-frequency drift/audit backstops
12	Forgejo workspace	Durable code, issues, proposals, configs
13	Hindsight memory	Persistent scoped memories across runs
14	Supervisor UI	Human inspection/management surface

Implementation order

1. Forgejo workspace
2. Hermes worker pack
3. Local worker contract files
4. Forgejo bridge
5. Matrix room topology
6. Subscriber-launcher
7. Local run ledger
8. Matrix status bot
9. Subscriber runtime policy layer
10. Cron layer + Reconciliation jobs
11. Hindsight memory layer
12. Supervisor UI

Access model

• Matrix-visible profiles — room participation only
• Local worker scripts — no Matrix credentials
• CLI/admin profiles — local dev without room presence

Directory layout

docs/             — design spec, proposals
src/              — implementation
  workers/        — bounded worker scripts
  bridge/         — Forgejo bridge
  subscriber/     — subscriber-launcher
  status-bot/     — Matrix status reporting
  ledger/         — local run ledger
  policy/         — runtime policy layer
  cron/           — scheduled work
  reconciliation/ — drift/audit jobs
  supervisor-ui/  — human inspection surface
config/           — example configs, contracts
tests/            — test suite
install/          — install/sync helpers

Spec: docs/design-spec.md