mcpField
S
sign-off-axi

sign-off-axi

github.com/umeranjum17エージェントワークフロー0234 回インストール今日更新
リポジトリ

sign-off-axi について

sign-off-axiは、ユーザーの入力やレビューが必要なエージェント向けのローカル意思決定ボード兼CLIです。質問、証拠、レポート、作業チケットを画面に表示し、ユーザーの回答をイベントとしてエージェントに返します。

主な機能

  1. 01ワンクリック回答の収集
  2. 02質問と返信の追跡
  3. 03証拠とデザインのレビュー
  4. 04チケットによる作業整理
  5. 05待機イベントで回答を返却

活用シーン

  1. 01計画についてユーザーの判断を得る
  2. 02デザインのレビューを依頼
  3. 03確認用の証拠を提示
  4. 04プロジェクトの作業と返信を追跡

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/umeranjum17/sign-off --skill sign-off-axi

インストール後、Claude Code で/sign-off-axiを入力して読み込まれたか確認します。

詳細

sign-off-axi

sign-off-axi は質問を 1 つのローカルページ（127.0.0.1）にまとめ、ユーザーがそれぞれワンクリックで回答できるようにし、後から読み返せるように回答を保存します。 各質問は 1 つの項目です。投稿し、回答を待ち、回答を読み返します。 ボードには 5 つの場所があります。Today（ユーザーの対応が必要なこと、今日確認できたこと、およびあなたの返信）、Decide（回答待ちのすべての質問と、レビューが必要なデザイン。スマートフォンでは「Show more」を選ぶと、件数を変えずに次の行が表示されます）、Evidence（証拠。質問は含みません）、Reports（説明）、Tickets（エピック、チケット、タスクとしての作業）です。 各カードを開くと、それぞれ専用の画面が表示されます。画面には 1 つのアクションバー（回答、またはレポートへの「Agree」「Disagree」「Comment」「Ask」）、1 つの Activity（投稿者、各回答、メモ、コメントと返信、およびそれぞれの進捗状況）、そして開いた元のリスト内を移動するための「Previous」と「Next」があります。ボード自体のバージョンは --version、サイドバーの下部、Today の「More」で確認できます。また、HTTPS または localhost ではアプリとしてインストールできます。「More」を選び、次に「Install app」を選んでください。

ボードファイルを指定しない場合、コマンドはプロジェクト内で npx -y sign-off-axi init が設定した最も近い .sign-off/ ボードを使用します（リポジトリのルートまで検索します）。それがなければ ~/.sign-off/decisions.json を使用します。別のボードを使う場合に限り、コマンドの後にボードファイル名を指定してください。テストや一時的な実行がユーザー自身のボードにアクセスすることがあってはなりません。SIGN_OFF_HOME に一時フォルダーを設定してください。 使い捨てのサーバーを open <board> またはフォアグラウンドの serve <board> で起動した場合は、終了前に npx -y sign-off-axi stop <board> で停止してください（同じボードファイルを指定します）。表示された PID をシェルから強制終了したり、タイムアウトまでサーバーを動作させたままにしたりしないでください。stop は記録されたサーバーがそのボードを提供していることを確認し、他のボードには影響しないようにします。

最新のガイダンスは CLI で確認できます

このファイルに記載されたコマンド、フラグ、出力は信用しないでください。インストール済みのコピーは古くなっている場合があります。最新の情報は CLI で確認してください。

  • npx -y sign-off-axi --help でコマンド、ボード、使用例を確認できます。
  • npx -y sign-off-axi <command> --help で特定のコマンドのフラグを確認できます。

sign-off-axi をグローバルにインストールする必要はありません。npx -y sign-off-axi で実行してください。 sign-off-axi の出力に sign-off-axi で始まる後続コマンドが表示された場合は、代わりに npx -y sign-off-axi ... として実行してください。 通常の sign-off コマンドはモデルを呼び出しません。オプトイン方式のスタンドアロン所有者ディスパッチャーは、登録済みのインストール済み Claude Code セッションを通常の認証情報と、任意で登録されたモデルを使って再開します。

回答をイベントとして受け取る

