Hermes Agent Kanban: the shortest reliable way for Brian to get started

Research Summary

Hermes Agent Kanban: the shortest reliable way for Brian to get started

Short thesis

The easiest reliable starting point is not a complex multi-lane swarm. It is: create 2-3 real Hermes profiles with clear role names, start the gateway so the embedded dispatcher is alive, create one assigned task on the default board, and watch it move from ready to running to done or blocked. Kanban is durable and operator-friendly once that loop works, but it is unforgiving about one thing: the assignee must resolve to a real profile, and something must actually be dispatching.

Recommended happy path

• Use the default board. Do not start with multi-board or multi-tenant complexity.

• Create a tiny roster of profiles first: one worker (backend-dev or researcher), optionally one reviewer, optionally one orchestrator later.

• Start the gateway instead of a standalone kanban daemon. Current docs and CLI reference both treat the gateway-embedded dispatcher as the normal path.

• Create one task with an explicit assignee and no dependencies.

• Watch it through the dashboard or hermes kanban tail <id> until it either completes or blocks.

• Only after that works should Brian add dependencies, orchestrator-driven decomposition, worktrees, or multiple boards.

Step-by-step getting-started workflow

1) Minimum setup Brian actually needs

• A working Hermes install.

• At least one real profile that can do work. The docs are explicit that the dispatcher matches task.assignee to a profile name by default, and leaves unresolved assignees sitting in ready.

• A running gateway if Brian wants the default durable path. Current Kanban docs say the dispatcher runs inside the gateway by default with kanban.dispatch_in_gateway: true.

• Optional but recommended: the dashboard, because it is the most comfortable operator view for watching the board.

Practical minimum command set:

• hermes profile create backend-dev --clone

• hermes profile create reviewer --clone (optional at first)

• hermes kanban init

• hermes gateway start

• hermes dashboard

Why this is the minimum:

• hermes kanban init is optional because the CLI auto-inits, but it is a clean explicit first step.

• backend-dev is enough for the first end-to-end proof.

• reviewer is only needed once Brian wants a review-required loop.

• An orchestrator profile is not required for day one. The tutorial and docs show that Kanban works fine with directly created tasks.

2) Required profiles / assignees: what matters in operator reality

The important fact is simple: assignee strings are identities. For the default lane shape, those identities are Hermes profile names.

That means Brian should start with role-shaped profile names he will actually want to assign:

• backend-dev

• researcher

• reviewer

• maybe later orchestrator

This naming matters because:

• the dispatcher uses the assignee to decide what profile to spawn,

• the orchestrator discovers profile names via hermes profile list,

• typoed or deleted profile names are one of the cleanest ways to strand tasks in ready.

The shortest recommendation: start with one worker profile and use that exact same string in --assignee.

3) Create the first task

The shortest credible first card is one task with one assignee and no dependencies:

• hermes kanban create "Sanity-check Kanban worker" --assignee backend-dev --body "Read the task, write a short summary comment, then complete the task."

Why this exact shape works:

• no parent links, so the task can go straight to ready,

• no worktree or shared-dir complications,

• no review loop,

• no orchestration ambiguity.

If Brian wants a coding-flavored first task instead:

• hermes kanban create "Document the current repo layout" --assignee backend-dev --body "Inspect the repo, summarize the main directories, and complete the task with changed_files or findings metadata."

For day one, Brian should avoid:

• --parent dependencies,

• worktree workspaces,

• dir:<path> workspaces,

• --tenant, unless he already truly needs tenant namespacing,

• triage-column auto-decomposition.

4) How the dispatcher/gateway picks it up

The current system behavior is:

• task is created,

• if it is eligible, it lands in ready,

• the gateway-embedded dispatcher sweeps boards on its tick,

• it atomically claims a ready task,

• it spawns hermes -p <assignee> chat -q <prompt> in the task workspace,

• the child worker gets environment like HERMES_KANBAN_TASK, HERMES_KANBAN_RUN_ID, HERMES_KANBAN_WORKSPACE, and board/db pointers,

• the worker closes the loop with kanban_complete(...) or kanban_block(...).

Operator consequence: if Brian creates a card and nothing is running the gateway/dispatcher, the card will just sit in ready. The CLI literally warns about this when it can detect no gateway.

