comet-open

Comet Phase 1：Open

開始または再開する前に、comet-classic/reference/classic-layout.md を読んで、その指示に従ってください。このファイル内のすべての OpenSpec CLI 呼び出しにはアダプターを使用し、すべてのパスには、そのプロトコルでバインドされた <classic-*> 論理ルートを使用してください。

前提条件

• アクティブな変更がないか、ユーザーが新しい変更の作成を希望しています。

手順

0. 出力言語を設定する

OpenSpec に渡すすべての質問と成果物の生成リクエストでは、en や zh-CN などの正規化された ID を使って、解決済みの Comet 成果物言語を指定する必要があります。.comet.yaml が存在する前は、プロジェクトの .comet/config.yaml、次にグローバルの ~/.comet/config.yaml から classic.language を読み取ってください。初期化後は、comet state get <name> language を使用してください。言語が設定されていない場合に限り、現在のリクエストの言語を使用してください。proposal.md、design.md、tasks.md は、主にその言語で記述してください。

0a. 現在の変更をバインドする

既存の変更を再開する場合は、まず <classic-change-dir>/.comet.yaml を確認してください。

• ファイルが存在し、解析できる場合は、comet classic workspace resolve <change-name> --json を実行し、返された projectRoot に移動して、その場所で変更を選択してください。
• 状態がなく、変更ディレクトリが有効な場合は、選択した分離モードを使ってワークスペースを準備してください。返された projectRoot に移動し、comet state init <change-name> full --isolation <selected-isolation> を実行してから、変更を選択してください。
• 状態が不正な場合は停止し、解析エラーを報告してください。バージョン管理、バックアップ、または検証可能な成果物を使って手動で修復した後にのみ、再開してください。state set で破損した状態を上書きしないでください。

comet classic workspace resolve <change-name> --json
# Enter the returned projectRoot
comet state select <change-name>

新しい変更の場合は、まず .comet.yaml を初期化し、直ちに上記の選択コマンドを実行してください。状態が存在する前に、選択状態を手動で書き込まないでください。

0b. Open の前にワークスペースを選択して準備する

Classic の変更を作成する際は、comet-classic/reference/workspace.md を読んでください。OpenSpec の成果物や .comet.yaml を作成する前にワークスペースを選択してください。Build まで先送りしないでください。

• ユーザーが並行作業を明示的に希望する場合は、worktree を直接使用してください。OpenSpec の成果物や状態を作成する前に、独立したワークスペースを準備してください。
• 分離方法が指定されていない場合は、リファレンスに従ってください。選択が必要な場合は、利用可能な current、branch、worktree の各オプションを提示してください。推奨を示しても、ユーザーの選択に代わるものではありません。
• current と branch でも、作業は順番に行う必要があります。これらを並行セッションに適した方法として説明しないでください。

OpenSpec の new を実行する前に、ワークスペースを準備してください。

comet classic workspace prepare <name> --isolation <current|branch|worktree> --json
# Enter projectRoot; run subsequent OpenSpec/state commands and artifact writes there

prepare コマンドは、ブランチが一致する登録済みの worktree を再利用します。ブランチが残っている一方で登録済みの worktree が削除されている場合は、worktree を再作成します。明示的な再バインドを依頼するのは、ブランチ名が変更された場合、別の作業に転用された場合、またはその所有者を確認できない場合に限ってください。

0c. OpenSpec との互換性を確認する

初回使用時、または上流のインストール内容を変更した後に一度実行し、トラブルシューティング用にバージョンを記録します。

comet classic openspec -- --version

バージョンから互換性を推測するのではなく、実際の機能を確認します。ステータスには、changeRoot、applyRequires、および各アーティファクトのrequires、outputPath、statusが含まれている必要があります。指示には、使用可能なresolvedOutputPathが含まれている必要があります。このアダプターは OpenSpec 1.11.0/1.12.0 の状態インターフェースに対して確認済みですが、過去のすべてのバージョンとの互換性は保証されません。コマンドが使用できない場合、ゼロ以外のコードで終了する場合、または必須機能が不足している場合は、エラーとアップグレードの案内を示して停止します。ユーザーの環境を自動的にアップグレードしないでください。

