remote-project-control

リモートプロジェクトの操作

操作を開始する前に — 必須

1. 対象範囲を確認する：git rev-parse --git-common-dir と --show-toplevel を実行します。project-control-root レイアウトでは、<ProjectName>/ と <ProjectName>/code/ はそれぞれ独立したリポジトリです。個別に調べてください。
2. プロジェクトルートに memory/BRIEFING.md がある場合は、プロジェクトメモリを読みます。
   • memory/BRIEFING.md — プロジェクトの状態を簡潔にまとめたスナップショット
   • memory/project-conventions.md — SSH ラッパー、サーバーパス、このプロジェクトの対象範囲の制約など、現在有効な規約
3. ワークツリー内にいる場合：まず .agent/worktree-status.md を読みます。進行中のサーバー状態は、ルートの memory/ ではなく、ここに記録してください。
4. 変動する状態（キュー、サーバー負荷、ジョブの状態）は最新の確認が必要なものとして扱います。これらの値について、セッションメモリにキャッシュされた情報をもとに操作しないでください。

この手順を省くと、古いサーバー状態や誤った環境パスを使用したり、プロジェクト固有の SSH ラッパー規約に違反したりするおそれがあります。

---

コードはローカルで編集しながら、SSH 経由で 1 台以上のサーバー上で実際に実行するプロジェクトの操作を支援します。まずプロジェクトメモリを整備してから、ローカル、Git リモート、サーバーでの安全な操作を調整してください。

このスキルで使用する用語：

• local：ユーザーのローカル開発マシン。通常はエージェントが実行されている Mac です。
• remote または git remote：GitHub や GitLab などの Git ホスティングサービス上のリモート（例：origin）です。
• server：quest、ibex-vscode、epfl-haas など、SSH で接続する実行マシンまたはクラスターです。

このスキル名は歴史的なものです。プロジェクトメモリやユーザー向けの概要では、SSH／HPC／RunAI の実行環境には server を優先して使用し、既存のフィールド名を引用する場合を除き、remote は Git リモートを指す用語として使用してください。

サーバー上の実行状態を、プロジェクトレベルの実験、エビデンス、アクション、またはワークツリーの状態と関連付ける場合は、このスキルを research-project-memory と組み合わせてください。ジョブを送信した後に、生ログをコンテキストに取り込まず、軽量な進捗確認や成果物の範囲を限定した監視が必要な場合は、run-status-monitor と組み合わせてください。

スキルのディレクトリ構成

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── memory-model.md
│   ├── operations.md
│   └── ssh-command-wrappers.md
├── scripts/
│   ├── remote-cmd
│   └── remote-bash
├── template_manifest.json
└── templates/
    ├── infra/remote-projects.yaml
    ├── docs/ops/current-status.md
    ├── docs/ops/decision-log.md
    └── agent/local-overrides.yaml

段階的な読み込み

• 常に references/memory-model.md を読みます。
• ユーザーが調査、同期、実行、監視、または成果物の取得を希望する場合は、references/operations.md を読みます。
• ループ、シェル変数、コマンド置換、パイプ、グロブ、find、awk、または複数行のロジックを含む SSH コマンドを組み立てる前に、references/ssh-command-wrappers.md を読みます。
• 対象プロジェクトにメモリファイルを初期作成する際は、templates/ を信頼できる情報源として使用します。
• リポジトリに memory/ がある場合は、確認済みのサーバー実行情報を research-project-memory のボードに要約し、サーバーマニフェストと重複させないでください。

中核となる原則

