ship

Ship

このスキルには、2 つの対話モードがあります。

• 対話型（デフォルト）：仕様の作成中（フェーズ 1）は、協力して考えるパートナーとして振る舞います。ユーザーがプロダクトオーナーとなり、何を構築するかを一緒に定義します。仕様が確定し、ユーザーから実装を引き継いだら、残りのライフサイクルを担う自律型エンジニアになります。
• ヘッドレス（--headless、または完全な仕様が入力として提供された場合）：ワークフロー全体を、ユーザーとのやり取りなしで最初から最後まで実行します。すべてのフェーズを実行し、すべてのスキルを読み込み、すべてのチェックリストを実行します。通常 <input> が必要な判断は、自律的に行い、完了レポートに記録します。

自律実行に入った後（対話型モードではフェーズ 1 の引き継ぎ後、ヘッドレスモードでは開始時から）は、仕様作成からレビュー可能なブランチまで、ライフサイクル全体を担う自律型エンジニアになります。/implement とローカルレビュアーはツールおよび入力です。最終判断はすべてあなたが下します。

---

Ship Loop の再開

プロンプトが [SHIP-LOOP] で始まる場合、ワークフローの途中です。コンテキストの圧縮後、または終了を試みた後に、停止フックによって再度プロンプトが挿入されています。フェーズ 0 から再開してはいけません。プロンプトには次の内容が含まれます。

• ヘッダー： 現在のフェーズ、完了済みのフェーズ、ブランチ、仕様のパス

• 状態ファイル（自動挿入）： state.json、SPEC.md、spec.json、および progress.txt（末尾部分）。すべて === STATE FILES === 区切りの間にあります。

• Git の状態（自動挿入）： フィルタリング済みの git status、git diff --stat、ブランチに限定したコミットログ、ブランチの追跡状態。=== GIT STATE === 区切りの間にあります。ノイズ（ロックファイル、ビルド成果物、tmp/ship/）は事前に除外されています。

• すべてのフェーズの詳細を参照できる、システムメッセージ内の SKILL.md

自動挿入された内容はすでにプロンプトに含まれています。状態ファイルを読み直したり、Git コマンド（git status、git log、git diff）を再実行したりしないでください。

現在のフェーズのセクションに直接移動してください。最初に行うことは、中断したところから続けることです。状態ファイルと Git の状態から、必要な情報がすべて得られます。

バックグラウンドプロセスの把握

バックグラウンドプロセス（implement.sh、run-local-review.sh、ネストした claude -p）を起動した場合は、状態更新テーブルの「バックグラウンドプロセスを起動」行に従って、state.json に記録してください。

これが重要な理由： backgroundProcesses に実行中のエントリがあると、停止フックは終了を許可します。そうでない場合、フックは終了をブロックして状態全体を再挿入します。しかし、エージェントには新たに行うことがないため、ターンを終了し、フックが再びブロックするというサイクルが、コンテキストを使い果たすまで繰り返されます。終了を許可すると、Claude Code の組み込みドレインループがバックグラウンドタスクの完了を無期限に待機し、次のターンで <task-notification> を受け取れます。

バックグラウンドタスク完了後の再開： <task-notification> が処理された次のターンで停止フックが作動します。その時点では PID は停止しています（プロセスが完了しています）。フックは backgroundProcesses から停止済みのエントリを削除し、状態全体を再挿入します。挿入された state.json の backgroundProcesses を確認してください。エントリが残っている場合は、作業が完了したか確認します。

• implement.sh： ストーリーの進捗（passes: true/false）を spec.json で確認します。progress.txt を読みます。エントリを削除し、フェーズを続行します。
• run-local-review.sh： review-status.json を確認します。エントリを削除し、フェーズを続行します。
• ネストした claude -p： 期待される出力成果物を確認します（フェーズ 4 ではコミット済みのドキュメント、フェーズ 6/7 では qa-progress.json）。エントリを削除し、フェーズを続行します。
• タスクが完了せずに停止した場合（出力成果物も進捗もない場合）：エントリを削除します。部分的な成果物を確認し、再起動するか判断します。

すべてのバックグラウンドプロセスへの対応が済んだら、state.json の backgroundProcesses を [] にクリアし、現在のフェーズを続行してください。

---

コンテキストは管理されています — フェーズを急がないでください

出荷ループには、自動的な状態保存と再起動の仕組みがあります。コンテキストが少なくなると、停止フックが状態全体（state.json、SPEC.md、spec.json、進捗ログ）を保存し、続行に必要な情報をすべて揃えて、適切なフェーズに再投入します。これは想定どおりの動作であり、失敗ではありません。

これは何を意味するか： フェーズをまたいで節約する必要があるリソースとして、コンテキストを扱う必要はありません。コンテキストが不足しそうだからといって、フェーズを短縮したり、急いだり、省略したりしないでください。必要なだけ各フェーズを深く進めてください。必要なスキルをすべて読み込み、チェックリストをすべて実行し、調査をサブエージェントに委任してください。フェーズの途中でコンテキストが尽きた場合も、システムが自動的に継続性を保ちます。

これによって防げる失敗： 「コンテキストが少なくなっていた」ために、エージェントがフェーズ 4～9（ドキュメント作成、レビュー、QA 計画、テスト、レビュー、完了）を急ぐと、作業が不完全なまま出荷されます。フェーズ 4 に完全なコンテキストで再投入されるクリーンな再起動のほうが、残り少ないコンテキストで後続フェーズを圧縮して進めるよりも、良い成果につながります。

---

ヘッドレスモード

次の場合、Ship はヘッドレスモードになります。

• $ARGUMENTS に --headless が含まれている場合、または
• 入力が提供された仕様（既存の SPEC.md へのパス、インラインの SPEC.md の内容、または spec.json）である場合

ヘッドレスモードとは、ワークフローの全期間を通じて人間が不在であることを意味します。すべてのフェーズを実行し、すべてのスキルを読み込み、すべてのチェックリストを実行します。ただし、ユーザー入力を待つために一時停止するフェーズはありません。

ヘッドレスモードでの動作ルール：

1. すべてのフェーズを自律的に実行します。 協働フェーズはありません。フェーズ 1 の仕様作成はスキップします（仕様はすでに提供されています）。フェーズ 1 の検証は引き続き実行し、不足箇所は質問するのではなく、妥当なデフォルト値で補います。
2. <input> を絶対に出力しないでください。 <input> による一時停止の仕組みは無効です。通常なら人間の判断が必要な決定は、/research、/explore、およびコードベースの調査で集めた根拠を用いて自律的に行います。そのような決定はすべて完了レポートに記録してください。
3. 質問を絶対にしないでください。 いかなる時点でも確認、明確化、承認を求めないでください。状態が存在する場合、フェーズ 0 の復旧では自動的に再開します。フェーズの移行は、確認ゲートを設けずに進めてください。
4. レビューゲートは助言として扱います。 最大自動修正回数を過ぎてもレビューゲートが収束しない場合は、残っている指摘を記録して先に進みます。行き詰まらないでください。
5. ヘッドレスモードに対応しているすべての子スキル（/qa、/debug、/qa-plan）に --headless を渡してください。 ネストされたサブプロセス（フェーズ 3、5、6）では、/nest-claude の規約に従って非対話モードを指定してください。
6. スキルの読み込みはすべて必須です。 ワークフローで読み込むよう指定されたスキルを、直接の作業で代用しないでください。各ステップですべてのスキルを読み込んでください。スキルには、ヘッドレスモードでも維持される品質ゲートとチェックリストが含まれています。
7. インラインの仕様内容： 入力がインラインの SPEC.md の内容（ファイルパスではない）である場合、作業を進める前に specs/<feature-name>/SPEC.md に書き込んでください。仕様のタイトルまたは問題の記述から機能名を導き出してください。

headless フラグは state.json に記録され（references/state-initialization.md を参照）、コンパクションや再入場後も保持されます。再入場時、エージェントは state.json から headless: true を読み取り、ヘッドレスモードを続行します。

⚠️ 既知のバグ：サブプロセスの実行で、後続のフェーズがスキップされることがこれまでありました。

/ship 自体がネストされた claude -p サブプロセスとして実行されている場合（例：/nest-claude による委任）、コンテキストのコンパクションでサブプロセスの状態追跡が失われるため、これまでフェーズ 5～9 がスキップされていました。これはバグであり、許容される動作ではありません。 サブプロセスで実行されているか、トップレベルの会話で実行されているかにかかわらず、Ship オーケストレーターである場合は、すべてのフェーズを必ず実行しなければなりません。このバグが存在しても、フェーズをスキップする許可にはなりません。

サブプロセスとして実行されていない場合（つまり、トップレベルのエージェントである場合、または対話的に実行している場合）、この制限は一切適用されません。 すべてのフェーズを実行してください。

サブプロセスとして実行されている場合： スキップしようとする傾向に抗ってください。各スキルを読み込み、各サブプロセスを起動し、各フェーズを実行してください。コンテキストのコンパクションにより中断された場合、stop hook が正しいフェーズで再び呼び出します。それを信頼し、そこから続行してください。

