Hermes Kanban の境界 API と worker protocol を外部エージェントに教えるための記事

この記事はなにか

これは 人間向けの CLI 解説記事ではない。

Hermes Agent のタスクボード (Kanban) を、Claude Code / Codex / ローカル LLM bot などの外部エージェントに「正しくしゃべらせる」ための仕様メモとして書いている。読者として想定しているのは、エージェントを Hermes のワーカーとして組み込みたいエンジニア — 具体的には、ブリッジスクリプトを書く人と、エージェントに渡すシステムプロンプトや SKILL.md を書く人。両者が一次資料として横に置ける形を目指している。

シリーズ位置としては、次の記事「サブスク Claude Code を Hermes のワーカーとして動かす工夫」の 前提記事 にあたる。Kanban の「境界 API」としての性質をここで先に固め、次の記事で具体的な運用設計に入る。

結論先出し

エージェントに教えるべき要点は 4 つに整理できる。

Kanban DB を直接書いてはいけない。何の経路で触るにしても、必ず公式 surface 経由で。
誰が何の surface を使うかが分かれている。Hermes 内の worker model は
```
kanban_*
```
tool call、外部 bridge / 人間 / cron は
```
hermes kanban
```
CLI。同じ DB layer に到達するが、入口が違う。
状態モデルとライフサイクルを覚える。エージェントは「自分が今どの状態にあり、何を呼べば次へ進むか」を理解している必要がある。
最小プロトコルだけ覚えさせる。dispatcher 起動型と pull 型 external bridge で前段が違う以外、本体の流れは同じ — 読む → 動く → heartbeat → complete または block。

以下、この 4 点を順に開く。

アクターと surface の整理

Kanban を触る主体は少なくとも 4 種類いて、それぞれ使う surface が違う。

主体	使う surface
人間オペレータ	hermes kanban ... CLI / /kanban ... slash command / dashboard
cron / script / 外部 bridge	hermes kanban ... CLI
Hermes dispatcher-spawned worker (LLM 本体)	kanban_show , kanban_complete , kanban_block , kanban_heartbeat などの tool call
Orchestrator profile	kanban_create , kanban_list , kanban_link , kanban_unblock を含む拡張 toolset

ここを混ぜると事故る。特に注意すべきは:

Hermes 内の worker は CLI を shell out しない。worker model は
```
kanban_*
```
toolset を呼ぶ。CLI と toolset はどちらも同じ kanban_db layer に到達するので、状態遷移・イベントログ・依存タスクの自動昇格などの整合性が保たれる。
外部 bridge (Claude Code, Codex, ローカル LLM bot を Hermes に繋ぐ薄い層) は CLI を使う。これは bridge 自体が「人間相当の外部スクリプト」だから。

つまり本稿で扱う「エージェントに教える」は、正確には 2 つのターゲットがある:

(a) 外部 bridge= CLI を叩くスクリプト + LLM。bridge の責務として
```
list
```
/
```
watch
```
/
```
claim
```
が必要。
(b) Hermes 内 worker LLM=
```
kanban_*
```
tool call で動く。CLI は呼ばない。

両方に共通するのは、Kanban DB を直接書かないこと、状態モデルを理解していること、最小プロトコルを守ること。

なぜ DB を直接書いてはいけないか

CLI でも

kanban_*

tool でも、どちらの surface も同じ kanban_db layer に乗っている。この layer をスキップして SQLite を直接書くと、最低でも次の 3 つが壊れる:

claim の atomicity: 「
```
ready
```
で誰も lock していないタスクだけを、自分の lock 付きで取る」という排他操作を 1 トランザクションで処理する。手書き SQL でこの保証を再現するのは面倒で、書き間違えると 2 つの worker が同じタスクを握る race が起きる。
イベントログの整合性: 状態遷移ごとに events テーブルに行を足すのが規約。surface を通せば自動で書かれるが、生 SQL で
```
tasks.status
```
だけ書き換えるとログが無音になり、
```
tail
```
/
```
watch
```
での進捗追跡が不能になる。
依存タスクの自動昇格: 親タスクが
```
done
```
になったときに子を
```
todo → ready
```
に上げる処理は、surface 経由でしか発火しない。
```
link
```
/
```
unlink
```
で組んだ DAG が機能しなくなる。

