OpenSpec

Stores (beta) ​

Rencanakan perubahan yang mencakup beberapa repositori: satu store, banyak repo.

OpenSpec biasanya berada di dalam satu repo: folder openspec/ di samping kode yang direncanakannya. Sebuah store memindahkan folder tersebut ke repositori tersendiri, dan beberapa repo kode dapat memakainya bersama-sama.

Setelah setup sekali saja di setiap mesin, perintah seperti status, new change, dan archive dapat bekerja di dalam store dari direktori mana pun.

         team-plans  (sebuah store: OpenSpec di repo-nya sendiri)
         ├── .openspec-store/store.yaml   nama store-nya
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ di-setup sekali di setiap mesin,
                   │ dibagikan dengan push dan clone seperti repo lainnya
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(repo kode)   (repo kode)    (repo kode)

Anda berbagi store dengan git, sama seperti cara Anda berbagi kode: lakukan commit, push, pull, dan review sendiri. Spec dan change mendapatkan branch dan pull request dengan cara yang sama seperti kode.

Kapan Anda membutuhkannya ​

Dua alasan umum untuk menggunakan store:

  • Frontend dan backend di repo terpisah: satu fitur menyentuh keduanya, dan rencananya membutuhkan satu tempat tunggal alih-alih dua bagian terpisah.

          shop-plans  (store)
      └── openspec/changes/add-discounts/    satu rencana untuk fitur tersebut
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(repo frontend)     (repo backend)

  • Satu produk, beberapa repo klien: Android, iOS, dan web dirilis dari repo masing-masing tetapi berbagi satu perilaku yang diharapkan. Spec mendeskripsikan perilaku, bukan implementasi, jadi satu spec dapat dipakai untuk ketiganya.

            product-specs  (store)
        └── openspec/specs/checkout/spec.md    perilaku yang diharapkan
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(repo kode)   (repo kode)   (repo kode)

Anda bisa memiliki lebih dari satu store, meskipun kami menyarankan untuk menjaga jumlahnya tetap sedikit.

Menyiapkan store ​

Satu orang membuat store, lalu semua orang lain bergabung ke store tersebut.

  1. Buat store (satu orang, sekali per tim). Jalankan openspec store setup dan jawab pertanyaan yang muncul:

    bash
    # jalankan dari mana saja; perintah ini menanyakan apa yang akan dibuat dan di mana
openspec store setup

    Perintah ini menanyakan tiga pertanyaan:

    • Nama store: team-plans
    • Di mana store ini sebaiknya disimpan?: sudah diisi otomatis dengan ~/openspec/<name>, tekan Enter untuk menerimanya atau ketik path lain
    • Buat store ini?: menampilkan apa yang akan dibuat, jawab Yes

    Lalu perintah ini melaporkan apa yang telah dibuat:

    yaml
    Store ready: team-plans
Location: ~/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.

  2. Push ke host git Anda. Buat repo team-plans kosong di host Anda terlebih dahulu. Setup tidak menambahkan remote git, jadi hubungkan store ke repo tersebut, lalu push:

    bash
    # hubungkan store ke repo kosong di host git Anda
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# publikasikan
git push -u origin main

  3. Bergabung ke store (setiap anggota tim, sekali per mesin):

    bash
    # dapatkan store ke mesin Anda
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# beri tahu OpenSpec di mana store berada
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Registrasi memberi tahu mesin Anda di mana store ini berada. Nama store sudah di-commit di dalamnya, dalam .openspec-store/store.yaml. Setup telah meregistrasi salinan pembuatnya, jadi hanya salinan hasil clone yang memerlukan langkah ini.

  4. Pastikan berhasil, dari direktori mana pun:

    bash
    # perintah OpenSpec apa pun menjangkau store berdasarkan nama
openspec status --store team-plans
    yaml
    Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

Jenis setup ​

OpenSpec memiliki tiga setup. Bagian selanjutnya dari halaman ini menggunakan nama-nama berikut:

  • repo-local: OpenSpec di dalam repo Anda, tanpa store. Ini default.
  • store-only: repo Anda tidak menyimpan spec atau change miliknya sendiri. Semuanya berada di store.
  • store-optional: proyek Anda memiliki folder openspec/ sendiri dan juga menjangkau store saat Anda memintanya.

Default: OpenSpec di dalam repo Anda (repo-local) ​

openspec init menempatkan folder openspec/ di samping kode Anda, dan spec serta change repo tersebut berada di sana. Tidak ada store yang terlibat. Ini adalah setup yang diajarkan di Set up your project, dan sebagian besar proyek tidak pernah membutuhkan setup lain.

web-app  (code repo)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec di luar repo Anda, di dalam store (store-only) ​

Repo tidak menyimpan spec atau change miliknya sendiri. Semua yang direncanakannya berada di store, dan satu baris di config repo menghubungkan keduanya.

