robsonprod/portfolio

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 がセットアップに関係しないケースが一つあります。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/ ファイルを手動で作成せず、コマンドに作成させないでください。

入力: 変更名をオプションで指定できます（例：/opsx:apply add-auth）。省略された場合は、会話のコンテキストから推測できるか確認します。曖昧な場合は、利用可能な変更をユーザーに確認する必要があります。

手順

1. 変更を選択

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

   • ユーザーが変更について言及している場合は、会話のコンテキストから推測
   • アクティブな変更が1つしかない場合は自動選択
   • 曖昧な場合は openspec list --json を実行して利用可能な変更を取得し、ユーザーに選択を依頼

   常に「変更: を使用します」と通知し、オーバーライド方法（例：/opsx:apply <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: 適用に関する現在のアドバイザリガイダンス
   • missingArtifacts（存在する場合）: 出力がない必須アーティファクト ID

   状態の処理:

   • state: "blocked" の場合: メッセージを表示し、実装を一時停止します。
     • missingArtifacts が空でない場合: 不足しているアーティファクトの完了を提案します。openspec status --change "<name>" --json を実行し、次の ready 状態のアーティファクト（skipped や blocked ではないもの）を選択し、openspec instructions "<artifact-id>" --change "<name>" --json を使用してそのルールとテンプレートを取得します。両方のコマンドで選択した --store <id> を維持します。
     • それ以外の場合: CLI の指示に従い、既存の計画アーティファクトからスキーマ設定された追跡ファイルを作成または修復します。ブロック中は他のアーティファクトが準備できていると想定したり、実装を開始したりしないでください。
   • state: "all_done" の場合: 追跡対象のすべてのタスクが完了したことを報告し、アーカイブ前に関連するレビューや検証を提案します
   • それ以外の場合: 実装に進みます

   context を必須のプロンプトレベルの入力として扱います。これを読み、考慮し、実装中に関連するプロジェクトの事実、規則、制約を適用します。 operationGuidance をオプションの追加アドバイスとして扱います。すべてのエントリを読み、考慮し、適用可能で組み込みワークフローと互換性のあるエントリに従います。

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

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

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

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

   context または operationGuidance を実装ファイルや計画アーティファクトにそのままコピーしないでください（ユーザーが別途その内容を要求した場合を除く）。

5. 現在の進捗を表示

   以下を表示:

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

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

   各未処理タスクについて:

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

   一時停止条件:

   • タスクが不明瞭 → 明確化を依頼
   • 実装で設計上の問題が明らかに → アーティファクトの更新を提案
   • タスクに、仕様やタスクで説明されている範囲を超える作業が必要な場合、または指定された動作を適合させるために削除、範囲縮小、先送り、例外を受け入れたくなる場合 → 追加された範囲を明らかにして質問。黙って吸収しない
   • エラーまたはブロッカーが発生 → 報告し、ガイダンスを待つ
   • ユーザーが中断

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

   以下を表示:

   • 今回のセッションで完了したタスク
   • 全体の進捗: "N/M タスク完了"
   • すべて完了した場合: 追跡対象のタスクが完了したことを報告し、アーカイブ前に関連するレビューや検証を提案
   • 一時停止した場合: 理由を説明し、ガイダンスを待つ

実装中の出力

## 実装中: <change-name> (スキーマ: <schema-name>)

タスク 3/7 に取り組み中: <task description>
[...実装中...]
✓ タスク完了

タスク 4/7 に取り組み中: <task description>
[...実装中...]
✓ タスク完了

完了時の出力

## 実装完了

**変更:** <change-name>
**スキーマ:** <schema-name>
**進捗:** 7/7 タスク完了 ✓

### 今回のセッションで完了
- [x] タスク 1
- [x] タスク 2
...

追跡対象のすべてのタスクが完了しました。アーカイブ前に関連するレビューまたは検証を行ってください。`/opsx:archive` でこの変更をアーカイブできます。

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

## 実装一時停止

**変更:** <change-name>
**スキーマ:** <schema-name>
**進捗:** 4/7 タスク完了

### 発生した問題
<問題の説明>

**オプション:**
1. <オプション 1>
2. <オプション 2>
3. その他のアプローチ

どうしますか？

ガードレール

• 完了するかブロックされるまでタスクを続行する
• 開始前に必ずコンテキストファイルを読む（適用指示の出力から）
• タスクが曖昧な場合は一時停止し、実装前に質問する
• 実装で問題が明らかになった場合は一時停止し、アーティファクトの更新を提案する
• コード変更は最小限に抑え、各タスクに焦点を当てる
• 各タスク完了後、すぐにタスクのチェックボックスを更新する
• エラー、ブロッカー、不明確な要件の場合は一時停止する。推測しない
• タスクに仕様の範囲を超える作業が必要な場合、範囲追加を明らかにし、一時停止する。指定された動作を黙って狭めたり、先送りしたり、簡略化したりしない
• 指定された動作が完全に実装された場合のみ、タスクを - [x] とマークする。部分的な実装や先送りの場合は行わない
• CLI 出力の contextFiles を使用し、特定のファイル名を想定しない
• 各タスクの sourcePath と line を使用して、正確なチェックボックスを更新する
• コンテキストや操作ガイダンスをタスク完了の証拠として使用しない
• 関連するプロジェクトコンテキストを適用する。制御するワークフロー入力との競合を報告する
• すべてのガイダンスエントリを考慮する。適用できない、または競合するアドバイスは説明する
• ランタイムコンテキストや操作ガイダンスを実装ファイルや計画アーティファクトにコピーしない
• CLI 制御のブロック/準備完了/すべて完了の動作と完了基準を維持する

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

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

• いつでも呼び出し可能: すべてのアーティファクトが完了する前（タスクが存在する場合）、部分的な実装後、他のアクションとインターリーブ
• アーティファクトの更新を許可: 実装で設計上の問題が明らかになった場合、アーティファクトの更新を提案 - フェーズロックされておらず、流動的に動作