feat: create profile based on workspace

[christso]

Problem

Creating a reusable agent profile for a workspace currently requires imperative, user-specific setup. For example, setting up a Compound Engineering OMP profile requires:

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

This creates a shell function in ~/.bashrc:

omp-compound() {
    command omp --profile=compound-engineering "$@"
}

The OMP profile state is stored under:

~/.omp/profiles/compound-engineering/agent

The workspace declaration does not currently describe the named profile, generated launcher, native plugin installation, or enabled skills. Users must discover and run those setup steps separately.

Goal

Allow a project-scoped .allagents/workspace.yaml to declaratively define reusable, user-scoped agent profiles.

A user should be able to clone a workspace and explicitly install a declared profile:

allagents profile install compound-engineering

AllAgents should then install the declared client configuration, plugins, skills, MCP servers, instructions, and settings; generate the declared launcher; and record enough ownership state to update or remove the profile safely.

Profile composition comes from workspace.yaml. Installation must not ask the user to choose launchers, plugins, skills, or refs that should have been declared in the file. Interactive behavior is limited to selecting a profile when no name is supplied, approving user-global changes, and resolving collisions or trust decisions.

Terminology

• Workspace profile: a named declarative configuration under profiles in .allagents/workspace.yaml. It is not necessarily a native profile object in the client runtime.
• Client: a supported agent runtime configured inside a workspace or workspace 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 does not provide an appropriate native profile mechanism, such as COPILOT_HOME or CLAUDE_CONFIG_DIR.
• Configuration override: a client-specific configuration layer that may inherit global or project configuration rather than providing strict isolation, such as OpenCode's OPENCODE_CONFIG or OPENCODE_CONFIG_DIR.
• Launcher: the generated platform-native executable that selects the declared client profile/configuration and forwards arguments. It is not a POSIX shell alias.
• Ref: the requested source revision for a profile plugin, such as a Git tag, branch, or commit.
• Native installation: invoking the client's own plugin/package installation lifecycle in the selected native profile or configuration root. It is distinct from AllAgents file synchronization.

Use client in the public workspace schema. Do not introduce a separate target concept for profile clients.

Scope model

The declaration and installation have different scopes:

Project-owned .allagents/workspace.yaml
                  |
                  +-- top-level clients/plugins -> existing project/default sync
                  |
                  +-- profiles -> explicitly installed user-scoped client state

Requirements:

• profiles is valid in a project-scoped .allagents/workspace.yaml.
• Profiles are always installed into user/global native profiles or configuration roots; a profile is not a project-scoped installation target.
• Existing top-level clients and plugins retain their current project/default behavior.
• Ordinary project synchronization must not silently install, update, or remove user-scoped profiles.
• Profile lifecycle requires explicit commands such as profile install, profile update, and profile remove.
• Removing a profile declaration or switching branches must not implicitly delete an installed user profile.
• A profile declaration must not accept scope: project.
• Project-local configuration may still be discovered when a launcher runs from a project, according to the selected client's documented precedence. That does not change the profile's user scope.

Workspace schema

Profiles belong in the existing .allagents/workspace.yaml as a top-level section, not under the existing workspace: file-sync object and not in separate per-profile workspace files.

Illustrative shape:

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

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

Schema requirements:

• profiles is keyed by profile name.
• Each profile contains a clients array using the existing client vocabulary.
• A client entry expresses the client name, profile/configuration selection where needed, installation mode, launcher, and client-specific settings.
• Profile plugins use ref for requested source revisions.
• A plugin may restrict itself to selected clients in the same profile using clients.
• Existing skill selection applies to profile plugins: omitting skills enables all plugin-provided skills; an array is an allowlist; { exclude: [...] } is a blocklist.
• Profile-specific MCP servers, instructions, and settings are declared in the same profile.
• Machine-specific paths, resolved credentials, generated launcher paths, and installation state must not be committed to the workspace declaration.

Example with explicit skill selection:

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

    plugins:
      - source: EveryInc/compound-engineering-plugin
        ref: main
        install: native
        skills:
          - ce-plan
          - ce-work
          - ce-code-review

For native installation, the client installer owns plugin materialization and discovery. AllAgents must not separately copy native plugin skills. If a client cannot enforce a declared skill filter natively, installation must report the capability as unsupported rather than claim success.

Backward compatibility

Profile support must be additive:

• Existing top-level clients, plugins, and install modes retain their current meaning.
• Existing top-level plugin pin declarations remain accepted and unchanged.
• New profile plugin declarations use ref.
• Parsing may normalize legacy pin and profile-scoped ref to one internal requested-reference representation, but feat: create profile based on workspace #460 must not rename or remove the existing public pin field.
• Existing plugins[].clients continues to contain client names; it must not be reinterpreted as another identifier type.
• Profiles do not create or imply a default profile that replaces existing top-level declarations.

A future global pin to ref migration, if desired, is a separate versioned schema change.

Declarative installation behavior

Given:

allagents profile install compound-engineering

AllAgents must:

1. Read profiles.compound-engineering from the nearest .allagents/workspace.yaml.
2. Validate the complete profile before mutation.
3. Resolve each declared client's documented profile/configuration mechanism.
4. Resolve plugin source metadata and the requested ref.
5. Produce a concrete plan containing client commands, profile/configuration paths, launcher paths, plugin identities, skill selection, and MCP commands/endpoints.
6. Obtain approval before the first user-global mutation, unless an explicit non-interactive approval option was supplied.
7. Apply native or file installation exactly as declared.
8. Generate the platform-native launchers.
9. Persist ownership and resolved-revision state after successful operations.
10. Report created, updated, skipped, and failed resources per client.

If the command names the profile, composition must not be gathered interactively. Missing required declaration data is a validation error.

For native marketplaces, an adapter should resolve the installable plugin identity from authoritative marketplace metadata. If the declared source is ambiguous, validation must require an explicit client-native plugin identifier rather than guessing.

Compound Engineering OMP fixture

The canonical declaration is:

• workspace 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 must execute 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 generated POSIX launcher must behave equivalently to:

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

It must preserve arbitrary arguments and the OMP exit code. OMP's built-in --alias may be an explicitly requested compatibility mode, but it is not the default launcher implementation.

Native and file installation semantics

install: native must delegate to the selected client's installer and lifecycle. It must never silently fall back to file copying for a profile declaration.

The native operation owns marketplace registration, installed-plugin metadata, locks/runtime state, discovery, upgrade, and uninstall behavior. AllAgents records what it requested and what it owns, but does not emulate native installation by copying runtime files.

install: file means AllAgents-managed synchronization into the selected user profile or configuration root. Inside profiles, file installation remains user-scoped; it does not write to project client directories.

Linking is client-specific and should be supported only where the client exposes a real, documented link lifecycle. It is not a generic substitute for native.

Supported clients and adapter boundary

Support these clients through adapters:

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

Shared behavior includes workspace validation, profile selection, refs, skill filters, MCP declarations, launcher generation, approval, ownership tracking, reconciliation reporting, and secret references.

Each client adapter owns documented profile/configuration selection, file paths and precedence, native package commands, capability validation, MCP/settings serialization, reload behavior, and safe cleanup.

The implementation must use official documentation and inspect upstream source where behavior is not fully documented. Supported client versions and behavior must be pinned or tested.

Capability baseline

Client	Profile/configuration model
Pi	No named-profile command. PI_CODING_AGENT_DIR can select a separate agent directory. Pi core does not provide MCP.
OMP	First-class --profile <name> / OMP_PROFILE; native user state is stored under ~/.omp/profiles/<name>/agent.
OpenCode	No native profile flag. OPENCODE_CONFIG and OPENCODE_CONFIG_DIR provide additional configuration layers and may inherit global/project configuration; report this as a configuration override, not a native profile or strict isolation.
GitHub Copilot CLI	No named-profile command. COPILOT_HOME selects a user configuration root.
Codex CLI	codex --profile <name> selects a configuration overlay. CODEX_HOME is separate state-root selection and must not be confused with the profile overlay; native plugin scope must follow documented Codex behavior.
Claude Code	No named-profile command. CLAUDE_CONFIG_DIR selects a configuration directory for settings, history, and plugins.

A profile enables only capabilities supported by each client adapter. Unsupported declared capabilities must produce actionable validation errors.

Pi boundary

Pi core does not provide MCP. Its supported MCP path is the external pi-mcp-adapter, installed as a Pi package and configured through the adapter's documented files.

Adding Pi extension support and automatic pi-mcp-adapter installation/configuration is deferred to a later PR. Current profile work defines the adapter capability boundary but must reject those Pi capabilities as unsupported until the follow-up lands. AllAgents must not extend or fork Pi to add MCP.

Trust and secret handling

A committed project file can request user-global native installation and MCP configuration. Before mutation, AllAgents must show the resolved plan, including:

• client and profile/configuration mechanism;
• native commands;
• plugin/package source and resolved revision;
• launcher destination;
• local MCP commands or remote MCP endpoints;
• names, but never values, of requested secrets.

Secrets must be referenced through environment variables or an existing credential store. Resolved values must not be written to workspace YAML, generated launchers, AllAgents state, logs, errors, or command arguments. If a client cannot consume a secret reference without persisting plaintext, the adapter must report the capability as unsupported.

Non-interactive installation requires an explicit approval option. Merely cloning, opening, initializing, or ordinarily syncing a project must not install user-global profile resources.

Cross-platform launchers

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

Launcher names must be safe command basenames. Creation must refuse path traversal, symlink destinations, or unrelated existing files. Setup must check whether the launcher directory is on PATH and print exact remediation without modifying .bashrc, .zshrc, PowerShell profiles, or equivalent startup files.

Reconciliation and cleanup

Profile installation state is user-local and may outlive the project checkout. An installed profile must not depend on the original project directory unless the declaration explicitly references project resources and reports that dependency.