Umum terjadi ketika satu tim membangun semua repo dan merencanakan di satu tempat. Contoh-contoh di atas semuanya memiliki bentuk ini.

team-plans  (store)
└── openspec/
    ├── specs/       the repo's specs live here
    └── changes/     its changes too
          ▲
          │ store: team-plans   (the connecting line)
web-app  (code repo)
└── openspec/
    └── config.yaml    nothing else

OpenSpec di repo Anda dan di store (store-optional) ​

Repo tetap repo-local untuk pekerjaannya sendiri, sementara store menyimpan spec dan change bersama. Di dalam repo, OpenSpec menggunakan folder openspec/ proyek Anda, dan menjangkau store hanya saat Anda meneruskan --store.

Umum terjadi ketika sebuah repo telah menggunakan OpenSpec sebelum store ada, atau ketika repo yang sebagian besar independen hanya sesekali menyentuh pekerjaan bersama.

team-plans  (store)
└── openspec/          the shared specs and changes
          ▲
          │ only when you pass --store team-plans
web-app  (code repo)
└── openspec/          this repo's own
    ├── config.yaml
    ├── specs/
    └── changes/

Sebuah repo dapat dimulai sebagai repo-local dan memindahkan spec serta change-nya ke store nanti. Memindahkan spec dan change sebuah repo ke store menunjukkan caranya.

Di mana artefak dibuat saat menggunakan store ​

Saat Anda menggunakan store, OpenSpec juga harus memutuskan di mana artefak dibuat. Hal ini bergantung pada setup Anda:

  • store-only (proyek Anda hanya menulis ke store): setiap artefak dibuat di store. Baris store: di bawah mencatat hal itu.
  • store-optional (proyek Anda memiliki folder openspec/ sendiri dan juga menggunakan store): artefak dibuat di proyek Anda, kecuali Anda menyebutkan store dalam permintaan atau meneruskan --store untuk change tersebut. Agen Anda kemudian membawa flag itu melalui sisa alur kerja.

OpenSpec menulis artefak ke salah satu dari dua tempat: folder openspec/ proyek Anda, atau folder milik store. OpenSpec memilih dalam urutan ini, dan opsi pertama yang berlaku yang menang:

  1. --store <id> pada sebuah perintah. Selalu menang, dari direktori mana pun.
  2. Folder openspec/ proyek Anda. Jika proyek Anda memiliki folder specs/ atau changes/ sendiri, OpenSpec menggunakannya.
  3. Baris store: di proyek Anda. Cara proyek store-only mencatat store-nya.
  4. defaultStore di mesin Anda. Opsi cadangan ketika tidak ada opsi di atas yang berlaku.

Jika tidak ada satu pun yang berlaku dan Anda memiliki store yang telah diregistrasi, perintah akan gagal dan menampilkan daftarnya. Ketika id sebuah store cocok dengan nama repo Anda di remote origin-nya, error tersebut menyebutkan store itu dan baris store: yang memilihnya. OpenSpec tidak pernah memilih store berdasarkan nama atas kemauannya sendiri, karena repo di organisasi berbeda dapat memiliki nama yang sama.

Saat OpenSpec memilih store, OpenSpec mencetak Using OpenSpec root: ... sebelum output perintah.

Baris store: (proyek store-only) ​

Tambahkan satu baris ke openspec/config.yaml proyek Anda:

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

Semua yang Anda atau agen Anda jalankan di dalam proyek kini menggunakan store, tanpa perlu mengetik flag:

bash
# di dalam web-app, terhubung
openspec status
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans
  • Tanpa baris tersebut: jalankan perintah biasa di proyek store-only dan OpenSpec berhenti dengan error yang menampilkan daftar store yang telah Anda registrasi.
  • Commit baris itu: anggota tim yang melakukan clone proyek Anda juga mendapatkan baris tersebut. Mereka tetap perlu meregistrasi store di mesin mereka (langkah 3 dari Menyiapkan store), atau OpenSpec akan error dan memberi tahu mereka untuk meregistrasinya.
  • Di samping folder nyata: jika proyek Anda juga memiliki folder specs/ atau changes/, OpenSpec menggunakan folder tersebut dan mengabaikan baris itu, dengan peringatan.

Memasang integrasi di repo store-only ​

Jalankan init dari root repo kode untuk memasang file integrasi tool AI tanpa memindahkan perencanaan kembali ke repo tersebut:

bash
# di dalam web-app, di root repositori
openspec init --tools claude
  • File integrasi: ditulis di repo kode.
  • openspec/config.yaml: dipertahankan byte demi byte, termasuk baris store:.
  • openspec/specs/ dan openspec/changes/: tidak dibuat di repo kode.

OpenSpec menolak perintah ini dari subdirektori repo kode. Jalankan dari root repositori.

OpenSpec juga menolak --language di sini karena bahasa tersebut berada di config store eksternal. Jalankan init di root store atau edit config tersebut secara langsung.

