shirusu

shirusu は、複数の AI モデル (Claude / Codex / Gemini / その他) を、**役割・能力・
コスト・リスクに応じて振り分ける** 汎用タスク処理オーケストレーター
(旧称: AI Workbench Orchestrator)。
開発だけでなく、メール文面・情シス業務・ドキュメント整理・意思決定支援・
経理文面・個人事業の事務作業まで、仕事全般に使うことを想定している。

設計思想: AI を直接賢くするのではなく、
AI の使い方・順番・レビュー・ログを賢くする。

特定モデルに依存しない (Fable 5 について)

本ツールの構築時には、高性能モデル **Fable 5 を親オーケストレーター兼リード
アーキテクトとして使用したが、実行時必須依存ではない**。

基本構造

用途別ではなく 処理タイプ (能力単位) でワークフローを分ける。

workflow処理タイプ用途例
think読む・調べる・整理する調査、要約、資料読解、論点整理
make作る・書く・整えるコード、メール文、手順書、チェックリスト
decide比較して判断材料を出すツール選定、A/B 比較、移行判断、費用対効果

エージェントも能力別 (Router / Planner / Researcher / Reader / Summarizer /
Writer / Maker / Comparator / Risk Checker / Reviewer / Critic / Integrator)。
各 step の出力は Reviewer が採点し、不合格なら指示つき再生成 → モデル格上げ →
人間確認、という制御ループを回す (policies/retry.yml)。

クイックスタート

npm からインストールして、自分のプロジェクトで始める (AI 未接続・無料で試せる):

npm install -g shirusu

cd <あなたのプロジェクト>
shirusu init          # tasks/sample.md ほかの雛形と .gitignore 設定を用意

# AI 未接続でも動く (mock runner)
shirusu run tasks/sample.md --mode make --runner mock

# 実行結果の確認 (成果物・判断ログ・レビュー結果が入っている)
ls .shirusu/runs/

実際の AI で流すときは --runner mock を外す (--mode auto で振り分けも自動):

shirusu run tasks/sample.md --mode auto

リポジトリを clone して開発する場合は npm install && npm run build の後、
npx shirusu を同様に使う (run 証跡はリポジトリ直下の runs/ に入る)。

ここまでが基本フロー。ここから先は v0.7 で増えた4つの機能を、続けて
1つずつ試せる (すべて mock runner なので AI 未接続・無料で体験できる)。

# 重要なタスクだけ深く粘らせる (depth。既定は standard、常に deep にすべきではない)
# 勝利条件→生成→破壊レビュー→修正の工程が増え、02-victory.md と
# 05-critique.md に残る (depth の全段階は後述の「深さ」節)
shirusu run tasks/sample.md --mode make --runner mock --depth deep
ls .shirusu/runs/*/02-victory.md .shirusu/runs/*/05-critique.md

# 主要AIが使えなくなった場合の影響を事前に確認する (drill。結果は .shirusu/runs/drills/ に残る)
shirusu drill --without claude

# 作業ディレクトリを実際に変更する (write mode)
# 確認プロンプトが出るので y と答える (--auto は確認を省略するオプションで既定ではない)
# --scope public は「作業ディレクトリの参照を許可する」設定 (write そのものの許可ではない)
# mock runner は決定的に mock-write-artifact.md を1つ作成するので、変更を確実に確認できる
shirusu run tasks/sample.md --mode make --runner mock --write --scope public
cat mock-write-artifact.md   # 書き込まれたことを確認 (デモ用ファイルなので削除してよい)

対話モード (shirusu を引数なしで起動) で /gui を体験する:

shirusu
shirusu › /gui