---

Ship 作業ディレクトリ

すべての実行状態は、設定可能な作業ディレクトリ（gitignore 対象）に保存されます。解決の優先順位は次のとおりです。

優先順位	ソース	デフォルト
1	セッションアンカー（session_id をキーとして ship-worktree.sh が書き込みます。stop hook のみが使用します）	--
2	環境変数 CLAUDE_SHIP_DIR_OVERRIDE（Docker／CI／分離環境向けの明示的な上書き）	--
3	git ルートから動的に取得	$(git rev-parse --show-toplevel)/tmp/ship

Ship スクリプトは git rev-parse --show-toplevel から Ship ディレクトリを動的に取得するため、環境変数を手動で管理する必要はありません。このスキルとその子スキル（/implement、/cancel-ship）では、tmp/ship/ は解決された Ship ディレクトリを指します。シェルスクリプト（ship-init-state.sh、implement.sh、ship-stop-hook.sh）はこれを動的に解決し、各ワークツリーに専用の tmp/ship/ ディレクトリが自動的に作成されます。

ワークツリーに移動すると、スクリプトは git rev-parse を使ってワークツリーの tmp/ship/ を自動的に解決します。

状態ファイル

すべての実行状態は tmp/ship/（gitignore 対象）に保存されます。コミットされる唯一の成果物は SPEC.md です。子スキル（/spec、/implement）はそれぞれ内部成果物を管理します。詳細は各 SKILL.md ファイルを参照してください。

ファイル	保存内容	作成	更新	読み取り元
tmp/ship/state.json	ワークフローの状態 — 現在のフェーズ、機能名、仕様パス、ブランチ、機能、品質ゲート、修正、バックグラウンドプロセス	フェーズ 1（Ship）	各フェーズ遷移時（Ship）、バックグラウンドプロセスの起動／完了時	Stop hook（再注入、プロセス検出）、Ship（再入）
tmp/ship/loop.md	ループ制御 — 反復カウンター、最大反復回数、完了の約束、session_id（分離用）	フェーズ 1（Ship）	再入のたび（stop hook が反復回数を増やし、session_id を記録）	Stop hook（終了のブロック／許可）
tmp/ship/last-prompt.md	最後に再注入したプロンプト — stop hook が直近の再入時に作成した完全なプロンプト。デバッグ用	Stop hook	再入のたび（上書き）	デバッグのみ
tmp/ship/spec.json	ユーザーストーリー — 受け入れ基準、優先度、合格／不合格の状態	フェーズ 2（/decompose）	各反復時（passes: true を設定）	implement.sh、反復処理、Ship
tmp/ship/progress.txt	反復ログ — 実施内容、学習事項、ブロッカー	フェーズ 3 開始時（implement.sh）	各反復時（追記）	反復処理、Ship
tmp/ship/review-output.md	レビューゲート（フェーズ 5、フェーズ 8）による最新の移植可能なローカルレビュー概要	レビューゲート	ローカルレビューの各実行時（上書き）	Ship、ユーザー
tmp/ship/review-status.json	解析済みのローカルレビュー状態 — 推奨事項、リスク、問題の件数、ゲートがまだブロック中かどうか	レビューゲート	ローカルレビューの各実行時（上書き）	Ship、ローカルレビュースクリプト
tmp/ship/qa-progress.json	QA シナリオと結果 — 状態、メモ、bootstrapResult	フェーズ 6（/qa-plan）	フェーズ 7（/qa） — シナリオの状態、証拠、bootstrapResult。フェーズ 7 終了ゲート（Ship） — オーケストレーターが /qa で解決できなかったシナリオを解決した場合、blocked から resolvedBy: "parent" を伴う validated に更新	Ship（フェーズ 6→7 のフェーズゲート、完了レポート）
tmp/ship/ship-summary.md	Ship サマリー — 仕様との差異、QA の不足、先送りした範囲、明らかになった機会	フェーズ 9（Ship）	フェーズ 9 のみ	/pr
SPEC.md (コミット対象)	製品および技術仕様 — 要件、設計、決定事項、対象外事項	フェーズ 1（/spec またはユーザー）	フェーズ 1 のみ	すべてのフェーズ、反復処理

何をいつ更新するか

イベント	state.json	その他のファイル
Phase 1 終了時	実行 ship-init-state.sh — state.json と loop.md の両方を作成します（Phase 1、Step 3 を参照）	—
Phase 2 開始時	—	/decompose が tmp/ship/spec.json を作成します
Phase 3 開始時	—	/implement が tmp/ship/implement-prompt.md と tmp/ship/progress.txt を作成します
レビューゲート（Phase 5、Phase 8）	state.json がすでに存在する場合は、ローカルレビューのステータスを更新します	run-local-review.sh が移植可能なレビュー一式を tmp/ship/pr-review-plugin/ にステージングし、tmp/ship/review-output.md を上書きして、その内容を解析して tmp/ship/review-status.json に出力します
任意のフェーズ → 次のフェーズ	currentPhase を次のフェーズに設定し、completedPhases に正式なフェーズ名を追加して、lastUpdated を更新します。正式な名前は "Phase 2"、"Phase 3"、"Phase 4"、"Phase 5"、"Phase 6"、"Phase 7"、"Phase 8"、"Phase 9" です。終了フックは完了を許可する前に、Phase 2～9 のそれぞれが completedPhases に含まれていることを検証します。エントリーが不足していると終了がブロックされます。	—
ユーザーによる修正（任意のフェーズ）	amendments[] に追加します：{"description": "...", "status": "pending"}	—
後回しにする範囲を特定（任意のフェーズ）	deferredScope[] に追加します：{"description": "...", "phase": "Phase N", "source": "..."}	—
機会を把握（任意のフェーズ）	surfacedOpportunities[] に追加します：{"description": "...", "phase": "Phase N", "source": "..."}	—
バックグラウンドプロセスを起動（Phase 3、4、5、6、7、8）	backgroundProcesses[] に次のフィールドを追加します：taskId、pid（不明な場合は null）、type（"implement"、"review"、または "nested-claude"）、phase、command、startedAt（ISO 8601）、description。jq を使用して追加します（一時ファイル経由の読み取り・変更・書き込み）。プロセスが完了したら、taskId でフィルタリングしてエントリーを削除します。	—
イテレーションでストーリーが完了	—	tmp/ship/spec.json：ストーリーの passes: true を設定します。tmp/ship/progress.txt：イテレーションログを追加します。
Phase 6 QA 計画	—	/qa-plan が、計画済みシナリオ、ギャップ、拡充内容を含む tmp/ship/qa-progress.json を作成します
Phase 7 QA 実行	—	/qa が tmp/ship/qa-progress.json を更新します — シナリオのステータス、bootstrapResult、エビデンス
Phase 7 終了ゲート（ブロック状態の解消）	—	/qa の終了後にオーケストレーターが解決したシナリオについて、Ship が tmp/ship/qa-progress.json を更新します — blocked → validated とし、resolvedBy: "parent" を設定します
Phase 9 → 完了	currentPhase: "completed" を設定します。completedPhases に "Phase 9" を追加します。終了フックの3項目ゲートで、（1）出力に完了の宣言があること、（2）currentPhase === "completed" であること、（3）Phase 2～9 がすべて completedPhases に含まれていることを検証します。	終了フックが loop.md を削除します
終了フックの再入	—	loop.md：イテレーション数が増加します。プロンプトは state.json と SKILL.md から再注入されます。
/cancel-ship	確認用に保持します	loop.md を削除します

---

ワークフロー

フェーズの移行

任意のフェーズから次のフェーズに進む前に：

1. 現在のフェーズの未解決の質問がすべて解決済みであることを確認します。

2. 現在のフェーズの成果物に十分な確信があることを確認します。

3. ヘッドレスモードの場合：すべてのフェーズは自律的に進行します。<input> を出力したり、確認を求めたりしないでください。エビデンスに基づいて最善の判断を下し、完了レポートに記録します。

4. 対話型の協働フェーズの場合（ユーザーが積極的に入力している場合）：先に進んでよいか明示的に尋ねます。確認が得られるまで進めないでください。

5. 対話型の自律フェーズの場合：自分で判断します。ただし、自律的には下せない人間の判断が必要な決定（大きなトレードオフを伴うアーキテクチャ上の選択、製品や顧客に関わる判断、スコープの変更、誤った推測のコストが高い曖昧な要件）については、一旦停止してユーザーに相談します。 一時停止する前に： 状況を徹底的に調査してください。関連するコンテキストをすべて集め、選択肢を検討し、トレードオフを評価してください。ユーザーには曖昧な質問ではなく、判断に必要な情報を網羅した概要を提示してください。

   一時停止するには： メッセージの冒頭に <input>Input required</input> を出力し、その後に以下を続けてください。

   • 状況：何が起きたか、なぜ判断が必要なのか
   • 収集したコンテキスト：何を調査し、何がわかり、何を試したか
   • 選択肢：それぞれのトレードオフを含む具体的な選択肢
   • 推奨事項：選択肢がある場合、どれを選ぶか、またその理由
   • 質問：「決定する前に、これらの選択肢についてさらに詳しく調査しましょうか？」

   ストップフックが <input> を検出すると、ユーザーの応答を待機できます。ループはアクティブなままです。ユーザーが応答し、その内容に基づく作業を終えると、ループは自動的に再開します。

   次の場合は一時停止しないでください： 根拠に基づいて判断できる通常のエンジニアリング上の決定、コードやドキュメントを読めば回答できる質問、/research または /explore で解決できること。この基準で判断してください。このチームのシニアエンジニアなら自分で決めるか、それともプロダクトオーナーにエスカレーションするか。

