boring-new-app

新しいアプリリポジトリをエンドツーエンドでセットアップする

あなたはメンテナー（Factory を所有する人）の代わりに作業します。成果物は、エキスパートのエージェントが機能の開発を始めると、あとは Factory が引き継ぐリポジトリです。以下の手順はすべてあなた自身で実行し、下記の判断事項と、本人のブラウザーが必要な作業についてのみ本人に確認してください。

0. 本人と決めること（一度のメッセージですべて確認）

• リポジトリ：OWNER/NAME（新規）— または既存のリポジトリ（その場合は §6 に進みます）。
• アプリのタイトル。
• ランタイム：vm（自分が所有するホスト上のコンテナー。エージェントはアプリ内で実行）または cloudflare（D1 を備えた Worker。エージェントは宣言型でハブにより実行され、コードを持つエージェントもジョブもありません）。既定値は vm です。
• エキスパート：GitHub のログイン名。ボットのアカウントは指定できません（GitHub では自分のプルリクエストを自分で承認できず、ボットが契約プルリクエストを作成するためです）。
• ボット：トークンが FACTORY_TOKEN となるアカウント（既定値：メンテナー）。

1. 前提条件（確認し、可能なものは修正）

gh auth status                       # signed in as the maintainer, scopes repo + workflow
gh auth setup-git                    # git (and npx github:…) use gh's credentials
gh api repos/hachej/boring-factory --jq .full_name    # read access to the factory
gh api repos/hachej/boring-app --jq .is_template      # the app template: must print true
gh api repos/hachej/boring-factory/actions/permissions/access --jq .access_level   # must be "user"

アクセスレベルが user でない場合、ほかのリポジトリから Factory のワークフローを呼び出せません：gh api -X PUT repos/hachej/boring-factory/actions/permissions/access -f access_level=user。

トークンでは確認できないため、本人に一度確認してください：

• Claude GitHub App がすべてのリポジトリへのアクセス権を持ってインストールされていること （https://github.com/apps/claude）— そうでなければ、新しいリポジトリにインストールします。
• Cursor ワーカーを使う場合：Cursor の GitHub 統合でリポジトリが認識され、オンデマンド利用が有効になっていること（https://cursor.com/dashboard）。

2. 3 つのシークレット

シークレットを表示してはいけません。gh secret set にパイプで渡してください。

シークレット	入手先
FACTORY_TOKEN	ボットのトークン。ボットがサインイン済みのメンテナーである場合：gh auth token
CURSOR_API_KEY	メンテナーの Cursor キー（シークレットストアから取得）
CLAUDE_CODE_OAUTH_TOKEN	本人のみ：本人のマシンで claude setup-token を実行（Claude Pro/Max）。チャットへの貼り付けを依頼してはいけません。本人が自分で gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo OWNER/NAME を実行するか、§3 の前にエクスポートします

§3 の前に可能なものをエクスポートして、init で設定できるようにします：

export FACTORY_TOKEN="$(gh auth token)"
export CURSOR_API_KEY="…"            # read from your secret store, never echoed

3. リポジトリを作成する

まずドライランを実行し、計画を 3 行で本人に伝えてから作成します：

npx -y github:hachej/boring-factory init OWNER/NAME --expert EXPERT --bot BOT --title "TITLE" --runtime vm
npx -y github:hachej/boring-factory init OWNER/NAME --expert EXPERT --bot BOT --title "TITLE" --runtime vm --yes

init はテンプレート hachej/boring-app からプライベートリポジトリを作成し（gh repo create --template）、これをアプリにする 1 つのコミットをプッシュします（名前、タイトル、ポート、ランタイム：scripts/init-app.mjs は deploy/<runtime>/ のみを残します；CODEOWNERS；project.md のエキスパート）。ラベルと設定を適用し、エキスパートを招待し、環境内に見つかったシークレットと FACTORY_BOT 変数を設定します。その後、不足していると報告されたシークレットを設定します（§2）。アプリにはスキルがなく、固定されているバージョンもありません。ワークフローは @main の boring-factory を呼び出します。

