openspec-apply-change

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

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

入力：変更名を指定できます（例：$openspec-apply-change (Codex) or /openspec-apply-change (other agents) add-auth）。省略した場合は、会話の文脈から推測できるか確認します。曖昧な場合や複数の候補がある場合は、利用可能な変更をユーザーに確認する必要があります。

手順

1. 変更を選択する

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

   • ユーザーが変更について言及していれば、会話の文脈から推測します
   • アクティブな変更が 1 つだけの場合は、自動選択します
   • 複数の候補がある場合は、openspec list --json を実行して利用可能な変更を確認し、ユーザーに選択を依頼します

   必ず「Using change: 」と、変更名を上書きする方法（例：$openspec-apply-change (Codex) or /openspec-apply-change (other agents) <other>）を伝えてください。

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

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

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

   • schemaName：使用するワークフロー（例：「spec-driven」）
   • planningHome、changeRoot、actionContext：計画のスコープと編集上の制約
   • タスクを含む成果物（通常は「spec-driven」では「tasks」ですが、その他のスキーマではステータスを確認してください）

3. 適用手順を取得する

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

   これにより、以下が返されます：

   • contextFiles：成果物 ID から具体的なファイルパスの配列への対応（スキーマによって異なり、proposal/specs/design/tasks や spec/tests/implementation/docs などがあります）
   • 進捗（合計、完了、残り）
   • ステータス付きのタスクリスト
   • 現在の状態に応じた動的な指示
   • オプションの context：選択したルートから読み込む、現在必須のプロジェクト指示
   • オプションの operationGuidance：適用時に参照する、現在の助言

   状態ごとの対応：

   • state: "blocked"（成果物が不足）の場合：メッセージを表示し、$openspec-continue-change (Codex) or /openspec-continue-change (other agents) の使用を提案します（インストールされていない場合は、openspec status --change "<name>" --json を実行して次の成果物を確認し、openspec instructions <artifact-id> --change "<name>" --json を実行して作成方法を確認してください）
   • state: "all_done" の場合：完了を伝え、アーカイブを提案します
   • それ以外の場合：実装に進みます

   context は必須のプロンプトレベルの入力として扱います。読み、実装時に関連するプロジェクトの事実、規約、制約を考慮して適用してください。 operationGuidance は追加の任意の助言として扱います。すべての項目を読み、考慮したうえで、適用可能で組み込みのワークフローと両立する項目に従ってください。

   どちらのフィールドも、CLI から返される状態、不足している成果物、タスク、進捗、contextFiles、組み込みの instruction とは区別して扱ってください。これらはタスク完了の根拠ではなく、組み込みの指示に置き換わるものでも、ブロック状態を回避する許可を与えるものでもありません。context が組み込みの指示、ユーザーによる明示的な選択、または CLI が制御する値と矛盾する場合は、その矛盾を報告し、優先される値を維持してください。ガイダンスが適用できない場合や、これらの優先される入力と矛盾する場合は、それに従わず、理由を説明してください。これらはプロンプトレベルの動作上の規約であり、強制可能なチェックではありません。

4. コンテキストファイルを読む apply の指示の出力にある contextFiles に記載されたすべてのファイルパスを読み込みます。 ファイルは使用中のスキーマによって異なります。

   • spec-driven：proposal、specs、design、tasks
   • その他のスキーマ：CLI の出力にある contextFiles に従います

   ユーザーから別途依頼がない限り、context または operationGuidance をそのまま実装ファイルや計画成果物にコピーしないでください。

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

   次の内容を表示します。

   • 使用中のスキーマ
   • 進捗：「N/M tasks complete」
   • 残りのタスクの概要
   • CLI からの動的な指示

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

   未完了のタスクごとに、次の操作を行います。

   • 作業中のタスクを表示する
   • 必要なコード変更を行う
   • 変更を最小限に抑え、対象を絞る
   • tasks ファイルでタスクを完了にする：- [ ] → - [x]
   • 次のタスクに進む

   次の場合は一時停止します。

   • タスクが不明確な場合 → 説明を求めます
   • 実装によって設計上の問題が明らかになった場合 → 成果物の更新を提案します
   • エラーまたはブロッカーが発生した場合 → 報告して指示を待ちます
   • ユーザーが中断した場合

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

   次の内容を表示します。

   • 今回のセッションで完了したタスク
   • 全体の進捗：「N/M tasks complete」
   • すべて完了した場合：アーカイブを提案します
   • 一時停止した場合：理由を説明して指示を待ちます

実装中の出力

## 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 tasks complete! You can archive this change with `$openspec-archive-change (Codex) or /openspec-archive-change (other agents)`.

一時停止時の出力（問題発生時）

## 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 の指示の出力から）コンテキストファイルを読み込みます
• タスクが曖昧な場合は、実装の前に一時停止して質問します
• 実装によって問題が明らかになった場合は、一時停止して成果物の更新を提案します
• コード変更は最小限に抑え、各タスクの範囲に限定します
• 各タスクを完了したら、すぐにタスクのチェックボックスを更新します
• エラー、ブロッカー、要件の不明確さがあれば一時停止し、推測で進めません
• CLI の出力にある contextFiles を使用し、特定のファイル名を想定しません
• タスク完了の根拠として context や operation guidance を使用しません
• 関連するプロジェクトコンテキストを適用し、優先されるワークフロー入力との競合を報告します
• ガイダンスの各項目を検討し、適用できない助言や競合する助言があれば説明します
• 実行時のコンテキストや operation guidance を実装ファイルや計画成果物にコピーしません
• CLI が制御するブロック／準備完了／すべて完了の動作と完了基準を維持します

柔軟なワークフローへの統合

このスキルは、「変更に応じたアクション」モデルをサポートします。

• いつでも呼び出せます：すべての成果物が完成する前（タスクがある場合）、実装の一部が完了した後、他のアクションと交互に実行する場合
• 成果物の更新が可能です：実装によって設計上の問題が明らかになった場合、フェーズに縛られず柔軟に作業を進め、成果物の更新を提案します