create-upstash-software-factory

Upstash ソフトウェアファクトリーを作成する

あなたは、1つの役割を持つ小規模なシステムを誰かが構築するのを支援しています。GitHub イシューに ready ラベルを付けると、コーディングエージェントが Upstash Box 内で実装し、レビューしてマージできるプルリクエストが返ってくるシステムです。このスキルには、動作する実装（assets/template/ 内）と構築時の知見が含まれているため、ゼロから作るのではなく、実証済みのコードを応用できます。

構築するもの

• ファクトリーリポジトリ（新規で、通常はプライベート）。設定、連携コード、ワークフロー、ワーカーイメージの定義を格納します。
• 各アプリリポジトリ内の小さなトリガーワークフロー。許可されたユーザーが ready ラベルを付けると、repository_dispatch を使ってリポジトリ名とイシュー番号をファクトリーリポジトリに送信します。
• ファクトリーリポジトリ内のファクトリーワークフロー。空いているワーカーを確保し、そのワーカーの Box 内でエージェントを実行し、リポジトリのチェックを実行して、ブランチをプッシュし、プルリクエストを作成します。イシューのラベルで状態を示します：ready、factory:running、factory:review、factory:needs-attention。
• ワーカープール。1つのワーカーは、名前が付いた1つの Upstash Box です。アイドル状態の Box は一時停止されます。ワーカーのエージェントタイプによって、その Box で使用するサインイン方法、コマンド、モデル、作業量が決まります。

ユーザーが後から変更したくなる設定のほとんどは、factory.config.json にあります。各キーについては references/config.md を参照してください。

コードを変更する前に references/architecture.md を読んでください。確保プロトコルとラベルの状態、およびそのような設計にした理由が説明されています。

作業の進め方

段階ごとに作業し、各段階の終わりで止めてください。それぞれの段階で、ユーザーが動作を確認できる成果を残します。最初にすべてを構築してからまとめてデバッグすると、うまくいきません。元の構築時に見つかった複数の不具合は、各段階を個別にテストしたことで初めて明らかになったものです。

すべての段階に適用されるルール：

• サインインとキーの作成は、すべてユーザーが行います。 シークレットの値を見る必要はありません。値はユーザー自身で .env に入力するよう依頼してください。それでもチャットに貼り付けられた場合は、値を繰り返さずに .env に保存し、プロジェクト完了後にローテーションするよう提案してください。
• このフォルダーの外で何かを変更する前に、プレビューを表示してください。 クラウドリソースを作成または変更するスクリプト（smoke-test、provision-workers、build-snapshot、apply-box-settings、install-trigger、set-secrets、create-demo-issues、delete-workers）はプレビューを出力し、実行には --yes が必要です。まずプレビューを表示してください。check-setup、status、list-boxes、plan は読み取りのみです。box-exec と release-worker は、1つの Box に対してただちに操作を実行します。
• 完全な削除はユーザーに任せてください。 データを保持している Box、イシュー、スナップショットの削除は取り消せません。コマンドを提示し、ユーザー自身に実行してもらってください。数分前に作成した、何も保持していない Box やスナップショットの後片付けなら問題ありません。
• アプリリポジトリへの変更はプルリクエスト経由で行います。これにより、取り込む内容をオーナーがレビューできます。
• 検証したことと、検証していないことを明示してください。「プッシュしたが、まだ実行していない」と「テスト済み」は異なる主張です。
• 簡潔な記録を残してください。 各段階の後、ファクトリーリポジトリ内の docs/ に短いファイルを追加します。構築した内容、正確なコマンド、失敗も含む実際の結果を記したテストログを残してください。ユーザーは手順の確認、動画の録画、後日のデバッグにこれらを使います。

ユーザーのマシンに必要なもの

Node 20.6 以降、git、GitHub CLI gh が必要です。ファクトリーリポジトリの作成、そのリポジトリとアプリリポジトリへのシークレットと変数の設定（各リポジトリで管理者権限が必要です）、ワークフローファイルのプッシュ（workflow スコープが必要）ができるユーザーとしてサインインしている必要があります。プロジェクトのスキャフォールディング後、scripts/check-setup.mjs でこれらの大半を確認できます。

ステージ 0：ドキュメントが最新であることを確認する

Upstash Box SDK、Claude Code、Codex は頻繁に変更されます。テンプレートの記述は作成時点では正確でしたが、依存する部分を利用する前に、最新のドキュメントと照らし合わせて確認してください。

