handoff

引き継ぎ

別のマシンに届くのは、GitHub 上のものと Handoffs フォルダー内のものだけです。引き継ぎドキュメントに会話の内容を記録し、その隣にある handoff_map.json で各プロジェクトのアクティブな引き継ぎを指定します。別のマシンでは lets-go スキルがそれを再開し、その後クリアします。未マージ作業のアラートにより、このマシンに取り残される作業を把握できます。

開始時に伝えること：「引き継ぎスキルを使って、このセッションを引き継ぎます。」

シェルスニペットは bash（Windows では Git Bash）で実行します。マップの読み書きは、必ず node .agents/skills/handoff/handoff-map.mjs 経由で行い、手作業では変更しません。すべてのマシン上のすべてのリポジトリで共有されるためです。各コマンドは JSON を出力し、このマシンの転送手段で必要な場合は、ファイルをクラウドとの間で移動します。

ユーザーが引数を渡した場合は、次のセッションの目的が示されています。それに合わせてドキュメントを作成してください。

0. 設定

• リポジトリ： このスキルは docs/agents/handoffs.md と docs/agents/workspace.md を読み取ります。.agents/skills/handoff/settings/README.md に従ってこれらを読み、不足しているものがあれば補完してください。定義ファイルはその隣にあります。
• マシン： config に configured: true と表示されるまで、.agents/skills/handoff/machine-config.md に従ってください。Handoffs フォルダーを設定できない場合は、代わりに OS の一時ディレクトリにドキュメントを作成し、それが別のマシンには届かないことをユーザーに伝え、ステップ 2 の後で停止してください。完了処理まで進めると、誰も引き継げないドキュメントが残ります。

1. 未マージ作業を監査し、通知する

origin/main にないものは、少なくともプッシュされない限り、別のマシンからは見えません。

git fetch origin --prune
git status --porcelain --untracked-files=all
git stash list
git worktree list
git for-each-ref refs/heads --format='%(refname:short) %(upstream:short) %(upstream:track)'
git branch --no-merged origin/main
git branch -r --no-merged origin/main
gh pr list --author @me --state open --json number,title,headRefName,url

続いて、Workspace status command を実行します。追加の各ワークツリーでは git status --porcelain を実行し、Private companion がチェックアウトされている場合は git -C <companion> status --porcelain と git -C <companion> log --oneline @{u}..HEAD も実行します。

--no-merged は、スカッシュマージされたブランチを過剰に検出します。表示されたブランチごとに gh pr list --state merged --head <branch> --json number,headRefOid を実行してください。ブランチの先端がマージ済み PR の headRefOid と一致するか、その祖先である場合（git merge-base --is-ancestor <branch> <headRefOid>）、その作業は main に含まれています。対象から除外してください。

残ったものを次の 2 つのグループに分類します。

• ローカルのみ — 別のマシンからは見えません。未コミットまたは未追跡の変更、スタッシュ、未プッシュのコミット、アップストリームのないブランチ、およびコンパニオン内の同様のものです。
• プッシュ済み、未マージ — 到達可能ですが、main には含まれていません。プッシュ済みのブランチとオープンな PR が該当します。

いずれかのグループに項目がある場合は、ドキュメントを書く前に、見出し ⚠ Work not merged to main の下でユーザーにすぐ通知してください。 各項目を 1 行で示し、リポジトリ、ブランチまたはパス、グループを記載します。ローカルのみの作業はプッシュしない限り別のマシンには届かないことを明確に伝え、プッシュするかどうかを尋ねてください。完了済みのブランチには ship スキルを提案してください。この通知は情報提供であり、処理を止めるものではありません。どちらの場合も続行してください。報告する項目がない場合は、「すべての作業が origin/main にあります。」と伝えてください。

2. ドキュメントを作成する

node .agents/skills/handoff/handoff-map.mjs get --key <Map key>

