kelly-app-skill-creator

Kelly App Skill Creator

人間とエージェントが繰り返し行う作業を、Busabase を基盤とするスキルに変換します。標準的な配布先を Busabase AirApp とする、正規の Hono プロジェクトを作成します。プロダクトのワークフローと App-in-Skill の成果物契約を担い、Busabase のリソース実装と AirApp のデプロイ方法は委任します。

所有範囲

このスキルはフォーマット層の上にあるテイスト層です。この分担により、双方が本来の役割を守れます。

• $busabase-app-creator（busabase-skill-creator および busabase-template-creator の名称でも公開されています。名称は3つですが、スキルは1つです）が、成果物の有効性に関わるすべてを担います。スキル／テンプレート／パッケージのフォーマット、AirApp のランタイム言語、フレームワーク、サーバー構成、依存関係と SDK の制約、セキュリティ境界、検証、同期、デプロイの方法が含まれます。同スキルの契約では「テイストではなく、フォーマットと正確性を担う」とされており、視覚的な意見はあえて含まれないため、この層が担えます。
• このスキルは、成果物をKellyらしくするすべてを担います。プロダクトの動作、情報アーキテクチャ、画面に表示されるUI、レイアウト、インタラクションパターン、レスポンシブ動作、アクセシビリティ、ヘルプと設定、ハッシュルーティング、生成されるすべてのアプリの視覚的な受け入れ基準が含まれます。基盤となる成果物は、同スキルの「Two Ways In」にあるパッケージ優先の方法で作成し、その上にこのスキルのUI契約を適用します。
• $kelly-app-skill-creator-tests は、生成されたアプリのリポジトリレベルの適合性、プロセス、レスポンシブなブラウザ動作、OSS Busabase、Cloud OAuth、永続化、AirApp との同等性のテストを担います。
• Kelly UI の判断を $busabase-app-creator に委任してはいけません。また、ランタイムのスキャフォールドによって、このスキルのデスクトップまたはスマートフォン用シェルを置き換えたり、弱めたりしてはいけません。
• ここで AirApp のランタイム制限を繰り返してはいけません。ランタイムのルールがUI実装に影響する場合は、競合する別のランタイム契約を作らず、UI契約の範囲内で対応します。

必須の依存関係

アプリを作成または変更する前に、次の手順を実行してください。

1. 接続先、対象の Space、ノードの検出、ChangeRequests、レビュー、マージ、信頼された変更について、$busabase を読み、従ってください。
2. リソースモデリング、ネイティブ Views、Vault の境界、AirApp の制約、スキャフォールディング、検証、同期、デプロイについて、$busabase-app-creator を読み、従ってください。アプリスキルの作成には、同スキルのパッケージ優先の方法を使用します。アプリを含むスキルはテンプレートであるため、同スキルのガイダンスでもスキルを作成する際はこの方法に案内されます。成果物はテンプレートパッケージとして作成し、インストールして検証します。パッケージ内のアプリの見た目には、このスキルのUI契約を適用します。

依存関係を利用できない場合は、このスキルのローカルな成果物契約とプロダクト契約を維持し、利用できない Busabase 操作の前に停止して、不足している依存関係を正確に報告してください。別のデータバックエンドを作り出してはいけません。

生成されたアプリの完成を宣言する前に、$kelly-app-skill-creator-tests を読み、従ってください。アプリ固有のユニットテストは <app-root>/test/ に置き、共有ハーネス、外部 Busabase、OAuth、レスポンシブなブラウザ動作、AirApp との同等性の受け入れテストは、テスト用スキルに委任してください。利用できない場合は、アプリの決定的なローカルチェックを実行し、完全な完了を主張するのではなく、不足している適合性テストスイートを報告してください。

リファレンスマップ

アプリの作成や UI の変更を行う際は、3 つの UI リファレンスをすべて最後まで読んでください。他の 2 つはすべてのビジュアルトークンについて最初のリファレンスを参照しているため、まず editorial-visual-system.md を読みます。作業に取りかかる前に、選択した他のリファレンスもすべて最後まで読んでください。

必要な内容	リファレンス
Busabase SDK、ノード選択、設定、状態、ロック、準備状況、シークレット	references/busabase-data-contract.md
ランタイムの準備状況、製品のオンボーディング、セットアップ UX、再設定	references/setup-onboarding.md
人による判定、エージェントによる修正、主張、外部実行、リハーサル、復旧	references/review-and-execution-contract.md
製品の形状の選択	references/app-types.md
Research／Plan／Action／Retrospective のパターン	references/workflow-patterns.md
書体、色の系統、レイアウトレジスター、ダークモード、入稿用ルール	references/editorial-visual-system.md
注意喚起 UI、レビューアクション、ルーティング、設定、i18n	references/ui-workflow-patterns.md
デスクトップおよびモバイルのシェル実装	references/mobile-shell-layout.md
大規模なビルド不要のフロントエンドモジュール分割	references/frontend-modules.md
カスケードレイヤーを使った大規模なスタイルシートの分割	references/css-modules.md
依頼されたスクリーンショットまたはデモ録画	references/demo-recording.md

