openspec-ff-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": null の場合は、セットアップされていません。ここに openspec/ ディレクトリがなく、openspec new change などの書き込み操作を実行すると、副作用として作成されます。このコマンドは 0 以外の終了コードも返しますが、それは故障した CLI ではなく、セットアップされていないことを示しています。再試行したり回避策を講じたりせず、JSON を確認してください。

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

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

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

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

入力： ユーザーのリクエストには、変更名（kebab-case）または作成したいものの説明が含まれている必要があります。

手順

1. 明確な入力がない場合は、何を作成したいか尋ねます

   自由回答形式で、選択肢を提示せずにユーザーに尋ねます。

   "どのような変更に取り組みたいですか？作成または修正したいものを説明してください。"

   説明から kebab-case の名前を導き出します（例：「ユーザー認証を追加する」→ add-user-auth）。

   重要： ユーザーが作成したいものを理解するまでは、先に進まないでください。

2. 変更ディレクトリを作成します

   openspec new change "<name>"
   

   これにより、CLI が解決した計画用ディレクトリに、ひな形を含む変更が作成されます。

3. アーティファクトのビルド順を取得する

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

   JSON を解析して、次の情報を取得します。

   • applyRequires：実装前に必要なアーティファクト ID の配列（例：["tasks"]）
   • artifacts：すべてのアーティファクトの一覧。それぞれに status と requires のエッジ（直接依存するアーティファクト ID）が含まれます
   • planningHome、changeRoot、artifactPaths、actionContext：パスとスコープに関する情報です。リポジトリ内のパスを想定するのではなく、これらを使用してください。

4. 必須セット内のすべてのアーティファクトを作成する

   アーティファクトの進捗を管理するため、ToDo リストを使用します。

   依存関係の順にアーティファクトを処理します（保留中の依存関係がないものを先に処理します）。

   a. ready（依存関係が満たされている）の各アーティファクトについて：

   • 手順を取得します。

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

   • 手順を示す JSON には次の内容が含まれます。
     • context：プロジェクトの背景情報（あなたへの制約です。出力に含めないでください）
     • rules：アーティファクト固有のルール（あなたへの制約です。出力に含めないでください）
     • template：出力ファイルに使用する構成
     • instruction：このアーティファクトの種類に固有のスキーマガイダンス
     • skipped／warning：変更で skip_specs が宣言され、このアーティファクトを作成してはならない場合に表示されます。作成を中止し、別のアーティファクトを選んでください
     • resolvedOutputPath：書き込み先の解決済みパスまたはパターン
     • dependencies：コンテキストとして読み込む、作成済みの依存アーティファクト
   • 作成済みの依存ファイルをコンテキストとして読み込みます。以前の会話で確認済みでも、必ずディスクから再読み込みしてください（ユーザーが編集している可能性があります）。
   • ドラフトを作成する前に、関連するプロジェクトを調査します：最初に context と rules を読み、その後 openspec/ の外にある関連する実装、近接するテスト、設定、ドキュメントを調査します。調査は読み取り専用とし、変更の範囲に応じたものにしてください。得られた内容は後続のアーティファクトでも再利用し、必要に応じて追加で調査します。
     • リクエストとプロジェクトのコンテキストから対象プロジェクトを特定します。計画の保存先がコードと別の場所にある場合もあります。対象が不明確であれば、ユーザーに確認してください。グリーンフィールドの変更やコード以外の変更の場合は、利用可能な構成と関連ドキュメントを調査します。ソースを利用できず、それが計画に重大な影響を及ぼす場合は、その制約を伝えて確認を求めてください。
     • 見つかった内容に基づいて、スコープ、アプローチ、タスクを定めます。確認できた動作と仮定・提案する内容を区別し、既存の仕様との矛盾は、どちらが正しいかを独断で決めずに明らかにします。
     • この調査を今すぐ実施し、実装時に行う一般的な「コードベースを調査する」や「計画を立てる」といったタスクを残さないでください。未解決の疑問に対して追加調査が必要な場合は、その内容を具体的に示します。
   • 作成を始める前に出力パスを選択します。resolvedOutputPath が glob の場合は、instruction に従って glob に一致する changeRoot 内の具体的なパスを選びます。シンボリックリンクを解決した後も、親ディレクトリとファイル自体（すでに存在する場合）の両方が changeRoot 内にあることを確認してください。満たさない場合は中止してユーザーに伝えます。それ以外の場合、出力パスは resolvedOutputPath です。
   • instruction フィールドで特定のスキルまたはコマンドに作成が委任されている場合、その出力パスにアーティファクトを書き込める場合に限り実行します。書き込めない場合は中止してユーザーに伝えます。その後、出力パスにアーティファクトファイルが存在することを確認します。
   • それ以外の場合は、template を構成として使用してアーティファクトファイルを作成し、指定された出力パスに書き込みます。
   • context と rules は制約として適用します。ただし、ファイル内に転記しないでください。
   • 簡潔に進捗を表示します。「✓ を作成しました」 b. 必要なセット内のすべてのアーティファクトが存在するまで続けます（apply.requiresだけではありません）
   • 各アーティファクトを作成した後、openspec status --change "<name>" --jsonを再実行します
   • 必要なセットは、applyRequiresと、status --json内のrequiresエッジをたどってそこから到達できるすべてのアーティファクトです。依存関係を再帰的にたどります（spec-drivenではproposal、specs、design、tasksが対象です）。このセット外のアーティファクトには手を加えないでください
   • statusが確認するのはファイルの存在だけです。したがって、applyRequiresのアーティファクトがdoneと表示されていても、依存関係が存在するとは限りません。たとえば、tasks.mdを早期に作成すると、specsが未作成でもtasksはdoneになります。必要なセットを作る際は各アーティファクトのstatusではなく、requiresエッジを使ってください。doneのアーティファクトにも依存先は記載されています
   • status: "skipped"と表示されているアーティファクトは条件を満たしています。この変更では.openspec.yamlでskip_specsが宣言されているため、そのファイルは存在してはいけません。作成しようとしないでください
   • 必要なセット内で不足しているアーティファクトをすべて作成してから、再確認します。アーティファクトを作成すると、ほかのアーティファクトのブロックが解除されることがあります
   • スキップできるのは、statusですでにskippedと報告されている場合、またはアーティファクト自身のinstructionで条件付きとされている場合のみです。openspec instructions <artifact-id> --change "<name>" --jsonを実行し、instructionフィールドで任意と示されている場合（例：「該当する場合にのみ作成」）に限りスキップしてください。spec-drivenのdesign.mdは該当します。specsは、上記のskippedステータスの場合に限り該当し、独自の判断でスキップしてはいけません。ユーザーに伝え、再検討しないでください
   • 依存関係は利用を可能にするものであり、ゲートではありません。条件付きの依存アーティファクトをスキップしたことだけが理由で、必要なアーティファクトがblockedのままでも、そのアーティファクトを作成してください
   • 必要なセット内のすべてのアーティファクトがdone、skipped、または意図的なスキップのいずれかになるまで続けます

   c. アーティファクトの作成にユーザーからの情報が必要な場合（コンテキストが著しく不明瞭な場合）：

   • ユーザーに確認を求めます
   • その後、作成を続けます