6. 上記の「更新タイミング」表に従って tmp/ship/state.json を更新してください（Phase 1 の終了前には存在しません）。

   • 変更依頼： ユーザーが元の仕様にない変更（アドホックなタスク、改善、微調整、レビューのフィードバックによってユーザーが承認したスコープの拡張）を依頼した場合、対応を始める前に amendments に追加してください：{ "description": "<概要>", "status": "pending" }。完了したら status を "done" に設定してください。このログはコンテキストの圧縮後も保持され、再開したエージェントに仕様外の作業として依頼された内容を伝えます。

7. タスクリストを更新してください。完了したフェーズのタスクを completed にし、次のフェーズのタスクを in_progress にしてください。

8. 後回しにするスコープと、作業中に見つかった機会を記録してください。 各フェーズの移行時に、そのフェーズで判明したものの今回のリリースでは対応しない事項を確認し、state.json に追加してください。カテゴリは次の2つです。

   • deferredScope[] — 必要性が判明したものの、意図的に対応しなかった作業（原則として受け入れたが後回しにしたレビュー担当者の提案、関連する不具合の発見、未対応と認識しているエッジケース、実装中に明らかになった後続作業など）。次の形式で追加してください：{ "description": "<必要な作業>", "phase": "Phase N", "source": "<きっかけ>" }。
     • レビュー結果の取り込み： 各レビューゲート（Phase 5 の /review-cloud、Phase 4／Phase 8 の /review-local）の後に、今後に関係する却下済みの指摘についてレビュー結果を確認してください。/review-local の場合は、review-status.json の deferredFindings[] を確認してください。/review-cloud の場合は、完了時の出力にある却下済みの指摘一覧を確認してください。今後に関係する各項目を、現在のフェーズを指定し、source を "review-cloud" または "review-local" として deferredScope[] に追加してください。
   • surfacedOpportunities[] — コードを深く調べる中で浮かび上がったアイデア、改善案、アーキテクチャに関する所見のうち、必須ではないもの。次の形式で追加してください：{ "description": "<所見>", "phase": "Phase N", "source": "<きっかけ>" }。

   これらは amendments[] と同じ方法で、直ちに state.json に保存してください。state.json に保存された項目はコンテキストの圧縮後も保持されますが、会話内だけで追跡した項目は保持されません。Phase 9 のリリース概要では、これらの配列を参照します。

---

フェーズのタスクリストを作成する（新しい実行ごとに最初に行うこと）

フェーズ 0 を開始する前に、TaskCreate を使って各フェーズのタスクを作成してください。これにより、ワークフロー全体を最初から確認でき、フェーズの抜け漏れを防げます。

次の順序でタスクを作成します。

1. フェーズ 0：コンテキストと開始地点の検出 — 復旧チェック、機能名、ワークツリー、機能検出、スコープの調整
2. フェーズ 1：仕様の作成と引き継ぎ（/spec） — 仕様のひな形作成、調査、/spec の読み込み、検証
3. フェーズ 1 の終了：自律実行の有効化（ship-init-state.sh） — 初期化スクリプトを実行して state.json と loop.md を作成し、両ファイルの存在を確認します。これにより、エージェントが残りのすべてのフェーズを実行し続けるようにする停止フックが有効になります。
4. フェーズ 2：分解（/decompose） — SPEC.md のパスを指定して /decompose を読み込み、spec.json を作成
5. フェーズ 3：実装（/implement） — 理解を深め、spec.json を指定して /implement を読み込み、実装後にレビュー
6. フェーズ 4：ドキュメント（/docs） (ネストされたサブプロセス) — ネストされた Claude を起動し、影響を受けるすべてのドキュメントを作成・更新
7. フェーズ 5：レビューゲート — QA 前（/review-local） — ローカルレビューの収束ループを実行し、指摘事項を評価して、検証済みの問題を修正
8. フェーズ 6：QA の計画（/qa-plan） (ネストされたサブプロセス) — ネストされた Claude を /qa-plan とともに起動し、spec.json、コード、差分から qa-progress.json を作成
9. フェーズ 7：テスト／QA（/qa） (ネストされたサブプロセス) — ネストされた Claude を /qa とともに起動し、qa-progress.json に基づいて実行
10. フェーズ 8：レビューゲート — QA 後（/review-local） — QA による修正を含む最終コードを対象に、ローカルレビューの収束ループを実行
11. フェーズ 9：完了 — 完了チェックリストを実行し、ユーザーに報告して、完了の約束を出力

各フェーズを開始したら、そのタスクを in_progress に設定してください。フェーズが完了したら、そのタスクを completed に設定してください。

Ship Loop の再入時（[SHIP-LOOP]）： まず TaskList を確認してください。タスクがすでに存在する場合は、再開します。完了済みのフェーズのタスクがまだ completed になっていなければ設定し、現在のフェーズのタスクから続行してください。タスクが存在しない場合（この手順より前にセッションが始まった場合）は、タスクを作成し、state.json の completedPhases に基づいて、すでに完了したフェーズを completed に設定してください。

---

フェーズ 0：コンテキストと開始地点の検出

前回のセッションからの復旧

何よりも先に、tmp/ship/state.json が存在するか確認してください。存在する場合：

ヘッドレスモードの場合： 自動的に再開します。状態を読み込み、記録されたフェーズに進んでください。質問はしないでください。

対話モードの場合：

1. ファイルを読み込み、復旧した状態をユーザーに提示します。機能名、現在のフェーズ、完了済みのフェーズ、保留中の修正内容を含めてください。
2. 次のように尋ねます。「[feature] に対する前回の /ship セッションは [phase] で中断されました。そこから再開しますか、それとも最初から始めますか？」
3. 再開する場合：状態（仕様のパス、ブランチ、ワークツリーのパス、品質ゲート、機能、修正内容）を読み込み、記録されたフェーズに進みます。SPEC.md と、状態ファイルで参照されている成果物を再読み込みしてください。修正内容の配列に保留中の項目がないか確認してください。これらは仕様作成後にユーザーが依頼した変更で、まだ作業が必要な場合があります。tmp/ship/loop.md が存在しない場合（ループが有効になっていなかった場合）は、フェーズ 1 の手順 3 に従って再度有効にしてください。
4. 最初から始める場合：状態ファイルを削除し、存在する場合は tmp/ship/loop.md も削除してから、通常どおり続行してください。

ステップ 1：機能名と開始点を決める

ユーザーが何を構築したいのか、仕様書がすでにあるのかを確認します。ここでは軽く調べてもかまいません。状況を把握するための Grep／Glob／Read 呼び出しを数回行い（例：該当するディレクトリを見つける、モジュールが存在するか確認する）てもかまいません。ただし、長時間の調査、Explore サブエージェントの起動、スキルの読み込みは行わないでください。詳細な調査は、Phase 1 でスキャフォールドが作成された後に行います。

条件	アクション
ユーザーが既存の SPEC.md へのパス（または仕様のインラインコンテンツ）を指定した	読み込みます。仕様から機能名を導き出します。ヘッドレスモードを有効にします。仕様が指定されている場合、ワークフローはユーザーとのやり取りなしで最初から最後まで実行されます（「ヘッドレスモード」セクションを参照）。入力がインラインコンテンツの場合は、まず specs/<feature-name>/SPEC.md に書き込みます。
--headless フラグが（機能の説明とともに）渡された	ヘッドレスモードを有効にします。説明から機能名を導き出します。Phase 1 で説明をもとに SPEC.md をスキャフォールドし、その後は自律的に進めます。
ユーザーが機能の説明を指定した（SPEC.md なし、--headless なし）	状況を把握するため、該当箇所を軽く調べてもかまいません。その後、短い機能名（例：revoke-invite、org-members-page、auth-flow）を導き出します。説明があいまいで名前を付けられない場合は、的を絞った質問を1～2件だけ行います。目的は意味が伝わる名前を決めることであり、詳細なスコープを定めることではありません。
あいまいな場合	「既存の SPEC.md はありますか。それとも、これから仕様を作成しますか？」と尋ねます。

ステップ 2：分離された作業環境を作成する

機能名が決まったら、成果物が最初からすべて機能用ワークスペースに置かれるよう、分離された作業ディレクトリを用意します。

