ストア: 独自のリポジトリで計画する

ベータ版です。 ストア、参照、ワーキングコンテキスト、ワークセットは新機能です。コマンド名、フラグ、ファイル形式、JSON出力は、リリース間でまだ変更される可能性があります。以下のすべてのウォークスルーは現在のビルドに対して実行されましたが、アップグレード後にこのガイドを再度読むことをお勧めします。

これが解決する問題

OpenSpecは通常、1つのコードリポジトリ内に存在します。コードの隣にある openspec/ フォルダが、そのリポジトリの仕様と変更を保持しています。

しかし、計画が1つのリポジトリの規模を超えた瞬間に、これは適合しなくなります。

• 作業が複数のリポジトリにまたがる場合 — 1つの機能がAPIサーバー、Webアプリ、共有ライブラリに影響を与えるとします。計画はどのリポジトリの openspec/ フォルダに置くべきでしょうか？
• コードが存在する前に計画を立てる場合、またはこのリポジトリのコードになることのないものを計画する場合。
• 要件が1つのチームによって所有され、他のチームによって消費される場合。Wikiのバージョンは乖離し、コーディングエージェントは結局それを読むことができません。

ストアがその答えです。計画のみを目的とするスタンドアロンのリポジトリです。すでに知っている openspec/ の構造（仕様と変更）に加えて、小さなアイデンティティファイルを持っています。マシン上で名前を付けて一度登録すれば、後はどこからでも通常のOpenSpecコマンドをその中で実行できます。

形状

            team-plans  (ストア: 自リポジトリ内で計画を管理)
            ├── .openspec-store/store.yaml     ID: "I am team-plans"
            └── openspec/
                ├── specs/      真実 (現状の仕様)
                └── changes/    進行中の変更
                      ▲
                      │ 各マシンに名前で登録される;
                      │ 通常のリポジトリと同様にプッシュ/クローンで共有
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (コードリポジトリ)   (コードリポジトリ)   (コードリポジトリ)

このシンプルさを保つための2つのルール:

1. ストアは単なるGitリポジトリです。 コミット、プッシュ、プル、レビューはすべて自分で行います。OpenSpecは決して自動的にクローンしたり、同期したり、プッシュしたりしません。
2. 仕組みではなく宣言。 リポジトリはストアとの関係を宣言できます（下記参照）。宣言はOpenSpecが伝えられる内容を変えるだけで、コマンドが動作する場所を変えることはありません。

最初のストアまで5分

2つのコマンドで、何もない状態からストアスコープの変更を機能させるところまで進めます:

openspec store setup team-plans --path ~/openspec/team-plans

Store ready: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share this store by committing and pushing it like any Git repo.

openspec new change add-login --store team-plans

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Next: openspec status --change add-login --store team-plans

これが全体モデルです。以降のライフサイクルは、status、instructions、validate、archive など、ご存知の操作とまったく同じで、各コマンドに --store team-plans を付けます。表示されるすべてのヒントにはフラグが含まれます。Using OpenSpec root: の行は、コマンドがどこで動作しているかを常に示します。

ストーリー: 1つのチーム、1つの計画リポジトリ

チームは仕様と変更をコードリポジトリに散らばらせる代わりに、team-plans に保持します。

初日（セットアップ担当者）:

openspec store setup team-plans --path ~/openspec/team-plans \
  --remote git@github.com:acme/team-plans.git
git -C ~/openspec/team-plans push -u origin main

--remote を渡すと、クローンURLがストア自身のIDファイル（.openspec-store/store.yaml）内の最初のコミットに記録されます。将来のすべてのクローンは、その由来を知った状態で作成されるため、ヘルスチェックやエラーメッセージで、まだストアを持っていないチームメイト向けに、コピー＆ペースト可能な完全な修正手順を表示できます。

すべてのチームメイト（マシンごとに1回）:

git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans

以降、全員が名前で同じ計画リポジトリを操作します:

openspec status --store team-plans --change add-login
openspec show add-login --store team-plans

作業の共有は意図的にGitを使用します。 作成した変更は、コミットしてプッシュするまで自分のチェックアウト内にのみ存在します。コードと同じです。ストアは通常のリポジトリであるため、計画にはブランチ、プルリクエスト、レビューが自動的に付いてきます。

