Schematy

Zmiana tego, co produkuje OpenSpec: artefakty, ich kolejność i szablony.

Schemat definiuje, co proponuje zmiana: które artefakty, w jakiej kolejności i z jakich szablonów. Na przykład domyślny schemat wbudowany, spec-driven, generuje cztery artefakty w przybliżonej kolejności, każdy budując na poprzednim:

propozycja → specyfikacje → projekt → zadania

Rozgałęź schemat, jeśli chcesz, aby były to różne dokumenty – czy to oznacza mniej z nich, inne nazwy, czy inną strukturę.

Gdzie znajdują się schematy

OpenSpec szuka schematu w trzech miejscach, w kolejności, i używa pierwszego, który znajdzie:

1. Twój projekt: openspec/schemas/, zapisany w repozytorium, więc cały zespół go otrzymuje.
2. Twoja maszyna: ~/.local/share/openspec/schemas na macOS i Linux (lub pod $XDG_DATA_HOME, jeśli go ustawisz), lub %LOCALAPPDATA%\openspec\schemas na Windows. Schematy tutaj są dostępne w każdym projekcie, w którym pracujesz.
3. Pakiet: wbudowane schematy, takie jak spec-driven, są dostarczane wewnątrz samego OpenSpec.

Ta sama nazwa może istnieć w więcej niż jednym miejscu, a bardziej konkretna lokalizacja ma pierwszeństwo. Polecenie openspec schema which pokazuje, która kopia jest używana:

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

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

Co zawiera schemat

Schemat jest definiowany przez folder zwykłych plików: jeden schema.yaml, który deklaruje artefakty, i szablon dla każdego z nich. Oto wbudowany schemat spec-driven:

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

• schema.yaml: deklaruje każdy artefakt, plik, który generuje, szablon, od którego zaczyna, co wymaga najpierw, i instrukcję, którą agent otrzymuje podczas jego tworzenia. Każde pole ma swoją specyfikację w schema.yaml.
• templates/: jeden szkielet markdown na artefakt, który agent wypełnia.

Oto wpis artefaktu tasks w schema.yaml, skrócony:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Checklist implementacji z śledzonymi zadaniami
    template: tasks.md
    instruction: |
      ...co agentowi jest powiedziane podczas tworzenia tasks.md...
    requires:
      - specs
      - design

Wbudowane schematy są dostarczane wewnątrz pakietu openspec, więc nigdy ich nie edytujesz na miejscu. Uzyskujesz swoją własną kopię poprzez rozgałęzienie.

Tworzenie własnego niestandardowego schematu

Istnieją dwa sposoby uzyskania własnego schematu:

1. Rozgałęź istniejący schemat i edytuj swoją kopię. Zacznij tutaj, gdy istniejący schemat jest bliski tego, czego chcesz, ponieważ wszystko w nim już działa.
2. Zacznij od zera, gdy żaden z nich nie pasuje, tworząc pusty schemat za pomocą openspec schema init.

Rozgałęź istniejący schemat

1. Rozgałęź schemat, od którego chcesz zacząć, uruchamiając polecenie z katalogu głównego projektu:

   $ 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

   Podaj drugi argument, aby wybrać nazwę (openspec schema fork spec-driven team-flow). Nazwy są w formacie kebab-case.

2. Edytuj kopię: schema.yaml i szablony. Edycja twojego rozgałęzienia wyjaśnia, co należy zmienić.

3. Zvalidateuj go:

   openspec schema validate spec-driven-custom

   To jest jedyne polecenie, które wykrywa uszkodzony schemat (brakujące szablony, zły YAML, cykle zależności) przed rozpoczęciem zmiany.

4. Wskazuj swój projekt na niego w openspec/config.yaml. Ten krok jest Twoim zadaniem, ponieważ rozgałęzienie nie dotyka config.yaml:

   schema: spec-driven-custom

5. Nowe propozycje zmian teraz followują Twój schemat. Zmiany utworzone wcześniej zachowują schemat, z którym się zaczęły.

Aby zastąpić domyślny schemat wszędzie bez dotykania config.yaml, rozgałęź do tej samej nazwy: openspec schema fork spec-driven spec-driven. Kopia Twojego projektu następnie zacienia wbudowany schemat, jak wyjaśniono w sekcji Gdzie znajdują się schematy.

Zacznij od zera

openspec schema init tworzy nowy schemat zamiast kopiować jeden:

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

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

Szkielet jest pusty. Artefakty pochodzą tylko z czterech wbudowanych identyfikatorów, a wygenerowane szablony nie zawierają instrukcji, więc agent otrzymuje mniej wskazówek, dopóki nie napiszesz własnych. Stamtąd kroki rozgałęzienia mają zastosowanie bez zmian: zvalidateuj go, a następnie wskaż config.yaml na niego.

Edycja twojego rozgałęzienia

Rozgałęzienie ma dwa rodzaje plików do edycji:

• templates/ zmieniają szkielet każdego dokumentu. Dodaj sekcję do szablonu tasks, a każdy nowy tasks.md zaczyna się od niej. Zachowaj # tytuł na pierwszej linii: artefakt dziedziczy go, więc każdy wygenerowany plik otwiera się jako tytułowany dokument.
• schema.yaml zmienia sam proces: które artefakty istnieją, co każdy z nich wymaga najpierw, i instrukcję, którą agent otrzymuje podczas jego tworzenia.

Na przykład, aby usunąć dokument projektowy dla lżejszego przepływu:

1. Usuń wpis design z schema.yaml.

2. Usuń design z listy requires artefaktu tasks.

3. Zvalidateuj:

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

Pomiń krok 2 i zvalidateuj, a wykryje to błąd:

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

Zvalidateuj po każdej ręcznej edycji. Uszkodzony schemat w przeciwnym razie ujawnia się w środku zmiany, gdy proces wymaga pliku, którego nie ma. Podobnie jak config.yaml, edycje schematu docierają do agenta przy następnym uruchomieniu.

Rozgałęzienie to migawka

openspec update odświeża zainstalowane umiejętności i polecenia, i nigdy nie dotyka openspec/schemas/. Twoje rozgałęzienie działa dokładnie tak, jak je zostawiłeś, co oznacza również, że przestaje otrzymywać ulepszenia, gdy wbudowany schemat ewoluuje. Aby później wybrać te ulepszenia, rozgałęź wbudowany schemat ponownie pod nową nazwą i przenieś różnice.

Udostępnianie schematów

Udostępnianie schematu oznacza skopiowanie jego folderu.

• Ze swoim zespołem: zapisz openspec/schemas/ i każdy na repozytorium go używa.
• W swoich projektach: umieść folder w katalogu użytkownika z sekcji Gdzie znajdują się schematy.
• Od społeczności: katalog społecznościowy zawiera udostępnione schematy. Skopiuj jeden do openspec/schemas/<nazwa> i działa jak Twój własny.

Pracujemy nad rejestrem schematów, publicznym i prywatnym, aby schematy mogły być instalowane przez nazwę zamiast kopiowane ręcznie.

Używaj OpenSpec z Superpowers

Utrzymywany przez społeczność schemat superpowers-bridge łączy artefakty OpenSpec z umiejętnościami wykonawczymi Superpowers. Przed skopiowaniem go do swojego projektu, postępuj zgodnie z instrukcjami instalacji i kompatybilności mostu.

Most jest wydawany poza OpenSpec. OpenSpec nie testuje ani nie wersjonuje swojej integracji z Superpowers.