Skip to content
Back to search

hermes-conductor

One Hermes conductor. Many coding CLIs. Zero trust in self-reports. Production multi-harness orchestration patterns: worktree lanes, verification gates, recovery playbooks — from 18 kanban boards and every incident that tried to ruin them.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/forcewake--hermes-conductor/badge.svg)](/listings/forcewake--hermes-conductor)

HTML

<a href="/listings/forcewake--hermes-conductor"><img src="/api/listings/forcewake--hermes-conductor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The role playbooks are installable Hermes skills:

# on your orchestrator profile's machine/home:
hermes skills install forcewake/hermes-conductor/skills/kanban-orchestrator

# on each worker profile:
hermes skills install forcewake/hermes-conductor/skills/kanban-worker

> `hermes skills install` accepts any `owner/repo/path` GitHub identifier — > no registry listing needed. The `patterns/` docs are meant to be read by > the human operating the controller, not installed.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 173 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Hermes Conductor
  2. **One Hermes conductor. Many coding CLIs. Zero trust in self-reports.**
  3. Production orchestration patterns for running external coding agents — Claude Code, OpenCode, Codex CLI, MiMo, agy, or anything else that edits files — under a single [Hermes Agent](https://github.com/NousResearch/hermes-agent) kanban controller.
  4. Distilled from **18 production boards, 367 cards, 566 agent dispatches — and every incident that tried to ruin them.**
  5. ```
  6. ┌──────────────────────┐
  7. │ Hermes Conductor │
  8. │ (route-only profile) │
  9. │ "Don't do the work. │
  10. │ Route only." │
  11. └──────────┬───────────┘
  12. decompose / fan-out / verify / integrate
  13. ┌──────────────────┬─────┴────────┬──────────────────┐
  14. ▼ ▼ ▼ ▼
  15. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
  16. │ worktree │ │ worktree │ │ worktree │ │ worktree │
  17. │ lane A │ │ lane B │ │ lane C │ │ lane D │
  18. │ Claude Code │ │ OpenCode │ │ Codex CLI │ │ MiMo │
  19. └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
  20. │ diff/tests/commits — verified by the controller, never │
  21. ▼ trusted from the agent's own report ▼
  22. ┌─────────────────────────────────────────────────────────────────┐
  23. │ canonical integration branch + evidence │
  24. └─────────────────────────────────────────────────────────────────┘
  25. ```
  26. ## Demos
  27. Both are real runs, no cuts; only idle time is compressed.
  28. **1. Native dispatch cycle** — the controller creates a card, the gateway dispatcher hands it to a worker profile, the worker implements and tests, and the controller re-runs the tests itself before accepting the evidence. That last step is the whole point.
  29. ![hermes-conductor demo](assets/conductor-demo.svg)
  30. Cast: [`demo.cast`](assets/demo.cast) · narrated cut: [SVG](assets/conductor-demo-narrated.svg) / [MP4](assets/demo-narrated.mp4)
  31. **2. Claude Code as the lane executor (pattern 01)** — the controller keeps the card controller-owned, Claude Code works an isolated git worktree headlessly (`claude -p`), then the controller re-runs the tests and closes the card with evidence. Same board API, any CLI executor.
  32. ![claude-code lane demo](assets/cc-lane-demo.svg)
  33. Cast: [`demo-claude-code.cast`](assets/demo-claude-code.cast) · video: [MP4](assets/cc-lane-demo.mp4)
  34. ## Lane executor modes: CLI or SDK
  35. Pattern 01 shows the raw CLI lane (`claude -p`). For production lanes we run a structured runner built on the official Claude Agent SDK instead — same board lifecycle, tighter contract:
  36. - per-lane budget caps (`max_budget_usd`), `max_turns`, hard timeout
  37. - explicit allowed/disallowed tool grants per lane (no ambient toolset)
  38. - fail-closed provenance checks: the lane refuses to start if the runtime is not on the `expected_model` / `expected_context_window` the card was planned for
  39. - every run emits a JSON receipt (turns, cost, result) that the controller attaches as card evidence instead of parsing chat output
  40. That last point matters more than it sounds: receipts turn "the agent said it went fine" into machine-checkable evidence. The runner is being packaged for separate publication — watch this repo.
  41. ## Why this exists
  42. The multi-harness wave is here — "Hermes as the brain, other agents as the arms." What the bridge demos don't show you is what happens on day 3:
  43. | Failure | What actually happens |
  44. |---|---|
  45. | **Self-report trust** | An external agent says "done, tests pass." Nothing passed. If your controller believes it, your canonical branch rots. |
  46. | **Parallel mutation collision** | Two worker cards land in the same checkout. Both "succeed." One overwrites the other. |
  47. | **Stale-base auto-promotion** | A dependency completes → downstream card auto-promotes → its lane worktree still points at last week's HEAD. Silent divergence. |
  48. | **Approval deadlock loops** | A worker hits a pending-approval command; the dispatcher respawns it forever; your board eats tokens overnight. |
  49. | **Evidence-free "done"** | Cards close with vibes instead of commit IDs and command output. Audits become archaeology. |
  50. Every pattern in this repo exists because we hit the failure above it — in production, at 2am, more than once.
  51. ## The golden rules
  52. 1. **The orchestrator never implements.** Its SOUL.md says: *"Do not implement. Do not research. Do not write code. Route only."*
  53. 2. **External agent self-reports are never card-completion evidence.** The controller verifies the worktree diff, reruns gates, and completes cards with commit IDs + command output.
  54. 3. **Every mutating lane gets its own worktree.** Parallel cards sharing a checkout is not a workflow, it's a race condition. `--workspace worktree` or `dir:` — never the canonical checkout.
  55. 4. **`--parent` is a dependency edge, not a folder.** Children stay blocked until the parent completes *with evidence*.
  56. 5. **Controller-sequential for dependent chains.** "Implement all" on a dependency graph is an ordered queue, not a parallel fan-out — unless the plan proves independence.
  57. 6. **Completing a dependency may auto-promote stale lanes.** After every unblock: `git worktree list`, check each promoted lane's HEAD, block-and-restart anything stale.
  58. 7. **Standing lanes stay blocked; bounded cron owns execution.** Ready + normal assignee on an eternal lane card = the dispatcher will spawn uncontrolled one-shots.
  59. 8. **Complete with evidence or don't complete.** `kanban complete <id> --result "commit abc123, gates green"` — status flips without evidence get reverted.
  60. ## Install
  61. The role playbooks are installable Hermes skills:
  62. ```bash
  63. # on your orchestrator profile's machine/home:
  64. hermes skills install forcewake/hermes-conductor/skills/kanban-orchestrator
  65. # on each worker profile:
  66. hermes skills install forcewake/hermes-conductor/skills/kanban-worker
  67. ```
  68. > `hermes skills install` accepts any `owner/repo/path` GitHub identifier —
  69. > no registry listing needed. The `patterns/` docs are meant to be read by
  70. > the human operating the controller, not installed.
  71. ## What's inside
  72. ### `patterns/` — the playbooks
  73. | # | Pattern | Solves |
  74. |---|---|---|
  75. | 01 | [Controller-managed external worktree lanes](patterns/01-controller-managed-external-worktree-lanes.md) | **The core pattern.** Launch templates for Claude Code / OpenCode / MiMo / agy lanes, smoke-first discipline, stale-base recovery, completion verification. |
  76. | 02 | [Workspace isolation](patterns/02-workspace-isolation.md) | Same-checkout collisions: `worktree` for parallel mutation, reclaim/block one card at a time. |
  77. | 03 | [Single-repo MCP swarm](patterns/03-single-repo-mcp-swarm.md) | Swarm inside one repo: skill preflight, isolation checks, review-required completion loop, final MCP verification gates. |
  78. | 04 | [Controller-sequential epic finalization](patterns/04-controller-sequential-epic-finalization.md) | Closing an epic after children fan out: PR handoff, integration order, canonical gates. |
  79. | 05 | [Controller-sequential recovery](patterns/05-controller-sequential-recovery.md) | The collision-recovery checklist: reclaim auto-spawned cards, integrate in dependency order, re-check the board after each card. |
  80. | 06 | [Production swarm recovery](patterns/06-production-swarm-recovery.md) | Large completion swarms: research fan-out, task subscriptions, progress watchers. |
  81. | 07 | [Prototype furnace daily digest](patterns/07-prototype-furnace-daily-digest.md) | Standing-lane boards: committed-artifact counting, evidence gates, survivor selection, repo verification. |
  82. ### `skills/` — installable role playbooks
  83. | Role | What it is |
  84. |---|---|
  85. | [`kanban-orchestrator`](skills/kanban-orchestrator/SKILL.md) | The decomposition playbook: profile discovery, anti-temptation rules, fan-out/in, reviewer remediation loops, research-swarm artifact contracts. Includes [reviewer-remediation-loop](skills/kanban-orchestrator/references/reviewer-remediation-loop.md) and [research-swarm-artifact-pattern](skills/kanban-orchestrator/references/research-swarm-artifact-pattern.md). |
  86. | [`kanban-worker`](skills/kanban-worker/SKILL.md) | The worker lifecycle: claim → workspace → heartbeat → `kanban_complete(summary, metadata)` or `kanban_block` — plus edge cases that kill workers. |
  87. ### `examples/` — cheatsheet
  88. - [`kanban-cheatsheet.md`](examples/kanban-cheatsheet.md) — the commands, in the order you'll actually use them.
  89. ## Quickstart
  90. You have [Hermes Agent](https://github.com/NousResearch/hermes-agent) v0.20+ running with the kanban dispatcher enabled (`kanban.dispatch_in_gateway: true`).
  91. ```bash
  92. # 1. Board + first controller-managed card
  93. hermes kanban init
  94. hermes kanban create "Ship feature X" \
  95. --assignee your-worker-profile \
  96. --workspace worktree \
  97. --body "Implement per 01-spec.md. Tests green. Complete with commit ID as evidence."
  98. # 2. Give the orchestrator profile its constitution (SOUL.md):
  99. # "Do not implement. Do not research. Do not write code. Route only."
  100. # 3. Watch the controller — not the agents — close cards
  101. hermes kanban watch
  102. ```
  103. Then read [pattern 01](patterns/01-controller-managed-external-worktree-lanes.md) before your second card. It's the difference between a demo and a pipeline.
  104. ## Battle scars (where these came from)
  105. - A "successful" overnight swarm where three lanes silently built on a base that no longer existed → patterns 01, 05.
  106. - Two worker cards editing the same checkout for hours before anyone noticed → patterns 02, 05.
  107. - A card auto-promoted by its dependency completing, dispatched into a worktree two days stale → pattern 01's stale-base check.
  108. - A dispatcher loop respawning a worker stuck on an approval, all night → the standing-lane rule.
  109. - Review findings that "fixed" themselves because the reviewer card and the fix card raced → the remediation loop in `skills/`.
  110. None of these are hypothetical. All of them have a recovery checklist here.
  111. ## Requirements
  112. - Hermes Agent v0.20+ (kanban CLI + gateway dispatcher)
  113. - External coding CLIs installed and authenticated (any subset — Claude Code, OpenCode, Codex, MiMo, agy, custom)
  114. - git worktrees enabled in your environment
  115. ## Contributing
  116. Questions, feedback, or your own adaptations of the patterns — post in the [discussion board](https://github.com/forcewake/hermes-conductor/discussions/1) (it's the pinned thread).
  117. Ran a multi-harness board and hit a failure none of these patterns cover? Open an issue with the incident — recovery playbooks from real failures are exactly what this repo collects.
  118. ## Related
  119. The lane runtimes in these patterns were not picked by vibes — they were picked by measurement. [coding-agent-battles](https://github.com/forcewake/coding-agent-battles) is the public benchmark harness: 12 scenarios, 6 agent scaffolds, 72 runs, with per-run token/cost telemetry, correctness evidence, and an audit pack.
  120. ## License
  121. [MIT](LICENSE) — battle-tested by necessity, shared so you can skip the 2am part.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.