Scope Precedence

Scope Precedence

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 `aiwg doctor`.

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:

aiwg use sdlc --provider claude --scope user        # user-scope: 2026.5.0
cd project-A && aiwg use sdlc --provider claude     # project: 2026.5.0
cd project-B && aiwg use sdlc --provider claude     # project: 2026.6.0-beta.1

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 (`aiwg new-bundle`) 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. `--force` 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

`aiwg list --shadows` (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:

# What's at project scope?
aiwg list --provider claude

# What's at user scope?
aiwg list --scope user

# Compare manually — if a name appears in both, project wins.

`aiwg doctor --scope user` 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

`aiwg refresh` defaults to refreshing the project-scope deploy. To refresh both:

aiwg refresh                      # project scope only
aiwg refresh --scope user         # user scope only (TBD — tracked in #1156)

Until dual-scope refresh ships, run `aiwg use` twice — once with `--scope project` (default) and once with `--scope 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

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

guide to `--scope user`

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