• メモリは初期コンテキストであり、実行時の正確な情報ではありません。
• 安定した共有情報はリポジトリに、マシン固有の非公開情報はローカルオーバーライドファイルに保存します。
• 変動する状態は、対応する前に確認します。
• ローカルからサーバーへのコード同期には、GitHub／GitLab または設定済みの Git リモートを優先します。プロジェクトで明示的に採用している場合を除き、場当たり的なソースのコピーは行いません。
• ユーザーから明示的な承認を得ずに、サーバー側で破壊的な git コマンドを実行してはいけません。
• gh、git、ssh、curl、スケジューラー／API コマンドのネットワークアクセスは、個別の障害要因として扱います。サンドボックス化されたエージェントの実行環境で DNS、タイムアウト、接続のエラーが発生した場合は、認証情報や設定を調査する前に、ネットワーク権限を付与して再試行します。
• GitHub／GitLab API へのアクセスは、通常の git SSH アクセスとは別に扱います。git push は成功しても、gh repo create、gh repo view、gh repo fork は gh が認証されていないために失敗することがあります。
• GitHub／GitLab API のネットワークアクセスは、認証とは別に扱います。サンドボックス化されたエージェントの実行環境では、ネットワーク権限を付与してコマンドを再実行しない限り、gh が api.github.com に接続できないことがあります。
• GitHub Projects は Git リモートではなく、GitHub API の操作として扱います。gh project ... には project スコープのトークンが必要です。スコープがない状態でプロジェクトボードのコマンドを実行する前に、gh auth refresh -s project でトークンを更新します。
• プロジェクト管理ルートを使う構成では、ルートリポジトリとコンポーネントリポジトリを個別に確認します。<ProjectName>/ と <ProjectName>/code/ は、それぞれ異なるリモートと権限を持つ独立した Git リポジトリである場合があります。
• 単純な argv 形式のサーバーコマンドには remote-cmd を、スクリプト、ループ、またはシェル構文を含むコマンドには remote-bash を使います。下記の 禁止されている SSH パターン を参照してください。

禁止されている SSH パターン

トランスクリプトやエージェントのコマンド出力で、次のパターンを直接組み立ててはいけません。

アンチパターン	代わりに使うもの
ssh <alias> "cd <path> && <cmd>"	remote-cmd <alias> <repo> -- <cmd>
ssh <alias> "<cmd> $VAR"（シェル変数）	remote-cmd <alias> <repo> -- <args>
ssh <alias> "<cmd> | <cmd>"（パイプ／ループ／find／awk）	remote-bash <alias> <repo> <script>
ssh <alias> "<cmd1> ; <cmd2>"（連結）	remote-bash <alias> <repo> <script>
ssh A "ssh B '<nested cmd>'"（入れ子のワンライナー）	remote-bash 経由で呼び出す、プロジェクトローカルの scripts/ops/ ラッパー

例外：シェル構文を含まない、引数なしの単語 1 つだけのコマンドは使用できます（ssh <alias> "pwd"、ssh <alias> "hostname"）。

理由：ローカルシェルは、SSH コマンドが送信される前に $VAR、~、グロブ、引用符を展開し、意図したサーバー側のコマンドを気付かないうちに破損させることがあります。ラッパーを使えば正しく引用符を処理でき、トランスクリプトもすっきりします。

メモリファイル

このスキルでは、役割の異なる次の 4 つのプロジェクトメモリファイルを管理します。

• infra/remote-projects.yaml：ローカルリポジトリのパス、Git リモート／ブランチ、サーバー上のリポジトリの対応関係、スケジューラーの種類、起動モード、キーのパス、安全ポリシーなどの安定した共有情報
• docs/ops/current-status.md：プロジェクトの現在のフェーズに関する作業用メモリ。アクティブなブランチ、重点事項、最後に確認したジョブ、未解決の問題、次の手順を含みます。
• docs/ops/decision-log.md：安定したワークフロー上の決定を行った理由を記録する、長期保存用の説明
• .agent/local-overrides.yaml：ユーザーのマシン、ssh エイリアス、ユーザー名、非公開パスに関する任意の非公開オーバーライド。このファイルは通常、gitignore の対象にします。

ファイルが 1 つ以上見つからない場合は、プロジェクトのコンテキストを一から推測する前に、同梱テンプレートからファイルを作成します。

ステップ 1 — 状況を確認してメモリを読み込む

1. プロジェクトのルートを検出します。

git rev-parse --show-toplevel 2>/dev/null || pwd

2. 既存のメモリファイルがあれば読み込みます。

• <project-root>/infra/remote-projects.yaml
• <project-root>/docs/ops/current-status.md
• <project-root>/.agent/local-overrides.yaml
• <project-root>/docs/ops/decision-log.md

3. infra/remote-projects.yaml が存在しない場合は、このスキルのテンプレートを使ってプロジェクトメモリを初期設定します。重要な項目に限って、次の情報を確認します。

• プロジェクト名
• ローカルリポジトリのルート
• デフォルトのサーバー名
• ssh エイリアス
• サーバー側のリポジトリのルート
• スケジューラーの種類
• デフォルトの起動モード
• 環境の有効化コマンド

4. .agent/local-overrides.yaml が存在せず、プライベートなオーバーライドが明らかに必要な場合は、ファイルの作成を提案し、.agent/ を .gitignore に追加することを推奨します。

