# Queen Poll Kanban

> Use when waiting for hermes kanban tasks Queen dispatched.

- Skill: `jajabong/queen-poll-kanban` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jajabong/queen-poll-kanban`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jajabong/queen-poll-kanban/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jajabong (https://skillmd.com/u/jajabong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jajabong/queen-poll-kanban

---


# Queen Poll Kanban

Queen-mode helper: actively wait for kanban tasks to reach a terminal state, instead of fire-and-forget dispatching and waiting for the user to come back.

## Why

`hermes kanban dispatch` runs the gateway daemon every 60s. A task spawned at T=0 may not be picked up until T=60. If Queen dispatches and returns to user, the user has no idea when the task finishes. Orchestrator mode means Queen polls.

## When to use

- After `hermes kanban create` with `--workspace dir:<path>` or `--workspace worktree`
- When dispatching ≥2 independent tasks (multi-project drill)
- When the user expects Queen to report completion, not just "I dispatched it"

## How

```bash
# Single task
python3 ~/.hermes/scripts/queen_poll.py \
    --task-id t_4211cbca \
    --interval 10 \
    --timeout 600

# Multi-task by board
python3 ~/.hermes/scripts/queen_poll.py \
    --board multi-project-drill \
    --interval 10 \
    --timeout 900

# Match by title substring
python3 ~/.hermes/scripts/queen_poll.py \
    --match "audit" \
    --interval 15 \
    --timeout 300
```

Exit code: `0` when all matched tasks reach `done`/`blocked`/`crashed`; `1` on timeout.

In the main session, run with `terminal(background=true, notify_on_complete=true)` so the process doesn't block the main loop; the result re-enters the conversation when the poll completes.

## What the script does

- Polls `hermes kanban list --json` every `--interval` seconds
- Prints a one-line status change whenever a task moves to a new state
- Exits when all matched tasks are terminal, or `--timeout` is reached
- Filters by `--task-id`, `--match`, or `--board`

## Known issues

- `hermes kanban list --json` output format may include extra preamble text. The script handles JSON-or-text via `json.loads` fallback to `[]`.
- A worker that exits cleanly without calling `kanban_complete` registers as `crashed` (protocol_violation). Queen should treat crashes as work-not-done and either re-dispatch with `--max-retries` or accept partial result.
- `--board` is a TOP-LEVEL flag on `hermes kanban`, not a subcommand flag. Use `hermes kanban --board X list --json`, not `hermes kanban list --board X --json` (the latter errors with "unrecognized arguments").
- `hermes kanban boards` outputs human text, not JSON. The script parses the `SLUG` column. Falls back to `["default"]` if parsing fails.

## Anti-pattern: 口头说"后台跑"不实际起进程

**Bug found in production** (2026-08-10 multi-project drill): Queen said "Queen 现在主动 poll 6 个任务，后台跑，结果出来自动汇报" — but never actually invoked `queen_poll.py`. The gateway daemon had spawned workers and tasks had completed within minutes, but Queen had no polling process running, so the only way the user learned the result was to ask "进展如何". That is fire-and-forget with extra steps.

**Mandatory**: before claiming "后台跑 / 自动汇报 / 完成会通知", Queen MUST have already invoked:

```
terminal(command="python3 ~/.hermes/scripts/queen_poll.py ...", background=true, notify_on_complete=true)
```

and received a `session_id`. Without a live `session_id`, no poll is running and no auto-report will happen. If Queen can't or doesn't run the poll, do not claim auto-report.

## Self-test

```bash
python3 ~/.hermes/scripts/queen_e2e_test.py
```

Verifies SOUL structure (4 subsections + hard rule 7), script exists/executable, queen_poll runs against `--all-boards` and `--board proj-a`, gateway daemon present. Run after every SOUL/script change.

## See also

- `hermes kanban` — 33 subcommands (init/boards/create/swarm/assign/claim/complete/dispatch/daemon)
- SOUL §长程执行 → "Queen 主动 polling 模式 (v29.8)" + "硬规则 防止口嗨后台 (v29.8.1)"
- `~/.hermes/scripts/queen_poll.py` — the script