ユーザーがすでに Context7 や追加インストールを希望しないと伝えている場合は、ステップ 3 に進んでください。

1. Context7 を探します。このセッションに Context7 MCP サーバーがあるか、インストール済みの ctx7 コマンドがあれば、どちらでも構いません。
2. 見つからない場合は、Context7 を使ってもよいかユーザーに尋ねます。最も手軽な方法は npx ctx7@latest library "Upstash Box" "create a box and run shell commands" です。CLI をその場でダウンロードして実行するため、軽い用途ならサインインは必要ありません。正式にインストールする場合は、記憶に頼ったコマンドではなく、Context7 の最新の手順（https://context7.com および https://github.com/upstash/context7）に従い、サインインはユーザーに完了してもらいます。`npx ctx7@latest loginまたはCONTEXT7_API_KEYを使うと、利用枠が増えます。Context7 では、Box のドキュメントはライブラリ/websites/upstash_box` にあります。
3. Context7 を使わない場合は、公式ページを直接確認します。
   • Box クイックスタート：https://upstash.com/docs/box/overall/quickstart
   • シェルコマンドの実行：https://upstash.com/docs/box/overall/shell
   • スナップショット：https://upstash.com/docs/box/overall/snapshots
   • ライフサイクル、一時停止、再開：https://upstash.com/docs/box/overall/how-it-works
   • Claude Code：https://code.claude.com/docs
   • Codex：https://developers.openai.com/codex および https://github.com/openai/codex

Box の作成、シェルコマンド、スナップショット、一時停止と再開を確認し、その後、ユーザーが選んだ各エージェント CLI のヘッドレスモード、サインイン、モデル設定も調べてください。references/upstash-box.md には検証済みの項目とテンプレートで使う SDK 呼び出しが記載されているので、比較対象がわかります。

ステージ 1：ヒアリング

何かを書く前に、以下の質問をしてください。多くの項目には妥当なデフォルトがあるため、デフォルトを提示して先に進めます。質問をする前に、リポジトリを自分で確認し（gh repo view、README、package.json または同等のファイル、.gitignore、既存のワークフロー）、回答案を提示してください。

1. アプリのリポジトリ。 どのリポジトリですか？ 各リポジトリについて、次を確認します。
   • デフォルトブランチと、ファクトリーのプルリクエストの対象にするブランチ（baseBranch）。異なる場合があります。トリガーワークフローはデフォルトブランチに置く必要があり、install-trigger.mjsがこれを処理します。
   • セットアップコマンド（依存関係のインストール）と、プルリクエストの前に合格する必要があるチェックコマンド（テスト、ビルド、リンター）。チェックがないリポジトリも構いませんが、その場合は人間によるレビューだけがチェックになることを明確に伝えてください。
   • 言語とツールチェーンおよびそのバージョン。標準の Box には Node、npm、pnpm、yarn、bun、git と、pip や venv を含まない Python 3.11 が用意されています（references/upstash-box.md）。Python を使える状態にする場合を含め、それ以外はすべてワーカーイメージが必要です。また、そのイメージは最初の実行（Stage 6）より前に用意しておく必要があります。
   • テストに必要なもの：データベースなどのサービス、環境変数、所要時間の目安。セットアップとチェックには、それぞれfactory.commandTimeoutMinutes（デフォルトは20）が適用されます。
   • テストに必要なシークレット（テスト用データベース URL など）。これらはリポジトリのsecretsに設定し、セットアップ、チェック、エージェントから利用できますが、イメージには含めません。
   • セットアップやエージェント独自のツールがリポジトリのフォルダー内に残すファイルのうち、リポジトリの.gitignoreで除外されないもの：仮想環境、キャッシュ、ブラウザーツールのスクリーンショットフォルダーなどです。これらはリポジトリのexcludeに列挙してください。そうしないと、プルリクエストに含まれてしまいます。
