Beceriler
Her OpenSpec becerisi: argümanlar, ne oluşturur ve nasıl yanıt verir.
Beceriler iki set halinde gelir:
- Çekirdek (Core): varsayılan olarak kurulur, ana planlama döngüsüdür.
- İsteğe Bağlı (Optional): yalnızca Profiller üzerinden eklediğinizde kurulur.
Her beceri, OpenSpec'i kullanan bir projeyi bekler. Herhangi bir şey yazan ilk adımından önce beceri, çözümlenmiş bir kök (resolved root) olup olmadığını kontrol eder. Kök yoksa ne olacağı, becerinin nasıl çağrıldığına bağlıdır:
- Otomatik seçimi: OpenSpec'i siz adlandırmadan, ajanınız kendi inisiyatifiyle beceriyi seçti. OpenSpec'i bırakır ve isteğinize OpenSpec kuruluymuş gibi normal şekilde yanıt verir.
- Açık OpenSpec isteği: OpenSpec'i, beceriyi veya komutunu adlandırdınız. Yazmadan önce durur ve nasıl devam edileceğini sorar: burada
openspec initçalıştırın,--store <id>ile bir store hedefleyin veya OpenSpec olmadan devam edin. Cevabınızı bekler.
Komutlar her zaman ikinci durumdadır. openspec/config.yaml dosyasında bu makinede çözümlenemeyen bir store adı geçen bir proje (kayıtlı olmayan veya hatalı store: satırı) başlatılmamış olarak değerlendirilmez: beceri durur ve store hatasını çözüm önerisiyle birlikte gösterir. Her iki durumda da hiçbir beceri kendi başına bir openspec/ dizini oluşturmaz. Aşağıdaki maddeler, kök yerleşik olduğunda her becerinin ne yaptığını açıklar.
| Beceri | Görev | Tür |
|---|---|---|
| openspec-explore | Bir fikir değişim önerisi (change proposal) olmaktan önce üzerinde düşünmek | Çekirdek |
| openspec-propose | Tüm planlama artefaktlarını tek adımda içeren bir değişim önerisi oluşturmak | Çekirdek |
| openspec-apply-change | Bir değişim önerisinin görevlerini uygulamak | Çekirdek |
| openspec-update-change | Bir değişim önerisinin planını revize etmek | Çekirdek |
| openspec-sync-specs | Bir değişim önerisinin spesifikasyon güncellemelerini specs/ dizinine birleştirmek | Çekirdek |
| openspec-archive-change | Tamamlanmış bir değişim önerisini arşive taşımak | Çekirdek |
| openspec-new-change | Bir değişim önerisini boş bir iskelet olarak başlatmak | İsteğe Bağlı |
| openspec-continue-change | Sıradaki planlama artefaktını seferberinde oluşturmak | İsteğe Bağlı |
| openspec-ff-change | Uygulamanın gerektirdiği her artefaktı içeren bir değişim önerisini tek geçişte oluşturmak | İsteğe Bağlı |
| openspec-verify-change | Uygulamanın plana uygunluğunu kontrol etmek | İsteğe Bağlı |
| openspec-bulk-archive-change | Birden fazla değişim önerisini birden arşivlemek | İsteğe Bağlı |
| openspec-onboard | Bir gerçek değişim önerisini baştan sona yaparak iş akışını öğrenmek | İsteğe Bağlı |
Aşağıdaki her madde, bir sonraki adımı sahiplenen beceriyi adlandırır. Profeliniz bu beceriyi hariç tutarsa, kurulu dosyalar onu asla adlandırmaz: devir, eşdeğer openspec komutuna veya size düz bir isteğe dönüşür; yalnızca eksik bir beceriye işaret etmek için var olan satır hiç yazılmaz. Dolayısıyla sahip olduğunuz beceriler, her zaman sahip olduğunuz becerilere devir yapar. Hangi seti aldığınız Profiller ile belirlenir.
openspec-explore
Bir fikir, değişiklik önerisi haline gelmeden önce üzerinde düşün.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir konu: bir fikir, bir sorun, bir karşılaştırma veya bağlamında keşfedilecek mevcut bir değişiklik önerisinin adı. Hiçbir şey verilmezse keşif moduna girer. |
| Oluşturur | Varsayılan olarak hiçbir şey. Yalnızca okur ve inceler. İstek üzerine içgörüleri yakalar: openspec/changes/<name>/ altında yeni bir değişiklik önerisi veya mevcut bir önerinin proposal, design, specs veya tasks belgelerinde güncellemeler. Asla kod değil. |
| Yanıt | Zorunlu çıktısı olmayan açık bir konuşma. Düşünce netleştiğinde sorunu, yaklaşımı, açık soruları ve sonraki adımları özetler ve bunları yakalamayı önerir. Karar sizindir. Uygulama burada asla başlamaz. |
openspec-propose
Bir değişiklik önerisi oluşturun ve tüm planlama yapıtlarını tek adımda üretin.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir kebab-case ad (add-dark-mode) veya düz bir açıklama. İkisini de vermezseniz sorar. |
| Oluşturur | Şemanın tanımladığı her yapıtı bağımlılık sırasına göre içeren openspec/changes/<name>/ (spec odaklı: proposal, spec deltaları, design, tasks). Asla kod değil. |
| Yanıt | Oluşturulan yapıtlar, incelemeye hazır ve sonraki adım. Orada durur; uygulama openspec-apply-change komutunu bekler. |
openspec-apply-change
Bir değişiklik önerisinin görevlerini uygulayın, liste tamamlanana veya engellenene kadar üzerinde çalışın.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir değişiklik önerisi adı (add-auth), isteğe bağlı. Hedef belirsizse aktif değişiklik önerilerini listeler ve seçmenizi ister. |
| Oluşturur | Kod: her görevin gerektirdiği asgari değişiklikler, proje dosyalarınızda. Değişiklik önerisinde, sourcePath ve tek tabanlı line ile tanımlanan izlenen dosyada tamamlanan her görevi işaretler (- [ ] → - [x]). Bir şema görevleri birden fazla dosyada izleyebilir. |
| Yanıt | Görev başına ilerleme, ardından genel bir sayım (N/M görev tamamlandı). Hepsi tamamlandı: openspec-archive-change önerir. Eksik yapıtlar nedeniyle engellendi: openspec-continue-change komutuna veya bu beceri kurulu değilse openspec status ve openspec instructions komutlarına işaret eder (çekirdek profil bunu dışarıda bırakır). Belirsiz görevler veya hatalar: duraklar ve sorar. |
openspec-update-change
Bir değişiklik önerisinin mevcut planlama yapıtlarını revize edin ve birbirleriyle tutarlı tutun.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir değişiklik önerisi adı, isteğe bağlı, artı istediğiniz revizyon. Revizyon belirtilmezse bir tutarlılık incelemesi çalıştırır: yapıtlar çelişkiler, boşluklar ve tekrarlar açısından birbirine karşı kontrol edilir. |
| Oluşturur | Zaten var olan yapıt dosyalarını düzenler. Tek istisna: specs/**/*.md gibi bir glob olarak yazılmış ve en az bir dosyası olan bir yapıt için, yolu onayladıktan sonra eksik bir eşlikçi dosya ekleyebilir. Henüz dosyası olmayan bir yapıt openspec-continue-change görevidir. Bu beceri yoksa (çekirdek profil onu dışarıda bırakır), bunun yerine openspec status ve openspec instructions komutlarına işaret eder. Asla kod değil. |
| Yanıt | Her önerilen revizyonu gösterir ve yalnızca siz onayladıktan sonra yazar, her seferinde bir yapıt. Neyin revize edildiği ve sonraki adımla biter; uygulama openspec-apply-change komutunu bekler. |
openspec-sync-specs
Bir değişiklik önerisinin spec güncellemelerini arşivlemeden specs/ klasörüne birleştirin.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir değişiklik önerisi adı, isteğe bağlı. Ayrıca delta spec'lerinin bir alt kümesini de adlandırabilirsiniz ve yalnızca onlar senkronize edilir. |
| Oluşturur | Her delta spec için openspec/specs/<capability-path>/spec.md dosyasını düzenler veya oluşturur, eklenen, değiştirilen, kaldırılan ve yeniden adlandırılan gereksinimleri ana spec'e birleştirir. Asla kod değil. |
| Yanıt | Güncellenen spec'ler doğrulandıktan sonra, yetenek başına eklenen, değiştirilen, kaldırılan veya yeniden adlandırılan gereksinimlerin bir özeti. Değişiklik önerisi aktif kalır; arşivleme openspec-archive-change komutunu bekler. |
openspec-archive-change
Tamamlanmış bir değişiklik önerisini arşive taşıyın.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir değişiklik önerisi adı, isteğe bağlı. |
| Oluşturur | Değişiklik önerisi klasörünü openspec/changes/archive/YYYY-MM-DD-<name>/ konumuna taşır (ad zaten bir tarihle başlıyorsa tarih eklenmez). Onayınızla önce bekleyen delta spec'leri senkronize eder. openspec-sync-specs kuruluysa bu iş akışını çalıştırır. Aksi takdirde, delta spec'lerini ana spec'lere kendisi birleştirir. Asla kod değil. |
| Yanıt | Eksik yapıtlar veya görevlerle arşivlemeden önce uyarır ve sorar, delta spec'leri mevcutsa senkronize edilip edilmeyeceğini sorar. Bir özetle biter: ad, şema, arşiv konumu, spec senkronizasyon durumu ve varsa uyarılar. |
openspec-new-change
Bir değişiklik önerisini boş bir iskelet olarak başlatın.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir kebab-case ad (add-user-auth) veya düz bir açıklama, artı yalnızca varsayılan olmayan bir iş akışı için bir şema adı. İkisini de vermezseniz ne inşa etmek istediğinizi sorar. |
| Oluşturur | openspec/changes/<name>/ boş bir iskelet olarak: henüz yapıt yok, asla kod değil. |
| Yanıt | İskeletin adı ve konumu, iş akışının yapıt dizisi, durum (0/N tamamlandı) ve ilk yapıtın şablonu. Yapıtların taslağını çizmek openspec-continue-change komutunu bekler. |
openspec-continue-change
Bir değişiklik önerisindeki bir sonraki planlama yapıtını oluşturun, her seferinde bir tane.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir değişiklik önerisi adı, isteğe bağlı. Hâlâ belirsizse en son değiştirilenler arasından seçmenizi ister. |
| Oluşturur | Şemanın dizisindeki hazır olan tek sonraki yapıt, değişiklik önerisi klasörüne yazılır. Her çalıştırmada bir yapıt, asla kod değil. |
| Yanıt | Oluşturulan yapıt, ilerleme (N / M tamamlandı) ve bunun açtığı yapıtlar. Planlama tamamlandığında bunu söyler; uygulama openspec-apply-change komutuna geçer. |
openspec-ff-change
Bir değişiklik önerisi ve uygulamanın ihtiyaç duyduğu tüm planlama yapıtlarını tek geçişte oluşturun.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir kebab-case ad veya düz bir açıklama. İkisini de vermezseniz sorar. Adlandırılmış değişiklik önerisi zaten mevcutsa onun yerine devam etmeyi önerir. |
| Oluşturur | openspec/changes/<name>/ ve uygulamanın gerektirdiği her planlama yapıtı, bağımlılık sırasına göre (spec odaklı: proposal, specs, design, tasks), yalnızca atlanmış veya koşullu olarak işaretlenmiş yapıtlar hariç. Asla kod değil. |
| Yanıt | Değişiklik önerisinin adı ve konumu, oluşturulan her yapıt ve atlanan koşullu yapıt ve nedeni. Orada durur; uygulama openspec-apply-change komutunu bekler. |
openspec-verify-change
Uygulamanın değişiklik önerisinin yapıtlarıyla eşleştiğini kontrol edin.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Bir değişiklik önerisi adı, isteğe bağlı. Belirsiz olduğunda sorar ve tasks yapıtı olan değişiklik önerilerini listeler. |
| Oluşturur | Hiçbir şey. Değişiklik önerisinin yapıtlarını ve kod tabanını okur. Doğrulama yalnızca rapor amaçlıdır. |
| Yanıt | Bir rapor: Eksiksizlik, Doğruluk ve Tutarlılık için bir puan kartı, ardından önerilerle birlikte CRITICAL, WARNING ve SUGGESTION sorunları ve son bir arşive hazır olma değerlendirmesi. Hiçbir şeyi değiştirmez ve arşivlemez. |
openspec-bulk-archive-change
Birden fazla değişiklik önerisini aynı anda arşivleyin.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Yok. Aktif değişiklik önerilerini listeler ve herhangi bir sayıda seçmenizi ister, tümü için bir seçenekle. Hiçbiri aktif değilse bunu söyler ve durur. |
| Oluşturur | Arşivlenen her değişiklik önerisi için openspec/changes/archive/YYYY-MM-DD-<name>/ (zaten tarihli adlar öneklerini korur). Her birinin spec deltaları önce openspec-sync-specs ile senkronize edilir. Asla kod değil. |
| Yanıt | Her değişiklik önerisi için bir durum tablosu ve tüm grup için tek bir onay, ardından arşivlenen, atlanan ve başarısız olanların bir özeti, artı spec senkronizasyon sonuçları. İki değişiklik önerisi aynı spec'e dokunduğunda kod tabanını kontrol eder ve uygulanan deltaları en eskiden başlayarak senkronize eder. |
openspec-onboard
Gerçek bir değişiklik önerisini baştan sona yaparak iş akışını öğrenin.
| Sözleşme | Açıklama |
|---|---|
| Argümanlar | Yok. Kod tabanınızı küçük başlangıç görevleri için tarar ve birini seçmenizi veya kendi görevinizi tanımlamanızı ister. |
| Oluşturur | Seçilen görev için gerçek bir değişiklik önerisi, her seferinde bir yapıt, ardından uygulamayı onayladığınızda gerçek kod. Sonunda değişiklik önerisini arşivler. |
| Yanıt | Girdiğiniz duraklamalarla tam döngünün anlatımlı bir yürüyüşü: keşfet, oluştur, her yapıtı inşa et, uygula, arşivle. Bir özet ve openspec-propose komutuna bir işaretçi ile biter. Yaklaşık 15 ila 20 dakika sürer. |