作成後、comet state artifacts <name> --jsonでパス、必須の依存関係すべて、実際のファイルを確認します。applyRequiresと Classic の必須の proposal/tasks を再帰的に展開し、依存関係の完全な閉包を取得します。その閉包に design が必要な場合、指示で任意とされていても省略しないでください。閉包の範囲外の design は必須ではありません。

specs を省略できるのは、リクエストで動作仕様が一切変更されず、.openspec.yamlでskip_specs: trueが明示的に設定され、競合する spec ファイルが存在しない場合に限られます。サポートされるロールは proposal/specs/design/tasks です。必須ロールや出力パターンがサポートされていない場合は、扱い方を推測せずにその旨を報告してください。

1. アイデアを検討し、要件を明確にする

今すぐ必須： Skill ツールを使用してopenspec-exploreスキルを読み込みます。この手順を省略しないでください。

外部の OpenSpec 指示を調整する： その探索方法のみを使用します。公式 CLI を直接呼び出す指示、固定の cwd に移動する指示、ハードコードされた OpenSpec ディレクトリを読み書きする指示には従わないでください。すべての CLI 呼び出しにはcomet classic openspec -- <args...>を使用し、すべてのパスにはこの呼び出しにバインドされた<classic-*>ルートを使用します。

まずユーザーの PRD、デザイン、確認済みの事実を再利用します。以下の項目で不足している点を特定し、確認事項の要約を作成します。スコープ、解決策、または受け入れ条件を変える未知の点についてのみ質問します。情報が十分であれば、追加質問をせずに進めます。確認の往復に最低回数はありません。

• 目標：ユーザーが実際に抱えている問題と、望んでいる結果。
• 非目標：今回の変更で明示的に対象外とするもの。
• スコープ：対象に含める、または含めないモジュール、ユーザー、プラットフォーム、データ。
• 主な未知の点：未解決の前提、リスク、依存関係。
• 受け入れシナリオ案：少なくとも主要な成功パスと重要なエッジケース。

要約には、目標、非目標、スコープ、主な未知の点、受け入れシナリオ案の5項目すべてを含める必要があります。

ユーザーに質問する前に、comet-classic/reference/decision-point.mdを読みます。質問、推奨案、その理由、および各選択肢の影響を示し、利用可能であればAskUserQuestionツールを優先して使用します。現在の不足点についてのみ質問します。不足している事実や資料では現実的な選択肢を提示できない場合は、何が不足しているかを説明して提供を求めます。この手順は外部の探索スキルからの質問にも適用します。スキルを読み込んでも、選択肢の提示を省略したり、ユーザーに代わって決定したりすることはできません。

完全な PRD はコピーせず、パスと関連セクションを参照します。確定済みの事実を再確認せず、実際に矛盾している点のみを明確にします。OpenSpec スキルは引き続き必須の依存関係です。探索が終わったら Comet に戻ります。外部スキルだけで design、実装、アーカイブに進んではいけません。探索の承認は、Open による最終的なアーティファクト確認の代わりにはなりません。

1a. 作成前に PRD を分割するか確認する

大規模な PRD、ロードマップ、製品全体の提案、または複数の独立した機能、モジュール、ユーザージャーニー、マイルストーンを含む確認事項の要約については、OpenSpec アーティファクトを作成する前に、複数の変更に分ける必要があるか評価します。

明確になった情報を使って、分割案を提示します。各項目には以下を含めます：

• 提案する変更名。
• 目的とスコープ。
• 明示的な非目標。
• 依存関係または推奨される実行順序。
• 主要な受け入れシナリオ。

次のいずれかに該当する場合は、分割を推奨します。

• PRD に、独立して設計、構築、検証、アーカイブできる複数の機能が含まれている。
• 複数のモジュールまたはユーザージャーニーにまたがり、その一部を独立して出荷できる。
• 明確に異なる提供マイルストーンがある。
• 複数のデルタ仕様が、個別に受け入れ・出荷できる独立した目標に対応している。文書やタスクの数だけでは分割の判断はできません。
• ある部分の失敗や遅延が、他の部分の進行を妨げるべきではない。

分割を推奨する場合は、comet-classic/reference/decision-point.md の下で一時停止し、ユーザーの選択を待ちます。次の選択肢をすべて含めてください。