2. エージェント。 Claude Code、Codex、両方、または別のものを使いますか？ 各エージェントについて、サブスクリプションでサインインするか、API キーを使うかを確認します。references/agents.mdを参照してください。エージェントの種類は1つだけでも、十分なファクトリーになります。ここではモデルを決めないでください。その判断については、以下で説明する別のタイミングがあります。
3. ワーカー。 エージェントの種類ごとに何台必要ですか？ まず、Upstash のプランにおける Box の上限を確認します（Upstash コンソールでプランを確認でき、scripts/list-boxes.mjsで既存の Box を確認できます）。無料プランでは Box は合計10台までで、一時停止中の Box も数に含まれていました。スモークテスト用に1枠を空けておいてください。プランの上限をfactory.boxLimitに設定すると、check-setup.mjsが同じアカウント上の他のプロジェクトの Box も含めて計算します。エージェントの種類が複数ある場合は、ラベルのない課題を最初に担当する種類も確認してください。回答がないと均等に作業が割り振られますが、一方が定額制サブスクリプションで、もう一方がトークン課金の場合には適切ではありません。回答は、エージェントの種類ごとのpriorityになります。
4. ファクトリーを起動できる人。 allowedActorsに設定する、実際の GitHub ユーザー名を確認します。実行にはユーザーのエージェント利用枠または API 予算が使われるため、このリストは重要です。また、ファクトリーのリポジトリに書き込み権限を持つ人も確認してください。その人たちは Actions のログを閲覧できます。
5. ファクトリーのリポジトリと所有者。 名前、プライベートかパブリックか、所有者を決めます。所有者は、アプリのリポジトリを所有するアカウントまたは組織と同じである必要があります。細粒度の GitHub トークンで指定できる所有者は1つだけだからです。名前が使用可能か確認し、以前の試行で作られたもの（古いファクトリーのリポジトリ、アプリのリポジトリに残った古いトリガーワークフロー、Upstash アカウント上の古い Box）が存在しないことも確認してください。最初の構築では、残骸が実際に混乱の原因になりました。
6. 作業に表示する名前。 プルリクエストとコメントには GitHub トークンの所有者名が表示され、コミットにはgitAuthorが付与されます。実在する誰の名前を使うか確認してください。その人はプレビューをホストするチームのメンバーである必要があり（コミット作成者に関する注意点を参照）、ブランチでレビューが必須の場合、自分のプルリクエストを承認できません。専用のマシンユーザーを使えば、両方の問題を避けられます。そのユーザーの noreply アドレスを使ってください。新しいアカウントでは、[email protected]のような形式です。
7. 組織のルール（リポジトリが組織に属している場合）。組織で細粒度トークンが許可されているか、承認が必要かを確認します。SSO の設定も確認してください。必須の署名付きコミットやブランチ名のパターンなど、factory/issue-Nへのプッシュを拒否するブランチルールはありますか？ Actions の許可リストはありますか？ Actions の実行時間は課金されますか？ 実行中は、その全期間にわたってランナーを占有します。
8. ワーカーイメージ。 Box が作成される前に、イメージに含めるものを決めてください。最初にイメージがビルドされ、そのイメージを使ってワーカーが作成されるからです。後から変更が必要になると、ワーカーを削除して作り直すことになります。ツールチェーン以外に、スキル、MCP サーバー、ブラウザーツール、別のエージェント CLI も必要ですか？ ブラウザーへのアクセスは、デフォルトですべての Box で有効です（factory.browser）。そのことをユーザーに伝えてください。また、Box の作成時にしか選択できないことも伝えます。これにより、Upstash が実行し、そのコンソールに表示される Chromium が Box に提供されます。エージェントが Chromium を操作するには、agent-browserなど、そのためのツールがイメージに必要です。頻繁に編集するCLAUDE.mdやAGENTS.mdなどのハウスインストラクションファイルは、通常イメージには含めません。これらはjobFilesになります（references/config.md）。そのようなファイルを使う前に、ユーザーと一緒に内容を確認してください。ファイルは GitHub リポジトリに置かれ、Linux の Box で実行されるため、プライベートなメモ、ローカルパス、そのユーザーのマシンにしかないツールへの参照は削除する必要があります。また、コミット、プッシュ、プルリクエストの作成といったファクトリーの指示に反するルールは、ファクトリーのプロンプトが優先されます。references/worker-image.mdを参照してください。
9. ホスティングに関する注意点。 アプリのリポジトリでプレビュー（Vercel、Netlify）をデプロイしたり、レビューボットを実行したりしますか？ これらはファクトリーのコミットに反応します。

Box またはスナップショットを作成する前に、モデルと推論の労力について確認してください

ワーカーのモデルと推論の労力は、CLI が読み込む設定ファイル内の Box に保存されるため、その Box から取得するスナップショットにも含まれます。これらはファクトリーが追加するコマンドラインフラグではありません。これにより、1 つのファクトリー内に、安価で高速なワーカーのプールと、難しいエンジニアリング作業向けのプールを並べて用意できます。

