Planning an app with Hermes Agent Kanban: a practical workflow from idea to release

Hermes Agent’s current Kanban feature is best understood as a durable work queue for multiple Hermes profiles. It is not just a visual checklist. It stores tasks in SQLite, keeps comments and run history, tracks dependencies, and lets the dispatcher start the right profile when a task becomes ready. That matters when a project is too large for one long chat thread.

This article uses a concrete example: building “HabitLoop”, a mobile habit tracking app. The same pattern works for a web app, an internal tool, or a release pipeline, but an app makes the workflow easy to see because product, design, backend, mobile, QA, and release work all have to meet somewhere.

What problem Kanban solves

Hermes already has delegate_task, and for short subtasks it is still the simpler tool. The official Kanban documentation draws a clear line: delegate_task behaves like an RPC call where the parent waits for the child; Kanban behaves like a durable message queue and state machine. Each handoff is a row that a human or another profile can inspect later.

That difference shows up quickly in app development. A real app does not move in a straight line from “write code” to “done”. A product profile may write the MVP scope. A designer may define the onboarding and stats screens. A backend profile may build auth and sync APIs. A mobile profile may implement the app shell, local cache, and integration. A reviewer may block the task because the reset token can be reused. A release profile may prepare the store notes and rollback plan.

Without a board, that workflow tends to become a fragile chain of chat summaries. With Kanban, the board itself is the handoff layer. Tasks can run in parallel, wait on parent tasks, get blocked for human input, and retry with the previous run’s reason included in context.

The pieces that matter

The official docs and the GitHub source describe these core concepts:

• Board: an isolated queue. The default board keeps its database at ~/.hermes/kanban.db. Additional boards use ~/.hermes/kanban/boards/<slug>/kanban.db, with their own workspaces and logs.
• Task: a row with title, body, assignee, status, priority, tenant, workspace, result, and related run data. The documented statuses include triage, todo, ready, running, blocked, done, and archived.
• Link: a parent to child dependency. When all parent tasks are done, the dispatcher can promote the child from todo to ready.
• Comment: the durable discussion thread on a task. Humans and agents can both write comments, and workers see the thread when they start or restart.
• Workspace: where a worker does the work. The docs list scratch, dir:<absolute-path>, and worktree. For coding tasks, worktree helps isolate branches of work.
• Dispatcher: the loop that reclaims stale claims, promotes tasks, claims ready work, and spawns the assigned profiles. By default it runs inside the Hermes gateway, controlled by kanban.dispatch_in_gateway: true and a default tick interval of 60 seconds.

One implementation detail is worth calling out. Workers do not normally shell out to hermes kanban complete. The source file tools/kanban_tools.py registers structured tools such as kanban_show, kanban_complete, kanban_block, kanban_heartbeat, kanban_comment, kanban_create, and kanban_link. These tools are gated. A normal chat session sees no Kanban tools unless it is running as a Kanban worker or has the Kanban toolset enabled. The dispatcher sets environment variables such as HERMES_KANBAN_TASK and pins the worker to the right board.

Step 1: create a board for the app

For a one-off experiment, the default board is enough. For a real app, create a project board so tasks, logs, and workspaces do not mix with other work.

hermes kanban boards create habitloop-app \
  --name "HabitLoop App" \
  --description "Habit tracking mobile app from MVP to release" \
  --switch

hermes kanban init
hermes gateway start
hermes dashboard

The dashboard exposes the Kanban tab with task columns, task drawers, comments, event history, retry history, and recovery actions. The CLI, slash command, dashboard, and worker tools all write through the same database layer, so the state is shared rather than copied.

Step 2: turn the app into a task graph

A common mistake is to create one giant task called “Build HabitLoop”. Kanban works better when the task graph mirrors the actual project. Start with product and design, then gate engineering and QA on those outputs.

PM=$(hermes kanban create "Define HabitLoop MVP scope" \
  --assignee pm \
  --workspace scratch \
  --body "Write target users, MVP features, non-goals, acceptance criteria, and release milestones." \
  --json | jq -r .task.id)

DESIGN=$(hermes kanban create "Design HabitLoop onboarding and core screens" \
  --assignee designer \
  --workspace scratch \
  --body "Produce IA, screen list, empty states, and copy notes for onboarding, daily check-in, stats, settings." \
  --json | jq -r .task.id)