• 「複数の OpenSpec 変更を作成する」: 提案された各項目を独立した変更として作成します。
• 「1 つの変更を維持する」: 1 つの変更のまま続行し、その理由を proposal/design/tasks に記録します。
• 「分割を修正する」: 希望する調整を尋ね、リストを修正し、再度確認を得ます。

受け入れられたすべての項目は、/opsx:new ではなく /comet-open を通じて作成してください。/comet-open は OpenSpec の成果物と .comet.yaml の両方を作成し、各変更を Comet 状態機械の下に保ちます。

ユーザーが PRD の分割方法を選択する前に、proposal.md、design.md、tasks.md を作成しないでください。複数の変更を選択した場合、この /comet-open の呼び出しは分割の確認とスケジューリングのみを処理し、承認された順序で各項目に対して /comet-open を呼び出します。

確認されたバッチを直ちに .comet/batches/<batch-id>.json に保存してください。安定したケバブケースの batch-id を使用します。少なくとも version、元の目標の要約、作成時刻、順序付けられた変更名、および各項目の目標、スコープ、非目標、受け入れシナリオ、pending|open-complete|selected ステータスを記録してください。各項目の作成または完了後にファイルをアトミックに更新してください。このリストはバッチの順序と進捗を追跡するものであり、各変更の .comet.yaml を置き換えるものではありません。

バッチ項目に対して /comet-open を呼び出す際は、「確認済み分割項目」とラベル付けし、その目標、スコープ、非目標、受け入れシナリオを渡してください。確認済み項目については、その項目が依然として複数の独立した機能を明確に含んでいない限り、PRD 分割の評価を省略してください。

個々のバッチ項目を Open から /comet-design へ自動的に移動しないでください。バッチが完了したら、一時停止してどの変更を開始するかを尋ねます。選択された変更のみを /comet-design へ進めてください。他の変更はアーカイブせずに残し、後で /comet-classic を通じて復帰できるようにします。

完了したすべてのバッチ項目を確認してください。これを省略しないでください: すべての項目が Open を完了した後、確認済みリストのすべての <name> に対して次を実行してください。

comet state check <name> design --json

このエントリは、必須のクロージャ全体、実際の OpenSpec 出力、および Comet 状態を検証します。別途ステータススキャンを繰り返さないでください。isComplete は診断用であり、オプションの成果物は進行を妨げません。ステータスを照会するのは、チェックが失敗した後に、欠落している依存関係を特定したり、報告されたパス/機能エラーを診断したりする場合のみとしてください。

いずれかの分割項目がこれらのチェックに失敗した場合、バッチ完了を宣言したり、どの変更を開始するかを尋ねたりしないでください。それ以上の進行を停止し、その変更の最初の ready または blocked 成果物のところで /comet-open を再開してください。OpenSpec チェックは合格しても Comet 状態チェックが失敗する場合は、まず .comet.yaml の初期化またはフェーズを修復し、その後でバッチチェックを再実行してください。

すべての項目がエントリチェックに合格した後にのみ、どの変更を開始するかを尋ねることができます。ユーザーが選択した項目をバッチリストで selected としてマークし、その変更のみを /comet-design へ進めてください。他の変更はアーカイブせずに残し、後で /comet-classic を通じて復帰できるようにします。 復旧時は、.comet/batches/<batch-id>.json を読み込み、作成済みかつアーカイブされていない変更について、上記のチェックを実行します。すでにチェックに合格している項目は再作成しないでください。失敗した項目は、OpenSpec が返す最初の ready アーティファクトから再開します。残りの項目は保存済みリストから作成します。リストが見つからない、または破損している場合は、停止してユーザーにリストの再構築または確認を依頼してください。ディレクトリ名から元のバッチを推測しないでください。

1b. 要件をまとめ、変更名を決める

アーティファクトを作成する前に、Step 1 の調査結果を、目標、対象外、スコープ、主な不明点、受け入れシナリオ案を含む確定済みブリーフにまとめます。そのスコープを正確に表す英語の kebab-case の変更名を導き出します。