テンプレートでは、すべてのエージェントタイプに "boxSettings": "ask" が設定されています。この設定でも読み込みはできるため、初期段階は進められますが、Box またはスナップショットを作成するすべてのスクリプトが処理を拒否します。そのため、あるエージェントタイプの Box を初めて作成する直前、またはスナップショットを初めてビルドする直前（通常はステージ 4 のスモークテストで、以降は新しい種類のワーカーを追加するたび）に作業を止めて、ユーザーに確認してください。

「Claude Code ワーカーには、Claude Code 独自のデフォルトのモデルと推論の労力を使いますか。それとも、特定のモデルと労力を指定しますか？」（ほかのハーネスについても同様に確認してください）

• デフォルトを使う場合は、そのエージェントタイプの "boxSettings": [] を設定します。空のリストが、デフォルトを選んだことを示す記録になります。
• モデルまたは労力を指定された場合は、そのハーネスが受け付ける値を調べ（references/agents.md に Claude Code と Codex で検証済みの設定例があり、最新のドキュメントにはモデル名が記載されています）、boxSettings に入力します。
• 同じハーネスで複数種類のワーカーを使うか、たとえば簡単な作業には小型モデルを使い、難しい課題には高い労力設定で大型モデルを使うかどうかを確認してください。それぞれの種類は独立したエージェントタイプです。auth と command は同じで、boxSettings は異なります。それぞれに固有のワーカーと agent:<name> ラベルがあり、イメージを使う場合は固有のスナップショットもあります。エージェント名は 14 文字以下の小文字にしてください。
• 大型モデルや高い労力設定を使うとサブスクリプションの上限、または API の予算をより速く消費し、並列ワーカーを使うと消費量が倍増することを、一度伝えてください。

smoke-test.mjs、provision-workers.mjs、build-snapshot.mjs のプレビューには、Box に適用されるモデルと労力が表示されます。--yes を追加する前に、その行をユーザーに見せてください。

後から変更する場合：boxSettings を編集し、既存の Box に対して scripts/apply-box-settings.mjs --yes を実行します。スナップショットがある場合は、そのエージェントタイプのスナップショットも再ビルドしてください。

ブラウザーアクセスも同時に決めます

ファクトリーが作成するすべての Box はブラウザーアクセスを有効にします。factory.browser のデフォルト値が true のためです。ユーザーが不要だと言わない限り、有効のままにしてください。モデルとは異なり、作成済みの Box では変更できません。切り替えられるのは Box.create({ browser: true }) だけです。次の 2 点が重要で、どちらも初回のビルド時にワーカーをすべて削除して再作成する必要があります。

• Box.fromSnapshot は browser: true を無視します。SDK はその値を送信しません。
• スナップショットから作成した Box のブラウザーアクセスは、スナップショット元の Box と同じになります。そのため、イメージはブラウザーアクセスが有効な Box でビルドする必要があります。build-snapshot.mjs はこの条件を確認し、満たされない場合は処理を拒否します。

同じプレビューにブラウザーの行も表示されます。provision-workers.mjs と smoke-test.mjs は、作成するすべての Box をテストし、ブラウザーアクセスが無効な Box が最初に見つかった時点で停止します。詳しくは references/upstash-box.md を参照してください。

ステージ 2：ファクトリーのリポジトリをひな形から作成する

1. assets/template/ のすべてのファイルを、ドットファイルと .github/ を含めてプロジェクトフォルダーにコピーします。
2. ヒアリング内容をもとに factory.config.json を入力します。ローダーはプレースホルダーを拒否するため、すべての OWNER を置き換える必要があります。Upstash アカウント内のほかのものと重複しない boxNamePrefix と boxLabel を選びます（ステージ 3 で確認します）。ユーザーが使わないエージェントタイプは削除します。boxSettings は "ask" のままにしてください。
3. npm install を実行し、package-lock.json をコミットします。これがないと、ワークフローの npm ci が失敗します。
4. git init を実行し、.env が無視されることを確認してコミットした後、gh repo create OWNER/NAME --private --source . --push（または --public）を実行します。

テンプレートは、依存関係が 1 つ（@upstash/box）だけの、シンプルな Node ES モジュールです。ユーザーから別の方法を希望された場合を除き、この構成を維持してください。所有者自身が読んで変更できることを意図しています。

