scaffold-project

プロジェクトのスキャフォールディング

新規リポジトリを、検証済みのベースラインへブートストラップします。すべての品質ツールが設定され、実際に動作することを確認できる骨組みを作成し、最初の機能開発をすべてのチェックが通る状態から始められるようにします。

機能コードに先走って取りかからないでください。成果物はハーネスであり、テストが1つ通ることで検証します。それ以上は作成しません。

進捗を管理する

以下の各ステップ（0～4）についてTODOを作成し、順番に完了してください。各ステップは、完了条件を満たした場合にのみチェックを入れます。ステップ0はゲートです。新規プロジェクトでないために止めた場合は、リストを中断して適切な手順へ誘導してください。それ以外の場合、この手順で防ぐべき失敗は、ステップを飛ばすことです。つまり、ベースラインが検証されないままになったり、setup-repo への引き継ぎを忘れたりすることです。

0. 対象が新規プロジェクトであることを確認する — ゲート

スキャフォールディングでは、プロジェクトルート（Git リポジトリ、ルートのマニフェスト、ルートの README、ルートの CI、ルートの pre-commit フック）を書き込みます。既存プロジェクトに対して行うと、実際に使われている設定と競合したり、上書きしたりするおそれがあります。したがって、何よりも先に、どこにスキャフォールディングするのかを特定し、そこが空であることを確認してください。このゲートは必須です。感覚で判断するものではありません。確認を実行してください。

対象ディレクトリを特定します。 既定では現在の作業ディレクトリです。ユーザーが保存先（「packages/ の下に bot パッケージをスキャフォールディングする」など）を指定した場合、対象はそのパスです。現在の作業ディレクトリが中身のあるリポジトリルートでも、ユーザーが新しいサブパッケージを求めている場合は、対象をその新しいサブディレクトリにし、そのディレクトリを分類してください。ルートの判定で止めてはいけません。

自分で確認してください（ディレクトリの中身をユーザーに尋ねず、実際に調べてください）。

• ls -A <target> — ディレクトリが存在するか、空かを確認します。
• git -C <target> rev-parse --is-inside-work-tree と git -C <target> ls-files | wc -l — Git リポジトリ内か、追跡対象のファイルがいくつあるかを確認します。
• 対象にパッケージマニフェスト（package.json、Cargo.toml、pyproject.toml、go.mod など）があるか確認します。

分類して分岐します。

対象の状態	意味	対応
存在しない、または存在するが空／.git、README、LICENSE のみで、マニフェストがない	新規プロジェクト	ステップ1へ進みます。
既存の Git リポジトリ内にある新規／空のサブディレクトリ（例：モノレポの packages/bot）	サブパッケージ	サブディレクトリを対象としてステップ1へ進み、inside-existing-repo = true に設定します（ステップ2ではルートに触れる作業を省略します）。
マニフェストまたは多数の追跡対象ファイルがある、実在するプロジェクト	新規プロジェクトではない — 停止	スキャフォールディングしないでください。下記のとおり誘導します。

停止が必要な場合は、選択肢を並べずに適切な手順へ誘導してください。

• ユーザーが既存リポジトリでこのスキルセットを使う（トラッカーの設定、コマンドの検証、ドキュメント作成など）ことを望んでいる場合、これはスキャフォールディングではなく setup-repo の作業です。実行するよう伝えてください。
• ユーザーがこのリポジトリ内に新しいパッケージを作成することを望んでいる場合、新しいサブディレクトリのパスを確認してから、そのサブディレクトリを対象にゲートを再実行してください（サブパッケージの行に該当するはずです）。
• 誤ってこの手順にたどり着いた場合は、作業を止め、ユーザーが再検討できるようにしてください。

検出したケースと、適用する誘導先を伝えてください。完了条件： 対象を新規プロジェクトまたはサブパッケージに分類し、確定したパスをユーザーに確認してもらうか、作業を停止して誘導先を明示していること。

1. 技術スタックを詳しく確認する

必須のサブスキル：grilling を使い、特定した対象の技術スタックとレイアウトに関する決定を確定してください。各項目について、選択肢、影響、推奨される既定値を含む質問カードをすべて提示します（インラインのみ）。

• プロジェクト名（マニフェストと README で使用）
• 言語とランタイム
• フレームワーク（または「なし — プレーンなライブラリ／CLI」）
• テストランナー
• フォーマッターとリンター
• パッケージマネージャー
• リポジトリのレイアウト（単一パッケージかワークスペース／モノレポか、ソースとテストのディレクトリ構成）
• ライセンス
• レビュー前に変更をコミットするか、ステージングするか

事実関係は自分で調べてください（ユーザーがインストールしているツール、サブパッケージの場合は親リポジトリですでに使われているものなど）。ユーザーには、判断が必要な事項だけを提示してください。

