{"slug": "agnostic-ai-v0-83-0-explain-instructions-and-check-project-setup", "title": "agnostic-ai v0.83.0: explain instructions and check project setup", "summary": "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`.", "body_md": "## Upgrading from v0.82.0\n\nStop any running `agnostic-ai watch` process before updating the installation or project config.\n\n**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).\n\nInstall through your existing package manager. For a global npm installation:\n\n```\nnpm install -g agnostic-ai@0.83.0\n```\n\nFor 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).\n\n**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.\n\n## What agnostic-ai changed\n\n### See which instructions cover a file\n\nClaude Code and Codex now join Cursor in file-specific instruction reports. Use a configured project target:\n\n```\nagnostic-ai explain --file src/main.go --target claude\nagnostic-ai explain --file src/main.go --target codex\nagnostic-ai explain --context --target claude\n```\n\nThe 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).\n\n`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).\n\n### Check the project version before starting work\n\nThe 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:\n\n```\nset -e\nagnostic-ai project --check\nagnostic-ai project -- doctor --scope project --check-references\n```\n\nThe 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).\n\n### Keep worktree setup and handoff notes in the right checkout\n\nClaude 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:\n\n```\nagnostic-ai hook worktree-refresh --repo /path/to/main --worktree /path/to/linked\n```\n\nOnly 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).\n\n### Adopt OpenCode V2 and Copilot user hooks\n\nFor OpenCode V2 on macOS or Linux, a native before-tool check can use:\n\n```\nname: guard-shell\ntargets: [opencode]\nevent: PreToolUse\nmatcher: shell\ncommand: .agnostic-ai/scripts/guard-shell.sh\nx-opencode:\n  plugin-api: v2\n```\n\nCreate 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).\n\nOpenCode 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/).\n\nCopilot 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).\n\n### Keep source edits and diagnostics usable\n\n`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).\n\nVS 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.\n\n`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).\n\n## What changed in the targets\n\n**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.\n\n**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.\n\n**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.\n\n**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.", "url": "https://wpnews.pro/news/agnostic-ai-v0-83-0-explain-instructions-and-check-project-setup", "canonical_source": "https://agnostic-ai.org/updates/2026-10-11-v0.83.0/", "published_at": "2026-10-10 22:00:00+00:00", "updated_at": "2026-10-11 21:03:30.779418+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents"], "entities": ["agnostic-ai", "Claude Code", "Codex", "Cursor", "OpenCode", "npm", "pnpm"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/agnostic-ai-v0-83-0-explain-instructions-and-check-project-setup", "markdown": "https://wpnews.pro/news/agnostic-ai-v0-83-0-explain-instructions-and-check-project-setup.md", "text": "https://wpnews.pro/news/agnostic-ai-v0-83-0-explain-instructions-and-check-project-setup.txt", "jsonld": "https://wpnews.pro/news/agnostic-ai-v0-83-0-explain-instructions-and-check-project-setup.jsonld"}}