openspec-apply-change

OpenSpec の変更からタスクを実装します。

ストアの選択： ユーザーがストア（このマシンに登録された独立した 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 を確認してください。

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

それ以外の場合、ルートがないときに次に行うことは、このワークフローにどう到達したかによって異なります。

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

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

入力：変更名を指定できます（例：/openspec-apply-change add-auth）。省略された場合は、会話の文脈から推測できるか確認してください。曖昧な場合は、利用可能な変更を必ずユーザーに尋ねてください。

手順

1. 変更を選択する

   名前が指定されている場合は、それを使用します。指定されていない場合は、以下のとおりです。

   • 会話の文脈でユーザーが変更について言及していれば、それを推測します
   • アクティブな変更が 1 つだけなら、それを自動選択します
   • 判断できない場合は、openspec list --json を実行して利用可能な変更を取得し、どれを選ぶかユーザーに尋ねます

   必ず「Using change: 」と、変更方法（例：/openspec-apply-change <other>）を案内してください。

2. ステータスを確認してスキーマを把握する

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

   JSON を解析して、以下を把握します。

   • schemaName：使用するワークフロー（例：「spec-driven」）
   • planningHome、changeRoot、actionContext：計画の範囲と編集上の制約
   • タスクを含む成果物（通常は spec-driven の場合は「tasks」。それ以外は status を確認）

3. 適用手順を取得する

   openspec instructions apply --change "<name>" --json
   

   これは次を返します:

   • contextFiles: アーティファクト ID -> 具体的なファイルパスの配列（スキーマによって異なります - proposal/specs/design/tasks または spec/tests/implementation/docs の可能性があります）
   • 進捗（合計、完了、残り）
   • ステータス、ソースパス、ソース行を含むタスクリスト
   • 現在の状態に基づく動的な指示
   • オプションの context: 選択されたルートからの現在の必須プロジェクト指示入力
   • オプションの operationGuidance: apply に対する現在の助言的ガイダンス
   • missingArtifacts（存在する場合）: 出力のない必須アーティファクト ID

   状態の処理:

   • state: "blocked" の場合: メッセージを表示し、実装を一時停止します。
     • missingArtifacts が空でない場合: /openspec-continue-change を使用してそれらを作成することを提案します。
     • それ以外の場合は、CLI の指示に従って、既存の計画アーティファクトからスキーマで設定されたトラッキングファイルを作成または修復します。ブロックされている間に別のアーティファクトが準備できていると仮定したり、実装を開始したりしないでください。
   • state: "all_done" の場合: 追跡されているすべてのタスクが完了したことを報告し、アーカイブする前に必要に応じてレビューまたは検証を提案します
   • それ以外の場合: 実装に進みます

   context はプロンプトレベルの必須入力として扱います。それを読み、考慮し、 実装中に関連するプロジェクトの事実、規約、制約を適用してください。 operationGuidance はオプションの追加的な助言として扱います。すべての エントリを読み、考慮し、適用可能で組み込みの ワークフローと互換性のあるエントリに従ってください。

   両方のフィールドを、CLI が返す状態、欠落しているアーティファクト、タスク、 進捗、contextFiles、および組み込みの instruction から分離しておいてください。それらは タスク完了の証拠ではなく、組み込みの指示を置き換えるものでもなく、 ブロックされた状態を回避することを許可するものでもありません。context が組み込みの 指示、明示的なユーザーの選択、または CLI が制御する値と競合する場合は、 競合を報告し、制御する値を保持してください。guidance が適用できない場合、またはそれらの制御入力と 競合する場合は、それに従わず、その理由を説明してください。 これらはプロンプトレベルの動作契約であり、強制力のあるチェックではありません。

4. コンテキストファイルを読み込む

   apply 指示の出力で contextFiles の下にリストされているすべてのファイルパスを読み込んでください。 ファイルは使用されているスキーマによって異なります:

   • spec-driven: proposal、specs、design、tasks
   • その他のスキーマ: CLI 出力の contextFiles に従ってください

   ユーザーが別途その内容を求めない限り、context や operationGuidance を逐語的に実装 ファイルや計画アーティファクトにコピーしないでください。