defaultStore di mesin Anda ​

Setel sekali jika setiap proyek yang Anda kerjakan menggunakan store yang sama. OpenSpec menggunakan nilai ini sebagai fallback ketika tidak menemukan flag, tidak ada folder openspec/ lokal, dan tidak ada baris store::

bash
# gunakan team-plans setiap kali tidak ada hal lain yang menyebutkan store
openspec config set defaultStore team-plans

# batalkan
openspec config unset defaultStore

Perintah yang tetap lokal. init, update, templates, schemas, dan subperintah openspec schema hanya bekerja pada direktori saat ini dan tidak menerima --store.

Memindahkan spec dan change sebuah repo ke store ​

Untuk mengubah sebuah repo dari repo-local menjadi store-only:

  1. Pindahkan semua isi openspec/specs/ dan openspec/changes/ repo ke folder yang sama di store.
  2. Hapus folder yang kini kosong, sehingga folder openspec/ repo hanya berisi config.yaml.
  3. Tambahkan baris store: ke config.yaml tersebut.

openspec status di dalam repo kini diawali dengan Using OpenSpec root: team-plans.

Bekerja di store ​

Alur kerja tidak berubah, baik bagi Anda maupun agen Anda. Propose, apply, dan archive berjalan seperti biasa. Satu-satunya perbedaan adalah di mana artefak dibuat, dan bagian di atas membahasnya.

Buat change dari dalam repo store-only dan change tersebut akan berada di store:

bash
# di dalam web-app; baris store: mengarahkan ini ke team-plans
openspec new change add-login
yaml
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
  • Ke mana ia pergi: ke repo store, bukan di samping kode Anda.
  • Membagikannya: change hanya ada di checkout Anda sampai Anda commit dan push repo store. Anggota tim melihatnya saat mereka pull. Hal yang sama berlaku untuk setiap artefak yang ditulis alur kerja.
  • Path dalam dokumentasi: di mana pun dokumentasi menampilkan path openspec/, dalam setup store folder tersebut adalah milik store.

Ketika artefak dibuat di tempat yang tidak Anda duga, openspec doctor memeriksa setup Anda tanpa mengubah apa pun dan mencetak perbaikan untuk setiap temuan:

bash
# periksa root saat ini dan store-store-nya
openspec doctor
yaml
Doctor

Root
  Location: /Users/you/openspec/team-plans
  OpenSpec root: ok
  Store: team-plans (metadata ok)

References
  (none declared)

openspec context menampilkan daftar root dan store yang digunakan direktori Anda saat ini, ketika Anda menginginkan gambaran yang sama tanpa pemeriksaan.

Untuk membuka store dan sebuah repo dalam satu jendela editor, agar agen Anda dapat membaca keduanya, lihat Worksets (beta).

Baca spesifikasi dari store lain ​

Repo Anda dapat menyimpan folder openspec/ sendiri dan tetap mengizinkan agent Anda membaca spesifikasi store lain. Deklarasikan store tersebut di bawah references: pada openspec/config.yaml repo Anda:

yaml
# api-server/openspec/config.yaml
references:
  - team-plans

Referensi bersifat read-only. Pekerjaan Anda tetap berada di repo Anda, dan referensi hanya mengubah apa yang disampaikan kepada agent Anda.

Ketika sebuah workflow membuat artifact, instruksinya akan mendapatkan indeks spesifikasi dari store yang direferensikan, masing-masing dilengkapi ringkasan satu baris dan perintah persis untuk mengambilnya:

xml
<referenced_stores>
<!-- Konteks upstream read-only. Ambil apa yang Anda butuhkan; kutip apa yang Anda gunakan. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Aturan untuk menagih dan mengembalikan dana pelanggan.
  Ambil: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Sebuah referensi juga dapat membawa URL clone store, untuk mesin yang belum memiliki store tersebut:

yaml
references:
  - team-plans
  - { id: design-system, remote: "git@github.com:acme/design-system.git" }

Dengan URL yang dideklarasikan, openspec doctor mengubah store yang hilang menjadi perbaikan yang dapat ditempel:

yaml
# keluaran dibungkus agar pas
Referensi
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Store yang direferensikan 'design-system' tidak terdaftar di mesin ini.
    Perbaikan: 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

Batas Beta ​

  • Bentuknya dapat berubah: nama perintah, flag, dan format file dapat berubah antar rilis. Baca ulang halaman ini setelah melakukan upgrade.
  • Tanpa sinkronisasi, secara desain: OpenSpec tidak pernah melakukan clone, pull, atau push. Checkout yang basi menunjukkan spesifikasi yang basi sampai Anda melakukan pull, dan referensi dibaca dari apa pun yang ada di disk.
  • Satu checkout per nama store: mendaftarkan folder kedua di bawah nama yang sudah terdaftar akan gagal, dengan petunjuk untuk menjalankan openspec store unregister terlebih dahulu.