Scope Precedence

Scope Precedence

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

When the same framework is installed at both project scope (`.claude/`) and user scope (`~/.claude/`), the AI platform decides which one takes effect. AIWG mirrors that resolution and surfaces drift through the agent-owned doctor operation.

TL;DR

Project scope wins. Any artifact present in the project deploy shadows the user-scope copy of the same name. The user-scope copy remains intact and will be visible again the moment the project deploy is removed (or a different project is opened).

Why This Order

The host platforms drive the policy — AIWG follows it.

  • Claude Code: scans `.claude/` first, then `~/.claude/`. Same-name

artifacts in the project shadow the user copy. Documented at code.claude.com/docs/en/skills and /sub-agents.

  • Cursor: project `.cursor/rules/` takes precedence over the

user-scope rules path (per Cursor's MDC discovery rules).

  • OpenCode / Warp / Windsurf / Factory: similar

project-first-then-user resolution; AIWG records the user-scope paths in `USER_SCOPE_PATHS` but the platforms perform the actual shadow.

The behavior is consistent enough across providers that AIWG doesn't try to enforce a different precedence — operators get whatever their host platform does.

Mental Model

Think of user scope as your default and project scope as your override:

~/.claude/skills/sdlc-accelerate     ← default (user-scope deploy)
{repo-A}/.claude/skills/...          ← repo A uses defaults
{repo-B}/.claude/skills/sdlc-accelerate ← repo B overrides with a custom version

In repo A, the platform falls through to the user-scope deploy. In repo B, the project deploy shadows it. This matches how shell `PATH`-style resolution works in most tooling.

Implications

Pinning Versions

Use user scope as the place to pin a specific framework version that should be your global default:

Use AIWG to complete this documented outcome: Use user scope as the place to pin a specific framework version that should be your global default
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Project A and B each pick the project deploy; the user-scope deploy isn't reached. Open a third project that doesn't have `.claude/` populated and the user-scope `2026.5.0` is what's visible to Claude.

Project-Local Overrides

Project-local bundles (the agent-owned new-bundle operation) deploy to project scope by default. When a project-local bundle and a user-scope artifact have the same name, the project-local copy shadows. This makes it easy to override a single agent or skill per project without disturbing your global default.

See `from-fork-to-project-local.md`.

Safety-Critical Override

Project-scope artifacts can shadow upstream cleanly. AIWG enforces a denylist on safety-critical artifacts (security rules, license checks): shadowing them requires an explicit `overrides:` declaration in the project-local manifest. the force option does not bypass the denylist. See adr-override-shadow-policy.md.

This denylist applies the same way regardless of scope — a project-scope deploy can't silently shadow a safety-critical upstream artifact, and neither can a project-scope deploy silently shadow a safety-critical user-scope artifact.

Detecting Shadows

the agent-owned list operation (project-scope) shows project-local bundles that shadow upstream. There's no equivalent dedicated command for "user-scope shadowed by project-scope" because the host platform's discovery handles the resolution and there's no AIWG-side manifest that captures the shadow.

If you want to audit what your platform is actually using:

Use AIWG to complete this documented outcome: If you want to audit what your platform is actually using
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

the agent-owned doctor operation validates that user-scope artifacts still exist on disk; it doesn't try to predict which scope your platform will resolve at runtime.

Refresh Behavior

the agent-owned refresh operation defaults to refreshing the project-scope deploy. To refresh both:

Use AIWG to complete this documented outcome: the agent-owned refresh operation defaults to refreshing the project-scope deploy. To refresh both
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Until dual-scope refresh ships, run the agent-owned use operation twice — once with `the scope option project` (default) and once with `the scope option user`.

When Versions Diverge

If project scope is on framework version X and user scope is on Y:

  • Inside the project: X is what's used
  • Outside the project (or in any other project that doesn't have

`.claude/` populated): Y is what's used

the agent-owned doctor operation doesn't currently warn about version skew between scopes. It will when the doctor `the scope option user` validation gains a cross-scope comparison pass. Tracked under #1156.

guide to `the scope option user`

  • `README.md` — Customization paths overview
  • ADR-4 — Scope flag, path map, precedence policy