kanban-worker

Kanban Worker — 落とし穴と例

このスキルが表示されているのは、Hermes Kanban ディスパッチャーが --skills kanban-worker を指定してあなたをワーカーとして起動したためです。このスキルは、ディスパッチされたすべてのワーカーに自動的に読み込まれます。ライフサイクル（6 つのステップ：状況把握 → 作業 → ハートビート → ブロック／完了）も、自動的にシステムプロンプトへ挿入される KANBAN_GUIDANCE ブロックに記載されています。このスキルでは、適切な引き継ぎの形式、再試行の診断、エッジケースについて詳しく説明します。

ワークスペースの扱い

ワークスペースの種類によって、$HERMES_KANBAN_WORKSPACE 内での作業方法が決まります。

種類	内容	作業方法
scratch	新規の一時ディレクトリ。あなた専用です	自由に読み書きできます。タスクがアーカイブされると GC によって削除されます。
dir:<path>	共有の永続ディレクトリ	他の実行も、あなたが書き込んだ内容を読み取ります。長期的に保持される状態として扱ってください。パスは絶対パスであることが保証されています（カーネルが相対パスを拒否します）。
worktree	解決済みパスにある Git worktree	.git が存在しない場合は、まずメインリポジトリから git worktree add <path> ${HERMES_KANBAN_BRANCH:-wt/$HERMES_KANBAN_TASK} を実行し、その後 cd して通常どおり作業します。ここで変更をコミットしてください。

テナントの分離

$HERMES_TENANT が設定されている場合、タスクはテナントの名前空間に属しています。永続メモリを読み書きする際は、テナント間でコンテキストが漏れないよう、メモリエントリーにテナント名を付けてください。

• 良い例：business-a: Acme is our biggest customer
• 悪い例（漏洩します）：Acme is our biggest customer

適切な要約とメタデータの形式

kanban_complete(summary=..., metadata=...) による引き継ぎは、後続のワーカーがあなたの作業内容を把握するためのものです。効果的な形式の例を示します。

コーディングタスク：

kanban_complete(
    summary="shipped rate limiter — token bucket, keys on user_id with IP fallback, 14 tests pass",
    metadata={
        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
        "tests_run": 14,
        "tests_passed": 14,
        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
    },
)

人によるレビューが必要なコーディングタスク（review-required）：

ほとんどのコード変更タスクは、人間のレビュアーが確認するまでは本当の意味で完了とは言えません。完了ではなくブロックし、reason の先頭に review-required: を付けて、ダッシュボードでレビューが必要な行として表示されるようにしてください。kanban_block が受け取るのは人が読める理由のみであるため、構造化メタデータ（変更したファイル、テスト件数、差分／PR の URL）は、先にコメントへ記載してください。コメントは、注釈を永続的に残すためのチャネルです。レビュアーが承認すると hermes kanban unblock <id> を実行します。その際は、追加対応に使えるコメントスレッドとともに、あなたが再起動されます。変更を求める場合は、別のコメントで依頼します。

import json

kanban_comment(
    body="review-required handoff:\n" + json.dumps({
        "changed_files": ["rate_limiter.py", "tests/test_rate_limiter.py"],
        "tests_run": 14,
        "tests_passed": 14,
        "diff_path": "/path/to/worktree",  # or PR url if pushed
        "decisions": ["user_id primary, IP fallback for unauthenticated requests"],
    }, indent=2),
)
kanban_block(
    reason="review-required: rate limiter shipped, 14/14 tests pass — needs eyes on the user_id/IP fallback choice before merging",
)

タスクが本当に終端に達した場合に限り、kanban_complete を使用してください。たとえば、1 行の誤字修正、機能への影響がないドキュメントの変更、成果物そのものがレポートである調査タスクなどです。

調査タスク：

kanban_complete(
    summary="3 competing libraries reviewed; vLLM wins on throughput, SGLang on latency, Tensorrt-LLM on memory efficiency",
    metadata={
        "sources_read": 12,
        "recommendation": "vLLM",
        "benchmarks": {"vllm": 1.0, "sglang": 0.87, "trtllm": 0.72},
    },
)

レビュータスク：

kanban_complete(
    summary="reviewed PR #123; 2 blocking issues found (SQL injection in /search, missing CSRF on /settings)",
    metadata={
        "pr_number": 123,
        "findings": [
            {"severity": "critical", "file": "api/search.py", "line": 42, "issue": "raw SQL concat"},
            {"severity": "high", "file": "api/settings.py", "issue": "missing CSRF middleware"},
        ],
        "approved": False,
    },
)

