OpenSpec

OpenSpec Agent Sözleşmesi ​

openspec CLI'nin makine tarafından okunabilir yüzeyleri, src/ ile doğrulanmıştır (capstone denetimi, 2026-06-11). Aşağıdaki her şekil, üreten koddan belgelenmiştir.

1. Genel kurallar ​

  • Her çağrıda tek JSON belgesi. --json modunda stdout tam olarak bir JSON belgesi taşır (2 boşluklu güzel yazdırma). İnsan metni, döner göstergeler ve depolama pankartı stderr'e gider.
  • Depolama pankartı. İnsan modunda, seçilen depolama kökü stderr'e Using OpenSpec root: <id> (<path>) yazdırır. JSON modunda asla yazdırılmaz.
  • Anahtar büyük/küçük harf kullanımı yüzeye bağlıdır (Bilinen tutarsızlıklara bakın): store/doctor/context yüklemeleri snake_case kullanır; iş akışı yüklemeleri (status, instructions, new change, validate, list) camelCase kullanır, ancak gömülü root nesnesi her zaman store_id kullanır.
  • İsteğe bağlı anahtarlar çoğu yüklemelerde atlanır, null olarak bırakılmaz (ör. root.store_id, member.path). Açıkça null kullanan istisnalar her şekil için belirtilir (store doctor git.*, hata yüklemeleri).

2. Tanı zarfı ​

Her makinede okunabilir tanı (StoreDiagnostic) için aynı zarf şekli kullanılır:

json
{
  "severity": "error" | "warning" | "info",
  "code": "snake_case_string",
  "message": "human sentence",
  "target": "dotted.surface (optional)",
  "fix": "one actionable sentence/command (optional)"
}

Tanılar iki konumda görünür: sağlık bulguları için durum dizileri (status: StoreDiagnostic[] üst düzeyde veya girdi başına) ve komut başarısızlığında tek öğeli bir status dizisine dönüştürülen fırlatılan hatalar.

3. Kök seçimi ve RootOutput ​

Tüm kök çözümleyen komutlar (list, show, validate, status, instructions, instructions apply, instructions archive, new change, archive, doctor, context, schemas) bir OpenSpec kökünü aşağıdaki öncelikle çözümler:

  1. --store <id> → kayıtlı mağazanın kökü (source: "store").
  2. Aksi takdirde, openspec/ içeren en yakın üst dizin: planlama şekli → source: "nearest" (store: işaretçisi stderr uyarısıyla yok sayılır); geçerli bir store: işaretçisi olan yalnızca yapılandırma dizini → o mağaza, source: "declared".
  3. En yakın kök yok + genel defaultStore ayarlanmış (openspec config set defaultStore <id>) → o mağaza, source: "global_default"; geçersiz bir kimlik, temel mağaza hatası ve openspec config unset defaultStore adını taşıyan bir fix ile başarısız olur.
  4. En yakın kök yok, varsayılan yok ve kayıtlı mağazalar mevcut → no_root_with_registered_stores hatası.
  5. Kök yok, varsayılan yok, mağaza yok: komutlar mevcut çalışma dizinini source: "implicit" olarak kabul edebilir; ancak doctor, context, list ve toplu validate bunun yerine no_openspec_root ile başarısız olur. list, openspec/project.md ile eski projeler için örtülü geri dönüşü korur.

Başarılı JSON yükleri normalde kökü içerir; schemas --json başarılı olduğunda kasıtlı olarak §4.13'te belgelenen uyumluluk düz dizisi olarak kalır:

json
"root": { "path": "/abs/path", "source": "store" | "declared" | "global_default" | "nearest" | "implicit", "store_id": "id (only when store-selected)" }

Kök-başarısızlık sözleşmesi: JSON modunda bir çözümleme başarısızlığı { ...commandNullShape, "status": [diagnostic] } çıktısını stdout'a yazdırır ve 1 ile çıkar.

4. Komut JSON şekilleri ​

4.1 list --json ​

