openspec-propose

新しい変更を提案します。変更を作成し、すべての成果物を一度に生成します。

計画の範囲：このワークフローで作成するのは計画成果物のみです。このワークフローを選択または開始したユーザーのリクエストは、計画のみを許可するものです。たとえビルドや修正を求めていても、プロジェクトのコードを編集しないでください。計画成果物を作成し終えたら、そこで停止してください。最初のリクエストで実装を求められていても、同じ応答内で実装を開始しないでください。成果物を提示した後、新しいユーザーリクエストがあるまで待ってから、apply ワークフローを開始してください。

スキーマで定義されている成果物を含む変更を作成します。デフォルトの仕様主導スキーマでは、次のとおりです。

• proposal.md（内容と理由）
• specs/<capability-path>/spec.md（システムが実現すべきこと。メインの仕様ではなく、差分）
• design.md（方法）
• tasks.md（実装手順）

<capability-path> は specs/ を基準とした仕様ディレクトリのパスです（例：user-auth、identity/user-auth）。既存の機能のパス全体を維持し、新しい機能にはプロジェクトで確立された構成を採用してください。

ユーザーが実装の準備ができたら、apply ワークフローを明示的に開始する必要があります。

---

ストアの選択： ユーザーがストアを指定した場合（ストアとは、このマシンに登録された独立した 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/ ルートを対象にします。

入力：ユーザーのリクエストには、変更名（kebab-case）またはビルドしたいものの説明を含めてください。

手順

1. リクエストを把握し、重要な曖昧さを明確にする

   明確な入力がない場合は、ユーザーに自由回答形式で質問してください（選択肢は提示しません）。

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

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

   重要：ユーザーが何をビルドしたいのかを把握するまでは、先に進まないでください。

   リクエストに、範囲、外部から確認できる動作、互換性、受け入れ基準に実質的な影響を及ぼす曖昧さがある場合は、変更を作成する前にユーザーへ確認してください。細かな点は妥当な前提を置き、計画成果物に記録してください。

2. ワークフローのスキーマを決定する

   ユーザーが別のワークフローを明示的にリクエストしない限り、設定済みのデフォルトスキーマを使用してください。

   別のスキーマを使用するのは、ユーザーが次のいずれかを行った場合に限ります。

   • 特定のスキーマ名を明示的に指定する → --schema <schema-name> を使用します
   • 「ワークフローを表示して」または「どのようなワークフローがあるか」と尋ねる → 現在の作業ディレクトリで openspec context --json を実行し、権威あるルートを特定します。ユーザーが登録済みのストアを明示的に選択した場合は、openspec context --json --store "<store-id>" を使用します。次に、返された root.path を作業ディレクトリとして openspec schemas --json を実行し、ユーザーに選んでもらいます。これにより、ローカルの store: ポインターまたはグローバルの defaultStore で選択されたルートが維持されます。schemas は --store を受け付けません。context が no_openspec_root のみを報告する場合は、代わりに現在の作業ディレクトリで openspec schemas --json を実行します。このフォールバックは、無効なストアや利用できないストアには使用しないでください。

   それ以外の場合は、設定済みのデフォルトを維持するため、--schema を省略してください。

