agnostic-ai v0.83.0: explain instructions and check project setup

Agnostic-ai released v0.83.0, adding an `explain` command that reports which instructions cover a given file for Claude Code, Codex and Cursor targets, plus a new `project` command that verifies the installed project binary's version contract before startup. The release also makes OpenCode V2 hooks optional and macOS/Linux-only, with V1 remaining the default, and requires users to stop any running `agnostic-ai watch` process before upgrading from v0.82.0, which cannot run the new project helper. Git and lifecycle hooks now prefer the project installation, so a declared local dependency must be installed and its exact version must agree with `requires`.

Upgrading from v0.82.0 Stop any running agnostic-ai watch process before updating the installation or project config. Git and lifecycle hooks now prefer the project installation. If your project declares agnostic-ai in package.json , install that dependency before running its hooks. An existing exact package version must agree with requires ; a global binary cannot replace a missing declared local installation. Update the dependency, lockfile and requirement together. See project version checks https://agnostic-ai.org/docs/cli-reference/maintain/ project . Install through your existing package manager. For a global npm installation: npm install -g agnostic-ai@0.83.0 For an exact project config pin, agnostic-ai upgrade --requires updates requires and the schema URL to the installed version, then syncs. It also replaces minimum or range requirements and local overrides. To keep a deliberate minimum or range, retain that value, update the schema URL to v0.83.0 , review agnostic-ai migrate --dry-run , and run agnostic-ai sync . Finish with agnostic-ai sync --check , then restart watch. See upgrade behavior https://agnostic-ai.org/docs/cli-reference/maintain/ upgrade . OpenCode V2 hooks are optional and require macOS or Linux. V1 remains the default. Select x-opencode.plugin-api: v2 per hook when using V2; V2 cannot load V1 plugins. On Windows, use OpenCode V1 for generated hooks. Review supported events and blocking behavior https://agnostic-ai.org/docs/targets/opencode/ opencode-v2-hooks before switching. What agnostic-ai changed See which instructions cover a file Claude Code and Codex now join Cursor in file-specific instruction reports. Use a configured project target: agnostic-ai explain --file src/main.go --target claude agnostic-ai explain --file src/main.go --target codex agnostic-ai explain --context --target claude The file report names source specs, planned output paths, selectors and reasons. It marks session-dependent discovery as unknown, including Codex's launch directory. The context report ranks startup sources by words and bytes and separates on-demand bodies. These reports describe planned project configuration; word counts are estimates, not model tokens or observed session context. See instruction and context reports https://agnostic-ai.org/docs/cli-reference/inspect/ explain-a-source-file . compare claude codex now includes hooks, MCP connections and portable permissions. It shows where a field is preserved, translated or unsupported before you move tools. Connection values are hidden, and permission summaries hide recognized credentials. See comparison coverage https://agnostic-ai.org/docs/cli-reference/inspect/ compare . Check the project version before starting work The new project command chooses the installed project binary, checks its version contract, and runs sync or a delegated command. To stop a cached environment before startup when configuration is missing or stale: set -e agnostic-ai project --check agnostic-ai project -- doctor --scope project --check-references The second check covers configured targets and generated skill links without approving local hooks. If the installation is missing or mismatched, agnostic-ai project --bootstrap uses the committed npm or pnpm lockfile to repair it and regenerate output. Install v0.83.0 through your package manager first: v0.82.0 cannot run this helper. Failed checks now retain command errors and timeout reasons. See project readiness https://agnostic-ai.org/docs/cli-reference/maintain/ project-readiness . Keep worktree setup and handoff notes in the right checkout Claude Code handoff hooks now read the active checkout from native event input. To rerun changed environment setup in an existing linked worktree, sync there first, then run: agnostic-ai hook worktree-refresh --repo /path/to/main --worktree /path/to/linked Only that worktree's setup marker resets. The separate hook worktree-remove helper removes a registered clean worktree under an explicitly allowed root; changed, ignored or locked contents stop removal. See refreshing setup https://agnostic-ai.org/docs/cli-reference/maintain/ hook-worktree-refresh and safe removal https://agnostic-ai.org/docs/cli-reference/maintain/ hook-worktree-remove . Adopt OpenCode V2 and Copilot user hooks For OpenCode V2 on macOS or Linux, a native before-tool check can use: name: guard-shell targets: opencode event: PreToolUse matcher: shell command: .agnostic-ai/scripts/guard-shell.sh x-opencode: plugin-api: v2 Create the executable script first. A before-tool command exiting 2 blocks the operation; other failures are logged and continue. Commands receive native event JSON on stdin. Timeouts and plugin unload stop owned processes. This route has no portable on mapping or structured stdout decisions. See OpenCode V2 hooks https://agnostic-ai.org/docs/targets/opencode/ opencode-v2-hooks . OpenCode sync and import also preserve disable-model-invocation: true and native invocation metadata. V2 keeps a manual-only skill out of the model's available list while allowing explicit loading; V1 does not enforce the flag. Import preserves the V2 MCP envelope, disabled servers, separate timeouts and servers added by hand. See OpenCode configuration https://agnostic-ai.org/docs/targets/opencode/ . Copilot user hooks now round-trip through agnostic-ai import --global copilot and agnostic-ai sync --global --only copilot . Sync keeps matching handwritten handlers in their original files to avoid duplicate execution, and creates them in the managed file on a fresh machine. See Copilot hooks https://agnostic-ai.org/docs/targets/copilot/ hooks . Keep source edits and diagnostics usable new now scaffolds all ten spec kinds. import reconcile plans later skill edits, assets and deletions against the canonical tree after a migration; review and apply that plan separately. See scaffolding https://agnostic-ai.org/docs/cli-reference/start/ new and reconciliation https://agnostic-ai.org/docs/cli-reference/start/ import-reconcile . VS Code shows saved source errors in Problems, clears resolved findings, reports failed drift checks and keeps checks current. Staged checks do less repeated work, typo checks use less memory, and sync --json remains valid on a fresh shared-skill setup while reporting unchanged links as skipped. explain reports when Claude Code or Amp chooses a home skill over a same-name project skill. doctor rtk --command previews RTK rewrites and declared approval changes; it cannot establish live approval. Credential previews hide more secrets, Cline hook tool names remain literal data, and build downloads and npm releases receive stronger verification. Full list: v0.83.0 release notes https://github.com/Chemaclass/agnostic-ai/releases/tag/v0.83.0 . What changed in the targets OpenCode V2 needs a different hook plugin format. The migration reference https://opencode.ai/v2/docs/build/plugins/migrate-v1 , checked October 11, 2026, says V1 plugin code cannot run in V2. The opt-in mapping above follows V2's contract, verified against 2.0.26; generated V2 hooks remain limited to macOS and Linux. Its skill reference https://opencode.ai/v2/docs/skills , checked the same day, also documents manual skill selection. The preserved flag controls automatic availability while keeping explicit loading possible. Copilot CLI combines user and project hooks. Its hooks reference https://docs.github.com/en/copilot/reference/hooks-reference , checked October 11, 2026, documents user files under ~/.copilot/hooks/ or $COPILOT HOME/hooks/ . The global sync and import commands above now cover that route. The cloud agent uses repository hook files instead. Kiro can retain learned repository context. Kiro CLI 2.29.0 https://kiro.dev/changelog/ , announced October 9, 2026, adds Memory to local V3 sessions. Use /memories , then config , to choose read/write, read-only, or off. Writes require a trusted workspace; automatic updates require read/write. The memory guide https://kiro.dev/docs/memory.md , checked October 11, describes repository-scoped records, while IDE support remains coming soon. Configure this in Kiro: agnostic-ai does not sync or import its learned records. Trae can group work across multiple repository paths. Trae v3.6.0 https://www.trae.ai/api/changelog , dated October 8, 2026, adds an Agent-window project that mounts multiple paths and groups its tasks, file tree and search. Set up these workspaces in Trae. The announcement gives no project configuration file to sync, and agnostic-ai does not create or import the mounts.