feat: declaratively materialize global agent profiles

[christso]

Problem

AllAgents can synchronize plugins and agent artifacts into default user and project client locations, but it cannot declaratively create separate user-level client profiles.

For example, setting up a Compound Engineering OMP profile currently requires imperative commands:

omp --profile compound-engineering plugin marketplace add EveryInc/compound-engineering-plugin
omp --profile compound-engineering plugin install compound-engineering@compound-engineering-plugin

The user must also remember how to launch that profile. OMP can create a shell alias, but that mutates shell startup files and is not a portable launcher lifecycle.

The desired profile, launcher, native plugins, selected skills, MCP servers, and settings should be reproducible from the user-owned AllAgents workspace instead of imperative setup steps.

Goal

Allow the user-level ~/.allagents/workspace.yaml to declaratively define reusable agent profiles:

profiles:
  compound-engineering:
    clients:
      - name: omp
        install: native
        launcher: omp-compound

    plugins:
      - source: EveryInc/compound-engineering-plugin
        ref: main
        install: native

A user explicitly materializes a declared profile once:

allagents profile install compound-engineering

AllAgents creates the selected native profile, configuration root, or documented configuration override, installs its declared resources, generates its launchers, and records enough ownership state to update or remove those resources safely.

Once installed, ordinary allagents update reconciles the installed profiles declared by the user-level workspace as part of the existing user sync pass. If the command is run from a project workspace, the existing project sync pass still runs independently.

Scope model

Global profiles and project workspaces are independent:

~/.allagents/workspace.yaml
├── top-level plugins           -> existing default user client state
└── profiles                    -> explicitly installed user-level client profiles

<project>/.allagents/workspace.yaml
└── top-level clients/plugins   -> existing project-local client state

Requirements:

• profiles is valid only in ~/.allagents/workspace.yaml.
• A project-scoped .allagents/workspace.yaml containing profiles is a validation error.
• Profiles always materialize user-level native profiles, configuration roots, or documented configuration overrides. An override isolates AllAgents-managed writes but may inherit other client, user, or project configuration; it does not promise strict runtime isolation.
• A profile declaration does not accept scope.
• Project workspaces have no profile lifecycle or profile ownership state.
• Profile commands never search for or read a project workspace declaration.
• Profile installation, update, status, and removal never mutate project files.
• Project synchronization never copies project resources into a global profile.
• Removing a profile declaration does not authorize removal of an installed profile.
• Ordinary sync must not create an uninstalled profile or silently remove an installed profile.

Runtime composition

Profile state and project state do not need an AllAgents merge step.

A generated launcher selects only the declared user-level client profile and preserves the caller's current working directory. The client runtime continues to discover project-local files through its normal rules.

For OMP:

#!/bin/sh
exec omp --profile compound-engineering "$@"

When run inside a synchronized project, both omp and omp-compound can discover that project's .agents, .omp, and other OMP-supported project files. When run outside the project, those project resources are absent. AllAgents does not copy, adopt, track, or reconcile project resources as profile resources.

Launchers must not run allagents update, inspect project configuration, access the network, or perform installation as a side effect of launching the client.

Terminology

• Profile declaration: a named entry under profiles in the user-level ~/.allagents/workspace.yaml.
• Installed profile: user-level client state materialized from a profile declaration and recorded in AllAgents profile ownership state.
• Client: a supported agent runtime configured by a profile, such as OMP, Codex CLI, or Claude Code.
• Native runtime profile: a first-class profile mechanism provided by a client, such as OMP --profile or Codex --profile.
• Configuration root: a client-specific user-state directory selected through an environment variable or equivalent when the client has no suitable native profile mechanism, such as COPILOT_HOME or CLAUDE_CONFIG_DIR.
• Configuration override: a client-specific configuration layer that may inherit other user or project configuration rather than providing strict isolation, such as OpenCode's OPENCODE_CONFIG or OPENCODE_CONFIG_DIR.
• Launcher: a generated platform-native executable that selects a declared client profile or configuration root and forwards arguments. It is not a shell alias.
• Native installation: invoking the selected client's package or plugin lifecycle inside the selected profile or configuration root.
• File installation: AllAgents-managed synchronization into the selected user profile or configuration root.
• Managed resource: a resource AllAgents created and may update or remove while its recorded identity still matches.
• Referenced resource: a matching resource that existed independently. AllAgents may use it but must preserve it on removal.