回答はあなたに届くため、誰かが代わりに気づく必要はありません。

  1. 自分用の filer id を1つ選びます。エージェントのセッション ID、または任意の短い名前（A-Z a-z 0-9 . _ - の文字を1〜128個）を指定します。指定しない場合、投稿時に Claude Code のセッション ID があれば保存されます。カードのアクティビティでは、短い名前は投稿者と回答を受け取った人として表示され、セッション ID のみの場合は Agent と表示されます。
  2. すべての項目を --filer <id> を指定して投稿するか、すべてのコマンドで一度 SIGN_OFF_FILER=<id> をエクスポートします。
  3. 質問、プラン、またはガイド付きレポートを投稿した直後に（エビデンスの投稿は待機しません）、npx -y sign-off-axi wait --filer <id> を実行します（投稿時と同じボードファイルを使います）。まだ受け取っていない項目への回答をすべて返します。待機を開始する前に届いた回答も対象です。その後、ボード上の該当カードに 既読 と表示されます。また、ガイド付きプランまたはレポートへの さらに掘り下げる 操作も返されます（回答方法は、以下のレポートのセクションを参照してください）。返信のたびに、またプランが差し戻された後にも再度実行します。ガイド付きページは、回答が必要なものがないときも待機を続けます。相手が後から回答を変更することもあります。その場合は、replaces（置き換えられる回答。すでにそれに基づいて行動している可能性があります）が付いた新しい回答として届くため、以前の回答に代えて新しい回答に基づいて行動してください。TIMEOUT の場合は再度実行します。NOT_FOUND は、待機中の項目も「さらに掘り下げる」をサポートする項目もないことを意味します。ファイラーに紐付いた待機だけが「さらに掘り下げる」を受け取ります。ボード全体を対象にした回答待機では、キューに残ったままになります。これにはリスナーが実行中である必要があります。休止中のエージェントセッションは起動しません。
  4. 回答、メモ、デザイン変更のメモ、新しいラウンド、またはコメントに基づいて行動したら、相手に知らせます。npx -y sign-off-axi feedback <key> --reply "<実施した内容を1〜2行で>" --link <プルリクエストまたは新しいバージョン> を実行します（または、文言なしで --acted --link <url> を指定します）。カード上で相手が送ったもの（回答、メモ、新しいラウンド、コメント）にはすべて、送信済み、配信済み（あなたの待機または on_answer フックが受信）、既読、返信済み の履歴が表示され、あなたの返信とリンクも記録されます。返信は相手の「今日」に表示されます。読んだものの、まだ行動していない場合は feedback <key> --read を実行します。引き継いだだけの場合は --delivered を指定します。--at <epoch seconds> を指定すると、過去に発生したステップ（再生）を記録できます。カードにすでに表示されているステップはそのまま残るため、安全に2回実行できます。カードを再投稿すると、相手が送った内容は対応済みとしてマークされます。
  5. Claude Code セッションがアイドル状態の間に単独で「さらに掘り下げる」を使うには、作成時にセッションの実際の UUID を登録します。npx -y sign-off-axi owner <board> --filer <id> --host claude --session <actual UUID> --cwd <absolute project folder> を実行します（--model <model id> は任意です）。ホストから提供されたセッション ID を使い、ID をでっち上げたり、別のセッションを登録したりしないでください。ホストから UUID が提供されていない場合は、登録できないと伝えてください。別のローカルプロセスで npx -y sign-off-axi owner <board> --dispatch --timeout 3600 を実行します。プロセスが終了したら再起動してください。そのオーナーのリクエストを wait で同時に受け取らないでください。サポート対象は Claude Code のみで、Firstmate は不要です。起動したら、リクエストと元のドキュメントを確認し、owner <board> --ack <id> で正確な ID を確認したうえで、deeper <board> --id <id> --text "<answer>" を --more なしで一度だけ実行して最終回答を送ります。再試行してもリクエストは保持され、完了した回答に追記されることはありません。owner <board> では、配信済みやオーナー既読とは別に、キューに残った失敗が表示されます。代わりの回答を送らないでください。すでに稼働中のリスナーでは、引き続きストリーミング形式の回答を利用できます。
  6. ブロックできない場合、ボードの所有者はボードと同じ場所にある config.yaml に on_answer: <command> を設定できます。このコマンドは、回答を JSON として標準入力から受け取り、各回答について実行されます。シェルは介さないため、| や > は機能しません。代わりにスクリプトを指定してください。実行可能かどうかは npx -y sign-off-axi doctor で確認できます。

各カードは、スマートフォンで10秒で読める内容にします

ユーザーはスマートフォンでボードを見ることがよくあります。コードを書かない人が10秒で理解できる内容にしてください。

  • タイトル：結果または質問を、短い一文で示します。「パスキーでサインインできるようになりました」「今週、新しいサインイン機能をリリースしますか？」のようにします。ツール名、実行 ID、バージョン表記、ファイルパス、エラーコードは使いません。
  • --about：ユーザーにとって何が変わったのかを、短い1〜2文で説明します。ASD-STE100 Simplified Technical English で記述してください。短い文を使い、能動態にし、一般的な語を選びます。
  • カードに証拠を表示します。スクリーンショットまたは録画（--media）を添えて、確認する結果を --type evidence として投稿してください。ユーザーは「合格」「不合格」「要修正」から選びます。証拠の行には、最初のキャプチャと確認結果（Passed、Failed、Not run）がタイトルの横に表示されます。タップすると行がその場で開き、すべてのキャプチャがスワイプできる帯状の表示に並びます。主張の証拠となるキャプチャを最初に置き、タイトルには結果を書きます。言葉よりも図のほうが伝わる場合は、図またはインタラクティブページを追加してください（下記参照）。
  • カードからダウンロードできるファイルをユーザーに提供します。たとえば、インストール用の Android ビルドなどです。--attach <file> を追加してください（最大5ファイル、種類は問いません。既定では各ファイル1 GBまで。上限は SIGN_OFF_ATTACH_MAX_MB で変更できます）。ユーザーはスマートフォンまたはタブレットで、カードの「ダウンロード」をタップします。ファイルはボードの横にコピーされ、ストリーミングされます。メモリには読み込まれません。カードには --media のキャプチャ、またはファイルだけが必要です。
  • 1枚のカードにつき、質問は1つにし、推奨する回答も示します（下記の質問の基準を参照）。
  • プルリクエストまたはページを --link に設定します。run を含む契約証拠メッセージでは、outcome の行がカードの先頭に表示されます。ユーザーが確認できる結果として記述してください。

各カードをチケットにリンクします