• スコープと名前が明確であれば、そのまま続行します。 要約や名前の承認だけを目的とした一時停止は追加しないでください。最終レビューで、名前、スコープ、アーティファクトの内容をまとめて確認します。
• ユーザーが名前を提示した場合は、kebab-case に正規化し、進捗報告でその名前を伝えます。正規化によって意味が変わらない場合、再確認は不要です。
• 確認済みのバッチ項目の要約と名前を再利用します。スコープが変わった場合、またはリストに必要な情報がない場合に限り、改めて確認してください。
• 互いに両立しないスコープまたは対象変更の選択肢が残っている場合に限り、comet-classic/reference/decision-point.md に従って、両方を含む質問をしてください。名前の好みだけを理由に一時停止してはいけません。

OpenSpec の変更名は、英語の kebab-case（小文字、数字、単一のハイフン）にする必要があります。名前が競合していても目標が明確な場合は、同じ意味の競合しない名前を選び、そのまま続行してください。既存の変更を再利用するか、新しい変更を作成するか判断できない場合に限り、ユーザーに尋ねてください。

確定済みブリーフまたは変更の識別情報がまだ不明確な間は、comet classic openspec -- new change を実行したり、proposal/design/tasks を作成したりしないでください。Step 2 に進む前に、不足情報を補うか、ユーザーによる実質的な決定を得てください。

2. 変更の構成を作成し、状態を初期化する

今すぐ必須： Skill ツールを使って openspec-new-change スキルを読み込んでください。この手順を省略しないでください。

外部の OpenSpec 指示を適用する場合： 変更の作成方法のみを使用します。公式 CLI を直接実行したり、固定の cwd を採用したり、固定の OpenSpec ルートに書き込んだりしないでください。作成、状態確認、指示の取得は comet classic openspec -- <args...> 経由で行ってください。この呼び出しの論理ルート（<classic-change-dir> を含む）をすべてのパスに使用します。

完全な /comet-classic フローでは、既定で openspec-propose を読み込まないでください。ユーザーが proposal とアーティファクトをまとめて作成するよう明示的に依頼した場合に限り、読み込みます。

外部の OpenSpec 指示を適用する場合： 同じ制約が openspec-propose にも適用されます。公式 CLI、固定 cwd、固定の物理的な OpenSpec パスは使用しないでください。コマンドはアダプターを使用し、アーティファクトにはリゾルバーが提供する <classic-*> ルートを使用してください。

読み込んだスキルに従って、変更の初期構成を作成します。Step 1b ですでに明確な確定済みブリーフが作成されている場合は、「STOP and wait for user direction」の動作を上書きし、質問を繰り返さずに続行してください。

確定済みブリーフを使ってアーティファクトの内容を作成します。スコープを左右する曖昧さがブリーフに残っている場合に限り、スキルの質問に戻ってください。

初期構成を作成したら、復旧可能な状態をただちに初期化します。すべてのアーティファクトの生成完了を待たないでください（エントリーチェックはここではなく、Step 3 で一度実行します）。

comet state init <name> full --isolation <selected-isolation>
comet state select <name>

いずれかのコマンドが失敗した場合は停止してください。その後、comet classic openspec --agent-json -- status --change "<name>" --json を一度実行し、互換性を確認します。

• 解決済みの changeRoot は、バインドされた <classic-change-dir> と一致する必要があります。planningHome がある場合は、リポジトリ内にある必要もあります。外部の成果物パスはサポートされていません。
• artifacts には、Classic で必須の ID proposal と tasks を含め、それらの requires を再帰的にたどる必要があります。
• applyRequires は、解決可能な成果物 ID のリストである必要があります。直接および推移的な依存関係がすべて存在し、循環していないことを確認してください。
• フィールドが欠けている場合、リポジトリ外のパスがある場合、または必須 ID が欠けている場合は、直ちに停止してください。推測したテンプレートで代用しないでください。

チェックに合格したら、OpenSpec から返されたスキーマと依存関係グラフに基づいて、必要な成果物を生成してください。

Agent JSON モードでは、上流のフィールドを data.upstream.data から読み取ってください。data.nextAction から返された完全な argv と cwd のみを実行してください。上流の生の nextSteps は診断専用です。

OpenSpec の状態から成果物を生成します：

