wokitoki

WokiToki (toki)

WokiToki は、AI が会話の途中で呼び出す、ローカルで動作するブロッキング型のフィードバック CLI です。ダークテーマの Web UI を表示してブラウザーを開き、ユーザーが回答するまで待機します。送信されると、AI が同じターン内で解析する単一の Result JSON を標準出力に出力します。ブランドのイメージは「トランシーバー」です。やり取りは一問ずつ、一つの回答を返します。コマンドは toki で、すべてのツール出力は ~/.toki/ の下に保存されます。

このスキルはユーザーレベル（グローバル）でインストールされます。すべてのプロジェクトで自動的に読み込まれるため、リポジトリごとの設定は不要です。書き込まれるファイルはすべて ~/.toki/ の下に保存される（現在の作業ディレクトリには保存されない）ため、どのリポジトリ内で toki を実行しても、そのリポジトリには一切痕跡が残りません。.gitignore の編集も不要です。

すべてを一つのエンジンで処理します。仕様はブロックのリストです。controls を持つブロックは質問、controls を持たないブロックはレポートの段落です。一つの仕様で両方を組み合わせれば、ハイブリッドフォームを無料で作成できます。

フェーズ 0 — 初回実行時のバイナリ確認（セッション中の初回呼び出し前）

toki はソースとして提供され、初回使用時に単一のグローバルバイナリへコンパイルされます。初めて呼び出す前にバイナリが存在することを確認し、存在しない場合はビルドしてください。

command -v toki >/dev/null 2>&1 || bun build --compile "<skill-dir>/cli/index.ts" --outfile "$HOME/.bun/bin/toki"

• <skill-dir> はこのスキルのインストールディレクトリです。ユーザーレベルの場合は ~/.claude/skills/wokitoki です。
• Bun のインストールでは ~/.bun/bin がすでに PATH に含まれているため、ビルド直後の toki をすぐに実行できます。
• フォールバック（--compile を使用できない場合、またはバイナリを書き込めない場合）：bun "<skill-dir>/cli/index.ts" <specPath> でソースから実行します。動作は同じですが、初回起動が遅くなります。

初回実行の詳細（サイズ、PATH、再ビルド）→ references/setup.md。

AskUserQuestion とインラインの文章との使い分け

状況	使用するもの
1～2 個の選択肢から選ぶ場合、単一のはい／いいえ、または単純な判断が 3 件以下の場合	AskUserQuestion
複数選択や切り替えを含む判断事項が一度に 3 件を超える場合	WokiToki
ユーザーが一度に一点ずつ反応できるような、複数セクションにわたる長い説明／レポート	WokiToki
返信を、それが対象とする正確な語句に紐づける必要がある場合	WokiToki（ハイライトして引用）
対話型でない場合／CI／ブラウザーを操作する人がいない場合	どちらも使わず、プレーンテキストで出力

代替手段を使わない理由：

• AskUserQuestion は（約 4 件の質問 × 約 4 個の選択肢に）制限され、ターミナルに限定されます。リッチな自由入力には対応しておらず、ユーザーが回答している間に参照内容を表示することもできません。
• インラインの文章形式の質問票では、返信をどこにも紐づけられません。AI は返信の各文がどの段落や項目に対応するかを推測する必要があります。WokiToki は安定した id をキーとしてブロックごとの回答を返すため、対応関係が正確です。

仕様スキーマの概要

{
  "title": "Auth plan — decisions",      // required, non-empty
  "intro": "Optional markdown at top",   // optional
  "submitLabel": "Submit answers",        // optional (default "Submit")
  "blocks": [                              // required, non-empty
    {
      "id": "q1",                          // required, unique within the spec
      "content": "Which token strategy?",  // markdown string (may be empty "")
      "controls": {                        // OMIT for a report paragraph
        "type": "single",                  // single | multi | toggle
        "options": [                        // required for single/multi, FORBIDDEN for toggle
          { "value": "jwt", "label": "JWT stateless" },
          { "value": "session", "label": "Server-side session" }
        ],
        "required": true                    // optional (default false)
      },
      "text": { "required": true, "placeholder": "Justify" }  // text ALWAYS present at runtime; required decided per-block
    }
  ]
}

• controls がない場合はレポートの段落です。ある場合は質問です。リストに両方が混在している場合はハイブリッドです。
• controls.type：single（ラジオボタン）、multi（チェックボックス）、toggle（ブール値の切り替え。options は不要）。
• controls.required と text.required はそれぞれ独立しています。ブロックごとに、どちらか一方、両方、またはどちらも必須にできます。
• id は AI が割り当てる安定したキーで、回答はこのキーに紐づけられます。