作業がチケットに紐づいていて、その ID がわかる場合は、そのチケットの raise と post のすべてで --ticket <id> を指定してください（--type や --kind の値は問いません。また、メッセージや --from の項目に "ticket" が含まれる場合も同様です）。カードにはチケットの行が表示されます。チケットのタイトルと進捗も表示され、その行を開くと、チケットに紐づくすべてのカードを含めてチケットを開きます。

  • これは任意で、参照情報にすぎません。チケットがわからない場合は省略し、IDを決して作らないでください。チケットがボードにない場合、カードには行が表示されず、従来どおり機能します。
  • チケットは単独で管理できます。npx -y sign-off-axi ticket --id <id> --title "<the work>" --progress <0-100> で作成し、作業の進行に合わせて再度 --progress を設定します。チケットはエピック > チケット > タスクの階層になります。--parent <id> で別の項目の下に配置できます。また、配下に項目があるチケットは、それらの平均進捗として進捗が計算されるため、配下に何もない項目の進捗を変更します。わかる場合は --priority P0-P3 と --project <name> を追加します。作業が待機中なら --hold yes、再開したら --hold no を指定します。ユーザーが作業を依頼した場合は --asked yes を指定します。リリース先には --release <label> を指定します。表示先の状態を設定するには --state queued|"in progress"|"on hold"|done を指定します（進捗と保留の設定より優先されます）。プルリクエストには --pr <url> を指定します（繰り返し指定するか、カンマ区切りで指定してください）。チケットのページには、リリース、状態、リンクされた各プルリクエストが表示されます。--pr を指定すると一覧が置き換わるため、すべて指定してください。値を空にすると、その項目がクリアされます。自分のチケットだけを記述してください。ticket --id <id> でチケットとそのカードを表示し、ticket ですべてのチケットを一覧表示します。

カードの緊急度を示し、プロジェクトにアイコンを設定します

  • カードの緊急度がわかる場合は、raise と post で --priority P0（最も緊急）から P3（最も緊急度が低い）を指定してください（--type や --kind の値は問いません。また、メッセージや --from の項目に "priority" が含まれる場合も同様です）。カードにはチップとして表示され、ボードを緊急度順に並べ替えられます。わからない場合は省略してください。優先度が設定されていないカードにはチップが表示されません。
  • プロジェクト専用のアイコンがある場合は、画像をボードのフォルダーに置き、npx -y sign-off-axi project --name <project> --icon <path from the board's folder> を一度実行してください（.png、.jpg、.webp、.svg のいずれかで、スクリプトを含まず、500 KB 以下）。名前には、カードで使っているプロジェクト名を指定します。アイコンのないプロジェクトには頭文字が表示されます。アイコンを描いたり、勝手に作ったりしないでください。

良い質問をする

これらのルールに違反する質問は sign-off に拒否され、該当するフィールドと修正方法が示されます。現在のフラグは raise --help で確認できます。

  • 新しい Decide の質問には --ask-ref <captain-message-id-or-hold-id>（メッセージまたはフィード内の ask_ref）が必要です。これは、この回答を必要としている captain のメッセージまたは実際の hold を指定します。作り上げた参照ではなく、実際の ID を使ってください。CLI が確認するのは形式であり、別のツールでの存在ではありません。フォローアップはボードではなくバックログに登録してください。プラン、レポート、エビデンス、エンゲージメント記録、投稿済みのカードは、引き続き利用できます。
  • 1つの決定につきカードは1枚です。投稿する前に npx -y sign-off-axi list --full を実行し、未解決のカードを確認してください。同じ決定がすでにある場合は、再度質問しないでください。そのカードの回答を待つか、より適切な質問にするために --merge <its key> を指定してカードを1枚投稿してください。古いカードは、新しいカードのすべての選択肢を提示している必要があり、回答後は非表示になってクローズされます。1つの決定に対してカードを2枚投稿してはいけません。同じ質問を繰り返す投稿（回答が同じ、またはタイトルの単語が80％以上共通するもの）は投稿されず、どのカードの回答を待つべきかが拒否理由に示されます。1枚のカードに回答があると、同じ決定に関するすべての未解決の質問にも、その回答が適用されます。カードには、質問が回答されるまで1つの質問が紐づきます。統合されたカード自体が何かを統合することはなく、回答済みまたは却下済みのカードは統合されません。
  • タイトル：ボタンで回答できる、12語以内の簡潔な質問を1つにし、「?」で終えてください。「Say yes or no:」、「Captain hold:」、「Captain:」のような接頭辞や、タスク名、IDは含めないでください。
  • --why：何についての質問か、なぜ今回答が必要なのかを、1～2行で簡潔に説明してください。
  • ボタンは、テキスト内の選択肢と一致させてください。はい／いいえの質問には Yes と No を使います。選択式の場合は、選択肢ごとに --option を1つ指定し、それぞれのラベルはその文字（A、B、C）で始めてください。テキスト内に A／B／C を記載しながら Yes／No ボタンを使うことはできません。また、質問に Done や Not now のボタンを使うこともできません。
  • --outcome <value>=<text>：各選択肢について、その回答を選んだ場合に次に何が起きるかを1行ずつ指定します。すべての選択肢に指定してください。
  • --recommend で推奨する回答を指定し、--recommend-reason に理由を1行で記載してください。
  • --default：ユーザーが応答しなかった場合にどうするかを指定し、いつ適用するかを --silent-by <ISO UTC time> で指定します。その時点での動作は、ユーザーの leash によって決まります。「When it matters」（デフォルト）では、期限の --silent-by に open board が --default を適用します。「Act, then tell me」では、raise がただちに --recommend を適用し、picked <value> と通知します。「Ask me first」では何も適用されません。この方法で適用された回答は、taken: default または taken: agent として wait に届きます。そのまま進めて、引き続き回答を待ってください。ユーザーはまだ回答を変更できます（変更には replaces が付きます）。ユーザーに代わって自分で選んではいけません。
  • 削除または上書きを伴う、元に戻せない、金銭を使う、パスワードやキーに触れる、またはアクセス権を変更する質問には、--guard destructive|irreversible|money|credential|security を指定してください。leash の設定にかかわらず、こうした質問ではデフォルトの適用も選択も行われません。質問の文面からボードが該当すると判断した場合も保護されますが、該当する場合は必ず guard を指定してください。
  • 誤って投稿したカードは、npx -y sign-off-axi dismiss <key> で非表示にし、restore <key> で戻せます。ユーザーがカードの Discard をタップして理由（Not relevant、Replaced by newer、Done elsewhere）を選ぶと、カードは Archived に移動します。Undo を使えば10秒以内に元に戻せます。その後、wait --filer が理由とともに discarded としてカードを渡します（--events の行は "event":"discarded"）。そのカードが求めていた作業は中止してください。answers にも discarded として表示されます。同じ効果で自分で破棄するには、dismiss <key> --reason not-relevant|replaced|done-elsewhere を使ってください。
  • タスクが終了したら（統合、破棄、または別の方法で回答済みになった場合）、npx -y sign-off-axi dismiss --filer <id> を実行してください。投稿したカードのうち、まだ回答待ちのものはすべて Decide から消えます。レポートは提出から1日後にメインビューから自動的に消えます。画面の Archived で回答を待ち、restore <key> で戻せます。エビデンスは却下されるまで Evidence 画面に残り、同じキーで証拠を変更して再投稿すると、既存のカードが置き換わります。削除されるものはありません。 適切なはい／いいえ形式の質問：