BACKEND=$(hermes kanban create "Implement HabitLoop sync API and auth" \
  --assignee backend-dev \
  --workspace worktree \
  --body "Design database tables, auth/session flow, habit CRUD, check-in sync API, and tests." \
  --json | jq -r .task.id)

MOBILE=$(hermes kanban create "Build HabitLoop mobile MVP" \
  --assignee mobile-dev \
  --workspace worktree \
  --body "Implement onboarding, habit list, daily check-in, local cache, stats, and API integration." \
  --json | jq -r .task.id)

QA=$(hermes kanban create "QA HabitLoop MVP against acceptance criteria" \
  --assignee reviewer \
  --workspace worktree \
  --body "Read PM, design, backend, and mobile handoffs. Run tests, check core flows, list release blockers." \
  --json | jq -r .task.id)

Then link the dependencies:

hermes kanban link $PM $DESIGN
hermes kanban link $PM $BACKEND
hermes kanban link $DESIGN $MOBILE
hermes kanban link $BACKEND $MOBILE
hermes kanban link $MOBILE $QA

This graph lets product and design feed the build instead of becoming background text lost in a chat transcript. The mobile task does not have to start before the API and screen plan exist. QA does not start until the app task has a handoff.

Step 3: let profiles work through the board

Each assignee is a Hermes profile. That profile can have its own model, memory, tools, and permissions. The official docs say Kanban workers should use the bundled kanban-worker skill, and the dispatcher also passes --skills kanban-worker when spawning workers.

A worker’s normal lifecycle is:

• Call kanban_show() to read the task, parent handoffs, comments, prior attempts, and formatted worker context.
• Work inside $HERMES_KANBAN_WORKSPACE.
• Call kanban_heartbeat(note="...") during long runs.
• Finish with kanban_complete(summary="...", metadata={...}).
• Call kanban_block(reason="...") if it needs a decision, credential, missing file, or review direction.

For engineering tasks, the handoff should include evidence. A backend profile might complete with metadata like this:

{
  "changed_files": ["api/auth.py", "api/habits.py", "tests/test_habits.py"],
  "verification": ["pytest tests/test_habits.py -q"],
  "residual_risk": ["rate limit policy not finalized"]
}

That is much more useful than “done”. A reviewer can see what changed, what was tested, and what risk remains.

Step 4: use block and unblock as the review loop

The practical value of Kanban shows up when something fails. Suppose the reviewer finds that offline check-ins can duplicate records and that a password reset token can be reused. The reviewer should block the task rather than burying the feedback in a final message.

# Worker tool call, shown as intent rather than a CLI command
kanban_block(reason="Offline check-in sync can duplicate records; reset token is reusable within 30 minutes.")

A human can then comment and unblock from the dashboard, CLI, or a gateway slash command:

hermes kanban comment $MOBILE "Fix by adding client-side idempotency key and server-side de-dup on check_in_id."
hermes kanban unblock $MOBILE

The next dispatcher tick moves the task back to ready and starts a new run for the same assignee. The tutorial documentation notes that the new worker context includes the previous block reason, so the retry can focus on the actual problem instead of rediscovering it.

Step 5: monitor the project without babysitting it

Most day-to-day monitoring can happen with a short set of commands:

hermes kanban list
hermes kanban stats
hermes kanban watch --kinds completed,blocked,gave_up,timed_out
hermes kanban tail <task_id>
hermes kanban runs <task_id>
hermes kanban log <task_id>

The docs also describe gateway notifications for task completion and failure events. That fits app development well: builds, reviews, and release checks often take long enough that you do not want to sit in a terminal watching them.

When not to use it

Kanban has real machinery: a database, dispatcher, profiles, workspaces, comments, runs, and recovery logic. Do not use it for every tiny question. If the job is a quick answer or a short isolated edit, normal chat or delegate_task is lighter.

Use Kanban when the work crosses roles, spans multiple sessions, needs human review, may fail and retry, or needs an audit trail. For an app like HabitLoop, that usually starts as soon as the work moves from “try an idea” to “plan, build, review, and release.”

Sources

• Hermes Agent official docs: Kanban (Multi-Agent Board)
• Hermes Agent official docs: Kanban tutorial
• GitHub source: hermes_cli/kanban.py
• GitHub source: hermes_cli/kanban_db.py
• GitHub source: tools/kanban_tools.py