feat(hermes): manage kanban auto-implementation config in dotfiles - #50
Merged
Conversation
Nix Diffkohei-m4-mac-miniAttribute: Diff OutputSC-N-843Attribute: Diff Output
Generated by nix-diff-action using dix |
Nix Diffkohei-m4-mac-miniAttribute: Diff OutputSC-N-843Attribute: Diff Output
Generated by nix-diff-action using dix |
thinceller
force-pushed
the
feat/hermes-kanban-config
branch
from
August 8, 2026 17:21
04fc6fc to
3dc1090
Compare
Add Planner SOUL.md, worker profile config, and kanban skills to dotfiles so they can be restored on a fresh machine. - hosts/oberon/hermes-documents: SOUL.md / AGENTS.md for context injection - hosts/oberon/hermes-skills: to-kanban / kanban-worker-impl skills - home-manager/files.nix: symlink worker profile and to-kanban script
home-manager/files.nix は macOS 用の home-manager 設定であり、Hermes Agent が 動くのは NixOS ホストの oberon (hosts/oberon 配下、system.activationScripts 経由でデプロイ) だった。そのため worker プロファイルの config.yaml / SOUL.md / to-kanban.py を home.file に置いても oberon には一切反映されず、 実質デッドコードになっていた。 加えて、hermes v0.16.0 は SOUL.md を HERMES_HOME からしか読まず、named profile (`hermes -p worker`) は HERMES_HOME/profiles/worker/ をそのまま 新しい HERMES_HOME として扱う。profile の config.yaml は root の config.yaml とマージされず完全に置き換わるため、直接 YAML を静的配置する だけでは今後 root 側の設定 (model / skills / memory 等) を変更するたびに worker 側の重複ファイルを手で追従させる必要が生じる。 これを解消するため: - home-manager/files.nix に追加された Hermes 関連ブロックを削除し、master 相当に戻す。 - configs/hermes/ 配下のファイルを hosts/oberon/hermes-profiles/ ・ hosts/oberon/hermes-scripts/ へ移動し、Nix module 経由でオーケストレー ションする形に変更する。 - hermes-agent.nix に sharedSettings を導入し、default (planner) と worker の config.yaml を同じ設定から生成する (lib.recursiveUpdate で approvals.mode のみ上書き)。worker は kanban dispatcher から stdin=DEVNULL で spawn されるため、smart/manual だと承認待ちが必ず deny になるので off にする。 - system.activationScripts.hermes-worker-profile で SOUL.md ・ config.yaml ・ plugins symlink を HERMES_HOME/profiles/worker/ 配下へ 配置する (NixOS module 自体にはそのためのオプションがないため)。 - to-kanban.py を呼び出す `to-kanban` ラッパーを extraPackages に追加し、 SKILL.md に store path を埋め込まずに済むようにする。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
oberon の Hermes Planner の SOUL.md は grill-with-docs → to-spec → to-tickets という設計ワークフローの必須工程として mattpocock/skills の skill を参照しているが、これまでは oberon 上に手動インストールされて いるだけで git 管理外だった。手動インストールだと別マシンに復元しても このパイプラインが起動しないため、nvfetcher で pin して skills.external_dirs 経由で読み込ませる。 リポジトリ全体を external_dirs に載せると in-progress や personal 配下 まで system prompt に載ってしまうため、runCommand で使う6つの skill (grill-with-docs, to-spec, to-tickets, domain-modeling, grill-me, grilling) だけを取り出して読み込む。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
kanban_context というツールは存在せず、workspace は各リポジトリの共有 チェックアウトでタスクごとに新しい clone は作られない。この前提とズレた 記述を直さないと、worker が前のタスクのブランチの上に枝分かれしたり、 存在しないツールを呼んで詰まったりする。 - SOUL.md (worker) / SKILL.md (kanban-worker-impl): タスク取得を kanban_show に統一し、ワークスペース準備を「fetch してから base branch を基点に checkout -B」に差し替え、完了後に base branch へ 戻る後片付けステップと force push / direct push 禁止の制約を追加 - SKILL.md (to-kanban): 実際に PATH 提供されている to-kanban コマンドの 挙動 (先に全タスク作成 → hermes kanban link で依存を張る) に説明を 合わせ、存在しない execute_code フォールバックの記述を削除 - SOUL.md (Planner): to-kanban の依存関係付け実態を反映 - 存在しない skill `hermes-kanban-implementation` への参照と、既存の 文字化け (伎う/報呌/レビューー) を修正 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
現行ブランチの AGENTS.md は master 版にあった knowledge-base vault への 記録/参照手順と GitHub リポジトリ作業のガードレール (force push 禁止、 default branch 直 push 禁止など) を移設先なしに削除してしまっていた。 hermes-skills/vault-capture/SKILL.md は今も「AGENTS.md の Inbox capture 手順」を名指しで参照しており、参照が壊れた状態だった。 master 版の全セクションをそのまま復元し、現ブランチで追加された Hermes Agent on oberon セクション (誤字「後わりに」→「末尾に」を修正) の 下に統合した。GitHub 作業の repo allowlist にのみ、kanban の対象リポジトリ になった thinceller/thinceller.net を追加している。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
依存解決を 2 パス方式にした。1 パス目でファイル順に全タスクを作成し、 2 パス目で blocked_by の辺を張ることで、後続チケットへの前方参照 (#2 が #3 に依存する等) があっても num_to_id が揃った状態で 解決できるようにした。旧実装は作成順にしか解決できず、未作成の チケットへの依存を黙って捨てていた。 未解決の依存が残った場合は最後に一覧を stderr に出して exit 1 する ようにした。旧実装は依存が落ちても "Done." と表示して exit 0 に なるため、dispatcher が依存なしタスクとして即座に worker に渡して しまう事故が operator に気づかれなかった。 その他: - 見出し番号のゼロ埋め正規化を parse_ticket 内で統一 (1桁見出しでも blocked_by とキー空間が一致するように) - 見出し区切りに en dash / コロンを追加 - kanban create に --skill kanban-worker-impl を渡し、worker への skill 強制ロードを有効化 - 呼ばれていなかった run_hermes を削除し、link_tasks を実際に使用 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
kanban board は kanban.db というランタイム状態そのものであり、NixOS モジュールが管理するファイルではないため、hermes-agent モジュールの 設定オプションとしては表現できない。そのため独立した systemd oneshot unit として追加し、別マシンへ復元した際に手動での board 作成が不要に なるようにする。 `hermes kanban boards create` は同じ slug の board が既に存在すると 非ゼロで終了するため、`|| true` で握りつぶす。これにより起動のたびに 実行されても、初回は board を作成し、以降は何もしない冪等な処理になる。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
to-spec / to-tickets は issue tracker とラベル語彙の設定が無いと /setup-matt-pocock-skills の実行を促すが、この skill は対象リポジトリに 設定ファイルを書き込む性質のものであり、この環境の skills.external_dirs には含めていない。そのため Planner は初回実行時に「設定がない」状態に 落ちてしまう。 skill を実行させる代わりに、確定済みの設定内容(issue tracker は local files、spec の置き場、ドメインドキュメントの場所、triage ラベル語彙)を SOUL.md に直接明記することで、skill を経由せずに前提条件を満たす。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
コードレビューで、依存なしで先に作った直後のタスクが dispatcher に ready のまま 拾われてしまう隙、'#' 無し依存表記で本文中の数字を誤って依存に取り込む不具合、 hermes コマンド失敗時に stderr が握りつぶされ原因不明の生トレースバックになる問題 などが判明した。トポロジカルソートで依存元から順に --parent 付きで作成する方式に 変更し、作成前に全チケットを検証することで、これらの欠陥を構造的に解消する。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
hermes v0.16.0 の kanban boards create は mkdir -p 相当で冪等 (既存 board でも exit 0) なので、|| true は「既存だったケース」ではなく slug 不正や DB/権限エラーだけを握り つぶしていた。unit が SUCCESS を報告しつつ board が無い状態になり得るため削除する。 また board は dispatch 開始前に存在してほしいので after ではなく before に、 --default-workdir も --name と同様に escapeShellArg で扱いを揃える。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
board が systemd unit (hermes-kanban-boards) で宣言的に用意されるようになったため、 SKILL.md の手動作成の案内は誤りになった。削除し、代わりに board の宣言元と Blocked by の '#' 必須ルールを明記する。また AGENTS.md の GitHub 作業規約は hermes/<slug> ブランチのみを想定しているが、kanban worker タスクは worker の SOUL.md とリポジトリの CLAUDE.md/AGENTS.md に従い feat/<task-id>-<slug> を使うため、 矛盾に見えないよう一行補う。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
サブディレクトリ作成のループを install -d の複数引数指定にまとめて 読みやすくし、plugin symlink に upstream (nix/nixosModules.nix) と同じ plugin.yaml 存在チェックを入れて壊れた plugin を早期に検知できるようにする。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
kanban-worker-impl skill (76行) は worker プロファイルの SOUL.md (132行) と ワークフロー・検証コマンド・ブランチ/コミット/PR 規約・制約がほぼ1:1で重複していた。 さらに --skill で強制ロードしたときにしか読まれないため、ダッシュボードや kanban_create で手動作成したタスクには手順が届かない一方、SOUL.md は worker の system prompt に常に入る。SOUL.md を唯一の情報源にして skill を廃止する。 あわせて to-kanban.py の parse_ticket が返す未使用の "path" キーを削除し、 CLAUDE.md の Hermes Implementation Worker セクションから SOUL.md や Verification セクションと重複する記述を削って要点だけに圧縮する。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
upstream の to-tickets skill が出力する「- **Blocked by**: #1」のような 箇条書き記号付き・コロン位置違い・大文字違いの表記を、完全一致の startswith("**Blocked by:**") では認識できず、依存なし扱いのまま 黙って通過していた（再現済み、exit 0）。依存が落ちたチケットは parent 無しで作られ、ready になって順序を無視して dispatch されてしまう。 正規表現で緩く受けるようにし、Blocked by 行が1行も無いチケットは テンプレート違反として TicketError で落とすようにした （黙って依存なし扱いにするより、タスクを1件も作る前に落とす方が安全）。 併せて見出しの # レベルを1〜3個まで許容し、`## 06 — タイトル` が ファイル名フォールバックに落ちてカード名が slug になる問題も直す。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
install -d は最終要素にしか mode/owner を適用しないため、 .hermes/profiles が呼び出しシェルの umask と root 所有で作られていた。 umask 077 環境で nixos-rebuild switch すると profiles が 0700 root:root になり、hermes -p worker が起動できなくなる。install -d の対象ディレクトリ 列の先頭に profiles 自体を追加して防ぐ。 また sharedSettings の skills.external_dirs が worker にもそのまま乗り、 approvals.mode = off の worker が planner 専用の to-kanban (タスク作成) を 含む skill 一式を持ってしまっていた。worker は1つも使わないため空にする。 documents."AGENTS.md" のコメントは、worker の cwd がリポジトリ側に移るため AGENTS.md が worker に届かないという事実と食い違っていたので訂正し、 worker profile に .env が無い理由 (dispatcher が gateway の os.environ を そのまま継承する) をコメントとして明示した。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
worker は approvals.mode = off で無人実行され、承認プロンプトを出しても ユーザーと会話できない。散文の規約が唯一の防御線であるにもかかわらず、 「ユーザーへの承認を求めずに…行わない」という書き方は、承認を得れば 可能であるかのように読める。マージ・force push・作業ツリー破壊・ 本番反映などを列挙し、理由を問わず実行しない絶対禁止事項として書き直した。 併せて、workspace がリポジトリでない場合に自分で clone せず kanban_block する規約を追加した（clone は人間が行う運用のため）。 また「変更するファイルをタスクで明示されているものに限定する」は、 to-tickets がファイルパスを書かない方針のためほぼ常に成立せず、 ファイルを1つ足すだけで block してしまっていたので、完了条件を 満たすための新規ファイル作成を許容する書き方に改めた。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Planner の SOUL.md と to-kanban skill の SKILL.md が、実際には無い `hermes kanban link` による依存解決を説明していたので、実装通り 「依存順にタスクを作成し、--parent で依存を張る」に訂正した。 Planner の to-tickets ワークフローには、Blocked by を必ず #1 形式で 書く制約を明記した。 CLAUDE.md の Hermes Implementation Worker セクションが指す検証コマンドが darwin 向け nix build になっており、oberon (x86_64-linux) には darwin builder が無いため worker が必ず失敗する状態だったので、cloud sessions 向けの nix eval 手順に差し替えた。 workspace の clone を自動化しない方針の代わりに、新しいホストへの 復元手順・対象リポジトリの増やし方をドキュメント化した (docs/reference/hermes-kanban.md)。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
thinceller
force-pushed
the
feat/hermes-kanban-config
branch
from
August 8, 2026 18:44
3dc1090 to
e7123b5
Compare
thinceller
reviewed
Aug 10, 2026
thinceller
marked this pull request as ready for review
August 10, 2026 16:14
worker SOUL.md にプロジェクト別の検証コマンドを直書きすると、対象リポジトリが 増えるたびに dotfiles 側の更新が必要になり、リポジトリ本体の規約と二重管理になる。 検証コマンドとブランチ・コミット規約は各リポジトリの CLAUDE.md / AGENTS.md を 唯一の正とし、worker はそれを読んで従う形に変えた。 - 「プロジェクト別検証コマンド」節を削除 - 検証手順は「リポジトリの CLAUDE.md / AGENTS.md に書かれたコマンドを完全に実行する。 書かれていなければ kanban_block」に変更 - base branch の決め打ち (dotfiles=master / thinceller.net=main) をやめ、 origin/HEAD から取得させる - oberon には言語ランタイムがグローバルに無いという環境固有の事情だけは残し、 flake の devShell を持つリポジトリでは nix develop -c 経由で実行させる - 「ブランチ・コミット・PR の規約」はリポジトリ側に規約が無い場合の既定値と明記 - docs/reference/hermes-kanban.md の「新しい対象リポジトリを増やすとき」を追随 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
SOUL.md は Hermes の identity slot として全ターンに無条件で載るため、 そこに「設計工程は必ずこの順番」「作成できるのはこの4ファイルだけ」と書くと、 その制約が vault へのメモや記事のクリップなど汎用業務にも等しく掛かってしまい、 AGENTS.md が定める Inbox capture などと正面から矛盾していた。 常に効いていてほしいもの (人格・言語とトーン・安全上の一線) は SOUL.md に残し、 常に効いていてほしい設定値 (issue tracker・spec 置き場・triage ラベル・board slug) は /to-spec や /to-tickets が単独で呼ばれても効くよう AGENTS.md に、 設計依頼のときだけ効けばよい工程 (順序・承認ゲート・設計中のファイル制限) は 新設の design-pipeline skill に、それぞれ性質で置き場を分けた。 「Planner」という人格は無くなり、default profile は汎用アシスタントになる。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Slack ゲートウェイは常に default profile で動き、会話からプロファイルを 切り替える機構が無いため、identity slot (SOUL.md) に設計工程の細かい制約を 書くと vault へのメモや記事のクリップなど汎用業務にも等しく掛かってしまう。 この構造上の理由と、性質による置き場の使い分け (SOUL.md / AGENTS.md / skill) を リファレンスに明記し、後から見て経緯が追えるようにする。 「dotfiles で管理しているもの」の表も、Planner という人格が無くなり design-pipeline skill へ移った新しい構成に合わせて更新した。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
設計工程を design-pipeline skill へ移して「Hermes Planner」という人格が 無くなったが、ドキュメントと Nix のコメントに Planner 表記が残っていた。 実態と食い違うので default profile / design-pipeline に置き換える。 - docs/reference/hermes-kanban.md: 冒頭の説明、フロー図のノード名、 「新しい対象リポジトリを増やすとき」の board slug 表の所在 (SOUL.md -> AGENTS.md へ移動済み)、表内の 2 箇所 - hermes-documents/AGENTS.md: プロファイル節の default の説明 - hermes-agent.nix: plannerSkills / external_dirs / approvals.mode / activation script のコメント 4 箇所 Nix の変数名 plannerSkills と derivation 名 matt-pocock-planner-skills は 設計工程用の skill 群という意味で通るのでそのままにした。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
thinceller
approved these changes
Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
Hermes kanban 自動実装ワークフローで作成した設定ファイルを dotfiles 管理下に置き、マシン移行時にも復元できるようにします。
変更内容
hosts/oberon/hermes-documents/SOUL.md: Planner 用人格・ワークフローAGENTS.md: oberon 上の Hermes 全般規約hosts/oberon/hermes-skills/to-kanban/:to-tickets出力から kanban タスクを作成するカスタムスキルkanban-worker-impl/: Worker の実装フローカスタムスキルhome-manager/files.nix~/.hermes/profiles/worker/SOUL.mdへの symlink~/.hermes/profiles/worker/config.yamlへの symlink~/.hermes/scripts/to-kanban.pyへの symlink（executable=true）hosts/oberon/hermes-agent.nixdocumentsにSOUL.mdを追加CLAUDE.mdHermes Implementation Workerセクションを追加（以前の作業分）検証
nix fmt nix build .#nixosConfigurations.oberon.config.system.build.toplevel --no-link両方とも成功しました。
注意
.envや GitHub PAT、SSH 鍵などの秘密情報は引き継ぎ sops-nix により管理されます。~/.hermes/SOUL.mdは NixOS activation でworkingDirectory/SOUL.mdに置き換えられるため、手動で削除するか、或は home.file で symlink することも検討できます。