Migracja do OPSX

Ten przewodnik pomoże Ci przejść ze starszego przepływu pracy OpenSpec do OPSX. Migracja została zaprojektowana tak, aby przebiegała płynnie — Twoja dotychczasowa praca zostaje zachowana, a nowy system oferuje większą elastyczność.

Co się zmienia?

OPSX zastępuje stary przepływ pracy oparty na fazach podejściem płynnym, opartym na akcjach. Oto kluczowa zmiana:

Aspekt	Legacy	OPSX
Komendy	/openspec:proposal, /openspec:apply, /openspec:archive	Domyślnie: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (rozszerzone komendy przepływu pracy opcjonalne)
Przepływ pracy	Twórz wszystkie artefakty jednocześnie	Twórz stopniowo lub wszystkie naraz — Twój wybór
Cofanie się	Niewygodne bramy fazowe	Naturalne — aktualizuj dowolny artefakt w dowolnym momencie
Dostosowywanie	Stała struktura	Oparte na schemacie, w pełni modyfikowalne
Konfiguracja	CLAUDE.md ze znacznikami + project.md	Czysta konfiguracja w openspec/config.yaml

Zmiana filozofii: Praca nie jest liniowa. OPSX przestaje udawać, że jest.

Przed rozpoczęciem

Twoje istniejące prace są bezpieczne

Proces migracji został zaprojektowany z myślą o zachowaniu danych:

• Aktywne zmiany w openspec/changes/ — Całkowicie zachowane. Możesz je kontynuować za pomocą poleceń OPSX.
• Zarchiwizowane zmiany — Nieskazitelné. Twoja historia pozostaje nienaruszona.
• Główne specyfikacje w openspec/specs/ — Nieskazitelné. To Twoje źródło prawdy.
• Twoja treść w CLAUDE.md, AGENTS.md itp. — Zachowana. Usunięte zostaną wyłącznie bloki znaczników OpenSpec; wszystko, co napisałeś, pozostaje.

Co zostanie usunięte

Wyłącznie pliki zarządzane przez OpenSpec, które są zastępowane:

Co	Dlaczego
Katalogi/pliki starszych poleceń z ukośnikiem	Zastąpione przez nowy system umiejętności
openspec/AGENTS.md	Przestarzały wyzwalacz przepływu pracy
Znaczniki OpenSpec w CLAUDE.md, AGENTS.md itp.	Nie są już potrzebne

Lokalizacje starszych poleceń według narzędzia (przykłady — Twoje narzędzie może się różnić):

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Devin Desktop, wcześniej Windsurf: .windsurf/workflows/openspec-*.md
• Cline: .clinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md (tylko rozszerzenia IDE; nieobsługiwane w Copilot CLI)
• Codex: OpenSpec używa teraz kanonicznej ścieżki .agents/skills/openspec-*. Pliki SKILL.md zarządzane przez OpenSpec pod dawną ścieżką .codex/skills są pojednowane dopiero po istnieniu zastępców; pliki niestandardowe i rozbieżne kopie pozostają na miejscu. Jeśli nieoznaczony katalog .agents zawiera już umiejętności OpenSpec, OpenSpec zachowuje istniejące renderowanie Codex ($openspec-*) lub ogólne (/openspec-*) zamiast zgadywać na podstawie katalogu legacy. Wybierz codex jawnie za pomocą openspec init, aby przejąć własność. Sprzątanie starszych promptów dotyczy nadal wyłącznie nazw plików z listy dozwolonych OpenSpec w $CODEX_HOME/prompts lub ~/.codex/prompts.
• Inne (Augment, Continue, Amazon Q itp.)

Migracja wykrywa skonfigurowane narzędzia i sprząta ich pliki legacy.

Lista usunięć może wydawać się długa, ale to wszystkie pliki, które OpenSpec pierwotnie utworzył. Twoja własna treść nigdy nie jest usuwana.

Co wymaga Twojej uwagi

Jeden plik wymaga ręcznej migracji:

openspec/project.md — Ten plik nie jest automatycznie usuwany, ponieważ może zawierać kontekst projektu, który napisałeś. Musisz:

1. Przeglądnąć jego zawartość
2. Przenieść przydatny kontekst do openspec/config.yaml (patrz wskazówki poniżej)
3. Usunąć plik, gdy będziesz gotów

Dlaczego wprowadziliśmy tę zmianę:

Stary project.md był bierny — agenci mogli go przeczytać, mogli nie przeczytać, mogli zapomnieć, co przeczytali. Zauważyliśmy, że niezawodność była niespójna.