完了条件： 上記の各項目について、特定した対象パスを含めて、すべて明示的に確認し、1つの要約ブロックにまとめ、ユーザーの承認を得ていること。

2. スケルトンを作成する

確定した選択内容に基づき、解決済みのターゲットにスケルトンを構築します。サブパッケージモード（inside-existing-repo = true）では、(ルートのみ) と記された手順をスキップします。これらは親リポジトリが管理するためです。また、競合する設定を新たに作成せず、親の共有設定を引き継ぎます。

1. Git (ルートのみ) — ディレクトリがまだリポジトリでなければ git init を実行し、スタックに適した .gitignore を作成します。サブパッケージモードでは、リポジトリを初期化せず、ルートの .gitignore にも手を加えません。必要な場合に限り、パッケージローカルの ignore ファイルを追加します。
2. プロジェクトのスケルトン — マニフェスト、ソースディレクトリ、最小限のエントリーポイントを用意します。サブパッケージモードでは、ワークスペースの共有ツールチェーン設定を拡張し（たとえば、ルートを extends する tsconfig）、ワークスペースにパッケージを登録します。
3. テストハーネス — ランナーをインストールして設定し、合格するサンプルテストをちょうど 1 つ用意します。このテストの目的は配線の確認（インポートが解決されること、ランナーがファイルを検出すること、アサーションが実行されること）であり、実際の動作をテストすることではありません。
4. フォーマッターとリンターの設定 — コミットする設定を用意し、format、lint、typecheck（該当する場合）をそれぞれ単一のコマンドで実行できるようにします。サブパッケージモードでは、ルートの設定を引き継ぎ、パッケージレベルの上書きだけを追加します。
5. コミット前フック (ルートのみ) — コミットのたびに、ステージ済みファイルをフォーマットしてから、リンター、型チェック、テストを実行します。スタックで一般的なフックの仕組みを使います。サブパッケージモードでは、競合するルートフックをインストールせず、親リポジトリの既存フックに（このパッケージを対象として）組み込みます。
6. CI のひな型 (ルートのみ) — プッシュ時とプルリクエスト時に同じ検証コマンドを実行するワークフローを 1 つ用意します。サブパッケージモードでは、新しいパイプラインを作成せず、既存の CI にパッケージを対象とするジョブを追加します。
7. README のひな型 — プロジェクト名、1 段落の説明文のプレースホルダー、インストールコマンドと検証コマンドを記載します。ターゲットに配置します（サブパッケージモードでは <target>/README.md に配置し、リポジトリのルートには置きません）。
8. ドキュメントの初期ファイル — スキルセットの templates/CONTEXT.md を使った CONTEXT.md、templates/specs-INDEX.md を使った docs/specs/INDEX.md、空の docs/adr/ ディレクトリを、すべてターゲットを基準に作成します。任意のプロジェクトドキュメントレイヤー： 一度だけ提案します（グリーンフィールドの複数機能プロジェクトでは役立ちますが、小規模なプロジェクトでは省略し、後から /establish-project で追加できます）。ユーザーが希望した場合は、templates/product-vision.md、templates/architecture-INDEX.md、templates/product-guidelines.md を使って docs/product/vision.md、docs/architecture/INDEX.md、docs/product/guidelines.md も初期ファイルとして作成します。希望しない場合は、これらを一切作成しません。レイヤーは setup-repo への引き継ぎ時に有効化できます。

完了条件： 該当するすべての項目が存在し、コミット済み（またはステップ 1 でユーザーが選択した方法に従ってステージ済み）であること。

3. ベースラインを検証する

必須サブスキル：verify を使用します。検証スイート全体（型チェック、リンター、テスト）を改めて実行し、出力を確認してください。ルートモードでは、コミット前フックが実際に起動し、正常に完了することも確認します（使い捨てのコミットまたはドライランを実行）。

チェックが失敗する、または検証されていない状態でスケルトンを引き継ぐことは完了ではありません。先に進む前に、問題のある要素を修正するか削除してください。

完了条件： すべての検証コマンドが成功し、成功した出力をユーザーに提示していること。

4. 引き継ぐ

スケルトンが完成したことと、次のステップとして setup-repo を実行し、エージェント向け設定（docs/agents/*.md — 検証コマンド、トラッカー、ラベル、リリース手順）を作成することをユーザーに伝えます。docs/agents/ は自分で作成しないでください。そのウィザードが管理します。

スキル全体の完了条件： リポジトリのルートから、依存関係をインストールするコマンドが 1 つ、ターゲットの検証スイートを成功させるコマンドが 1 つあること。最終的な要約では、両方のコマンドを明記します（サブパッケージモードでは、検証コマンドの対象を新しいパッケージに限定します）。