cekura-infra-test-suite

Cekura Voice AI インフラストラクチャ CI/CD スイート

作業を始める前に、skill_name="cekura-infra-test-suite"、verification_tag="ack:cekura-infra-test-suite:2h6r7k"、plugin_version="0.19" を指定して mcp__cekura__cekura_skill_started を呼び出してください。すぐに戻り、Cekura が使用中のスキルを確認できるようになります。ツールを利用できない場合は、そのまま続けてください。

音声エージェントのリポジトリ内に、コンパクトでレビューしやすい Cekura テストスイートを構築してください。成果物は、CI から Cekura の Tests-as-Code エンドポイントに送信する JSON 仕様です。ダッシュボードに永続的な評価器を作成するものではありません。

リポジトリ、そのデプロイ先、Cekura エージェントが対象となる場合は、このスキルを使用してください。単発のダッシュボード評価器や適応型品質シナリオには、代わりに cekura-eval-design を使用してください。

実行方法 — 2 つのコンテキスト、1 つの手順

以下の手順はどちらのコンテキストでも同じです。異なるのは、コードの取得元、すでに把握している情報、結果の保存先です。質問せずに判別してください。リポジトリがすでに作業ディレクトリになっている場合は → ターミナルです。mcp__github__github_checkout_repo を使ってコードを取得する必要がある場合は → Cekura ダッシュボードから起動されています。

	ターミナル	ダッシュボード
リポジトリ	すでに作業ディレクトリになっている	github_checkout_repo で取得
エージェント	設定から推定するか、質問する	起動メッセージに記載
認証情報	実際にない場合があり、質問してもよい	MCP セッションはすでに認証済みです。決して質問しないでください
結果	ユーザーがコミットできる作業ツリー	github_open_pull_request による 1 つのプルリクエスト

やり取りのルール

1 回の実行につき質問は 1 つだけで、最初の応答で次の質問をしてください。

これは手動ディスパッチのみで実行します。Actions タブからブランチを指定して開始し、実際に通話を行います。代わりに検証用の dry run チェックボックスを設けます。トリガーも追加しますか？ push、PR、スケジュール、または cekura-test ラベルを使い、ラベルが付いた各 PR を個別のプレビューとしてデプロイして、このスイートを実行しますか？

references/preview-deploy.md に記載された条件をボットが満たす場合に限り、ラベルを提案してください。起動メッセージにすでにトリガーが指定されている場合は、この質問への回答済みとして扱い、質問しないでください。それ以外の場合は、判明した内容を報告しながら質問し、そのまま作業を続けてください。回答を待たないでください。手順 6 までに回答がなければ、手動ディスパッチを設定し、トリガーの追加方法を引き継ぎ時に伝えてください。これ以外は、作成するファイルや配置場所、作業を進めてよいかなど、何も質問しないでください。例外は、ターミナルで認証情報が不足している場合（手順 7）です。ダッシュボードでは、認証情報について決して質問しないでください。

API アクセス — Cekura MCP サーバー

対象を特定する前に MCP サーバーを認証し、読み取りには MCP を優先してください。Tests-as-Code の検証には、以下の公開 HTTPS エンドポイントを使用します。ベース URL とキーは環境変数または CI シークレットから取得し、ソース管理から取得しないでください。エンドポイントが存在しない場合はその旨を報告し、ダッシュボードの評価器に切り替えないでください。

安全性とスコープ