Use client in the public workspace schema. Do not introduce a separate target taxonomy.

Workspace schema

profiles is a top-level section in the user-level workspace:

profiles:
  compound-engineering:
    clients:
      - name: omp
        install: native
        launcher: omp-compound
        settings: {}

    plugins:
      - source: EveryInc/compound-engineering-plugin
        ref: main
        install: native

    mcpServers: {}

Schema requirements:

• profiles is keyed by profile name.
• Profile names are 1–64 lowercase ASCII characters matching ^[a-z0-9][a-z0-9._-]{0,63}$. . and .. and Windows reserved device basenames are invalid.
• Each profile contains one or more clients, and each client name is unique within that profile.
• Client names use the existing public client vocabulary.
• The profile key is the default native profile/configuration-root identity. Adapters may derive a safe client-specific path from it, but generated machine paths are never workspace input.
• Shared client fields are name, install, launcher, and settings.
• Client-level install is the default plugin materialization mode for that client; a plugin-level install overrides it. It never installs the client executable.
• launcher is optional. Omitting it creates no launcher.
• Launcher names use the profile-name grammar. Declarations and retained installed state must not contain platform-equivalent launcher collisions, including case-folded Windows names and .ps1/.cmd companions.
• settings is an optional strict client-specific object selected by the client name and defaults to {}. Unknown or unsupported settings fail validation before mutation.
• Profile plugins use the existing source, ref, install, clients, and skills vocabulary.
• A plugin can restrict itself to clients in the same profile through clients. Without that selector, it applies to every client in the profile.
• Omitting skills enables all plugin-provided skills; an array is an allowlist; { exclude: [...] } is a blocklist. Native installation with a skill selection fails when the client cannot enforce that selection.
• Profile-specific agents and instructions come from declared plugins through the existing artifact model. Profiles do not introduce a standalone instructions field.
• mcpServers uses the existing workspace MCP declaration vocabulary. Each server applies to every client in the profile unless its existing clients selector restricts it. A selected client that cannot materialize the server fails the complete profile plan before mutation.
• Machine-specific paths, resolved credentials, generated launcher paths, resolved revisions, and ownership state are invalid declaration fields.
• The profile schema is strict. Unknown fields are errors.

There is no generic public capabilities field. The declaration names concrete desired resources. The planner derives the required capabilities, and the selected client adapter reports whether it can materialize them.

Commands and synchronization

allagents profile install [name]

• Reads only ~/.allagents/workspace.yaml.
• Selects the named declaration; if omitted in an interactive terminal, prompts from declared profiles.
• Validates and plans the complete profile before mutation.
• Shows profile/configuration selection, commands, paths, launchers, plugin identities, refs, skills, MCP endpoints or command names, and secret names.
• Requires approval before the first mutation unless an explicit non-interactive approval option is supplied.
• Creates the profile and records ownership incrementally.
• Is idempotent when the same profile is already installed and unchanged.

allagents profile status [name]

• Reads declarations and user-local ownership state without mutation.
• Reports installed, missing, drifted, partial, unsupported, and declaration-missing states per client and resource.

allagents profile remove <name>

• Plans removal from user-local ownership state even when the declaration no longer exists.
• Requires explicit approval.
• Removes only unchanged managed resources whose ownership is still proven.
• Releases referenced resources without deleting them.
• Reports retained, modified, shared, unsupported, and failed resources.

allagents update [--profile <name>...]

Without --profile, the existing command reconciles every applicable resource:

1. Reconcile the user-level workspace, including every installed profile that still has a declaration.
2. When the current directory contains a project workspace, reconcile that project using the existing project behavior.

Both applicable passes are attempted independently with no cross-scope rollback. They may share fetched source caches but do not share declarations, resource plans, or ownership state. Human and JSON output report each scope separately, and the command exits nonzero if either scope fails.