npx -y sign-off-axi raise --ask-ref <captain-message-id-or-hold-id> --title "Ship the new sign-in screen this week?" \
  --why "The screen is ready and the release goes out Friday." \
  --outcome yes="It ships to everyone on Friday." --outcome no="It waits for next week's release." \
  --recommend yes --recommend-reason "Every check passed on 3 phones." \
  --default no --silent-by 2026-10-19T16:00Z

適切な A／B／C の選択肢：

npx -y sign-off-axi raise --ask-ref <captain-message-id-or-hold-id> --title "Which day should the release ship?" \
  --why "Two fixes are still in review." \
  --option a="A: Today" --option b="B: Friday" --option c="C: Next week" \
  --outcome a="It ships now, without the 2 fixes." --outcome b="It ships with both fixes." --outcome c="It waits for the redesign too." \
  --recommend b --recommend-reason "Both fixes land by Thursday." --default b

証拠は立証し、レポートは説明し、計画は承認を求めます

  • Evidence：実際に機能することを示す証拠です。実際の製品の画面または動画を使用します（--type evidence）。Evidence に保存され、依頼ではないため、証拠を質問として投稿しないでください。テキストのみの画像やプレースホルダー画像は拒否されます。
  • Plan：作業を始める前にユーザーの承認を得るために、これから行うことを示します（post --kind plan --from plan.json。形式は post --help とパッケージのドキュメントにあるコントラクトを参照してください）。ユーザーは各セクションを承認または変更し、各決定に回答して、すべてを一度に返します。依頼と同じように返答を待ち、answers --json で内容を読み取ってください（各セクションにつきメモが1つ、各決定につき値が1つです）。
  • Design review：post --kind design（スキーマ 2）は Designs（スマートフォンでは Decide の2つ目のリスト）に投稿し、デザインを振り分ける担当者がレビューします。ユーザーの Decide に直接投稿しないでください。その担当者が promote <key> を実行すると、カードが Decide に移動します。自分で promote を実行しないでください。デザインカードは、閲覧者が Yes または Change で回答する、簡潔な質問を1つだけ含みます。
    • タイトルはその質問にしてください。12語以内で、たとえば「Reports に新しいスマートフォン用の最終画面を追加してよいですか？」のようにします。タスク名、ブランチ名、PR、スライス、エージェントのメッセージ ID、ファイル名は、タイトルにも about にも使わないでください。画面タイトルやキャプションも使えません。投稿すると拒否されます。
    • 変更した状態ごとに画面を1つずつ用意します（最大8つ。同じ状態を3つの幅で表示するのは不可）。各フレームに固有の画像を用意してください。today（現在リリースされているもの）、built または proposed（新しい見た目）、そして異なる場合に限り target（承認済みデザイン）を指定します。他のフレームと同じように見えるフレームは削除してください。フレーム間の差が0.1％未満の場合、投稿すると拒否されます。複数の列を1枚の画像にまとめないでください。ボードがフレームにラベルを付けて整列します。
    • 各フレームで、area（画像内の割合）を使って変更箇所を囲み、1行の caption で説明します。変更が表示される状態を撮影してください。フェードや移動した線など、静止状態では確認できない変更には、スクロールした状態が必要です。
    • accepts には、Yes の回答が承認するフレームを指定します。振り分け担当者の判定は reviewed に指定します。形式は post --help を参照してください。パッケージの fixtures/contract/design.v2 に例があります。
  • Report：詳細な説明です。ユーザーが説明を求めた場合、または概念、デザイン、トレードオフについて理解が必要な場合に限り使用します。マージ、PR の結果、受領通知、判定、ステータスメモは Report ではありません。
  • Report は、ボードが1つのスクロール表示として描画するフィールドの集まりです。テキストカードでも、自分で作成するページでもありません。npx -y sign-off-axi report init .sign-off/reports/<key> --purpose <kind> を実行し、report.json の FILL: 行をすべて置き換えてから、npx -y sign-off-axi post --kind report --from .sign-off/reports/<key>/report.json --filer <id> を実行してください。FILL: のまま残したテキストは拒否されます。
  • すべての Report で、purpose に用途を指定します。report init と投稿処理では、用途のない Report は拒否されます。それより前に投稿した Report には、report kind <key> <kind> --by <your id> を使って一度だけ種類を指定してください。適切な種類を選びます。research（調査と発見：質問、選択肢、情報源）、plan（実装計画：作業をどのように構築するかを順を追って説明）、decision（決定と推奨：1つの選択肢を比較検討）、audit（基準に照らして確認した内容と修正事項）、incident（インシデントと振り返り：何が起きたか、原因、変更内容）、status（作業の進捗状況）、または該当するものがない場合は other です。ボードでは Report の行と見出しに種類と用途を示す1行が表示され、ユーザーは Reports を種類で絞り込めます。
  • Plan も同様ですが、担当者が決定する質問を含みます。report init .sign-off/plans/<key> --plan を実行し、plan.json に記入してから、post --kind plan --from <file> --filer <id> を実行し、その後 wait --filer <id> を実行してください。担当者は Go ahead を押して、推奨したすべての選択肢を承認できます。そのため、自分が実行する内容を推奨し、相手が何も返答しなかった場合にどうなるかを quiet に記載してください。
  • ボードに表示される順序に従い、各項目を閲覧者向けに記述します。これは何か（答えと画像を1つ。棒グラフ、手順、タイル、またはデザイン、アーキテクチャ、Plan の Report に必要な図）、理解した内容（依頼を自分の言葉で言い換え、認識違いがあれば指摘できるようにする）、見つけたこと、推奨事項（Plan）、決めていただくこと（Plan。質問は最大5つで、それぞれに自分の選択と理由を添える）、次のステップ。
    • 最初に答えを示します。画像の見出しは、答えを述べる簡潔な1文にしてください。
    • 各ポイントにつき画像は1つです。数値は details に記載し、タップして開く形にしてください。文中に入れないでください。
    • 行は短くします。text は1行、more はその場で開く補足とし、ポイントの間は改行してください。閲覧者がスクロールしなければ読めない段落は使わないでください。
    • コードを書かない人にも伝わる平易な言葉を使い、ID、ファイルパス、ツール名は含めないでください。
    • 事実が古くなる可能性がある場合は、その事実が有効だった日付を記載します。
  • 調査 Report（比較、選択肢の検討、「X を使うべきか？」という質問）には、説明 Report より厳しい基準が適用されます。自分で集めた数値だけを根拠にした少数の選択肢は却下されます。
    • まず必須条件を示します。実際に存在する選択肢を幅広く調査してから、必須条件に基づいて候補を絞り込みます。各選択肢を除外した理由を1行で示します。
    • 候補に残したすべての選択肢を、同じ軸で比較し、長所と短所をすべて示してください。比較可能な1つの表にまとめ、各選択肢につき found の項目を1つ用意します。長所と短所は text に、各軸は more に「軸：値。」の形式で、軸ごとに改行して記載します。軸と順序はすべて同じにしてください。ボードではこのセクションを1つの表として描画します。古いボードでは同じ行がテキストとして表示されます。
    • 主張ごとに、外部の根拠とリンクを示してください。対象は GitHub の Issue（未解決のバグ、リグレッション、アップグレードによる破損、メンテナーの回答内容）、Reddit、Hacker News、X、フォーラム、ブログです。サイトから情報を取得できない場合は、読めなかった内容を明記してください。ベンダーの宣伝、スター数、自チームの作業ログの数値は根拠になりません。
    • 自分で確認した内容と、他者の主張を分けてください。セクションを分けるか、各行の先頭に「確認：」または「報告：」を付けます。
    • 最後に、明確な推奨事項を1つと次点を1つ挙げ、それぞれの理由を示します。
  • Plan では、その中のすべての選択肢に対して同じ調査基準を満たしたうえで、承認に必要な内容を示します。選択肢とその長所・短所、推奨事項、範囲（対象に含めることと含めないこと）、順序に沿った手順、リスクとその対処方法、完了を証明する方法を記載してください（understood に Done when、証拠の保存先を next に記載します）。
  • 新しいガイド付きの既定値は Plan スキーマ 3 と Report スキーマ 5（コントラクト 1）で、必須の filer を指定します。古いスキーマも読み込めます。Plan では各項目に、Report では表示中の項目のバーに、Ask a question、Go deeper、Simplify this、Show an example、Why? に加え、自由記述とフォローアップが用意されています。ユーザーが質問すると、セクションの入力欄にフォーカスが移り、テキストの入力と Send が必要です。それ以外のプリセットはすぐに送信されます。質問とカスタム入力には空でないテキストが必要です（最大500コードポイント）。自由記述とフォローアップにはカスタム入力を使います。該当するセクションで、指定された操作と質問に正確に答えてください。説明する、詳しく述べる、簡単な言葉にする、例を示す、理由を説明する、のいずれかを行います。すべて同じエンゲージメント経路を使います。バージョン1では、操作、変更不可の所有者、ドキュメントのリビジョン、対象を引き継ぎ、選択範囲を任意で含めます（作成者が記述したフィールド、コードポイントでの開始位置と終了位置、正確な引用文）。選択範囲がある場合は、ドキュメント内の引用箇所に即して回答してください。これらのフィールドは deeper --json --all で読み取ります。元のドキュメントを参照して依頼された操作に回答し、テキストを書き換えたり Plan の決定を変更したりしないでください。対応中の返信には --filer <your id> が必要です。登録済みのセッションでは、まず正確な ID を確認応答します。古くなった対象や別の所有者からの依頼は拒否されます。回答はその場で開き、目に見える形で読まれるまで再読み込み後も New のままです。Report と送信済み Plan の後も、またすべての返信の後も、所有者のディスパッチャー／リスナーを稼働させたままにしてください。
  • ボードには、各項目を誰がいつ読んだかと、各項目で利用できるプリセットが表示されます。担当者がプリセットをタップすると、wait --filer <id> は依頼を返します（操作、項目、質問があればその質問を含む）。または npx -y sign-off-axi deeper <board> --filer <id> を実行して、未対応の依頼を一覧表示できます。稼働中のリスナーは平易な言葉で、数行ずつ回答します。各部分について npx -y sign-off-axi deeper <board> --filer <id> --id <id> --text "<what you found>" --more を実行し、最後に --more を付けずに1回実行して回答を完了してください。登録済みの休止中の所有者は、上記の方法で確認応答し、最終回答を1つ送ります。ボードは各部分を、担当者がタップした位置に表示します。担当者が項目に対して Agree、Disagree、Comment を送ると、その項目とテキストを含むイベントとして同じ wait に届きます。同じ deeper --id <id> --text で回答し、担当者の指摘が正しければページを修正してください。長い説明文で回答しないでください。短く伝えれば、担当者は追加の質問をできます。
  • ボードを幅390 pxで開き、担当者に見せる前に確認してください。最初の画面に答えと画像の両方が表示されている必要があります。
  • デザインの成果物（モデルが作成した画面、モック、選択肢）についての Report には、貼り付けた画像ではなく、必ずギャラリーを用意します。report init <folder> --purpose <kind> --gallery を実行し、各選択肢のスクリーンショットをボードファイルのフォルダー内に保存します（幅390のスマートフォン用フレームと幅1280のデスクトップ用フレーム。ライトモード用のコピーは不要です）。最初のセクションのギャラリーに、選択肢ごとの label、作成した model、実行日時 ran（UTC）、各フレームの device（phone または desktop）、src、表示内容を説明する caption を記入します。caption または device がないフレームは投稿時に拒否されます。ボードでは選択肢がスワイプできる帯（デスクトップでは横並び）として描画され、両方のフレームが並んで表示されます。タップすると全画面で開きます。
  • Report の各項目はボード独自のブロックで表示し、HTML や CSS を自分で使わないでください。セクションに blocks を追加すると、次を使用できます。callout（独立して表示するメモ、警告、質問）、beats（時刻、タイトル、言葉を付けた画像で構成するステッパー）、video（ポスター画像付き動画）、table、compare（変更前と変更後）、evidence 行（ステータスは fixed、progress、waiting）。ファイルはボードファイルの隣に置いてください。投稿時に固定されます。最初の段落が about の内容と重複していると、投稿時に警告が表示されます。そこで新しい情報を伝えてください。
  • Report は、自作ページではなくボードのキット（次の章を参照）を使って作成してください。ページを使えるのは、どのブロックでも表示できず、閲覧者がタップする必要のあるデモに限ります（report init <folder> --page --purpose <kind> を参照）。