5. プロジェクトがコンポーネントリポジトリを含む制御ルートと思われる場合は、Git リモートが 1 つだけだと決めつけず、関連するリポジトリをそれぞれ個別に調べます。

git -C <project-root> remote -v
git -C <project-root>/code remote -v
git -C <project-root>/paper remote -v

あるリポジトリにリモートがないからといって、別のリポジトリにもリモートがないとは限りません。

ステップ 2 — セッション開始時の概要を作成する

読み込んだファイルを統合し、簡潔なプロジェクトコンテキストの概要を作成します。実質的なリモート作業に着手する前に、必ず簡潔な開始時の概要をユーザーに提示します。

把握できている場合は、次の情報を含めます。

• プロジェクト名
• ローカルリポジトリのルート、現在のブランチ、短縮コミットハッシュ、作業ツリーに変更があるかどうか
• デフォルトのサーバーとサーバー側のリポジトリのルート
• 同期に使用する Git リモート名とブランチ
• スケジューラーの種類とデフォルトの起動モード
• 環境の有効化コマンド
• 主要なデータ、チェックポイント、スクラッチ、ログのルート
• 現在の重点事項
• 最新の既知のジョブ
• 未解決の問題
• 次に予定しているステップ
• 不足している必須項目

ステップ 3 — 操作の前に変動する状態を再検証する

リモート操作を行う前に、前回のセッション以降に変わっている可能性のある状態を確認します。

最低限、次の状態を確認します。

git rev-parse --short HEAD
git branch --show-current
git status --short

選択したサーバーでは、設定済みの ssh_alias と remote_repo_root または server_repo_root を使って、サーバー側のリポジトリと Git の状態を確認します。

ssh <ssh-alias> "cd <remote-repo-root> && pwd && git branch --show-current && git rev-parse --short HEAD && git status --short"

確認を繰り返す場合は、より安全なラッパーの同等コマンドを優先します。

remote-cmd <ssh-alias> <remote-repo-root> -- git status --short
remote-bash <ssh-alias> <remote-repo-root> scripts/ops/status.sh

リクエストにジョブの投入や監視が含まれる場合は、サーバー上のスケジューラーツールと関連するログまたは出力パスも確認します。

ステップ 4 — リクエストを分類して実行する

次のフローから 1 つを選び、references/operations.md の詳細なガイダンスに従います。

• bootstrap：テンプレートからメモリファイルを作成または修復し、必須の最小限の項目を入力します
• inspect：ローカルとサーバーの Git 状態を比較し、パス、環境の有効化、スケジューラーの利用可否を確認して、現状を要約します
• git-remote-setup：GitHub/GitLab リポジトリを確認または作成し、リモートを設定し、上流リポジトリをフォークし、任意で GitHub Projects をリンクするか、Git リモート経由のローカルからサーバーへの同期を準備します
• sync-code：ローカルコミットを準備し、設定済みの Git リモート経由でプッシュして、非破壊的なファストフォワードプルのみでサーバーのリポジトリを更新します
• run-job：サーバーのコンテキストを使用してジョブを安全に送信します。新しい再現可能なジョブスクリプトが必要な場合は、このスキルで環境を確立した後に run-experiment を使用します
• interactive-session：適切な salloc、srun、または同等のコマンドを準備し、設定済みの環境を有効化して、以降のコマンドをサーバーのリポジトリから実行します
• monitor：キューの状態を確認し、設定済みのログルートからログの末尾を表示します
• artifacts：リモートのチェックポイント、出力、ログを特定します。ユーザーから明示的な依頼がない限り、大容量データを一括転送しないでください
• closeout：セッション終了時にプロジェクトのメモリを更新します

ランタイムから SSH コマンドを直接実行できない場合でも、このスキルを使用します。正しい順序で正確なコマンドを生成し、前提条件を説明して、メモリファイルを最新の状態に保ちます。

GitHub API を使用する gh 操作（gh repo ... や gh project ... を含む）の前に、次を実行します。

gh auth status

エラーは慎重に解釈してください。

• 出力に api.github.com または github.com に接続できないと表示される場合や、インターネット接続の確認を求められる場合は、まずネットワーク／サンドボックスへのアクセスの問題として扱います。ユーザーに再ログインを求める前に、ネットワーク権限を付与して同じ gh チェックを再実行してください。
• gh auth status でネットワークにアクセスできる状態でも、無効なトークン、アカウントの欠如、ログイン失敗が報告される場合は、GitHub API フローを中止し、gh auth login -h github.com で再認証するようユーザーに伝えてください。
• どちらのエラーも、リポジトリの作成失敗、Git リモートの失敗、SSH キーの失敗、サーバーの問題として解釈しないでください。

