koko

Koko 開発

joelclaw と同じ BEAM 上で動作するエージェントである、Koko の Elixir プロジェクトで作業するときにこのスキルを使用します。

使用する場面

• Koko で新しい GenServer、スーパーバイザー、イベントハンドラーを構築する
• ワークロード（ヘルスパルス、イベントダイジェスト、シャドウ実行器）を実装する
• Koko を新しい Redis チャネルや joelclaw のイベントに接続する
• OTP の監督ツリーやプロセスのクラッシュをデバッグする
• Koko のシャドウ結果を TypeScript の同等機能と比較する

トリガー：koko、elixir agent、beam、otp、shadow executor、koko workload、koko event、mix

プロジェクトの場所

• リポジトリ：~/Code/joelhooks/koko（github.com/joelhooks/koko）
• ホスト：Overlook（Mac Mini M4 Pro）。ssh joel@panda でアクセスできます
• AGENTS.md：詳細なコンテキストはリポジトリのルートにあります

ADR の確認

実装前に、必ず関連する ADR を確認してください。 Koko のアーキテクチャは ADR に基づいています。

ADR	タイトル	ステータス	URL
0114	Elixir/BEAM/Jido の移行	提案済み	joelclaw.com/adrs/0114-elixir-beam-jido-migration
0115	Koko プロジェクト憲章	提案済み	joelclaw.com/adrs/0115-koko-project-charter
0116	Redis ブリッジプロトコル	提案済み	joelclaw.com/adrs/0116-koko-redis-bridge-protocol
0117	最初のワークロード	提案済み	joelclaw.com/adrs/0117-koko-first-workloads
0118	シャドウ実行器	提案済み	joelclaw.com/adrs/0118-koko-shadow-executor

新しいワークロードを追加する前に：ワークロード計画については ADR-0117 を、シャドウ実行パターンについては ADR-0118 を確認してください。

Redis 連携を変更する前に：ブリッジプロトコルとフェーズの境界について、ADR-0116 を確認してください。

アーキテクチャを変更する前に：~/Vault/docs/decisions/ に ADR を提案するか、既存の ADR を更新してください。

主な制約

1. Koko は読み取り専用です（フェーズ 1）。 PubSub のオブザーバーのみです。LPUSH の読み取りは行わず、権威ある書き込みも行いません。
2. 結果はシャドウのみです。 Redis の joelclaw:koko:shadow:<function> またはローカルファイルに書き込みます。Typesense、Todoist、ゲートウェイ、本番環境の状態には書き込みません。
3. Koko がクラッシュしても、何も壊れません。 TypeScript スタックは Koko に依存していません。
4. Redis は localhost:6379 — Overlook 上の k8s NodePort です。

開発コマンド

# Run
cd ~/Code/joelhooks/koko
mix deps.get
mix run --no-halt

# Test
mix test

# Interactive
iex -S mix
Koko.events_seen()

# Format
mix format

# Remote (from another machine)
ssh joel@panda "cd ~/Code/joelhooks/koko && mix run --no-halt"

従うべき OTP パターン

• 関心事ごとに GenServer を 1 つ配置する — ヘルスチェッカー、イベントアキュムレーター、シャドウランナーは、それぞれ別のプロセスにします
• スーパーバイザーの戦略：プロセスが連携していない限り one_for_one を使用します（連携している場合は rest_for_one）
• handle_info でイベントタイプをパターンマッチする — if/else の連鎖は使用しません
• すべてのログ出力に Logger.info("[koko]") のプレフィックスを使用する
• 早期にクラッシュさせる — リカバリーはスーパーバイザーに任せ、失敗を防御的に処理するコードは書きません

実装フェーズ

フェーズ 1：パッシブオブザーバー（現在）

• PubSub 経由で joelclaw:gateway:events を購読する ✅
• イベントをログに記録して分類する ✅
• 次の作業：ヘルスパルス GenServer を追加する（ADR-0117 のワークロード 1）

フェーズ 2：専用チャネル

• 処理対象の作業用に joelclaw:koko:events を作成する
• TypeScript から Koko にファンアウトする：LPUSH joelclaw:koko:events <payload>
• Koko が結果を joelclaw:koko:results に書き込む

フェーズ 3：シャドウ実行器

• 選択した Inngest 関数を Koko の GenServer としてミラーリングする
• 同じ入力で並列実行し、結果を比較する
• シャドウログは joelclaw:koko:shadow:<function>

フェーズ 4：本格移行

• Koko が TypeScript よりも確実にワークロードを処理する
• 手動で介入せずに 30 日間稼働する
• 開発者体験（DX）が快適である