openspec-update-change

既存の変更の計画アーティファクトを改訂し、一貫性を保ちます。コードは決して編集しないでください。

ストアの選択： ユーザーがストアを指定した場合（ストアとは、このマシンに登録されている独立した OpenSpec リポジトリです）、または作業対象がストア内にある場合は、openspec store list --json を実行して登録済みのストア ID を確認し、仕様と変更を読み書きするコマンド（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）に --store <id> を渡してください。選択したら、以降のワークフローでは --store <id> を常に適用してください。以下に示す、ストアを指定していないコマンド例はすべて省略形です。実行する前にフラグを追加してください。たとえば、以下に示すストア未指定の形式ではなく、openspec status --change "<name>" --json --store "<id>" を実行します。ほかのコマンドはこのフラグを受け付けません。コマンドが表示するヒントには、すでにフラグが含まれています。後続のコマンドでもそのまま付けてください。ストアを指定しない場合、コマンドは最も近いローカルの openspec/ ルートを対象にします。

プロジェクトの確認： ここで説明する手順は、OpenSpec をすでに使用しているプロジェクトを対象とします。最初に何かを書き込む手順（new change、archive、sync specs、またはアーティファクトファイルの作成）を実行する前に、プロジェクトにルートがあることを確認してください。openspec list --json を実行し（ストアを選択している場合は、そのストアがルートとなるため --store <id> を付けます）、root を読み取ります。root オブジェクトがあれば、プロジェクトはセットアップ済みです。"root": null は未セットアップを意味します。ここに openspec/ ディレクトリがなく、openspec new change などの書き込み操作によって副作用として作成される状態です。このコマンドはゼロ以外の終了コードも返しますが、それが正常な結果であり、CLI の故障ではありません。再試行したり回避策を講じたりせず、JSON を確認してください。

status のエラーメッセージが Declared in または Invalid store declaration in で始まり、このプロジェクトの openspec/config.yaml（または config.yml）を示している場合、"root": null はセットアップに関する問題ではありません。このプロジェクトは、宣言されているもののこのマシンでは解決できないストア（未登録のストア、または書式が不正な store: 行）を通じて OpenSpec を使用しています。未初期化と判断して以下の分岐をスキップしてはいけません。書き込みの前に停止し、そのエラーの message と fix をユーザーに提示してください。

それ以外でルートがない場合、この先の対応はワークフローの開始方法によって異なります。

• 自動選択： ユーザーが OpenSpec に言及せず、このスキル名も指定せず、スラッシュコマンドも実行していないのに、自分でこのワークフローを選択した場合です。OpenSpec の使用をやめ、OpenSpec がインストールされていない場合と同様に通常のリクエストへ回答してください。セットアップを求めたり、OpenSpec のセットアップについて言及したりしないでください。
• OpenSpec を明示的にリクエスト： ユーザーが OpenSpec に言及した、このスキル名を指定した、またはそのスラッシュコマンドを実行した場合です。書き込みを行う前に停止し、どう進めるかを尋ねてください。プロジェクトをセットアップする（openspec init）、既存のストアを対象にする（--store <id>）、または今回のリクエストでは OpenSpec を使わずに進める、のいずれかを提示します。返答を待ってください。

どちらの分岐でも、副作用としてルートを作成してはいけません。ユーザーから依頼されるまで openspec init を実行せず、openspec/ ファイルを手動で作成せず、コマンドによって作成されることも避けてください。

入力： 変更名は任意で指定できます。省略された場合は、会話の文脈から推測できるか確認してください。曖昧な場合は、利用可能な変更を提示するよう必ず求めてください。

このワークフローでは既存のアーティファクトを改訂します。まだ存在しないアーティファクトを作成する場合は、/openspec-continue-change を使います。

手順