要するに、公式 surface (CLI または kanban_* tools) が「セマンティクスを保証する API」 であり、SQLite ファイルそのものは内部実装の都合にすぎない。

1 枚絵

人間 / cron / script / 外部 bridge         Hermes 内 worker model
        │                                          │
        ▼                                          ▼
   hermes kanban ... CLI                  kanban_* tool call
        │                                          │
        └────────────────┬────────────────────────┘
                         ▼
                kanban_db layer
        (atomicity / events / dependency promotion)
                         │
                         ▼
              SQLite (board ごとに分離された DB / workspace / dispatcher scope)

入口は 2 つあるが、整合性を維持する層は 1 つ。これが、Kanban を「ゲートウェイ間の境界に置ける」性質の正体になっている。

ボードは per-board に分離されている

旧来「単一の

kanban.db

にすべてのタスクが入る」とイメージされがちだが、現行では SQLite DB / workspace / dispatcher scope がボード単位で分離されている。default ボードは旧来の場所、追加ボードはそれぞれ独立した領域を持つ。gateway-embedded dispatcher は tick ごとに各ボードを sweep する (ボードごとに別プロセスや別スレッドが立つわけではない)。

bridge / scripting 側で押さえておくべきこと:

スクリプトでは必ず
```
--board <slug>
```
を明示する (
```
switch
```
のグローバル current は別シェル間で事故る)
CLI の board 解決順序は
```
--board
```
→
```
HERMES_KANBAN_BOARD
```
環境変数 → current file → default
ボードをまたいで状態を集計したい場面では、各ボードに対して個別にクエリする必要がある

ボードの切り方の目安:

プロジェクト単位:
```
qi-portal
```
,
```
support-chat
```
ドメイン単位:
```
bidding-cases
```
,
```
hr-tickets
```
ゲートウェイ間の境界:
```
cross-org-decisions
```
,
```
client-handoff
```
一時ワークフロー:
```
2026q2-audit-prep
```

個人ノートを Kanban に書くのは設計ミス。それは Vault と Memory の仕事で、Kanban に書いた瞬間に他ゲートウェイから可視になる。

状態モデル

タスクは次の状態を取る (v0.14.0 時点)。

triage ──specify/decompose──> todo ──deps done──> ready ──claim──> running ──complete──> done
                              ↑                    ↑                  │
                              │                    │                  ├── block ────> blocked ──┐
                              │                    │                  │                          │
                              │                    │                  └── schedule ─> scheduled ─┤
                              │                    │                                              │
                              └────────────────────┴────────── unblock ─────────────────────────┘

ポイント:

本流は

triage → todo → ready → running → done

。

```
blocked
```
と
```
scheduled
```
は本流の中継点ではなく、。
```
ready
```
/
```
running
```
から脇に park される side state
```
unblock
```
は単一コマンドだが、戻り先は 2 系統に分岐する: タスクの依存が解決済みなら、
```
ready
```
に未解決なら戻る (図中の
```
todo
```
に
```
unblock
```
線は両方をまとめて描いている)。
```
archived
```
は表示制御。

各状態の意味を agent 視点で整理する:

状態	agent から見た意味
triage	まだ仕様化されていない。agent が触る対象ではない。 specify または decompose で次状態に上がる。
todo	仕様は決まったが依存未解決。まだ claim できない。
ready	依存解決済み、claim 可能。dispatcher が拾うか、外部 bridge が取りに来る。
running	誰かが claim 中。他 agent は触らない。
done	正常終了。 summary (人間向け handoff) と metadata (機械向け handoff) が次工程の情報源。
blocked	人間 / 他 bot の判断待ち。dispatcher は自動再開しない。
scheduled	時間トリガー待ち。 schedule で park、時刻到来 or unblock で本流に戻る。

エージェントが特に押さえるべきは:

```
ready
```
でなければ claim できない。
```
todo
```
に対して claim を試みても失敗する。
TTL 内に heartbeat / comment / complete / block のどれかを送らないと、最終的に他 worker に取り直される。TTL の値も、heartbeat 不在時の stale 判定の閾値も、いずれも build / config に依存する。外部 bridge は
```
running
```
中の claim には TTL がある。
```
claim --ttl <seconds>
```
で TTL を policy として明示し、それより十分短い間隔で heartbeat を打つ設計にする。
silent return は禁止。worker が
```
complete
```
/
```
block
```
を呼ばずに正常終了した場合、現行実装では
```
protocol_violation
```
扱いになり、
```
auto-block
```
/
```
gave_up
```
でタスクが閉じられる。詰まった場合も進めた場合も、必ず
```
block
```
か
```
complete
```
でタスクを閉じる。

最小プロトコル

エージェントが暗記するのはこれだけ。前段が違う以外は共通。

CLI と toolset の引数の差: CLI コマンドは外部から叩くので
<task_id>
を必ず受け取る。一方、Hermes 内 worker の
kanban_*
toolset はtask-scopedで、worker は自分が動かしているタスクを既知の対象として扱う。原則として task_id を渡さず、body / summary / note 等の中身だけを引数に取る。

共通プロトコル (Hermes 内 worker / 外部 bridge どちらも)

1. 読む

surface	コマンド
CLI (外部 bridge / 人間 / script)	hermes kanban show <task_id> / hermes kanban context <task_id>
toolset (Hermes 内 worker)	kanban_show()

surface

コマンド

CLI (外部 bridge / 人間 / script)

hermes kanban show <task_id>

hermes kanban context <task_id>

toolset (Hermes 内 worker)

kanban_show()

CLI 側で

show

はタスク本体 + コメント + イベント履歴、

context

は「worker がこれから動くために必要な情報の塊」を 外部から確認する ための surface。

Hermes 内 worker では、

kanban_show()

の返り値に task body / comments / parent handoffs / prior attempts / worker_context がまとめて入る。別途 kanban_context() を呼ぶ前提にしない — toolset 側に対応する tool は存在せず、CLI の

context

は外部の人間 / bridge が worker の見え方を覗くための診断用と理解する。

2. 長時間ジョブで heartbeat

surface	コマンド
CLI	hermes kanban heartbeat <task_id> --note "step 2 of 4"
toolset	kanban_heartbeat(note="step 2 of 4")

長い作業では節目ごとに heartbeat を打つ。打たないと、heartbeat 不在の stale 判定を経て他 worker に取り直される (stale 判定の閾値は build / config に依存する。手元 build では

kanban.dispatch_stale_timeout_seconds

に対応する設定が確認できたが、設定名や既定値はバージョン間で変わり得るため、bridge はこれに依存しない設計が望ましい)。

bridge では

claim --ttl 900

のように自分で TTL を明示し、TTL より十分短い間隔 (目安として数分ごと) で heartbeat を打つ policy が安全。公式 docs でも、長時間 operation では

kanban_heartbeat(note="...")

を定期的に打つ worker protocol として説明されている。

3. 観測事実を comment で残す

surface	コマンド
CLI	hermes kanban comment <task_id> --author claude-code-bridge "本文"
toolset	kanban_comment(body="本文")

ここに書くのは 観測事実・検証結果・未解決事項・handoff に必要な情報。chain-of-thought 的な内部思考の逐語ログではなく、次の読者が再現・判断できる事実を書く。CLI の

--author

は呼び出し主体の識別子 (bridge 名など)。toolset 側は profile が自動的に author になる。

4. 正常終了

CLI:

hermes kanban complete <task_id> \
  --summary "Implemented API endpoint and added integration test." \
  --metadata '{"changed_files":["src/api/foo.ts","test/api/foo.test.ts"]}'

toolset:

kanban_complete(summary="...", metadata={...})

。実装の中身ではなく「次に必要な情報」を書く。
```
summary
```
は人間向け handoff
。downstream の自動化スクリプトや子タスクが消費する free-form JSON。
```
metadata
```
は機械向け handoff

