Check specs and output

Doctor

Claude skill overrides

RTK approval diagnostics

Start troubleshooting with doctor. It checks project and local setup, then suggests a next step. It is read-only unless you pass --fix.

Use validate for invalid spec formats, lint for spec quality, and sync --check for generated files that differ from the sources. status summarizes the project. verify runs your own tasks to check each AI tool's behavior.

validate and lint skip built-in hooks whose target selectors match no selected tool. User-authored hooks get the usual checks.

validate

Load all specs and report parse errors. On success it prints loaded 12 entries. ok.. With no specs it prints loaded 0 entries. ok. and stderr suggests init or import.

For event names, see portable hook events and each target page. Use on: to share an event across tools.

lint

Check spec quality after parsing. Exits 1 on errors. Each code, and the context budgets, are on lint codes; agnostic-ai explain LINT011 prints one code's cause, fix, and config key.

agnostic-ai lint --strict

Fix the named source, rerun lint, then sync if generated output changes.

verify

Run your own checks against each selected AI tool. Omit --target to check every configured target. It first runs sync --check; a missing or stale generated file stops it before any verifier runs or any result is written.

agnostic-ai verify --target codex

The command in verify.command runs once per target, without a shell, and gets this JSON on stdin. Stdout and stderr pass through. A non-zero exit stops the run and becomes the agnostic-ai exit code.

Record and compare runs

Recording is optional. Pick a private destination and an evaluation identifier that names the same task suite, dataset revision, and evaluation rules for both runs:

agnostic-ai verify --target codex --evaluation smoke-v1 --record before.json
# Change an instruction, then regenerate the tool configuration.
agnostic-ai sync
agnostic-ai verify --target codex --evaluation smoke-v1 --record after.json
agnostic-ai verify compare before.json after.json [--json]

Each target in a comparison gets one result:

A changed harness fingerprint names the configuration change, not a failure. The elapsed difference is the second duration minus the first (nanoseconds in JSON); one comparison does not show a statistical improvement. verify compare exits 0 when it can read both files, regressions included, and 1 on an invalid or unsupported file.

The files use schema version: 1 with started_at (UTC RFC 3339), evaluation, verifier_identity, and targets. Each target holds the input fields above, elapsed_ns, outcome, and an optional exit_code. The outcome is passed (exit 0), failed (non-zero exit), execution_error (launch, cancellation, or context preparation failed), or skipped (not attempted after an earlier failure; no context or exit code, duration 0). The CLI and model fields do not establish the model used at runtime.

verifier_identity hashes the resolved executable and the configured arguments. For a known interpreter, a direct script argument adds its code; options before the script, module loading, and inline code leave the identity unknown. Other file arguments do not change it. Change the evaluation identifier when tasks, datasets, remote dependencies, or rules change without changing the executable, arguments, or script.

Raw arguments, verifier output, and environment values are not saved; credentials in CLI and model metadata are redacted, and an evaluation identifier holding a detected credential is rejected. Files are written in one step with mode 0600, which needs a filesystem with hard links for a new file. If saving fails, a failed evaluation keeps its exit code and a passing one exits 1; the save error is reported separately. Pass rates, token use, and cost are not inferred.

status

Show project configuration and sync state. It exits 0 even on drift; in CI, use sync --check or doctor.

agnostic-ai status [--json]

Project: my-project
Layers:  project (.agnostic-ai/)
Specs:   3 rules, 1 agent, 2 skills
Targets: claude, cursor, copilot
Last sync: 2026-05-07 14:22 (5 files changed)
Drift:   in sync