Nowy kontekst w config.yaml jest aktywnie wstrzykiwany do każdego żądania planowania OpenSpec. Oznacza to, że Twoje konwencje projektu, stack technologiczny i zasady są zawsze obecne, gdy AI tworzy artefakty. Wyższa niezawodność.

Kompromis:

Ponieważ kontekst jest wstrzykiwany do każdego żądania, warto być zwięzłym. Skup się na tym, co naprawdę ważne:

• Stack technologiczny i kluczowe konwencje
• Nieoczywiste ograniczenia, o których AI musi wiedzieć
• Zasady, które wcześniej często były ignorowane

Nie martw się o perfekcję. Nadal uczymy się, co działa najlepiej, i będziemy udoskonalać sposób wstrzykiwania kontekstu w miarę eksperymentów.

---

Uruchamianie migracji

Oba polecenia openspec init i openspec update wykrywają pliki legacy i prowadzą Cię przez ten sam proces sprzątania. Użyj tego, które pasuje do Twojej sytuacji:

• Nowe instalacje domyślnie używają profilu core (propose, explore, apply, update, sync, archive).
• Zmigrowane instalacje zachowują wcześniej zainstalowane przepływy pracy, zapisując profil custom, gdy jest to potrzebne.

Używanie openspec init

Uruchom to, jeśli chcesz dodać nowe narzędzia lub ponownie skonfigurować, które narzędzia są ustawione:

openspec init

Polecenie init wykrywa pliki legacy i prowadzi przez sprzątanie:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

Co się dzieje, gdy powiesz tak:

1. Katalogi starszych poleceń z ukośnikiem są usuwane
2. Znaczniki OpenSpec są usuwane z CLAUDE.md, AGENTS.md itp. (Twoja treść zostaje)
3. openspec/AGENTS.md jest usuwany
4. Nowe umiejętności są instalowane w .claude/skills/
5. openspec/config.yaml jest tworzony z domyślnym schematem

Używanie openspec update

Uruchom to, jeśli chcesz tylko zmigrować i odświeżyć istniejące narzędzia do najnowszej wersji:

openspec update

Polecenie update również wykrywa i sprząta artefakty legacy, a następnie odświeża wygenerowane umiejętności/polecenia, aby pasowały do Twojego bieżącego profilu i ustawień dostarczania.

Środowiska nieneinteraktywne / CI

Dla skryptowych migracji:

openspec init --force --tools claude

Flaga --force pomija pytania i automatycznie akceptuje sprzątanie.

Obejmuje to sprzątanie plików promptów Codex zarządzanych przez OpenSpec w globalnym katalogu promptów Codex. Sprzątanie dotyczy wyłącznie nazw plików starszych promptów Codex z listy dozwolonych OpenSpec, usuwa je dopiero po istnieniu zastępczych umiejętności .agents/skills/openspec-* i zachowuje wszystkie inne pliki.

---

Migracja project.md do config.yaml

Stary openspec/project.md był swobodnym plikiem markdown z kontekstem projektu. Nowy openspec/config.yaml jest strukturalny i — co kluczowe — wstrzykiwany do każdego żądania planowania, dzięki czemu Twoje konwencje są zawsze obecne, gdy AI pracuje.

Przed (project.md)

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

Po (config.yaml)

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Kluczowe różnice

project.md	config.yaml
Swobodny markdown	Strukturalny YAML
Jeden blok tekstu	Osobny kontekst i zasady per artefakt
Niejasne, kiedy jest używany	Kontekst pojawia się we WSZYSTKICH artefaktach; zasady tylko w dopasowanych artefaktach
Brak wyboru schematu	Jawne pole schema: ustawia domyślny przepływ pracy

Co zachować, co odrzucić

Podczas migracji bądź selektywny. Zapytaj siebie: "Czy AI potrzebuje tego do każdego żądania planowania?"

Dobre kandydatury do context:

• Stack technologiczny (języki, frameworki, bazy danych)
• Kluczowe wzorce architektoniczne (monorepo, mikrousługi itp.)
• Nieoczywiste ograniczenia ("nie możemy użyć biblioteki X, ponieważ...")
• Krytyczne konwencje, które często są ignorowane

Przenieś do rules: zamiast tego

• Formatowanie specyficzne dla artefaktu ("używaj Given/When/Then w specyfikacjach")
• Kryteria przeglądu ("propozycje muszą zawierać plan wycofania")
• Pojawiają się one tylko dla dopasowanego artefaktu, utrzymując inne żądania lżejszymi

Pozostaw całkowicie

• Ogólne najlepsze praktyki, które AI już zna
• Rozbudowane wyjaśnienia, które można streścić
• Kontekst historyczny, który nie wpływa na bieżącą pracę

Kroki migracji

1. Utwórz config.yaml (jeśli nie został już utworzony przez init):

   schema: spec-driven