ローカルGUI (http://127.0.0.1:3777) の Runs タブで直近の run が並んでいることを
確認したら、ターミナルに戻り Ctrl+C で対話モードを終了する。詳細は次の
「対話モード」節。

対話モード

shirusu を引数なしで起動すると対話画面になる。受付係 (Concierge、
lightweight_router ロールの低コストモデル) が毎ターン発言を分類する:

ターミナル上では専用の画面構成になる (依存ゼロ、ANSI スクロールリージョン):

┌────────────────────────────────────────┐
│ 会話・実行ログ (上部スクロール領域)      │
│  ● タスク化 make ワークフローで処理します │
│  ▸ plan  ✔ 完了 (claude/sonnet)         │
├─ ✻ make 実行中 (maker → claude) 12s ───┤ ← 区切り線 + 稼働ステータス (常時更新)
│ shirusu › /gui                           │ ← 下部固定の入力行。ここに打つとGUIも開ける
└────────────────────────────────────────┘

会話ログは .shirusu/runs/sessions/ に、タスク実行ログは .shirusu/runs/ に残る
(ホーム内起動時は runs/)。--auto で実行前確認をスキップできる
(コミット・外部送信・公開など、変更を確定する人間承認境界は変わらない)。

実行ごとに runs/{日付}_{時刻}_{タスク名}/ が作られ、入力・Router 判定・
各 step の出力・プロンプト全文・レビュー結果・final.md・run-summary.json が残る。

runs/2026-07-02_103000_sample/
├─ 00-input.md        # 入力タスク
├─ 01-router.json     # Router 判定
├─ 02-plan.md         # 実行計画
├─ 03-output.md       # 成果物
├─ 04-review.md       # レビュー (スコア・pass/fail)
├─ 05-final.md        # 統合済み最終成果物
├─ final.md           # ↑のコピー (常に同名で参照できる)
├─ run-summary.json   # 実行サマリ (--resume に使用)
└─ prompts/           # 各 step に渡したプロンプト全文

主なコマンド

shirusu [chat] [-c] [--runner <name>] [--auto] [--scope <s>] [--log-level <l>]
shirusu init                       # サンプルタスクと .gitignore 設定を用意 (初回セットアップ)
shirusu run <task.md> [--mode auto|think|make|decide] [--runner <name>]
                    [--write] [--auto] [--depth quick|standard|deep|extreme]
                    [--scope public|restricted|private|local-only]
                    [--log-level full|redacted|metadata|minimal]
                    [--best-of N] [--review-votes N] [--resume <runDir>] [--dry-run]
shirusu serve [--port 3777]        # ローカルGUI (http://127.0.0.1:3777)
shirusu stats [--limit N]          # ロール×モデルの実績集計 (score/リトライ率/所要)
shirusu audit export [--month YYYY-MM]   # 月次監査レポート
shirusu clean [--days N] [--yes]   # 古い run の削除
shirusu list workflows|agents|runners
shirusu validate

深さ (depth)

depth動作
quick軽い処理向け。run では standard と同じ
standard既定のワークフロー
deep勝利条件→生成→破壊レビュー→修正→仕上げ
extremedeep に2案選抜と3票レビューを追加

対話モードのコマンド: `/help /gui /connect /runs /status /knowledge /draft /trace /audit
/scope /mode /feedback /copy /quit`。発言に Backlog の課題URL・課題キー
(HAMONI-1302 等) が含まれると、確認のうえ課題+コメントを取得してナレッジ化する
(/connect backlog で初期設定)。(互換のため ai-orch でも起動できる)

判断ログ (このツールの中核価値)

各 run は成果物と同時に 「なぜそのAIに任せたか」の記録 = KOKUIN (印) を残す
(思想: docs/philosophy.md、形式: docs/shirushi-spec.md)。

もし明日、そのAIが使えなくなったら? shirusu drill --without claude で、
どのロールがどこへ落ち、何を人間が確認すべきかを事前に確認できる。
モデルの解決連鎖と要求能力を表示し、訓練結果は runs/drills/ に残す。
「説明できないAI活用は、仕事では使えない」を停止時の備えからも支える。

scope (データ境界) と log-level

どのAIを重点的に使うか (models.prefer / avoid)

契約プランの事情 (定額のGLMに物量を寄せたい、codexは温存したい等) は
.shirusu/config.yml で decisions ではなく「候補の並び」として表現できる:

models:
  prefer: [glm, claude]   # 候補をこの順に優先
  avoid: [codex]          # 除外ではなく最後尾へ降格 (=温存)

確率的な重みではなく決定的な優先順 (監査可能・再現可能)。並び替えが起きた事実は
decision-log の fallbacks に記録される。

設定は2層: shirusu ホームの config.yml (global、全プロジェクト共通) を土台に、
各プロジェクトの .shirusu/config.yml が上書きする。APIキー類も同様に global の
secrets.local.json に1回置けば全案件で有効。GUI の Environment 画面
(/gui env) で、AIランナーの検出状況・導入コマンド・APIキー・prefer/avoid を
一箇所で管理できる。GLM (GLM Coding Plan) は
GLM_API_KEY を設定すると runner として使える (Anthropic互換エンドポイント経由。
GLM_MODEL / GLM_BASE_URL で調整可。定額プランのためコストは記録しない)。

グローバルインストールと作業ディレクトリ

tarball で配布・インストールする (社内配布)

配布側は npm pack で tarball を作る (prepack が自動ビルドする):

npm pack                      # shirusu-0.7.0.tgz ができる

受け手は Node 20+ があれば tarball 1つで導入できる (依存は tarball に同梱):

npm i -g shirusu-0.7.0.tgz    # グローバルインストール
shirusu                       # どこからでも起動できる

tarball には実行に必要な assets (dist / agents / policies / workflows / gui /
sample task) が同梱される。config.yml は配布物に含まれないため、初回は
GUI の Environment 画面 (shirusu serve → /gui env) または各プロジェクトの
.shirusu/config.yml で設定する (項目未設定時は健全な既定値で動く)。

cd <このリポジトリ>
npm run build
npm link          # どこからでも `shirusu` で起動できるようになる

他の AI CLI と同様、cd した場所が作業対象 になる:

定義ファイル (agents / workflows / policies) は常に shirusu ホームから読む。
SHIRO_HOME 環境変数で別の定義ディレクトリに切り替えられる。

ナレッジスペース (knowledge/)

実行履歴とは別に、ユーザーが蓄積してきたドキュメントを置く場所。
.md / .txt を置くと索引が受付係に渡され、タスク化の際に関連ナレッジが
knowledge: として紐づき、workflow 実行時に全文が各エージェントへ入力される。

場所スコープ
<shirusuホーム>/knowledge/global — どこで起動しても参照
<作業ディレクトリ>/.shirusu/knowledge/project — そのプロジェクト専用

対話モードの /knowledge で一覧表示。詳細は knowledge/README.md。

タスクの書き方

tasks/template.md をコピーして frontmatter (title / mode / domain / risk /
output / 必要なら write: true) と本文 (依頼・背景・制約・人間が判断すること) を書く。
tasks/sample.md が実例。

安全設計 (要点)

詳細: docs/safety.md

GUI (shirusu serve)

shirusu serve で http://127.0.0.1:3777 にローカルGUIが起動する (外部公開されない)。
対話モードでは「GUIを開いて」のように依頼するか、/gui [target] を入力すると、
必要に応じてローカルGUIを起動して対象画面を開ける。自動でブラウザを開かない場合は
shirusu chat --no-open を使う。
Dashboard / New task (自然言語→タスク化→実行) / Runs / Run detail (final・判断ログ・
承認ドキュメントの閲覧) / Knowledge / Settings (.shirusu/config.yml) / Connectors (設計のみ)。
GUI は CLI コアの上に乗る補助UIで、タスク実行は内部で CLI を子プロセス起動する。
トークン類は .shirusu/secrets.local.json に分離され、画面・APIに値は表示されない。

ドキュメント

フィードバック (1.0.0 までは無料です)

shirusu は現在、正式版 (1.0.0) に向けた検証期間中で、すべての機能を無料で
利用できます。1.0.0 以降、業務利用 (法人・チームでの利用) は有料化を予定しています
(価格は検証結果をふまえて決定します)。個人の評価・学習目的の利用は 1.0.0 以降も
無料の方針です。なお、すでに配布済みの 0.x 系バージョンが後から有料になることは
ありません。検証期間中にフィードバックをいただいた方には、有料化後の優遇
(早期割引) を予定しています。

詰まった所、判定の意味が分からなかった所、「これでは業務に使えない」という声を、
フィードバックフォームからそのまま送ってください。開発の優先順位に直接反映します。

なお、会話モードの /feedback や GUI の Run detail からの記録は手元の証跡
(.shirusu/) に残るもので、開発側へ自動送信されることはありません。

MVP に含まれないもの (意図的な除外)

DB / ユーザー管理 / Slack・Gmail の実送信連携 / 無承認の完全自律実行 /
本番環境操作 / 自動コミット / GitHub 自動 push / npm publish / メール自動送信。
「小さく始めて育てる」ため、外部作用を持つ機能は人間の手に残している。

構築プロセスについて

この分担自体が、本ツールが目指す「役割に応じたモデル振り分け」の実例である。