Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / kanban-workflow-automation

Kanban workflow automation

Kanban is a durable work system for turning broad goals into owned work items, routing those items to agent profiles, and tracking each result until completion, review, or recovery. It keeps the board as the shared source of truth while agents, the dispatcher, and people work through the same task graph.

System boundary

Kanban separates planning from execution. A planner or human defines the work graph, the dispatcher starts the right worker for each ready item, and the worker reports its result back to the board. This makes work discoverable and resumable instead of tying it to one chat turn or one parent process.

flowchart LR
    G[Goal or rough idea] --> T[Triage]
    T --> P[Specify or decompose]
    P --> D[Dependency graph]
    D --> R[Ready work]
    R --> W[Assigned worker]
    W --> H[Complete, review, or block]
    H --> N[Durable handoff and notification]
    N --> D

The board is the coordination boundary between these roles. A worker can finish one item without knowing how the rest of the plan runs, while a later worker can use the saved handoff and task history to continue the larger flow.

Work model

Boards and work items

A board is an isolated stream of work. A work item is one unit of work on that board with a goal, an owner, a state, and a place for durable results. Boards keep unrelated projects apart, while the work item gives every agent a stable object to read and update. hermes_cli/kanban_db.py hermes_cli/kanban_db.py

The main work-item states describe where attention belongs:

StateMeaning in the workflow
triageThe idea needs a usable specification or plan.
todoThe item exists but waits for a dependency or later routing step.
readyThe item may be claimed by its assigned worker.
runningA worker owns the current attempt.
reviewWork is ready for a reviewer or approval step.
blockedProgress needs a decision, capability, or outside event.
doneThe work has met its completion contract.
archivedThe item is kept for history but is outside active work.

References: hermes_cli/kanban_db.py• L1-13 hermes_cli/kanban_db.py• L328-365 hermes_cli/kanban_workflow.py• L27-51 hermes_cli/kanban_workflow.py• L110-142

Dependencies and workspaces

Dependencies turn separate work items into a graph. Independent children can run in parallel, while a child with open parents waits until those parents finish. Each item also has a workspace suited to its work, so an agent can operate without changing the board's coordination state. hermes_cli/kanban_db.py tools/kanban_tools_schemas.py

The graph supports two common shapes:

  • Fan-out: one plan creates several independent specialist tasks.
  • Fan-in: a later task waits for several completed tasks and combines their results.

Workspace choice follows the nature of the task:

  • A scratch space is useful for disposable work.
  • A shared directory is useful when the work must remain in an existing folder.
  • A worktree is useful when code changes need an isolated Git context.

References: hermes_cli/kanban_db.py• L569-589 hermes_cli/kanban_db_graph.py• L1-20 tools/kanban_tools_schemas.py• L386-445

Planning and routing

Triage and decomposition

Triage is the planning entry point for rough or incomplete requests. An agent-assisted specifier can turn a rough idea into a goal, approach, and acceptance criteria. A decomposer can instead create a small dependency graph and route each child to the best available profile. hermes_cli/kanban_specify.py hermes_cli/kanban_decompose.py

The planning choice is deliberate:

  • Keep the item as one task when it is already a single unit of work.
  • Split it when independent roles can make progress in parallel.
  • Keep the original root item as the owner of the larger outcome, so it can assess the child results and add follow-up work.

If an automated planner cannot find a matching profile, routing falls back to the configured default rather than leaving new work without an owner. A malformed or unavailable planning response leaves the item available for later attention instead of silently claiming success. hermes_cli/kanban_decompose.py hermes_cli/kanban_decompose.py

References: hermes_cli/kanban_specify.py• L32-60 hermes_cli/kanban_specify.py• L190-234 hermes_cli/kanban_decompose.py• L1-16 hermes_cli/kanban_decompose.py• L303-336

Assignment and dispatch

Assignment names the profile or worker lane that should perform the item. The dispatcher is the active work router: it promotes items whose dependencies are clear, claims each item once, and starts the assigned lane. It also limits concurrent work so a large fan-out does not overwhelm the host or a profile. gateway/kanban_watchers_dispatcher.py hermes_cli/kanban_db_dispatch.py

The dispatcher runs as a gateway-owned service by default. In a multi-gateway setup, one gateway owns dispatch while other gateways deliver notifications for the profiles they serve. This prevents competing dispatchers from starting the same item while keeping delivery close to each profile's communication channel. website/…/kanban-multi-gateway.md

See Kanban persistence for board state and Kanban dispatch for claim and routing rules.

References: gateway/kanban_watchers_dispatcher.py• L120-244 hermes_cli/kanban_db_dispatch.py• L88-151 website/…/kanban-multi-gateway.md• L19-52

Agent-assisted execution

Worker lifecycle

A worker lane is the execution role for one assigned item. The worker reads the task context, works in the assigned workspace, and must end the attempt with a clear board action: complete the item, request review, or block it with a reason. The board remains responsible for lifecycle truth; the worker supplies the work and the handoff. website/…/kanban-worker-lanes.md website/…/kanban-worker-lanes.md