App-in-Skill 契約

• 生成されるすべてのスキルには、独自の package.json、ロックファイル、サーバーエントリ、ブラウザーファイル、チェックを含む、完全な正規 AirApp プロジェクトが含まれます。配置先は <skill-root>/content/<name>-app/ です。これは busabase テンプレートのレイアウトであり、アプリスキルの標準的な形です。同じディレクトリがスキルであり、テンプレートであり、インストール可能なパッケージでもあり、何かを二重に置く必要はありません。 kelly-email は、この構成におけるフリートのリファレンスです。
• プロジェクトがまだ <skill-root>/app/ にあるスキルは、このレイアウトが導入される前のもので、移行を待っている状態です。フリート全体を移行中です。このようなスキルは現在の場所で維持してください。無関係な作業のついでに移動してはいけません。移動するとハーネスのパス、ルートスクリプト、スクリプト内の相対インポートも書き換わり、それぞれのテストスイートを再実行する必要があるためです。移行は独立したタスクであり、別の作業の副産物ではありません。
• どちらのルートも pnpm --dir <that-root> dev でローカル実行できる状態を維持してください。ただし、ユーザーからローカルプレビューまたはローカルデバッグを明示的に依頼されない限り、起動してはいけません。このドキュメントでは、該当する方をアプリルートと呼びます。
• ユーザーから既存のローカルアプリの起動、表示、または立ち上げを依頼された場合は、?demo=1 やその他の Demo セレクターを付けず、通常の本番 URL を開いてください。通常の起動経路では、Busabase への接続と OAuth ゲートを通る必要があります。Demo は、依頼されたデモ、スクリーンショット、録画、または別途実施する UI 受け入れ確認のために明示的に選択する場合に限ります。通常起動するアプリとして Demo の URL を提示してはいけません。
• ランタイム言語、フレームワーク、依存関係、SDK バンドル、サーバー、Nodepod、検証、デプロイ可能なファイルに関するルールは $busabase-app-creator に委ねてください。ここや生成されたドメインスキルで、これらのルールを繰り返したり、上書きしたりしてはいけません。
• コミット済みのローカルソースを正規のものとして扱ってください。そのソースから AirApp をビルドして同期し、リモート側だけを編集した AirApp を残してはいけません。リモートでの変更は、必ずローカルソースにも反映してください。
• ローカルと AirApp の両方で、同じ UI、ルート、ドメインロジック、検証、Busabase リソースマップを使用してください。分離するのはランタイムのブートストラップ／トランスポートアダプターに限ります。
• アプリケーションのデータ境界には busabase-sdk を使用してください。永続的なドメイン設定、ワークフロー状態、ユーザーの判断、ロック／請求、ドメインレコードは、ローカル JSON、app/.data/、SQLite、ブラウザーストレージではなく、Busabase に保存してください。
• 環境変数は、BUSABASE_BASE_URL、BUSABASE_API_KEY、BUSABASE_SPACE_ID など、接続のブートストラップに限って使用できます。環境変数を並行するドメイン設定システムとして使用してはいけません。
• API キーや Vault の値を、ブラウザーコード、UI の状態、ログ、デモ、スクリーンショットに決して公開してはいけません。シークレットへのアクセスは Hono サーバー、または信頼された AirApp 実行境界に留めてください。
• 外部への副作用は AirApp の外部で発生させてください。AirApp は ChangeRequest を生成する判断や提案を送信できます。送信、公開、削除、課金、送金、外部システムの変更に Vault を利用した連携を行えるのは、必要な認可を得た信頼された Agent または Workflow のみです。
• ローカルストレージは、動作、認可、ワークフロー、デバイス間での期待に影響しない、破棄可能なブラウザー表示状態に限って使用してください。オペレーターに追従すべき設定は Busabase に保存してください。
• プロバイダーを選択させないでください。ローカル開発では、同じ SDK 契約を通じてローカル、Cloud、またはセルフホスト可能な Busabase に接続します。

デフォルトの配信モード

ユーザーが明示的に pnpm dev、ローカル URL、ローカルプレビュー、またはローカルデバッグを求めない限り、airapp-first を使用します。