ボードのキットでレポートを作成する

ボードには、単語、ファイル、行を渡します。ボードは独自の書体と色で、ライトモードでもダークモードでも、全幅でひとつの溝に描画します。レポートにHTML、CSS、色、カードを自分で書いてはいけません。自作のページはボードに合わず、読んでもらいたい計画やレポートは、ほかのものと同じ見た目である必要があります。

  1. npx -y sign-off-axi report init .sign-off/reports/<key> --purpose <kind>を実行します（デザイン出力には--galleryを追加します）。その後、すべてのFILL:行を埋めます。表示する内容がないレポートには、ブロックは不要です。
  2. 段落の代わりにブロックで内容を示します。セクションにblocks（1～12個、指定された順）を追加します。画像や動画はそれぞれreport.jsonの隣に保存し、パスで指定します。投稿するとファイルがピン留めされます。
  3. 投稿します：post --kind report --from .sign-off/reports/<key>/report.json --filer <id>。幅390 pxでボードを開き、ライトモードとダークモードの両方で確認してから、表示されたと伝えます。

読者に見せるべきものに合わせてブロックを選びます。

ブロック用途フィールド
callout注意点、警告、質問など、ひとつの内容を目立たせるtone（note、warn、askのいずれか）、title（60）、text（280）
beats読者が順にたどる一連の内容：動画のシーン、フローなどbeats、2～12個。それぞれimage、time、title（80）、text（280）
video短い動画src（.mp4または.webm、50 MB）、poster、length、caption
image評価を添えない、参考用の画像src、caption（280）、任意のalt（280）。画像全体の縦横比は維持されます
fileダウンロードするローカルファイルsrc（5 MB以下の任意のファイル）、caption（280）。メディアと同様にピン留めされ、添付ファイルとしてダウンロードされます
table不規則な表を含む、元データの数値columns（1～20）、rows（最大30）。セルはテキスト（120）または{text, colspan, rowspan}です。空のセルや行ごとに長さの異なる表は、作成時のままにします。幅の広い表や不規則な表は、スマートフォンではブロック内をスクロールできます
compare変更前と変更後beforeとafter。それぞれimageとcaption（80）
evidence状態を添えたキャプチャrows。各行にimage、title、note、status（fixed、progress、waitingのいずれか）
  • 1ブロックにつきアイデアはひとつ、ポイントごとにブロックをひとつ使います。数値を示すなら3段落より表が適しており、画面の手順を示すなら番号付きリストよりステッパーが適しています。
  • 各パートで新しい内容を述べます。セクションの最初の段落がaboutを繰り返している場合、投稿時に警告が表示されますが、投稿は拒否されません。
  • モデルが作成した選択肢は、画像の羅列ではなくギャラリーです。上記のデザイン出力に関するルールを参照してください。galleryとblocksは同じセクションで併用できます。その場合、ギャラリーを先にします。
  • ファイルパスはボードフォルダー内に置き、..、?、#、バックスラッシュを含めないでください。投稿するとファイルの内容がピン留めされます。ファイルを変更した場合、再投稿するまで利用できません。
  • 画像は.png、.jpg、.jpeg、.webpのいずれかで、パスに..、?、#、バックスラッシュを含めてはいけません。
  • すべての見出しとラベルにはセンテンスケースを使い、すべて大文字の表記や色の名前を避けます。フィールド内にマークアップを記述しないでください。
  • 自作のページ（report init --page）は、初回投稿時にボードの見た目に合わせる必要があります。独自の色を3色以上指定したり、カードの中にカードを描画したりするページは投稿が拒否され、ブロックを使うよう案内されます。スキャフォールドはどちらも描画しません。システムカラー（Canvas、CanvasText、GrayText）を使ってください。すでにボードに投稿済みのレポートは、投稿時の状態のままです。