2. Dodaj swój kontekst (bądź zwięzły — to trafia do każdego żądania):

   context: |
     Your project background goes here.
     Focus on what the AI genuinely needs to know.

3. Dodaj zasady per artefakt (opcjonalnie):

   rules:
     proposal:
       - Your proposal-specific guidance
     specs:
       - Your spec-writing rules

4. Usuń project.md, gdy przeniesiesz wszystko przydatne.

Nie przejmuj się nadmiernie. Zacznij od podstaw i iteruj. Jeśli zauważysz, że AI czegoś ważnego nie wie, dodaj to. Jeśli kontekst wydaje się nadmierny, odchudź go. To żywy dokument.

Potrzebujesz pomocy? Użyj tego promptu

Jeśli nie jesteś pewien, jak skondensować swój project.md, zapytaj swojego asystenta AI:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

AI pomoże Ci zidentyfikować, co jest niezbędne, a co można pominąć.

---

Nowe polecenia

Dostępność poleceń zależy od profilu:

Domyślny (profil core):

Polecenie	Cel
/opsx:propose	Utwórz zmianę i wygeneruj artefakty planowania w jednym kroku
/opsx:explore	Rozważ pomysły bez struktury
/opsx:apply	Zaimplementuj zadania z tasks.md
/opsx:update	Zrewiduj artefakty planowania zmiany i utrzymaj ich spójność
/opsx:sync	Scal specyfikacje delta z głównymi specyfikacjami
/opsx:archive	Sfinalizuj i zarchiwizuj zmianę

Rozszerzony przepływ pracy (wybór niestandardowy):

Polecenie	Cel
/opsx:new	Rozpocznij nowy szkielet zmiany
/opsx:continue	Utwórz następny artefakt (po jednym)
/opsx:ff	Szybkie przewinięcie — utwórz artefakty planowania naraz
/opsx:verify	Zweryfikuj, czy implementacja odpowiada specyfikacjom
/opsx:bulk-archive	Zarchiwizuj wiele zmian naraz
/opsx:onboard	Prowadzony przepływ pracy onboardingu od początku do końca

Włącz rozszerzone polecenia za pomocą openspec config profile, a następnie uruchom openspec update.

Mapowanie poleceń z wersji legacy

Legacy	Odpowiednik OPSX
/openspec:proposal	/opsx:propose (domyślnie) lub /opsx:new, a następnie /opsx:ff (rozszerzony)
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

Nowe możliwości

Te możliwości są częścią rozszerzonego zestawu poleceń przepływu pracy.

Dokładne tworzenie artefaktów:

/opsx:continue

Tworzy po jednym artefakcie na raz na podstawie zależności. Użyj tego, gdy chcesz przeglądać każdy krok.

Tryb eksploracji:

/opsx:explore

Rozważ pomysły z partnerem, zanim zobowiążesz się do zmiany.

---

Zrozumienie nowej architektury

Od zablokowanego w fazach do płynnego

Poprzedni przepływ pracy wymuszał liniową progresję:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Jeśli jesteś na etapie implementacji i zdajesz sobie sprawę, że projekt jest błędny?
Szkoda. Bramki fazowe nie pozwalają łatwo wrócić.

OPSX używa akcji, a nie faz:

         ┌───────────────────────────────────────────────┐
         │           AKCJE (nie fazy)                    │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    dowolna kolejność          │
         └───────────────────────────────────────────────┘

Graf zależności

