setup-project

リポジトリに必要なプロジェクトの土台をインストールし、今後のすべてのセッションと、manifest-dev を使うかどうかにかかわらずすべてのチームメイトが、同じ方向性、同じ用語、同じ意思決定の記録に基づいて作業できるようにします。

インストールまたは提供されるものは4つあり、必須なのは最初の1つだけです。

• 配線 — プロジェクトが所有する ADR 規約ファイル、用語集、North Star（プロジェクトの目的、対象とする人、目標、掲げる原則、進捗の測定方法、そして基盤となる賭けを示す、継続的に参照する声明）、およびセッションにこれら3つを読み込んで維持させ、プロジェクトが採用する土台のバージョンを記録するプロジェクトコンテキストファイルのセクションです。履歴がまったくないプロジェクトを含め、すべてのプロジェクトで実行します。
• 検証ハーネス。推奨され、デフォルトでインストールされます — 今後の実行で変更されるものが引き続き機能するかを確認するための、プロジェクト固有の単一コマンドです。確認対象ごとの手順を備え、プロジェクトにすでにあるものを基に設定されます。ハーネスをインストールする前、アップグレードを提案する前、または既存のハーネスを監査する前に、references/VERIFICATION_HARNESS.md を読んでください。独自の検証方法を持つプロジェクトは、導入を見送ることができます。その場合、コンテキストファイルにその方法を記録します。
• シード — プロジェクト自身の履歴から再構築した用語と意思決定の記録、およびユーザーが承認するか選べる、いくつかの Taste エントリ（オーナーがすでに説明している方針上の好み）です。読み取れる履歴があれば実行し、配線を補完するものであって、決してその代わりにはなりません。
• 原則スキル。提案されます — デザインやプロンプトなど、プロジェクトの作業における重要な分野ごとのプロジェクトスキルです。各分野の作業をどのように進めたいかをまとめ、コンテキストファイルに参照行を設けます。また、その分野の作業にしか必要のない原則と Taste エントリは、コンテキストファイルから該当するスキルに移します。原則スキルを提案、作成、監査する前に、手順が記載された references/PRINCIPLES_SKILLS.md を読んでください。本人が「はい」と答えた場合にのみ、内容を書き込みます。

これらはすべてプロジェクトを対象とします。プロジェクトとは、今後のセッションで変更される作業を含む、またはこれから含む予定のリポジトリや作業フォルダーのことです。ユーザーが始める新規または空のフォルダーも、以下の Empty input の説明どおり対象になります。このスキルを実行した場所にプロジェクトがない場合 — ワークスペースのないチャット、ホームフォルダーや一時作業用フォルダー、完成済みの成果物を1つだけ含むフォルダー、またはセッションを実行しているフォルダーに関係のない質問など — そのことを伝え、セットアップするフォルダーを尋ねてください。フォルダーが指定されるまで、何も書き込まないでください。

完全な記録ではなく、よい出発点を目指してください。プロジェクトの過去の推論の大半は、実際には復元できません。復元できなかった内容を正直に示すシードは、完全に見えてもそうではないシードより、はるかに価値があります。

フラグ

--no-mine はシードの作成を省略します。配線と検証ハーネスは通常どおりインストールされます。指定がなければ、履歴がある場所でシードの作成を実行します。コミットもドキュメントもコードもないプロジェクトには、シードの材料がありません。その場合は、これを明示するためのフラグは不要です。

最上位のオプションだけをフラグとして解釈してください。引用符で囲まれているもの、またはコード形式で記されているものは、話題として扱います。

すでに存在するものが基準です

作成する前に読み込み、プロジェクトがすでに管理しているものを上書きしないでください。