1. 最初の反復では、Step 2 の互換性チェックで得たステータスを再利用し、以降の反復では直前の書き込み後に更新されたステータスを再利用してください。復旧時または外部成果物の変更時に限り、comet classic openspec --agent-json -- status --change "<name>" --json を再実行し、完全な上流 JSON を data.upstream.data から読み取ってください。

2. applyRequires と proposal/tasks の依存関係全体を展開してください。すべての項目が done または正当な理由で skipped になったら、comet state artifacts <name> --json を実行し、合格した場合に限ってループを終了してください。最上位の tasks 成果物が完了していても、未完了の依存関係が隠れることはありません。isComplete は診断用です。

3. 未完了の成果物のうち、status: "ready" のものを対象に、CLI の順序に従って applyRequires の依存関係を進めるものを優先してください。生成順序をハードコードしたり、スキーマに proposal/design/tasks しか含まれないと仮定したりしないでください。

4. 各 <artifact-id> の最新の指示を取得してください：

   comet classic openspec --agent-json -- instructions <artifact-id> --change "<name>" --json
   

5. 返された JSON の指示に従ってください：

   • dependencies にある完了済みの依存関係をすべて読み取ってください。
   • 成果物の構造には template を使用してください。
   • instruction に従ってください。
   • context と rules を制約として適用してください。成果物にコピーしないでください。
   • resolvedOutputPath に書き込んでください。ワイルドカード出力の場合は、指示で必要とされる実ファイルをすべて作成してください。
   • CLI から返された実際の出力ファイルが存在し、空でないことを確認してください。

6. 各成果物の作成後、ローカルで comet state artifacts <name> --json を使って依存関係全体を検証してください（OpenSpec のサブプロセスは使いません）。依存関係の欠落または順序エラーが報告された場合、あるいは最新の指示が必要な場合に限り、ステータスを一度だけ更新してから、パスと依存関係全体を再確認してください。done の項目は再生成しないでください。対象は依存関係全体に含まれる新たに ready になった項目に限り、無関係な任意の成果物は処理しないでください。

失敗とブロックされた依存関係への対処： applyRequires が未完了で、必要な依存関係の中に ready のものがない場合は、該当する blocked 成果物とその missingDeps を報告して停止してください。順序を推測したり、依存関係を飛ばしたりしないでください。また、アダプターの status / instructions が失敗する、無効な JSON を返す、リポジトリ外を指す、または使用可能な resolvedOutputPath がない場合は、OpenSpec のエラーを報告して停止してください。ハードコードされたドキュメント構造で代用しないでください。

名前とスコープを確認してください： Step 1b で解決した英語の kebab-case 名を使用してください。中国語名を含め、kebab-case でない名前は使用できません。解決済みの概要とユーザーのリクエストにスコープを一致させてください。独断でスコープを広げたり狭めたりしないでください。

次の成果物が存在することを確認してください：

<classic-change-dir>/
├── .openspec.yaml
├── .comet.yaml
├── proposal.md       # Why + What: problem, goal, scope
├── design.md         # When required or useful; keep technical decisions here without duplicating them
└── tasks.md          # Task checklist

3. エントリ状態を検証する

状態が正しく初期化されたことを確認します。

comet state check <name> open

成功したらステップ 4 に進みます。失敗した場合、スクリプトが具体的な原因を報告します。

未完了の作成手順を再開する： オープンな操作は安全に再試行できます。復旧時は、完了済みの作業を保持しながら、次の順序で状態を処理してください。

1. 状態がない場合は、選択した分離モードを準備し、返された projectRoot に移動して、comet state init <name> full --isolation <selected-isolation> を実行します。不正な状態は上書きせず、停止して修正してください。その後、変更を選択し、comet state check <name> open を実行します。
2. comet classic openspec --agent-json -- status --change "<name>" --json を実行し、changeRoot、コア ID、applyRequires、artifacts、missingDeps を再確認します。
3. done：アーティファクトは変更せず、再生成しないでください。
4. ready：comet classic openspec --agent-json -- instructions <artifact-id> --change "<name>" --json で手順を取得し、それに従ってアーティファクトを作成します。その後、ステータスを更新する代わりに、comet state artifacts <name> --json でローカルの依存関係を検証します。
5. blocked：missingDeps に従い、まず applyRequires の依存関係を完了します。各依存関係の完了後に comet state artifacts <name> --json で検証し、新たな問題が報告された場合にのみステータスを更新します。ブロックされたアーティファクトを直接生成しないでください。
6. 必須の依存関係がすべて完了するか、正当にスキップされ、comet state artifacts <name> --json が成功するまで繰り返します。