1. 変更を選択する

   名前が指定されている場合は、それを使用します。指定されていない場合：

   • ユーザーが変更に言及していれば、会話の文脈から推測します
   • アクティブな変更が 1 つだけなら、それを自動選択します
   • 曖昧な場合は、openspec list --json を実行して、最終更新日時の新しい順に並んだ利用可能な変更を取得し、ユーザーに選択を求めます

   選択を求めるときは、最終更新日時が新しい変更の上位 3～4 件を選択肢として提示し、以下を表示してください。

   • 変更名
   • ステータス（例：「0/5 タスク」、「完了」、「タスクなし」）
   • 最終更新日時から分かる更新時期（lastModified フィールドに基づく）

   最終更新日時が最も新しい変更には「（おすすめ）」を付けてください。ユーザーが更新したい変更である可能性が高いためです。 常に「Using change: 」と、上書き方法（例：/openspec-update-change <other>）を案内します。

2. 変更の成果物を取得する

   openspec status --change "<name>" --json
   

   JSON を解析して現在の状態を把握します。応答には以下が含まれます。

   • schemaName：使用中のワークフロースキーマ（例：「spec-driven」）
   • artifacts：ステータス（「done」、「skipped」、「ready」、「blocked」）を含む成果物の配列
   • isPlanningComplete：計画用成果物がすべて完了しているかを示すブール値。古い CLI バージョンでは、同じ値が isComplete として公開されています。
   • planningHome、changeRoot、artifactPaths、actionContext：パスと対象範囲のコンテキストです。リポジトリ内のパスだと決めつけず、これらを使用してください。

   成果物の ID とパスはアクティブなスキーマから取得します。推測したり、ハードコードされた成果物名に基づいて分岐したりしないでください。カスタムスキーマも変更なしで動作する必要があります。

   編集するファイルは artifactPaths.<id>.existingOutputPaths にある、ディスク上に実在するファイルです。グロブ成果物（例：specs/**/*.md）はすでに展開されています。また、ステップ 4 で一部のみが入力されたグロブ成果物の配下に置くことが確認された具体的なパスも含まれます。resolvedOutputPath には書き込まないでください。グロブ成果物の場合、これは実在するファイルではなく、依然としてグロブパターンです。

3. 依頼内容を把握する

   • ユーザーが具体的な変更（「設計で X を使うようになりました」など）を求めている場合は、それを編集の出発点にします。
   • 「更新して」や「整合性を取って」とだけ依頼された場合は、整合性レビューとして扱います。既存の成果物を読み、相互に矛盾、抜け、重複がないか確認します。

4. 読み取りと突き合わせ

   • リクエストが触れる成果物と、変更における他の既存の成果物を読み取ります。
   • 要求された編集はファイルではなく会話の中で下書きします。それが何を変更するのかを正確に洗い出してください。すべての書き込みはステップ 5 が担います。その後、下書きした編集に対して、他のすべての既存の成果物をあらゆる方向から照合してください。後続の成果物への編集が、先行する成果物の改訂を必要とすることがあり、逆方向だけではありません。ビルド順は有用な読み取り順であり、どの成果物を改訂できるかを制約するものではありません。
   • 現在不整合、欠落、または矛盾しているものをすべて記録します。
   • すでに存在するファイル（existingOutputPaths）への改訂を提案します。成果物に既存の出力ファイルがなく、ステータスが ready または blocked の場合は、その旨を記録し、それらを作成するために /openspec-continue-change をユーザーに案内します。skipped の成果物はそのままにし、欠落しているものとして扱ったり、continue ワークフローに先送りしたりしないでください。
   • glob 成果物（例: specs/**/*.md）は、少なくとも 1 つのファイルが一致した時点で done とマークされ、continue ワークフローは ready の成果物のみを処理します。existingOutputPaths が空でない glob 成果物について、突き合わせで欠落ファイルが特定された場合:
     1. openspec instructions "<artifact-id>" --change "<name>" --json を実行し、その instruction と template を使用します。context と rules は制約として扱い、ファイルにコピーしないでください。instructions が skipped: true を報告した場合は、ファイルを作成しないでください。現在の依存ファイルをディスクから読み取り、必須の非スキップ依存ファイルが欠落している場合は、停止してユーザーにまずそれを復元するよう依頼してください。
     2. changeRoot 内で、artifactPaths.<id>.outputPath に一致し、まだ存在しない具体的なパスを選択します。シンボリックリンクされた親ディレクトリを解決した後も、それが changeRoot 内にとどまることを確認します。glob の resolvedOutputPath は有効なターゲットではありません。
     3. 新しいファイルをステップ 5 の提案された改訂に含め、ユーザーが確認した後にのみ作成します。
     4. 確認後、作成の直前に、ステータスと instructions を更新します。成果物がまだスコープ内にあり、スキップされておらず、部分的に populate されていることを確認します。上記の具体的なパスのチェックを繰り返します。
     5. ターゲットがすでに存在する場合に失敗する作成操作を使用します。instruction が作成を別のスキルやコマンドに委譲する場合は、それが確認済みのパスとこれらのガードレールを遵守できるときにのみ呼び出します。それ以外の場合は停止します。いずれかのチェックが失敗した場合、または確認済みの下書きがもはや有効でない場合は、既存のコンテンツを置き換えたり別のパスを選んだりするのではなく、停止してユーザーと突き合わせを行ってください。
   • 変更がすでに首尾一貫している場合は、その旨を伝え、改訂を提案しないでください。