後続のパーサー（レビュアー、アグリゲーター、スケジューラー）が、説明文を読み直さなくても利用できるように metadata の形式を整えてください。

成果物の納品（artifacts=[...]）

チャート、PDF、スプレッドシート、生成画像、アーカイブなど、人が実際に必要とするファイルをタスクで作成した場合は、その絶対パスを kanban_complete(artifacts=[...]) に渡してください。ゲートウェイの通知機能がそれぞれをネイティブの添付ファイルとしてタスクの登録者にアップロードするため、成果物は、取得しに行かなければならないパスではなく、完了メッセージと一緒にチャットに届きます。

kanban_complete(
    summary="Q3 revenue analysis: 14% QoQ growth, EMEA the laggard. Chart + full PDF attached.",
    artifacts=["/tmp/q3-revenue.png", "/tmp/q3-report.pdf"],
    metadata={"rows_analyzed": 48000, "growth_qoq": 0.14},
)

画像と動画はインラインで埋め込まれます。PDF、docx、csv/xlsx/json/yaml、pptx、zip/tar/gz、音声、htmlはファイルとしてアップロードされます。ルール：

• 絶対パスのみを指定してください。また、完了時にもファイルが存在していなければなりません。すでに削除した一時ファイルを指定しないでください。
• 実際の成果物のみを指定してください。中間ログ、一時ファイル、人がすでに持っている入力ファイルは含めないでください。
• 通知機能が読み取るのは、トップレベルのパラメーター artifacts です。成果物のパスを metadata（例：metadata.codex_lane.artifacts）に入れてアップロードされることを期待しないでください。通知機能が調べるのはトップレベルの artifacts リストのみで、summary／result のテキストもベストエフォートで確認します。メタデータのパスは後続ワーカーの管理用であり、納品用ではありません。
• 文字列をそのまま指定すると要素が1つのリストに自動変換され、既存の metadata.artifacts と重複を除いて統合されます。

この仕組みはカンバン以外でも使えます。どのエージェントのインターフェースでも、応答にファイルの絶対パスを書くだけでファイルを納品でき、Slack／Discord／Telegramなどがネイティブにアップロードします。artifacts パラメーターは、構造化されたカンバン用のエントリーポイントです。

自分が実際に作成したカードの申告

実行中に新しいカンバンタスクを作成した場合（kanban_create を使用）、そのIDを kanban_complete の created_cards に渡してください。カーネルは各IDが存在し、あなたのプロフィールによって作成されたことを検証します。存在しないIDがあると、問題の内容を示すエラーが発生して完了がブロックされ、拒否された試行はタスクのイベントログに永続的に記録されます。正常に実行された kanban_create の戻り値から取得したIDのみを列挙してください。文章からIDを作り出したり、以前の実行のIDを貼り付けたり、別のワーカーが作成したカードを申告したりしてはいけません。

# GOOD — capture return values, then claim them.
c1 = kanban_create(title="remediate SQL injection", assignee="security-worker")
c2 = kanban_create(title="fix CSRF middleware", assignee="web-worker")

kanban_complete(
    summary="Review done; spawned remediations for both findings.",
    metadata={"pr_number": 123, "approved": False},
    created_cards=[c1["task_id"], c2["task_id"]],
)

# BAD — claiming ids you don't have captured return values for.
kanban_complete(
    summary="Created remediation cards t_a1b2c3d4, t_deadbeef",  # hallucinated
    created_cards=["t_a1b2c3d4", "t_deadbeef"],                   # → gate rejects
)

kanban_create の呼び出しが失敗した場合（例外、tool_error）、カードは作成されていません。存在しないIDを含めないでください。作成を再試行するか、IDを省略して、概要に失敗について記載してください。文章スキャンの処理では、自由形式の概要に含まれる、解決できない t_<hex> 参照も検出されます。これらは完了をブロックしませんが、ダッシュボード上のタスクに注意喚起として表示されます。

すぐに回答を得られるブロック理由

悪い例："stuck" — 人が状況を把握できません。

良い例：必要な判断を具体的に示す一文です。詳しい背景はコメントに記載してください。

kanban_comment(
    task_id=os.environ["HERMES_KANBAN_TASK"],
    body="Full context: I have user IPs from Cloudflare headers but some users are behind NATs with thousands of peers. Keying on IP alone causes false positives.",
)
kanban_block(reason="Rate limit key choice: IP (simple, NAT-unsafe) or user_id (requires auth, skips anonymous endpoints)?")

ブロックメッセージは、ダッシュボード／ゲートウェイの通知機能に表示されます。コメントには、人がタスクを開いたときに読む詳しい背景を記載します。