• docs/adr/CONVENTIONS.md が存在する → プロジェクト独自の ADR 規約があります。それが基準です。置き換えず、この実行で書き込むものにはすべてその規約に従ってください。その後、references/UPDATE.md → 比較してから提案する に従って比較してください。このファイル、docs/NORTH_STAR_CONVENTIONS.md、コンテキストファイルのサーフェスセクションがいずれも対象です。
• CONTEXT.md が存在する（またはルートの CONTEXT-MAP.md で指定されたコンテキストファイルが存在する） → 読み込んでください。抽出した語彙は追加候補として提案し、置き換えには使わないでください。
• NORTH_STAR.md が存在する → 読み込んでください。シードコンテンツは追加候補として、またはすでに示されている方針の根拠として提案してください。書き換えてはいけません。方針を変更できるのは、references/NORTH_STAR_FORMAT.md の保守ルールに従い、明示的に委任された範囲内で承認された裁定がある場合に限ります。
• docs/adr/ に記録があるが、CONVENTIONS.md が存在しない → プロジェクトには文書化されていない規約があり、その記録が根拠になります。命名規則、各記録に含まれるセクション、相互参照の方法、インデックスの形式から規約を推測し、同梱のデフォルトをそのまま置き換えるのではなく、実態に合わせて規約ファイルを作成してください。ここにデフォルトを変更せず導入すると、既存の記録群が規約に準拠していないと宣言することになり、それは誤りであり、ファイルが無視される最短の道でもあります。記録群に一貫性がない場合や、そのまま従うとインデックスを再構築できなくなる場合は、その旨を伝えてユーザーに選んでもらってください。黙って決めてはいけません。
• プロジェクトのコンテキストファイルに、すでにこの設定の一部が含まれている → 不足している設定だけを追加し、ほかはそのまま残してください。サーフェスセクションがあるもののテンプレートと異なる場合は、references/UPDATE.md → 比較してから提案する に従って比較し、提案してください。書き換えてはいけません。

想定用途と範囲を限定した調整

まず、該当するプロジェクトおよび個人の指示を確認してください。../ticket-up/references/AUTHORITY.md には、割り当て、委任された判断、および保持される承認権限が定義されています。範囲を限定した調整を行う場合は、これを参照してください。セットアップでは、後続の割り当てをどのように実行するかを設定します。プロジェクトの運用を割り当てるものではありません。

質問する前に、依頼と既存の指示から想定用途を推測してください。ここでいう調整とは、orchestrate スキルがプロジェクトのチケットを実行すること、またはそれに割り当てられた成果を、それぞれ独立したセッションで実現することを指します。プロジェクトのみのセットアップには、調整、チケットストア（プロジェクトのチケットが保存される場所。リポジトリ内のファイル、GitHub Issues、または別のトラッカーなど）、通知設定は必要ありません。調整を想定する場合は、 ../ticket-up/references/STORE_CONFIG.md を読み込み、そこを通じて既存のチケットストア、そのチケットストアが置かれているトラッカー、自動化が使用するアカウント、および実行に人の対応が必要な場合の通知先を特定してください。チケットは作成しないでください。プロジェクトが成果の進捗を判断するためにすでに指定している証拠と、通知元を確認してください。重要な未決事項だけを質問し、利用可能なアクセス権を確認してください。開始を妨げる機能やアクセスが不足している場合は、その内容を明示してください。人が希望する場合は、作業が完了するまで実行を継続するために、ホストがすでに提供している機能を使用してください。セットアップでスケジューラーをインストールすることはありません。

スキルの現在のデフォルト設定を維持してください。想定用途に関係する、プロジェクト固有の調整のみを提案し、その適用範囲、担当者、委任される判断、保持される判断を平易な言葉で説明してください。たとえば、方針の決定は委任しつつ、生成結果の承認はユーザーに残すことができます。新しいユーザーの選択を保存する前に、正確な提案文と保存先を示してください。共有ルールは、検出されたプロジェクトのコンテキストファイル、またはそのファイルからアクセスできる関連ファイルに、個人ルールは既存の非公開指示の仕組みに保存してください。すでに示されている判断を再利用してください。空のポリシー文書や網羅的な権限マトリックスを用意する必要はありません。