--profile is a repeatable filter:

allagents update --profile compound-engineering
allagents update --profile compound-engineering --profile security-review

When one or more profile filters are present:

• Reconcile only the selected profiles. Skip top-level user resources and the project workspace.
• Read declarations only from ~/.allagents/workspace.yaml.
• Require every selected name to have both a declaration and installed ownership state.
• Validate the complete selected set before the first mutation.
• Deduplicate repeated names while preserving their first-seen order.
• Never treat a missing installation as an install request.
• Support the normal --dry-run and --offline update controls.
• Reject combinations with --scope or --client; the complete profile is the reconciliation unit.
• Report results per profile in human and JSON output and exit nonzero if any selected profile fails or remains partial.
• Remove resources deleted from a still-declared profile only when they remain unchanged and managed.
• Fail on collisions or lost ownership instead of overwriting.

Update is an explicit reconciliation command and does not prompt for separate approval. Deleting an entire profile declaration leaves its installed state declaration-missing and unchanged; ordinary update does not remove it.

Declarative materialization

Before the first mutation, AllAgents must:

1. Parse and validate the complete user workspace and selected profile.
2. Resolve each client's documented profile or configuration-root mechanism.
3. Resolve plugin source metadata and requested refs.
4. Resolve authoritative client-native plugin identities where native installation is requested.
5. Validate skill filtering, MCP, settings, launcher, and cleanup capabilities against each adapter.
6. Inspect destination resources and classify them as creatable, managed, referenced, conflicting, drifted, or unsupported.
7. Produce a concrete ordered plan with redacted effects.
8. Obtain approval when required by the selected lifecycle command.

Apply must execute the approved plan without rediscovering composition interactively. Missing declaration data is a validation error.

For native marketplaces, an adapter resolves the installable plugin identity from authoritative marketplace metadata. If a source remains ambiguous, this version fails validation rather than guessing.

Client adapter seam

Shared profile orchestration owns:

• Workspace and profile validation
• Profile selection
• Requested and resolved refs
• Skill selection semantics
• Plan construction and ordering
• Approval and dry-run behavior
• User-local ownership state
• Result reporting
• Launcher safety
• Secret-reference redaction

Each client adapter owns:

• Native profile, configuration-root, or override selection
• Supported client versions
• Exact native commands
• File locations and precedence
• Native plugin identity resolution
• Client-specific settings validation and serialization
• Skill-filter support
• MCP serialization
• Runtime reload behavior
• Project-file discovery documentation
• Safe status inspection and cleanup

Adapter capabilities are typed implementation metadata, not workspace-authored claims. At minimum they report support for native installation, file installation, launchers, skill filters, MCP, settings, status inspection, and cleanup.

An unsupported declared capability is an actionable validation error. Explicit install: native must never fall back to file copying.

Compound Engineering OMP fixture

The canonical declaration is:

• Profile: compound-engineering
• Client: omp
• Launcher: omp-compound
• Marketplace source: EveryInc/compound-engineering-plugin
• Native plugin: compound-engineering@compound-engineering-plugin
• Installation mode: OMP native installation

The adapter executes the equivalent of:

omp --profile compound-engineering plugin marketplace add EveryInc/compound-engineering-plugin
omp --profile compound-engineering plugin install compound-engineering@compound-engineering-plugin

The POSIX launcher behaves equivalently to:

#!/bin/sh
exec omp --profile compound-engineering "$@"

It preserves arbitrary arguments, the current working directory, signals, and the OMP exit code. OMP's built-in --alias may be an explicitly requested compatibility mode later, but it is not the default launcher implementation.

Native and file installation

install: native delegates to the selected client's installer inside the selected profile or configuration root. The native operation owns marketplace registration, installed-plugin metadata, locks, discovery, upgrade, and uninstall behavior. AllAgents records what it requested and which resources it introduced; it does not emulate native installation by copying runtime files.

install: file synchronizes files only into the selected user profile or configuration root. It never writes profile resources into a project directory.

Linking is supported only where a client exposes a documented link lifecycle. It is not a generic substitute for native installation.

Ownership state and recovery

