Troubleshooting

Start any investigation with /doctor in your AI chat — one pass covers setup, adapters, commands, plans, overview freshness, configuration, dashboard state, and workflow drift.

Installation

npx fails with EBADDEVENGINES

The project enforces pnpm through devEngines.packageManager. Switch to pnpm dlx:

pnpm dlx create-syntaxis@latest

Don’t strip out the project’s package-manager requirement just to dodge this.

--scaffold won’t run

It only runs against an empty directory. To bring a stack into a project that already has files, install without --scaffold and run /scaffold from chat instead — that path merges rather than refusing outright.

A scaffolder can’t find its toolchain

Syntaxis never installs a system SDK on your behalf. Grab whichever toolchain it named — the .NET SDK, the Flutter SDK, Rust for Tauri — and run it again.

Commands

The slash command just isn’t there

1. Confirm which adapter actually got installed: .claude/skills/ for Claude Code, .agents/skills/ for Codex.
2. Restart the tool inside this folder. A session that was already open before installation won’t see the new skills.
3. Run npx create-syntaxis@latest status to double-check the install itself.

Some other skill runs instead

Tell the agent to follow the local skill file directly — something like “follow .claude/skills/test-run/SKILL.md.” Then run /doctor to check whether a conflicting global skill is using the same name.

create-syntaxis feature says that’s not a terminal command

That’s correct, and intentional. Workflow commands run in your AI chat, full stop. The terminal CLI only ever covers installation, updates, status, and the dashboard.

Workflow

/complete won’t finish

Almost always an unresolved finding. Look in syntaxis/context/findings.md for a P0 or P1 sitting at open or fixed. Note that fixed still blocks completion — a repair needs /audit to re-review it before it can move to closed.

It also refuses to proceed on stale, pending, or changes-requested independent-review state.

A mutating command stops and points at /doctor

syntaxis/config.json is invalid. Rather than guess what your policy should have been, Syntaxis just stops — /doctor reports the actual schema problem.

The overview looks stale

One of the plans changed in a way that mattered since the overview was last generated. Re-run /overview.

It feels like work in progress got lost after a context clear

It didn’t. Read syntaxis/context/current-feature.md directly, or run /status — this is exactly what artifact-driven state exists to prevent.

Testing

/automate won’t write any tests

No harness is set up yet. Run /tests browser or /tests mobile first — /automate only ever writes into a harness that already exists, it never installs one itself.

A new test passes even though the behavior is broken

/automate is supposed to catch exactly this by proving each test can fail. If one slipped past that check, the usual culprit is a selector that never matched anything, so the assertion silently ran against nothing. Invert the assertion and confirm it fails for the reason you’d expect.

/test-run refuses to even start

Either an entry criterion from syntaxis/qa/test-plan.md wasn’t met, or the build under test couldn’t be pinned down. A cycle run against an unidentified build would produce a record that proves nothing at all.

A mobile harness won’t run

Check what’s actually available in the environment: SDKs, simulators, connected devices, whether it’s headless. /tests mobile reports on this honestly instead of configuring a harness it already knows can’t execute.

Dashboard

Dashboard state looks malformed

Run /doctor. With your approval, it can offer to reset malformed generated dashboard state. Never hand-edit syntaxis/.state/run.json.

The dashboard won’t start

It binds to 127.0.0.1. Make sure that port is actually free and that you’re running the command from the project root.

Still not fixed

Open an issue with the version (npx create-syntaxis@latest --version), which adapter you’re using, your OS and Node version, and the exact step where things went wrong.