A repeat profile install or profile update must be idempotent and reconcile the selected declaration. Persist successful ownership state incrementally so an interrupted installation can resume safely.

profile remove must:

1. show the planned removals;
2. use native uninstall/remove commands where available;
3. remove only registrations, files, configuration roots, and launchers recorded as AllAgents-owned and still matching the recorded identity;
4. preserve pre-existing, modified, unrelated, shared, or credential-store resources;
5. stop relevant test/runtime processes before deleting a disposable root;
6. report unsupported or failed cleanup operations without claiming success.

Deleting a declaration from workspace.yaml does not authorize global removal.

Workspace JSON Schema

Publish a versioned JSON Schema for .allagents/workspace.yaml, including profile/client/ref fields and client-specific configuration.

Generate the schema from the authoritative Zod input model, commit the generated artifact, and enforce a drift test. Document a stable versioned URL and YAML-language-server/editor setup. Runtime Zod validation remains authoritative.

OMP support and delivery order

AllAgents currently does not support omp as a client. Deliver the work in this order:

1. Add omp to the supported client schema and implement ordinary OMP file/native installation support in a linked PR.
2. Add the profile schema, explicit lifecycle commands, user-scope enforcement, adapter context, ownership state, and launcher support.
3. Complete the Compound Engineering OMP profile fixture end to end.
4. Add and verify profile behavior for the remaining clients through their adapters.
5. Publish the generated external schema after the profile input shape is settled.

The OMP work must include focused schema, command, reconciliation, trust, cleanup, and launcher tests and document OMP-specific paths and reload behavior.

Dogfood requirement

Dogfood the same explicit profile-install flow a user will run. For the Compound Engineering OMP fixture:

1. use an isolated disposable home/config environment so the exact compound-engineering and omp-compound names cannot collide with real user state;
2. install the profile from .allagents/workspace.yaml;
3. install the Compound Engineering plugin through OMP's native commands;
4. launch omp-compound from a fresh shell and from outside the declaring workspace;
5. verify argument and exit-code pass-through;
6. verify the Compound Engineering plugin and skills are loaded;
7. verify the default OMP profile remains unchanged;
8. change the declaration and verify reconciliation/idempotence;
9. stop all processes and run the explicit profile removal flow;
10. verify the plugin, marketplace registration, disposable profile state, and launcher are removed.

Each additional client adapter needs at least one recorded real-runtime dogfood run before it is marked supported. Runs may occur on separate CI or manual hosts; support must not depend solely on whether a client happened to be installed on one development machine.

Acceptance criteria

Schema and compatibility

• .allagents/workspace.yaml can declare profiles keyed by profile name.
• Profiles contain clients; no separate public target taxonomy is introduced.
• Profile plugins use ref.
• Existing top-level clients, plugins, pin, and project/default synchronization remain backward compatible.
• Profiles are top-level and do not create an implicit default profile.
• A generated, versioned workspace JSON Schema is published and checked for drift from runtime validation.

Scope and lifecycle

• Profiles declared by a project are installed only into user/global client profiles or configuration roots.
• Profile declarations reject scope: project.
• Ordinary project sync does not silently apply or remove profiles.
• Explicit install, update, status, and remove operations are available.
• Removing a declaration does not implicitly uninstall an installed profile.
• Re-running install/update is idempotent and recovers safely from partial failure.

Composition

• The declaration determines clients, profile/configuration selection, launchers, plugins/packages, refs, skill selection, MCP servers, instructions, and settings.
• Named profile installation does not prompt for composition already required in the declaration.
• Unsupported client capabilities fail with actionable errors.
• Pi extensions and MCP remain unsupported until their linked follow-up.

Installation and ownership

• install: native uses the selected client's native installer and never silently becomes file copy.
• install: file inside a profile writes only to the selected user profile/configuration root.
• Adapters report and track the resources AllAgents owns.
• Cleanup uses native removal where available and preserves unrelated or pre-existing user state.

Launchers and security

• POSIX and Windows launchers forward arbitrary arguments and exit codes.
• Launcher creation does not mutate shell startup files.
• PATH problems are reported with actionable instructions.
• User-global mutations require an explicit command and approval.
• Secrets remain references and are never persisted in generated artifacts or diagnostic output.

Verification

• The Compound Engineering OMP profile is installed and removed end to end in an isolated disposable environment.
• Its generated omp-compound launcher works from a fresh shell and outside the declaring workspace.
• The native plugin and its skills are verified as loaded.
• Every supported client adapter has a recorded real-runtime verification before being marked supported.

Primary references

• AllAgents workspace schema
• AllAgents plugin-stack example
• Pi settings, skills, extensions, and packages
• OMP configuration, MCP, and marketplaces
• GitHub Copilot CLI configuration, skills, MCP, and plugins
• Codex configuration, skills, MCP, and plugins
• Claude Code settings, skills, plugins, and MCP
• OpenCode configuration, CLI, plugins, skills, and MCP
• Compound Engineering OMP installation