• airapp-first では、アプリのルートを正規のソースとして生成・維持し、決定論的なチェックを実行したうえで、同じレビュー済みツリーを Busabase AirApp ChangeRequest として提出します。プロジェクトがローカルサーバーに対応しているという理由だけで、単独のローカルサーバーを起動してはいけません。
• 名前が指定された AirApp CR が明示的な権限のもとでマージされた後、選択した Busabase で AirApp を実行し、そこでプロダクト、デスクトップ、スマートフォン、アンビエントセッション、リソース、および実データの受け入れ確認を行います。正確なクリック可能な AirApp URL を返し、localhost URL で代用してはいけません。
• local-preview はユーザーから明示的に求められた場合にのみ使用します。その場合は pnpm dev を起動し、Connection UX Contract を適用して、Demo ではないローカル URL を、ユーザーに提示する主 URL として報告します。また、プロセスは単独で動作し、AirApp をアップロードまたはデプロイしていないことを明確に伝えます。受け入れ確認で Demo も必要な場合は、起動時のデフォルトではなく、別の検証経路として実行します。
• Busabase で作成した Folder や Base は、AirApp が存在する証拠にはなりません。Busabase にアップロード、デプロイ、または実行中であると述べる前に、実際の airapp ノードと、そのマージ済みバージョンを確認します。
• ローカルプレビューが 2 つ目の実装になることはありません。起動したかどうかにかかわらず、同じアプリルートのツリーのみを AirApp に提出するソースとして維持します。

Connection UX Contract

local-preview が明示的に求められた場合、すべてのスタンドアロン App-in-Skill は、CLI ログインや貼り付けた API キーなしで使用できる必要があります。このスタンドアロンの状況でのみ、接続が存在しない場合は、次の項目を含む、目的を絞ったセットアップ画面を 1 つ表示します。

• 正規の Cloud URL を使用する、選択済みの Busabase Cloud オプション。
• セルフホスト型またはエンタープライズ向け Busabase 用の URL フィールドを 1 つ表示する Custom server オプション。
• ブラウザー OAuth を開始する、優先度の高い Connect Busabase アクションを 1 つ。
• 決定論的な Demo プロバイダーがあるアプリでは、視覚的に控えめな副次的 Demo アクションを 1 つ。

API キー、デバイスコード、ターミナルコマンド、プロバイダーの選択、またはシークレットの保存方法を求めてはいけません。Cloud/custom はホスティング先の選択であり、データプロバイダーの選択ではありません。選択したサーバーは接続の初期設定にのみ保持します。プロダクトの設定はすべて、busabase-sdk を介して Busabase ノードから取得します。

OAuth から戻った後は、認証の成功、Space の指定、リソースの準備状況を区別します。Space ヘッダーを付けずに Busabase 認証の検証を呼び出し、アクセス可能なすべての Space を取得します。Cloud またはエンタープライズホストから複数の Space が返された場合は、名前と安全な ID を表示するネイティブの Space セレクターを表示します。オペレーターが 1 つを確認するまで、アプリのリソースを調査、初期化、修復してはいけません。Space が 1 つだけ返された場合は、自動的に選択します。オープンソース版の Busabase は単一の local Space を報告し、このセレクターは表示しません。

検証済みの Space ID のみを、ドメイン設定とは別に、ローカルの接続初期設定として永続化し、プロキシ経由のすべての SDK リクエストに x-busabase-space として設定します。サーバーの変更またはサインアウト時には選択をクリアします。後続のセットアップ画面と「ヘルプと設定」画面には、選択した Space の名前と ID を表示します。セッションの期限切れまたは取り消し時には、簡潔な再試行メッセージとともに接続画面に戻します。Demo は接続に成功したように装わず、読み取り専用であることを明示します。

busabase-sdk/airapp-node がエクスポートする正規の createBusabaseAirAppLocalGateway() を使用します。PKCE、トークンの更新、Space の永続化、またはプロキシのコードを各 server.js にコピーしてはいけません。ブラウザーから提供される x-busabase-space は信頼できないため、ゲートウェイが検証したサーバー側の選択を決して上書きしてはいけません。SPACE_SELECTION_REQUIRED と SPACE_NOT_ALLOWED は安定した理由として扱い、どのセットアップ画面を表示するかの判断に、人間向けのエラー文を解析してはいけません。

「スタンドアロン」はホストが示す事実であり、アプリが推測するものではありません

assets/runtime-detection/ をコピーしてください。再導出してはいけません。 3 つのファイルすべてを、生成する各 App に含めます。

アセット	配置先	役割
runtime.js	app/js/runtime.js	「自分がどこにいるか」を判定する唯一のモジュール
server-route.js	/health の隣にある server.js 内	注入された情報をブラウザーに渡す
check-rules.mjs	scripts/check.mjs のアサーション	ルールが破られた場合にビルドを失敗させる

文章ではなくアセットをコピーするのは、文章では解決できなかったためです。生成された65個の Appがそれぞれ独自に同じループバックホスト名テストを再発明しており、あるAppのチェック スクリプトでは、そのテストを必須にするところまで至っていました。

