mstack-handoff

mstack ハンドオフ

このホストでも別のホストでも、新しいエージェントセッションが現在の作業を停止した場所から正確に続けられるように、1つのファイルを作成します。また、そのようなファイルがあれば、そこから作業を再開します。作業はハンドオフの作成だけです。残りの作業は完了せず、ファイルを書き込んで確認した時点で停止します。

ファイルには、ほかのファイルには記載されていない内容だけを含めます。未コミットの作業、進行中の判断、これから必要なゲート、次に実行するコマンドです。それ以外（仕様、計画、progress.md、イシュー、プルリクエスト、コミット）は、パスまたはリンクとして記載します。

ホストツール

役割	Claude Code	Codex
質問ツール	AskUserQuestion	チャットで番号付きの質問をして、返答を待つ
スキルフォルダー	このスキルの読み込み時に表示されたベースディレクトリ	この SKILL.md があるフォルダー
ネットワークが必要なコマンド（gh）	直接実行	サンドボックスでネットワークが無効になるため、承認済み（昇格）コマンドとして実行

このスキルのファイル

ファイル	使用時期
references/handoff-template.md	手順4、および再開時
scripts/check-handoff.mjs	手順5

基本ルール

1. ハンドオフ中は何も変更しません。 ハンドオフのために、コミット、スタッシュ、プッシュ、プル、リベース、リセット、プルリクエストの作成、トラッカーへの投稿をしてはいけません。未コミットの作業はそのまま残し、ファイルに記載します。
2. 根拠を示すか、「仮定」と明記します。 このセッションで確認したステータスは、確認方法を記載します。それ以外は、次のセッションがファイルの内容を信頼できるよう、「仮定」と明記します。
3. ゲートをグリーンとみなせるのは、最後の編集後にこのセッションで合格した場合だけです。 正確なコマンド、実行時の HEAD、結果行を記載します。後続の編集より前に合格したゲートは、再度実行が必要です。
4. 秘密情報や個人情報は記載しません。 秘密情報は値を貼り付けず、名称だけを記載します。
5. 調べれば分かることは質問しません。 コンテキストが不足しているときにハンドオフすることも多いため、質問できるのはファイルの保存先だけです。ユーザーが指定しておらず、既定の保存先が適さない場合に限ります。

ハンドオフを作成する

1. 安全な状態で停止する

現在の小さな手順を完了するか、取り消して、リポジトリの状態を説明できるようにします。新しい作業は始めません。起動したサブエージェント、レーン、バックグラウンドジョブは停止するか、完了するまで待ちます。まだ実行中のものがあれば、ワークツリー、ブランチ、ジョブまたはスレッド ID、実行内容を記録します。元に戻せない手順は実行しません。

2. リポジトリのスナップショットを取る

リポジトリのルートから次のコマンドを実行し、出力を手順4で使えるように保管します。どれも読み取り専用です。

git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git rev-parse --abbrev-ref --symbolic-full-name @{u}   # fails when there is no upstream: record "none"
git status --porcelain=v1 -b -uall                     # the uncommitted work, file by file
git stash list                                         # report existing stashes; never create one
git worktree list --porcelain
node <skill-folder>/scripts/check-handoff.mjs --fingerprint <repository root>   # the Tree fingerprint for the identity line

フィンガープリントは最後に、最終編集後に取得します。未コミットの変更と未追跡ファイルをハッシュ化するため、git status の表示に変化がなくても、内容が変わればフィンガープリントも変わります。

GitHub では、gh pr list --head '<branch>' --state all --json number,url,state,isDraft を使ってプルリクエストを確認します（ブランチ名はシェルで展開されないよう、シングルクォートで囲みます）。該当するものがなければ [] が出力されます。ブランチにプルリクエストがない場合に失敗するため、ここでは gh pr view を使わないでください。別のホストでは、その CLI または接続済みツールを使うか、「不明」と記載します。

3. 残りの状態を収集する