• カバレッジを提案する前に、リポジトリを調査してください。フレームワーク名だけから、プロバイダー、トランスポート、ツール、パイプラインの動作を推測しないでください。
• Cekura は読み取り専用として扱ってください。エージェント、有効なメトリクス、パーソナリティ、テストプロファイル、スキーマ、エクスポートデータに対して GET を実行できます。書き込みに類するリクエストとして許可されるのは scenarios_validate_json — validation のみです。これは何も作成せず、ダイヤルもしません。scenarios_run_json はクレジットを消費するため、絶対に呼び出さないでください。
• シナリオ、テストプロファイル、パーソナリティ、メトリクス、エージェント、フォルダーの作成、編集、削除、複製、エクスポートして再インポートする操作は絶対に行わないでください。ユーザーが仕様を確認し、コストを了承したうえで別途依頼しない限り、スイートを実環境で実行しないでください。
• API キー、電話番号、本番の顧客データ、デプロイ用シークレットを仕様やコミットするワークフローに含めないでください。CI シークレットと、機密情報を含まないステージング互換のプロファイルデータを使用してください。
• 既存の無関係なリポジトリの変更を保持してください。編集は、以下の 成果物 で確定するファイル一覧に限定されます。2 つ目のワークフローを追加するのではなく、既存の Cekura ワークフローを拡張してください。
• 対象、有効なメトリクス、パーソナリティ、ステージング用フィクスチャが不明な場合は、より弱いチェックに置き換えず、そのケースをブロックとしてマークしてください。
• ある動作のテストに、ファイル一覧の範囲外の変更（ランタイムコード、Dockerfile、デプロイ設定、Cekura レコード、存在しないメトリクス）が必要になる場合は、そこで停止してブロッカーを報告してください。 自分のテストを可能にするために、変更の差分がどれほど小さく、理由がどれほど妥当でも、その変更を加えないでください。テストできない対象と必要な対応を明記し、判断はユーザーに委ねてください。スコープ変更にあたらないものは 2 つあります。このスイートのチェックのみを目的とするガード（ケース数チェック。ケースの追加にあわせて更新します）と、references/preview-deploy.md のプレビューステップです。

「インフラストラクチャテスト」と呼ばれる 2 つの別物

ステップ 0 の前に、この点を確定してください。解釈を誤ると、調査をやり直すことになります。

依頼	内容	対応
「Cekura の事前定義済みインフラストラクチャスイートを追加して」	Cekura が提供する、すぐに使える 18 件以上のレイテンシ／割り込み／ノイズ／パケットロス／保留シナリオ	MCP ツールからは利用できません。 Evaluators → Infrastructure Suite → Add to my Project（または add_infrastructure_suite API）を使用するよう案内してください。これにより AI Interrupting user = 0 のルーブリックルールも追加されることに注意してください。また、CI から選択できるよう、コピーに infrastructure-suite タグを付けてください。コピーを手作業で作成したり、以下の手順を実行したりしないでください。
「自分のボット向けにインフラ／CI テストを作成して」	顧客自身のパイプラインコードに基づくテスト	以下の手順を実行してください。

依頼がどちらにも解釈できる場合は、ステップ 0 の前に 1 度だけ、短い質問をしてください。この確認が必要なのはターミナルの場合のみです。ダッシュボードからの起動ではリポジトリとエージェントが指定されるため、どちらを指すか確定します。

成果物 — 書き始める前に確定する3つのファイル

基本形は、ほとんどのリポジトリで次のとおりです。

cekura.tests.json                    the suite
.github/workflows/cekura-tests.yml   the CI gate (created, or the existing Cekura job extended)
README.md                            a section: what runs, which secrets, which permissions

何も書く前に正確な一覧を決め、最初の回答で提示してください。 3つは基本形であり、上限ではありません。重要なのは、一覧を最初に確定しておくことです。途中で4つ目のファイルが必要だと気づくと、1回の作業が4ラウンドの調整になってしまいます。リポジトリ独自の規約で必要な場合に限り、追加または置き換えを行い、その理由を説明してください。

• CI が GitHub Actions ではない → .gitlab-ci.yml、Jenkinsfile のステージ、Makefile のターゲットなどに置き換えます。追加ではなく、置き換えです。
• ドキュメントが README 以外の場所にある → そのリポジトリで定められた場所にセクションを追加します。
• 独立してデプロイ可能なボットが2つある → 1つの仕様で両方をカバーできない場合は、仕様を2つ作成します。

追加してはいけないもの：カバレッジの注記（README のセクションと PR の本文に記載します）、同梱した lint_suite.py または run_suite.py、このスキルが独自に考案した設定ファイルです。追加ファイルは、顧客がずっと保守し続ける対象を1つ増やします。それを必要とする規約を挙げられないなら、追加すべきではありません。ドライランの前に、一覧全体を一度に作成してください。リンターはこのスキル自体のディレクトリから実行し、ワークフローは Cekura が公開している run-suite アクションを使ってスイートを実行します。

プルリクエストを提出先とする場合は、提案する前に必要な GitHub App の権限を明記してください。必要なのは、読み書き権限を持つ Contents と Pull requests、および .github/workflows/ に書き込むための読み書き権限を持つ Workflows です。最後の権限を App に付与するだけでは不十分です。組織の管理者がインストール上で変更を承認する必要があります。