3. 変更ディレクトリを作成する 以下からスキーマ形式を1つ選択します。登録済みのストアを選択した場合は、そのコマンドと、以下に示す後続の OpenSpec コマンドのうち --store を受け付ける各コマンドに --store "<store-id>" を追加します。

   設定済みのデフォルトを使用する場合：

   openspec new change "<name>"
   

   明示的に指定したスキーマを使用する場合：

   openspec new change "<name>" --schema "<schema-name>"
   

   これにより、CLI が .openspec.yaml を使って解決した計画ホームに、ひな形の変更が作成されます。

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

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

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

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

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

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

   アーティファクトを依存関係の順に処理します（未解決の依存関係がないアーティファクトを最初に処理します）。

   a. 依存関係が満たされている ready 状態のアーティファクトごとに、次の操作を行います。

   • 指示を取得します。

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

   • 指示の JSON には、次の内容が含まれます。
     • context：プロジェクトの背景情報（あなたが従う制約。出力には含めないでください）
     • rules：アーティファクト固有のルール（あなたが従う制約。出力には含めないでください）
     • template：出力ファイルに使用する構成
     • instruction：このアーティファクト種別に固有のスキーマガイダンス
     • skipped／warning：変更で skip_specs が宣言され、このアーティファクトを作成してはならない場合に存在します。その場合は作成を中止し、別のアーティファクトを選択します
     • resolvedOutputPath：出力先の解決済みパスまたはパターン
     • dependencies：コンテキストとして読み込む、完了済みのアーティファクト
   • 完了済みの依存ファイルをコンテキストとして読み込みます。以前の会話で確認済みでも、必ずディスクから再読み込みしてください（ユーザーが編集している場合があります）。
   • instruction フィールドで特定のスキルまたはコマンドに作成が委任されている場合は、自分でファイルを作成せず、それを実行してアーティファクトを生成し、アーティファクトファイルが resolvedOutputPath に存在することを確認します。
   • それ以外の場合は、template を構成として使用してアーティファクトファイルを作成し、resolvedOutputPath に書き込みます。resolvedOutputPath が glob の場合は、instruction に従って具体的なファイルパスを選択します。
   • context と rules は制約として適用しますが、ファイルに転記してはいけません。
   • 簡潔な進捗を表示します：「Created 」 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 が宣言されているため、そのファイルは存在してはなりません。作成しようとしないでください
   • 必要なセット内で不足しているアーティファクトをすべて作成し、再確認します。1つ作成することで、ほかのアーティファクトが作成可能になる場合があります
   • スキップできるのは、status がすでに skipped と報告している場合、またはそのアーティファクト自体の instruction が条件付きであると示している場合に限ります。後者の場合は openspec instructions <artifact-id> --change "<name>" --json を実行し、instruction フィールドで任意と明記されている場合（例：「次の場合にのみ作成」）に限りスキップします。spec-driven の design.md は該当します。specs は上記の skipped ステータスの場合に限り該当し、独自の判断でスキップしてはいけません。ユーザーに伝えたうえで、再検討しないでください
   • 依存関係は作成を可能にするものであり、制約ではありません。条件付きの依存アーティファクトをスキップしたことだけを理由に、必要なアーティファクトが blocked のままでも作成してください
   • 必要なセット内のすべてのアーティファクトが done、skipped、または意図的にスキップ済みとなったら終了します

   c. アーティファクトの作成にユーザーの入力が必要な場合（コンテキストが不明確な場合）

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

6. 最終ステータスを表示します

   openspec status --change "<name>"
   

出力

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

• 変更名と場所
• 作成したアーティファクトの一覧と簡単な説明、およびスキップした条件付きアーティファクトがあればその理由
• 準備状況：「実装に必要なすべてのアーティファクトが準備できています。」
• プロンプト：「アーティファクトのレビュー準備ができました。準備ができたら、$openspec-apply-change (Codex) or /openspec-apply-change (other agents) を実行するか、この変更を適用するよう依頼してください。」

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

• 各アーティファクトの種類について、openspec instructions の instruction フィールドに従ってください。これは、よく知っているアーティファクト名であっても、最優先の指示です
• instruction フィールドで特定のスキルまたはコマンドを使ってアーティファクトを作成するよう指示されている場合は、アーティファクトを直接書くのではなく、それを実行してください
• スキーマで定義された各アーティファクトの内容に従ってください
• 新しいアーティファクトを作成する前に、依存するアーティファクトを読み、コンテキストを確認してください
• 出力ファイルの構成には template を使い、各セクションを埋めてください
• 重要：context と rules は、あなたが従うべき制約であり、ファイルに記載する内容ではありません
  • <context>、<rules>、<project_context> ブロックをアーティファクトにコピーしないでください
  • これらは作成内容を導くものですが、出力に含めてはいけません ガードレール
• このワークフローを呼び出したリクエストで許可されているのは、計画のみです。そのリクエストに含まれる実装や適用の指示は引き継がれません。このワークフロー中に変更を実装したり、適用ワークフローを開始したり、プロジェクトコードを編集したりしないでください。成果物を提示したら、適用ワークフローを開始する新たなユーザーリクエストを待ってください
• apply.requires に記載された ID だけでなく、適用フェーズが依存するすべての成果物を作成してください
• 新しい成果物を作成する前に、必ず依存する成果物を読み込んでください。会話の記憶ではなく、ディスクから読み直してください（最後に確認してからファイルが変更されている可能性があります）
• スコープ、外部から確認できる動作、互換性、受け入れ基準に大きく影響する曖昧さがある場合は質問してください。細かな点については、妥当な想定をして記録してください
• 同じ名前の変更がすでに存在する場合は、それを続行するか、新しく作成するかをユーザーに確認してください
• 次に進む前に、各成果物ファイルを書き込んだ後、そのファイルが存在することを確認してください