# User-Scope Deployment

`aiwg use` deploys frameworks to your project tree by default
(`.claude/`, `.codex/`, `.factory/`, etc.). With `--scope user`, AIWG also
mirrors the deploy to the platform's user-scope directory under your
home folder, so the framework is available across every project on the
machine without re-running `aiwg use` per project.

This is most useful when:

- You're the sole user of a workstation and want a framework available
  globally
- A platform's discovery model favors user-scope (Claude Code reads
  `~/.claude/skills/` from every project automatically)
- You manage a small fleet of repos and don't want a `.claude/` deploy
  in each one

If you're working in a team repo where everyone needs the same
deployment regardless of personal setup, stick with the default
project-scope deploy and commit `.aiwg/` (or whichever provider dirs
your team uses).

## Quick Start

```bash
# Deploy SDLC to ~/.claude/{agents,commands,skills,rules}/ alongside
# the project deploy
aiwg use sdlc --provider claude --scope user

# --user is a shorthand for --scope user
aiwg use sdlc --provider claude --user

# List user-scope deployments (works from any cwd)
aiwg list --scope user

# Validate user-scope registry against actual disk state
aiwg doctor --scope user
aiwg doctor --user --verbose       # surface every missing path

# Revert the user-scope mirror (registry + recorded artifact files)
aiwg remove sdlc --scope user
aiwg remove sdlc --user --provider claude --dry-run
```

## Supported Providers