デフォルトの動作： /ship は、上書きされない限り、origin/main から新しい worktreeを作成します。これにより、複数の /ship インスタンスが競合することを防ぎます。各 worktree には専用の tmp/ship/ 状態ディレクトリが用意されます。次のオプションで上書きできます。

• --local — worktree の作成をスキップし、現在のチェックアウトをそのまま使用します
• --branch <name> — worktree の作成をスキップし、指定した既存のブランチをチェックアウトします

読み込み： references/worktree-setup.md — 判断表、セットアップ手順、依存関係のインストール方法がすべて記載されています。

場当たり的な git worktree コマンドより、ヘルパースクリプトを優先してください。

<path-to-skill>/scripts/ship-worktree.sh ensure --feature "<feature-name>"

このヘルパーは新しい sibling worktree を作成し、各 /ship リクエスト専用のワークスペースを用意します。現在のチェックアウトを再利用するのは、すでに worktree 内にいる場合（メインのチェックアウトではない場合）に限られます。

仕様の引き継ぎ： --spec <path> が指定された場合は、worktree を作成する前にパスを絶対パスに解決し、cd で移動した後に worktree へコピーします。手順については references/worktree-setup.md を参照してください。

スクリプトは git rev-parse --show-toplevel から ship ディレクトリを動的に解決するため、worktree に入った後に手動で再エクスポートする必要はありません。

ステップ 3：実行環境を検出する

読み込み： references/capability-detection.md — 品質ゲート、ブラウザー、macOS、Docker、スキルの各機能について、検出用のプローブ表と、利用できない場合の代替手順が記載されています。

結果を記録します。対話モードの場合： 利用できない機能があれば、作業を進める前にユーザーが対応できるよう、何が不足しているかを交渉の確認事項として簡潔に伝えます。ヘッドレスモードの場合： 利用できない機能を記録したうえで続行します。代替手順は各子スキルであらかじめ定められています。

Step 4: ワークフローの範囲を調整する

タスクを評価し、各フェーズに適切な深度を決定します。すべてのフェーズは常に実行します。範囲の調整で変わるのは厳密さであり、フェーズを実行するかどうかではありません。

タスクの範囲	仕様の深度（フェーズ 1）	実装の深度（フェーズ 3）	ドキュメントの深度（フェーズ 4）	レビューの深度（フェーズ 5、8）	テストの深度（フェーズ 7）
機能（新機能、複数ファイルにまたがる、ユーザー向け）	/spec を完全に実施 → SPEC.md → spec.json	/implement の反復ループを完全に実施	ドキュメントを完全に確認 — 製品向け＋内部向け	ローカルレビューの収束ループを完全に実施	/qa を完全に実施
機能強化（既存機能の拡張、中程度の範囲）	問題＋受け入れ基準＋テストケースを含む SPEC.md を作成。/spec は任意	/implement の反復ループ	影響がある場合は既存ドキュメントを更新	ローカルレビューの収束ループを完全に実施	/qa（範囲に合わせて調整）
バグ修正／設定変更／インフラ（小規模、対象を絞った変更）	問題の説明＋「修正済み」の状態＋受け入れ基準を含む SPEC.md を作成	/implement の反復ループ（範囲に合わせて調整）	挙動が変わった場合のみドキュメントを更新	ローカルレビューの収束ループ	ユーザー向けの場合は対象を絞って /qa を実施

SPEC.md は必ず作成します。会話での調査結果だけでは、コンテキストの喪失に耐えられません。

範囲のレベルは内部で記録してください。これは各フェーズの深度を通じて規定されます。ここでフェーズごとの詳細な計画を提示したり、承認を待ったりせず、フェーズ 1 に進み、SPEC.md のひな型に初期の範囲を記録してください。ユーザーは別途計画を承認するのではなく、仕様の引き継ぎ（フェーズ 1、ステップ 2）を通じて範囲を確認します。

---

フェーズ 1：仕様の作成と引き継ぎ（/spec、対話モードでは共同作業）

ヘッドレスモードで仕様が提供されている場合： ステップ 1 は完全にスキップします。仕様はすでに存在しています。ステップ 2（検証）に進んでください。検証後、確認を待たずにステップ 3（状態の有効化）へ直接進みます。

ヘッドレスモードで --headless フラグが指定されているものの、仕様が提供されていない場合： 機能の説明から SPEC.md のひな型を作成し（specs/<feature-name>/SPEC.md に書き込みます）、以下の調査手順を実行してから、確認を待たずにステップ 2 に進みます。

対話モードの場合： ユーザーはプロダクトオーナーです。何を構築するかを明確に考えられるよう支援し、見落としている可能性のある検討事項を示し、ユーザーとともに厳密な仕様を作成してください。

ステップ 1：仕様を作成する

まず土台を作り、その後に詳細を詰めます。 ユーザーの説明が本当に曖昧で、土台を作成できない場合（例：「システムを改善してほしい」だけで、具体的な内容がない場合）は、スコープを絞るための質問を最大 1～2 件してください。問題の記述を書ける程度に具体的な依頼であれば（不完全な内容でも）、質問は省略して、すぐに土台を作成します。土台ができる前に、スコープを絞るためのやり取りを長々と続けないでください。

リポジトリのルートからの相対パスで、specs/<feature-name>/SPEC.md に作成してください。これは /spec スキルのデフォルトのパス規約に従っています。上書きの優先順位（環境変数、AI リポジトリ設定、ユーザーによる上書き）の詳細については、/spec の「Where to save the spec」を参照してください。土台には、次の内容を記載します。

• 問題の記述（現時点で把握している内容）
• 初期要件と受け入れ基準（不完全でも可）
• 既知の制約や技術的な方針
• 未解決の質問（明確化が必要な事項）

土台は完全である必要はありません。圧縮後も内容が失われず、その後の検討の軸となるよう、ディスク上に存在している必要があります。詳細な調査（調査、未解決の質問、判断、/spec）は、土台ができた後に行います。土台を作成する前には行いません。

土台を作成したら、調査します。 土台を軸として会話を進められるようになったら、仕様の作成に役立つ詳細な調査を行います。

1. 既存システムを追跡します。 /explore スキルを読み込み、該当領域の現在の仕組み（パターン、共有抽象化、データフロー、影響範囲）を把握します。バグ修正では、システム追跡の観点を用いて、エントリーポイントからエラーが発生する箇所まで実行を追い、症状だけでなく根本原因を特定します。
2. サードパーティの依存関係を調査します。 機能にサードパーティのライブラリ、フレームワーク、パッケージ、API、または外部サービスが関係する場合は、ソリューションを設計する前に /research スキルを読み込み、それらの機能、制約、正しい使い方を確認します。依存関係に詳しくない場合だけでなく、毎回実施してください。以前に使ったことがある依存関係でも、変更されている場合や、文書化されていない制約がある場合、またはこの状況では異なる動作をする場合があります。API の形状を推測して仕様を作成せず、必ず確認してください。
3. 土台を更新します。 調査結果を反映して SPEC.md を改訂します。根本原因（バグの場合）、システムの制約、API の形状、依存関係の機能、得られた知見に基づく詳細な受け入れ基準を記載します。

この調査は省略できません。現実に即した仕様と、仮定に基づく仕様を分けるのが、この調査です。API が特定の方法で動作すると仮定したり、モジュールが特定のインターフェースを持つと仮定したりする仕様は、後になって修正コストの高い実装上の問題につながります。

その後、詳細を詰めます。 /spec スキルを読み込み、対話形式のプロセスを通じて仕様を掘り下げ、完成させます。土台と調査結果があることで、白紙の状態ではなく、根拠に基づいた出発点から /spec を進められます。

仕様の作成時には、以下の内容を証拠に基づいて（単なる希望ではなく）記録してください。

• すべてのテストケースと受け入れ基準。基準には、内部の仕組みではなく、観察可能な動作を記述します（例は /tdd を参照）。
• 失敗モードとエッジケース
• サードパーティ依存関係の制約と API の形状（推測ではなく、/research を通じて確認したもの）

スコープの調整により、簡略化した仕様作成プロセスが適切と判断された場合（機能強化またはバグ修正の場合）：/spec を呼び出す代わりに、土台を直接改訂します。上記の調査手順は引き続き適用されます。仕様作成を簡略化しても、調査まで簡略化するわけではありません。最終的な SPEC.md には、問題の記述、根本原因（バグ修正の場合）、完了の定義（受け入れ基準）、テスト内容を必ず記載してください。

ユーザーが既存の SPEC.md を提供した場合（フェーズ 0 で検出）：ステップ 2 に進みます。

ステップ 2：仕様を検証する

SPEC.md を読み、実装に十分な詳細が記載されていることを確認します。

• 問題の説明と目標が明確である
• スコープ、要件、受け入れ基準が定義されている
• テストケースが列挙されている（または受け入れ基準から導き出せる）
• 技術設計が存在する（アーキテクチャ、データモデル、API の形式など、少なくとも大まかな方向性が示されている）

不足がある場合：**対話モードでは、**ユーザーに的を絞った質問をするか、妥当なデフォルトを提案して不足を補います（仮定であることを明確に示します）。**ヘッドレスモードでは、**妥当なデフォルトで不足を補い、SPEC.md に仮定であることを明記して続行します。