Stage 3: アカウントとシークレット

ユーザーに次の作業を依頼します。

• Upstash コンソールで Box API キーを作成し、.env に UPSTASH_BOX_API_KEY として設定します。
• きめ細かなアクセス許可を設定できる GitHub トークンを作成します。リソース所有者は、リポジトリを所有するアカウントまたは組織です。リポジトリアクセスには、ファクトリーのリポジトリとすべてのアプリのリポジトリを指定します。アクセス許可は Contents、Pull requests、Issues をすべて読み取りと書き込みに設定します。.env に FACTORY_GITHUB_TOKEN として設定します。各アプリのリポジトリにあるトリガーは、このトークンを使ってファクトリーのリポジトリにディスパッチイベントを送信するため、ファクトリーのリポジトリも含める必要があります。組織では、トークンを使えるようにする前に、オーナーの承認が必要な場合があります。
• references/agents.md の説明に従って各エージェントにサインインし、生成されたシークレットを .env に設定します（設定に localFile がある場合は、ローカルファイルに残しておきます）。API キーには、このプロジェクト用に作成した、利用上限のあるキーを推奨します。

続いて node --env-file=.env scripts/check-setup.mjs を実行します。ツールと設定、値が設定されているシークレット（値そのものは表示されません）、トークンがすべてのリポジトリを参照できるかどうか、Box キーが機能するかどうか、Upstash アカウントにすでに何があるかを確認します。先に進む前に、報告された問題を解決してください。

Stage 4: エージェントの種類ごとに1つの Box でスモークテストを行う

最初の Box なので、先にモデルと作業量について確認します。その後、エージェントの種類ごとに次の手順を実行します。

node --env-file=.env scripts/smoke-test.mjs claude

プレビューを表示してから、--yes を付けて実行します。Box を1つ作成し、その Box にあるツールチェーンを表示して、ブラウザーアクセスが可能であることを確認します。エージェントの種類に応じたデフォルト設定を書き込み、ファクトリーとまったく同じ方法でエージェントにサインインし、BOX OK と返信するよう求めた後、Box を削除します。間違いが起きやすい項目、つまり Box キー、エージェント CLI が存在するかどうか、サインイン方法、サマリーファイルを確認できます。

スモークテストでは、ワーカーの Box を作成するときと同じ方法で Box を作成します。エージェントの種類に応じたイメージがある場合は、そのイメージを使用します。そのため、標準の Box に CLI がないエージェントの場合は、まずイメージをビルドし（Stage 6）、次にこのスモークテストを実行します。テストでは、そのイメージをベースに起動します。事前に適切なインストールコマンドを見つけるには、--keep を付けてスモークテストを実行し、scripts/box-exec.mjs <box name> "<command>" でコマンドを手動で試してください。

Box の作成時に上限エラーが発生した場合、アカウントが上限に達しています。一時停止中の Box も数に含まれます。削除する Box はユーザーが決めます。

Stage 5: ドライランでトリガーを確認する

1. 設定作業中に実際のジョブが開始されないよう、まずドライランモードを有効にします。gh variable set FACTORY_DRY_RUN --body true --repo OWNER/FACTORY-REPO
2. node --env-file=.env scripts/set-secrets.mjs を実行してプレビューを確認し、ユーザーの承認後に --yes を付けて実行します。リポジトリの設定が変更されるため、先に確認してください。
3. node scripts/install-trigger.mjs を実行してプレビューを確認し、その後 --yes を付けて実行します。使用中のエージェントの種類ごとに、課題ラベルと agent:<name> ラベルを1つ作成します。また、各アプリのリポジトリのデフォルトブランチに、トリガーワークフローを追加するプルリクエストを作成します。ユーザーにプルリクエストをマージしてもらいます。
4. ユーザーに、いずれかのアプリのリポジトリでテスト課題を作成し、ready ラベルを付けてもらいます。
5. ファクトリーのリポジトリにある Actions タブで実行内容を確認します。「Show the plan」ステップに、課題、すべてのワーカー、および選択されるワーカーが表示されるはずです。ラベルごとに実行がちょうど1つ表示されます。

実際のジョブを開始する準備がワーカーに整うまで、ドライランモードを有効にしたままにしてください。