Profile state is user-local and separate from both global and project sync state:

~/.allagents/profiles/<profile-name>/state.json

The versioned state records:

• Installed profile and client identities
• Normalized declaration digest
• Requested and resolved plugin refs
• Concrete native package, marketplace, MCP, configuration, and launcher identities
• Managed or referenced ownership relationship
• Last observed content or identity fingerprint where available
• Cleanup mechanism
• Per-operation completion and partial-failure state

State never contains secret values.

Persist successful ownership changes immediately so interrupted installation or update can resume safely. External installers and configuration writers are not one transaction; a partial operation must report partial, retain uncertain provenance, and stop before unsafe cleanup.

Repeat install or update is idempotent. Removal compares recorded ownership with live state and preserves modified, unrelated, shared, referenced, or uncorroborated resources. Policy-retained resources are preserved and this profile's ownership relationship is released. Failed or uncertain operations retain their state for retry and leave the profile partial. Profile state is deleted only after every relationship has been removed or explicitly released.

Trust and secrets

The global workspace is user-owned, but it can still request executable native installation and MCP configuration. Plans must disclose:

• Client and profile/configuration mechanism
• Native commands
• Package sources and resolved revisions
• Launcher destinations
• Local MCP command names and arguments with secrets redacted
• Remote MCP endpoints
• Names, but never values, of requested secrets

Secrets are environment or credential-store references. Resolved values must not be written to workspace YAML, generated launchers, ownership state, logs, errors, or command arguments. If a client cannot consume a secret reference without persisting plaintext, the adapter reports that capability as unsupported.

The portable secret-reference syntax is ${ENV_VAR}, where the name matches [A-Za-z_][A-Za-z0-9_]*. AllAgents preserves the reference during planning and materialization. An adapter may use it only where the client resolves the environment reference at runtime without writing the value; otherwise the declaration is unsupported.

Launcher names must be safe command basenames. Creation refuses path traversal, symlink destinations, unsafe parents, or unrelated existing files.

Cross-platform launchers

• Linux/macOS: write an executable wrapper to the configured user bin directory, defaulting to an XDG-compatible location such as ~/.local/bin.
• Windows PowerShell: write a .ps1 launcher that selects the profile/configuration root, forwards all arguments, and returns the client exit code.
• Windows command compatibility: write a companion .cmd shim where required for discovery from PowerShell and cmd.exe.

AllAgents checks whether the launcher directory is on PATH and prints exact remediation. It never modifies .bashrc, .zshrc, PowerShell profiles, or equivalent startup files.

Supported clients and delivery order

Profile adapters are required for:

• Pi
• OMP
• OpenCode
• GitHub Copilot CLI
• OpenAI Codex CLI
• Claude Code

Capability baseline:

Client	Profile/configuration model
Pi	PI_CODING_AGENT_DIR selects a separate agent directory. MCP requires the external pi-mcp-adapter package in that selected agent root.
OMP	--profile <name> / OMP_PROFILE; native state under ~/.omp/profiles/<name>/agent.
OpenCode	OPENCODE_CONFIG and OPENCODE_CONFIG_DIR add configuration layers and do not guarantee strict isolation.
GitHub Copilot CLI	COPILOT_HOME selects a user configuration root.
Codex CLI	--profile <name> selects a configuration overlay. CODEX_HOME is a separate state-root mechanism and must not be conflated with it.
Claude Code	CLAUDE_CONFIG_DIR selects settings, history, and plugin state.

Pi core has no built-in MCP support. Pi MCP is conditionally supported through npm:pi-mcp-adapter.

Pi MCP prerequisite

A profile that selects Pi and declares mcpServers must have pi-mcp-adapter active in the same selected PI_CODING_AGENT_DIR. The prerequisite is satisfied when either:

• the package is already present and usable in that Pi agent root, in which case AllAgents records it as referenced; or
• the same profile declares npm:pi-mcp-adapter with install: native for Pi, in which case the plan installs it before writing MCP configuration and records it as managed.

Example:

profiles:
  pi-research:
    clients:
      - name: pi
        launcher: pi-research

    plugins:
      - source: npm:pi-mcp-adapter
        clients: [pi]
        install: native

    mcpServers:
      research:
        command: research-mcp