ワークフロー

0. 新規作成か更新かを判断する

まずこれを実行してください。以降のすべてがここで決まります。

grep -rl 'schemas/test-suite' --include='*.json' .       # definitive: a spec's $schema line
git ls-files | grep -Ei '(cekura|tests?).*\.json$'       # candidates
git ls-files '.github/workflows/*' '.gitlab-ci.yml' 'Jenkinsfile' | xargs grep -ln 'cekura' 2>/dev/null

• 仕様がない → 新規作成します。手順1～8を進めてください。
• 仕様がある → その場で更新します。プルリクエスト規模の更新には、cekura-bot-test-writer スキルを使います。内容をすべて読み、すべての key を保持して、手順5から始めてください。既存のスイートはレビュー済みのソースコードであり、キーを変えない限り結果の比較可能性が保たれます。更新時に最もよくある正しい結果は、変更なしです。 手順5から始めることは、残りの確認を省略することではありません。 作成したものはすべて、手順1b、手順4の期待結果に関する契約、手順7のドライランを経る必要があります。更新は変更規模が小さいだけで、基準が低いわけではありません。判定側の契約ではなく、古いファイルの書式に合わせて作成したテストケースは、より質の低いテストケースです。変更しない既存ケースにリンター警告があっても、ここで修正する必要はありません。
• ワークフローがすでに Cekura を呼び出している → 手順6でそのファイルを拡張し、2つ目のファイルは追加しません。既存のシークレット名とトリガーの規約を再利用してください。

1. 実際のエージェント経路を読み解く

プロバイダー名だけを検索するのではなく、ランタイムのエントリーポイントから呼び出し経路をたどります。ソースコード上の参照箇所とともに、次の項目を一覧にしてください。

• 入出力の方向とトランスポート（電話、WebSocket、WebRTC、SIP、LiveKit、Pipecat など）。
• STT、LLM、TTS、VAD／ターン検出、バッファリング、エンドポイント判定、中断処理の各プロセッサー。
• プロンプト／設定の読み込みとセッションごとの変数。
• ツール、転送／通話終了の動作、DTMF／IVR、ボイスメール、アイドル状態／タイムアウト、再試行、エラー処理。
• 対応言語、および言語／プロバイダーを切り替えるコードパス。
• テスト用フィクスチャ、モック、ステージング環境の依存関係、既存の Cekura JSON ファイルまたはワークフローファイル。

references/discovery.md には質問一覧があります。各レイヤーで確認すべきことと、それぞれの回答によって可能になるアサーションをまとめています。ルールは、すべてのしきい値と、エージェントの発話から引用したすべてのフレーズを file:line 形式で記録することです。出典のある数値があれば、「アイドルタイマーがいずれ発火する」が「8秒後に発火し、Are you still there? と話す」になります。出典のない数値は推測であり、ボットではなくスイートを失敗させる原因になります。

候補となる動作ごとに、実行する側とトランスポートを記録してください。シミュレーション上の発信者とテスト対象のエージェントは、それぞれ異なるコードを実行することがあります。一方の側だけを実行するカバレッジでは、もう一方の側の回帰がカバーされているとは証明できません。

1b. 指標やパーソナリティを選ぶ前に、エージェントの記録を確認する

ディスカバリーには2つの側面があります。リポジトリから分かるのはエージェントの機能であり、**Cekuraから分かるのは、スイートで何を検証できるかです。**キーまたは認証済みセッションを利用できる場合は、作成に着手する前にこれらを確認してください。いずれも読み取り専用で、推測を事実に変えてくれます。

• **対象エージェントで有効になっている指標。**仕様で参照できるのは、そのエージェントにすでに存在し、有効になっている指標だけなので、この一覧がスイートで測定できる範囲の上限になります。数値の指標（レイテンシー、中断など）は expected_outcome と併せて設定してください。これらは、トランスクリプトを読むジャッジでは測れないものを測定します。インフラストラクチャのスイートでは、そこが大部分を占めるポイントです。
• **利用可能なパーソナリティ。**コミット間で結果を比較できるよう、IDで1つを固定してください。また、インラインのパーソナリティにはない設定（ネットワークシミュレーション、発話プラン、メッセージプラン）を備えているかも確認します。それによって、ID参照にするかインラインにするかを判断できます。
• エージェント本体 — プロバイダー、チャネル、インバウンドかアウトバウンドか、連絡先番号、最大実行時間。これにより、ジョブが設定されていないチャネルを理由に実行後に拒否されるのではなく、CIジョブの接続先チャネルを設定前に確認できます。
• 最新の仕様スキーマ。このスキルにある例よりも優先されます。