チームのコードリポジトリとの接続。 計画を完全に外部化しているコードリポジトリでは、openspec/config.yaml に1行だけ追加する必要があります:

# web-app/openspec/config.yaml
store: team-plans

これで、web-app 内で実行されるすべてのOpenSpecコマンドは、フラグなしで team-plans に対して動作します:

cd ~/src/web-app
openspec status --change add-login

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
...

ポインタはフォールバックであり、オーバーライドではありません。明示的な --store が常に優先され、リポジトリが独自の実際の計画フォルダを持つ場合は、それらが優先されます（古いポインタを削除するよう警告が出ます）。

マシン上のすべてのリポジトリに1つのデフォルト。 多くのコードリポジトリで同じストアに計画を置いている場合、各リポジトリに store: 行を追加する代わりに、グローバルに一度だけ設定します:

openspec config set defaultStore team-plans

これで、計画ルート外で実行され、--store もプロジェクトポインタも指定されていないコマンドはすべて team-plans に解決されます。これは優先順位の最下位に位置するため、--store、ローカルルート、プロジェクトの store: ポインタはすべて優先されます。ルートバナーとJSONの root ブロックは、source: "global_default" とストアIDを報告するため、マシン全体のデフォルトとリポジトリ自身のポインタを常に区別できます。クリアは openspec config unset defaultStore で行います。IDが未登録の場合、コマンドはエラーを出し、登録するか古いデフォルトをクリアするよう指示します。

例: 1つの機能、2つのコンポーネントリポジトリ

add-checkout-promo が checkout-api と checkout-web の両方を変更するとします。チームは共有の製品契約を1つ持ちたい一方で、各コードリポジトリは独自の実装タスク、ブランチ、レビューを必要とします。

2つのレイヤーを使用します:

1. 共有の動作は team-plans に保持します。
2. 実装計画は各コンポーネントリポジトリに保持し、ストアを読み取り専用の上流コンテキストとして参照します。

まず、ストアで共有契約を計画します:

openspec new change add-checkout-promo --store team-plans
openspec status --change add-checkout-promo --store team-plans

プロポーザルと仕様は、コンポーネント間の境界での動作を記述する必要があります。たとえば、サービスが返すプロモーションフィールドや、フロントエンドが不適格なチェックアウトをどう処理するかなどです。この変更は、他のブランチやプルリクエストと同様にストアリポジトリでレビューします。

計画はどのようなコンテキストを参照しますか?

ストアを選択するとOpenSpecルートが変わります。そのストアを使用するすべてのコードリポジトリを自動的に発見して読み込むわけではありません。ストアの指示は、ストア内の成果物と設定されたコンテキストを参照します。コンポーネントコードを参照するのは、それらのフォルダがエージェントやエディタでも利用可能で、エージェントが読み込んだ場合のみです。

ワークセットは、計画ストアと両方のコードリポジトリを一緒に開く便利な方法です:

openspec workset create checkout-promo \
  --member ~/openspec/team-plans \
  --member ~/src/checkout-api \
  --member ~/src/checkout-web \
  --tool code
openspec workset open checkout-promo

これにより、フォルダが1つのIDEワークスペースで表示されます。ソースコンテキストをストアにコピーしたり、影響を受けるリポジトリを選択したり、エージェントに編集権限を付与したりするわけではありません。永続的なクロスコンポーネントの事実は共有仕様に置きます。プランナーがたまたま調べたソースを記憶していることに頼らないでください。

各リポジトリでの実装はどう始まりますか?

明示的な --store やより近い openspec/ ルートが適用されない場合、store: team-plans ポインタはコマンドをそのストアにルーティングします。これは、apply が呼び出されたディレクトリによってストアのタスクリストを分割するものではありません。OpenSpecは現在、タスクをリポジトリにルーティングしません。

各コンポーネントが独立したスコープの apply/review サイクルを必要とする場合は、ローカルのOpenSpecルートを設定し、中央ストアを直接指す代わりに参照します:

# checkout-api/openspec/config.yaml (checkout-web にも同様)
schema: spec-driven
references:
  - team-plans

共有契約が承認され、ストアのメイン仕様で利用可能になったら、コンポーネントの部分に対して小さなローカル変更を作成します:

cd ~/src/checkout-api
openspec new change implement-checkout-promo-api

cd ~/src/checkout-web
openspec new change implement-checkout-promo-ui