実行が表示されない場合は、次の順に確認します。トリガーのプルリクエストがデフォルトブランチにマージされていること、ラベルを付けたユーザーが allowedActors に含まれていること、アプリのリポジトリに FACTORY_GITHUB_TOKEN シークレットが設定されていること、そのトークンがファクトリーのリポジトリに書き込めること、両方のリポジトリで Actions の実行が許可されていること。

ステージ 6：ワーカーにイメージが必要な場合のワーカーイメージ

いずれかのリポジトリのセットアップやチェックで、標準の Box にないものが必要な場合（スモークテストで何があるかが表示されています）、エージェントの CLI が不足している場合、またはユーザーがスキル、MCP サーバー、ブラウザーを求めている場合は、今すぐ実施してください。それ以外の場合は省略してください。後から追加できます。

1. worker/setup.sh を編集します。まず references/worker-image.md を読んでください。イメージに含めるものと、スクリプトの記述方法を左右する Boxes の仕様について説明しています。
2. ワーカーを 1 つだけ作成します。それ以上作成しないでください：node --env-file=.env scripts/provision-workers.mjs <worker id> --yes。イメージができるまで、ほかのワーカーは待機します。この Box は factory.browser からブラウザーアクセスを取得し、イメージはそのアクセスをすべてのワーカーに引き継ぎます。
3. ビルドします：node --env-file=.env scripts/build-snapshot.mjs <worker id>。プレビューを表示してから、--yes を指定します。このコマンドは、Box にブラウザーアクセスがあることを確認し、その Box でセットアップを実行し、エージェントの種類の boxSettings を書き込み、シークレットと古いワークスペースを削除し、ディスクをスキャンしてシークレットらしきものがないか確認し、スナップショットを作成して、その ID を agents.<name>.snapshotId として保存します。設定をコミットしてください。
4. イメージが必要なエージェントの種類ごとに、手順 2 と 3 を繰り返します。--shared を指定すると、代わりにすべてのエージェントの種類で共有するツールのみのイメージを 1 つビルドし、factory.snapshotId として保存します。
5. scripts/box-exec.mjs を使って Box 内で確認します。ツールのバージョンと、各ツールを使った実際の操作を確認してください。

この後に作成する Boxes は、イメージから起動します。ビルドに使用した Box にはすでにすべてが揃っているため、何も削除する必要はありません。再作成が必要なのは、それより前に存在していた Boxes だけです（ユーザーが delete-workers.mjs を実行してから provision-workers.mjs を実行します）。

ステージ 7：最初の実際の実行

ドライランモードをオフにします：gh variable delete FACTORY_DRY_RUN --repo OWNER/FACTORY-REPO。テスト用 Issue にユーザーが ready を付け直すよう依頼してください（いったん削除してから、もう一度追加します）。実行を監視し、次の各項目をすべて確認してください。元のビルドでは、どの項目も少なくとも一度は失敗しています。

• Issue の状態が ready から factory:running、さらに factory:review に変わり、ワーカー名を記したコメントが付いている。
• PR が作成され、Closes #N と記載されており、説明にはエージェント自身の要約が含まれている。「(The agent gave no summary.)」ではない。
• リポジトリのセットアップとチェックが実行され、ログ上で成功している。
• PR のプレビューデプロイとその他のボットのチェックが成功している。デプロイがブロックされる場合は、通常、コミット作成者が正しくありません。
• ワーカーが解放されている：node --env-file=.env scripts/status.mjs でワーカーが空き状態で、Box が一時停止中と表示される。
• 認証情報が残っていない：node --env-file=.env scripts/box-exec.mjs <worker> "ls -d ~/.git-credentials /workspace/home/.factory" --pause で、どちらも見つからないことを確認します。

エージェントの種類ごとに Issue を 1 つずつ使って繰り返します。種類を指定するには、ready を付ける前に Issue に agent:<name> を付けます。

ステージ 8：スケールテスト

1. node --env-file=.env scripts/provision-workers.mjs を実行し、プレビューをユーザーに表示します。各 Box のイメージ、モデル、推論の労力が一覧表示されます。次に --yes を指定して実行します。すべてのワーカーについて一時停止状態の Box を作成するため、実行が同じ Box の作成を競合することはありません。
2. demo-issues.example.json を基に scripts/demo-issues.json を作成します。ユーザーのリポジトリに合った、小規模で互いに独立した機能を記述します。ワーカー数より多くの Issue を作成し、いくつかは待機するようにします。
3. node scripts/create-demo-issues.mjs --yes はラベルなしで Issue を作成するため、ユーザーは都合のよいタイミングでラベルを付けられます。--ready を指定するとすべての Issue が一斉に開始されます。この場合、allowedActors に含まれるユーザーとして gh にサインインしている必要があります。
4. その後、次の項目を確認します。Issue ごとに実行が 1 回だけ行われていること、すべての Issue が factory:review または factory:needs-attention になっていること、すべてのワーカーが再び空き状態であること、レート制限による失敗がないこと。API キーを使う場合は、ユーザーにプロバイダーの使用状況ページを確認してもらいます。