The model-facing Kanban tools match these roles. Orchestrators can list, create, link, and unblock work. Task workers can inspect their item, report progress, attach evidence, and perform their own terminal handoff. This keeps planning authority separate from execution authority. tools/kanban_tools.py tools/kanban_tools_schemas.py tools/kanban_tools_schemas.py

See Kanban worker orchestration for worker roles and Kanban workflow execution for the execution path.

References: website/…/kanban-worker-lanes.md• L12-21 website/…/kanban-worker-lanes.md• L74-105 tools/kanban_tools.py• L83-114 tools/kanban_tools_schemas.py• L47-87

Review and handoff

Completion is a handoff to the next reader, not only a status change. Workers can finish directly when the contract is met, or move the item into review when another agent or person must approve the result. A reviewer can approve the work or send actionable changes back to the original implementer without treating normal review as a failure. website/…/kanban-worker-lanes.md tools/kanban_tools_schemas.py

The handoff carries a short summary and optional structured evidence. This lets downstream work use the result without scraping a worker transcript. For code work, the completion contract can also require an accepted published change before the item is considered done. tools/kanban_tools_schemas.py website/…/kanban.md

References: website/…/kanban-worker-lanes.md• L85-95 tools/kanban_tools_schemas.py• L89-165 tools/kanban_tools_schemas.py• L221-288 website/…/kanban.md• L48-95

Human and agent coordination

Notifications and wake-up

Notifications connect durable board events back to the person or agent that created the work. The notifier claims unseen events for each subscription, sends a task update, and can wake the originating session when the event needs a decision or a follow-up turn. It keeps the event cursor durable so retries do not lose work. gateway/kanban_watchers_notifier.py gateway/kanban_watchers_notifier.py

The notification flow treats delivery and wake-up as related but separate actions. A passive message can show progress, while a wake-up returns control to the session that can inspect the board and decide what to do next. Failed delivery is retried, and subscriptions remain active through recoverable task states so later retries and review cycles remain visible. gateway/kanban_watchers_notifier.py gateway/kanban_watchers_notifier.py

References: gateway/kanban_watchers_notifier.py• L44-75 gateway/kanban_watchers_notifier.py• L321-342 gateway/kanban_watchers_notifier.py• L507-516 gateway/kanban_watchers_notifier.py• L767-840

Recovery and retry

Recovery keeps a task from becoming lost when a worker, provider, or host fails. The dispatcher distinguishes normal retryable failure from a task that needs human attention, then requeues, blocks, or escalates the item with a durable event and reason. Liveness signals and run history help it tell an active worker from a dead or stalled attempt. hermes_cli/kanban_db_dispatch.py hermes_cli/kanban_db_dispatch.py

The recovery model is bounded. Repeated failures can trip a circuit breaker instead of creating an endless spawn loop. A worker that exits without a terminal Kanban action is also recorded as a protocol failure and receives only bounded retries. This leaves the item visible for repair rather than marking incomplete work as successful. hermes_cli/kanban_db_dispatch.py hermes_cli/kanban_db_dispatch.py

See Kanban recovery for failure, reclaim, and retry behavior.

References: hermes_cli/kanban_db_dispatch.py• L605-640 hermes_cli/kanban_db_dispatch.py• L750-850 hermes_cli/kanban_db_dispatch.py• L931-987 hermes_cli/kanban_db_dispatch.py• L1103-1135

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the workflow states, model-tool status choices, and board UI transitions aligned.
  • Keep dependency completion rules aligned with the dispatcher promotion rules.
  • Keep worker terminal actions aligned with run closure and retry classification.
  • Keep event names aligned across persistence, notification, and wake-up paths.
  • Keep board routing aligned across single-gateway and multi-gateway deployments.

Important failure modes

TriggerConsequenceGuard
A child is linked to an unfinished parentThe child waits instead of running.Dependency promotion checks all parent states.
A worker exits without a terminal board actionThe attempt is recorded as a protocol failure and may be retried or blocked.Worker lifecycle requires complete, review, or block.
A worker stays active without liveness progressThe dispatcher may reclaim the attempt and requeue it.Heartbeats and runtime activity extend active work.
Repeated spawn or worker failures continueThe item is blocked instead of respawned forever.The failure circuit breaker bounds retries.
A notification send failsThe event cursor is not settled, so the event can be retried.Delivery rewinds or drops only a persistently dead subscription.

Key files

FileWhy to read it
hermes_cli/kanban_db.pyBoard, task, dependency, run, and event concepts.
hermes_cli/kanban_workflow.pyThe board states and human move rules.
hermes_cli/kanban_decompose.pyAgent-assisted graph planning and profile routing.
gateway/kanban_watchers_dispatcher.pyGateway-owned dispatch across boards.
hermes_cli/kanban_db_dispatch.pyClaim, worker start, retry, and recovery behavior.
tools/kanban_tools_schemas.pyThe planning and worker handoff contract exposed to agents.
gateway/kanban_watchers_notifier.pyEvent delivery and session wake-up.
website/…/kanban-worker-lanes.mdThe worker-lane and review model.