Set up agnostic-ai with a coding agent

Use this guide when a user asks you to install or configure agnostic-ai in a repository. Your job is to preserve existing AI tool behavior, establish .agnostic-ai/ as the source of truth, and leave the project with a clean validation result.

Safety contract

• Work from the repository root. Read its contributor and agent instructions first.
• Check git status --short. Preserve unrelated work and never discard user changes.
• Inspect agnostic-ai.yaml, .agnostic-ai/, and the native configuration for tools already used by the project.
• Import existing native configuration before the first sync. Sync is an output operation, not a migration shortcut.
• Enable only the targets the project uses or the user requests. Never select every target by default.
• Preview changes before writing. Stop on an ownership or overwrite error and explain the conflicting path.
• Treat .agnostic-ai/ as canonical after setup. Native target files are generated outputs.

1. Install or verify the CLI

Start with:

agnostic-ai --version

If the command is missing, use the platform installer.

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/Chemaclass/agnostic-ai/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/Chemaclass/agnostic-ai/main/scripts/install.ps1 | iex

Run agnostic-ai --version again. If the shell cannot find the binary, add the installer destination to PATH before continuing. See Installation for pinned versions and other methods.

2. Detect the project state

Choose one path:

• Already configured: agnostic-ai.yaml and .agnostic-ai/ exist. Do not run init again. Review the configured targets and continue to validation.
• Existing native AI configuration: files such as CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/, or .github/copilot-instructions.md exist, but agnostic-ai is not configured. Import them during initialization.
• Fresh setup: no canonical or native AI configuration exists. Initialize only the targets the project will use.

When target choice is ambiguous, ask the user. Do not infer that every installed CLI belongs in this repository.

3. Initialize safely

For existing native configuration, replace the example target list with the tools the project uses:

printf '%s\n' 'claude,codex' | agnostic-ai init --from all

--from all imports every detected source. When several tools contain different top-level instructions, review .agnostic-ai/AGNOSTIC_AI.md and merge the useful content before syncing. The last imported top-level file wins automatically, so this review is required.

For a fresh project:

printf '%s\n' 'claude,codex' | agnostic-ai init

Do not use --demo in a real repository unless the user asks for example specs. Add project rules only from conventions already present in the repository or supplied by the user. See Getting started for the spec workflow and Migration for detailed import behavior.

4. Validate and preview

Run these commands in order:

agnostic-ai validate
agnostic-ai lint
agnostic-ai sync --dry-run

Read the preview. Confirm that selected targets, output paths, and preserved instructions match the project. Resolve validation errors in the canonical specs. Do not silence unsupported-capability warnings until you understand their effect.

5. Sync and prove the result

agnostic-ai sync
agnostic-ai sync --check
git status --short
git diff -- .

Inspect the generated files and .gitignore changes. The default setup ignores generated outputs, so a fresh clone must run agnostic-ai sync. If the project commits generated outputs instead, keep them in the same change as their source specs.

Finish by reporting:

• the installed agnostic-ai version and install method;
• selected targets and imported sources;
• canonical files created or changed under .agnostic-ai/;
• generated outputs and whether Git tracks them;
• the results of validate, lint, and sync --check;
• any unsupported capability or decision left for the user.

Do not call setup complete until agnostic-ai sync --check exits successfully.