Busabaseは、ホストするすべてのランタイムでApp自身のプロセスを起動し、空でない BUSABASE_AIRAPP_RUNTIME を注入します。これを設定するのはBusabaseだけなので、値がない こと自体が「スタンドアロン」であるという確かな情報です。server.js は describeBusabaseAirAppRuntime() の結果を再公開する必要があります。ブラウザーは環境変数を 読み取れず、SDKは名前が変更されたランタイム値や将来追加されるランタイム値にも対応します。

URLからこれを判定してはいけません。ホスト名、window.self !== window.top、/api/airapp-preview/ のパスプレフィックスのいずれも使わないでください。 こうしたテストはどちらの方向にも誤判定します。BusabaseがホストするAppはDesktopと OSSでは localhost から配信されるため（http://localhost:15419）、「ループバックなら スタンドアロン」という判定は誤りです。一方、スタンドアロンの pnpm dev へは、LAN IPや https://3111-t14e66e832aa5e6a.dev.budaapps.com のような署名付き開発トンネル経由で アクセスすることがよくあるため、「ループバックでなければホスト環境」という判定も誤りです。 後者の誤判定は特に深刻です。Appが自身の接続ゲートを非表示にし、認証情報なしで /api/v1 を呼び出すため、オペレーターが対処できないエラーが報告されます。

ブラウザーコードは __airapp/runtime を相対パスで（先頭にスラッシュを付けずに） 確認します。ホスト環境のAppはBusabaseのオリジンのサブパスから配信されることがあるためです。 また、ホスト環境のオリジンにあるキャッチオールルートがHTMLのシェルを 200 で返すことが あるため、レスポンスがJSONであることも確認する必要があります。

runtime.js はプローブの結果をトップレベルの await で解決するため、2つの述語は 呼び出し箇所では同期的なままです。いずれかの述語を再エクスポートし、同時に呼び出す モジュールでは、import と export を使ってください。export { … } from "./runtime.js" は その名前をローカルにバインドしません。静的チェックがすべて通っても、実行時にAppが shouldUseLocalGateway is not defined で停止します。

2つではなく、必ず次の3つの状態を判定してください。hosted、standalone、unknown。 ランタイムを判定できない場合、各判断はそれぞれ安全な側に倒してください。

判断	unknown の場合の安全な既定値	理由
接続ゲートを表示する	表示する	不要なゲートはオペレーターが閉じられますが、必要なゲートがないとオペレーターは先に進めません。
ChangeRequestを作成せずに書き込みをマージする	マージしない	レビュー可能な書き込みは承認できますが、自動マージされた書き込みはすでにレビューの境界を越えています。

scripts/check.mjs は location.hostname とiframeのネストに関するテストで失敗し、 サーバーが /__airapp/runtime を公開することもアサートする必要があります。

認証後に references/setup-onboarding.md を適用してください。インフラの準備と製品の オンボーディングは別物です。接続され、マテリアライズ済みのAirAppでも、ワークフローが 動作する前に、オペレーターのコンテキスト、ポリシー、ソース、しきい値、スケジュール、 承認ルールが必要な場合があります。

オペレーターに、Nodes/Basesの作成、名前のないChangeRequest一覧の承認、または マテリアライズ済みIDのデプロイ設定へのコピーを指示してはいけません。承認済みの遅延 プロビジョニング用ブループリントでは、Spaceの選択後に限って Initialize workspace アクションを1つだけ表示し、そのSpaceで宣言された構造を正確に含む冪等なChangeRequestを $busabase-app-creator が送信する間、簡潔な進捗状況を表示してください。マテリアライズが 完了したら、自動的に続行してください。閲覧者に書き込み権限がない場合は、保留中のCR ID 1つか、必要な権限を正確に表示してください。オペレーターがレビューするのはそのリクエストで あり、手作業で行うスキーマの手順ではありません。 この画面はメインアプリと同じスマートフォン向けの仕様を満たす必要があります。390px と 360px の幅で、サーバーの選択肢は1列に並び、主操作ボタンは全幅で表示されること、横方向にはみ出さないこと、ターミナルでの手順を表示しないことが条件です。デプロイ済みの AirApp は既存の Busabase セッションを使用するため、ローカル OAuth のゲートを表示したり、/auth/status や /auth/start を呼び出したり、Busabase の OAuth エンドポイントに移動したりしてはいけません。

PKCE、コールバックの検証、所有者のみが行えるローカル認証情報の登録、トークンの更新と失効、プロキシへの注入、AirApp の既存セッションに関するルールは、$busabase-app-creator に委任してください。ブラウザーの JavaScript に OAuth アクセストークン、リフレッシュトークン、PKCE 検証子、Vault の値を渡してはいけません。

必須 UI 仕様

1つのワークフローに特化したエディトリアルデスクを構築してください。ランディングページでも、汎用ダッシュボードでもありません。references/editorial-visual-system.md、references/ui-workflow-patterns.md、references/mobile-shell-layout.md を、実装と受け入れの必須条件として適用してください。