• conflicts が空でない場合 — 続行する前に、どのコピーが最新のマップかユーザーに確認します。
• file が null でない場合 — このリポジトリに関する以前の引き継ぎが、まだ受け取られていません。読み込み、現在も有効な内容を引き継ぎ、レポートでそのファイルを旧版として示します。ファイルはそのまま残します。

ファイル名を選びます（ユーザーが引数を指定した場合は --topic <slug> を渡します）。

node .agents/skills/handoff/handoff-map.mjs name --key <Map key>

出力された path に、別のマシンを使う初見の読者向けのドキュメントを直接書きます。 以下のセクションを、次の順序で記載します。

1. 現在の状態 — リポジトリ、ブランチ、origin/main のコミット、最新のリリースタグ、ワークツリー、プッシュ後のコンパニオンの状態。
2. 未マージの作業 — ステップ 1 の一覧をそのまま記載するか、「なし — すべて origin/main にあります。」
3. このセッションで行ったこと — 説明文ではなく、成果とその記録（PR、issue、コミット）。
4. 次のステップ — 具体的な手順を順番に記載します。最初の手順は、確認を求めずに開始できるものにします。
5. 未決事項 — ユーザーからの回答が必要な事項。
6. マシン固有の知識 — エージェントのメモリとセッションのスクラッチパッドはこのマシンに残ります。次のステップに必要な事実や注意点を書き出します。
7. 推奨スキル — 次のエージェントが呼び出すべきスキルと、それぞれの実行ステップ。

Extra document content に記載されている内容をすべて追加します。仕様、ADR、issue、PR、コミット、差分など、ほかの記録にすでにある内容は繰り返さず、パスまたは URL で参照します。このドキュメントはリポジトリを離れて個人用クラウドドライブに保存されます。ホームディレクトリは <home> と表記し、シークレット、トークン、パスワード、個人データは記載しません。コンパニオンの内容や非公開の issue は引用せず、リンクします。

ファイルを読み返したときにドキュメント全体が確認できれば、このステップは完了です。

3. アクティブにする

node .agents/skills/handoff/handoff-map.mjs set <file> --key <Map key>

CLI ミラーでは、ドキュメントをプッシュし、マップを最新の状態で取得し、このリポジトリのエントリを書き込み、マップをプッシュして、クラウド上のコピーを読み返します。別のセッションが間に書き込んだ場合は再試行します。出力の current が <file> であり（CLI ミラーでは verified が cloud であることも）、完了条件です。previous が null でなく、かつ <file> と異なる場合は、旧版の引き継ぎです。フォルダーに残し、レポートに記載します。

4. end-session で終了する

end-session スキルを、引数 invoked by handoff; document at <path> を指定して呼び出します。ハーネスがスキルを呼び出せない場合は、.agents/skills/end-session/SKILL.md を読み、その手順に従います。作業は別のマシンで続くため、end-session によってこのチェックアウトが main に戻される場合があります。それ以外の承認ゲートも引き続き適用されます。

end-session により、ドキュメントに記載した事実（作業のプッシュやコミット、issue のクローズやオープン、ブランチやワークツリーの削除、未決事項のユーザーによる決定）が変わった場合は、ドキュメントを修正し、新しいバージョンを（マップを除いて）送信します。

node .agents/skills/handoff/handoff-map.mjs push <file>

end-session の後、現在の状態と未マージの作業のすべての項目が真であれば、ドキュメントは完成です。

5. レポート

• ドキュメントのパスと、現在そのドキュメントを指しているマップエントリ（previous → current）。
• end-session 自身のレポート。
• ステップ 1 の監査を最後にもう一度実行します。長い終了処理の後も最新状態を維持できるよう、現在の ⚠ main に未マージの作業 の一覧、または「未マージの作業はありません — 別のマシンでは origin/main から開始できます。」を記載します。
• 注意事項：別のマシンで、このリポジトリの lets-go スキルを実行すること。同期フォルダーなら、1 分ほどでドキュメントが届きます。CLI ミラーでは、すでにクラウドにあります。