仕様の詳細（すべてのフィールド、既定値、検証ルール）→ references/schema.md。そのままコピーして使える仕様の例→ references/examples.md。

正確な実行方法

1. 仕様を JSON ファイルに書き込みます。規則：~/.toki/spec-<name>.json（ファイル名を spec-<name>.json にすると、バックアップは ~/.toki/result-<name>.json に保存されます）。仕様をリポジトリではなく ~/.toki/ の下に置くことで、作業中のリポジトリにファイルが一切追加されないようにできます。
2. 実行します（ブロッキング）： toki <specPath>。UI を提供してブラウザーを開き、待機します。（セッションでの初回実行時は、上記の Phase 0 バイナリチェックを行います。）
   • フラグ：--port <n>（既定値は 4747。使用中の場合は自動的に次のポートを使います）、--timeout <min>（既定値は 1440＝24 時間。小数も可）、--no-open（URL を出力しますが、ブラウザーは開きません）、--help。
3. stdout を解析します。 stdout には Result JSON のみが出力されます — 1 つのオブジェクトで、バナーはありません。進捗状況、待機 URL、エラーはすべて stderr に出力されます。stdout を読み取り、JSON.parse で解析して、同じターンを続行します。

終了コード：

コード	意味
0	送信成功 — Result JSON は stdout にあります
1	タイムアウト（--timeout までに送信されなかった）または実行時エラー — stdout に利用可能なデータはありません
2	不正な仕様（ファイルを読み取れない、または検証に失敗）— [toki] invalid spec at <path>: … を stderr に出力

Result のバックアップも ~/.toki/result-<name>.json に書き込まれますが、AI が参照する正本は stdout のコピーです。

ユーザー不在時のプロトコル

セッションは長時間にわたることが想定されています — 既定の --timeout は 24 時間（1440 分） で、--timeout <min> で変更できます。ユーザーが席を外してセッションを開いたままにすることがあるため、終了コードが 0 以外でも、必ずしもエラーとは限りません。

終了コード	意味	AI の対応
0	送信済み — Result JSON は stdout にあります	解析して、同じターンを続行します
1	送信なしでタイムアウト（または実行時エラー）	失敗ではなく、ユーザーが 離席中 とみなします — 以下を参照してください
2	不正な仕様（読み取り不可／検証に失敗）	仕様を修正して再実行します
130	Ctrl-C（SIGINT）	ユーザーがキャンセルしました — 次に何をしたいか尋ねます

終了コード 1 の場合、エラーにしたり、何も伝えずに先へ進んだりしないでください。ユーザーがキーボードから離れているものとして扱い、簡潔な待機メッセージを表示して、再起動を提案します — 例：「toki を待機状態にしましたが、返答はありませんでした。引き続き対応できます — お知らせいただければ再起動します。」ユーザーが戻ったらすぐに、同じ仕様で toki を再実行できるようにしておきます。

Result の読み取り

{
  "submittedAt": "2026-05-29T12:34:56.000Z",
  "blocks": [
    { "id": "q1", "controlAnswer": "jwt", "text": "Prefer JWT for scale", "quotes": ["token strategy"] }
  ],
  "meta": { "answered": 5, "total": 8 }
}

ResultBlock ごとに、ブロックのコントロールタイプに応じて controlAnswer をデコードします。

• single → string（選択されたオプションの value）、または未回答の場合は null。
• multi → string[]（選択されたオプションの value の配列。選択がない場合は []）。
• toggle → boolean。
• レポートブロック／コントロールなし → null。

その他のフィールド：

• text — そのブロックに対するユーザーの自由記述（未編集の場合は空文字列 ""）。
• quotes — ユーザーがそのブロックの content から強調表示した正確な語句の string[]。返信でどの語句が強調されているかを正確に示すため、text の解釈時に考慮します。
• images — ユーザーがそのブロック（またはテーブル行）に画像を 1 枚以上貼り付けた場合にのみ存在します。各項目は、AI が Read できる ~/.toki/ 配下の絶対ファイルパスです — インラインの base64 ではありません。
• meta.answered — 何らかの回答があるブロック数（コントロールの選択および／または空でないテキスト）。meta.total — ブロック数。

blocks[].id を仕様で割り当てた id に対応付け、すべての回答を判断事項／段落に結び付けます。

注記

• UI の表示部分は英語です（リポジトリアーティファクトの規則）。ブロックの content は、作成時に指定した言語になります。
• CLI は依存関係を切り離し（Bun の組み込み機能のみを使用し、外部依存はゼロ）、単独のグローバルバイナリとして配布されます — cli/README.md を参照してください。