Stores: Merencanakan di Repo Sendiri

Beta. Stores, referensi, konteks kerja, dan workset adalah hal baru. Nama perintah, flag, format berkas, dan keluaran JSON mungkin masih berubah bentuk antar rilis. Setiap walkthrough di bawah dijalankan terhadap build saat ini, tetapi baca ulang panduan ini setelah pembaruan.

Masalah yang Diselesaikan

OpenSpec biasanya berada di dalam satu repo kode: folder openspec/ di samping kode Anda, yang memuat spesifikasi dan perubahan untuk repo tersebut.

Hal itu tidak lagi cocok ketika perencanaan Anda lebih luas dari satu repo:

• Pekerjaan Anda meliputi beberapa repo — satu fitur menyentuh server API, aplikasi web, dan pustaka bersama. Di folder openspec/ mana rencana itu berada?
• Tim Anda merencanakan sebelum kode ada, atau merencanakan hal-hal yang tidak pernah menjadi kode di repo ini.
• Persyaratan dimiliki oleh satu tim dan digunakan oleh tim lain. Versi wiki menjadi tidak sinkron, dan agen pengkodean Anda tidak dapat membacanya.

store adalah jawabannya: repo mandiri yang seluruh tugasnya adalah perencanaan. Ia memiliki struktur openspec/ yang sudah Anda kenal — spesifikasi dan perubahan — ditambah berkas identitas kecil. Anda mendaftarkannya di mesin Anda satu kali, berdasarkan nama, dan kemudian setiap perintah OpenSpec normal dapat bekerja di dalamnya dari mana saja.

Bentuknya

            team-plans  (a store: planning in its own repo)
            ├── .openspec-store/store.yaml     identity: "I am team-plans"
            └── openspec/
                ├── specs/      what is true
                └── changes/    what is in motion
                      ▲
                      │ registered on each machine by name;
                      │ shared by pushing/cloning like any repo
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (code repo)   (code repo)    (code repo)

Dua aturan menjaga kesederhanaan ini:

1. Store hanyalah repo git. Anda melakukan commit, push, pull, dan review sendiri. OpenSpec tidak pernah melakukan clone, sync, atau push apa pun secara mandiri.
2. Deklarasi, bukan mekanisme. Repo dapat mendeklarasikan bagaimana mereka berhubungan dengan store (ditunjukkan di bawah). Deklarasi mengubah apa yang dapat dikatakan OpenSpec kepada Anda — bukan di mana perintah Anda beroperasi.

Lima menit menuju store pertama Anda

Dua perintah membawa Anda dari nol ke perubahan yang berfungsi dengan cakupan store:

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

Itulah seluruh modelnya. Dari sini, siklus hidupnya persis seperti yang Anda ketahui — status, instructions, validate, archive — dengan --store team-plans pada setiap perintah, dan setiap petunjuk yang dicetak membawa flag tersebut untuk Anda. Baris Using OpenSpec root: selalu memberitahu Anda di mana perintah beroperasi.

Cerita: satu tim, satu repo perencanaan

Sebuah tim menyimpan spesifikasi dan perubahan mereka di team-plans alih-alih menyebarluaskannya di berbagai repo kode.

Hari pertama (siapa pun yang mengaturnya):

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

Menyertakan --remote mencatat URL clone di dalam file identitas store itu sendiri (.openspec-store/store.yaml), pada commit awal. Setiap clone di masa depan lahir dengan mengetahui asal-usulnya, sehingga pemeriksaan kesehatan dan pesan galat dapat mencetak perbaikan lengkap yang dapat ditempel untuk rekan tim yang belum memilikinya.

Setiap rekan tim (satu kali per mesin):

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

Setelah itu, semua orang bekerja di repo perencanaan yang sama berdasarkan nama:

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

Berbagi pekerjaan adalah git, dengan sengaja. Perubahan yang Anda buat hanya ada di checkout Anda sampai Anda melakukan commit dan push — sama seperti kode. Rencana mendapat branch, pull request, dan review secara gratis, karena store adalah repo biasa.

Menghubungkan repo kode tim. Repo kode yang perencanaan sepenuhnya di-eksternalisasikan hanya membutuhkan satu baris, di openspec/config.yaml:

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