5. 確認と適用を、成果物を 1 つずつ

   • このステップが、このワークフローにおけるすべての成果物の書き込みを実行します。これより前のステップで成果物を編集することはありません。
   • 各提案された改訂とその理由を提示します。これにはステップ 4 で下書きした要求された編集も含みます。ユーザーが確認した後にのみ書き込みます。
   • ユーザーが改訂を拒否した場合は、それを書き込まないでください。その成果物は変更しないままにします。
   • 大幅な書き直しが必要な場合は、まずその成果物の rules と template を取得します:

     openspec instructions "<artifact-id>" --change "<name>" --json
     

6. 次のステップを案内する（ガイダンスのみ - 決して実行しないでください）

   • existingOutputPaths が空で、ステータスが ready または blocked の成果物 -> それらを作成するために /openspec-continue-change を提案します。
   • 変更がすでに実装済み（タスクがチェック済み / すでに適用済み）-> コードが改訂された計画と一致しなくなっている可能性があります。デルタをコードに反映するために /openspec-apply-change を提案します。
   • すべて完了し、実装済み -> /openspec-archive-change を提案します。

出力 各回の実行後、次の内容を示してください。

• 修正した成果物（および却下した修正案）
• 一部がすでに作成されていた glob 成果物の下に作成したファイル
• /openspec-continue-change に委ねた内容（ファイルがまだなく、ステータスが ready または blocked の成果物。skipped の成果物は対象外）
• 変更の現在の状況と、次に推奨するコマンド

ガードレール

• 計画成果物のみを対象とし、実装コードは絶対に編集しないでください。改訂した計画がコード変更を示唆する場合は、作業を中止し、/openspec-apply-change を案内してください。
• openspec status が報告した成果物 ID とパスを使用してください。ハードコードされた成果物名に基づいて分岐してはいけません。
• existingOutputPaths に含まれる具体的なファイルと、手順 4 で許可された、一部が作成済みの glob 成果物の下にあることを確認した具体的なパスのみを編集してください。glob の resolvedOutputPath には書き込まないでください。
• 作業のビルドフロンティアを先に進めてはいけません。成果物の existingOutputPaths が空で、ステータスが ready または blocked の場合は、/openspec-continue-change の担当です。skipped の成果物には手を加えないでください。新規ファイルを作成できるのは、existingOutputPaths が空でない glob 成果物の下にあることを確認した具体的なパスに限られます。
• 書き込む前に、すべての編集についてユーザーの確認を得てください。
• リクエストによって変更の意図が変わる場合は、変更を新規に開始するよう /openspec-new-change を案内してください（「更新するか、新規に開始するか」の判断基準）。