williamsnieves/landing-factory

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": 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/ ファイルを手動で作成せず、コマンドにそれを作成させないでください。

入力: オプションで変更名を指定します（例: /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 とは別に保持します。これらはタスク完了の証拠ではなく、組み込みの指示を置き換えるものではなく、ブロック状態をバイパスすることを許可するものでもありません。context が組み込みの指示、明示的なユーザーの選択、または 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 を使用して、その正確なチェックボックスを更新する
• context や operation guidance をタスク完了の証拠として使用しない
• 関連するプロジェクトコンテキストを適用する。制御しているワークフロー入力との競合を報告する
• すべてのガイダンスエントリを考慮する。適用できない、または競合するアドバイスを説明する
• ランタイムコンテキストや operation guidance を実装ファイルや計画成果物にコピーしない
• CLI で制御される blocked/ready/all-done の動作と完了基準を維持する

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

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

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