| Provider | User-scope path | Status |
|----------|-----------------|--------|
| Claude Code | `~/.claude/{agents,commands,skills,rules}/` | **Verified** ([docs](https://code.claude.com/docs/en/skills)) |
| OpenClaw | `~/.openclaw/{agents,commands,skills,rules,behaviors}/` | Always user-scope (no `--scope project`) |
| OpenHuman | `~/.openhuman/skills/` for kernel skills; `~/.openhuman/.aiwg/{skills,rules}/` for AIWG payload; agents remain project `.agents/agents/` | **Verified** against OpenHuman induction ADR; home-dir provider with AGENTS.md command/rule bridge |
| Hermes | `~/.hermes/skills/` | Always user-scope (skills only) |
| Codex | `~/.agents/skills/` (skills); `~/.codex/prompts/` (commands; deploy-for-visibility, not auto-scanned) | **Verified** ([`codex-rs/core-skills/src/loader.rs`](https://github.com/openai/codex)) |
| Cursor | `~/.cursor/{agents,skills,commands,rules}/` (harmless mirror; not auto-scanned) | **Non-applicable** — Cursor's "User Rules" feature is in-app settings, not filesystem-discovered; only project-scope `.cursor/rules/*.mdc` is confirmed. See [#1159](https://git.integrolabs.net/roctinam/aiwg/issues/1159) |
| OpenCode | `~/.config/opencode/{agents,commands}/`; skills at `~/.agents/skills/` (cross-provider canonical) | **Verified** ([opencode.ai/docs/skills](https://opencode.ai/docs/skills/), [opencode.ai/docs/rules](https://opencode.ai/docs/rules/)) — user-scope root is `~/.config/opencode/`, NOT `~/.opencode/` |
| Factory AI | `~/.factory/{droids,skills,commands}/` | **Verified** ([docs.factory.ai/cli/configuration/skills](https://docs.factory.ai/cli/configuration/skills)) for skills; droids/commands paths follow project-scope convention |
| Copilot | `~/.config/github-copilot/{agents,prompts,instructions}/` (harmless mirror; not auto-scanned) | **Non-applicable** — VS Code Copilot's user-scope customization is `settings.json` + Settings Sync, not filesystem discovery. See [#1160](https://git.integrolabs.net/roctinam/aiwg/issues/1160) |
| Warp | `~/.warp/{agents,commands,rules}/` (harmless mirror; not auto-scanned) | **Non-applicable** — Warp's user-scope mechanism is Warp Drive (cloud-synced), not filesystem discovery. WARP.md aggregation is the project-scope path. See [#1162](https://git.integrolabs.net/roctinam/aiwg/issues/1162) |
| Windsurf | `~/.windsurf/{agents,skills,workflows,rules}/` (harmless mirror; not auto-scanned) | **Non-applicable** — Windsurf's user-scope mechanism is Cascade Memories (in-app, agent-managed) + global rules in the settings UI, not filesystem discovery. See [#1163](https://git.integrolabs.net/roctinam/aiwg/issues/1163) |

`aiwg use ... --scope user --provider <unknown>` errors fast rather
than silently falling back to project scope.

### Codex specifics

Codex's user-scope skills land at `~/.agents/skills/` — that's the
cross-provider canonical path the codex-rs loader actually scans. Codex
commands deploy at `~/.codex/prompts/` for operator visibility, but
codex-rs ships a static built-in command enum so this directory is **not
auto-scanned** by the runtime. The directory exists per AIWG's ADR-1
"always deploy" invariant: operators can see what AIWG would have
shipped, and AGENTS.md acts as the discovery bridge for the actual
commands. Same applies at project scope (`.codex/prompts/`).

## How It Works

A user-scope deploy is **additive**: it doesn't replace the project
deploy, it copies alongside it.

1. `aiwg use sdlc --provider claude --scope user` runs the normal
   project-scope deploy first (writing to `.claude/`)
2. Then it mirrors each artifact directory (agents, commands, skills,
   rules, behaviors) to the corresponding user-scope path
3. The mirror records exactly which entries it copied, per artifact
   type, so `aiwg remove` can later delete only this framework's
   contributions to the shared user-scope dirs
4. The deploy is recorded in a per-user registry at
   `~/.aiwg/installed.json` so `aiwg list` and `aiwg doctor` can find
   it from any cwd

## The Per-User Registry

`~/.aiwg/installed.json` holds one entry per framework deployed at
user scope:

```json
{
  "version": "1",
  "installed": {
    "sdlc": {
      "version": "2026.5.0",
      "source": "bundled",
      "installedAt": "2026-05-08T02:33:00.000Z",
      "deployedTo": {
        "claude": {
          "agents": 189,
          "commands": 0,
          "skills": 386,
          "rules": 14,
          "entries": {
            "agents": ["api-designer", "test-engineer", "..."],
            "skills": ["sdlc-accelerate", "intake-wizard", "..."]
          }
        }
      }
    }
  }
}
```

The `entries` snapshot is what enables precise `aiwg remove --scope
user`: the handler reads this list and deletes exactly those entries
from the user-scope dirs, leaving every other framework's artifacts
in place.

Older registry entries (written before the `entries` snapshot was
recorded) fall back to a conservative "registry-only revert" with a
manual cleanup hint. Re-running `aiwg use` upgrades the entry.

## Coexistence with Project Scope

Both scopes can be installed simultaneously. The project deploy in
`.claude/` shadows the user deploy in `~/.claude/` for any project
that contains the project artifacts (mirroring how Claude Code itself
resolves: project takes precedence over user). See
[`scope-precedence.md`](./scope-precedence.md) for the resolution
rules.

This means you can:

- Pin a specific framework version at user scope as your default
- Override per-project with a different version or with custom
  project-local bundles

## Removing a User-Scope Deploy

```bash
# Revert all providers' user-scope mirrors of sdlc
aiwg remove sdlc --scope user

# Revert just one provider
aiwg remove sdlc --user --provider claude

# Preview without touching disk
aiwg remove sdlc --user --provider claude --dry-run
```

The remove handler:

1. Looks up the framework's entry in `~/.aiwg/installed.json`
2. For each provider's deploy, walks the recorded `entries` list
3. Deletes each entry from its corresponding user-scope dir
4. Updates the registry

Other frameworks' artifacts in the same user-scope dirs are untouched.

## Validation with Doctor

```bash
aiwg doctor --scope user            # summary — exit 1 on drift
aiwg doctor --user --verbose        # list every missing path
```

`aiwg doctor --scope user` walks the per-user registry, calls `stat`
on each recorded entry path, and reports drift. Drift means a
recorded entry doesn't exist on disk anymore — usually because
something was deleted manually. Repair by re-running `aiwg use` or
clear the stale registry entry with `aiwg remove --scope user`.

## OpenClaw, OpenHuman, and Hermes

OpenClaw is exclusively user-scope by design — its native discovery
model only reads from `~/.openclaw/`. So:

- `aiwg use ... --provider openclaw` is implicitly user-scope (no
  flag needed)
- `aiwg use ... --provider openclaw --scope user` is a no-op
- `aiwg use ... --provider openclaw --scope project` errors with a
  clear message: there is no project-scope OpenClaw deploy to track

OpenHuman is also home-dir-oriented for skills. `aiwg use ... --provider
openhuman --scope user` records the OpenHuman home-rooted payload in the
user registry so `aiwg list --scope user`, `aiwg doctor --scope user`, and
`aiwg remove --scope user --provider openhuman` can reason about it from
any cwd. Markdown agents remain workspace-scoped at `.agents/agents/` by
design, and commands/rules are bridged through `AGENTS.md`.

Hermes is similar (skills-only at user scope by design).

## Test Isolation

If you're writing tests that exercise user-scope behavior and don't
want them to clobber your real `~/.aiwg/installed.json`, set
`AIWG_USER_REGISTRY_PATH` to a tmpdir path. The registry helper
honors this env override and reads/writes there instead.

```bash
export AIWG_USER_REGISTRY_PATH=/tmp/aiwg-test-reg/installed.json
```

Production code never sets this — it exists for the test suite.

## Related

- [`scope-precedence.md`](./scope-precedence.md) — How project-scope
  and user-scope deploys resolve when both are installed
- [`README.md`](./README.md) — Customization paths overview
- [`from-fork-to-project-local.md`](./from-fork-to-project-local.md)
  — Project-local bundle workflow

## See Also

- AIWG #1156 — User-scope deployment for providers that support
  ~/-level discovery
- ADR-4 — Scope flag and path map