Kanban Agent Execution

What it is

A visible execution workflow that uses board movement to show agent progress and blockers.

Operating shape

• Difficulty: intermediate
• Cadence: continuous
• Category: execution

Core concepts

• Kanban Execution
• Agent Team Delegation
• Sessions
• Artifacts
• Manual Triggering

Source evidence

• vendor/hermes-agent/toolsets.py#<file> — Structural Source Map fallback for toolsets.py. A core source file in the Tool Registry and Toolsets structure within Tools, Toolsets, and MCP.

Related articles

• Ten Hermes Workflows That Turn a Chatbot into a 24/7 Assistant
• Six Hermes Use Cases for a More Intentional Personal Operating System

Implementation pattern

Outcome

Move one bounded task from creation through worker claim to a structured completion handoff, then prove the board’s block, unblock, and retry recovery path.

Before you start

• Create the disposable workspace and input.txt exactly as shown below; do not use a directory containing credentials.
• Run hermes kanban assignees and copy an existing low-privilege profile name into ASSIGNEE; never invent lab-worker.
• Keep one dispatcher only: the supported default is the gateway-embedded dispatcher.
• Set a low retry limit and a precise acceptance test so failure is visible.

Input and output contract

Input is input.txt containing three lines. The task may create only output.txt, containing the same lines sorted alphabetically. Completion must include a structured summary plus metadata naming the changed file and verification performed. No network access, commits, or files outside the disposable workspace are allowed.

Expected output.txt
alpha
beta
gamma

Build it

Create the input, initialize the board, inspect gateway state, and list real assignees:

LAB_DIR="$HOME/hermes-labs/kanban-agent-execution"
mkdir -p "$LAB_DIR"
printf 'gamma\nalpha\nbeta\n' > "$LAB_DIR/input.txt"
cd "$LAB_DIR"

hermes kanban init
hermes gateway status
hermes kanban assignees

If status reports an installed but stopped service, run hermes gateway start and check status again. If no service is installed, either run hermes gateway install followed by hermes gateway start, or keep hermes gateway running interactively in a second terminal. Do not continue until hermes gateway status or the foreground terminal proves the gateway and embedded dispatcher are running.

Set ASSIGNEE to an exact name returned by hermes kanban assignees, then create the bounded task:

ASSIGNEE="replace-with-a-listed-profile"
test "$ASSIGNEE" != "replace-with-a-listed-profile"

hermes kanban create "Sort the three-line fixture" \
  --assignee "$ASSIGNEE" \
  --workspace "dir:$LAB_DIR" \
  --max-retries 3 \
  --body "Read input.txt, create only output.txt sorted alphabetically, verify it has exactly three lines, then complete with a summary and metadata listing changed_files and the check run. Do not use the network or commit."
hermes kanban watch --assignee "$ASSIGNEE"

The worker should use its kanban_show, heartbeat, and kanban_complete tools; humans use the CLI to inspect the same board.

Verify it

• hermes kanban list --assignee "$ASSIGNEE" shows the task progress from ready/in-progress to done.
• hermes kanban show <task_id> and hermes kanban runs <task_id> show a completed run, summary, and metadata.
• output.txt exactly matches the expected three lines; no other file changed.
• Human-block fixture: create a second ordinary task, immediately run hermes kanban block <block_task_id> "needs input: missing fixture", add the requested fixture, then run hermes kanban unblock <block_task_id>. This tests an explicit human dependency, not dispatcher retry.
• Dispatcher-retry fixture: use a fresh temporary directory that is deliberately not a Git repository as the parent of a requested worktree. Hermes accepts the task, but the dispatcher cannot materialize a linked worktree there, so this exercises the source-defined spawn-failure path rather than relying on a missing dir: workspace (Hermes creates missing dir: paths automatically):

NON_REPO_PARENT="$(mktemp -d)"
RETRY_JSON=$(hermes kanban create "Prove dispatcher retry" \
  --assignee "$ASSIGNEE" \
  --workspace "worktree:$NON_REPO_PARENT/worker" \
  --max-retries 3 \
  --body "This fixture must never reach a worker." \
  --json)
RETRY_TASK_ID=$(printf '%s' "$RETRY_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

hermes kanban runs "$RETRY_TASK_ID"
hermes kanban show "$RETRY_TASK_ID"

Wait for the dispatcher to exhaust the three attempts. The runs must record spawn failures and the task must finish in the circuit-breaker blocked state with a gave_up outcome. Inspect the evidence before removing the empty temporary parent. Do not confuse this automatic retry history with manual block/unblock.

• Both fixture histories retain earlier attempts instead of erasing failure evidence.

If it fails

• If a ready task never starts, run hermes gateway status and hermes kanban diagnostics; do not start the deprecated standalone daemon alongside the gateway.
• If the assignee does not exist, choose one reported by hermes kanban assignees rather than inventing a profile.
• If the circuit breaker blocks the main task, inspect hermes kanban runs <task_id> and the worker log, fix the cause, then explicitly unblock. The intentionally invalid worktree fixture should remain blocked until its test is inspected.
• If the worker touches the wrong path, stop it, discard the disposable workspace, and recreate the task with a tighter boundary.

Safety, privacy, and cost

Workers are agents with file/tool access. Use disposable workspaces, narrow profiles, clear stop conditions, and low retry/concurrency limits. Never place secrets in task bodies or metadata, which are durable board records. Each retry can repeat model and tool cost; inspect the first failure instead of automatically increasing retries.

Official references

• Kanban tutorial
• Kanban feature reference
• Tools reference