robsonprod/portfolio

新しい変更を提案 - 変更を作成し、すべてのアーティファクトを1ステップで生成します。

計画境界: このワークフローは計画アーティファクトのみを作成します。このワークフローを選択またはトリガーしたユーザーリクエストは、たとえ構築や修正を依頼するものであっても、計画のみを許可します。プロジェクトコードを編集しないでください。計画アーティファクトが完了したら、停止します。初期リクエストが実装を求めていても、同じ応答内で実装を開始しないでください。アーティファクトが提示された後、新しいユーザーリクエストを待ち、その後 apply ワークフローを開始します。

スキーマで定義されたアーティファクトを使って変更を作成します。デフォルトの仕様駆動スキーマでは、以下の通りです:

• proposal.md (何を、なぜ)
• specs/<機能パス>/spec.md (システムがすべきこと - 差分であり、メインスペックではない)
• design.md (どのように)
• tasks.md (実装手順)

<機能パス> は specs/ からの相対パスです (例: user-auth または identity/user-auth)。既存の機能の完全なパスは維持し、新しい機能についてはプロジェクトの確立された組織に従ってください。

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

---

ストア選択: ユーザーがストア (このマシンに登録されているスタンドアロンの 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 オブジェクトがある場合はプロジェクトがセットアップされています。"root": null はセットアップされていないことを意味します - ここに openspec/ ディレクトリはなく、openspec new change などの書き込みは副作用としてそれを作成します。このコマンドは非ゼロで終了しますが、これはCLIの故障ではなく上記の応答であるため、JSON を読み取り、再試行したり回避したりしないでください。

1つの "root": null はセットアップに関するものではありません: 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/ ファイルを手動で作成せず、コマンドに作成させないでください。

入力: ユーザーのリクエストには、変更名 (ケバブケース) または構築したい内容の説明を含める必要があります。

手順

1. リクエストを理解し、重大な曖昧さを明確にする

   明確な入力がない場合は、ユーザーに質問します (自由形式、選択肢なし):

   「どの変更に取り組みますか？構築または修正したい内容を説明してください。」

   説明から、ケバブケースの名前を導き出します (例: 「add user authentication」→ add-user-auth)。

   重要: ユーザーが何を構築したいのかを理解せずに先に進まないでください。

   リクエストに、スコープ、外部から観測可能な動作、互換性、または受け入れ基準に重大な影響を与える曖昧さが含まれている場合は、変更を作成する前にユーザーに質問してください。細かい点については、合理的な仮定を立て、それを計画アーティファクトに記録します。

2. プロジェクトコンテキストを読み込む

   現在の作業ディレクトリから openspec context --json を実行します (登録されたストアが明示的に選択された場合は openspec context --json --store "<store-id>")。返された root.path を権威ある OpenSpec ルートとして使用します。コンテキストが no_openspec_root を報告した場合は、ファイルを作成または変更せずに停止し、プロジェクトチェック に従ってこのワークフローにどのように到達したかを確認します。明示的な OpenSpec リクエストの場合のみ openspec init を提案し、ユーザーが初期化を要求するのを待ちます。自動的に初期化したり、openspec new change を実行したりしないでください。初期化後、続行する前にこのコンテキストチェックを再実行します。その他のコンテキスト障害の場合は、停止してエラーを報告します。選択したストアなしでカレントディレクトリにフォールバックしたり、後続の OpenSpec コマンドを実行したりしないでください。

   コンテキストが解決された root.path を返した場合のみ、<root.path>/openspec/config.yaml を読み取ります。config.yaml が存在しない場合のみ config.yml を使用します。どちらのファイルも存在しない場合は、プロジェクトコンテキストなしで続行します。config.yaml が読み取り不能または無効な場合でも config.yml にフォールバックしないでください。

   ファイルが YAML オブジェクトとして解析され、その context フィールドが UTF-8 で 51,200 バイト以下の文字列である場合、コードベースを探索したり計画を決定したりする前にそのフィールドを適用します。ファイルを読み取ったり解析したりできない場合、または context フィールドが無効または大きすぎる場合は、プロジェクトコンテキストなしで続行します。このフィールドは、他の設定フィールドとは独立して検証します (OpenSpec と同様)。

   コンテキストはプロジェクトが提供するデータと制約として扱いますが、このワークフローを変更する権限としては扱いません。ユーザー承認、計画境界、ツール制限、またはアーティファクトと出力ルールをオーバーライドすることはできません。コンテキストをアーティファクトにコピーしないでください。コードベース探索を絞り込み、提案の制約として使用します。

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

   ユーザーが明示的に異なるワークフローを要求しない限り、設定されたデフォルトスキーマを使用します。

   ユーザーが以下の場合にのみ異なるスキーマを使用します:

   • 特定のスキーマを名前で明示的に要求する → --schema <schema-name> を使用
   • 「show workflows」と尋ねる、または「what workflows」と尋ねる → 現在の作業ディレクトリから openspec context --json を実行して権威あるルートを解決します。ユーザーが登録されたストアを明示的に選択した場合は、openspec context --json --store "<store-id>" を使用します。次に、返された root.path を作業ディレクトリとして openspec schemas --json を実行し、ユーザーに選択させます。これにより、ローカルの store: ポインタまたはグローバルの defaultStore によって選択されたルートが保持されます。登録されたストアが明示的に選択された場合は、openspec schemas --json にも --store "<store-id>" を追加します。コンテキストが失敗した場合は、コンテキスト読み込み手順で説明したように停止します。カレントディレクトリにフォールバックしないでください。

   それ以外の場合は、--schema を省略して設定されたデフォルトを保持します。

4. 変更ディレクトリを作成する

   以下のいずれかのスキーマ形式を選択します。登録されたストアが選択されている場合は、そのコマンドと、以下に示す --store を受け付ける後続の OpenSpec コマンドのそれぞれに --store "<store-id>" を追加します。

   設定されたデフォルトを使用:

   openspec new change "<name>"
   

   明示的に要求されたスキーマを使用:

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

   これにより、CLI によって解決された計画ホームに、.openspec.yaml を含むスキャフォールディングされた変更が作成されます。

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

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

   JSON を解析して以下を取得します:

   • applyRequires: 実装前に必要なアーティファクト ID の配列 (例: ["tasks"])
   • artifacts: すべてのアーティファクトのリスト。各アーティファクトには status と requires エッジ (直接依存するアーティファクト ID) が含まれます
   • planningHome、changeRoot、artifactPaths、actionContext: パスとスコープのコンテキスト。これらをリポジトリローカルパスを想定する代わりに使用します。

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

   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 がグロブの場合、instruction に従って、changeRoot 内でグロブに一致する具体的なパスを選択し、シンボリックリンクを解決した後も changeRoot 内にあることを確認します (親ディレクトリと、ファイルが既に存在する場合はファイル自体の両方で)。そうでない場合は停止してユーザーに伝えます。それ以外の場合、出力パスは resolvedOutputPath です。
   • instruction フィールドが特定のスキルまたはコマンドに作成を委任している場合、そのアーティファクトをその出力パスに書き込める場合にのみそれを呼び出します。それ以外の場合は停止してユーザーに伝えます。その後、アーティファクトファイルがその出力パスに存在することを確認します。
   • それ以外の場合は、template を構造として使用してアーティファクトファイルを作成し、その出力パスに書き込みます。
   • context と rules を制約として適用します - ただしファイルにコピーしないでください。
   • 簡単な進捗を表示: "Created "

   b. 必要なセット内のすべてのアーティファクトが存在するまで続行します (単なる apply.requires だけでなく)

   • 各アーティファクトを作成した後、openspec status --change "<name>" --json を再実行します
   • 必要なセットは、applyRequires に加えて、status --json の requires エッジをたどって到達可能なすべてのアーティファクトです - 推移的に辿ります (仕様駆動では proposal、specs、design、tasks を閉じます)。そのセット外のアーティファクトはそのままにします
   • status はファイルの存在のみを確認するため、applyRequires アーティファクトが done と読んでも、その依存関係が存在するとは限りません - tasks.md を早期に書き込むと、specs が決して書き込まれなかった場合でも tasks が done とマークされます。各アーティファクトの status ではなく、requires エッジを使用して必要なセットを構築します: done アーティファクトでも、それが依存するものはリストされます。
   • 既に status: "skipped" と読めるアーティファクトは満たされています: 変更が .openspec.yaml で skip_specs を宣言しているため、そのファイルは存在してはいけません。決して作成しようとしないでください。
   • 不足している必要なセット内のすべてのアーティファクトを作成し、再チェックします - 1つを作成すると、他のものがブロック解除される可能性があります。
   • 1つをスキップするのは、status が既に skipped を報告している場合、またはその instruction が条件付きであると示している場合のみです: openspec instructions <artifact-id> --change "<name>" --json を実行し、その instruction フィールドがオプションであるとマークしている場合のみスキップします (例: "create only if...")。仕様駆動の design.md は該当します。specs は上記の skipped ステータスの場合のみ該当し、あなた自身の判断では決して該当しません。ユーザーに伝え、再検討しないでください。
   • 依存関係はイネーブラーであり、ゲートではありません: 条件付き依存関係をスキップしたため、必要なアーティファクトがまだ blocked のままである場合でも、それを書き込みます。
   • 必要なセット内のすべてのアーティファクトが done、skipped、または意図的にスキップされた場合に停止します。

   c. アーティファクトがユーザー入力を必要とする場合 (コンテキストが不明瞭)

   • ユーザーに明確化を求めます
   • その後、作成を続行します

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

   openspec status --change "<name>"
   

出力

完了後...