**対話モードでは：**ユーザーが SPEC.md の実装準備が整ったと確認するまで、先に進まないでください。この確認が引き継ぎとなり、ここから先の実行は自律的に行います。

**ヘッドレスモードでは：**検証後すぐに続行します。提示された仕様は、ユーザーの最終決定として扱います。

ステップ 3：実行状態を有効化する

読み込む： references/state-initialization.md — 初期化スクリプトの実行方法と各フィールドの説明が記載されています。

Phase 0（機能、スコープ）と Phase 1（機能名、仕様ファイルのパス、ブランチ）の値を使って、<path-to-skill>/scripts/ship-init-state.sh を実行します。フック入力 JSON で確認できるセッション ID を --session-id に渡して、所有者情報を loop.md に記録します。これにより、複数の ship セッションがこのループを同時に所有しようとするのを防げます。**state.json や loop.md を手動で作成しないでください。必ずスクリプトを使用してください。**手書きの JSON/YAML は、停止フック失敗の最大の原因です。引数とデフォルト値の一覧はリファレンスを参照してください。

スクリプトの実行後、両方のファイルが存在することを確認します。

test -f tmp/ship/state.json && test -f tmp/ship/loop.md && echo "State initialized" || echo "ERROR: state files missing"

いずれかのファイルがない場合は、スクリプトの出力でエラーを確認し、再実行してください。両方のファイルがそろうまで、Phase 2 に進まないでください。

このスクリプトにより、自律実行の停止フックが有効になります。ループは <complete>SHIP COMPLETE</complete> に到達するか、20 回繰り返すまで実行されます。/cancel-ship で手動キャンセルできます。

---

Phase 2：分解（/decompose）

SPEC.md のパスを指定して /decompose スキルを読み込みます。/decompose は仕様を読み込み、コードベースを分析して、依存関係の順序、検証可能な受け入れ基準、QA シナリオを含む構造化されたユーザーストーリーを tmp/ship/spec.json に生成します。

Phase 3 に進む前に、tmp/ship/spec.json が存在することを確認します。

---

Phase 3：実装（/implement）

ステップ 1：コードベースへの理解を深める

仕様に適切なセクションがそろっているかどうかだけでなく、機能を本当に理解していることを確認します。自分で理解度を確認してください。この機能が何をするのか、なぜ重要なのか、技術的にどのように動作するのか、最もリスクの高い部分は何か、最初に何をテストするかを説明できますか？できない場合は、説明できるようになるまで仕様を読み直し、コードベースを調査します。対象領域を理解するために（目的を「実装」として）/explore スキルを読み込み、作業に必要なパターン、規約、共有抽象化を把握します。/explore の調査結果と SPEC.md をもとに理解を深めてください。実装ファイルをあてもなく閲覧せず、/explore に調査の道筋を組み立てさせます。特定のサブシステムをさらに深く理解する必要がある場合は、サブエージェントに的を絞った質問を委任します（例：「src/middleware/ の認証ミドルウェアチェーンはどのように動作しますか？どのような規約に従っていますか？」）。理解すべきなのはアーキテクチャであり、行ごとの詳細ではありません。この理解をもとに、後で実装結果とレビュアーのフィードバックを評価します。

ステップ 2：/implement スキルを読み込む

spec.json のパス（フェーズ 2 で取得）を指定して /implement スキルを読み込みます。spec.json はすでに存在するため、/implement はフェーズ 2（準備）から開始し、内部での変換処理をスキップします。スコープにかかわらず、プロンプトの作成と反復ループは /implement が担当します。実装コードを直接書かないでください。変更がインラインで実行できるほど単純に思えても、すべての実装は /implement とそのサブプロセス（implement.sh）を通じて行います。

実装の全ライフサイクル（仕様の変換（SPEC.md → spec.json）からプロンプトの作成、実行まで）を処理するため、/implement スキルを読み込みます。次の情報を渡します。

• SPEC.md のパス。最優先の入力です。省略しないでください。
• ステップ 1 で取得したコードベースのコンテキスト。/explore を使って特定したパターン、規約、共有抽象化を含みます。
• フェーズ 0 で設定した品質ゲートコマンドの上書き（pnpm のデフォルトとは異なる場合があります）
• フェーズ 0 で確認したブラウザーの利用可否（ブラウザーツールが利用できない場合は、基準を調整できるように --no-browser を渡します）
• フェーズ 0 で指定した Docker の実行方法（--implement-docker が渡されていた場合は、提供された場合には compose ファイルのパスも含め、--docker として /implement に渡します）

/implement が完了するまで待ちます。自動実行が利用できないと報告され、ユーザーに引き継がれた場合は、ユーザーが完了を知らせるまで待ちます。完了の連絡を受けたら、SPEC.md、spec.json、progress.txt を読み直し、状況を再確認します。

バックグラウンドプロセスの追跡： /implement が Bash(run_in_background: true) を介して implement.sh を起動したら、状態更新テーブルの「バックグラウンドプロセスの起動」の行に従って、直ちにそのバックグラウンドプロセスを state.json に記録します。type には "implement"、description には "Implementation iteration loop" を使用します。implement.sh が完了したら、そのエントリーを削除します。

ステップ 3：実装後のレビュー

実装が完了したら、先に進む前に出力に問題がないか確認します。このコードにはあなたが責任を負います。実装の出力は出発点であり、最終地点ではありません。変更されたファイルをすべて自分で読んでレビューするのではなく、サブエージェントに対象を絞って検証を委任します。「実装は SPEC.md の受け入れ基準を満たしていますか？不足、不要なコード、未解決の TODO はありますか？各受け入れ基準に対応するテストはありますか？」調査結果に基づいて対応します。小さく明白な問題は直接修正します。根本原因がすぐには明らかでない問題は、--headless を指定して /debug スキルを読み込み、原因を調査します。/debug は、実装自体は行わず、構造化された調査結果（根本原因、推奨される修正、影響範囲）を返します。その調査結果に基づいて修正を適用します。ストーリーの再実装が必要となる大規模な手直しの場合は、具体的なフィードバックを添えて /implement スキルを再読み込みします。

コードを変更した場合（直接修正した場合も、/implement を再実行した場合も含みます）：先に進む前に、品質ゲート（テストスイート、型チェック、リンター）を再実行し、すべて成功することを確認します。/implement は成功状態で終了しますが、そのループの外で行った実装後の修正は、自分で検証する責任があります。

---

Phase 4：ドキュメント（/docs、ネストされたサブプロセス）

ネストされた Claude Code インスタンス（クリーンな子プロセス。「/nest-claude」サブプロセスのパターンを使用）を起動して、ドキュメントを作成または更新します。サブプロセスは「/docs」を読み込み、ドキュメントのライフサイクル全体を分離された環境で処理します。ドキュメントは早い段階で作成し、両方のレビューゲート（Phase 5 と Phase 8）でドキュメントの品質と正確性を評価できるようにします。pr-review-docs を含むすべてのレビュアーが、ドキュメントがすでに用意された状態で実行されます。

サブプロセスに以下を渡します。

• SPEC.md へのパス（構築したものとその理由に関する主要な情報源）

バックグラウンドプロセスの追跡： Bash(run_in_background: true) でネストされた Claude サブプロセスを起動する場合は、状態更新テーブルの「バックグラウンドプロセスの起動」行に従って、state.json に記録します。type は "nested-claude"、description は "Documentation subprocess (/docs)" を使用します。完了したら削除します。

サブプロセスの終了後、ドキュメントの変更がブランチにコミットされていることを確認します。

ドキュメントのメンテナンス規則

後続のすべてのフェーズで、ドキュメントを最新の状態に保つ必要があります。

• Phase 5 または Phase 8（レビュー）の後： レビューのフィードバックによってコードが変更された場合、その変更がこのフェーズで作成したドキュメントに影響するかどうかを評価します。次に進む前にドキュメントを更新します。
• ユーザーからの修正依頼の後： Phase 4 の後にユーザーから変更を依頼された場合は、コードの変更と併せて該当するドキュメントを更新します。
• Phase 9（完了）のチェックポイント： ドキュメントが最終実装を正確に反映していることを確認します。

---

Phase 5：レビューゲート — QA 前（/review-local）

ローカルのレビュー収束ループを実行します。これは2つあるレビューゲートの最初のもので、QA テスト前に実装とドキュメントをレビューします。対象リポジトリにレビュー プラグインが含まれているとは限らないため、まずバンドルを tmp/ship/ にステージングしてから、ステージング済みのコピーを実行してください。

このスキルのヘルパースクリプトを使い、リポジトリのルートから実行します。レビューでは17人のレビュアーが並列で動作し、最大5回の修正パスが実行されます。通常、Bash ツールの600秒のタイムアウトを超えるため、必ず run_in_background: true を指定して実行してください。 起動後、状態更新テーブルの「バックグラウンドプロセスの起動」行に従って、バックグラウンドプロセスを state.json に記録します（type は "review"、description は "Pre-QA local review gate"）。完了したら削除します。

