Probleemoplossing

Concrete oplossingen voor concrete problemen. Elke entry noemt een symptoom, legt de waarschijnlijke oorzaak in één zin uit en geeft je de oplossing. Als je hier je probleem niet ziet, kan de FAQ helpen, en de Discord zeker.

Installatie en configuratie

openspec: command not found

De CLI is niet geïnstalleerd, of je shell kan hem niet vinden. Installeer hem globaal en controleer:

npm install -g @fission-ai/openspec@latest
openspec --version

Als hij geïnstalleerd is maar nog steeds niet gevonden wordt, staat je globale npm bin-map waarschijnlijk niet in je PATH. Voer npm prefix -g uit om te zien waar globale pakketten staan: op macOS en Linux bevinden de binaries zich in de bin/-map van die map, en op Windows staan ze direct in die map. Zorg dat dat pad in je PATH staat. (npm bin -g is verwijderd in npm 9.)

Als je de AI-geassisteerde installatie hebt gebruikt, is dit het verwachte overdrachtspunt: die prompt vertelt je assistent om je de PATH-wijziging te tonen in plaats van zelf je shell-startbestanden te bewerken.

"Requires Node.js 20.19.0 or higher"

OpenSpec draait op Node 20.19.0+. Controleer je versie en upgrade indien nodig:

node --version

Als je bun gebruikt om OpenSpec te installeren, houd dan rekening met het feit that OpenSpec nog steeds draait op Node, dus je hebt Node 20.19.0+ nodig in je PATH, ongeacht wat. Zie Installatie.

openspec init heeft mijn AI-tool niet geconfigureerd

Init vraagt welke tools je wilt instellen. Als je je tool hebt overgeslagen of een andere wilt toevoegen, voer je het gewoon opnieuw uit, of gebruik de niet-interactieve vorm:

openspec init --tools claude,cursor

De volledige lijst met tool-IDs staat in Ondersteunde Tools. Gebruik --tools all voor alles, --tools none om tool-configuratie over te slaan.

Commando's verschijnen niet

Als /opsx:propose (of het equivalent van je tool) niet verschijnt of niets doet, werk dan deze lijst af. Ze staan in volgorde van snelst te controleren eerst.

1. Je zit misschien op de verkeerde plek. Slash-commando's gaan in de chat van je AI-assistent, niet in je terminal. Als je /opsx:propose in je shell hebt getypt, is dat het probleem. Zie Hoe Commando's Werken.

2. Genereer de bestanden opnieuw. Vanuit je projectroot:

   openspec update

   Dit schrijft de skill- en commandobestanden opnieuw voor elke tool die je hebt geconfigureerd.

   Instructiebestanden komen van de geïnstalleerde CLI, dus een verouderde CLI rapporteert dat alles up-to-date is zonder ooit de nieuwere workflows te schrijven. openspec update controleert nu of dat het geval is en biedt een upgrade aan — neem het aanbod aan als je het ziet.

3. Herstart je assistent. De meeste tools scannen bij het opstarten naar skills en commando's. Een nieuw venster lost het vaak op.

4. Bevestig dat de bestanden bestaan. Voor Claude Code, controleer dat .claude/skills/ openspec-*-mappen bevat. Andere tools gebruiken hun eigen mappen, allemaal opgesomd in Ondersteunde Tools.

5. Controleer of je dit project hebt geïnitialiseerd. Skills worden per project geschreven. Als je een repo hebt gekloond of van map bent gewisseld, voer daar openspec init (of openspec update) uit.

6. Bevestig dat je tool commandobestanden ondersteunt. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent en het gedeelde .agents-doel krijgen geen gegenereerde opsx-*-commandobestanden; ze gebruiken skill-based aanroepen in plaats daarvan, dus /opsx zal voor hen nooit automatisch worden aangevuld. Typ $openspec-propose in Codex, /skill:openspec-propose in Kimi Code en /openspec-propose in de rest. Het gedeelde .agents-doel is vendor-neutraal, dus /openspec-propose is de algemene vorm in plaats van een gegarandeerde — als je assistent daar niet op reageert, controleer dan in de eigen documentatie hoe het een skill aanroept. Amazon Q krijgt wel commandobestanden, maar laadt ze in zijn promptbibliotheek in plaats van in zijn slashmenu — typ daar @opsx-propose, niet /opsx. De vorm van elke tool staat opgesomd in Hoe Aan te Roepen.