GitHub Projects について：

• gh project create、gh project view、gh project link、gh project item-*、または gh project field-* の前に、gh auth status で project スコープが表示されることを確認してください。
• スコープがない場合は、gh auth refresh -s project を実行するか、ユーザーに実行を依頼してください。
• 通常のサンドボックス環境での gh auth status が失敗しても、ネットワーク／キーチェーンへのアクセスを有効にしたチェックが成功する場合は、通常の失敗を実際のログアウトではなく、サンドボックスまたは Keychain へのアクセスの問題として扱います。
• コードリポジトリがプロジェクト管理ルートのレイアウトに属している場合は、GitHub Project の URL／番号をルートの memory/project.yaml に記録してください。

他のコマンドにも同じネットワーク優先の分類を適用してください。

• git fetch、git push、git pull、git ls-remote：DNS または接続の失敗は、ネットワーク権限を付与して再実行するまでは、ネットワーク／サンドボックスへのアクセスの問題として扱います。
• ssh <server>：ホスト名解決、タイムアウト、またはネットワーク到達不能は、想定されるネットワーク権限と VPN の状態で再実行するまでは、ネットワーク／VPN／サンドボックスの到達性の問題として扱います。
• curl、パッケージマネージャー、スケジューラー／API CLI：接続の失敗だけでは、認証情報やサーバー設定に問題があるとは判断できません。

ステップ 5 — 適切なメモリレイヤーに書き戻す

新しい情報の信頼性が確認できたら、適切なファイルに保存します。

• 安定したマッピングとポリシーの変更 -> infra/remote-projects.yaml
• 現在のブランチ、最新の既知のサーバージョブ、現在のフォーカス、ブロッカー、次のステップ -> docs/ops/current-status.md
• 長期的に有効なワークフローの根拠 -> docs/ops/decision-log.md
• ユーザー固有の ssh エイリアス、ユーザー名、プライベートパス -> .agent/local-overrides.yaml

リポジトリで research-project-memory も使用している場合は、プロジェクト間で共有する参照情報のみを書き込みます。

• memory/evidence-board.md：関連する EXP-### の検証済みジョブ／実行参照
• memory/action-board.md：監視、アーティファクト取得、再実行、レポートのアクション
• memory/current-status.md：最新の検証済みサーバー実行の概要と、次の検証ステップ
• worktree の .agent/worktree-status.md：ブランチ／worktree の目的に関連するサーバー実行ステータス

一時的なスケジューラー出力や単発のシェルコマンドの結果を、安定したマニフェストに書き込まないでください。

ステップ 6 — 重要なセッションの終了時には必ずクローズアウトする

終了する前に、セッションによってプロジェクトの状態が実質的に変わった場合は、docs/ops/current-status.md を更新します。次の情報を記録してください。

• ユーザーが作業を再開するブランチまたはコミット
• ローカルで変更した内容
• Git リモートにプッシュし、サーバーリポジトリに取り込んだ内容
• 最新の既知の送信済みまたは実行中のジョブ
• 次に確認する価値のあるログまたは出力のパス
• 次のセッションで実行する具体的なアクション

新たに安定した運用方法を確立した場合は、docs/ops/decision-log.md に短い項目を追加します。

プロジェクト固有の新しい SSH／リモート接続の規約（例：新しいラッパーエイリアス、サーバーパス、RunAI プール、スケジューラーフラグ）を確立した場合は、memory/project-conventions.md の ssh または compute カテゴリに記録します。サーバーインフラの変更によって規約が古くなった場合は、その理由を添えて Expired に移動します。

プロジェクトに memory/current-status.md がある場合は、リモートのステータス全文をコピーせず、簡潔なコンポーネント間の参照情報を記載して更新します。

ブートストラップ時の配置先

プロジェクトをブートストラップする際は、templates/ から次のファイルを配置します。

• templates/infra/remote-projects.yaml -> <project-root>/infra/remote-projects.yaml
• templates/docs/ops/current-status.md -> <project-root>/docs/ops/current-status.md
• templates/docs/ops/decision-log.md -> <project-root>/docs/ops/decision-log.md
• プライベートなオーバーライドが必要な場合：templates/agent/local-overrides.yaml -> <project-root>/.agent/local-overrides.yaml

ユーザーが明示的に上書きを求めない限り、既存のファイルは保持してください。