shiplight

Shiplight

Shiplight の QA 作業への単一のエントリーポイントです。このスキルはサブコマンドを受け取り、適切なワークフローに振り分けます。Shiplight ブランドに関する操作はすべてここを経由します。上記の説明には意図的に条件を設けており、ユーザーが「shiplight」と指定するか、/shiplight と入力した場合にのみこのスキルが起動します。一般的な「テストを書いて」という依頼では起動しません。

ルーティングの仕様

1. サブコマンドを特定します。 引数をディスパッチテーブルと照合します。最初のトークンだけを頼りにしてはいけません。同義表現は複数語になることが多く（yaml test、set up tests for my app）、意図を示す語がトークン以外の語で始まる場合もあるためです（create yaml test、show failing tests）。次の順序で照合します。(a) 先頭の語が正式なトークンと完全一致するか、(b) 引数に含まれる正式なトークンまたは同義表現のフレーズのうち最も長いもの、(c) 同義表現／意図の列との全体的な意図の一致。最も一致するサブコマンドを1つ選びます。
2. コンテキストを引き継ぎます。 セレクターで消費されなかった内容は、コンテキストとしてサブコマンドに渡します。自然な言い回しが想定されています。ユーザーがハイフン付きのトークンを正確に入力することはありません。意図を照合し、残りを対象として扱ってください。 例：
   • /shiplight cover checkout flow → cover ＋ コンテキスト checkout flow
   • /shiplight create a yaml test for login → create-yaml-tests（「yaml test」で照合）＋ コンテキスト for login
   • /shiplight create agent verification for the signup flow → create-agent-verification（「agent verification」で照合）＋ コンテキスト for the signup flow
3. ディスパッチします。 該当する references/<subcommand>.md（入れ子のサブコマンドの場合は references/<subcommand>/index.md）を読み、コンテキストを引き継いでその手順に従います。
4. 推測せず、確認します。 セレクターが空（/shiplight のみ）または曖昧な場合（「曖昧さに関する注記」を参照）は、メニューを表示して確認の質問を1つします。ユーザーは操作を求めていますが、方法を指定していません。これは情報提供を目的とする help とは異なります。help はサブコマンドを一覧表示／説明するもので、実行はしません（references/help.md を参照）。
5. 破壊的な操作を確認します。 空でないプロジェクトに対して init を自動実行してはいけません。先に確認してください。

共有レイヤー

• help と support を除き、サブコマンドを呼び出すたびに、テストプロジェクトのルートを特定してから references/_shared/update-check.md を1回実行します（日次のスキル更新＋shiplightai CLI バージョンゲート）。この処理によって実行が停止する場合があります。CLI が最新の公開バージョンより古い場合、サブコマンドの開始前に処理を停止し、アップグレードを案内します。
• 各サブコマンドには、必要な references/_shared/ モジュール（auth、mcp、evidence-and-report、project-layout、ground-truth、knowledge、secrets、vocabularies、test-spec-template）が記載されています。操作の前にそれらを読みます。これらは唯一の信頼できる情報源であり、サブコマンドごとに同じ内容を繰り返すことはありません。

サブコマンド（メニュー）

引数なしで呼び出された場合、または確認を求める場合は、このグループ化されたメニューを表示します。

セットアップ

• init — Shiplight のテストプロジェクトをひな形から作成し、specs/context.md を書き込みます
• setup-test-auth — テスト対象アプリケーションのログインを設定し、再利用可能なブラウザー／Playwright の状態を保存します
• update — インストール済みの Shiplight スキルと shiplightai CLI を更新します

作成

• create-yaml-tests — 仕様から決定論的な YAML E2E テストを実装します
• create-agent-verification — 再利用可能なエージェント実行検証スクリプトを作成します
• cover — テスト形式と作業量を決定し、計画を立て、作成担当を進行させ、結果を報告します

保守

• fix — 失敗しているテスト、または現状とずれたテストを再現して修正します

確認

• verify — ローカル開発中にブラウザーで UI の変更を検証します

レビュー

• review — アプリの品質レビュー（セキュリティ、プライバシー、デザイン、パフォーマンスなど）

リリース

• ci — CI ワークフローと失敗のトリアージパイプラインを設定します
• cloud — Shiplight Cloud のテスト結果（実行、失敗／不安定なテスト、アーティファクト）と分析情報（健全性の概要、成功率／実行数の推移、遅いテスト／不安定なテストのランキング、失敗の原因分析）を読み取ります

ヘルプ

• help — サブコマンドを一覧表示します。詳細を確認するには help <subcommand> を指定します（実行はしません）
• support — 人によるサポートを受けます。セッション診断情報を添えてサポートチケットを作成し、返信を確認します

メニューの最後に次のフッター行を表示します。 お困りですか？/shiplight support から担当者に連絡できます — このセッションの情報をもとにチケットが自動作成されます。

