Upgrading from v0.75.0

Stop sync --watch before migrating or installing. For rules meant to use only file filters, remove both explicit and folder-inferred scope. For example, move .agnostic-ai/rules/src/typescript.md to .agnostic-ai/rules/typescript.md, remove scope: src, and use globs: ["src/**/*.ts"]. Scope, globs and paths now form a union: keeping a scope selects its whole directory too. Make this change before a postinstall can run sync.

Manually align existing exact requires and schema pins to 0.76.0/v0.76.0 for every install channel; keep a deliberate minimum/range that accepts this release. Then choose your existing channel:

Standalone macOS/Linux: agnostic-ai upgrade --version v0.76.0.

Project npm dependency: npm install --save-dev --save-exact agnostic-ai@0.76.0.

For other channels, see installation. Use the local runner for a project dependency. Regenerate, lint and check, then review and commit tracked changes before restarting watchers:

agnostic-ai sync
agnostic-ai lint
agnostic-ai sync --check

If a Claude environment spec has setup, remove an equivalent hand-written worktree bootstrap hook to avoid running it twice.

What agnostic-ai changed

Rules and model roles have clearer meaning

Selectors now combine directory scope and file patterns. Follow the migration above; scoped context explains each target's activation limits.

Model tiers let agents, skills and settings name a role instead of repeating target choices:

models:
  strong: {claude: opus, codex: gpt-5.5, effort: high}
  fast: {claude: haiku, codex: o4-mini}

A spec with model: strong gets its target's model. Use available account IDs and explain the consuming spec to inspect its resolution. Models.

Protect files and test guards before relying on them

A settings spec can protect project paths:

protected:
  paths: [.github/**, composer.lock]
  decision: deny

Claude uses Edit permissions; Codex and Gemini use hooks; Cursor supports CLI-only deny. Other targets remain advisory. Trust Codex hooks and check shell dependencies before relying on guards; shell writes can bypass edit-tool protection. Protected paths.

Shared .agnostic-ai/scripts/ bodies copy with permissions intact and target references rewritten. Events and reply protocols still need native handling. After sync, test an existing force-push guard:

agnostic-ai hook run guard --target codex --bash "git push --force" --expect block

hook run checks command-hook payloads and decisions for Claude, Codex, Gemini, Trae, OpenHands, Goose and Augment. Non-command/asynchronous handlers are not blocking-guard tests. hook paths extracts edited paths from event payloads. Hook scripts, hook commands.

Gate unsupported behavior without losing hand-written settings

coverage.fail-on-notes: true can fail project sync on unsupported fields; coverage.accept records intentional differences with reasons. Acceptance does not add support, and lint catches stale entries. Failed sync restores outputs. Shared settings now retain unrelated user keys while removing stale generated values, and malformed MCP JSON fails instead of being replaced. Coverage.

Native outputs fit each tool better

  • Codex: exact subtree rules produce nested AGENTS.md; filename filters remain inline with a note. Start Codex in the subtree to load its instruction chain. Opt-in exec-policies-from-permissions translates Bash permissions, but prefix matching can widen exact commands. Review the Codex mapping before enabling it.
  • Claude: environment setup runs once per new worktree; x-claude.setup: false opts out. .worktreeinclude excludes runtime files.
  • Gemini, Cursor and Copilot: agent MCP servers use Gemini's native mcp_servers; Cursor gets CLI allow/deny permissions with notes for unsupported rules; Copilot writes agents and skills back to existing native paths and retains instruction descriptions.

The v0.76.0 changelog has the remaining fixes.

What changed in the targets

  • VS Code 1.140 (September 30): root .mcp.json is preferred; deprecated .vscode/mcp.json still loads. agnostic-ai keeps the legacy default. Its existing outputs.copilot.root-mcp-file: .mcp.json opt-in also writes the portable root file, so review the diff when adopting it. Release notes, MCP formats.
  • Kiro workflows (September 30, including IDE 1.2.4): opt-in recipes under .kiro/workflows/ remain native-managed. v0.76 does not emit/import workflow recipes, and agent x-kiro metadata does not create them. IDE notes, Web announcement.