**エージェントの内容がリポジトリと食い違う場合は、何かを作成する前にそのことを伝えてください。**Pipecat の薬局向け回線を構築するリポジトリが、別のプロバイダーにある単なる「親切なアシスタント」を指していれば、書く価値のあるすべてのケースが失敗します。最初の実行で赤が並べば、間違ったエージェント ID ではなく、スイートが壊れているように見えてしまいます。最初の応答で不一致を明示し、引き継ぎの冒頭で触れ、プルリクエスト本文の先頭にも記載してください。それでも、スイートはリポジトリに基づいて作成します。リポジトリの内容が正しく、エージェント ID が修正された時点で適切なものになるからです。

認証情報がない場合は、その旨を明確に伝えてください。expected_outcome のみを使用し、パーソナリティは固定せず、スイートを未検証として明記します。不足を補うために、指標のスラッグやパーソナリティ ID を決して捏造しないでください。有効でないスラッグはドライランで確実に拒否されます。そこで判明するのは適切ですが、推測した値では往復の手間が無駄になるだけです。

2. 編集前にカバレッジマトリクスを作成する

編集前にカバレッジ表を作成してください。これはファイルではなく、README のセクションとプルリクエスト本文に記載します。そうすれば、レビュー担当者は古くなる文書をリポジトリに残さずに、判断の根拠を確認できます。

コードパス／ソースの根拠	検証する動作	シート＋トランスポート	トランスクリプトで確認できるアサーション	ケースキー	ステータス

スイートで実行して判定できる動作のみを含めてください。たとえば、中断後に期待する発話が続くことは検証しますが、音量タグ、環境音、内部プロセッサー自体が実行されたことは検証しません。別のトランスポート、テストフィクスチャ、指標、またはバックエンド機能が必要な行には uncovered と記し、不足しているものを明示してください。

references/case-catalog.md には、実証済みの9つのケースパターンが記載されています。それぞれ、シーケンスレベルとしきい値レベルでの検証内容、およびテストを無効にする drop-if 条件が示されています。まずここから始め、その後、このリポジトリ固有のバグ履歴から必要性が分かるケースを追加してください。drop-if 条件に該当するケースは移植しないでください。実際のパイプラインをカバーする6件のスイートは、使えないテストが6件含まれる12件のスイートより優れています。

ユーザーが段階別のスイートを求めていない限り、デプロイ可能な10～12ケースのスイートを1つ作ることを優先してください。高速なプルリクエスト用スイートも必要な場合は、コンパクトに（通常は4～6ケース）保ち、広範なスイートがその上位集合になるようにします。互換性のあるターンは1つのケースにまとめてください。別のサブシステム、シート、トランスポート、プロバイダー、または終了時の呼び出しライフサイクルを扱う場合にのみ、ケースを追加します。

3. 仕様の形を選択する

対象環境から返される最新のスキーマを基準にしてください。通常、v1 の仕様は次のようになります。

{
  "$schema": "https://docs.cekura.ai/schemas/test-suite/v1.json",
  "version": "1",
  "suite": { "name": "…", "description": "…" },
  "defaults": { "frequency": 1, "language": "en", "max_duration": 180 },
  "scenarios": []
}

安定した、説明的な key の値を維持してください。再利用可能なデフォルト値は、すべてのケースで実際に共通する場合に限り、スイートレベルに設定してください。defaults フィールドは、個々のケースで上書きできます。条件付きアクションを含む各ケースでは、language を明示的に設定してください。tools は、シミュレートされた呼び出し元が利用できる機能を指定します。 dtmf、receive_dtmf、end_call、end_call_only_on_transfer、send_sms、call_hold

ケースで必要な場合に限り、テストデータを設定してください。

"test_profile": {
  "name": "returning-caller-gold-tier",
  "agent_variables":  { "order_id": "ORD-4471" },
  "caller_variables": { "user_name": "Maria" }
}

