Troubleshooting

Four situations that come up in practice, and what's actually happening in each.

A validator fails and won't clear

check-setup-complete and check-config refuse waivers by design — see Validators. There's no bypass flag and no way to mark an item resolved without actually resolving it. Read the exact error text; it names the specific field or file that's wrong, not just "setup incomplete." Fix the root cause it names and re-run. If a value is genuinely unknown rather than wrong, leave it as <USER-TODO> — that's a warning, not a failure, and setup will still finish around it.

The agent doesn't pick up .agentsmyth/setup-bundle.md

After init, the CLI prints: Next step: open your AI agent and say: "run the agentsmyth setup". That freeform phrase relies on the agent's own judgment to notice .agentsmyth/ sitting in the repo root — it doesn't always land. Every supported tool also gets an explicit, typed command from agentsmyth prepare: /agentsmyth in Claude Code, Cursor, Windsurf, and Copilot (VS Code), or /prompts:agentsmyth in Codex. Type it instead of the freeform sentence — it's a fixed command the tool resolves directly, not natural language the agent has to interpret and choose to act on. If neither works, point the agent at the file directly: "read .agentsmyth/setup-bundle.md and follow it."

The hook is rejecting a legitimate commit

The mandatory pre-commit hook checks that staged files are covered by a real lifecycle task artifact, and that any staged lifecycle artifact's entering phase gate is actually satisfied. If it's rejecting something you're confident is fine — a genuinely out-of-band commit, an emergency fix, anything the lifecycle gate wasn't built to anticipate — the only bypass is git commit --no-verify. There's no config flag or waiver file; that's deliberate, so a bypass is always visible in the commit itself rather than silently configured away.

Version skew between ~/.agentsmyth/ and the installed package

agentsmyth check compares the agentsmyth_version stamped in this repo's repo-profile.yaml against the currently installed CLI's own version, and warns if they differ. It does not block check, and it does not mean anything is currently broken — it means this repo is behind the installed package.

Run agentsmyth upgrade. That is the command that clears it: it refreshes the global definitions tree, brings this repo's own governed files current, and rewrites the version stamp the warning is reading.

agentsmyth prepare will not clear it. prepare refreshes the shared tree under ~/.agentsmyth/workflow/ and writes nothing into your repo, so the repo-local stamp never moves and the warning returns on the next check. See Updating for what an upgrade does to each file.