ディスパッチテーブル

正規名	同義語／意図	リファレンス
init	shiplight をセットアップ、新しいテストプロジェクト、ひな形を作成	references/init.md
setup-test-auth	テストアプリの認証、テスト対象アプリケーションへのログイン、認証済みテストアカウント、テストセッションを保存、ストレージ状態	references/setup-test-auth.md
update	自己更新、スキルをアップグレード、スキルを更新、shiplight cli をアップグレード、shiplightai を更新、cli が古い	references/update.md
create-yaml-tests	yaml テスト、yaml テストを作成、yaml/e2e テストを書く、決定論的テスト、e2e テスト、テストを書く	references/create-yaml-tests/index.md
create-agent-verification	エージェント検証、エージェント検証を作成、検証スクリプト、繰り返し実行可能なエージェントチェック、ライブ環境の検証、フルスタックテスト、クロスレイヤーテスト、スタック全体をテスト、UI を操作してバックエンド／データベースを確認、バックエンドの状態も検証、リリース前のスモークテスト、リリース前スモーク	references/create-agent-verification/index.md
cover	カバレッジ、テストカバレッジ、未テストの箇所、カバレッジの不足、テスト戦略、テストを計画、仕様を書く、テスト計画、アプリのテストをセットアップ、テストを作成、この機能をテスト	references/cover/index.md
fix	失敗したテスト、トリアージ、テストを修正、製品の変更に合わせてテストを更新	references/fix.md
verify	スクリーンショット、変更を検証、UI を確認、視覚的な確認	references/verify.md
review	セキュリティレビュー、アプリをレビュー、アクセシビリティ、プライバシー、パフォーマンス、seo	references/review/index.md
ci	github actions、ci のセットアップ、パイプライン	references/ci/index.md
cloud	クラウドの結果、テスト実行結果、失敗したテスト、不安定なテスト、ci の結果、アーティファクトをダウンロード、テストの健全性、成功率、成功率／実行数の推移、最も遅いテスト、最も不安定なテスト、失敗の原因分析、失敗の内訳、分析	references/cloud/index.md
support	行き詰まった、サポートに問い合わせる、担当者と話す、人によるサポート、shiplight が壊れている、shiplight のバグを報告、チケットを作成、サポートチケット、チケットの状態	references/support.md
help	shiplight でできること、コマンド一覧、使い方、?	references/help.md

あいまいな指示に関する注意事項

• 「test」／「write a test」 → create-yaml-tests（決定論的で、UI に重点を置く）か、create-agent-verification（UI とバックエンドの状態にまたがる）のどちらも考えられます。ユーザーが主要なユーザージャーニー、バックエンド／レイヤー横断の検証、リリース前のスモークテスト、または実稼働環境での判断を示していない限り、create-yaml-tests を既定とします。ただし、不明確な場合は確認してください。
• 「smoke test」 → それだけではあいまいです。主要画面を手早く UI で確認する場合は create-yaml-tests、リリース前に主要なユーザージャーニーが機能し、かつバックエンドに適切な状態が残ることを確認する場合は create-agent-verification です。ユーザーがバックエンドの期待値やリリースゲートを明示していない限り、どちらを指すのか確認してください。
• 「verify」／「verification」 → 動詞としての「確認する」（変更を今すぐチェックする）は verify、再利用可能な検証スクリプトの「作成」は create-agent-verification です。create- という形式が見分ける目印です。ユーザーの表現から判別できない場合は確認してください。
• 「triage」 → Shiplight では fix（失敗するテストを修正する）を意味します。review の内部的なトリアージ／計画ステップと混同しないでください。
• 「failing tests」／「flaky tests」 → CI から（「クラウド上で」「直近の実行から」、複数のテストの報告として）読み取る場合は cloud（ホストされた結果）、壊れたテストを修正する場合（「自分のテストが失敗している」「これを直して」）は fix です。表現から判別できない場合は確認してください。
• 「report a bug」／「X is broken」 → 何が壊れているかによります。ユーザーのアプリの不具合は報告すべき事実であり（_shared/ground-truth.md）、サブコマンドではありません。Shiplight 自体（スキル、CLI、クラウド API）の不具合は support です。ユーザーがどちらを指すのか不明な場合は確認してください。
• 「login」／「auth」 → 対象が示されていない場合は、何を認証するのか確認してください。テスト対象アプリの認証には setup-test-auth、Shiplight プラットフォームの認証と SHIPLIGHT_API_TOKEN の設定には、/shiplight サブコマンドではなく CLI コマンド npx shiplight setup-api-token を使います。

サブコマンドの完了または中断後（次のステップの提案）

サブコマンドの最終レポートの後（中断された実行のレポートも含む）、任意で次のステップを1 つ提案できます。ルールは次のとおりです。