1. スコープ。 対象となる課題またはタスクと、それぞれの状態です。作業がワークフローの実行である場合は、そのステータステーブルをコピーします。mstack-plan の実行である場合は、タスクテーブルをコピーする代わりに、プランのフォルダーとその progress.md を示し、続行方法としてプランの execute-plan.md を記載します。
2. ゲート。 作業の完了を判定するすべてのチェック（テスト、型チェック、Lint、ビルド、プランまたはリポジトリの完了チェックリスト）です。それぞれを、今回のセッションで証拠をもって合格した「グリーン」か、正確なコマンドと理由を記載した「未実施」にします。
3. 決定事項。 3 種類に分けます。ユーザーが承認した事項（承認箇所も記載）、ユーザーの判断待ちの事項（質問と推奨案）、そして自分で判断した事項（理由も記載）です。
4. 注意点。 次のセッションで見落としやすいことです。
5. 推奨スキル。 次のセッションで読み込むスキルを名前で示します。最初に実行していた mstack スキル、その後に未解決のバグがあれば mstack-diagnose などを記載します。

4. ファイルを書く

references/handoff-template.md に従い、セクションを順番どおりに記載します。「Start here」を最初にします。

ファイルはリポジトリの外に書き込み、誤ってコミットされないようにします。ユーザーがパスを指定している場合はそのパスを使用します。指定がない場合は ~/.mstack/handoffs/<repository folder name>/<yyyy-mm-dd-hhmm>-<slug>.md を使用します（Windows の場合は %USERPROFILE%\.mstack\handoffs\ の下）。システムの一時フォルダーは既定で使用しないでください。ホストによっては再起動のたびに削除されるためです。シェルによる展開を防ぐため、echo やヒアドキュメントではなく、ファイルツールを使って書き込みます。

5. ファイルを確認する

node <skill-folder>/scripts/check-handoff.mjs <handoff-file>

このコマンドは、タイトル、リポジトリの現在のブランチ・HEAD・Tree フィンガープリントと照合した識別行、空のセクションがないこと、セクションとその順序、グリーンゲートの行、テンプレートのプレースホルダーの残存、シークレットらしき文字列、そしてファイルがリポジトリ内の未無視ファイルではないことを確認します。出力された行をすべて修正し、再度実行します。リポジトリにシークレットスキャナー（たとえば gitleaks）がインストールされている場合は、ファイルに対しても実行します。node がない場合は、ファイルを読んで同じ点を確認し、その旨を記載します。

次に、次のセッションで読む人になったつもりで、ファイル全体を一度読みます。推測にすぎない内容は確度を下げ、初見の読者が手順を追えない箇所は補います。

6. 引き継いで終了する

次の内容を返信します。

1. ファイルの絶対パス。
2. 作業ツリーにのみ保存されているもの（未コミットのパス）と、コミット、スタッシュ、プッシュのいずれも行っていないこと。
3. 再開地点を 1 文で記載します。
4. ユーザーが求めた場合、または次のセッションが別のホストで実行される場合は、references/handoff-template.md の貼り付け用プロンプトを記載します。

その後は停止します。このセッションでは作業を続けないでください。

ハンドオフから再開する

ユーザーがハンドオフファイルからの続行を求めた場合：

1. 何かを実行する前に、ファイル全体を読みます。
2. node <skill-folder>/scripts/check-handoff.mjs <handoff-file> --resume で確認します。ファイルに破損や不備がある場合は失敗し、ブランチ、HEAD、Tree フィンガープリントが記録時と同じかどうかが報告されます。
3. 「Start here」の手順を順番に実行します。変更がある場合は、「If the state changed」セクションに従います。ブランチが異なる場合や履歴が書き換えられている場合は、ユーザーが判断するまで停止します。HEAD が先に進んでいる場合、または未コミットの作業が変更されている場合は、すべてのグリーンゲートを未実施に戻します。
4. ファイルを前回のセッションの記録として扱います。完了済みと記載された作業をやり直さず、最初のゲートを再実行してから、その結果を信頼します。また、「assumed」と記載された主張を土台にする前に、必ず再確認します。
5. mstack-plan フォルダーが示されている場合は、そのプランの execute-plan.md と再開ルールに従います。プランのタスクでは、それらが優先されます。
6. 前回のセッションがどこで停止したか、何を再確認したか、再開地点をユーザーに伝えてから、推奨されているスキルを使って作業を続けます。