レポートの種類に応じたワークフローに従う

各種類のレポートには、その種類の文書にふさわしい内容が決まった順序であります。各内容を "part": "<id>" として1つのセクションに記述します（最大10セクション）。post は、レポート5にパートの欠落、重複、または種類に合わないパートがある場合、投稿を拒否し、修正箇所を示します。report init <folder> --purpose <kind> を実行すると、記入するすべてのパートが作成されます。ボードは、読み手が各パートを読み進めるにつれて埋まっていくレポートの進捗バーとして、各パートを表示します。

すべての設計、アーキテクチャ、計画レポートに実際の図を描く

計画、および設計やアーキテクチャを説明するレポートには、少なくとも1つ、実際の図が必要です。つまり、アーキテクチャ図（構成要素と、それらが何と通信するか）やフロー（順序に沿った手順と矢印）のように、対象そのものを描いた図です。棒グラフ、タイル、番号付きリストは図ではありません。その他のレポートでは、構造、順序、依存関係が主題の場合に限り図を追加します。数値が主題の場合は、棒グラフやタイルをそのまま使います。

  • 計画またはレポートのファイルと同じ場所にある .html ページに、インラインの <svg> として描きます（手描き、または別途インストールする Archify スキルを使います：npx skills add tt-a1i/archify -g、続けて ARCHIFY_UPDATE_CHECK_DISABLED=1 archify finalize --quality showcase）。図の画像、<img>、ウェブから読み込むページは使わないでください。
  • visual、セクション、または項目に "diagram": [{"label": "Flow", "src": "diagrams/flow.html"}]（タブとして表示されるビューを1～3個）を追加します。その横にある行は、リスト内の同じ回答のままにします。メインの図は visual に配置し、読者が最初に目にする図にします。
  • スマートフォンで読みやすくします。viewBox の幅は320～340、列は最大2列、ラベルは約16文字以内、図中の文字は12 px 以上にし、凡例は付けません。横長のシーケンス図や比較図は収まらないため、同じフローを縦方向に描き、Today と After は2つのビューにします。
  • ライトモードとダークモードの両方で読みやすくします。すべての色をCSS変数にし、ライトモードとダークモードで色を切り替える @media (prefers-color-scheme: dark) ブロックを追加します（明るい背景には濃い文字、暗い背景には明るい文字）。ボードはページにライトモードかダークモードかを伝え、そのルールを有効または無効にするため、図はボードに合わせて切り替わります。黒や白を固定して描かないでください。
  • 最小の文字が幅390 pxのスマートフォンで12 px未満の図、ブランドマークを含む図（brand は設定しないでください）、または <svg> の描画がない図は、Post に拒否されます。Post は各ページを固定します（sha256 と bytes は自動で記録されます）。投稿後にページが変更されると表示されないため、変更後に計画またはレポートを再投稿してください。
  • レポートでは、図をタップすると全画面表示になり（スマートフォンでは図だけが表示されます）、計画では、スマートフォンに列幅いっぱいの図と Full size が表示され、デスクトップでは Show me をクリックするとその場で開きます。投稿済みだと伝える前に、幅390 pxでライトモードとダークモードの両方を開いて確認してください。