5. 現在の進捗を表示する

   次を表示します:

   • 使用されているスキーマ
   • 進捗: 「N/M タスク完了」
   • 残りのタスクの概要
   • CLI からの動的な指示

6. タスクを実装する（完了またはブロックされるまでループ）

   保留中の各タスクについて:

   • どのタスクに取り組んでいるかを表示する
   • 必要なコード変更を行う
   • 変更を最小限かつ焦点を絞ったものに保つ
   • 編集する前に、返された sourcePath と line のチェックボックスがタスクの説明とまだ一致していることを確認してください。一致しない場合は、apply 指示を再実行し、更新された位置を使用してください
   • 返された sourcePath と line でタスクを完了としてマークします: - [ ] → - [x]
   • apply 指示を再実行し、そのタスクが完了になり、進捗が変化したことを確認します
   • 次のタスクに進みます

   次の場合に一時停止します:

   • タスクが不明確 → 明確化を求める
   • 実装により設計上の問題が明らかになる → アーティファクトの更新を提案する
   • タスクが spec と tasks に記述されている範囲を超える作業を必要とする場合、または仕様された動作に合わせるためにそれを削除、縮小、延期、または例外を容認したくなる場合 → 追加されたスコープを明らかにして質問してください。暗黙のうちに吸収しないでください
   • エラーまたはブロッカーに遭遇 → 報告してガイダンスを待つ
   • ユーザーが中断する

7. 完了または一時停止時にステータスを表示する 表示:

   • このセッションで完了したタスク
   • 全体の進捗: 「N/M タスク完了」
   • すべて完了した場合: 追跡対象のタスクが完了したことを報告し、アーカイブする前に必要に応じてレビューまたは検証を提案する
   • 一時停止した場合: 理由を説明し、指示を待つ

実装中の出力

## Implementing: <change-name> (schema: <schema-name>)

Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete

Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete

完了時の出力

## Implementation Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓

### Completed This Session
- [x] Task 1
- [x] Task 2
...

All tracked tasks are complete. Review or verify the change as appropriate
before archiving. You can archive this change with `/openspec-archive-change`.

一時停止時の出力 (問題が発生した場合)

## Implementation Paused

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete

### Issue Encountered
<description of the issue>

**Options:**
1. <option 1>
2. <option 2>
3. Other approach

What would you like to do?

ガードレール

• 完了するかブロックされるまでタスクを続行する
• 開始前に必ずコンテキストファイルを読む (apply 指示の出力から)
• タスクが曖昧な場合は、実装する前に一時停止して確認する
• 実装によって問題が明らかになった場合は、一時停止して成果物の更新を提案する
• コード変更は最小限に抑え、各タスクの範囲内に収める
• 各タスクを完了した直後にタスクのチェックボックスを更新する
• エラー、ブロッカー、または不明確な要件が発生した場合は一時停止する - 推測しない
• タスクが仕様に記載されている以上の作業を必要とする場合は、追加されたスコープを明示して一時停止する - 仕様に記載された動作を黙って狭めたり、先送りしたり、簡略化したりしない
• タスクを - [x] にするのは、その指定された動作が完全に実装されたときだけであり、部分的に完了しているか先送りされているときではない
• CLI 出力の contextFiles を使用し、特定のファイル名を仮定しない
• 各タスクの sourcePath と行を使用して、その正確なチェックボックスを更新する
• コンテキストや操作ガイダンスを、タスクが完了した証拠として使用しない
• 関連するプロジェクトコンテキストを適用し、制御するワークフロー入力との競合を報告する
• すべてのガイダンス項目を検討し、該当しない、または競合するアドバイスを説明する
• ランタイムコンテキストや操作ガイダンスを実装ファイルや計画成果物にコピーしない
• CLI が制御する blocked/ready/all-done の動作と完了基準を維持する

流動的なワークフローの統合

このスキルは「変更に対するアクション」モデルをサポートします:

• いつでも呼び出し可能: すべての成果物が完成する前 (タスクが存在する場合)、部分的な実装の後、他のアクションと交互に
• 成果物の更新を許可: 実装によって設計上の問題が明らかになった場合は、成果物の更新を提案する - フェーズに固定されず、流動的に作業する