setup-project

目的

このスキルは、新しいリポジトリにのみ使用してください。公式 Git ソースから選択したチャンネルを解決し、インストール済みのバンドルテンプレートがその正確なコミットと一致することを検証し、バンドルをレンダリングし、今後の三者間更新に備えてコミットを記録し、新規プロジェクトのワークフローを初期化し、生成されたドキュメントを検証します。レガシーなプロジェクト状態の移行は行いません。

<skill-dir> はこの SKILL.md が含まれるディレクトリとして、<core-dir> はその兄弟ディレクトリにある dstack-core スキルディレクトリとして解決してください。ワークフローごとに環境が作成されるのではなく、uv がワークフローで1つの環境を再利用するよう、共有ワークフローランナーを通じてセットアップヘルパーを実行してください。

共有信頼契約

このワークフローを実行する前に、 ../dstack-core/references/TRUST-AND-AUTHORITY.md を読み、その内容に従ってください。この契約は、このワークフローにおける規範です。このスキルと矛盾する場合は、より制限の厳しいルールに従い、矛盾について報告してください。

起動時のバージョン確認

プロジェクトをレンダリングまたは初期化する前に、setup-project について ../dstack-core/references/SKILL-VERSION.md の指示に従ってください。読み取り専用の宛先事前チェックの後、プロジェクトを変更する前に、正確な1行の出力を取得し、セットアップの JSON／応答に含めてください。結果が stale の場合は npx skills update を案内してください。unavailable の場合は、最新性に関する確認を行っていないことを記録し、オフライン作業を妨げないでください。

セットアップ固有の権限：

• デフォルトのソースは gh:RobertDeRose/dstack です。stable は最新の安定版 PEP 440 タグを、unstable はデフォルトブランチの HEAD を選択します。デフォルトは Stable です。
• ヘルパーは選択されたタグ、ブランチ、または明示的なリビジョンを参照解除し、バンドルされた copier.yml と template/ がそのコミットと一致することを検証したうえで、到達可能な正確な40文字の SHA を .copier-answers.yml に記録します。スキルのメタデータをテンプレートの来歴として使用することはありません。
• --template-source と --vcs-ref は、開発／テスト用の明示的な上書きです。指定されたリビジョンは、記録されたソースから取得できる必要があります。
• このワークフローでは、既存のプロジェクトコンテンツを移行入力として解釈することはありません。ヘルパーには、プロジェクトファイルの上書きモードはありません。既存のリポジトリは /migrate-workflow に案内してください。

ルーティングの事前チェック

ヘルパーを呼び出す前に、宛先を確認してください。

1. .copier-answers.yml が存在する場合は、セットアップを実行しないでください。プロジェクトがすでに Copier で管理されていることを説明し、AskUserQuestion で次の質問を1つだけしてください：Run /update-project instead?
2. ユーザーが同意した場合にのみ、/update-project を実行してください。ユーザーが拒否した場合は、リポジトリを変更せずに終了してください。
3. プロジェクトファイルは存在するものの .copier-answers.yml が存在しない場合は、そこで終了し、ユーザーを /migrate-workflow に案内してください。移行ユーティリティをプロジェクトにコピーしたり、このワークフローで既存のリポジトリをマージしたりしないでください。
4. インストール済みのローカルスキルツリーまたは skills-lock.json 以外に存在するものがない、新規プロジェクトディレクトリである場合にのみ、セットアップを続行してください。

ヘルパーは既存の .copier-answers.yml がある場合、独自に処理を拒否します。これは非対話型の安全策であり、/update-project を自動的に実行する許可ではありません。

プロジェクト概要

ヘルパーを呼び出す前に、不足している情報をAskUserQuestionで一度に1つずつ、次の順序で収集します。

1. --purpose：問題と意図する結果を説明する1文；
2. --users：想定するユーザーを説明する1文；
3. --scope：現在サポートしている範囲を説明する1文；
4. --boundaries：主な対象外事項と責任範囲を説明する1文；
5. --project-kind：library、cli、service、application、infrastructure、documentation、otherから選択；
6. --language-profile：python、typescript、rust、go、elixir、nix、otherから1つ以上選択。