Sekarang setiap perintah OpenSpec yang dijalankan di dalam web-app beroperasi pada team-plans tanpa flag apa pun:

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

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

Penunjuk ini adalah fallback, bukan override: --store eksplisit selalu mengalahkan, dan jika repo tumbuh memiliki folder perencanaan sendiri, folder tersebut yang menang (dengan peringatan untuk menghapus penunjuk yang sudah tidak relevan).

Satu default untuk setiap repo di mesin Anda. Jika Anda bekerja di banyak repo kode yang semuanya merencanakan ke store yang sama, atur sekali, secara global, alih-alih menambahkan baris store: ke setiap repo:

openspec config set defaultStore team-plans

Sekarang perintah apa pun yang dijalankan di luar root perencanaan — dan tanpa --store serta tanpa penunjuk proyek — akan di-resolve ke team-plans. Ini berada di bagian bawah daftar prioritas, sehingga --store, root lokal, dan penunjuk store: proyek tetap menang. Banner root dan blok JSON root melaporkan source: "global_default" dengan id store, sehingga Anda selalu dapat membedakan default seluruh mesin dari penunjuk repo itu sendiri. Hapus dengan openspec config unset defaultStore. Jika id tidak terdaftar, perintah akan menghasilkan galat dan memberitahu Anda untuk mendaftarkannya atau menghapus default yang sudah tidak relevan.

Contoh: satu fitur, dua repo komponen

Misalkan add-checkout-promo mengubah baik checkout-api maupun checkout-web. Tim menginginkan satu kontrak produk bersama, sementara setiap repo kode tetap membutuhkan tugas implementasi, branch, dan review masing-masing.

Gunakan dua lapisan:

1. Simpan perilaku bersama di team-plans.
2. Simpan rencana implementasi di setiap repo komponen dan rujuk store sebagai konteks upstream read-only.

Pertama, rencanakan kontrak bersama di store:

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

Proposal dan spesifikasi harus menggambarkan perilaku di batas antara komponen — misalnya, field promosi yang dikembalikan oleh layanan dan bagaimana frontend menangani checkout yang tidak memenuhi syarat. Review perubahan ini di repo store seperti branch dan pull request lainnya.

Konteks apa yang dilihat perencanaan?

Memilih store mengubah root OpenSpec; itu tidak menemukan atau membaca setiap repo kode yang menggunakan store tersebut. Instruksi store melihat artefak dan konteks yang dikonfigurasi di store. Mereka melihat kode komponen hanya ketika folder tersebut juga tersedia untuk agen atau editor dan agen membacanya.

Workset adalah cara yang nyaman untuk membuka store perencanaan dan kedua repo kode bersama-sama:

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

Ini membuat folder terlihat di satu workspace IDE. Ini tidak menyalin konteks sumber ke dalam store, memilih repo yang terpengaruh, atau memberikan agen izin untuk mengeditnya. Letakkan fakta lintas komponen yang tahan lama di spesifikasi bersama; jangan mengandalkan perencana mengingat sumber yang kebetulan diperiksa.

Bagaimana implementasi dimulai di setiap repo?

Ketika tidak ada --store eksplisit atau root openspec/ yang lebih dekat berlaku, penunjuk store: team-plans mengarahkan perintah ke store tersebut. Ini tidak memecah satu daftar tugas store berdasarkan direktori tempat apply dipanggil. OpenSpec saat ini tidak mengarahkan tugas ke repo.

Ketika setiap komponen membutuhkan siklus apply/review yang di-cakop secara independen, berikan root OpenSpec lokal dan rujuk store pusat alih-alih menunjuk ke store tersebut:

# checkout-api/openspec/config.yaml (and likewise in checkout-web)
schema: spec-driven
references:
  - team-plans

Setelah kontrak bersama disetujui dan tersedia di spesifikasi utama store, buat perubahan lokal kecil untuk bagian komponen:

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

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