ユーザーにサインインを依頼する

作業にユーザーのサインインが必要な場合（たとえば npm login のログインリンクを使う場合）、サインインカードを1つ投稿します。カードは待機項目の先頭に表示されます。

  1. 投稿します：npx -y sign-off-axi post --type signin --key <key> --service "<service>" --link <sign-in URL> --unlocks "<what it unlocks>" --waits "<who waits>" --expires 15m。--expires はリンクの有効期限です。ISO形式の日時、または現在からの時間（例：15m）を指定します。http(s) のリンクだけを投稿し、パスワードやトークンは絶対に投稿しないでください。
  2. サインインが完了したことを確認したら、カードを閉じます：npx -y sign-off-axi signin done --key <key>。wait --key <key> は完了すると戻ります。
  3. リンクの有効期限が切れると、カードにその旨が表示されます。新しいリンクを取得し、同じ --key で再投稿します。カードには新しいリンクが表示され、再び待機状態になります。
  4. リンクの有効期限が短い場合（npm login --auth-type=web のリンクは約5分で期限切れになります）、--link と --expires の代わりに --start '["npm", "login", "--auth-type=web"]' を投稿します。「Open」をタップするたびに、ボードのコンピューター上でそのコマンドが実行され、出力された新しいリンクが開きます。コマンドが終了コード0で終わると、カードは自動的に閉じます。