{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress" } ], "root": RootOutput } — burada değişiklik başına status'un bir dize sabiti olduğuna dikkat edin. --specs: { "specs": [ { "id", "requirementCount" } ], "root" }.

4.2 show <item> --json ​

Değişiklik: { "id", "title", "deltaCount", "deltas": [...], "root" }. Spesifikasyon: { "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }.

4.3 validate --json ​

{ "items": [ { "id", "type": "change"|"spec", "valid", "issues": [ { "level", "path", "message", "line"?, "column"? } ], "durationMs" } ], "summary": { "totals": {items,passed,failed}, "byType": {...} }, "version": "1.0", "root" }. Herhangi bir öğe başarısız olduğunda 1 ile çıkar.

4.4 status --json ​

{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isPlanningComplete", "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }. isPlanningComplete her atlanmamış planlama kalıntısının var olduğu anlamına gelir; atlanan kalıntılar oluşturulmadan karşılanmış sayılır. Bu, gerçekleme görevlerinin tamamlandığı anlamına gelmez. isComplete aynı değere sahip uyumluluk takma adı olarak korunur. Her kalıntının requires alanı, doğrudan bağımlı kimliklerini içerir (her durum için mevcuttur, böylece kalıntı done olsa bile geçişli gerekli küme hesaplanabilir); missingDeps yalnızca blocked olduğunda görünür. artifacts dizisi bağımlılık sırasındadır; aynı anda hazır hale gelen kalıntılar arasındaki eşitliği şemanın artifacts: bildirim sırası bozar (asla alfabetik değildir), bu nedenle ilk ready girdisi yazılacak bir sonraki kalıntıdır; missingDeps aynı sırayı kullanır. "skipped", .openspec.yaml dosyasında skip_specs: true bildiren bir değişiklikte generates yolu specs/ altında olan bir kalıntıyı işaretler; bağımlılıkları karşılar ancak oluşturulmamalıdır. Aktif değişiklik yok: { "changes": [], "message", "root" }, çıkış 0.

--all (toplu, --change ile karşılıklı dışlayan — bunları birleştirmek { "changes": [], "root": null, "status": [d] } boş-şekli ile hata verir): { "changes": [ <değişiklik başına durum nesnesi, değişiklik başına kök yok>, ... ], "root" }, değişiklik adına göre sıralanır. Yüklenemeyen bir değişiklik yerine { "changeName", "status": [d] } katkıda bulunur; tarama devam eder, tam zarf korunur ve hem metin hem JSON modunda 1 ile çıkar. Geçersiz bir --schema, hiçbir değişiklik olmasa bile boş-şekil ile tüm çağrıyı başarısız kılar.

4.5 instructions <artifact> --json ​

{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "skipped"?, "warning"?, "template", "dependencies": [{id,done,path,description,skipped?}], "unlocks", "root" }. unlocks bu kalıntının hazır hale getirdiği kalıntıları, şemanın bildirim sırasına göre (status'un önerdiği aynı sıra) listeler. "skipped": true ("warning" ile birlikte), değişiklik skip_specs: true bildirdiğinde ve bu kalıntı atlandığında görünür — dosyalarını oluşturmayın. skipped: true olan bir bağımlılık girdisi dosyasız olarak karşılanır — yollarına okumaya çalışmayın.

ReferenceIndexEntry: { "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] } — çözümlenmiş girdiler root/specs/fetch taşır; çözümlenmemiş olanlar store_id + uyarı durumu taşır. Dizin 50KB ile sınırlıdır (reference_index_truncated).

4.6 instructions apply --json ​

{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "missingPrerequisites"?, "warnings"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }. missingArtifacts apply'nin bloke olduğu şeyi (şemanın apply.requires); missingPrerequisites ise apply çalıştırılmadan önce inşa edilmesi gereken her şeyi, inşa sırasına göre - bu gereksinimlerin geçişli kapanışı, bu nedenle daha uzun liste olabilir. warnings değişikliğin kendisiyle ilgili engelleyici olmayan sorunları listeler - bugün, delta spesifikasyonu olmadan ve skip_specs: true olmadan uygulanmaya hazır olan bir değişiklik openspec validate tarafından reddedilir. Her iki isteğe bağlı kök alanı (context, operationGuidance) her çağrıda seçilen kökten okunur. context ilgili proje gerçekleri, gelenekleri ve kısıtlamaları uygulanması gereken zorunlu bir istem düzeyi girdidir; operationGuidance ise yalnızca uygulanabilir ve yerleşik iş akışıyla uyumlu olduğunda takip edilen tavsiye niteliğinde bir girdidir. Her ikisi de durum, görevler, ilerleme, bağlam dosyaları ve yerleşik talimattan ayrı kalır.

4.7 instructions archive --json ​

{ "changeName", "context"?, "operationGuidance"?, "root" }. Çözümlenmiş depo/mağaza kökünde geçerli bir --change gerektirir ve apply ile aynı zorunlu-bağlam/tavsiye-rehberlik anlamsallarını kullanır. Bu salt okunur bir çalışma zamanı girdi yüzeyidir: statik arşiv iş akışını döndürmez, delta spesifikasyonlarını incelemez veya birleştirmez, ana spesifikasyonları yazmaz veya değişikliği taşımaz.

4.8 new change <name> --json ​

Başarı: { "change": { "id", "path", "metadataPath", "schema" }, "root" }. Başarısızlık: { "change": null, "status": [d] }, çıkış 1.

4.9 archive <name> --json ​

Başarı: { "archive": { "change", "archivedAs": "YYYY-MM-DD-ad", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }. Başarısızlık: { "archive": null, "root"?, "status": [d] }, çıkış 1. specsUpdated, yalnızca en az bir spesifikasyon dosyası yazıldığında veya emekli edildiğinde doğrudur (değişikliğin kaldırdığı son gereksinimin bulunduğu yetenek için spesifikasyon silinir, bu da değişikliğin .openspec.yaml dosyasında retire_capabilities: true gerektirir; her emeklilik warnings içinde adlandırılır, yalnızca spesifikasyon çağıranın ödeme kasasında yaşıyorsa yapıştırılabilir bir Git kurtarma komutu ile birlikte); zaten senkronize edilmiş bir değişiklik, tüm toplamlar sıfır olarak ve atlamalar warnings içinde listelenerek arşivlenir. JSON modu kesinlikle etkileşimsizdir: her istem noktası bir archive_* koduna dönüşür.

4.10 doctor --json ​

{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "drift"?: {ahead,behind}, "status": [] } | null, "references": [...], "status": [] }. drift (yalnızca bir üst akış takip referansına sahip git destekli mağaza ödemesi için mevcuttur), canlı uzak depoya göre değil, son getirilen üst akışa karşı ileri/geri sayımlardır. Herhangi bir önem derecesindeki sağlık bulguları 0 ile çıkar. Başarısızlık yükü: { "root": null, "store": null, "references": [], "status": [d] }, çıkış 1.

4.11 context --json ​

{ "root": { "path", "source", "store_id"?, "role": "openspec_root" }, "members": [ { "role": "referenced_store", "id", "path"?, "remote"?, "fetch"?, "status": [] } ], "status": [] }. KULLANILABILIR = yol mevcut VE durum boş. --code-workspace <path> {folders:[{name,path}]} yazar (yalnızca kullanılabilir referanslı mağazalar, ref: önekleri); JSON modunda yazma işlemi yazdırmadan önce gerçekleşir, böylece stdout yazma hatasında bile tam olarak bir belge içerir. Başarısızlık: { "root": null, "members": [], "status": [d] }, çıkış 1.

4.12 store ... --json ​

setup/register: { "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }. unregister/remove: { "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }. list: { "stores": [{id, root}], "status": [] }. doctor: { "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] } (null = bilinmiyor/araştırılmadı). Sağlık bulguları 0 ile çıkar; başarısızlıklar eşleşen boş-şekil ile 1 çıkış kodu verir. İstem iptali 130 ile çıkar.

4.13 schemas --json / templates --json ​

schemas: başarılı sonuç [ {name, description, artifacts, source} ] çıplak dizisi olarak kalır; kanonik kök seçim önceliğini çözümler ve --store <id> kabul eder. Kök seçim başarısızlığı: { "schemas": [], "root": null, "status": [d] }, çıkış 1. templates: anahtarlı nesne { "<artifactId>": {path, source} }, hâlâ mevcut çalışma dizini tabanlıdır, kök/durum anahtarları yoktur.

5. Çıkış-kodu sözleşmesi ​

DurumÇıkışStdout
Başarılı, sağlık bulguları dahil (doctor/context/store doctor)0yük
--json modunda komut hatası1status: [d] ve komutun null-shape'ini içeren bir JSON belgesi
Başarısız öğelerle validate1tam rapor
İstem iptali (store grubu, insan modu)130yalnızca stderr

6. Tanı kodu kataloğu ​

Çözüm ​

no_openspec_root, no_root_with_registered_stores, no_registered_stores, unknown_store, store_identity_mismatch, unhealthy_store_root, store_path_not_supported, invalid_store_pointer, initiative_option_removed, areas_option_removed; geçişli: invalid_store_id, invalid_store_registry, invalid_store_metadata.

OpenSpec-kök sağlığı (hata, düzeltme yok) ​

openspec_store_root_missing, openspec_store_root_not_directory, openspec_root_missing, openspec_root_not_directory, openspec_config_missing, openspec_config_not_file, openspec_specs_not_directory, openspec_changes_not_directory, openspec_archive_not_directory. Mağazalar beta sürecinde, openspec/specs/, openspec/changes/ ve openspec/changes/archive/ sağlıklı bir kökte eksik olabilir; bunlar yalnızca mevcut olduklarında ancak bir dizin olmadıklarında sağlık hatası oluşturur.

Mağaza kaydı/kimlik/durumu ​

invalid_store_id, invalid_store_registry, invalid_store_metadata, store_registry_busy, store_not_found, no_store_registry, store_registry_changed, store_metadata_missing, store_metadata_id_mismatch, store_metadata_invalid, store_id_conflict, store_path_conflict, store_already_registered (bilgi).

Mağaza kurulumu/kaydetme/kaldırma ​

store_setup_id_required, store_setup_path_required, store_setup_path_not_directory, store_setup_inside_git_repo, store_setup_non_empty_directory, store_setup_cancelled, store_path_required, store_path_missing, store_path_not_directory, store_root_pointer_declared, store_register_root_unhealthy, store_register_identity_confirmation_required, store_register_cancelled, store_remote_empty, store_remote_requires_hand_edit, store_remove_confirmation_required, store_remove_cancelled, store_remove_path_not_directory, store_remove_metadata_missing, store_root_missing (kaldırmada uyarı, doctor'da hata), store_root_not_directory.

Mağaza git ​

store_git_init_failed, store_git_identity_missing, store_git_commit_failed, store_git_no_commits (uyarı), store_clone_fragile_directories (uyarı), store_remote_divergence (bilgi, doctor), store_checkout_drift (bilgi, doctor).

Referanslar (uyarı) ​

reference_invalid_id, reference_registry_unreadable, reference_unresolved, reference_root_unhealthy, reference_index_truncated.

İlişkiler (uyarı; doctor; context yalnızca kayıt defteri olanı tutar) ​

relationship_registry_unreadable, root_pointer_ignored, root_pointer_invalid, pointer_declarations_inert.

Arşiv (JSON modu) ​

archive_change_name_required, archive_change_not_found, archive_change_symlink, archive_validation_failed, archive_confirmation_required, archive_tasks_incomplete, archive_spec_update_failed, archive_spec_validation_failed, archive_target_exists, archive_error.

Bağlam yazmaları ​

context_file_exists, context_output_dir_missing.

Yedekler ​

doctor_failed, context_failed, store_error, change_error, archive_error.

Bilinen tutarsızlıklar ​

Capstone denetimi tarafından kaydedilmiştir; yayınlanan anahtar yeniden adlandırmaları, bu sürüm sonrasına ertelenmiş ürün kararlarıdır:

  1. --json modunda, bazı hata yolları yalnızca stderr çıktısı verdi ve hiçbir JSON belgesi içermedi. Capstone gauntlet turunda düzeltildi: show/validate bilinmeyen ve belirsiz öğeler {status:[{code: unknown_item | ambiguous_item, ...}]} yayınlar; status/instructions/list/show/validate komutlarında atılan hatalar, JSON-farkında hata yardımcısı üzerinden yönlendirilir (komutun null-shape'i + status); store <bilinmeyen alt komut> --json {status:[{code: unknown_store_subcommand}]} yayınlar; list çözümleme hatalarında {changes|specs: [], root: null} null şeklini taşır.
  2. store_root_missing iki önem derecesiyle yayınlanır (kaldırmada uyarı, store doctor'da hata) — bağlama bağlı, yukarıda belgelenmiştir.
  3. snake_case (store ailesi) vs camelCase (iş akışı ailesi) anahtar yazımı; root.store_id her yerde snake_case'dir.
  4. src'te dört paralel zarf türü bildirimi mevcuttur; arşiv tanıları asla target taşımaz.
  5. list --json her değişiklik için status anahtarını bir dize numaralandırması olarak yeniden kullanır.
  6. Yalnızca validate çıktısı bir version alanı taşır.
  7. templates kök seçimini yok sayar (cwd tabanlı, --store yok).
  8. Kullanımdan kaldırılmış isim biçimleri (change/spec alt komutları) root/status olmadan zarfı çıkarılmamış yükler yayınlar.