5. 詰まったら block

CLI:

hermes kanban block <task_id> "cause: spec undecided
what happened: 仕様書のセクション 3.2 で A 案と B 案が併記されたまま。実装側が判断する根拠が無い。
options: A / B / C
recommendation: A (既存システムとの互換性で優位)
next action needed: human decision on which option to implement"

toolset:

kanban_block(reason="cause: ...")

block

の本文は必ず以下のテンプレに従う:

cause: <human decision needed | test failure | environment | auth missing | spec undecided>
what happened: <事実関係を 1 段落で>
options: <A, B, C — 具体的な選択肢>
recommendation: <どれを推すか、その理由>
next action needed: <解除する側がやるべき具体的アクション>

このテンプレが守られていれば、解除する側 (人間または別 bot) は一度のリードで全情報を受け取れる。「うまくいきませんでした」だけ書かれた block は最悪で、人間が往復で問い詰めることになる。

外部 bridge のみが前段で叩く

Hermes 内 dispatcher が spawn した worker は、起動時に自分のタスク ID が注入された状態 (

HERMES_KANBAN_TASK

環境変数) で動き出すので、自分で claim しに行く必要はない。

一方、外部 bridge は自力でタスクを取りに行く必要がある。

0a. 自分宛のタスクを探す

hermes kanban list --board <slug> --assignee claude-code-bridge --status ready --json
# あるいは stream 監視:
hermes kanban watch --assignee claude-code-bridge --interval 5
# → stdout に JSON Lines 形式で event を吐き続ける。SIGINT で抜ける。

0b. claim

hermes kanban claim <task_id> --ttl 900
# 成功すると workspace path が stdout に返る

TTL は本稿の bridge policy として 900 秒に明示している (build / config の既定値に依存しない)。claim 成功後はそこに

cd

してから、上の共通プロトコル (1〜5) に入る。

破ってはいけないルール

スタイル選好ではなく、破ると state が壊れるか、ボード全体が機能不全になる:

Kanban DB ファイルに生 SQL で UPDATE/INSERT/DELETE しない。公式 surface (CLI または
```
kanban_*
```
tools) 以外で書き込まない。
詰まったときも進めたときも、必ずsilent return は現行実装では
```
block
```
または
```
complete
```
でタスクを閉じる。
```
protocol_violation
```
として
```
auto-block
```
される。
CLI が non-zero exit した時の扱いは、claim 前と claim 後で分ける。
- claim 前(
```
list
```
  /
```
watch
```
  /
```
claim
```
  の失敗): race・一時的な board 状態変化・通信問題で起こり得る。bridge は短い backoff の後、rescan して別タスクを取りに行くか、同じタスクを後で再試行する。block は打たない(claim 前なので block する相手がいない)。
- claim 後(
```
show
```
  /
```
context
```
  /
```
heartbeat
```
  /
```
comment
```
  /
```
complete
```
  などの失敗): 短い再確認の後、解決不能なら
```
block
```
  で人間に渡す。
- した場合は、Kanban 上で状況を伝えられないので、
```
complete
```
  /
```
block
```
  自体が失敗別チャネル (Slack / Discord / メール / ログ aggregator) にアラートを出す。bridge 側でこの fallback channel を持っておく。
認証情報 / 秘密鍵 / 別ゲートウェイの vault 内容を body / comment / metadata に書かない。surface は redact しない。
cron / スクリプトからtransient な失敗で重複タスクが生まれる。決定的な要素から生成するのがコツ — 例:
```
create
```
するときは必ず
```
--idempotency-key
```
を付ける。
```
--idempotency-key "$(echo -n "${board}:${title}:$(date +%Y-%m-%d)" | sha256sum | cut -c1-16)"
```
のように、「ボード + 役割 + 実行日」程度のキーから ID を作る。
claim TTL 内に必ず何か送る (heartbeat / comment / complete / block のどれか)。

実装 worker / 外部 bridge が「触ってはいけない」CLI コマンド