agent_variables は、通話時にテスト対象のエージェントへ動的変数として渡されます。そのため、エージェントが同じ名前の変数をすでに読み取っている場合に限り、キーが機能します。どの変数が存在するかは検出によって確認できます。キーを独自に作成すると、エージェントが何も通知せずに無視するプロファイルになります。caller_variables がエージェントに渡されることはありません。これらはシミュレートされた呼び出し元のコンテキストであり、スクリプト化されたステップ内の {{test_profile.key}} の置換元です。

2 つのセクション間でフィールドを移動したり、JSON を自己完結させるためにプロファイルを独自に作成したりしないでください。

例外は 1 つありますが、これは一般的なケースではありません。 ソース内の明示的なテストハーネスモードで、渡された変数からプロンプト、プロバイダー、制限を取得して通話ごとに自身を設定するボットの場合、設定全体を agent_variables で渡します。リポジトリにそのようなモードがある場合は、その設定データをそのまま保持してください。そうでない場合、agent_variables に含まれるのは動的変数のみです。

インラインのパーソナリティには意図的に制限があります。必要な保存済みパーソナリティがネットワークシミュレーション、発話プラン、メッセージプラン、生成設定、背景音量、または割り込みレベルを使用する場合は、パーソナリティへの ID 参照を維持し、その依存関係を説明してください。インラインオブジェクトを検証に通すために、これらの設定を削除しないでください。

4. 作成する決定論的で観測可能なケース

決定論的なインフラストラクチャおよびリグレッションのカバレッジには、type: "conditional_actions"を使用します。 スクリプトは{role, first_message, conditions: [{when, say, then}]}です。エージェントが最初に話す場合、first_messageは""です。thenには、呼び出し元が次のターンで行う後続の手順を記述します。両方の席のすべての手順は一字一句そのまま記述し、<ai_generated>は決して使用しないでください。LLMが生成した呼び出し元の応答をCIゲートに含めてはいけません。以前のidベースの形式（id、condition、action、…）も引き続き検証されますが、非推奨です。

作成時は、公開されているcekura-eval-designスキルとそのconditional-actionsリファレンスを使用してください。

• <interruption time="Xs" />は、thenの手順の先頭に置く必要があります。 あいさつや導入の後には正の時間を指定してください。発話がすでに進行中の場合に限り、0sを使用します。
• <ivr text="…" />と<voicemail text="…" />は自己終了タグで、手順全体を占めます。 ブロック形式の<voicemail>…</voicemail>は拒否されます。続く発話はthenの手順に記述してください。
• <silence>は中断できますが、<hold>は中断できません。コードパスが実際に選択する動作をテストしてください。
• <speed ratio="N" />（0.1～2.0）と<volume ratio="N" />（0～2.0）は自己終了タグで、次に同じ種類のタグが現れるまで、その位置から適用されます。特定の語句だけに適用するには、代わりにtext="..."を追加してください。パスを検証するために使用し、聞き取れない属性をアサーションにしないでください。
• <network_simulation … />はpacket_loss（0～100）、jitter、latency（ミリ秒）を受け取り、自己終了タグです。音声品質を劣化させますが、それだけで何かが証明されることはありません。
• 保存済みの音声クリップは参照しないでください。録音はシナリオのcondition_audioマップに対するIDで参照されますが、仕様ではそのようなマップを持たない一時的なシナリオが生成されるため、コミット済みのスイート内の<audio> IDは何にも解決されません。（ダッシュボードの評価者では、録音を名前で参照できます。詳細はcekura-eval-designを参照してください。参照できないのは仕様の経路です。）

検証の前にリントしてください。 scripts/lint_suite.pyは、上記のすべてに加えて、仕様の構造、重複キー、インラインパーソナリティの制限をオフラインで無料でチェックします。

python3 <skill>/scripts/lint_suite.py cekura.tests.json --strict

サーバー独自のタグバリデーターを反映しているため、リントに問題がなければ、ドライランが失敗するのはローカルのチェックでは実際に検出できない理由（有効化されていないメトリクスや、そのチャネルに対応していないエージェントなど）に限られます。

期待される結果は判定基準です。その契約に沿って記述してください