• 観測済みの証拠のみ。 提案は、実行中にすでに観測されたもの（分析した差分、診断した失敗、読み取ったプロジェクトの状態）を根拠とします。提案を決めるためだけに追加の分析（新たな git diff、ファイルスキャン、ブラウザーセッション）を実行してはいけません。
• 既定では提案しません。 表のトリガーに該当しない場合は、提案行を一切出しません。失敗状態では、ほとんどの場合提案しません。ユーザーが次にすべきことは、別の Shiplight コマンドではなく、プロダクトの修正だからです。提案が行われるのは成功時です。「動作することを確認できました。では、それを永続化／継続化／可視化しましょう」。例外として提案が行われる失敗は、support の行にある Shiplight 側の失敗です。実行が途中で止まった場合も対象となり、中断レポートも該当します。
• 変更の性質に応じて判断します。 実行のきっかけとなったコード変更がバックエンドのみ、または UI への影響がごくわずかな場合は、ブラウザーを前提とする提案（verify、create-yaml-tests、review design）を抑制します。その場合に役立つのは、機能マップに基づいてユニット／コントラクト／統合テストを選ぶ cover と、レイヤー横断の実稼働チェックを行う create-agent-verification です。
• 質問ではなく、1 行の文で示します。 形式： Next: /shiplight <cmd> — <今回の実行に基づく理由>. 提案したコマンドを自動実行してはいけません。また、回答が必須の yes/no 質問をしてはいけません。判断するのはユーザーです。
• 提案は最大 1 つです。ただし、対象範囲に応じて cover と create-yaml-tests のように、実際に選択肢が分かれる場合に限り、2 つまで提案できます。
• CI／非対話モードの場合、および update／help／support の後は、提案を一切行いません。 | 実行後 | 実行中に確認されたトリガー | 推奨 | |-------|--------------------------------|---------| | init | アプリにログイン／認証が必要なルートがある | setup-test-auth。そうでなければ cover | | setup-test-auth | 別のコマンドを進めるために実行された | そのコマンドを再開します。そうでなければ何もしません | | verify | 意味のあるフローでテストに合格し、それをカバーする YAML テストがない | cover（機能レベル）または create-yaml-tests（範囲の狭い単一フロー）。verify は一時的なので、確実に固定します | | verify | 操作中に UI の問題が見つかった：ラベル／ロールの欠落、data-testids がない、不安定な DOM、コンソールの警告 | review design（アクセシビリティ＋テスト容易性） | | verify | チェックに失敗した、または変更が軽微だった | 何もしません | | fix | 診断結果が製品の変更であり、変更が修復したテストの範囲を超えている | cover <feature> を実行して、testing-what の仕様を更新します | | fix | ロケーターのずれが繰り返される／安定したセマンティックフックがない | review design（テスト容易性）。スプリントごとに修正を繰り返すのではなく、ずれの根本原因を特定します | | fix | CI の失敗が再現につながった、または複数のテストで原因が共通していた | cloud を実行して影響範囲を確認し、次回の実行が成功することを確かめます | | fix | 診断結果がアプリのバグだった | 何もしません。バグを報告します（_shared/ground-truth.md） | | create-yaml-tests | テストに合格し、CI E2E ワークフローがない | ci | | create-yaml-tests | フローの信頼性は、アサートより API／DB／ログの状態で判断する必要がある | create-agent-verification | | create-agent-verification | 安定した経路でケースが PASS し、証明が固定条件に集約される | create-yaml-tests（決定的なテストに移行）。証拠全体に対する判断に価値がある場合は対象外です | | create-agent-verification | ログイン／セッションのブートストラップで BLOCKED | setup-test-auth | | cover | Shiplight のテストを生成したが、CI との連携がない | ci | | cover | レポートの行が認証／環境に関して BLOCKED | setup-test-auth | | review | ユーザーがセッション中に UI の指摘事項を修正した | verify を実行して、修正が正しく表示されることを確認します | | review | 重大度の高い指摘事項に回帰テストがない | cover | | ci | ワークフローを設定した | プッシュまたは PR をオープンして実行を開始し、続いて cloud で初回実行の結果を確認します | | ci | テストがまだ存在しない | まず cover を実行します（ci/index.md に記載された前提条件です） | | cloud | 失敗／不安定なテストの原因が spec_issue／ずれと判断された | fix | | cloud | 原因の大半が app_regression と判断された | 実行するものはありません。報告すべきアプリのバグです | | cloud | テストされていないフローをカバーするレコーダーセッションがある | 録画から create-yaml-tests | | 任意 | 既知の修正方法がないShiplight 側の障害で実行が停止した：CLI のクラッシュ、原因不明の Shiplight API エラー、または同じステップが同じように 2 回失敗した | support。問い合わせに必要な診断情報はすでにこのセッションにあります |