Indeks referensi di instruksi setiap repo menyediakan ringkasan spesifikasi store dan perintah fetch yang tepat openspec show ... --store team-plans. Setiap proposal lokal mengutip kontrak bersama tersebut, dan tugasnya hanya menggambarkan pekerjaan di komponen tersebut. Kemudian jalankan /opsx:apply di setiap repo secara terpisah; resolusi root menjaga artefak dan pengeditan implementasi tetap di-cakop ke repo tersebut. Perubahan layanan dan frontend sekarang dapat diuji, direview, digabung, dan diarsipkan secara independen.

Jika implementasi harus dimulai sementara perubahan store bersama masih aktif, ambil secara eksplisit dengan openspec show add-checkout-promo --store team-plans; indeks referensi mencantumkan spesifikasi store yang kanonik, bukan perubahan store yang aktif. Jaga agar branch store dan branch komponen tetap terhubung dalam deskripsi pull request mereka sehingga reviewer dapat melihat versi kontrak mana yang diikuti setiap implementasi.

Cerita: persyaratan yang melintasi garis tim

Tim platform memiliki persyaratan. Tim produk membangun berdasarkan persyaratan tersebut, di repo mereka sendiri, dengan desain mereka sendiri. Referensi menggambarkan hubungan tersebut tanpa memindahkan pekerjaan siapa pun.

   platform-reqs (store)                 api-server (code repo)
   owned by the platform team            owned by a product team
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ reads    │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (their own designs)    │
   │   platform work          │          │ openspec/changes/        │
   │                          │          │   (their own work)       │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

Tim produk mendeklarasikan apa yang mereka gunakan di openspec/config.yaml repo mereka:

references:
  - platform-reqs

Referensi adalah konteks read-only. Repo tetap memiliki root openspec/ sendiri; pekerjaan tetap di sana. Yang berubah: openspec instructions di repo tersebut sekarang mencakup indeks spesifikasi store yang dirujuk — masing-masing dengan ringkasan satu baris dan perintah fetch yang tepat (openspec show <spec-id> --type spec --store platform-reqs). Agen yang bekerja di api-server dapat menemukan persyaratan pembayaran upstream, mengutipnya, dan menulis desain tingkat rendah di root repo sendiri — tanpa siapa pun menempelkan konteks di sekitar.

Referensi dapat membawa sumber clone-nya, sehingga rekan tim yang belum memiliki store tersebut mendapatkan perbaikan lengkap alih-alih jalan buntu:

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

Ketika Anda ingin rencana dan kode terbuka bersama, buat workset. Ini pribadi dan eksplisit: setiap orang memilih folder yang benar-benar mereka gunakan di mesin mereka. Tidak ada yang terkait dengan jalur checkout lokal tersebut yang di-commit ke repo perencanaan bersama.

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

Dua pertanyaan yang selalu dapat Anda ajukan

"Apakah setup saya sehat?" — openspec doctor memeriksa root saat ini dan store yang dirujuk, read-only, dengan perbaikan yang dapat ditempel untuk setiap temuan:

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

"Apa yang sedang saya kerjakan?" — openspec context merangkai set kerja dari deklarasi OpenSpec: root dan store yang dirujuknya.

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

Keduanya mendukung --json untuk agen. openspec context --code-workspace <path> juga menulis file workspace VS Code yang berisi seluruh set — satu-satunya penulisan yang dilakukan perintah ini.

Workset: buka kembali folder yang Anda kerjakan bersama

Terpisah dari semua hal di atas: sebagian besar orang membuka beberapa folder yang sama secara bersamaan setiap sesi — repo perencanaan ditambah dua atau tiga repo kode. Sebuah workset adalah tampilan pribadi yang diberi nama untuk hal tersebut, dibuka kembali dengan satu perintah di alat pilihan Anda.

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       ketiganya terbuka di alat Anda

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

platform  (terbuka di VS Code)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

openspec workset open platform kemudian meluncurkan alat yang tersimpan: editor (VS Code, Cursor) membuka satu jendela dengan semua anggota dan kembali. Anggota pertama adalah yang utama. Ganti alat kapan saja dengan --tool <id>.

Workset sengaja tidak sebagai status yang dibagikan. Workset ada di mesin Anda, tidak pernah dikomit, dan tidak membuat klaim tentang pekerjaan — workset hanya mencatat apa yang Anda suka buka bersama. Menghapus worket tidak akan menyentuh folder anggota. Alat baru adalah konfigurasi, bukan kode: apa pun yang diluncurkan melalui berkas ruang kerja atau flag lampiran per folder dapat ditambahkan di bawah kunci openers dalam konfigurasi global (openspec config edit).