assets/editorial-theme/ をコピーしてください。再導出しないでください。 生成するすべての App に、次の4ファイルを含めてください。

アセット	配置先	役割
editorial.css	app/styles/editorial.css。base-ui.css の後、アプリのスタイルの前に読み込みます	共有の base-ui トークンに適用するエディトリアルプロファイルです。色、フォントサイズ、角丸、時間の値を定義するのはこのファイルだけです
check-editorial.mjs	scripts/check.mjs のアサーションに組み込みます	他のスタイルシートに生の値が入り込んだ場合、ビルドを失敗させます
style-picker.css / style-picker.js	app/styles/style-picker.css と <script type="module"> タグ	オペレーターがファミリー／レジスターを変更できる「ヘルプと設定」のコントロールです。「ui-workflow-patterns.md の Style: Family, Register, Accent」を参照してください

このアセットをコピーするのは、runtime-detection/ と同じ理由からです。文章による指示だけでは守られませんでした。既存のアプリ全体では、宣言されたフォントサイズの67%が8～12.5pxに集中し、31種類の異なるサイズが使われていました。また、変数を使ってサイズを定義しているアプリは1つもありませんでした。どのアプリも同じ段落から独自のスケールを再導出していたのです。

• editorial.css は、フリート共通の scripts/base-ui.css に重ねるプロファイルであり、置き換えるものではありません。共有コンポーネントの管理は引き続き base-ui が担い、このプロファイルは、それらが参照するトークンの値だけを変更します。
• アプリごとに、アセットで定義されている7つの色ファミリーから1つ（data-theme）、3つのレイアウトレジスターから1つ（data-editorial）を選びます。デフォルトの ink-paper は、温かみのあるニュートラルな紙色、インク、控えめなインディゴ1色、インクに近い主ボタンを組み合わせたもので、ほとんどのデスクに適しています。より鮮やかなファミリーは、継承するのではなく、意図的に選びます。アプリのスタイルシートで8つ目のファミリーを作らないでください。既存のどれが最も近いか、それには何が足りないのかを伝えてください。
• 主題に合わない場合は、data-display="sans" を1つ指定するだけでセリフ体の見出しをオフにできます。見た目を形作るのはスケールとルールであり、書体にこだわる必要はありません。
• ディスプレイ用セリフ体は、--text-xl 以上でのみ使用します。本文サイズのCJKセリフ体は、置き換えたサンセリフ体より読みにくく、これらのアプリにはローカライズされたコピーが表示されます。
• 録画画面も主要なサーフェスとして扱います。重要な情報に15px未満の文字を使わず、閲覧者が気づく必要のある状態変化には --ease-state を適用し、判定が保存されたときは --ease-flash を1回だけ適用します。また、構造を伝えるのに1pxのほぼ白い線を使わないでください。
• ブランド、人の注意が必要な項目の概要、ワークフローナビゲーション、ヘルプと設定を、デスクトップの固定サイドバーに配置します。折りたたむとパネルアイコン付きのアイコンレールにし、ブランドアイコンは表示したままにします。
• 人が行うタスクを行動を表す言葉で示し、ワークフローナビゲーションの上に、最優先で対応すべき件数を表示します。レビューキューには、安定した行参照を使用します。
• アイテムを中心とする作業では、minmax(360px, 38%) minmax(0, 1fr) のようなデスクトップのリスト／詳細分割を使用します。リストと詳細は、それぞれのペイン内でスクロールさせます。
• 意味のあるビュー、選択状態、ヘルプと設定にはネイティブのハッシュルートを使用し、更新やブラウザーの戻る／進む操作でコンテキストが復元されるようにします。
• 幅が720px以下の場合は、実際のスマートフォン用シェルに切り替えます。コンパクトなトップバー、スクリーンを重ねるオフキャンバスサイドバー、個別の全高リスト／詳細ペイン、リストに戻る固定コントロール、ワークフローにある場合は詳細画面の固定主アクションを備えます。デスクトップUIを単に縮小するだけにしないでください。
• タッチターゲットは36〜44pxにし、長い値は折り返し、ページ全体の横方向のオーバーフローを防ぎます。ヘルプと設定はレスポンシブなモーダルにし、スマートフォンでは全画面パネルにします。
• 約1280x820、1280x720（録画時のビューポート。縦方向の100pxの差で、3行が見えるか、リストが画面下に隠れるかが変わります）、390x844、360x740で確認します。引き継ぎ前に、サイドバーの折りたたみ／ドロワー、スクリーンを覆う背景、ナビゲーション、行の選択、詳細から戻る操作、モーダルのタブ、ブラウザー履歴、オーバーフローをテストします。少なくとも2つの色ファミリーでスクリーンショットを撮り、そのうち1つはダークにします。ハードコードされた色は、確認するまで見つかりません。

Busabase のリソース運用

すべてを1つのJSONブロブに詰め込まず、各ノードの本来の強みに応じて選択します。