デザイン上の決定：言葉ではなく A／B／C のモックを見せる

ユーザーに見た目や動作を選んでもらう必要がある場合は、次の手順に従います。

  1. デザインに関する質問を1行で提示します。
  2. 構造（レイアウト、階層、または操作の手がかり）が異なるバリエーションを必ず3つ作成します。色だけが異なるバリエーションは対象外です。
  3. プロジェクト内の .sign-off/mocks/<key>/ に配置します（.sign-off/ がない場合は、npx -y sign-off-axi init を1回実行します）。ファイルを3つ（a.html、b.html、c.html、またはスクリーンショット）用意するか、?variant=a、b、c で指定したバリエーションを表示する index.html を1つ用意します。
  4. 平易な言葉で簡潔なトレードオフ（5行以内：各バリエーションの長所と短所）を書き、1つを推奨します。
  5. 次のコマンドでプロジェクトボードに投稿します。npx -y sign-off-axi post .sign-off/decisions.json --type design --key <key> を実行し、バリエーションごとに --option と --mock を1つずつ指定して、--tradeoff と --recommend も指定します（post --help を参照）。モックのパスは .sign-off/ からの相対パスです。例：--mock a=mocks/<key>/a.html、または1ページ形式の場合は --mock a=mocks/<key>/index.html?variant=a。バリエーションを URL でも実際に動作させる場合は、該当するバリエーションに --link a=<http or https URL> を追加します（バリエーションごとに1つ）。カードにはモックの下に「Open live」リンクが表示され、新しいタブで開きます。その後、npx -y sign-off-axi open .sign-off/decisions.json を実行し、ユーザーに URL を伝えます。
  6. npx -y sign-off-axi wait .sign-off/decisions.json --key <key> を実行して回答を待ちます。
  7. npx -y sign-off-axi answers .sign-off/decisions.json --key <key> --json を実行して回答を読み取ります。選択結果には answer と、場合によってはユーザーが添えたコメントである note が含まれます。"answer": "text" はユーザー自身の回答（「自分の回答として送信」または「返信を送信」）であり、note に格納されています。answer がない rounds の項目、または answer の at より新しい rounds の項目がある場合は、ユーザーがもう一度提案してほしいと考えています。その note を読み、3つの新しいバリエーションを作成して、新しいキーで投稿します。回答またはラウンドに comments のリストがある場合、ユーザーはモック内の箇所にコメントしています。mock はオプション、ref、tag、words は要素を示し、text はコメントです。該当するバリエーションに反映します。
  8. 選ばれた案を実際のコードに反映してから、.sign-off/mocks/<key>/ を削除します。

モックは使い捨ての作業なので、高速で低コストなモデルで作成します。first-draft がインストールされている場合は、モックの作成とともに、--tradeoff の末尾に Open in first-draft: <label> <url> のリンクを書き込めます。ボードでは実際のリンクとして表示されます。

言葉だけでは伝わらないときは、見てわかる形にします

項目を説明するのに必要な、最もシンプルな形式を使います。プレーンテキスト、図、インタラクティブページ、ナレーション付き動画の順に検討してください。

  • 図：.sign-off/mocks/<key>/ に SVG を描画する（または PNG として保存する）し、--type diagram --view mocks/<key>/flow.svg を指定して投稿します。
  • インタラクティブページ：.sign-off/mocks/<key>/ に自己完結型の .html ファイルを 1 つ作成し（CSS と JS はインラインで記述し、ネットワークは使いません）、--type interactive --view mocks/<key>/demo.html を指定して投稿します。サンドボックス内で実行されるため、fetch、リモートファイル、ダッシュボードへのアクセスはできません。
  • ナレーション付き動画（解説動画）：有料またはオンラインの音声サービスは使わず、無料のローカルツールだけを使って、自分で作成します。
    1. ASD-STE100 簡易テクニカル英語で短い台本を書きます。3～5 部構成とし、各部は短い文を 1～2 文、全体で約 20～40 秒にします。
    2. 各部につき静止画を 1 枚（スクリーンショットまたはシンプルなスライド）用意します。すべて同じサイズにします。たとえば 1280x720 の PNG にします。
    3. 無料のローカルエンジンを使って、各部のナレーションを作成します。たとえば piper（pip install piper-tts）または espeak-ng を使います：piper -m <voice>.onnx -f 1.wav < 1.txt
    4. 各静止画にナレーションを付けてから、各部を結合します：ffmpeg -loop 1 -i 1.png -i 1.wav -c:v libx264 -tune stillimage -pix_fmt yuv420p -c:a aac -shortest 1.mp4、続いて ffmpeg -f concat -i parts.txt -c copy -movflags +faststart explainer.mp4 を実行します（parts.txt には file '1.mp4' などを記載します）。
    5. --type explainer --media explainer.mp4 --about "<one-line summary>" と、各部につき 1 つの --chapter <m:ss>=<title> を指定して投稿します（各部の長さは ffprobe -show_entries format=duration で確認できます）。動画はカード上で再生され、チャプターを使うと各部に移動できます。

これらの形式はどれも、意思決定への回答として示します（はい／いいえ、または独自の --options と、推奨する選択肢を示す --recommend）。回答を待ち、同じように内容を確認してください。

リクエスト

$ARGUMENTS

上の行に質問がある場合、ユーザーはその質問を添えてこのスキルを名前で呼び出しています。最新の CLI ガイダンスを取得してから、その質問をしてください。 空欄の場合、またはプレースホルダーしかない場合は、会話の内容から質問を推測してください。

コメント

Markdown 対応