schema.yaml

Każde pole definicji schematu, do odczytu lub zapisu jednego elementu.

schema.yaml wylicza plany projektowe tworzone przez przepływ pracy (workflow). Definiuje również ich kolejność oraz przekazanie do etapu implementacji.

Lokalizacja

Schemat projektu znajduje się w katalogu openspec/schemas/<name>/:

openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

OpenSpec sprawdza trzy miejsca pod kątem istnienia tego katalogu. Zwycięża pierwsze dopasowanie.

Kopiowanie	Katalog
1. Projekt	<project>/openspec/schemas/<name>/
2. Użytkownik, macOS i Linux	~/.local/share/openspec/schemas/<name>/
2. Użytkownik, Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. Pakiet	Schematy zainstalowane wraz z CLI

Jeśli zmienna XDG_DATA_HOME jest ustawiona, katalog użytkownika przenosi się na $XDG_DATA_HOME/openspec/schemas/<name>/ na każdej platformie.

Nazwa katalogu jest kluczem wyszukiwania używanym przez --schema, config.yaml oraz .openspec.yaml. Jeśli pole name różni się od nazwy katalogu, OpenSpec nadal używa nazwy katalogu do wyszukiwania.

openspec schema which <name> wyświetla aktywny katalog oraz wszystkie ukryte kopie o niższym priorytecie.

Pola najwyższego poziomu

Pole	Umowa
name	Wymagane. Niepusty ciąg znaków przechowywany jako nazwa schematu. Wyszukiwanie nadal używa nazwy katalogu.
version	Wymagane. Dodatnia liczba całkowita przechowywana jako wersja schematu. Wartość nie zmienia zachowania OpenSpec.
description	Opcjonalny ciąg znaków drukowany przez openspec schemas. Brak wartości oznacza brak opisu dla schematu.
artifacts	Wymagane. Niepusta lista wpisów artefaktów.
apply	Opcjonalne ustawienia apply. Brak bloku powoduje użycie domyślnych ustawień apply.

Pola artefaktu

Każdy wpis pod artifacts definiuje jeden planowany plik lub zestaw plików.

Pole	Umowa
id	Wymagane. Unikalny, niepusty ciąg znaków używany w zależnościach, regułach projektu, poleceniach i ustawieniach apply.
generates	Wymagane. Ścieżka względna lub glob wskazujący agentowi, gdzie zapisać artefakt w folderze zmiany.
description	Wymagane. Ciąg znaków etykietujący artefakt w instrukcjach wysyłanych do agenta.
template	Wymagane. Ścieżka względna do formatu artefaktu w folderze templates/ schematu.
instruction	Opcjonalne wytyczne mówiące agentowi, jaką treść wyprodukować.
requires	Lista identyfikatorów artefaktów, które muszą być zakończone wcześniej. Domyślnie: [].

generates

Ścieżka zaczyna się od folderu zmiany. Dla zmiany o nazwie add-auth:

generates: proposal.md

Artefakt trafi tutaj:

openspec/changes/add-auth/proposal.md

Glob może pasować do wielu plików:

generates: specs/**/*.md

Pasuje to do plików Markdown poniżej openspec/changes/add-auth/specs/.

OpenSpec rozpoznaje te formy globów w generates:

• Znaki wieloznaczne i klasy znaków: wartości zawierające *, ? lub [, takie jak specs/**/*.md i review-[ab].md.
• Rozszerzenia nawiasów klamrowych: alternatywy takie jak review-{api,ui}.md i zakresy takie jak file-{1..3}.md.
• Extglobs: wzorce takie jak @(proposal|design).md, +(proposal|design).md i !(proposal|design).md.

Literale nazwy plików: sam początek od ! nie czyni tego globem. Użyj generates: '!review.md', aby nadać tę nazwę plikowi. Zwykłe nawiasy okrągłe takie jak (proposal|design).md oraz jednoelementowe nawiasy klamrowe takie jak review-{api}.md pozostają literałami.

OpenSpec odrzuca ścieżki absolutne, ścieżki zawierające segment .. oraz globy, które zagnieżdżają nawiasy klamrowe lub okrągłe głębiej niż na 16 poziomach, takich jak {a,{b,{c,...}}}. Rzeczywiste wzorce wymagają jednego lub dwóch poziomów. Odrzuca również globy, których nawiasy klamrowe rozszerzają się do więcej niż 1024 wzorców, takich jak powtórzenie {a,b} jedenaście razy lub zakres taki jak file-{1..5000}.md. Błąd mówi Artifact output pattern expands to more than 1024 patterns. Rzeczywiste wzorce rozszerzają się do garstki.

Ukończenie

OpenSpec sprawdza, czy wynik istnieje. Nie odczytuje pliku, aby zdecydować, czy artefakt jest kompletny.

Wartość generates	Kompletny, gdy
proposal.md	Istnieje ten plik.
specs/**/*.md	Glob pasuje co najmniej do jednego pliku.

template

Ścieżka zaczyna się od folderu templates/ schematu. W schemacie review-first:

template: proposal.md

OpenSpec odczytuje ten plik:

openspec/schemas/review-first/templates/proposal.md

OpenSpec przekazuje zawartość szablonu do agenta jako format wyjściowy. Nie kopiuje szablonu do folderu zmiany.

OpenSpec odrzuca ścieżki absolutne i ścieżki zawierające segment ...

requires

• Zależności: każdy ID w requires musi wskazywać inny artefakt w tym samym schemacie.
• Stan gotowości: artefakt staje się gotowy po ukończeniu wszystkich jego zależności.
• Nieprawidłowe grafy: brakujące ID, zduplikowane ID i cykle zależności kończą się błędem walidacji.
• Remisy: gdy kilka artefaktów jest gotowych, ich kolejność w artifacts decyduje, który z nich OpenSpec zwróci jako pierwszy.

Pola apply

apply definiuje, co musi istnieć przed rozpoczęciem implementacji.

Pole	Umowa
requires	Wymagane. Niepusta lista artefaktów, które muszą istnieć, zanim instrukcje apply staną się gotowe.
tracks	Opcjonalna ścieżka względna lub glob dla plików zadań Markdown w folderze zmiany. Domyślnie: null.
instruction	Opcjonalne wytyczne wysyłane do agenta, gdy apply jest gotowe. Domyślnie OpenSpec używa wbudowanych wytycznych.

requires artefaktu kontroluje kolejność planowania. apply.requires kontroluje moment, w którym instrukcje apply stają się gotowe.

tracks

Ścieżka zaczyna się od folderu zmiany. Dla zmiany o nazwie add-auth, tracks: tasks.md odczytuje:

openspec/changes/add-auth/tasks.md

Glob taki jak tracks: "**/tasks.md" odczytuje każdy pasujący plik, taki jak backend/tasks.md i frontend/tasks.md. OpenSpec łączy ich zadania i postęp. Użyj tej samej wartości dla pola generates artefaktu, aby status i lista śledziły te same pliki. Ograniczenia nawiasów klamrowych z generates (16 poziomów głębokości, 1024 rozszerzone wzorce) obowiązują również tutaj.

Apply pozostaje zablokowane, jeśli żaden plik nie pasuje lub dopasowane pliki nie zawierają żadnego pola wyboru z tekstem zadania. OpenSpec liczy te formy pól wyboru:

- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

Działa dowolny znacznik listy Markdown: -, *, + lub liczba do dziewięciu cyfr followed by . lub ). Dozwolone są spacje wiodące. Sekcja tasks.md strony spec-driven definiuje ściślejszy format produkowany przez domyślny schemat.

Śledzone pliki napędzają stan apply:

• blocked: żaden plik nie pasuje lub żaden czytelny plik nie ma pola wyboru z tekstem zadania.
• ready: co najmniej jedno zadanie oczekuje na wykonanie lub nie udało się odczytać dopasowanego pliku, podczas gdy inny dostarcza zadania.
• all_done: każde śledzone zadanie jest odhaczone i każdy dopasowany plik został odczytany.

Jeśli nie można odczytać dopasowanego pliku, apply utrzymuje zadania i postęp z czytelnych plików, ale nie oznacza zmiany jako all_done. Wyjście JSON apply identyfikuje każdy niedostępny plik i przyczynę.

OpenSpec odrzuca ścieżki absolutne i ścieżki zawierające segment ...

Domyślne apply

Zachowanie	Domyślne
Wymagane artefakty	Każdy artefakt w schemacie
Śledzenie postępu	Brak śledzonego pliku
Wytyczne agenta	Wbudowane wytyczne apply

Pełny przykład

name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

Walidacja

openspec schema validate <name> sprawdza:

• Typy pól i wymagane pola
• Ścieżki względne
• ID artefaktów, zależności i cykle
• ID apply.requires: każde musi być artefaktem w schemacie
• Pliki szablonów

Schemat z nieznanym ID apply.requires nie ładuje się, więc każda komenda go używająca zgłasza błąd.

Walidacja ostrzega (bez powodowania błędu), gdy apply.tracks nie jest dokładnie równe wartości generates jakiegokolwiek artefaktu. OpenSpec znajduje śledzony artefakt porównując te dwa ciągi znaków, więc cokolwiek innego pozostawia go niezdolnym do określenia, do którego artefaktu należy postęp pliku. Dotyczy to zarówno literówek takich jak task.md, jak i tracks: tasks/main.md przeciwko generates: tasks/*.md, gdzie glob faktycznie produkuje plik, ale ciągi znaków nadal się różnią. Apply nadal odczytuje plik w obu przypadkach, ale openspec list i openspec status liczą tasks.md zamiast tego.

Walidacja nie wychwytuje tych błędów:

Błąd	Co się dzieje
Pole jest pisane błędnie, np. instrution	OpenSpec je ignoruje. Walidacja nie zgłasza literówki.
name różni się od katalogu schematu	Walidacja przechodzi. OpenSpec nadal używa nazwy katalogu do wyszukiwania.