5. 最終ステータスを表示する

   openspec status --change "<name>"
   

出力

すべてのアーティファクトを作成した後、以下を要約します。

• 変更名と場所
• 作成したアーティファクトの一覧と簡単な説明、およびスキップした条件付きアーティファクトとその理由
• 準備状況：「実装に必要なすべてのアーティファクトが準備できました。」
• プロンプト：「タスクの作業を開始するには、/openspec-apply-changeを実行するか、実装するよう依頼してください。」

アーティファクト作成のガイドライン

• 各アーティファクトの種類について、openspec instructionsのinstructionフィールドに従ってください。これは、アーティファクト名に馴染みがある場合でも、権威あるガイダンスです
• instructionフィールドで特定のスキルやコマンドを使ったアーティファクトの作成が指示されている場合は、出力先を選択して確認した後、その場所に書き込める場合に限り、直接ファイルに書き込まず、指示された方法を実行してください
• 各アーティファクトに含める内容はスキーマで定義されています。これに従ってください
• 新しいアーティファクトを作成する前に、依存するアーティファクトを読み、コンテキストを確認してください
• 出力ファイルの構成にはtemplateを使い、各セクションを埋めてください
• 重要：contextとrulesはあなたに対する制約であり、ファイルに記載する内容ではありません
  • <context>、<rules>、<project_context>のブロックをアーティファクトにコピーしないでください
  • これらは記述内容の指針ですが、出力には含めないでください

ガードレール

• apply.requiresに記載されたIDだけでなく、applyフェーズが再帰的に依存するすべてのアーティファクトを作成してください
• 新しいアーティファクトを作成する前に、必ず依存するアーティファクトを読み込んでください。会話の記憶ではなく、ディスクから再読み込みしてください（最後に確認してからファイルが変更されている可能性があります）
• コンテキストが著しく不明瞭な場合はユーザーに確認してください。ただし、作業を進めるため、妥当な判断を優先してください
• 同じ名前の変更がすでに存在する場合は、その変更を続行するよう提案してください
• 各アーティファクトを書き込んだ後、次に進む前にファイルが存在することを確認してください