各リポジトリの指示にある参照インデックスは、ストア仕様の要約と正確な取得コマンド (openspec show ... --store team-plans) を提供します。各ローカルプロポーザルはその共有契約を引用し、タスクはそのコンポーネント内の作業のみを記述します。その後、各リポジトリで個別に /opsx:apply を実行します。ルート解決により、成果物と実装編集はそのリポジトリにスコープされます。サービスとフロントエンドの変更は、これで独立してテスト、レビュー、マージ、アーカイブできます。

共有ストアの変更がまだアクティブな間に実装を開始する必要がある場合は、openspec show add-checkout-promo --store team-plans で明示的に取得します。参照インデックスは、アクティブなストアの変更ではなく、標準のストア仕様を一覧表示します。レビューアーが各実装がどのバージョンの契約に従っているかを確認できるように、ストアのブランチとコンポーネントのブランチをプルリクエストの説明で関連付けてください。

ストーリー: チームの境界を越える要件

プラットフォームチームが要件を所有しています。製品チームは、各自のリポジトリで、各自の設計に基づいてそれらに対して開発します。参照は、誰の作業も移動させることなく、その関係を記述します。

   platform-reqs (ストア)                 api-server (コードリポジトリ)
   プラットフォームチームが所有            製品チームが所有
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ 読み取り │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (独自の設計)            │
   │   platform work          │          │ openspec/changes/        │
   │                          │          │   (独自の作業)            │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

製品チームは、リポジトリの openspec/config.yaml で何を参照するかを宣言します:

references:
  - platform-reqs

参照は読み取り専用のコンテキストです。リポジトリは独自の openspec/ ルートを維持し、作業はそこに残ります。変更されるのは、openspec instructions が、参照先ストアの仕様のインデックス（各仕様に1行の要約と正確な取得コマンド openspec show <spec-id> --type spec --store platform-reqs）をそのリポジトリで含むようになることです。api-server で作業するエージェントは、上流の支払い要件を見つけ、引用し、独自のルートでその低レベル設計を書くことができます。誰かがコンテキストを貼り付ける必要はありません。

参照にはクローンソースを含めることができ、まだストアを持っていないチームメイトは行き詰まる代わりに完全な修正手順を得られます:

references:
  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }

計画とコードを一緒に開きたい場合は、ワークセットを作成します。 これは個人的かつ明示的です。各人が自分のマシンで実際に作業するフォルダを選択します。ローカルチェックアウトパスについての情報が共有計画リポジトリにコミットされることはありません。

openspec workset create platform \
  --member ~/openspec/platform-reqs \
  --member ~/src/api-server \
  --member ~/src/web-app

いつでも質問できる2つのこと

「セットアップは健全か?」 — openspec doctor は、現在のルートとその参照ストアを読み取り専用でチェックし、各発見項目に対してコピー＆ペースト可能な修正手順を提供します:

Doctor

Root
  Location: /Users/you/src/api-server
  OpenSpec root: ok

References
  - platform-reqs: ok (/Users/you/openspec/platform-reqs)
  - design-system: Referenced store 'design-system' is not registered on this machine.
    Fix: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' && openspec store register '/Users/you/openspec/design-system' --id design-system

「何を使って作業しているか?」 — openspec context は、OpenSpecの宣言から作業セットを組み立てます: ルートとそれが参照するストアです。

Working context for api-server (/Users/you/src/api-server)

OpenSpec root
  api-server  /Users/you/src/api-server

Referenced stores
  platform-reqs  /Users/you/openspec/platform-reqs
    Fetch: openspec show <spec-id> --type spec --store platform-reqs

どちらもエージェント向けに --json をサポートしています。openspec context --code-workspace <path> はさらに、セット全体を含むVS Codeワークスペースファイルを書き出します — これがこのコマンドが実行する唯一の書き込みです。

ワークセット：共同で作業するフォルダを再開する

上記のすべてとは別に、多くのユーザーはセッションごとに同じ数少ないフォルダを開きます — 計画用リポジトリと2〜3つのコードリポジトリなどです。ワークセットとは、まさにそのための個人用・名前付きビューであり、お好みのツールで1つのコマンドで再開することができます。

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       3つともあなたのツールで開かれる

openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list

platform  (VS Code で開く)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