Bagaimana perintah memutuskan di mana harus bertindak

Setiap perintah normal menentukan root-nya dengan cara yang sama, dalam urutan ini:

1. --store <id>          Anda menyatakannya secara eksplisit        → store tersebut
2. nearest openspec/     root perencanaan nyata di sini            → repo ini
   (berjalan ke atas dari cwd)
3. store: pointer        config.yaml mendeklarasikan store          → store tersebut
4. defaultStore          konfigurasi global mengatur default mesin  → store tersebut
5. tidak ada di atas     ada store terdaftar di mesin ini?          → error dengan
                                                                    petunjuk pemilihan
                         tidak ada store terdaftar?                 → direktori saat ini
                                                                    (perilaku klasik)

Baris Using OpenSpec root: (dan blok root di output --json) memberi tahu Anda kasus mana yang sedang berlaku.

Keterbatasan yang diketahui

• Bentuk beta. Semua yang ada di halaman ini dapat berubah antar rilis — nama, flag, format berkas, kunci JSON.
• Satu checkout per id store per mesin. Mendaftarkan checkout kedua dengan id yang sama gagal dengan petunjuk untuk store unregister terlebih dahulu.
• Tidak ada sinkronisasi, pernah — berdasarkan desain. OpenSpec tidak pernah mengkloning, menarik, atau mendorong. Checkout usang menampilkan spesifikasi usang hingga Anda melakukan pull; referensi diindeks langsung dari apa pun yang ada di disk.
• Folder perencanaan kosong bisa tidak ada. Store baru mungkin belum memiliki openspec/changes/, openspec/specs/, atau openspec/changes/archive/ di Git. Hal itu diterima selama beta; folder tersebut muncul setelah perintah normal membuat berkas untuknya.
• Repo penunjuk tetap sebagai penunjuk. Repo khusus konfigurasi yang openspec/config.yaml mendeklarasikan store: <id> dianggap sebagai perencanaan yang dieksternalisasi, bukan sebagai checkout store untuk didaftarkan. Hapus baris store: terlebih dahulu jika Anda sengaja ingin mengubah repo itu menjadi root store lokal.
• Beberapa perintah tetap di tempatnya. templates dan bentuk kata benda yang sudah usang (openspec change show, ...) hanya bertindak pada direktori saat ini — tidak ada --store. schemas mengikuti presedensi pemilihan root kanonis dan menerima --store <id> sambil mempertahankan bentuk array JSON yang berhasil tidak berubah.
• Status per mesin adalah per mesin. Registri store dan workset adalah pengaturan lokal. Tidak ada tentang tata letak mesin Anda yang pernah dikomit ke perencanaan bersama.
• Dua gaya peluncuran untuk workset. Alat yang tidak dapat diluncurkan dengan berkas ruang kerja atau flag lampiran per folder tidak dapat ditambahkan sebagai pembuka.
• JSON agen memiliki pemisahan casing yang diketahui (kunci keluarga store adalah snake_case, keluarga alur kerja camelCase). Didokumentasikan di kontrak agen; penyatuannya ditunda hingga rilis berversi.

Tempat penyimpanan

Apa	Di mana	Dibagikan?
Perencanaan store	<store>/openspec/ (spesifikasi, perubahan)	Ya — commit dan push
Identitas store	<store>/.openspec-store/store.yaml	Ya — dikomit bersama store
Registri store	<data dir>/openspec/stores/registry.yaml	Tidak — hanya mesin ini
Workset	<data dir>/openspec/worksets/	Tidak — hanya mesin ini

<data dir> adalah ~/.local/share/openspec di macOS dan Linux (atau $XDG_DATA_HOME/openspec jika diatur), dan %LOCALAPPDATA%\openspec di Windows.

Referensi

Flag dan bentuk JSON yang tepat untuk setiap perintah di halaman ini: Referensi CLI (Store, Doctor, Konteks kerja, Workset pribadi) dan kontrak agen.