User-Scope Deployment

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.

the agent-owned use operation deploys frameworks to your project tree by default (`.claude/`, `.codex/`, `.factory/`, etc.). With `the scope option 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 the agent-owned use operation 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

Use AIWG to complete this documented outcome: Quick Start
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Global Bootstrap Without Project Artifacts

Use the global option when the provider supports native user-level discovery and you do not want each project to carry its own deployed agents, commands, skills, and rules:

Use AIWG to complete this documented outcome: Use the global option when the provider supports native user-level discovery and you do not want each project to carry its own deployed agents, commands, skills, and rules
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

AIWG stages the normal deployment temporarily, mirrors framework and kernel skills into the provider's user-level paths, records them in `~/.aiwg/installed.json`, and removes the stage. The current project receives only the lightweight context graph and provider bootstrap files, such as `WORKSPACE.md`, `AIWG.md`, `CLAUDE.md`, or `AGENTS.md`. It does not retain a project `.claude/`, `.codex/`, or equivalent artifact deployment.

Run the agent-owned regenerate operation in another project to generate or refresh those context-only hooks against the existing user-level installation. Providers without a verified filesystem-based user loader still require their documented project adapter; the global option does not make an unsupported global loader appear.

`the scope option user` remains the additive compatibility mode described below: it keeps the project deployment and mirrors it to user scope. the global option is the explicit no-project-artifact contract.

Supported Providers

Provider	User-scope path	Status
Claude Code	`~/.claude/{agents,commands,skills,rules}/`	Verified (docs)
OpenClaw	`~/.openclaw/{agents,commands,skills,rules,behaviors}/`	Always user-scope (no `the scope option project`)
OpenHuman	`~/.openhuman/skills/` for kernel skills; `~/.openhuman/.aiwg/rules/` for rule bodies; optional native agents in `~/.openhuman/agents/`; project `AGENTS.md` bridge	Verified against OpenHuman induction ADR; home-dir payload plus project context 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`)
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
OpenCode	`~/.config/opencode/{agents,commands}/`; skills at `~/.agents/skills/` (cross-provider canonical)	Verified (opencode.ai/docs/skills, 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) 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
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
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

the agent-owned use operation 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 `the scope option user` deploy is additive: it doesn't replace the project deploy, it copies alongside it.

1. the agent-owned use operation 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 the agent-owned remove operation 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 the agent-owned list operation and the agent-owned doctor operation can find it from any cwd

The Per-User Registry

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

{
  "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 the agent-owned remove operation: 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 the agent-owned use operation 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` 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

Use AIWG to complete this documented outcome: Removing a User-Scope Deploy
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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

Use AIWG to complete this documented outcome: Validation with Doctor
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 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 the agent-owned use operation or clear the stale registry entry with the agent-owned remove operation.

OpenClaw, OpenHuman, and Hermes

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

the agent-owned use operation is implicitly user-scope (no

flag needed)

the agent-owned use operation is a no-op
the agent-owned use operation errors with a

clear message: there is no project-scope OpenClaw deploy to track

OpenHuman is also home-dir-oriented for skills. the agent-owned use operation records the OpenHuman home-rooted payload in the user registry so the agent-owned list operation, the agent-owned doctor operation, and the agent-owned remove operation can reason about it from any cwd. The default deploy does not copy markdown personas. It writes a project-root `AGENTS.md` bridge for commands and indexed rules; optional curated native harness agents are TOML files under `~/.openhuman/agents/`.

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.

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

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

`scope-precedence.md` — How project-scope

and user-scope deploys resolve when both are installed

`README.md` — Customization paths overview
`from-fork-to-project-local.md`

— Project-local bundle workflow

User-Scope Deployment

User-Scope Deployment

Quick Start

Global Bootstrap Without Project Artifacts

Supported Providers

Codex specifics

How It Works

The Per-User Registry

Coexistence with Project Scope

Removing a User-Scope Deploy

Validation with Doctor

OpenClaw, OpenHuman, and Hermes

Test Isolation

Related

See Also