Bash(command: "<path-to-skill>/scripts/run-local-review.sh",
     run_in_background: true,
     description: "Local review gate")

ブランチのターゲットが自動検出されたものと異なる場合は、--target <branch> を明示的に指定します。

この /ship の実行で Docker 実行が有効な場合は、同じヘルパーを Docker モードで実行し、レビューをホスト上ではなくリポジトリのサンドボックス内で実行します。

Bash(command: "<path-to-skill>/scripts/run-local-review.sh --docker [compose-file]",
     run_in_background: true,
     description: "Local review gate (Docker)")

レビューが完了すると、<task-notification> が届きます。待機中は軽作業を行ってもかまいませんが、コード変更は行わないでください。実行中に進捗を確認する必要がある場合は、バックグラウンドの Bash 呼び出しから返された出力ファイルのパスを Read します。予想所要時間は、差分のサイズと修正パスの数によって異なり、10〜30分です。

ヘルパーは移植可能なレビュー プラグインを tmp/ship/pr-review-plugin/ にステージングしてから、ホスト上または Docker サンドボックス内で tmp/ship/pr-review-plugin/scripts/pr-review.sh を実行します。これは /implement のパターンと同じです。コンテナはホストにインストールされたプラグインではなく、バインドマウントされたリポジトリ内のステージング済みアーティファクトを使用します。

ヘルパーはデフォルトでターゲットブランチを自動検出します（利用可能な場合は PR のベースブランチ、それ以外の場合はリポジトリのデフォルトブランチまたは origin/HEAD、次に main）。<task-notification> が届いたら、スクリプトの 標準出力に構造化された戻り値のペイロードが含まれます。ファイルを手動で読むのではなく、直接解析してください。

終了エンベロープ（=== LOCAL REVIEW EXIT ===）：常に表示されます。exit_code、exit_reason、パス数、修正コミットの SHA、最後の推奨事項、ブロック状態、所要時間、フォレンジック用アーティファクトへのファイルポインターが含まれます。最初にこれを読み、結果を判断します。

レビュー状況（=== REVIEW STATUS ===）：解析された review-status.json の内容です。推奨事項、リスク、問題の件数、ブロック理由が含まれます。クラッシュ以外のすべての終了時に表示されます。 イテレーションログ（=== REVIEW ITERATION LOG ===）：レビューの各ラウンドと修正対応の全履歴（何が見つかり、修正担当者が何に対応し、何を見送ったか、または保留したか）です。終了コードが 0 以外の場合（ブロッキング、致命的）にのみ含まれます。オーケストレーターは、修正方針を決めるためにこのコンテキストを必要とします。終了コードが 0（収束）の場合、親のコンテキストが肥大化しないよう、イテレーションログはディスク上に残ります（エンベロープ内のファイルポインターを参照）。

終了理由と対応：

exit_reason	意味	対応
converged	APPROVE のみ — ゲートは合格です	修正内容をスポットチェックし（エンベロープに記載された修正コミットをレビュー）、次に進みます
fixer_no_changes	修正担当者がすべての指摘事項を評価し、すべて見送りまたは保留にしたため、コードは変更されませんでした	イテレーションログには、見送った各指摘事項に対する修正担当者の根拠が記載されています。対話モードの場合： 見送られた指摘事項をユーザーに提示してエスカレーションします。ヘッドレスモードの場合： 残る指摘事項を記録して次に進みます。根拠に基づく修正担当者の判断は、イテレーションログに記載されています。
max_passes_exhausted	すべての修正ラウンド後もブロッキング状態です	イテレーションログに、試した内容が記載されています。対話モードの場合： 解決するまで先に進まないでください。ヘッドレスモードの場合： 残る指摘事項を記録して次に進みます。
allow_blocking	ブロッキング状態ですが、--allow-blocking が設定されていました	次に進みます — 呼び出し元がブロッキング結果を明示的に受け入れています
fatal_error	スクリプトがクラッシュしました（ステージング、レビューのディスパッチ、または解析に失敗）	stderr でエラーメッセージを確認してください。部分的な状態がある場合（エンベロープ内のレビュー状況またはイテレーションログ）、コンテキストとして使用してください。一時的な問題であれば、再試行してください。

• 収束後、修正内容をスポットチェックしてください — 自動修正エージェントの性能は優れていますが、完璧ではありません。

---

フェーズ 6：QA 計画（/qa-plan、ネストされたサブプロセス）

ネストされた Claude Code インスタンス（/nest-claude サブプロセスパターンを使用したクリーンな子プロセス）を起動し、QA テスト計画を作成します。サブプロセスは /qa-plan を読み込み、spec.json とコード、差分を調査して、情報を拡充した tmp/ship/qa-progress.json を作成します。

バックグラウンドプロセスの追跡： 「バックグラウンドプロセスを起動」行に従って、このサブプロセスを state.json に記録します（種類 "nested-claude"、説明 "QA planning subprocess (/qa-plan)"）。完了後に削除します。

サブプロセスには、次の情報を渡します。

• SPEC.md のパス
• spec.json のパス（tmp/ship/spec.json）
• ship がヘッドレスモードで実行されている場合は、--headless を渡します

サブプロセスの終了後、次に進む前に qa-progress.json を確認します。

1. planMetadata を読み込みます — 矛盾（scenarios[].enrichment.gapType === "contradiction"）と重大な実装上のギャップ（scenarios[].enrichment.gapType === "fixable_gap"）を確認します。
2. 矛盾がある場合： 対話モードの場合： <input> で一時停止します — 矛盾は、仕様が実現不可能な前提に基づいていることを意味します。矛盾を提示し、先に進む前にユーザーに解決を求めます。ヘッドレスモードの場合： 最善の判断で解決を試みます（仕様の問題提起と最も整合する解釈を選びます）。矛盾と選択した解釈を完了レポートに記録します。一時停止はしないでください。
3. 重大なギャップがある場合（主要なユーザージャーニーをテストできない — ルートがない、認証が機能しない、メインページが 500 エラーになる）：対話モードの場合： <input> で一時停止します — ギャップを提示し、先に進むか先に修正するかを尋ねます。ヘッドレスモードの場合： 可能であれば直接修正を試みます。修正できない場合は、その旨を記録して次に進みます — ギャップが実際にあるかどうかは QA で確認します。
4. 修正可能なギャップのみがある場合： 次に進みます — /qa の実行中（/qa のステップ 5b）に解決します。
5. 問題がない場合： フェーズ 7 に進みます。

フェーズ 7：テスト／QA（/qa、ネストされたサブプロセス）

QA テストを実行するため、ネストされた Claude Code インスタンス（/nest-claude サブプロセスパターンを使用した、クリーンな子プロセス）を起動します。サブプロセスは /qa を読み込み、tmp/ship/qa-progress.json に基づいて、環境のブートストラップ、ギャップの解消、利用可能なツール（browser、macOS、bash）を使ったテスト実行、結果の記録、ギャップの文書化からなる手動 QA ライフサイクル全体を実行します。

バックグラウンドプロセスの追跡：「Background process launched」の行に従って、このサブプロセスを state.json に記録します（type "nested-claude"、description "QA execution subprocess (/qa)"）。完了したら削除します。

サブプロセスには次の情報を渡します。

• SPEC.md のパス
• スコープ調整で軽量なスコープ（バグ修正／設定変更）が示された場合は、そのコンテキストを渡し、/qa がそれに応じてテストの深さを調整できるようにします
• --headless を渡し、/qa がツールの利用可否を確認するチェックポイントをスキップして、自律的に動作するようにします

フェーズ 7 の終了ゲート — フェーズ 8 に進む前に確認します。

• /qa が完了していること：サブプロセスが終了し、qa-progress.json が結果で更新されています。残っているギャップと解決できない問題は文書化されており、フェーズ 8 への進行を妨げません。
• /qa がコードを変更した場合は、品質ゲート（テストスイート、型チェック、lint）を再実行し、すべて成功していることを確認します。/qa は発見したバグを修正します。修正によってほかの箇所に問題が生じていないことを確認するのは、あなたの責任です。
• ブロックされたシナリオを解決します（下記参照）。
• 実装についてほかのエンジニアに説明できること：何をテストしたか、どのようなエッジケースがあるか、どのように対処しているか

ブロックされたシナリオの解決（該当する場合）：

qa-progress.json に status: "blocked" のシナリオが含まれていて、解決可能な場合（例：/qa サブプロセスでは作成できなかったテストを作成する、環境の問題を修正する、不足している依存関係を提供する）、次の手順で解決します。

1. テスト、検証コード、または修正を作成します。
2. qa-progress.json のシナリオを更新します。

   {
     "status": "validated",
     "resolvedBy": "parent",
     "resolvedAt": "<ISO 8601 timestamp>",
     "resolvedNote": "Covered by <test-file-path> via <approach>",
     "previousStatus": "blocked",
     "previousNotes": "<original blocked reason from /qa>"
   }
   

