hermes-workflow 0.1.4

Declarative multi-stage workflow primitive over the Hermes Kanban board.

hermes-workflow

A declarative, versioned, multi-stage workflow primitive over the Hermes Kanban board.

A *.workflow.yaml template — params, abstract roles bound to lanes, stages with needs, a single-level expand fan-out plus an expand_out shape gate, a human gate, and workspaces — is instantiated into a Kanban card-graph that Hermes' existing dispatcher and worker lanes execute. It turns "hand-wire an orchestrator from scratch every run" into a repeatable, durable, inspectable run on the board you already use.

What it is

A template compiles to a linked card-graph. Materialization is lazy and single-level:

• workflow_start validates the template + bindings, runs a per-profile pre-flight, and creates the dynamic-free prefix (the static stages up to the first fan-out) plus a write-once compiled-snapshot blackboard root.
• The post_tool_call fan-out hook fires as stages complete: when a source stage finishes, it creates that fan-out's children and its join in one atomic create, wiring the join as a child of every instance.

Completion-gating is deterministic and injection-free, enforced by a pre_tool_call veto: it checks the expand_out shape + max, and commit-clean for worktree stages, before a stage may complete. There is no LLM in the gate.

All state lives on the board — body sentinels, links, and statuses — and the run root is a write-once compiled-snapshot blackboard. Nothing touches raw SQLite — every mutation goes through Hermes' board APIs (kanban_* from workers, kb.* from the host).

Requirements

• Hermes Agent v0.15.x
• Python ≥ 3.11
• For any role with lane: codex: the codex binary on PATH, and Hermes' bundled kanban-codex-lane skill present in that role's bound profile. This plugin reuses that skill — it does not re-ship it.

Quick Install

The intended primary path is PyPI:

pip install hermes-workflow

From source:

git clone https://github.com/carlosraphael/hermes-workflow
cd hermes-workflow
pip install -e .

Then enable it in EVERY bound profile — not just the orchestrator's. This is a pip / entry-point plugin, so hermes plugins enable does not apply to it (that command only sees user-dir and bundled plugins). Instead add hermes-workflow to the plugins.enabled list in each bound profile's config.yaml — open it with hermes -p <profile> config edit (or edit <that profile's HERMES_HOME>/config.yaml directly) and add:

plugins:
  enabled:
    - hermes-workflow

The change takes effect on the next session. (Do not use hermes config set plugins.enabled … — it writes a scalar string, which breaks the loader's list check.)

Per-profile enablement is the #1 failure mode. Workers read the plugin's load status from the assignee profile's home, so the plugin must be enabled and loadable in every profile a role binds to. workflow_start runs a per-profile loadability pre-flight and fails fast — creating zero cards — with a per-profile remediation map if any bound profile cannot load it (or a codex role is missing its codex binary / kanban-codex-lane skill).

Quickstart

Using examples/build-hermes-plugin.workflow.yaml — a workflow that dogfoods this repo, extending hermes-workflow with new workflow_* surfaces. Both invocation surfaces — the slash command and the CLI — take the same arguments. (examples/feature-delivery.workflow.yaml is a second, generic feature-delivery SDLC you can run against any repo.)

In-session slash command:

/workflow start --template examples/build-hermes-plugin.workflow.yaml \
  --params '{"repo":"/abs/path/to/hermes-workflow","capability":"a workflow_pause/workflow_resume tool pair"}' \
  --bindings '{"architect":"designer","builder":"coder","tester":"designer","reporter":"writer"}'

CLI:

hermes workflow start --template examples/build-hermes-plugin.workflow.yaml \
  --params '{"repo":"/abs/path/to/hermes-workflow","capability":"a workflow_pause/workflow_resume tool pair"}' \
  --bindings '{"architect":"designer","builder":"coder","tester":"designer","reporter":"writer"}'

Run lifecycle

1. The spec worker (role architect) decomposes the capability and returns metadata.surfaces = [{name, kind, summary}, …].
2. The fan-out hook creates one implement card per surface — each on its own pre-provisioned worktree, gated by commit-clean — and wires the integrate join as a child of all of them.
3. integrate (role architect) merges the per-surface branches; test (role tester) then runs the suite.
4. The review human gate promotes to ready. The operator runs hermes workflow approve <gate_card> — find it under awaiting_approval via hermes workflow status <root_id>.
5. report (role reporter) then runs, summarizing the added surfaces and the branches from the handoffs.

Commands

Both surfaces — the CLI (hermes workflow <cmd>) and the slash command (/workflow <cmd>) — dispatch the same tools (workflow_start … workflow_abandon).

Command	Form	What it does
start	--template <path> --params <json> --bindings <json> [--board]	Validate, pre-flight every bound profile, then seed the run (root blackboard + dynamic-free prefix). Fails closed with zero cards if any profile can't load.
status	<root_id> [--board]	Read-only run summary: per-stage rollup plus blocked_stages, awaiting_approval (the gate signal), and review_required.
validate	--template <path>	Deterministic, read-only template check. Rejects verify/retry and nested-expand.
reconcile	<root_id> [--board]	Re-drive a partial fan-out: create missing children, re-link to the join, progress-aware dedup, and surface review-required stalls.
approve	<gate_card> [--board]	Complete a human gate card so its downstream stages promote natively.
abandon	<root_id> [--board]	Hazard-free teardown: reclaim running workers, then archive the run reverse-topologically (leaves-first). Worktrees are preserved.

The four mutating commands (start, reconcile, approve, abandon) refuse to run inside a dispatcher-spawned worker — they are orchestrator-context only.

Bundled skills

Two skills are auto-registered on plugin load:

• workflow-author — how to write a *.workflow.yaml template within the 0.1.0 constraints; validate it with workflow_validate.
• workflow-orchestrator — start / status / approve / abandon / reconcile, plus the review-required backstop for recovering a stalled stage.

0.1.0 scope

Lanes are {profile, codex} only — claude-code is deferred to 0.2.x. verify.command / retry and granular reject / modify are deferred to 0.2.x. Nested fan-out (an expand stage that is itself an expand source) is forbidden in 0.1.0.

Documentation

Document	What it covers
AGENTS.md	Development guide for AI coding assistants and contributors.
CONTRIBUTING.md	Development setup, PR process, and code style.
docs/operations.md	Upgrade / version-gate procedure and operational caveats.
CONTEXT.md	The naming taxonomy (distribution / import / plugin / runtime layers).
docs/adr/	Architecture decision records.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development setup, PR process, and code style.

License

MIT — Copyright (c) 2026 Carlos Raphael. See LICENSE.