Şemalar

OpenSpec'in ürettiklerini değiştirin: yapıtlar, sıraları ve şablonları.

Bir şema, bir değişiklik önerisinin ne ürettiğini tanımlar: hangi yapıtları, hangi sırayla, hangi şablonlardan. Örneğin, spec-driven, varsayılan paketlenmiş şema, bu dördünü yaklaşık bu sırayla üretir; her biri öncekinin üzerine inşa edilir:

proposal → specs → design → tasks

Bunların farklı belgeler olmasını istediğinizde bir şemayı fork'layın; ister daha az olması, ister farklı adlar, ister farklı bir yapı olsun.

Şemalar nerede bulunur

OpenSpec bir şemayı sırasıyla üç yerde arar ve bulduğu ilkini kullanır:

1. Projeniz: openspec/schemas/, depo ile birlikte commit edilir, böylece tüm ekibiniz onu alır.
2. Makineniz: macOS ve Linux'ta ~/.local/share/openspec/schemas (veya ayarladıysanız $XDG_DATA_HOME altında), Windows'ta ise %LOCALAPPDATA%\openspec\schemas. Buradaki şemalar, çalıştığınız her projede kullanılabilir.
3. Paket: spec-driven gibi yerleşik olanlar, openspec'in kendi içinde gelir.

Aynı ad birden fazla yerde bulunabilir ve daha belirli konum kazanır. openspec schema which hangi kopyanın kullanıldığını gösterir:

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

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

Bir şemada neler var

Bir şema, düz dosyalardan oluşan bir klasörle tanımlanır: yapıtları bildiren bir schema.yaml ve her biri için bir şablon. İşte yerleşik spec-driven:

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

• schema.yaml: her yapıtı, ürettiği dosyayı, başladığı şablonu, önce ne gerektirdiğini ve ajanın onu oluştururken aldığı talimatı bildirir. Her alanın sözleşmesi schema.yaml içindedir.
• templates/: her yapıt için bir markdown iskeleti; ajan bunları doldurur.

İşte schema.yaml içindeki tasks yapıtının girişi, kısaltılmış:

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

Yerleşik şemalar openspec paketinin içinde gelir, bu yüzden onları asla yerinde düzenlemezsiniz. Fork'layarak kendi kopyanızı elde edersiniz.

Kendi özel şemanızı oluşturma

Kendi şemanızı elde etmenin iki yolu vardır:

1. Mevcut bir şemayı fork'layın ve kopyanızı düzenleyin. Mevcut bir şema istediğinize yakınsa buradan başlayın, çünkü içindeki her şey zaten çalışıyor.
2. Sıfırdan başlayın; hiçbiri uymuyorsa, openspec schema init ile boş bir şema iskeleti oluşturun.

Mevcut bir şemayı fork'lama

1. Başlamak istediğiniz şemayı fork'layın; proje kök dizininden çalıştırın:

   $ 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

   Adı seçmek için ikinci bir argüman iletin (openspec schema fork spec-driven team-flow). Adlar kebab-case'dir.

2. Kopyayı düzenleyin: schema.yaml ve şablonlar. Editing your fork neyi değiştireceğinizi kapsar.

3. Doğrulayın:

   openspec schema validate spec-driven-custom

   Bu, bir değişikliğin ortasındayken bozuk bir şemayı (eksik şablonlar, hatalı YAML, bağımlılık döngüleri) yakalayan tek komuttur.

4. Projenizi openspec/config.yaml içinde ona yönlendirin. Bu adım size aittir, çünkü fork config.yaml'a dokunmaz:

   schema: spec-driven-custom

5. Yeni değişiklik önerileri artık şemanızı izler. Daha önce oluşturulan değişiklikler, başladıkları şemayı korur.

config.yaml'a dokunmadan varsayılanı her yerde değiştirmek için aynı ada fork'layın: openspec schema fork spec-driven spec-driven. Projenizin kopyası daha sonra yerleşik olanı gölgeler; Where schemas live bunu açıklar.

Sıfırdan başlama

openspec schema init bir şemayı kopyalamak yerine yeni bir şema iskeleti oluşturur:

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

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

İskelet çıplaktır. Yapıtlar yalnızca yerleşik dört kimlikten gelir ve üretilen şablonlar hiçbir talimat içermez; bu yüzden kendi talimatlarınızı yazana kadar ajan daha az rehberlik alır. Buradan itibaren fork adımları değişmeden uygulanır: doğrulayın, ardından config.yaml'ı ona yönlendirin.

Fork'unuzu düzenleme

Bir fork'un düzenlenecek iki tür dosyası vardır:

• templates/ her belgenin iskeletini değiştirir. tasks şablonuna bir bölüm ekleyin ve her yeni tasks.md onunla başlar. # başlığını ilk satırda koruyun: yapıt onu miras alır, böylece üretilen her dosya başlıklı bir belge olarak açılır.
• schema.yaml iş akışının kendisini değiştirir: hangi yapıtların var olduğunu, her birinin önce ne gerektirdiğini ve ajanın onu oluştururken aldığı talimatı.

Örneğin, daha yalın bir akış için design belgesini kaldırmak isterseniz:

1. schema.yaml'dan design girişini silin.

2. tasks'in requires listesinden design'ı kaldırın.

3. Doğrulayın:

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

4. adımı atlayın ve doğrulama onu yakalar:

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

Her elle düzenlemeden sonra doğrulayın. Aksi takdirde bozuk bir şema, bir iş akışı orada olmayan bir dosyayı istediğinde, bir değişikliğin ortasında ortaya çıkar. config.yaml gibi, şema düzenlemeleri de bir sonraki çalıştırmada ajana ulaşır.

Bir fork bir anlık görüntüdür

openspec update yüklü becerileri ve komutları yeniler ve openspec/schemas/ klasörüne asla dokunmaz. Fork'unuz, bıraktığınız gibi çalışmaya devam eder; bu aynı zamanda yerleşik şema geliştiğinde iyileştirmeleri almayı bıraktığı anlamına gelir. Bunları daha sonra almak için yerleşik şemayı yeni bir adla tekrar fork'layın ve farklılıkları aktarın.

Şemaları paylaşma

Bir şemayı paylaşmak, klasörünü kopyalamak anlamına gelir.

• Ekibinizle: openspec/schemas/ klasörünü commit edin ve depodaki herkes onu kullanır.
• Projeleriniz arasında: klasörü Where schemas live bölümündeki kullanıcı düzeyi dizinine koyun.
• Topluluktan: community catalog paylaşılan şemaları listeler. Birini openspec/schemas/<name> klasörüne kopyalayın ve kendi şemanız gibi çalışır.

Herkese açık ve özel bir şema kayıt defteri üzerinde çalışıyoruz; böylece şemalar elle kopyalanmak yerine adlarıyla kurulabilecek.

OpenSpec'i Superpowers ile kullanma

Topluluk tarafından bakımı yapılan superpowers-bridge şeması, OpenSpec yapıtlarını Superpowers yürütme becerilerine bağlar. Köprüyü projenize kopyalamadan önce kurulum ve uyumluluk notlarını izleyin.

Köprü OpenSpec dışında yayınlanır. OpenSpec, Superpowers entegrasyonunu test etmez veya sürümlemez.