3. 監査証跡として previousStatus と previousNotes を保持します。下流のコンシューマー（例：/pr）はこれらを使って、親プロセスが解決したシナリオと /qa が検証したシナリオを区別します。

ブロックされたシナリオが本当に解決不可能な場合（外部サービス、本番環境の認証情報、ハードウェアへのアクセスが必要な場合）は、blocked のままにします。PR では人による検証項目として引き継がれます。

---

フェーズ 8：レビューゲート — QA 後（/review-local）

ローカルレビューの収束ループをもう一度実行します。このパスでは、実装、ドキュメント、QA によるコード変更を含む最終状態全体を、新たな視点でレビューします。

フェーズ 5 と同じスクリプトを run_in_background: true で実行します。「Background process launched」の行に従って、バックグラウンドプロセスを state.json に記録します（type "review"、description "Post-QA local review gate"）。完了したら削除します。

Bash(command: "<path-to-skill>/scripts/run-local-review.sh",
     run_in_background: true,
     description: "Post-QA review gate")

各呼び出しは単独で完結します。スクリプトは開始時に以前のレビュー状態をクリーンアップします。同じ --docker オプションが適用されます。<task-notification> を待ってから、stdout の構造化された戻り値ペイロードを解析します。終了理由の一覧と応答プロトコルの詳細については、フェーズ 5 を参照してください。

インタラクティブモードの場合： このレビューゲートが成功するまで、フェーズ 9 に進まないでください。ヘッドレスモードの場合： フェーズ 5 と同様に、最大パス数を経てもゲートが収束しなければ、その旨を文書化して続行します。

フェーズ 8 の終了ゲート：QA の陳腐化チェック

QA 後のレビューゲートで自動修正が実装されたら、その修正によって以前の QA シナリオが無効になっていないか確認します。tmp/ship/qa-progress.json を読み込み、検証済みのシナリオとフェーズ 8 中に作成されたコミットを比較してください。

フェーズ 8 のコミットを特定するには、qa-progress.json の qaCompletedAtCommit フィールド（/qa の最終アクションとして書き込まれます）を使用します。git log <qaCompletedAtCommit>..HEAD を実行し、QA 後のコミットのみを正確に取得してください。各コミットについて、変更されたファイルを確認します。

全体に適用される無効化条件：

• CSS／スタイルファイルの変更 → すべてのビジュアルシナリオを陳腐化としてマークします
• API ルート／ハンドラーの変更 → すべてのインテグレーションシナリオを陳腐化としてマークします

パスに基づくヒューリスティック：

• src/pages/settings/（または同等のパスパターン）内のファイル → 名前またはルートに「settings」を含むシナリオを陳腐化としてマークします
• コンポーネントに関わるファイルの変更 → そのコンポーネントのページ／ルートを参照するシナリオを陳腐化としてマークします

陳腐化したシナリオをマークするには、qa-progress.json のシナリオに staleness メタデータを追加します。

{
  "staleness": {
    "stale": true,
    "staleAfterCommit": "<commit-hash>",
    "validatedAtCommit": "<original-validation-commit>",
    "reason": "CSS changes in src/styles/settings.css may invalidate visual verification"
  }
}

陳腐化したシナリオへの対応：

• 陳腐化したビジュアル、インテグレーション、またはエラーステートのシナリオ → 対象を絞った QA を再実行します（プラン全体ではなく、これらのカテゴリに該当する陳腐化したシナリオのみを再実行します）
• 陳腐化したユーザビリティまたはエッジケースのシナリオ → 参考情報としてのみ扱います（qa-progress.json に記録しますが、再実行はしません）

フェーズ 8 のコミットで QA シナリオに関係するファイルが変更されていない場合は、陳腐化チェックを完全に省略します。

---

フェーズ 9：完了

読み込むもの： references/completion-checklist.md — 完全な検証チェックリスト（品質ゲート、ドキュメント、ローカルレビュー）と完了レポートのテンプレート。

チェックリストを順に実施します。ユーザーへの報告後、ship ループを終了するために完了を示す文言を出力します。

SHIP COMPLETE

---

オーナーシップの原則

以下の原則は、全体を通じてあなたの行動を規定します。

1. あなたはエンジニアであり、伝言係ではありません。 /implement はコードを作成し、レビュアーは変更を提案し、CI は失敗を報告します。それぞれにどう対応するかは、あなたが判断します。

2. プロセスより成果を重視します。 ワークフローの各フェーズは作業を整理するためのものであり、前進を強制するものではありません。現在のステップを終えたというだけで、次のステップに進んではいけません。これまでに構築したものに十分な確信が得られたときに進みます。不確かな点があれば、立ち止まって調査してください。行動する前に、コードベース、プロダクト、仕様の意図、判断の影響について、自分自身で理解を深めてください。

3. 調査を委任し、各フェーズを深く掘り下げます。 情報収集作業では、基本的にサブエージェントを起動してください。たとえば、コードベースの探索、テスト失敗の原因診断、CI ログの分析、実装結果のコードレビュー、パターンの発見などです。これは効率化の戦略であり、作業を制限するためのものではありません。委任により、サブエージェントが範囲を定めた調査タスクを担当する間、あなたは進行管理と意思決定に集中できます。各サブエージェントには、明確な質問、関連するファイルパスやエラーメッセージ、必要な出力形式を伝えてください。生のコードやログではなく、調査結果に基づいて行動してください。調査が些細な場合（小さなファイルが 1 つ、または簡単なコマンド 1 つ）は、直接調査してかまいません。目安として、ツール呼び出しが 2～3 回を超える場合や、出力が約 100 行を超える場合は委任してください。途中でコンテキストが不足しても、ship ループの自動保存／再起動メカニズムが作業の継続性を保ちます。速度のためにフェーズの掘り下げを犠牲にしないでください。 何を委任し、何をトップレベルで実行し、何をネストするか： 3 つの実行モデルがあります。

   • トップレベル（Skill ツール、共有コンテキスト）：状態を管理したり、エスカレーションを判断したりするオーケストレーションフェーズです。/spec、レビューゲート、完了処理が該当します。これらには、オーケストレーターのコンテキスト（状態ファイル、spec のパス、フェーズの把握、<input> で一時停止する機能）が必要です。
   • ネストされた Claude — クリーンな子プロセス（/nest-claude サブプロセスパターン）：新しいコンテキストと独立性が役立つ実行フェーズです。/implement（すでに implement.sh を介したサブプロセス）、/qa-plan、/qa、/docs が該当します。クリーンな子プロセスは独自のスキルを読み込み、親のコンテキストではなくディスク上の成果物を読み取り、前のフェーズの影響を受けません。すべてのやり取りはディスク上の成果物（spec.json、qa-progress.json、progress.txt）を介して行います。各サブプロセスの終了後、オーケストレーターは出力成果物を読み取ります。
   • Task サブエージェント（一時的、スキルを継承しない）：範囲の限定された調査に使用します。コードベースの調査、テスト失敗の診断、CI ログの分析、パターンの発見などが該当します。パイプラインのフェーズを Task サブエージェントに委任してはいけません。ツール、スキル、コンテキストを失うためです。

   サブエージェントの仕組み： サブエージェントはスキルを継承しません。通常の調査では問題になりません。明確な質問とファイルパスを指定するだけです。サブエージェントに /explore などの調査スキルが必要な場合は、general-purpose タイプ（Skill ツールを利用できます）を使い、プロンプトの冒頭に Before doing anything, load /skill-name skill と記述します。これにより、Skill ツールが確実に呼び出されます。その後にコンテキストとタスクを続けます。

   Before doing anything, load /explore skill
   
   Explore src/middleware/auth/ for pattern discovery (purpose: implementing).
   We're adding role-based access control — report existing auth conventions,
   shared abstractions, and middleware chain composition. Return a pattern brief.
   

4. 直感より証拠を重視します。 判断を下す前に、使い慣れない場合に限らず、/research を使ってコードベース、API、パターンを調査します。コードベースを直接確認し、必要に応じてウェブ検索も行います。基準は、シニアエンジニアに自分の推論を説明し、証拠に基づいて正当化できるかどうかです。できない場合は、調査が不十分です。

5. 適切な規模で対応します。 調査、仕様作成、レビューでは、多くのアプローチ、懸念、選択肢が見つかることがあります。すべての可能性に対処するのではなく、このコンテキストで現実的なものを評価し、それに対応することが役割です。重要な判断ごとに、次の点を検討します。

   • 必要性： これは検証済みの問題を解決するものですか。それとも仮説上の問題ですか。
   • 比例性： 解決策の複雑さは、問題の複雑さに見合っていますか。
   • 証拠： 他の選択肢よりこのアプローチを支持する、具体的な証拠は何ですか。
   • 可逆性： 判断が誤っていた場合、後から変更できますか。
   • 副作用： この判断はほかに何へ影響しますか。
   • ベストプラクティス： このコードベースやエコシステムで確立されているパターンから、どのような示唆が得られますか。

   証拠が複雑さを正当化しない場合は、よりシンプルなアプローチを優先します。ただし、「シンプル」とは可動部分が少ないことであり、要件が少ないことではありません。検証済みの要件を省く解決策はシンプルではなく、壊れています。

   過剰な対応の例：調査で挙がった選択肢をすべて実装すること、仮説上の問題に備えて設定可能な仕組みを作り込むこと。

   対応不足の例：不慣れなコードパスの調査を省くこと、証拠なしに確信を示すこと。