人が調整を承認する場合、または範囲を限定した調整を求める場合は、どの判断を本人に残すかを質問してください。それぞれについて、閉じた項目リストではなく、本人が示した例を添えた原則として記録し、既存の範囲限定指示の欄に書き込む前に、提案文を示してください。どの項目を記録するかはオーナーが決めます。プロジェクトのみのセットアップでは、この質問をしてはいけません。プロジェクトがすでに調整を行っていて、範囲限定指示に保持される判断が記されていない場合は、人がその場にいるときに、同じ質問を独立した項目として提案してください。

人がその場にいない実行では、不在を希望や回答として扱ってはいけません。既存の指示から推測したとしても、人がその場にいない場合、任意項目を希望されたものとみなしてはいけません。委任または保持される判断を記録する任意項目や、調整の準備を行う任意項目は、オーナーの判断を要する項目です。人の回答、またはプロジェクトがすでに記録している選択によってのみ確定します。これらはレポートで明示し、記録してはいけません。今回のセットアップを実行する割り当てですでに許可されている手順にあたる機械的な項目は進めてもかまいません。それ以外は実行で明示し、明示された各項目への回答が得られるまで、サーフェス版を書き込んではいけません。

サーフェスのバージョン

コンテキストファイルのプロジェクト・サーフェスセクションには、テンプレートに含まれるコメントとして、サーフェスのバージョンが1つ記録されています。ディスク上のファイルから読み取ってください。セッションにコンテキストファイルを読み込むホストはHTMLコメントを削除することがあるため、コンテキスト内のコピーには、ファイルに記録されているバージョンが表示されない場合があります。references/CHANGES.mdには各バージョンが1行ずつ記載され、最後の行が最新です。また、references/changes/vN.mdには、バージョンNがインストール済みのプロジェクトにもたらす内容が記載されています。記録されたバージョンより後のファイルだけを読み取ってください。この行はプロジェクトがどのサーフェスを備えているかを示すため、このスキルだけがこの行を書き込みます。インストール時と、更新の完了時に書き込みます。サーフェスの下に書き込まれる内容（新しい記録、用語集の項目、レシピなど）は、この行を変更しません。

figure-outは、辞退された更新の提案を独立した行に記録します。`` この辞退行は、figure-outが提案を繰り返さないようにするだけです。プロジェクトが備えている内容を示すものではないため、この実行ではバージョンとして読み取らず、サーフェスのバージョンを書き込む際に削除します。バージョン行だけがあり、その横に辞退行がある場合もない場合も、プロジェクト・サーフェスセクションが存在する場合、それは以前のfigure-outによる辞退の記録であり、このスキルによるものではありません。そのバージョン行は、そのバージョンまでの辞退行として読み取り、プロジェクトにはバージョンが記録されていないものとして扱い、セクションをインストールしてください。

記録されたバージョンは、プロジェクトが所有するコピーのどの差分を提案するかも決定します。references/UPDATE.md → 比較してから提案するを参照してください。

更新パス

コンテキストファイルにサーフェスのバージョンが記録されている場合、またはプロジェクトにすでにdocs/adr/CONVENTIONS.md、docs/NORTH_STAR_CONVENTIONS.md、NORTH_STAR.md、あるいはコンテキストファイル内のプロジェクト・サーフェスセクションがある場合、この実行は更新です。何かを提案または書き込む前に、references/UPDATE.mdを読んでください。更新の対象範囲、各不足項目の提案と報告の方法、プロジェクトが所有するコピーの比較方法が記載されています。追加で読み込むアップグレードガイドは、プロジェクトに記録されたバージョンによって異なります。

記録されたバージョン	読み込むもの
最新のCHANGES.mdに記載された最新バージョンより古いvN	references/upgrades/vN-to-current.md、続いてそのフォルダー内にある、後続の各vM-to-current.md
最新	ガイドなし
なし	バージョンガイドなし