本番環境は後で、アプリ内の deploy/<runtime>/DEPLOY.md を参照して手動でセットアップします。init はコマンドを表示します。Cloudflare では、本番用トークンは GitHub の環境 production（main に制限）にのみ保存し、リポジトリのシークレットには設定しません。プレビューには別アカウントのトークンを使用します。

4. 確認し、決めつけない

gh secret list --repo OWNER/NAME                     # the three names
gh variable list --repo OWNER/NAME                   # FACTORY_BOT
gh label list --repo OWNER/NAME --limit 100 | wc -l  # 26 or more
gh api repos/OWNER/NAME/invitations --jq '.[].invitee.login'
gh run list --repo OWNER/NAME --limit 5

main で最初に実行される ci：

• paths は赤で、想定どおりです。カスタマイズのコミットが main に直接プッシュされたためです。
• check は緑でなければなりません。赤の場合は gh run view <id> --log-failed でログを確認し、まずテンプレートの hachej/boring-app 内で原因を修正します（新しいすべてのアプリに影響するため）。次に、プルリクエストを通じてアプリ側を修正します。

5. エキスパートに引き継ぐ

以下を記入して本人に送ります：

OWNER/NAME への招待を承認したら、自分のマシンで次を実行してください： npx skills add hachej/boring-stack --skill boring-pm -g と gh repo clone OWNER/NAME。クローン内でエージェント（Claude Code、Codex または Cursor）を開き、作りたいものを説明してください。

メンテナーには、Actions タブのfactoryワークフロー（context → ci → triage → checks → gates → build）、イベントごとに triage がコメントを 1 件だけ投稿すること、各プルリクエストのチェック boring/ci と boring/proof を確認するよう伝えてください。

6. 代わりに既存のリポジトリを使う場合

npx -y github:hachej/boring-factory sync OWNER/NAME --dry-run
npx -y github:hachej/boring-factory sync OWNER/NAME --yes     # labels + the "Adopt the Boring Factory" pull request

プルリクエストでは、リポジトリに不足しているファイルだけをテンプレートからコピーして追加します（factory.yml の呼び出し元、フォーム、PR テンプレート、CODEOWNERS、ask ルール、project.md）。ブランチ上の project.md で setup と check を記入し、手動で一度マージします（Factory はマージされるまで有効になりません）。その後、§2、§4、§5 を実施します。一度限りの導入であり、その後は何も追跡も更新もされません。

問題が発生した場合

症状	原因	対処法
factory / context が gh api …: Not Found (404) で失敗する	Factory のバグ、またはアクセス権のないトークン	ログに記載された正確なパスを確認します。トークンに問題がなければ、boring-factory の main で修正します（アプリは @main で呼び出します）
ジョブが hachej/boring-factory/.github/workflows/… を使用できないと表示する	Factory のワークフローが共有されていない	§1、アクセスレベル user
新しいアプリで check が赤くなる	テンプレートのバグ	hachej/boring-app で修正してから、アプリでも修正します
Cloudflare アプリで check がエージェントを拒否する	index.mjs、ジョブ、またはサーバーコード内の Node を使うエージェントまたはチャット	エージェントを宣言型にするか、runtime: vm を選択します
Triage または claude worker が実行されない	CLAUDE_CODE_OAUTH_TOKEN がない、または期限切れ	§2
エキスパートがコントラクトの PR を承認できない	エキスパートがボットのアカウントである	エキスパートには別のアカウントを使います
Cursor のタスクがすぐに失敗する	Cursor のクォータまたは GitHub 連携	オンデマンド利用を有効にする、リポジトリを接続する、またはタスクに builder:claude のラベルを付けます
npx github:hachej/boring-factory が取得できない	git に認証情報がない	gh auth setup-git

原因が boring-factory（プロセス）または hachej/boring-app（テンプレート）にある場合は、そちらで修正して次のアプリで問題が起きないようにします。アプリだけにパッチを適用してはいけません。