Current defaults worth treating as real:

• dispatch interval: 60s by default,

• failure limit: 2 consecutive non-success attempts before auto-block,

• claim TTL: 15 minutes by default, with heartbeat/extension logic for long-running workers.

So the shortest expectation is: create a task, then either wait up to a minute or manually nudge/dispatch if using the dashboard/CLI.

5) How to watch progress

Best operator surfaces, from simplest to richest:

• Dashboard → Kanban tab: easiest for Brian. It shows columns, profile lanes, card drawers, run history, comments, and blockers.

• hermes kanban tail <task_id>: best terminal-native live view.

• hermes kanban show <task_id>: best compact forensic view after the fact.

• hermes kanban runs <task_id>: best for retry / crash / completion history.

What Brian should expect to see:

• ready → dispatcher has not claimed yet,

• running → a worker process owns it,

• blocked → worker asked for human input or circuit breaker tripped,

• done → worker completed cleanly.

The healthy first success is not fancy. It is simply: the card leaves ready, gains run history, and either lands in done or produces a legible blocked reason.

6) Most common failure modes

No gateway / no dispatcher

Symptom:

• task stays in ready forever.

Most likely cause:

• gateway is not running, or kanban.dispatch_in_gateway was turned off.

Fast fix:

• hermes gateway start

• if someone disabled embedded dispatch, turn kanban.dispatch_in_gateway back on and restart the gateway.

Assignee does not match a real profile

Symptom:

• task never gets picked up, diagnostics complain, or it remains stranded in ready.

Most likely cause:

• --assignee backend-dev was used but no backend-dev profile exists.

Fast fix:

• hermes profile list

• reassign to a real profile name, or create that profile.

Starting with too much orchestration

Symptom:

• triage cards fan out weirdly, or Brian is debugging orchestration before proving the basic worker loop.

Most likely cause:

• starting from auto-decompose/orchestrator workflows instead of a single direct task.

Fast fix:

• create one directly assigned task on the default board and prove the worker lifecycle first.

Long-running worker looks stale

Symptom:

• fear that the task died because it has been quiet for a while.

What the code says:

• Kanban now extends stale claims for live PIDs instead of instantly reclaiming them, specifically to avoid reclaim loops on slow tool-free model calls.

Practical read:

• a long quiet run is not automatically dead, but Brian should still inspect run history / logs / tail output before assuming it is healthy.

Worker crashes or repeatedly fails

Symptom:

• task returns to ready, then eventually lands in blocked / gave_up.

What the code says:

• non-success outcomes increment a failure counter,

• default breaker is 2 consecutive failures,

• protocol-violation crashes can trip immediately.

Practical read:

• if a task fails twice in a row, stop re-clicking and inspect the profile, tools, workspace assumptions, or prompt shape.

Workspace complications too early

Symptom:

• worktree setup or shared-dir assumptions break the first run.

Fast fix:

• first use the default scratch workspace. Save worktree and dir:<path> for after the core loop is proven.

Fastest path vs durable path

Fastest path:

• one cloned worker profile,

• default board,

• one directly assigned task,

• gateway running,

• dashboard open.

This proves Kanban works with the least cognitive overhead.

Durable path:

• 2-4 intentionally named profiles,

• reviewer lane for code-changing work,

• orchestrator only after direct assignment works,

• comments and structured handoff summaries as the normal protocol,

• dashboard + tail/runs/show as regular operating tools.

Brian should prefer the fastest path first, because Kanban's biggest early failure mode is not missing features — it is operator ambiguity about who is supposed to pick up the card. Once the assignee→profile→dispatcher chain is real, the rest becomes much easier.

Sources

• Hermes docs: Kanban overview.

• Hermes docs: Kanban tutorial.

• Hermes docs: Kanban worker lanes.

• Hermes docs: CLI Commands Reference (hermes kanban, hermes profile).

• Hermes code: hermes_cli/kanban.py dispatcher guidance and defaults.

• Hermes code: hermes_cli/kanban_db.py claim TTL, crash handling, and worker env wiring.

• Hermes code: tools/kanban_tools.py tool gating and worker heartbeat behavior.