openspec-propose

新しい変更を提案します。変更を作成し、すべてのアーティファクトを一度に生成します。

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

スキーマで定義されたアーティファクトを含む変更を作成します。デフォルトの仕様駆動型スキーマでは、次のとおりです。

• proposal.md（何を、なぜ行うか）
• specs/<capability-path>/spec.md（システムが何をすべきか。メイン仕様ではなく、差分）
• design.md（どのように行うか）
• tasks.md（実装手順）

<capability-path> は、specs/ からの相対パスで表す仕様ディレクトリです（例：user-auth、identity/user-auth）。既存のケイパビリティはフルパスを維持し、新しいケイパビリティにはプロジェクトで確立されている構成に従ってください。

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

---

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

入力：ユーザーのリクエストには、変更名（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 によって選択されたルートが維持されます。登録済みストアが明示的に選択されている場合は、openspec schemas --json にも --store "<store-id>" を付け加えてください。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 が宣言されているため、充足済みです。そのファイルは存在してはなりません。作成しようとしないでください
   • 必須セット内で不足している成果物をすべて作成し、再確認します。成果物を作成すると、ほかの成果物が作成可能になることがあります
   • スキップできるのは、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 を実行するか、この変更を適用するよう依頼してください。」

成果物の作成ガイドライン

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