• アプリのルート、リソースの検出、階層、安定した所有権、ナビゲーションには、FolderとNodeツリーを使用します。
• 構造化された設定、ポリシー、ワークフローの行、レビュー項目、クレーム、メトリクス、リレーションには、Baseを使用します。
• シークレットとシークレット参照にはVaultを使用します。準備状況のみを表示します。
• 長文の手順、調査テンプレート、プレイブック、編集可能な説明コンテンツにはDocを使用します。
• インポート、添付ファイル、エクスポート、大容量のアーティファクトには、DriveとFileを使用します。
• 定型的なテーブル、ギャラリー、カンバン、カレンダー、ガント作業には、ネイティブのViewsを使用します。
• 複数リソースを横断する統合、優先順位付け、ガイダンス、目的を絞ったコマンドには、AirAppを使用します。

実装前に、明示的なリソースマップを作成します。安定したノードIDまたはスラッグ、目的、スキーマ／バージョン、読み取り／書き込み動作、変更経路、各リソースを使用する画面またはジョブを記録します。references/busabase-data-contract.md を参照してください。

プロダクトループ

デフォルトでは、次の4段階の運用ループを使用します。

調査

スケジュールに従って、または必要に応じて証拠を収集します。期間キーに対する冪等なレポートを更新し、情報源の鮮度、網羅性、不確実性、調査結果を記録します。

計画

証拠を、情報源にひも付けた具体的かつ重複のない作業項目に変換します。人がオプトアウト、ブロック、優先順位の変更、スケジュールの変更、または修正の依頼をできるようにします。ユーザーにすべての行を確認させるのではなく、注意が必要な項目のキューを使用します。

アクション

対象となる作業をアトミックに確保し、レビュー可能な成果物またはChangeRequestsを作成し、進捗と失敗を記録します。影響の大きい副作用は、信頼された承認・実行経路を経由させます。

振り返り

結果を当初の証拠や判断と比較します。プロンプト、スキル、しきい値、情報源、スケジュール、リソーススキーマ、UIの改善案を、新たな計画項目として提案します。1つの結果だけをもとに、本番ルールをひそかに書き換えてはいけません。

すべての段階に専用画面が必要とは限りません。各段階がどこで行われるのか、または意図的に省略する理由を明示します。

発見

一度に1つずつ質問します。次の点を判断するのに十分な情報を把握します。

• 誰がアプリを運用し、どのくらいの頻度で、どのような成果に責任を持つか。
• 何が調査のきっかけとなり、1つの報告期間を定義するか。
• 証拠をどのように重複のない計画項目にするか。
• 何がデフォルトで実行可能となり、人が何を停止または修正できるか。
• アクションで何を作成し、どこでレビューし、どの影響が外部に及ぶか。
• 振り返りを有用にする要素は何か。
• どの状態で人の対応が必要か。
• どの操作をネイティブのViewsで行い、どの操作をAirAppで行うか。
• 既存のBusabase Folder、Base、Doc、Drive、File、Skill、Vaultノードのうち、再利用するものと提案が必要なものはどれか。

プロバイダー、フレームワーク、スキーマの仕組み、ローカル設定パス、シークレットの保存方法をユーザーに選ばせてはいけません。

プロダクトオーバーレイ

作成前に、$busabase-app-creator向けの簡潔なオーバーレイを作成します。

# Product Overlay

User and outcome: ...
App type: ...

Research: trigger, period key, evidence, freshness, idempotency
Plan: issue/recommendation rule, traceability, default eligibility, opt-out
Action: atomic claim, deliverable, review point, external side effects
Retrospective: outcome signals, cadence, skill/process feedback

Human attention states: ...
Agent responsibilities: ...
Product onboarding: required operating context and completion/version rule
Native Views needed: ...
AirApp screens and focused actions: ...
Busabase resource map: Folder/Node root, Bases, Docs, Drives/Files, Vault refs
Delivery mode: airapp-first unless the user explicitly requested local-preview
Guide copy in plain language: ...
Explicit exclusions: ...

オーバーレイではプロダクトの動作を説明します。$busabase-app-creatorは、それを完全なリソースグラフ、機能マトリクス、セキュリティモデル、標準的なアプリルートのスキャフォールド、AirApp互換の実装、検証、同期、デプロイへと変換します。

作成ワークフロー