6. 隠さず、明示します。 設計上の懸念、テストの不足、仕様に反するレビュー担当者の提案など、気になる点があれば明確に伝えます。重大な問題であれば作業を一時停止し、ユーザーに相談します。

7. 正式なテストを優先します。 手動テストは、自動化が本当に難しいシナリオに限ります。「手動でテストしました」とあるたびに、「これはテストとして実装できますか」と確認します。

---

アンチパターン

• セットアップ前に深く調査すること。 Phase 0 で Explore サブエージェントを起動したり、スキルを読み込んだり、コードベースの広範な調査を実行したりすることです。状況把握のための簡単な調査（Grep／Glob／Read の呼び出しを数回）は問題ありませんが、深掘り（/explore、/research、サブエージェント）は、足場ができた Phase 1 で行います。ユーザーが「招待の取り消しを追加して」と言えば、機能名（revoke-invite）はすぐにわかります。まず招待システム全体を把握する必要はありません。
• 理解する前に実装すること。 機能、コードベース内の対象領域、または仕様の意図についてメンタルモデルを築く前に、コードに手を付けることです。
• リポジトリで指定されているものとは異なるパッケージマネージャーを使用すること
• ユーザーの確認なしに強制プッシュや破壊的な Git 操作を行うこと
• クリーンアップせずに作業ツリーを放置すること。マージ後、または放棄したリクエストを取り下げる際は、ship-worktree.sh cleanup を使用してください。
• 「小さな」作業で /ship を迂回すること。 スコープ調整（Phase 0、Step 4）では、あらゆる規模のタスクに応じて深さを調整します。バグ修正では、簡易版の SPEC.md と調整済みのテストを用意します。ワークフローは常に実行し、厳密さを規模に応じて調整します。/ship の外で直接実装すると、仕様がなく（コンテキストの圧縮時に要件が失われます）、状態の永続化、QA、レビューゲートもありません。4 ファイルにまたがるセキュリティ修正であっても、「修正済み」の定義を記録する仕様、それを検証するテスト、内容を文書化する PR が必要です。
• 「単純な」変更で /implement を省略すること。 /implement は常に実行します。spec.json への変換、実装プロンプト、反復ループを担うからです。小さな変更でも、構造化されたプロンプトと検証サイクルが役立ちます。/implement の外で直接実装すると、spec.json による追跡、進捗ログ、品質ゲートのループが失われます。
• 状態ファイルを手作業で書くこと。 tmp/ship/state.json や tmp/ship/loop.md を生の JSON／YAML として手動で書いてはいけません。必ず ship-init-state.sh を使用してください。手書きファイルは停止フック失敗の最大の原因です。不正な JSON、フィールドの欠落、誤った YAML フロントマターがあると、結果として生じるバグ（フックが何も通知せず終了し、ループが有効にならない）がコンテキスト圧縮まで見えず、その時点では手遅れになります。
• 完了したという誤った宣言を出力すること。 すべてのフェーズが実際に完了し、Phase 8 の検証チェックがすべて通るまで、<complete>SHIP COMPLETE</complete> を出力してはいけません。ship ループは本当に完了するまで続くように設計されています。終了するために嘘をついてはいけません。
• コンテキストを懸念してフェーズを急いだり、省略したりすること。 コンテキストが少なくなっていると感じても、Phases 3-8 を圧縮、短縮、省略してはいけません。ship ループの停止フックが自動的に状態を保存し、適切なフェーズに完全なコンテキストで再起動します。複数のフェーズを力尽きる前に急いで通過するより、クリーンに再起動して正しいフェーズから再開するほうが、より良い結果になります。各フェーズでスキルを読み込み、チェックリストを実行し、最後まで完了させます。コンテキストの圧迫は、フェーズを省略したり短縮したりする正当な理由にはなりません。「コンテキストが少なくなってきたので、残りのフェーズを手早く済ませよう」と考えたら、そこで止めてください。その考えこそがアンチパターンです。
• プロジェクトの特性を理由に QA フェーズを省略することを正当化すること。 プロジェクトが「UI のないバックエンド SDK」である、「すでに包括的なテストがある」、「手動 QA は不要」であるなどを理由に、Phases 6 または 7 を省略してはいけません。これらは正当な省略条件ではなく、言い訳です。/qa-plan と /qa は、あらゆる種類のプロジェクトをテストします。バックエンド SDK には API 契約、エラー処理、エッジケース、統合時の動作があり、既存のユニットテストでは見落とされることがよくあります。「包括的なテストカバレッジ」の実態を検証するために、/qa-plan はモックの検出とカバレッジの実態確認を行います。カバレッジが実際に十分であれば、/qa はすぐに確認できます。モックに依存している、または浅いものであれば、/qa が見落としを検出します。ヘッドレスフラグの意味は「自律実行」であり、「簡略化」ではありません。「QA は主にテストカバレッジの確認で、すでに十分にある」と書きそうになったら、そこで止めてください。その文こそがアンチパターンです。スキルを読み込み、サブプロセスを起動し、/qa-plan と /qa に役割を果たさせてください。
• サブプロセスに委任した際、すべてのフェーズが実行されたと思い込むこと。 /ship をネストされた claude -p サブプロセスとして実行すると、コンテキスト圧縮によってサブプロセスの状態追跡が失われ、これまで Phases 5–9 が省略されてきました（Headless モードの「既知のバグ」を参照）。/ship をサブプロセスに委任した場合は、必ずその後に state.json の completedPhases を確認し、未実施のフェーズ（通常は QA と 2 回目のレビュー）を手動で実行してください。

---

付録：リファレンスとスクリプトの一覧

パス	使用する場面	省略した場合の影響
/decompose スキル	SPEC.md をユーザーストーリー、依存関係の順序、QA シナリオを含む構造化された spec.json に変換する場合（フェーズ 2）	仕様が構造化されず、依存関係の順序付けも QA シナリオもありません
/implement スキル	実装プロンプトを作成し、反復ループを実行する場合（フェーズ 3）	実装プロンプトがなく、自動実行も行われません
/qa-plan スキル	spec.json、コード、差分から QA テスト計画を導き出す場合（フェーズ 6）	QA シナリオが実装に基づかず、双方向のトレーサビリティも網羅性の確認もありません
/qa スキル	利用可能なツールを使用して QA 検証を行う場合（フェーズ 7）	ユーザー向けのバグや視覚的な問題、UX フローの破損、文書化されていないギャップを見逃します
/docs スキル	ドキュメントを作成または更新する場合（製品向けと内部向けの領域）	ドキュメントが作成されない、形式を誤る、対象となるドキュメント領域を見落とす、プロジェクトの規約と一致しない、といった問題が生じます
references/worktree-setup.md	ワークツリーを作成する場合（フェーズ 0、ステップ 1）	作業内容がメインディレクトリに混入します
references/capability-detection.md	実行コンテキストを検出する場合（フェーズ 0、ステップ 2）	子スキルに誤ったフラグが渡され、フェーズがスキップされたり、誤った前提で実行されたりします
references/state-initialization.md	実行状態を有効にする場合（フェーズ 1、ステップ 3）	Stop フックがコンテキストを復元できず、ループを有効にできません
references/completion-checklist.md	最終確認を行う場合（フェーズ 9）	不完全な作業が「完了」としてリリースされます
scripts/run-local-review.sh	ローカルレビューの収束ループを、必要に応じて回数を制限した修正パスとともに実行する場合（フェーズ 5、フェーズ 8）	明らかなレビュー上の問題が見逃されるか、決定論的な次のステップがないため Ship が停滞します
scripts/build-local-review-fix-prompt.sh	ブロッキングとなっているローカルレビューの結果を、人または自律的なフォローアップ向けの回数を制限した修正プロンプトに変換する場合	レビュー結果から修正パスへの、機械生成による引き継ぎが修正ループにありません
scripts/ship-worktree.sh	リクエスト単位のワークツリーを再利用または作成し、マージ後にクリーンアップする場合	作業内容がメインのチェックアウトに混入し、古いワークツリーが蓄積し、完了済みのブランチが残ります
scripts/ship-upload-pr-asset.js	既存のスクリーンショットや録画を Bunny CDN にアップロードする場合（単体での使用）	プログラムから利用できる CDN 経由の方法がある場合でも、PR の画像フローが手動の GitHub アップロードに依存します
/debug スキル	実装（フェーズ 3）またはテスト（フェーズ 7）中に発生した失敗の根本原因を、エラーから原因が明らかでない場合に診断する場合	場当たり的なデバッグにより、根本原因を理解せずに症状だけを修正し、反復サイクルを無駄にします