The Pi adapter must inspect the selected agent root's native package inventory and verify that the package can be resolved. A pi-mcp-adapter executable elsewhere on PATH is not sufficient because Pi loads the extension from its active package configuration.

If neither prerequisite path is satisfied, validation fails before MCP configuration is written and reports how to declare or install npm:pi-mcp-adapter. AllAgents never adds this executable third-party package implicitly.

pi-mcp-adapter reads standard .mcp.json and Pi-owned MCP files directly. AllAgents writes the declared configuration to the selected profile's <Pi agent dir>/mcp.json; it does not run pi-mcp-adapter init, which is an optional compatibility-import workflow.

Project MCP files remain project-owned and independent. A Pi launcher can consume them only when pi-mcp-adapter is active in that launcher's selected agent root. AllAgents does not copy project MCP configuration into profiles to satisfy the prerequisite.

Pi and OMP initial client support

Pi and OMP ship in the same initial client-support stage because OMP is a Pi fork and both discover Agent Skills and project-local configuration. Share path validation, skill synchronization, command execution, and result helpers where their contracts are identical. Keep separate adapters for their divergent roots, profile mechanisms, package formats, and native lifecycle commands.

Pi support includes:

• User discovery and file synchronization under ~/.pi/agent.
• Project discovery and file synchronization under .pi.
• Shared user and project skill discovery under .agents/skills.
• Native Pi package install, list, targeted update, and remove through the Pi CLI.
• User and project package scopes, including Pi's project trust requirements.
• Isolated profile roots selected through PI_CODING_AGENT_DIR.
• Conditional MCP support through profile-scoped pi-mcp-adapter prerequisite detection and Pi-owned MCP serialization.

OMP support includes:

• Default user discovery and file synchronization under ~/.omp/agent.
• Named-profile discovery and file synchronization under ~/.omp/profiles/<name>/agent.
• Project discovery and file synchronization under .omp.
• Shared user and project skill discovery under .agents/skills.
• Native OMP marketplace and plugin add, list, update/upgrade, install, and remove through the OMP CLI.
• User and project plugin scopes and named-profile command execution.

XDG and supported environment overrides can relocate client roots. Adapters must use documented client resolution and prefer native commands for package/plugin state instead of assuming every resource remains under the default home path.

Pull request plan

Implement this issue as a stack of independently reviewable PRs. Do not combine unrelated runtime adapters into one review, and do not advertise an adapter until its real-runtime dogfood passes.

1. feat(clients): add Pi and OMP support
   • Add both client types and their project/user artifact mappings.
   • Implement shared Agent Skills discovery and separate Pi package and OMP marketplace/plugin native adapters.
   • Cover default user and project scopes, XDG/environment path resolution, Pi project trust, and native status/update/remove behavior.
   • Add the Pi MCP prerequisite inspection primitives, but no profile commands or launchers.
2. feat(profile): materialize global Pi and OMP profiles
   • Add the global-only profile schema, planner, ownership state, install/status/remove commands, launchers, and repeatable allagents update --profile.
   • Integrate the Pi and OMP adapters, including conditional pi-mcp-adapter handling.
   • Complete the Compound Engineering OMP and native Pi package/MCP dogfood runs.
   • Ship a complete Pi/OMP profile lifecycle; do not leave scaffolding for these clients.
3. feat(profile): add OpenCode profile adapter
   • Implement configuration-override semantics, strict settings, lifecycle inspection, cleanup, and real-runtime dogfood.
4. feat(profile): add Copilot profile adapter
   • Implement COPILOT_HOME selection, native/file capabilities, lifecycle inspection, cleanup, and real-runtime dogfood.
5. feat(profile): add Codex profile adapter
   • Implement --profile versus CODEX_HOME semantics, strict settings, lifecycle inspection, cleanup, and real-runtime dogfood.
6. feat(profile): add Claude profile adapter
   • Implement CLAUDE_CONFIG_DIR selection, native plugin lifecycle, strict settings, cleanup, and real-runtime dogfood.
