Troubleshooting
Run commands from the directory containing agnostic-ai.yaml.
| Symptom | Next step |
|---|---|
agnostic-ai is not found | Check the install destination and PATH |
| The version did not change after upgrading | Run agnostic-ai upgrade --check to find PATH shadowing |
| Config is missing | Change to the project root, or run agnostic-ai init for a new project |
| A new clone or worktree has no tool files | Run agnostic-ai sync; ignored outputs are absent from Git |
| An edited spec has no effect | Run agnostic-ai list to confirm it loads, then agnostic-ai sync --dry-run to inspect planned output |
| A tool receives only some spec kinds | Check its capabilities and any unsupported-kind warnings |
sync --check reports drift | Run agnostic-ai sync, review the result, and commit outputs if the project tracks them |
| CI fails on every fresh checkout | Match the CI recipe to whether generated outputs are committed |
| Two targets emit to the same path | Read AAI-102 and inspect output overrides |
sync refuses to write a .*ignore file | Read AAI-103, import the patterns, and review their order and negations |
| A scoped rule is skipped, conflicts, or appears missing | Check scoped-rule diagnostics |
| Watch mode misses changes on a mounted filesystem | Try agnostic-ai sync --watch --watch-poll |
Inspect the project
agnostic-ai status
agnostic-ai validate
agnostic-ai doctor
status summarizes the project and reports drift without a failing exit code. validate checks source specs. doctor diagnoses configuration and output problems and can exit non-zero. See CLI reference for flags and exit behavior.
Use why to trace a generated file to its source, or graph to see which targets receive a spec. For a diagnostic code, run agnostic-ai explain AAI-003, replacing the code with the one reported.
Scoped rules
| Symptom | Next step |
|---|---|
unknown flag: --scope | Install a build containing the feature; see setup. |
| A rule is skipped or a filter cannot be preserved | Check target support and selector limits. |
| Shared readers conflict or instructions differ | Use compatible targets and identical shared content, or separate worktrees. --only and prefer-spec do not bypass scope conflicts. |
| Hand-authored or alternate instructions conflict | Import and preserve the original, then move its native filename. Follow migration. |
| An output override is rejected | Remove the named override and keep provenance headers enabled. |
Cursor has no scoped .mdc file | It can share nested AGENTS.md with Codex. Run agnostic-ai graph --spec <name>. |
| An old scope file remains | Run a full sync, then sync --check. Hand-authored files are preserved. |
Report a problem
Include the CLI version, OS, failing command, full error, and the smallest config/spec that reproduces the failure. Remove credentials from MCP configuration and logs before sharing. Open a bug report.