Werken met wijzigingen

"Change not found"

Het commando kon niet vaststellen welke wijziging je bedoelde. Noem het expliciet, of controleer wat er bestaat:

openspec list                    # zie actieve wijzigingen
/opsx:apply add-dark-mode        # noem de wijziging in de chat

Bevestig ook dat je in de juiste projectmap zit.

"No artifacts ready"

Elk artifact is al aangemaakt of geblokkeerd door een afhankelijkheid. Zie wat blokkeert:

openspec status --change <name>

Maak daarna eerst de ontbrekende afhankelijkheid aan. Onthoud de volgorde: proposal activeert specs en design; specs en design samen activeren tasks.

openspec validate rapporteert waarschuwingen of fouten

Validatie controleert je specs en wijzigingen op structurele problemen. Lees de melding: hij noemt het bestand en het probleem.

openspec validate <name>           # valideer één item
openspec validate --all            # valideer alles
openspec validate --all --strict   # strengere controles, geschikt voor CI
openspec validate --archived       # faal als gearcheefde wijzigingen ongecontroleerde tasks hebben

Gemeenschappelijke oorzaken zijn een ontbrekende verplichte sectie (zoals een spec zonder scenarios) of een verkeerd geformatteerde delta-header. Corrigeer het bestand en voer het opnieuw uit. De CLI-referentie documenteert de output-indeling.

Eén melding verdient een eigen opmerking:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Een MODIFIED-requirement vervangt het hele requirementblok, dus het moet elk scenario bevatten dat de wijziging overleeft, niet alleen degenen die je hebt bewerkt. Kopieer de genoemde scenarios terug uit openspec/specs/<capability-path>/spec.md naar de delta, waarbij je eventuele domeinmappen in het pad behoudt. Dit komt vaak voor bij een oudere wijziging nadat iemand anders een scenario aan hetzelfde requirement heeft toegevoegd — archivering weigert die wijziging in elk geval, en validatie zegt dat nu voordat je het implementeert.

De AI heeft onvolledige of verkeerde artifacts aangemaakt

De AI had niet genoeg context. Een paar aanpassingen helpen:

• Voeg projectcontext toe in openspec/config.yaml zodat je stack en conventies in elke aanvraag worden geïnjecteerd. Zie Aanpassing.
• Voeg per-artifact rules: toe voor richtlijnen die alleen op bijvoorbeeld specs van toepassing zijn.
• Geef een gedetailleerdere beschrijving wanneer je proposeert.
• Gebruik de uitgebreide /opsx:continue om één artifact tegelijk te maken en elk te beoordelen, in plaats van /opsx:ff die ze allemaal tegelijk doet.

Archivering wil niet afmaken, of waarschuwt over onvolledige tasks

Archivering blokkeert niet op onvolledige tasks, maar het waarschuwt je, omdat archivering meestal betekent dat het werk klaar is. Als tasks bewust overblijven (je dient een gedeeltelijke wijziging in), ga dan door. Anders voltooi eerst de tasks. Archivering biedt ook aan om je delta-specs te synchroniseren met de hoofdspecs als je dat nog niet hebt gedaan; zeg ja tenzij je een reden hebt om dat niet te doen.

"User force closed the prompt with 0 null"

Er is ergens openspec archive uitgevoerd waar niets een vraag kan beantwoorden — een AI-agent die het vanuit een tool aanroept, een CI-job, of een shell met gesloten stdin. Archivering vraagt tot drie bevestigingen, en een onbeantwoordbare vraag faalde vroeger met die ruwe melding.

Geef --yes om ze vooraf te beantwoorden:

openspec archive <change-name> --yes