記録されたバージョンにかかわらず、プロジェクトに移行対象のフィーチャーマップ、読者タスクリスト、または検証サーフェスのREADMEがある間は、最新のものに加えてreferences/upgrades/MOVE_TO_HARNESS.mdも読み込み、移行を1つの項目として提案してください。この項目は、ガイドの読み込み時にv3-to-current.mdが指定する項目です。移行が必要かどうかを決めるのは、記録された番号ではなく、プロジェクトの構成です。同様に、プロジェクトのNORTH_STAR.mdがまだ従来の9フィールド形式である間は、references/upgrades/RESHAPE_NORTH_STAR.mdを読み込み、形式変更を1つの項目として提案してください。各行について判断を終えていない所有者には、毎回の実行で再度提案されます。

実行

ステップ2～6では、プロジェクトに不足しているものをインストールします。プロジェクトにすでにサーフェスがある場合、これらのステップは、上記の更新パスの範囲内でのみ実行されます。更新で提案され、ユーザーが承諾した項目、機械的な項目については割り当てで許可された項目、またはデフォルトでインストールされるハーネスのステップ4については、ユーザーに伝えたうえでオプトアウトされなかった項目以外は、何も書き込みません。プロジェクトにサーフェスがまったくない場合（規約ファイル、North Star、サーフェスセクション、または推奨される検証ハーネスがない場合。現在プロジェクトが何を使って検証しているかは問いません）、承諾されれば対応するステップでインストールします。また、記録されたバージョンにかかわらず、更新の1項目として提案します。

1. プロジェクトのコンテキストファイルを解決します。 名前は CLI によって異なり、CLAUDE.md、AGENTS.md などがあるため、決めつけずに検出してください。アクティブなホストの検出とコンテキストファイルの解決ルールは ../review-code/references/context-file-adherence.md にあります。内容を読み、ルールに従ってください。用語集は、CONTEXT-MAP.md がある場合はそこから、なければ CONTEXT.md から解決してください。既存の用語集は保持し、存在しない場合は、既知のプロジェクト名と1行の目的を記載し、「Language」セクションを空にして作成してから、調査や接続を行ってください。これは --no-mine の場合にも実行します。

2. docs/adr/CONVENTIONS.md がすでに存在する場合を除き、ADR の規約を導入します。../figure-out/references/ADR_FORMAT.md を docs/adr/CONVENTIONS.md にコピーし、冒頭のみ次のように変更してください。それ以外は変更しないでください。

   • 見出しを # ADR Conventions に変更します。
   • ADR が何であるかを説明する文はそのまま残します。
   • 自己完結している旨の注記と ## Precedence セクション全体を、次の内容を述べる1つの段落に置き換えます。このファイルがプロジェクトの ADR 規約であり、優先して適用されること、決定と記述に必要なものがすべてここにあり、ツールも予備知識も不要であること、独自の既定値を持つツールはこの規約に従うこと、そして、その従属によってこのコピーはフォークとなり、同期による更新は行われないため、最新の状態を保つ責任はプロジェクトにあることを記載します。また、これを導入したセットアップを再実行すれば、現在の既定値に何が含まれるかを確認できる方法の1つであることも示してください。

   ## When a decision deserves a record 以降は、すべてそのまま引き継ぎます。このファイルはそれ自体で完結するように書かれているため、ツールを使わない読者も最初から最後まで理解できなければなりません。

   すでに記録がある場合は、単純にコピーするのではなく、上記の 既存の内容が優先される に従って既定の内容を既存の記録に示された慣行と調整し、解決が必要だった相違点を明示してください。

   プロジェクトに自動チェック（テストスイートや検証ハーネスなど）がある場合は、規約の再構築ルールに従って ADR インデックスを再構築するチェックを1つ用意してください。North Star に 有効な戦略上の選択肢 の一覧がある場合は、その規約に従ってその一覧も再構築してください。各記録の Revisit when 行を含む案内項目も対象です。ファイルとの差異があれば失敗させてください。手作業で再構築する一覧は、手作業で管理するインデックスと同じように古くなります。このルールを読んでいない貢献者にも一覧を維持させるのが、このチェックの役割です。プロジェクト独自のテスト形式、またはハーネスのシナリオとして作成してください。自動チェックがないプロジェクトには追加しません。再構築は記録を書く作業の一部として残します。インデックスまたは一覧の維持方法を決定記録で定める場合は、チェックの作成後、その記録の Enforced by 行にチェック名を記載してください。

