Skema

Ubah apa yang dihasilkan OpenSpec: artefak, urutannya, dan templatnya.

Skema mendefinisikan apa yang dihasilkan sebuah proposal perubahan: artefak mana, dalam urutan apa, dari templat mana. Misalnya, spec-driven, skema bawaan default, menghasilkan empat artefak berikut secara garis besar dalam urutan ini, masing-masing dibangun di atas yang sebelumnya:

proposal → specs → design → tasks

Lakukan fork pada skema ketika Anda ingin dokumen-dokumen tersebut menjadi berbeda, baik itu berarti jumlahnya lebih sedikit, namanya berbeda, atau strukturnya berbeda.

Lokasi skema

OpenSpec mencari skema di tiga tempat, secara berurutan, dan menggunakan yang pertama ditemukan:

1. Proyek Anda: openspec/schemas/, di-commit bersama repo agar seluruh tim Anda mendapatkannya.
2. Mesin Anda: ~/.local/share/openspec/schemas di macOS dan Linux (atau di bawah $XDG_DATA_HOME jika Anda mengaturnya), atau %LOCALAPPDATA%\openspec\schemas di Windows. Skema di sini tersedia di setiap proyek tempat Anda bekerja.
3. Paket: skema bawaan, seperti spec-driven, disertakan di dalam openspec itu sendiri.

Nama yang sama dapat muncul di lebih dari satu tempat, dan lokasi yang lebih spesifik akan diutamakan. openspec schema which menunjukkan salinan mana yang sedang digunakan:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Isi skema

Skema didefinisikan oleh sebuah folder berisi file-file biasa: satu schema.yaml yang mendeklarasikan artefak, dan satu templat untuk masing-masing artefak. Berikut adalah spec-driven bawaan:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: mendeklarasikan setiap artefak, file yang dihasilkannya, templat yang menjadi titik awalnya, apa yang diperlukan terlebih dahulu, dan instruksi yang diterima agen saat membuatnya. Kontrak setiap field dijelaskan di schema.yaml.
• templates/: satu kerangka markdown per artefak, yang diisi oleh agen.

Berikut entri artefak tasks dalam schema.yaml, versi ringkasnya:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

Skema bawaan disertakan di dalam paket openspec, jadi Anda tidak pernah mengeditnya langsung di tempat. Anda mendapatkan salinan sendiri dengan melakukan fork.

Membuat skema kustom Anda sendiri

Ada dua cara untuk mendapatkan skema Anda sendiri:

1. Lakukan fork pada skema yang sudah ada dan edit salinan Anda. Mulailah di sini jika skema yang ada sudah mendekati kebutuhan Anda, karena semua di dalamnya sudah berfungsi.
2. Mulai dari awal ketika tidak ada yang cocok, dengan membuat kerangka skema kosong menggunakan openspec schema init.

Lakukan fork pada skema yang sudah ada

1. Lakukan fork pada skema yang ingin Anda jadikan titik awal, dengan menjalankannya dari root proyek Anda:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Berikan argumen kedua untuk memilih nama (openspec schema fork spec-driven team-flow). Nama ditulis dalam kebab-case.

2. Edit salinannya: schema.yaml dan templat-templatnya. Mengedit hasil fork Anda membahas apa yang perlu diubah.

3. Validasi skema tersebut:

   openspec schema validate spec-driven-custom

   Ini adalah satu-satunya perintah yang mendeteksi skema rusak (templat hilang, YAML tidak valid, siklus dependensi) sebelum Anda berada di tengah-tengah perubahan.

4. Arahkan proyek Anda ke skema tersebut di openspec/config.yaml. Langkah ini perlu Anda lakukan sendiri karena proses fork tidak menyentuh config.yaml:

   schema: spec-driven-custom

5. Proposal perubahan baru sekarang mengikuti skema Anda. Perubahan yang dibuat sebelumnya tetap menggunakan skema yang dipakai saat dibuat.

Untuk mengganti default di semua tempat tanpa menyentuh config.yaml, lakukan fork dengan nama yang sama: openspec schema fork spec-driven spec-driven. Salinan proyek Anda kemudian akan menutupi skema bawaan, seperti yang dijelaskan di Lokasi skema.

Mulai dari awal

openspec schema init membuat kerangka skema baru alih-alih menyalin skema yang sudah ada:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

Kerangka yang dihasilkan masih kosong. Artefak hanya berasal dari empat id bawaan, dan templat yang dihasilkan tidak berisi instruksi, sehingga agen mendapat lebih sedikit panduan sampai Anda menulis sendiri. Setelah itu, langkah-langkah fork berlaku tanpa perubahan: validasi skema tersebut, lalu arahkan config.yaml ke skema itu.

Mengedit hasil fork Anda

Hasil fork memiliki dua jenis file yang perlu diedit:

• templates/ mengubah kerangka setiap dokumen. Tambahkan satu bagian ke templat tasks, dan setiap tasks.md baru akan dimulai dengan bagian tersebut. Pertahankan judul # di baris pertama: artefak mewarisinya, sehingga setiap file yang dihasilkan terbuka sebagai dokumen berjudul.
• schema.yaml mengubah alur kerja itu sendiri: artefak mana yang ada, apa yang diperlukan lebih dulu oleh masing-masing artefak, dan instruksi yang diterima agen saat membuatnya.

Misalnya, untuk menghapus dokumen design demi alur yang lebih ringkas:

1. Hapus entri design dari schema.yaml.

2. Hapus design dari daftar requires milik tasks.

3. Validasi:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Lewati langkah 2 dan validasi akan mendeteksinya:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Validasi setelah setiap pengeditan manual. Jika tidak, skema yang rusak akan muncul di tengah-tengah perubahan, ketika alur kerja meminta file yang tidak ada. Seperti config.yaml, perubahan skema sampai ke agen pada eksekusi berikutnya.

Hasil fork adalah snapshot

openspec update menyegarkan skill dan perintah yang terpasang, dan tidak pernah menyentuh openspec/schemas/. Hasil fork Anda tetap berfungsi persis seperti saat Anda tinggalkan, yang juga berarti hasil fork berhenti menerima peningkatan ketika skema bawaan berkembang. Untuk mengambil peningkatan tersebut nanti, lakukan fork lagi pada skema bawaan dengan nama baru dan pindahkan perbedaannya.

Berbagi skema

Berbagi skema berarti menyalin foldernya.

• Dengan tim Anda: commit openspec/schemas/ dan semua orang di repo akan menggunakannya.
• Antar proyek Anda: letakkan folder tersebut di direktori tingkat pengguna dari Lokasi skema.
• Dari komunitas: katalog komunitas mencantumkan skema yang dibagikan. Salin salah satunya ke openspec/schemas/<name> dan skema tersebut akan berfungsi seperti milik Anda sendiri.

Kami sedang mengerjakan registri skema, publik dan privat, agar skema dapat dipasang berdasarkan nama alih-alih disalin secara manual.

Menggunakan OpenSpec dengan Superpowers

Skema superpowers-bridge yang dikelola komunitas menghubungkan artefak OpenSpec ke skill eksekusi Superpowers. Ikuti catatan instalasi dan kompatibilitas bridge tersebut sebelum menyalinnya ke proyek Anda.

Bridge tersebut dirilis di luar OpenSpec. OpenSpec tidak menguji atau mengelola versi integrasi Superpowers-nya.