expected_outcome は読者向けのメモではありません。LLM 判定者は呼び出しのトランスクリプトを読み、各ステートメントを個別に yes、no、または blocked として採点します。物語風の文章で書かれた基準は、同じ基準を契約形式で書いた場合よりも評価が低くなります。そのため、最初の基準を書く前に cekura-eval-design/references/expected-outcomes.md を読んでください。 CI スイートで最も頻繁に破られるルールは次のとおりです。

• すべてのステートメントは「The main agent should」で始め、1 行につき 1 ステートメントにします。 番号付きの小論文でも、散文の段落でもありません。ケースごとに 2～6 行の、原子的なステートメントを記述します。数を満たすために水増ししてはいけません。
• 話者ラベルとして使えるのは「main agent」と「testing agent」だけです。 「the agent」、「the bot」、「the caller」、「the user」、「the assistant」は使いません。判定者はラベル付きの話者がいるトランスクリプトを読むため、基準内で呼び方を変えると、実行のたびに精度が落ちます。
• テストの設定理由は書きません。 なぜケースをこのように構成したのか、タグの役割は何か、しきい値はいくつか、といったことは、どれもここには含めません。判定者には、なぜ確認するのかではなく、何を確認するのかを伝えてください。
• 主観的な表現は使いません。「速やかに」、「簡潔に」、「温かく」、「明確に」、「適切に」などです。それぞれを、main agent が観察可能な形で何を言うか、または何をするかに置き換えてください。
• ケースで終了が明示的な目的となっている場合を除き、別れの挨拶や、誰が通話を終了したかは採点しません。 常に対象となるのは、それとは別の、main agent が会話を続けるかどうかです。testing agent が完了を示す（「これで必要なことはすべて分かりました」）一方で、さらに質問をしたときに、すでに会話を切り上げていたエージェントは、正当なチェックに失敗します。採点するのは回答であり、別れの挨拶ではありません。
• すべてのステートメントは、スクリプトに記述されたターンによって発生しなければなりません。 スクリプトが発生させないトリガーを持つステートメントは、実行のたびに blocked となります。これは厳格なテストではなく、無駄な項目です。ターンのリストで実際に 2 つの対応が許容される場合は、どちらか一方だけを求めるのではなく、どちらかを認める 1 行にしてください。

終始、範囲を絞り、トランスクリプトで検証できる内容にしてください。発話内容、タグ文字列がそのまま漏れていないこと、ターンの順序などです。実際の失敗を合格にするために、アサーションを弱めてはいけません。

scripts/lint_suite.py は、ラベルの混入、「The main agent should」の欠落、主観的な表現、終了に関する採点といった機械的な項目を警告として検出します。--strict を指定して実行してください。

メトリクス

対象エージェントを確認してから、有効なスラッグまたは ID だけでメトリクスを選択してください。メトリクスが存在しない、または無効になっている場合は検証エラーとして修正します。そのメトリクスをケースから削除する理由にはなりません。

expected_outcome を採点するには、Expected Outcome メトリクスを追加する必要があります。インフラストラクチャのスイートでは、エージェントで有効になっているメトリクスを確認し、数値メトリクスも追加してください。レイテンシと割り込みのメトリクスは、トランスクリプトを読む LLM 判定者には測定できない内容を測定します。

5. 変更を安全にレビューする

更新の場合は、最後のコミットだけでなく、PR のマージベースとの差分を確認してください。

git fetch origin main
BASE_REF="${PR_BASE_REF:-origin/main}"
MERGE_BASE="$(git merge-base "$BASE_REF" HEAD)"
git diff --name-status "$MERGE_BASE" HEAD
git diff "$MERGE_BASE" HEAD -- <runtime paths> <existing suite paths>

編集する前に、変更されたランタイムシンボルごとにカバレッジマトリクスの行を完成させてください。観察可能な動作に変更がなければ、「スイートの変更なし」という結論も有効です。無関係なケースを変更したり、期待される結果を緩和したり、近くのファイルが変更されたというだけで汎用的なプロバイダーテストを追加したりしないでください。

6. ファイルをまとめて一度に書き込む

ファイルのリストも含め、必要な判断はすべてすでに済んでいます。検証を始める前に、すべてのファイルをまとめて書き込んでください。1 つのファイルを書き、質問し、次のファイルを書く、という進め方はしません。この手順は、その繰り返しを防ぐためにあります。

ワークフロー