種類とプロファイルの選択は確認として扱います。2回目の確認質問はしないでください。otherは単独でのみ選択でき、認識されている言語ツールがないことを意味します。値は空でない1行にしてください。不足している情報をプロジェクト名から推測したり、デフォルト値を捏造したりしないでください。

次に、リポジトリがsingle-package（デフォルト）かmonorepoかを尋ねます。モノレポモードでは、正確なdisplay_name、小文字のハイフン区切りのslug、正規化された相対POSIX path、空でない正規のlanguage_profilesリストを含むパッケージオブジェクトを1～32個収集します。表示名と技術的な頭字語はそのまま保持してください。各オブジェクトを--monorepo-packageでJSONとして渡し、--repository-layout monorepoを渡します。ヘルパーのlayout_preflight全体を報告してください。無効、予約済み、重複、大小文字の衝突、またはシンボリックリンクされたパスが報告された場合は、レンダリングしないでください。

デフォルト

• プロジェクト名：指定された値。指定がない場合はbasename "$PWD"。
• 出力先：現在の作業ディレクトリ。
• テンプレートチャンネル：stable。ソースのデフォルトブランチのHEADを選択するには--unstableを渡します。
• レンダリング元：リビジョンを正確に検証した後のインストール済みバンドル。明示的な--template-sourceで上書きできます。
• 記録される更新元：--template-sourceが明示されていない場合はgh:RobertDeRose/dstack。
• 記録されるベースラインリビジョン：解決された正確なコミットSHA。stableの場合は、選択されたリリースタグも報告します。
• デフォルトブランチ：main。
• Beads：プロジェクトリポジトリでネイティブの非ステルス初期化を実行します。ネイティブのBeadsは共同作業用コントロールをコミットし、Gitのoriginを検出し、Doltの配置を管理して、同期を設定します。bd initでは--skip-hooksを維持し、正確なコミットパスを検証して、マシン作成のREADME除外設定を適用し、プロジェクトフックを通してそのコミットを修正した後、bd hooks installを実行し、bd hooks list --jsonを検証します。bdが利用できない場合は、初期化とフックの検証が未完了であることを報告してください。--stealthで代用したり、ランタイム／データベースのパスをコミットしたりしないでください。
• ツール：レンダリングと任意のGit初期化の後、Linux/macOSのx64/ARM64向けにmise.lockを解決し、mise install --lockedでインストールしてから、リポジトリローカルのhkフックを別途インストールします。これらの手順にはmiseとネットワークアクセスが必要です。

実行

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/setup-project.py [project-name] \
  --purpose "<problem and outcome>" \
  --users "<intended users>" \
  --scope "<current supported scope>" \
  --boundaries "<key exclusions and ownership boundaries>" \
  --project-kind <kind> \
  --language-profile <profile> [...] \
  --repository-layout single-package

プロジェクト名は省略可能で、省略した場合はbasename "$PWD"がデフォルトになります。別の新しいディレクトリを対象にするには--destination <path>を、スターターREADMEを省略するには--delete-readmeを、最新のデフォルトブランチコミットを使うには--unstableを追加します。

開発専用のテンプレート上書きでも、同じ必須の概要フラグを指定します。

uv run <core-dir>/scripts/run-workflow.py <skill-dir>/scripts/setup-project.py "Reader Control Plane" \
  --purpose "Coordinate reader devices from one control plane." \
  --users "Operators responsible for reader fleets." \
  --scope "Provisioning and health workflows for supported readers." \
  --boundaries "Reader firmware and identity-provider administration remain external." \
  --project-kind service \
  --language-profile python \
  --language-profile typescript \
  --template-source gh:example/dstack-fork \
  --vcs-ref <reviewed-tag-or-commit>