7. feat(config): publish profile workspace schemas
   • Generate separate user and project workspace JSON Schemas from the final authoritative Zod models.
   • Add drift enforcement, stable versioned URLs, and durable documentation.

Open the PRs as a dependency stack so work continues without waiting for merges:

PR	Branch	Base branch
1	feat/460-pi-omp-support	main
2	feat/460-profile-core	feat/460-pi-omp-support
3	feat/460-profile-opencode	feat/460-profile-core
4	feat/460-profile-copilot	feat/460-profile-opencode
5	feat/460-profile-codex	feat/460-profile-copilot
6	feat/460-profile-claude	feat/460-profile-codex
7	feat/460-profile-schema	feat/460-profile-claude

Each PR contains only its incremental slice and names its immediate prerequisite. Do not wait for a lower PR to merge before implementing or opening the next one. Review and merge bottom-up.

Before a lower PR squash-merges, record the old tip of every branch in the remaining stack. After the merge, fetch current origin/main and move only the direct descendant's incremental commits from the old predecessor tip onto origin/main:

git rebase --onto origin/main <old-predecessor-tip> <direct-descendant-branch>

Cascade the rewrite through later descendants by moving each branch's incremental commits from its old predecessor tip onto that predecessor's newly rewritten tip:

git rebase --onto <new-predecessor-tip> <old-predecessor-tip> <descendant-branch>

Push every rewritten branch with --force-with-lease. Retarget the direct descendant PR to main; keep every later PR targeted at its immediate predecessor branch. Do not use a plain git rebase origin/main, which can replay commits already represented by the squash commit. Never merge without explicit approval.

The adapter PRs follow the same profile interface and ownership contract established by the Pi/OMP profile PR. Issue #460 closes only after all listed adapters and generated schemas are merged.

Workspace JSON Schema

Publish a versioned JSON Schema for both user and project .allagents/workspace.yaml contexts:

• Runtime Zod validation remains authoritative.
• Generate the external schema from the authoritative input models.
• Commit the generated artifact and enforce a drift test.
• The project schema rejects profiles.
• The user schema includes strict profile/client/ref/settings definitions.
• Document stable versioned URLs and YAML language-server setup.

Dogfood requirement

Use an isolated disposable home and two disposable project directories so real user state cannot collide.

For the Compound Engineering OMP fixture:

1. Create ~/.allagents/workspace.yaml with the canonical profile declaration.
2. Install compound-engineering through allagents profile install.
3. Verify the marketplace and plugin were installed through OMP's native commands in the selected profile.
4. Launch omp-compound from a fresh shell and outside any project.
5. Verify argument, working-directory, signal, and exit-code pass-through.
6. Verify every Compound Engineering plugin skill loads in omp-compound and not in the default OMP profile. The native OMP fixture omits skills because OMP's native installer does not provide plugin-scoped skill filtering.
7. Create project A with a unique project skill and synchronize it.
8. Run both omp and omp-compound inside project A and verify both discover the project skill through normal OMP project discovery.
9. Run both launchers outside project A and verify the project skill is absent.
10. Create project B with a different project skill and verify there is no cross-project leakage.
11. Change the global profile declaration, run allagents update --profile compound-engineering, and verify targeted reconciliation and idempotence.
12. Verify project synchronization does not change profile ownership state and targeted profile update does not change project files.
13. Remove the profile explicitly and verify managed plugin state, marketplace registration, disposable profile state, and launchers are removed while both projects remain unchanged.

For the Pi fixture:

1. Create a second global profile using an isolated PI_CODING_AGENT_DIR and a disposable relative local Pi package fixture containing a uniquely named skill.
2. Install the package through Pi's native package lifecycle and verify the generated launcher selects the isolated Pi agent root without changing the working directory or suppressing Pi's normal project and shared .agents discovery.
3. Verify the profile skill loads through the Pi package and does not appear in the default Pi configuration.
4. Declare an MCP server without pi-mcp-adapter and verify planning fails before writing MCP configuration.
5. Declare npm:pi-mcp-adapter as a native Pi package in the same profile, install it before MCP configuration, launch a disposable stdio MCP server, and verify Pi can discover and invoke it.
6. Preinstall pi-mcp-adapter in another disposable Pi profile and verify AllAgents classifies it as referenced and preserves it on profile removal.
7. Synchronize a different skill into project .pi/skills and .agents/skills locations and verify default and profile launchers discover it only from that project.
8. Change the package declaration and run allagents update --profile <pi-profile> twice to verify targeted reconciliation and idempotence.
9. Remove the profile and verify its managed MCP adapter package, MCP configuration, package state, configuration root, and launcher are removed while referenced adapter packages, default Pi, and project state remain unchanged.