検証済みの仕様も、それだけではゲートになりません。実行は非同期です。POST はキューに登録されるとすぐに返るため、curl で終わるジョブは、1 件も評価される前に成功を報告します。失敗しようのないゲートは、カバレッジがあるように見える分、何もないより悪いものです。そのためワークフローでは、公開されている run-suite アクションを使ってスイートを実行します。このアクションは終端状態になるまでポーリングし、すべての実行が成功しない限り失敗します。YAML を記憶頼みで組み立てず、references/ci-wiring.md（ラベルの場合は references/preview-deploy.md）からテンプレートをコピーしてください。

ユーザーとの相談で変更しない、固定事項が 2 つあります。

• 既定ではチェックがオフの dry_run チェックボックスを備えた workflow_dispatch。 手動でのディスパッチは、呼び出しを実行するための意図的な操作です。チェックボックスは、実行しない場合のためにあります。
• ユーザーがそのトリガーでの実呼び出しを明示的に求めない限り、手動実行以外のすべてのトリガーでは検証のみを行います。 ラベルプレビューを選ぶことは、その明示的な要求に当たります。実際の呼び出しにはクレジットを消費します。知らないうちに課金されるプッシュを、誰もデフォルトとして同意してはいません。

デフォルトは workflow_dispatch のみです。 Actions タブから、ユーザーが選んだブランチに対して開始します。トリガーについては最初の応答で尋ねています。回答があればテンプレートの on: ブロックに追加し、なければ手動実行のみとし、引き継ぎ時にトリガーの追加方法を記載してください。回答を待って実行を保留してはいけません。

リポジトリに Cekura を呼び出すワークフローがすでにある場合は、2 つ目を追加せず、既存のものを拡張してください。

README のセクション

references/ci-wiring.md のテンプレートに必要事項を記入して追記します。スイートで確認できること、実行方法、読み取るすべてのシークレットと変数、およびカバレッジ対象外の行も含めたステップ 2 のカバレッジ表を記載してください。

7. リントしてから検証する — 検証は必須です

valid: true になっていないスイートは完成ではありません。 完成したように見えるファイルを渡すのではなく、その旨を明確に伝えてください。lint_suite.py では確認できないことは、すべてここで確認します。すべてのメトリックスラッグが存在し、このエージェントで有効になっているか、パーソナリティに到達できるか、エージェントが CI で使用するチャネルに対応しているか、サーバーのバリデーターがすべてのタグを受け入れるかを確認します。これらのいずれかに失敗する仕様は、完成度の低いスイートではなく、まったく実行できないスイートです。

したがって、手順はリント、検証、修正、再検証の順で、valid が返るまで繰り返します。

MCP ツール scenarios_validate_json で検証してください。 {agent_id, spec, channel} を受け取り、{valid, plan} を返します。何も作成せず、キーもシェルも必要ありません。ターミナルのないサンドボックスでも、未検証のまま引き渡してよい理由にはなりません。scenarios_run_json は絶対に使用しないでください。同じ質問を dry_run=true で行えますが、クレジットを消費して発信も行うため、破壊的なツールがある環境では使用できません。

ターミナルでセッションに認証情報がない場合は、認証情報を求めてください — API キーとエージェント ID、または認証済み MCP セッションが必要です。引き渡しの段階へ黙って進んではいけません。ダッシュボードではセッションがすでに認証済みなので、キーがない場合は不具合として報告し、質問してはいけません。ユーザーが認証情報を提供できない場合に限り、未検証のまま引き渡します。その場合は、引き渡し内容とカバレッジノートの両方にその旨を明記し、以下の正確なコマンドを記載してください。また、ワークフローを手動で実行して dry run にチェックを入れると同じ確認ができるため、このセッションでは確認できなかった内容を最初の実行で検出できることも記してください。

検証では、オブジェクトを作成したり発信したりせずに、構文、メトリクス、パーソナリティ、プロファイル、ターゲットとの互換性、予定される実行、推定コストを確認します。

python3 <skill>/scripts/lint_suite.py cekura.tests.json --strict   # free, offline, first
CEKURA_API_KEY=… python3 <skill>/scripts/run_suite.py --dry-run --agent-id 123 --channel pipecat_v2