送る価値のあるハートビート

良いハートビートは進捗を伝えます。例："epoch 12/50, loss 0.31"、"scanned 1.2M/2.4M rows"、"uploaded 47/120 videos"。

悪いハートビートの例："still working"、空のメモ、1秒未満の間隔。送信は数分に1回までとし、約2分未満で終わるタスクでは省略してください。

再試行のシナリオ

タスクを開いたときに kanban_show が、クローズ済みの実行を1件以上含む runs: [...] を返した場合は、再試行です。以前の実行の outcome ／ summary ／ error から、何がうまくいかなかったかを確認できます。同じ方法を繰り返さないでください。よくある再試行時の診断情報は次のとおりです。

• outcome: "timed_out" — 前回の試行は max_runtime_seconds に達しました。作業を分割するか、短縮する必要があるかもしれません。
• outcome: "crashed" — OOM またはセグメンテーション違反です。メモリ使用量を減らしてください。
• outcome: "spawn_failed" + error: "..." — 通常はプロファイル設定の問題です（認証情報がない、PATH が不正など）。やみくもに再試行せず、kanban_block を使って人間に問い合わせてください。
• outcome: "reclaimed" + summary: "task archived..." — オペレーターが前回の実行中にタスクをアーカイブしました。そもそも実行すべきではない可能性があるため、ステータスを慎重に確認してください。
• outcome: "blocked" — 前回の試行はブロックされました。ブロック解除のコメントがスレッドに追加されているはずです。

通知のルーティング

~/.hermes/config.yaml に notification_sources を追加すると、ゲートウェイでプロファイルをまたいだ Kanban タスク通知を受け取るように設定できます。

• notification_sources: ['*'] は、すべてのプロファイルからの購読を受け付けます。
• notification_sources: ['default', 'zilor-ppt'] または "default,zilor-ppt" は、指定したプロファイルからの購読に制限します。
• キーを省略すると、デフォルトの動作（プロファイルの分離）が維持されます。

禁止事項

• kanban_create の代わりに delegate_task を呼び出さないでください。delegate_task は自分の実行内で行う短い推論タスク用です。kanban_create は、1回の API ループを超えて継続するエージェント間の引き継ぎに使います。
• 人間に質問するために clarify を呼び出さないでください。あなたはヘッドレスで実行されており、リアルタイムで応答できるユーザーはいません。この呼び出しはタイムアウト（デフォルトで約120秒）し、入力が必要であることを示す情報がないまま、タスクが running 状態で停止します。代わりに kanban_comment（状況の説明）と kanban_block(reason=...)（判断が必要な場合）を使ってください。タスクはボード上でブロック状態になってオペレーターに表示され、オペレーターがコメントで回答してブロックを解除すると、スレッドを引き継いで再起動します。
• タスク本文に指示がない限り、$HERMES_KANBAN_WORKSPACE の外にあるファイルを変更しないでください。
• 自分に割り当てるフォローアップタスクを作成しないでください。適切な専門家に割り当ててください。
• 実際には完了していないタスクを完了扱いにしないでください。代わりにブロックしてください。

注意点

タスクの状態は、ディスパッチ後から起動までの間に変わることがあります。 ディスパッチャーがタスクを取得してからプロセスが実際に起動するまでに、タスクがブロック、再割り当て、またはアーカイブされている可能性があります。必ず最初に kanban_show を実行してください。blocked または archived が返された場合は、実行すべきではないため停止してください。

ワークスペースに古い成果物が残っている場合があります。 特に dir: と worktree のワークスペースには、以前の実行で使われたファイルが残っていることがあります。コメントスレッドを確認してください。通常、再度実行される理由とワークスペースの状態が説明されています。

案内が利用できる場合は、CLI に頼らないでください。 kanban_* ツールはすべてのターミナルバックエンド（Docker、Modal、SSH）で動作します。ターミナルツールから実行する hermes kanban <verb> は、CLI がインストールされていないコンテナ化されたバックエンドでは失敗します。迷った場合は、ツールを使ってください。

CLI の代替手段（スクリプト用）

すべてのツールには、人間のオペレーターやスクリプト向けの CLI 相当コマンドがあります。

• kanban_show ↔ hermes kanban show <id> --json
• kanban_complete ↔ hermes kanban complete <id> --summary "..." --metadata '{...}'
• kanban_block ↔ hermes kanban block <id> "reason"
• kanban_create ↔ hermes kanban create "title" --assignee <profile> [--parent <id>]
• など。

エージェント内からはツールを使ってください。CLI はターミナルを使う人間向けです。