必須の依存関係を進められない場合は、該当するブロック中のアーティファクトと missingDeps を列挙してから停止し、報告してください。既存のディレクトリや 3 つの固定ファイルがあっても、CLI のチェックの代わりにはなりません。一方、applyRequires の対象外であるオプションのアーティファクトは、isComplete: false という理由だけで実装を妨げてはなりません。

4. 内容の完全性を確認する

最新の成功した comet state artifacts <name> --json の結果を使って、必須アーティファクトを確認します。ファイルまたはスキーマを変更した後は、再実行してください。問題が残っている間は、ステップ 5 に進んだり、フェーズガードを実行したりしないでください。

続いて内容を確認します。proposal には問題、目標、スコープ、対象外を含める必要があります。design には大まかな意思決定とデータフローを含める必要があります。tasks は具体的である必要があります。スキーマから仕様やその他のアーティファクトが返された場合は、それらの内容も手順に照らして確認してください。proposal、design、tasks が存在していても、その他の必須コンテンツが任意になるわけではありません。

5. アーティファクトの確認をユーザーに求める

OpenSpec のアーティファクトと内容の確認がすべて完了したら、comet-classic/reference/decision-point.md に従って一時停止し、ユーザーの明示的な確認を待ちます。確認前にフェーズガードを実行したり、自動的に先へ進んだりしないでください。

この最終レビューでは、変更名、スコープ、アーティファクトの内容をまとめて確認します。ステップ 1b ではこの確認の代わりになりません。また、その前に別途、定型的な概要や名前の承認を追加で求めないでください。

次の概要と両方の選択肢を示し、単一選択の質問をしてください。

概要：

• 変更名と確定した概要： 最終的な名前、目標、対象外、スコープ、主な未確定事項。
• proposal.md： 背景、目標、スコープ。
• 仕様などのスキーマアーティファクト： 機能、要件、主な受け入れシナリオ。
• design.md： アーキテクチャに関する大まかな意思決定と解決策の選択。
• tasks.md： タスク数と主なタスク。

選択肢：

• 「確認して続行」：アーティファクトは期待どおりです。先へ進むためにフェーズガードを実行します。
• 「アーティファクトを調整」：希望する変更を確認して適用し、再度確認を求めます。

確認後、終了条件を満たしてください。調整が求められた場合は、該当するファイルを更新し、再度確認を得てください。

終了条件

• comet state artifacts <name> --json が成功すること：必要な依存関係がすべて完了しているか、正当な理由でスキップされており、必要な出力が空ではないこと。
• ユーザーが、すべての OpenSpec アーティファクトの内容が期待どおりであることを確認していること。
• フェーズガード： comet guard <change-name> open --apply を実行します。ガードはすべてのチェックに合格した後にのみフェーズを進めます。phase は auto_transition とは独立して更新されます。

終了する前に --apply を使用してください。使用しない場合、.comet.yaml は phase: open のままとなり、次回のエントリーチェックが失敗します。

comet guard <change-name> open --apply

完全なワークフローは phase: design に進みます。hotfix/tweak プリセットは phase: build に進みます。

次のフェーズに進む

comet-classic/reference/auto-transition.md と、成功結果に含まれる agent.continuation に従ってください。有効な状態情報がすでにある場合は、next、select、check を繰り返さないでください。以下は、コンテキストが失われた場合、外部で状態が変更された場合、または古い結果にその情報が含まれていない場合にのみ実行します。

comet state next <change-name>

• NEXT: auto：SKILL で指定されたスキルを呼び出して続行します。
• NEXT: manual：次のスキルを呼び出さないでください。HINT に従って制御を戻し、確認の質問を追加せずにこの呼び出しを終了します。
• NEXT: done：ワークフローは完了です。

hotfix/tweak スキルは、フェーズが直接 build に進んだ後の継続方法を独自に制御します。その next 結果には、対応するプリセットスキルが示されます。