Behoud alle vlaggen die je al doorgeeft — --skip-specs en --no-validate veranderen wat archivering doet, dus een blote --yes-heruitvoering is niet hetzelfde commando. Huidige versies noemen de vlag voor je en printen een Fix:-regel die je kunt plakken. Als je bedoelde om uit een lijst te kiezen, geef dan de wijzigingsnaam expliciet door: de picker heeft ook een antwoord nodig.

Als je in plaats daarvan archivering hebt uitgevoerd met de output naar een bestand omgeleid of door een tool gevangen en wel een antwoord hebt gepijpt (printf 'y\n' | openspec archive …), schreven oudere versies terminal-escape-codes naar die vangst terwijl ze de prompt tekenden — in sommige omgevingen genoeg om het bestand ernstig te laten opzwellen. Huidige versies lezen de bevestigingsprompts als gewone tekst wanneer stdout geen terminal is, en een argumentloze openspec archive (die anders een interactieve wijzigingspicker zou tekenen) vraagt je om een wijzigingsnaam vooraf door te geven in plaats van een menu naar de vangst te renderen. In beide gevallen blijven omgeleide en agent-uitvoeringen schoon; --yes doorgeven (met een wijzigingsnaam) slaat de prompts helemaal over.

Configuratie

Mijn config.yaml wordt niet toegepast

Drie gebruikelijke verdachten:

1. Verkeerde bestandsnaam. Het moet openspec/config.yaml zijn, niet .yml.
2. Ongeldige YAML. Voer het door een YAML-validator; de CLI rapporteert ook syntaxisfouten met regelnummers.
3. Je verwachtte een herstart. Dat is niet nodig. Configuratieveranderingen hebben onmiddellijk effect.

"Unknown artifact ID in rules: X"

Een sleutel onder rules: komt niet overeen met een artifact in je schema. Voor het standaard spec-driven-schema zijn de geldige IDs proposal, specs, design, tasks. Om de IDs voor elk schema te zien:

openspec schemas --json

"Context too large"

Het context:-veld is bewust beperkt tot 50KB, omdat het in elke aanvraag wordt geïnjecteerd. Samenvat het, of link naar langere documenten in plaats van ze te plakken. Slanke context levert ook betere en snellere resultaten op.

"Schema not found"

De schemanaam die je hebt verwezen bestaat niet. Lijst wat beschikbaar is en controleer de spelling:

openspec schemas                    # lijst beschikbare schemas
openspec schema which <name>        # zie waar een schema vandaan komt
openspec schema init <name>         # maak een aangepast schema

Zie Aanpassing.

Migratie van de legacy-workflow

"Legacy files detected in non-interactive mode"

Je zit in CI of een niet-interactieve shell, en OpenSpec vond oude bestanden om op te ruimen maar kan je niet vragen. Keur automatisch goed:

openspec init --force

Voor Codex kan OpenSpec oude beheerde promptbestanden detecteren in $CODEX_HOME/prompts of ~/.codex/prompts. Die opruiming is beperkt tot de op de whitelist van OpenSpec staande legacy Codex promptbestandsnamen, en niet-interactieve openspec init verwijdert alleen de bestanden waarvan de vervangende .agents/skills/openspec-*-skills bestaan. Niet-interactieve openspec update laat alle legacy-opruiming onaangetast tenzij je --force doorgeeft.

Commando's verschenen niet na migratie

Herstart je IDE. Skills worden bij het opstarten gedetecteerd. Als ze nog steeds niet verschijnen, voer openspec update uit en controleer de bestandslocaties in Ondersteunde Tools.

Mijn oude project.md is niet gemigreerd

Dat is bewust. OpenSpec verwijdert project.md nooit automatisch omdat het context kan bevatten die je hebt geschreven. Verplaats de nuttige delen naar de context:-sectie van config.yaml, en verwijder het daarna zelf. De Migratiegids loopt hier doorheen, inclusief een prompt die je aan je AI kunt geven om het destilleren te doen.

Nog steeds vastgelopen?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Vanuit je terminal: openspec feedback "what went wrong" opent een issue voor je.

Als je een probleem rapporteert, neem dan je OpenSpec-versie (openspec --version), je Node-versie (node --version), je AI-tool en het exacte commando en de output mee. Dat maakt hulp veel sneller.