1. 構成を決める前に、関連するリファレンスを読み、近隣の App ベースのスキルを確認します。
2. Busabase への接続を確立し、対象の Space を明示的に指定します。
3. 対象の Node ツリーを調査し、リソースマップの草案を作成します。
4. Product Overlay について合意し、技術設計の検証を $busabase-app-creator に依頼します。
5. $busabase-app-creator に、アプリのルートで完全な標準プロジェクトを作成または更新してもらいます。このスキル内に、別のランタイム構成を独自に作成しないでください。
6. busabase-sdk の上に、Busabase リポジトリ／サービスの境界を 1 つ実装します。ブラウザーのコードは Hono/AirApp のルートを呼び出し、認証情報を保持しません。
7. ランタイム／製品のオンボーディング状態と、オーバーレイで必要とされるすべてのレビュー／実行ライフサイクルを実装します。references/setup-onboarding.md と references/review-and-execution-contract.md を適用し、ローカルのマーカーやロック、別のプロバイダーを独自に作成しないでください。
8. setup、seed、refresh、migration、validation、sync の各スクリプトは、共有モジュールを呼び出す薄いエントリーポイントとして維持します。ドメインアダプターで厳密に必要とされ、AirApp との互換性が保たれる場合を除き、Python、ネイティブバイナリ、サブプロセスのオーケストレーション、ファイルシステムを使ったワークフロー状態の管理は避けてください。
9. 永続的なローカルサーバーを起動せずに、アプリ独自の lint／型チェック／テスト／ビルドを実行します。その後、リポジトリレベルの契約、ブラウザー、OSS、および利用可能な Cloud の各テストスイートに $kelly-app-skill-creator-tests を使用します。ユーザーが local-preview を明示的に選択した場合は、続行する前に pnpm --dir <app-root> dev も実行し、ローカル接続、ワークフロー、復旧、デスクトップ、スマートフォンでの受け入れ確認を完了します。
10. デフォルトでは、同じ標準ソースを $busabase-app-creator 経由でレビュー可能な AirApp CR として直接提出します。クリック可能な Busabase レビュー URL を返し、指定されたマージ承認を待ちます。
11. マージ後、Busabase で AirApp を実行し、同じリソースマップ、代表的なデータ、アンビエントセッション、メインワークフロー、復旧状態、および必須のデスクトップ／スマートフォンのシェル動作を検証します。標準の AirApp URL を報告します。local-preview が明示的に要求された場合に限り、ローカル URL も報告します。

オンボーディングと準備状況

references/setup-onboarding.md を適用してください。Busabase の準備が整っていない場合でも、明示的なローカルプレビューではアプリを起動できる状態に保つ必要があります。また、ホスト型 AirApp では、ローカルデータや Demo データへ暗黙に切り替えるのではなく、セットアップ／オンボーディングのゲートを 1 つ表示する必要があります。実行時の準備状況とプロダクトのオンボーディングは区別してください。

実行時の準備状況には、次の状態があります。

• 接続のブートストラップがない；
• Busabase が未認証、または到達不能；
• Space が曖昧、またはアクセス不能；
• アプリの Folder／リソースがない；
• スキーマのマイグレーションが必要；
• Vault の参照がない；
• 準備完了。

プロダクトのオンボーディングでは、別途、このワークフローに必要な永続的な運用コンテキスト、ポリシー、ソース、スケジュール、しきい値、承認ルールを扱います。そのフィールドと完了状態／バージョン状態を Busabase に保存してください。プロダクトの前提条件が満たされていない場合、外部読み取りや重大なアクションを有効にしないでください。

Product Overlay と機械可読なブループリントにオンボーディング契約を宣言してください。契約には、正の整数の version、明示的な必須フィールド、それぞれの所有元となる Base／Doc リソースキー、検証ルール、各フィールドによって有効になるアクションを含める必要があります。オンボーディング要件がないプロダクトでは、明示的に空の契約とその理由を宣言してください。省略しても「なし」とは見なされません。onboarding_version、完了状態、確定した完了時刻を、宣言された Busabase リソースに保存してください。バージョンが一致しない場合は、complete ではなく needs_review または migration_needed にしてください。

認証情報がない、または期限切れの場合は、上記の Connection UX Contract を適用してください。OAuth アクションを CLI の手順や認証情報入力に置き換えないでください。

サニタイズした接続識別子とリソース識別子、および実行可能な復旧手順を表示してください。ブラウザーでシークレット値を受け付けたり、エコーしたりしないでください。必要な場合は、レビュー済みの ChangeRequests を通じてリソースをプロビジョニングまたは修復してください。復旧手順では、オペレーターに初期化、再試行、Space の選択、または名前を指定した 1 件の CR のレビューを求めてもかまいませんが、Node／Base の構築や ID の配線を委ねてはなりません。

完了基準

以下をすべて満たした場合にのみ完了とします。

