openspec

OpenSpec（OPSX）スキル

このスキルは、成果物グラフ、スキーマ／テンプレートの解決、変更のライフサイクル、実験的なコマンド／スキルなど、OpenSpec の成果物駆動型ワークフローシステム（OPSX）を理解し、検討するためのガイドとして使用します。

クイックナビゲーション

• 成果物グラフの基本概念：references/artifact-core.md
• OPSX ワークフローの動作と使用方法：references/opsx-workflow.md
• セットアップとプロファイル（init、update、config profile）：references/setup-profiles.md
• スキーマのカスタマイズワークフローと課題：references/schema-customization.md
• エンドツーエンドのスキーマワークフローの課題と提案する解決策：references/schema-workflow-gaps.md
• 実験的リリース計画と展開チェックリスト：references/experimental-release-plan.md

リリースの主な変更点（1.2.0 → 1.3.0）

• ツール連携の拡充： Junie、Lingma、ForgeCode、IBM Bob のサポートが追加されました。
• より安全なセットアップ： シェル補完のインストールがオプトイン方式になり、.github/ ディレクトリが存在するだけでは Copilot の自動検出が実行されなくなりました。
• アダプターの修正： Pi のコマンド生成が修正され、OpenCode では標準の .opencode/commands/ パスが使用されるようになりました。
• より安全なステータス確認： プロジェクトに変更がまだない場合でも、openspec status が正常に終了するようになりました。

OPSX コマンド

コマンド	目的
/opsx:explore	アイデアを検討し、問題を調査します（構造化はしません）
/opsx:new	新しい変更を開始します
/opsx:continue	依存関係に基づいて次の成果物を作成します
/opsx:ff	ファストフォワード — すべての計画成果物を一度に作成します
/opsx:apply	必要に応じて成果物を更新しながら、タスクを実装します
/opsx:verify	実装が仕様に一致しているか検証します
/opsx:sync	差分仕様をメイン仕様に同期します
/opsx:archive	完了した変更を1件アーカイブします
/opsx:bulk-archive	完了した複数の変更を一度にアーカイブします

レガシー（非 OPSX）コマンド： /openspec:proposal はすべての計画成果物を一度に作成します。OPSX を優先してください。ただし、小規模で単純な変更や古いセットアップでは便利な場合があります。

スキーマ管理

openspec schemas                    # List available schemas
openspec schema which --all         # Show resolution sources
openspec schema init my-workflow    # Create new schema interactively
openspec schema fork spec-driven my-workflow  # Fork existing schema
openspec schema validate my-workflow  # Validate schema structure

プロジェクト設定

プロジェクトごとの設定を行うには、openspec/config.yaml を作成します。

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest, Playwright

rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format

スキーマの優先順位： CLI フラグ → 変更メタデータ → プロジェクト設定 → デフォルト（spec-driven）

基本概念

• ワークフローエンジンではなく、成果物グラフ： 依存関係によってアクションが可能になりますが、段階的な進行を強制するものではありません。
• ファイルシステムをデータベースとして使用： 完了状態は保存された状態ではなく、ファイルの有無から判断されます。
• 決定論的な CLI： コマンドには明示的な変更コンテキストが必要です（エージェントは推測しますが、CLI は厳密なままです）。
• XDG によるスキーマ解決： ユーザーによるオーバーライドが組み込みの設定より優先されます。
• テンプレートはスキーマに紐付け： テンプレートはスキーマと同じ場所に置かれ、厳密な2段階のフォールバックで解決されます。

判断ルール

• 意図が変わらず、範囲やアプローチを見直す場合は、update を優先します。
• 意図や範囲が根本的に変わる場合、または元の変更を独立して完了できる場合は、新しい変更を優先します。
• 成果物が変更された理由を明確に追跡できる履歴（proposal/specs/design/tasks）を必ず保持してください。

レシピ

1）次に作成できる成果物を確認する

1. アクティブな変更 ID を特定します。
2. 変更を明示的に指定して、ステータスと作成可能な成果物を照会します。
3. 作成可能な成果物とその依存関係を提示します。

期待される動作：必須の手順ではなく、作成可能な成果物を表示します。

2）特定の成果物向けの指示を生成する

1. XDG フォールバックを使ってスキーマとテンプレートを解決します。
2. コンテキストを構築します：変更メタデータ、依存関係のステータス、対象パス。
3. 拡充した指示をプレーンな Markdown で返します。

3) 新しい変更を開始する

1. 変更名が kebab-case であることを検証します。
2. 変更ディレクトリと README を作成します。
3. 初期ステータスと、最初に準備が整った成果物を表示します。

4) スキーマのカスタマイズに関するガイダンス

1. XDG のオーバーライドパスを説明します。
2. 組み込みのスキーマとテンプレートをコピーする方法を説明します。
3. 一覧表示と解決に使える検証手順または推奨 CLI コマンドを提示します。

5) 変更のスキーマバインディングを説明する

1. 利用できる場合は、変更のメタデータを優先します。
2. 設定されている場合は、プロジェクトのデフォルトスキーマにフォールバックします。
3. それ以外の場合は、spec-driven をデフォルトにします。

禁止事項

• システムを直線的なワークフローエンジンとして扱わないでください。
• 明示的に選択されていない変更を、アクティブだと見なさないでください。
• 報告せずにスキーマやテンプレートを暗黙に切り替えないでください。
• ベンダーのドキュメントを長文でそのままコピーせず、要約して実践的なガイダンスを提示してください。

出力に関する要件

• 成果物の準備状況と依存関係を明確に説明してください。
• 例では変更 ID を明示してください。
• 簡潔で実践的な手順を提示し、情報提供のみか、必須かを示してください。

リンク

• ドキュメント
• リリース
• GitHub
• npm