Artefakty tworzą graf skierowany. Zależności są umożliwieniami, nie bramkami:

                        proposal
                       (węzeł główny)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (wymaga:                  (wymaga:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (wymaga:
                     specs, design)

Po uruchomieniu /opsx:continue sprawdza, co jest gotowe, i oferuje następny artefakt. Możesz także tworzyć wiele gotowych artefaktów w dowolnej kolejności.

Umiejętności a polecenia

Poprzedni system korzystał z plików poleceń specyficznych dla narzędzia:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX korzysta z nowego standardu umiejętności:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Umiejętności są rozpoznawane w wielu narzędziach do kodowania AI i dostarczają bogatszych metadanych.

Codex w OPSX korzysta wyłącznie z umiejętności. OpenSpec nie generuje już niestandardowych plików promptów Codex; zamiast tego użyj wygenerowanych katalogów .agents/skills/openspec-*.

---

Kontynuowanie istniejących zmian

Twoje trwające zmiany działają płynnie z poleceniami OPSX.

Masz aktywną zmianę ze starszego przepływu pracy?

/opsx:apply add-my-feature

OPSX odczytuje istniejące artefakty i kontynuuje od miejsca, w którym skończyłeś.

Chcesz dodać więcej artefaktów do istniejącej zmiany?

/opsx:continue add-my-feature

Pokazuje, co jest gotowe do utworzenia na podstawie tego, co już istnieje.

Potrzebujesz zobaczyć status?

openspec status --change add-my-feature

---

Nowy system konfiguracji

Struktura config.yaml

# Wymagane: Domyślny schemat dla nowych zmian
schema: spec-driven

# Opcjonalne: Kontekst projektu (maks. 50KB)
# Wstrzykiwany do WSZYSTKICH instrukcji artefaktów
context: |
  Tło projektu, stos technologiczny,
  konwencje i ograniczenia.

# Opcjonalne: Reguły dla poszczególnych artefaktów
# Wstrzykiwane tylko do pasujących artefaktów
rules:
  proposal:
    - Dołącz plan wycofania zmian
  specs:
    - Użyj formatu Given/When/Then
  design:
    - Udokumentuj strategie awaryjne
  tasks:
    - Podziel na fragmenty o maksymalnym czasie 2 godzin

Rozwiązywanie schematu

Przy określaniu schematu OPSX sprawdza w kolejności:

1. Flaga CLI: --schema <name> (najwyższy priorytet)
2. Metadane zmiany: .openspec.yaml w katalogu zmiany
3. Konfiguracja projektu: openspec/config.yaml
4. Domyślny: spec-driven

Dostępne schematy

Schemat	Artefakty	Najlepszy dla
spec-driven	proposal → specs → design → tasks	Większość projektów

Wyświetl wszystkie dostępne schematy:

openspec schemas

Schematy niestandardowe

Stwórz własny przepływ pracy:

openspec schema init my-workflow

Lub sklonuj istniejący:

openspec schema fork spec-driven my-workflow

Zobacz Dostosowywanie po szczegóły.

---

Rozwiązywanie problemów

Wykryto pliki starszego typu w trybie nieinteraktywnym

Uruchamiasz w środowisku CI lub nieinteraktywnym. Użyj:

openspec init --force

Polecenia nie pojawiają się po migracji

Uruchom ponownie IDE. Umiejętności są wykrywane przy starcie.

Nieznany identyfikator artefaktu w regułach

Sprawdź, czy klucze rules: pasują do identyfikatorów artefaktów twojego schematu:

• spec-driven: proposal, specs, design, tasks

Uruchom to, aby zobaczyć prawidłowe identyfikatory artefaktów:

openspec schemas --json

Konfiguracja nie jest stosowana

1. Upewnij się, że plik znajduje się w openspec/config.yaml (nie .yml)
2. Zweryfikuj składnię YAML
3. Zmiany w konfiguracji obowiązują natychmiast — ponowne uruchomienie nie jest wymagane

project.md nie został zmigrowany

System celowo zachowuje project.md, ponieważ może zawierać twoją niestandardową treść. Przejrzyj go ręcznie, przenieś przydatne części do config.yaml, a następnie usuń go.

Chcesz zobaczyć, co zostałoby wyczyszczone?

Uruchom init i odrzuć monit o czyszczenie — zobaczysz pełne podsumowanie wykrytych elementów bez dokonywania żadnych zmian.

---

Szybki przegląd

Pliki po migracji

project/
├── openspec/
│   ├── specs/                    # Niezmienione
│   ├── changes/                  # Niezmienione
│   │   └── archive/              # Niezmienione
│   └── config.yaml               # NOWE: Konfiguracja projektu
├── .claude/
│   └── skills/                   # NOWE: Umiejętności OPSX
│       ├── openspec-propose/     # domyślny profil podstawowy
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # rozszerzony profil dodaje new/continue/ff/itp.
├── CLAUDE.md                     # Znaczniki OpenSpec usunięte, twoja treść zachowana
└── AGENTS.md                     # Znaśniki OpenSpec usunięte, twoja treść zachowana

Co zniknęło

• .claude/commands/openspec/ — zastąpione przez .claude/skills/
• openspec/AGENTS.md — przestarzałe
• openspec/project.md — przenieś do config.yaml, a następnie usuń
• Bloki znaczników OpenSpec w CLAUDE.md, AGENTS.md itp.

Ściągawka poleceń

/opsx:propose      Szybki start (domyślny profil podstawowy)
/opsx:apply        Implementuj zadania
/opsx:archive      Zakończ i zarchiwizuj

# Rozszerzony przepływ pracy (jeśli włączony):
/opsx:new          Utwórz szkielet zmiany
/opsx:continue     Utwórz następny artefakt
/opsx:ff           Utwórz artefakty planistyczne

---

Uzyskiwanie pomocy

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Dokumentacja: docs/opsx.md dla pełnego odnośnika OPSX