セットアップヘルパーは、レンダリング後の初期化を自ら実行します。新しいプロジェクトにはscripts/bootstrap.py、scripts/migrate-legacy-workflow.py、移行ガイドを生成しません。ツール、Beads、ドキュメントのセットアップをスキップしつつ、正確な復旧コマンドを保持するには--skip-post-setupを使います。--no-git-initを指定した場合もツールは解決されますが、出力先がすでに独立したGitリポジトリでない限り、フックと共同作業用Beadsの初期化は未完了として報告されます。

検証

少なくとも以下を確認します。

.copier-answers.yml
AGENTS.md
.beads/formulas/dstack-feature.formula.toml
docs/book.toml
docs/src/SUMMARY.md
docs/src/planned-features.md
docs/src/features/_template/design.md
docs/src/features/_template/index.md
scripts/check-docs.py
scripts/setup-tooling.py
mise.toml
hk.pkl
.config/rumdl.toml

新しいプロジェクトに不適切なパスが存在しないことを確認します。

MIGRATION.md
scripts/bootstrap.py
scripts/migrate-legacy-workflow.py

.copier-answers.yml に、選択したソース、解決済みの正確なコミット SHA、および dstack_template_channel が記録されていることを確認します。 生成された AGENTS.md で、git commit -F <file> を使った実際の複数行コミットメッセージが必須とされていること（複数の -m フラグやエスケープされた \n は使用しないこと）、および main へのマージには git merge --ff-only のみが許可されていることを確認します。ヘルパーはセットアップの一環として uv run --no-project python scripts/check-docs.py を実行します。ツールの実行が成功すると、空でない mise.lock が作成され、--locked を指定してインストールし、mise x -- hk install --mise を実行します。Beads フェーズでは、ネイティブな init の amend コミットの後にのみ bd hooks install を実行し、bd hooks list --json で報告されるすべてのフックがインストール済みかつ最新であることを必須とします。mise、解決、インストール、hk フックのセットアップ、または Beads フックのセットアップが失敗した場合、スキャフォールドはそのまま維持され、JSON の tooling オブジェクトと beads_hooks オブジェクトに、個別の状態、長さを制限したエラーテキスト、および正確な復旧コマンドが報告されます。 以下を実行して復旧を再試行します。

python3 scripts/setup-tooling.py --json

Beads の検証を実行する前に、利用可能かどうかを確認します。

if command -v bd >/dev/null 2>&1; then
  bd prime
  bd list --type epic --label workflow:feature --all --json --limit 0
else
  printf '%s\n' 'Beads verification outstanding: install bd, initialize it, then run bd prime.'
fi

bd が利用できない場合は、bd prime を実行しないでください。その場合、セットアップは完了してもかまいませんが、戻り値では Beads の初期化と検証が未完了として列挙されている必要があります。

Copier の契約

• .copier-answers.yml と初期スキャフォールドをコミットします。
• 安定版のセットアップと更新では、最新の安定版タグを選択します。不安定版のセットアップと更新では、ソースのデフォルトブランチの HEAD を選択します。どちらの場合も、使用した正確なコミットを記録します。
• npx skills update は、インストール済みのスキル定義とスクリプトを更新します。
• /update-project は、明示的に上書きされない限り、記録されたチャンネルを維持します。
• .copier-answers.yml を手動で編集しないでください。

返却内容

プロジェクト名、スラッグ、目的、ユーザー、対象範囲、境界、種別、言語プロファイル、リポジトリのレイアウト、パッケージに関する正確な回答、レイアウトの事前確認結果とレンダリング先、保存先、テンプレートチャンネル、選択した ref、記録された正確なコミット、スキルのバージョン、Git の結果、Beads の結果、ドキュメントの検証結果、tooling と beads_hooks の完全なステータス、未完了の復旧コマンド、および次の /plan-features アクションを報告します。セットアップが /update-project に振り分けられた場合は、ユーザーの同意に関する判断を報告し、セットアップを実行したと主張しないでください。