以下は人間オペレータのためのコマンドで、通常の実装 worker や外部 bridge には教えない方がよい (orchestrator profile の役割は別。第 3 節「アクターと surface の整理」を参照):

```
init
```
,
```
boards create/rm/rename
```
— ボードのライフサイクル管理
```
dispatch
```
(手動 tick),
```
daemon
```
— dispatcher 操作 (※
```
daemon
```
は将来 deprecate 予定。移行先は公式 docs を参照)
```
gc
```
,
```
diagnostics
```
— 運用メンテ
```
archive
```
— 完了済みの整理
```
assign
```
,
```
reassign
```
,
```
reclaim
```
— 担当変更 / 救出系

理由はシンプルで、エージェントが状況判断でこれらを叩くと ボード全体の整合性を agent 都合で壊す リスクがある。詰まったら

block

で人間に渡す、というモデルを守らせるほうが結果的に安全に回る。

v0.14.0 で追加された新機能

Hermes v0.14.0 (build 2026.5.16) で以下が追加された:

新ステータス: 時間トリガー待ちの side state (前述の状態モデル参照)。
```
scheduled
```
: タスクを
```
schedule <id>
```
コマンド
```
scheduled
```
に park する。time-delay / follow-up work 用。
: triage column のタスクを子タスク graph に fan out する。
```
decompose
```
コマンド
```
kanban.auto_decompose: true
```
のとき dispatcher tick ごとに自動実行されるオプションもある。

本稿の立場としては、これらは 当面エージェントには教えない:

```
schedule
```
はオペレーション層 (いつ実行するか) の意思決定で、agent が自律判断で park すべき対象ではない。
```
decompose
```
は粒度設計責任を agent に持たせることになる。仕様と運用上の振る舞いが安定するまでは、分解は人間オペレータ or 上位 orchestrator の責務にしておく方が安全。

手元の build では
swarm
というコマンドも観測されているが、現時点の公式 docs では未確認のため本稿のスコープ外とする。

参考: DB スキーマと read-only アクセス (人間向け)

この節は
人間のオペレータ・bridge スクリプトの実装者向け。エージェントには教えない。実装の中を知っておくと「なぜ surface 経由が必須なのか」が腑に落ちるが、エージェントに DB の存在を意識させると surface を迂回する誘惑が生まれる。

テーブル構成

v0.14.0 時点で、各ボードの SQLite には 6 つのテーブルが入っている。

テーブル	用途
tasks	タスク本体 (30 カラム)
task_links	親子依存 ( parent_id , child_id )
task_comments	コメント
task_events	状態遷移イベントログ
task_runs	実行履歴 (1 claim = 1 row)
kanban_notify_subs	通知 subscriber 管理 (v0.14.0 で追加)

tasks

テーブルの主要カラム

論理的にグルーピングするとこうなる:

-- 識別 / 基本属性
id, title, body, assignee, status, priority

-- ライフサイクル
created_by, created_at, started_at, completed_at

-- workspace
workspace_kind (scratch | worktree | dir), workspace_path

-- claim 状態 (排他制御)
claim_lock, claim_expires, worker_pid, last_heartbeat_at

-- namespace と冪等性
tenant, idempotency_key

-- 結果と handoff
result

-- 再試行制御 (circuit breaker)
consecutive_failures, last_failure_error, max_retries, max_runtime_seconds

-- run 紐付け
current_run_id  -- → task_runs.id

-- workflow (forward-compat)
workflow_template_id, current_step_key

-- skill 自動ロード
skills           -- JSON 配列

-- v0.14.0 で追加 ↓
session_id       -- bot session との紐付け (どのチャットから作られたか)
branch_name      -- git branch 別作業 (worktree 系の追跡性改善)
model_override   -- per-task で使う LLM を切り替え可能

status

カラムが取り得る値は

triage | todo | scheduled | ready | running | blocked | done | archived

の 8 種。前述の状態モデルと一対一に対応している。

tenant
(マルチテナント運用),
workflow_template_id
/
current_step_key
(workflow テンプレート系) は本稿のスコープ外。実運用での使い分けは別記事で扱う予定。