小規模なリポジトリで PR を並行して作成すると、同じファイルに変更が加わることを事前にユーザーに伝えてください。各作業は独立して行われますが、後からマージする際に競合が発生することがあります。これは並行作業の性質であり、ファクトリーの不具合ではありません。

ステージ 9：引き継ぎ

• ファクトリーリポジトリの README を作成します。何をするものか、リポジトリ、ワーカー、エージェントの種類を追加する方法、ラベルの読み方、および references/architecture.md の図を記載します。
• セットアップ中に漏えいしたシークレット（チャットに貼り付けたもの、画面に表示したもの）を列挙し、ローテーションを推奨します。GitHub トークンと各エージェントトークンの有効期限も記載します。
• 次の内容を一度、はっきりと伝えます。エージェントは自身の許可確認プロンプトを無効にして実行され、ジョブの実行中はサインイン状態を保持し、イシューのテキストを読み取ります。ブラウザーまたは Web アクセスがあれば、Web ページも読み取ります。allowedActors で制御するのはラベルを付けられるユーザーであり、イシューを書いたユーザーではありません。そのため、特に公開リポジトリでは、ラベルを付ける前にイシューを読んでください。
• 日常的に使うコマンドを示します。scripts/status.mjs、キャンセルされた実行後にビジー状態のままになったワーカー用の scripts/release-worker.mjs、モデル変更用の scripts/apply-box-settings.mjs です。

既存のファクトリーを変更する

• リポジトリを追加する： repos に追加し、GitHub トークンのアクセス権を拡張して、install-trigger.mjs --yes と set-secrets.mjs --yes を実行します。
• ワーカーを追加する： workers に行を追加し、Box の上限を確認します。新しい種類のワーカーであれば、モデルとエフォートについて確認し、provision-workers.mjs --yes を実行します。
• エージェントの種類を追加する： references/agents.md を読み、"boxSettings": "ask" を指定して agents に追加し、モデルについて確認します。スモークテストを実行した後、そのラベル用に install-trigger.mjs --yes を、シークレット用に set-secrets.mjs --yes を実行します。
• モデルまたはエフォートを変更する： エージェントの種類の boxSettings を編集し、apply-box-settings.mjs --yes を実行します。スナップショットがある場合は、そのエージェントの種類のスナップショットも再構築します。
• 既存のワーカーにブラウザーアクセスを付与する： 既存の Box では有効にできず、ブラウザーアクセスなしの Box で作成したイメージから、そのアクセスが引き継がれることもありません。"browser": true を設定し、設定から snapshotId の値を取り除いて、ユーザーにワーカーを削除してもらいます（delete-workers.mjs --yes）。その後、プレーンな Box を 1 つ作成し、その中でイメージを再構築してから、残りのワーカーを作成します。references/worker-image.md を参照してください。
• 起動できるユーザーを変更する： allowedActors を編集し、install-trigger.mjs --yes を実行して、PR をマージします。
• 問題が発生した場合： まず references/pitfalls.md を読みます。これまでに確認された障害の大半は、原因とともにここに記載されています。

参考ファイル

• references/architecture.md：コンポーネント、ジョブの手順、ラベルの状態、ワーカーの取得プロトコル、ファイルマップ、README の図。
• references/config.md：factory.config.json のすべてのキー。
• references/agents.md：サインイン、コマンドライン、およびサブスクリプションまたは API キーを使う Claude Code と Codex のモデルとエフォートの設定、さらにほかのエージェントを追加する方法。
• references/upstash-box.md：テンプレートで使われる SDK 呼び出し、標準の Box に含まれるもの、ドキュメントの場所。
• references/worker-image.md：スナップショットの構築と使用。
• references/pitfalls.md：元の構築時に起きたすべてのバグや予想外の事象と、その原因および修正方法。デバッグの前に読んでください。