3. North Star を導入します。ただし、NORTH_STAR.md がすでに存在する場合は除きます（その場合は 既存のものが優先される に従って提案のみ行います）。references/NORTH_STAR_FORMAT.md を読み込みます。ここには、ドキュメントの骨組み、6 つのセクション、North Star に記載できる 4 種類の行、4 つの位置状態、保守ルールが記載されています。そして、リポジトリのルートに NORTH_STAR.md を作成します。参照資料の 誠実に作成する に従って内容を準備します。ここには、何を事前に記載できるか、オーナーに何を尋ねるか、各セクションが独自の調査を待つ理由が示されています。empty の位置が、このドキュメントの TODO リストになります。成果物の事前記入は情報の掘り起こしにあたるため、--no-mine の場合は代わりに簡素な骨組みだけを書き、各セクションを、記入条件を添えて empty にします。ドキュメントと併せて、プロジェクト所有の規約コピーを docs/NORTH_STAR_CONVENTIONS.md に出力します。ただし、すでに存在する場合はそれが優先されます（ADR の規約と同じルールです）。参照資料の内容を # North Star Conventions に改題し、所有権のセクションを、このファイルがプロジェクトの North Star 規約であり、優先されることを示す 1 段落に置き換えます。ツールを必要とせず単独で完結し、同期によって更新されることのないフォークとします。最新のデフォルトに含まれる内容を確認する方法の 1 つとして、このファイルを導入したセットアップを再実行することを案内しつつ、最新の状態に保つ責任はプロジェクトにあると明記します。また、インストーラー向けの project-surfaces section の章は削除します。プロジェクトのメンテナーは、コンテキストファイル内でそのセクションを確認できるためです。

4. 検証ハーネスを導入します。将来の実行で変更されるものがプロジェクトにあり、そのコンテキストファイルに検証方法の選択が記録されていない場合が対象です。これは推奨されるデフォルトのため、ユーザーがプロジェクト独自の方法での検証を続けるためにオプトアウトしない限り、導入します。何が追加されるかを説明してから書き込み、ユーザーがオプトアウトできるようにします。プロジェクトがすでに独自の方法で検証している場合（独自の方法についての箇条書きがある場合、またはプロジェクト独自のテスト、スクリプト、ハーネスがある場合）も、同じように推奨ハーネスへのアップグレードを提案します。このハーネスは委譲によって既存のチェックを取り込み、それぞれがプロジェクト独自のコマンドを呼び出すレシピシナリオとなるため、プロジェクトが信頼しているものを置き換えることはありません。それ以前にオプトアウトしていた場合はその旨を伝えます。断られた場合は、箇条書きとチェックをそのまま残し、ディスク上で見つかったハーネスに対応する記録がなければ、その内容を記録します。導入時は references/VERIFICATION_HARNESS.md を読み込み、セットアップが作成するものと、ビルドで実行されるもの の節に従います。ツールのデフォルト言語をどのように提示し、上書きするかは、構成要素 に記載されています。オプトアウトの場合は、ユーザーと一緒にプロジェクトのコマンドと手順を確認し、ステップ 6 の検証に関する箇条書きに独自の方法として記録します。これにより、「把握する」「定義する」「実行する」のいずれでも、ハーネスが再び提示されることはありません。将来の実行で変更されるものがないプロジェクトには導入せず、その旨をレポートで伝えます。これは --no-mine の場合にも実行します。カタログは履歴ではなく、現状のソースから作成されます。

5. 事前に内容を記入します。ただし、--no-mine の場合、またはプロジェクトに surfaces のバージョンが記録されている場合を除きます（更新時の情報の掘り起こしは、references/UPDATE.md の記載に従う場合に限ります）。references/MINING.md を読み込み、そこに従います。各ソースから何を導き出せるか、また導き出せない場合に推論の根拠が失われていることを記録でどう示すか、用語集の候補を記載するのではなく承認する理由が説明されています。その後、--no-mine の場合も含めて、references/PRINCIPLES_SKILLS.md に従い、プロジェクトの重要な領域向けに原則スキルを提示します。--no-mine の場合、または履歴がない場合は、履歴のないプロジェクトについて同ファイルに記載された領域のみを読み取ります。