task_runs

テーブルの主要カラム

tasks

1 行に対して、claim されるたびに

task_runs

に 1 行が積まれる (再 claim や TTL 切れの reclaim も含めて履歴が残る)。

カラム	用途
id	run の識別子 ( tasks.current_run_id から参照される)
task_id	どのタスクの run か
started_at , ended_at	run の開始 / 終了時刻
worker_pid , worker_profile	この run を回した worker の識別
outcome	終了種別 (下記の enum を参照)
error	エラーメッセージ (失敗時)

outcome

で観測される代表的な値:

値	意味
completed	正常に complete した
failed	実行中にエラーで終了
reclaimed	TTL 切れで他 worker に取り直された
timed_out	max_runtime_seconds を超過
gave_up	worker が complete / block を呼ばずに終了 (= protocol_violation)。前述の auto-block の原因

(完全な enum は手元の

task_runs

の制約定義を参照。バージョンで増減し得るので、コード側で switch するなら未知値を

unknown

でフォールバックする方が安全。)

kanban_notify_subs

(v0.14.0 新規)

カラム	用途
task_id	通知対象のタスク
platform	通知先 ( discord , teams など)
chat_id , thread_id , user_id	通知先の identifier
notifier_profile	通知を行う Hermes profile
created_at	subscribe した時刻
last_event_id	最後に通知済みの event id (重複通知防止)

「特定タスクの進捗を Discord / Teams 等に通知する subscriber」を管理する。人間が「このタスクが終わったら教えて」を設定する用途。

ボードごとに DB は別、スキーマは同一

各ボードは独立した SQLite ファイルを持つが、スキーマは全ボードで同一。

.schema

の出力を比較しても diff は出ない。

読み取り専用で覗くショートカット

bridge スクリプトの分析用途では、CLI の

--json

出力で足りないケースに限って、読み取り専用で SQL を直接当てるのは OK。書き込みは禁止 (後述)。

# 対話で開くときは -readonly フラグ
sqlite3 -readonly <board-db-path>

# 1 行クエリは URI mode で read-only を強制
# running task の生存確認 (heartbeat が古い worker を炙り出す)
sqlite3 "file:<board-db-path>?mode=ro" \
  "SELECT id, title, assignee, last_heartbeat_at
   FROM tasks WHERE status='running';"

# 直近の失敗履歴
sqlite3 "file:<board-db-path>?mode=ro" \
  "SELECT task_id, outcome, error FROM task_runs
   WHERE outcome NOT IN ('completed', 'reclaimed')
   ORDER BY started_at DESC LIMIT 20;"

なぜ書き込みは禁止か (スキーマで再確認)

スキーマを見ると、たとえば

status

の遷移ひとつとっても、整合性のために連動して更新すべきカラムが多いのが分かる。

```
tasks.status
```
だけ書き換えると
```
task_events
```
に痕跡が残らず、
```
tail
```
/
```
watch
```
/ dashboard の表示と不整合になる
claim を生 SQL で取ろうとすると、
```
claim_lock
```
/
```
claim_expires
```
/
```
started_at
```
/
```
worker_pid
```
/
```
current_run_id
```
を atomic に書く必要があり、かつ
```
task_runs
```
に新 row を足す必要がある (これを 1 トランザクションで書けないと race る)
完了の生 SQL は
```
consecutive_failures
```
のリセットや dependency promotion の発火を逃す

公式 surface (CLI /

kanban_*

tools) はこれら全部を 1 操作の裏側で面倒見ている。読み取りオンリーの分析用途に限ってだけ、生 SQL を許す、というのが現実的な落とし所になる。

「実装こそ約束」原則の Kanban 版

ここで一段引いて、なぜ Kanban が「お願いだから SQL 書かないで」ではなく 「書いても整合性が壊れる構造」 になっているかを言語化しておく。

エージェントを業務に組み込む時の原則は、「規律を文書ではなく実装で強制する」だ。エージェントは説明書を律儀に読むとは限らないし、システムプロンプトに「SQL を書くな」と書いても、状況によっては書く。だから書けない構造にする:

公式 surface (CLI または
```
kanban_*
```
tools) が atomicity / event logging / dependency promotion を一括で面倒見る
公式 surface を経由しない書き込みは整合性を壊す
→ エージェントは「公式 surface を叩く」以外に選択肢がない

この性質によって、Kanban は ゲートウェイの内側ではなく、ゲートウェイ間の境界に置ける。複数の Hermes プロファイル (たとえば全社用と入札専用) が同じボードを共有しても、それぞれが自分の vault / memory で動きながら、タスクという最小限の単位だけを安全に受け渡せる。

これが次の記事「サブスク Claude Code を Hermes のワーカーとして動かす工夫」の前提になる。Claude Code を Hermes のボードに参加させるとは、Claude Code を境界 API の話者にする ということだ。

まとめ — SKILL.md / システムプロンプトに貼れる cheat sheet

# Hermes Kanban - Agent Protocol Cheat Sheet

- Kanban は durable task board。DB を直接書いてはいけない。
- 人間 / script / 外部 bridge は `hermes kanban` CLI を使う。
- Hermes 内 worker model は `kanban_*` tool call を使う (task-scoped、原則 task_id を渡さない)。
- 両方とも同じ kanban_db layer に到達するので整合性が保たれる。

- 状態モデル: triage → todo → ready → running → done。
  blocked と scheduled は ready/running から脇に park される side state。
- ready でなければ claim できない。
- scheduled / blocked のタスクは通常 worker の領域ではない。
  解除は人間 or orchestrator の責務。

- 最小プロトコル: read → work → heartbeat → complete or block。
  - CLI で読む:     show <task_id> + context <task_id>
  - tools で読む:   kanban_show()    ※ context 相当はこの返り値に含まれる
  - heartbeat:      heartbeat <task_id> / kanban_heartbeat(note="...")
  - comment:        観測事実・検証結果・handoff に必要な事実を書く (内部思考は書かない)
                    comment <task_id> --author ... / kanban_comment(body="...")
  - complete:       summary = 人間向け、metadata = 機械向け
                    complete <task_id> --summary ... --metadata ...
                    kanban_complete(summary="...", metadata={...})
  - block:          cause/what/options/recommendation/next-action テンプレ必須
                    block <task_id> "..." / kanban_block(reason="...")

- 外部 bridge は前段で list/watch → claim が必要。
- Hermes 内 worker は HERMES_KANBAN_TASK が注入されるので自分で claim しない。

- silent return 禁止。必ず complete または block で閉じる。
- CLI non-zero exit は claim 前 / claim 後で扱いを分ける。
  - claim 前 (list/watch/claim): backoff + rescan。block は打たない。
  - claim 後 (show/heartbeat/comment/...): 短く再確認し、解決不能なら block。
  - complete/block 自体が失敗: Kanban 外の fallback channel に alert。
- secrets / vault 内容 / token / raw PII を body/comment/metadata に書かない。
- cron/script から create するときは --idempotency-key 必須。
- board は per-board に分離。script では --board を明示。

次回予告

次の記事では、本稿の仕様を踏まえて サブスクの Claude Code を Hermes Kanban の外部 worker として実際に動かすときの運用設計 を扱う。具体的には:

bridge スクリプトの設計 (list/watch ループ、claim の取り方、TTL の扱い、workspace のマウント)
skill / システムプロンプトに何を書いて何を書かないか
Claude Code に「block を打つ」という習慣を仕込む工夫
サブスク (= 1 ライセンス) の Claude Code を複数タスクに並行で当てるかどうかの判断

を書く予定。

本稿は Hermes Agent
v0.14.0 (build 2026.5.16)時点の挙動に基づく。新コマンド
schedule
/
decompose
および手元 build で観測される
swarm
の詳細仕様 (特に
decompose
の auto-decompose 挙動と orchestrator 経由での使い方) は別記事で改めて整理する予定。

Hermes Agent Kanban CLI の仕様をエージェントに教えるための記事

추출된 키워드

원문