• ローカルプレビューがリクエストされたかどうかにかかわらず、スキルに完全な正規のアプリルートプロジェクトが含まれ、pnpm --dir <app-root> dev が引き続きサポートされること。
• $busabase-app-creator のランタイム、SDK、セキュリティ、検証、デプロイのチェックが、競合するローカルランタイム契約なしで合格すること。
• $kelly-app-skill-creator-tests で必須のローカルテストスイートと OSS テストスイートが合格し、宣言された環境が利用可能な場合は Cloud／AirApp テストスイートも合格すること。スキップした外部テストスイートは明示的に報告すること。
• Busabase 接続、対象 Space、アプリルート、リソースマップが明示されていること。
• 永続化するすべての設定、状態、決定、主張、ドメインデータに busabase-sdk と適切な Busabase ノードを使用すること。
• Vault の値と API 認証情報がブラウザーから見える場所に決して渡らないこと。
• ローカルのセットアップで Cloud／カスタム URL OAuth と明示的な Demo パスを利用でき、デプロイ済み AirApp では環境に設定されたセッションを使用すること。
• ローカル OAuth でアクセス可能な Space を確認し、単一の Space またはオープンソースの Space を自動選択し、複数の Space がある場合は明示的なセレクター選択を必須とし、その選択前にリソース初期化を行わないこと。
• ローカルの Hono 境界が busabase-sdk/airapp-node を使用し、受信した Space ヘッダーを無視して、安定した Space 理由に基づいて分岐すること。
• Research、Plan、Action、Retrospective を表現するか、意図的に省略すること。
• 人による対応、オプトアウト、レビュー、Agent のクレームルールが明確であること。
• ランタイムの準備状態、製品のオンボーディング、レビュー判定、Agent の修正、外部実行、復旧が、選択した参照契約に従うこと。
• ブループリントでオンボーディングのバージョン、必須フィールド、Busabase のストレージ、検証、ロック解除ルールを宣言するか、根拠を添えた明示的な空の契約を宣言すること。
• ローカル実行と AirApp 実行で、同一のアプリケーションソースとリソース契約を使用すること。
• デフォルトの成果物として、マージ済みで検証済みの AirApp とクリック可能な対象 URL を用意すること。ローカル URL を報告するのは、ローカルプレビューが明示的にリクエストされた場合のみとすること。
• 該当する場合、Kelly のデスクトップサイドバー、対応項目、ワークフローナビゲーション、一覧／詳細表示、ハッシュルーティング、ヘルプと設定の契約が実装されていること。
• editorial.css がアプリの最初のスタイルシートであり、editorialAssertions が scripts/check.mjs に含まれて合格し、宣言された data-theme／data-editorial のデフォルト値が明記されていること。
• 概要画面とワークスペースを、暗色を含む少なくとも 2 つのカラーファミリーでスクリーンショットに収め、何に注目すべきかを事前に知らなくても状態変化がわかる 10 秒間の承認用クリップを作成していること。
• 1280x820 と 1280x720 のデスクトップ、390px のスマートフォン、360px の幅の狭いスマートフォンで、ワークフローが視覚、インタラクション、水平方向へのはみ出しの各チェックに合格すること。
• 依存スキルで必須の検証、デプロイ、実データのチェックに合格し、「A Green Suite Is Not An Acceptance」の説明に従って検証されていること。

テストがすべて通っても、受け入れ確認にはなりません

テストに合格したということは、想定したケースが成立したということです。変更を検証済みとして報告する前に、実際の呼び出し元が使う方法で動作を確認してください。

• ユニットテストだけでなく、実際のインスタンスに対して本物のコマンドを実行してください。 アサーションだけで統合を確認しても、分かるのは自分の想定だけです。
• 新しいリグレッションテストが、修正を外すと失敗することを確認してください。
  原因を特定した後に書いたテストは、修正の有無にかかわらず通ってしまうことがよくあります。失敗しないテストは何も証明しません。修正を取り消して失敗することを確かめ、修正を戻してください。
• 既存のテストが、たまたまどのバリエーションを通ったのか確認してください。
  サーバー側が管理する ID を保持する往復テストは、スコープ内のすべてのシークレットを空にするバグがあっても成功し続けました。失敗する経路は、誰もテストを書いていないバリエーションだったからです。
• 原因を特定する前に、環境を疑ってください。
  古いローカルデータベース、暗号化キーの不在、node_modules の欠如は、レビュー中の変更に起因するリグレッションとまったく同じように見える失敗を引き起こします。結論を出す前に、どちらなのか確認してください。
• 共有インターフェースを変更した後は、下流の前提を再確認してください。
  これまで 404 だったルートを動作するように修正すると、クライアントがテストしていなかったエラーパスがすべて、実際に通るコードパスになります。ユーザーに見つかってからではなく、クライアント側の対応も一緒にリリースしてください。

実際に実行した内容と、スキップした内容を報告してください。どの環境で実行したかを明記しない「テストに合格しました」は、結果とは言えません。

停止条件

次に必要な操作に必要な依存関係が利用できない場合、対象の Space またはアプリのルートが曖昧な場合、ノードの機能では想定するモデルをサポートできない場合、シークレットがブラウザーに渡る場合、副作用にレビュー済みの信頼できる実行経路がない場合、またはローカル版と AirApp 版でビジネスロジックを分ける必要がある場合は、作業を停止してください。