Each additional client adapter requires a recorded real-runtime dogfood run covering its profile/configuration mechanism and normal project discovery behavior before support is advertised.

Acceptance criteria

Schema and scope

• Only ~/.allagents/workspace.yaml accepts top-level profiles.
• Project workspace validation rejects profiles.
• Profile declarations use existing client, plugin, ref, skill-selection, and MCP vocabulary.
• Client-specific settings are strict and adapter-owned.
• Existing top-level user and project configuration remains backward compatible.
• No implicit default profile is introduced.

Lifecycle

• Explicit profile install, status, and remove commands are available.
• allagents update without profile filters reconciles every installed profile that still has a declaration.
• Repeated --profile filters reconcile only the selected installed profiles and skip top-level user and project resources.
• Targeted update rejects missing declarations, missing installations, --scope, and --client before mutation.
• Ordinary update does not create undeclared installations or remove declaration-missing profiles.
• Profile operations are idempotent and recover safely from partial failure.
• allagents profile update is not introduced as a second spelling for the same mutation.
• Profile lifecycle is independent of project lifecycle.

Materialization

• The declaration determines clients, launchers, plugins, refs, skill selection, MCP servers, and settings.
• Named installation does not prompt for composition already present in the declaration.
• Native installation never silently becomes file installation.
• Unsupported client capabilities fail before mutation.
• Generated machine paths and state remain outside workspace YAML.

Ownership and cleanup

• Adapters report concrete resource identities and whether AllAgents manages or references them.
• Removal invokes native cleanup where supported.
• Removal preserves pre-existing, referenced, modified, unrelated, shared, and uncorroborated resources.
• Deleting a declaration does not implicitly uninstall a profile.
• Profile state contains no project resources or secret values.

Launchers and project independence

• POSIX and Windows launchers preserve arbitrary arguments, working directory, and exit codes; POSIX launchers also preserve normal signal delivery through exec.
• Launchers do not inspect, synchronize, or mutate project workspaces.
• Launchers do not modify shell startup files.
• The default and named client launchers discover the same synchronized project-local core resources according to the client's native rules. Extension-backed capabilities require their prerequisite in each selected client profile; Pi MCP specifically requires pi-mcp-adapter.
• Project resources are never copied into profile state.

Verification

• The Compound Engineering OMP profile installs, updates, reports status, and removes end to end in an isolated environment.
• omp-compound works from a fresh shell and outside a project.
• Default OMP state remains unchanged.
• Project-specific skills are visible to both default and named OMP launchers only inside the corresponding project.
• Pi user/project .pi discovery, shared .agents/skills discovery, native package lifecycle, isolated profile root, and cleanup are verified with the real Pi runtime.
• Pi MCP validation fails before mutation when pi-mcp-adapter is absent, accepts a declared same-plan native installation, recognizes an existing profile-scoped installation as referenced, and preserves referenced installations on removal.
• Every supported adapter has recorded real-runtime verification.
• Generated JSON Schema is checked for drift from runtime validation.

Primary references

• AllAgents workspace schema
• AllAgents workspace sync command
• AllAgents plugin-stack workspace
• Paperclip agent portability
• Paperclip adapter capabilities
• OpenClaw Claw profiles and ownership lifecycle
• Pi settings
• Pi skills
• Pi packages
• Pi MCP adapter
• OMP configuration
• OMP MCP
• OMP marketplaces
• Compound Engineering OMP installation
• GitHub Copilot CLI configuration
• Codex configuration
• Claude Code settings
• OpenCode configuration