openspec workset open platform は保存されたツールを起動します。エディタ（VS Code、Cursor）はすべてのメンバーを含む1つのウィンドウを開き、終了します。最初のメンバーがプライマリーとなります。--tool <id> を使用していつでもツールを上書きできます。

ワークセットは意図的に 共有状態 ではありません。それらはあなたのマシン上に存在し、コミットされることはなく、作業内容について何らかの主張を行うこともありません — あなたが一緒に開いておくことを好むものを記録するだけです。1つを取り除いてもメンバーフォルダには影響しません。新しいツールはコードではなく設定です：ワークスペースファイルやフォルダごとのアタッチフラグ経由で起動できるものは何でも、グローバル設定（openspec config edit）の openers キーの下に追加できます。

コマンドがどこで動作するかを決定する方法

通常のすべてのコマンドは、以下の順序でルートと同じ方法で解決します。

1. --store <id>          明示的に指定した場合        → そのストア
2. nearest openspec/     ここに実際の計画ルートがある→ このリポジトリ
   (cwd から上方向へ探索)
3. store: ポインター     config.yaml がストアを宣言  → そのストア
4. defaultStore          グローバル設定がマシンに    → そのストア
                         デフォルトを設定
5. 上記のいずれでもない  このマシンに登録されたストア→ エラー（選択のヒント付き）
                         登録済みストアなし？        → カレントディレクトリ
                                                          （従来の動作）

Using OpenSpec root: の行（および --json 出力内の root ブロック）は、どのケースに該当しているかを示します。

既知の制限事項

• ベータ版の形状。 このページにあるものはリリース間で変更される可能性があります — 名前、フラグ、ファイル形式、JSON キーなど。
• マシンごとにストアIDにつき1つのチェックアウトのみ。 同じIDの下に2番目のチェックアウトを登録しようとすると、まず store unregister を行うようヒント付きで失敗します。
• 同期は一切行わない — これは設計によるもの。 OpenSpec はクローン、プル、プッシュを行いません。古いチェックアウトでは、あなたが プルするまで仕様が古いままで表示されます。参照はディスク上のものからライブでインデックス付けされます。
• 空の計画フォルダが存在しない場合があります。 新しいストアには、Git に openspec/changes/、openspec/specs/、または openspec/changes/archive/ がまだ含まれていないことがあります。これはベータ期間中は許容され、通常のコマンドがそれらのファイルを作成すると、これらのフォルダが表示されます。
• ポインターリポジトリはポインターのまま。 openspec/config.yaml が store: <id> を宣言する設定専用リポジトリは、外部化された計画として扱われ、登録すべきストアチェックアウトとしては扱われません。そのリポジトリをローカルストアルートに変換したい場合は、まず store: ラインを削除してください。
• 一部のコマンドはその場にとどまります。 templates と非推奨の名詞形（openspec change show など）はカレントディレクトリのみに作用し、--store は受け付けません。schemas は標準的なルート選択優先順位に従い、--store <id> を受け付けますが、成功したJSON配列の形状はそのまま維持されます。
• マシン固有の状態はマシン固有です。 ストアレジストリとワークセットはローカル設定です。あなたのマシンのレイアウトに関する情報は、共有計画にコミットされることはありません。
• ワークセットには2つの起動スタイルがあります。 ワークスペースファイルやフォルダごとのアタッチフラグで起動できないツールは、オープナーとして追加できません。
• エージェントJSONには既知の大文字小文字の分割がある（ストアファミリーキーは snake_case、ワークフローファミリーは camelCase）。エージェント契約 で文書化されており、統一はバージョン付きリリースに延期されています。

各要素の場所

対象	場所	共有？
ストアの計画	<store>/openspec/ (specs, changes)	はい — コミットしてプッシュしてください
ストアの識別情報	<store>/.openspec-store/store.yaml	はい — ストアとともにコミットされます
ストアレジストリ	<data dir>/openspec/stores/registry.yaml	いいえ — このマシンのみ
ワークセット	<data dir>/openspec/worksets/	いいえ — このマシンのみ

<data dir> は macOS および Linux では ~/.local/share/openspec（または $XDG_DATA_HOME/openspec が設定されている場合）、Windows では %LOCALAPPDATA%\openspec です。

リファレンス

このページのコマンドのすべてのフラグおよび JSON 形状の詳細： CLI リファレンス（Stores, Doctor, Working context, Personal worksets）および エージェント契約。