6. プロジェクトのコンテキストファイルを接続します。 references/NORTH_STAR_FORMAT.md → プロジェクトサーフェスのセクション に従って、プロジェクトサーフェスのセクションを出力します。テンプレートが、出力するテキストの唯一の情報源です。受け入れられた、適用範囲を限定した調整のみを含めます。テンプレートでは任意の項目として認められていますが、このファイルはすべてのセッションで読み込まれるため、ここに記載する各行は恒久的なコストとなります。インポートは、特定のハーネスのファイル名ではなく、プロジェクトのコンテキストファイル のインポートとして記述します。

7. 反映内容を報告します。まず、人の判断が必要なものとして未回答にフラグを付けた項目と、利用できないアクセス権限や機能、その次の手順を報告します。次に、設定したスコープと保持した判断を報告します。また、調整を設定した場合は、まだ操作が始まっていないことを伝えます。続いて、インストールしたもの、サーフェスのバージョンを書き込んだ場所、各原則スキルで提示した内容と書き込んだ行数、コンテキストファイルの分類、更新で提示した内容と項目ごとにユーザーが選んだ内容、すでに整っていた項目の合計数、プロジェクトがハーネスを採用したか独自の方法を維持したかを報告します。ハーネスを採用した場合は、採用して目録に記載した内容、先に確認するかどうかの選択、証明実行で実行したシナリオ、シードした内容も報告します。シードを実行した場合は、references/MINING.md の Reporting セクションに、その部分で報告すべき内容が記載されています。比較の結果も、どちらの場合でも references/UPDATE.md → Compare, then offer に従って報告します。つまり、どのコピーのどのセクションが手順どおりに現在生成される内容と異なり、それぞれについてユーザーが何を選んだかを報告するか、コピーを比較した結果、現在のデフォルトの内容がすべてすでに反映されていたことを明確に伝えます。比較の報告がなければ、比較を実行しなかった場合とまったく同じに受け取られます。それを防ぐことこそ、この手順全体の目的です。シードを省略した場合は、実際の理由を報告します。--no-mine によって省略した、プロジェクトにすでにサーフェスのバージョンが記録されている、または利用可能な履歴がなかった、のいずれかです。

入力が空の場合

コミットもドキュメントもコードもないリポジトリを指定された場合は、設定をインストールして終了します。作成するのは、規約ファイル、プロジェクト名と1行の目的、空の「Language」セクションを含む CONTEXT.md、すべてのセクションが empty と記され、その補完条件が示された NORTH_STAR.md のひな形、そしてサーフェスのバージョンを記したコンテキストファイルのセクションです。ハーネスが確認する成果物はまだありません。そのため、ユーザーがここでオプトアウトしない限り、検証項目の推奨デフォルトを記録します。そして、確認対象を作る最初の実行では、その項目が指定するコマンドから始めて、ハーネスの最初の部分を作成します。シード元がなかったため、何もシードしなかったと伝えます。これはグリーンフィールドのケースであり、機能が低下した実行ではなく成功です。開始時点ですでにサーフェスが設定されていることこそが、この手順の目的です。

プロジェクト名や目的がわからない場合は、ユーザーに確認してください。それぞれ1行で記述します。誤って推測すると、誤った前提に基づいて用語集にシードされることになります。

注意点

• 豊富な履歴があるプロジェクトは、一般的なプロジェクトではありません。 プルリクエストに設計の根拠が記載されているプロジェクトはまれです。最初に見つけたドキュメントが充実したコミットを基準に、実行の目標を設定しないでください。
• プロジェクトのコンテキストファイルに規約を再記載しないでください。 このファイルは毎回のセッションで読み込まれますが、規約ファイルは必要なときに読み込まれます。詳細を重複させると、毎回のセッションに負担がかかり、内容がずれていく複製がもう1つ生まれます。