どちらのコマンドも、このスキルのディレクトリから実行します。これらは作成用ツールであり、リポジトリに保持されるファイルではありません。HTTP で直接実行する場合は、同じボディを $CEKURA_BASE_URL/test_framework/v1/scenarios/validate_scenarios_json/ に POST し、X-CEKURA-API-KEY ヘッダーを付けます。

ワークフローが送信するすべてのリクエストを、それぞれの channel で検証してください。プレビューの場合は、プレースホルダーのオーバーライドも指定します（references/preview-deploy.md に一覧があります）。valid: true を必須とし、フラグだけを見て終わらせず、返されたプランも確認してください。各ケースには意図したメトリクスが列挙されている必要があります。また、インラインの test_profile が指定されたケースは、mode: "inline" を返す必要があります。ケースが existing を返している場合、インラインブロックが反映されていません。

エラーはファイル内の位置（scenarios[2].metrics[0] など）にひも付けられて一度にすべて返るため、1 回の往復ですべての修正点がわかります。修正してください。エラーを回避するためにメトリクスを削除したり、ケースの条件を緩めたりしてはいけません。有効化されていないメトリクスは、スイートの欠陥ではなく、ワークスペースの設定上の問題です。認証情報や機微な発信者データを含まない場合に限り、検証レスポンスを保存してください。検証そのものを超える書き込みが必要に見える場合は、作業を中止して阻害要因を報告してください。

8. 納品

検証結果が valid: true になった場合にのみ納品します。認証情報を取得できなかった場合は、ステップ 7 の指示どおり、スイートに未検証のラベルを付けて納品します。

ダッシュボード — すべてのファイルを含む github_open_pull_request の呼び出しは 1 回だけにします。ファイルごとに呼び出したり、検証されていないスイートを対象にしたりしてはいけません。本文には、リポジトリにない情報を記載します。対象範囲の表、対象外の行とその理由、ドライランの計画（ケース数、予定実行数、推定コスト）、ワークフローが読み取るすべてのシークレット、変数、シークレットセット、ラベルと、それぞれの作成場所を記載します。また、ステップ 1b でエージェントの説明がリポジトリの内容と矛盾していることがわかった場合は、その不一致を最初に記載します。

書き込みが拒否された場合（403 Resource not accessible by integration、または 422 … The permissions requested are not granted to this installation）、原因は上記の 納品物 で指定した Workflows 権限です。チェックアウトによってリポジトリアクセスはすでに確認できています。接続が壊れていると示唆するのではなく、そのことを明確に伝えてください。

ターミナル — ファイルを作業ツリーに残して終了します。依頼されない限り、コミット、ブランチ作成、プッシュはしないでください。コミットメッセージを提示し、希望があれば gh pr create を案内します。PR 本文に記載する内容を報告してください。

引き継ぎ

リポジトリには次のものを残します。

• cekura.tests.json。フォーマット済みで、ソース管理対象になっていること。
• .github/workflows/cekura-tests.yml。新規作成するか、既存の Cekura ワークフローを拡張します。dry_run チェックボックスを設け、ユーザーから追加の依頼がない限り、手動ディスパッチのみをトリガーにします。
• ステップ 6 の README セクション。
• 検証結果。計画を含む valid: true、または検証コマンドを明記してスイートに 未検証 と表示します。

ケース数、チャネルとシートの対象範囲、依存関係、実環境での実行が必要な項目を報告します。トリガーについての質問に回答がなかった場合は、設定したトリガーと、別のトリガーを追加する方法を報告してください。ドライランで仕様の妥当性は確認できますが、デプロイが正常に機能することは確認できません。

同梱アセット

各ステップで必要なときに読み込みます。

• references/discovery.md — スタックに関する質問と、回答によって可能になるアサーション
• references/case-catalog.md — 実証済みの 9 種類のケース形式と、それぞれの除外条件
• references/ci-wiring.md — ワークフローと README のテンプレート、実行ターゲット、トリガー
• references/preview-deploy.md — cekura-test ラベルによるプレビューと、対象となるボット
• examples/cekura.tests.json — --strict でエラーなくリントできる 3 ケースのスイート

作成作業中は、このスキルのディレクトリから実行します。ユーザーのリポジトリにはコピーしません。

• scripts/lint_suite.py — オフラインの仕様および作成ルールのバリデーター。キーもネットワークも不要です。
• scripts/run_suite.py — 送信とポーリングを行います。ここではドライランに使用します。