Add extensible agent harnesses

[lcavadas]

Summary

• replace the hard-coded default-agent list with a declarative harness registry
• keep all built-in harnesses (including AFK) in Omarchy's shipped registry
• let ordinary Omarchy plugins expose an optional agentHarness block, so omarchy plugin add is the only installation path for third-party integrations
• populate Setup > Defaults > Agent dynamically from built-in harnesses and installed plugin metadata
• allow a harness-only integration to use kinds: [] and entryPoints: {}—no dummy QML service is required
• preserve current terminal/browser launch behavior while constraining third-party harnesses to mise installation and argv-only {project} / {prompt} templates
• prevent metadata-only plugins from being enabled, reconcile the selected default when its integration is removed or changes, and reject malformed or conflicting harness identities

Why

Agent harnesses should be an extension point within the existing plugin lifecycle—not a separate plugin category or installer. Built-in harnesses, including AFK, remain shipped by Omarchy and are always available in the Agent defaults menu; selecting an uninstalled harness installs it. A single third-party integration repository can ship a harness plus optional bar/panel/service UI, installed, updated, and removed through the normal plugin commands.

A harness-only integration is available as soon as its plugin is installed. It has no Quickshell component to enable, and its successful install output directs the user to choose it as their default. Plugins that do include UI retain normal enable/disable behavior independently from their harness metadata.

This removes the scalability problem: ordinary harnesses no longer need core changes to default-agent switches, menu JSON, migrations, and launch behavior. Third-party manifests permit only mise installation and argv templates with {project} / {prompt} substitutions; arbitrary install hooks and unknown placeholders are rejected. IDs and aliases use the same safe identity rules, and new installs/updates reject collisions; any pre-existing conflict is resolved deterministically with a warning.

Lifecycle and safety

• omarchy plugin add <git-url> validates and installs the integration.
• omarchy plugin update [id] validates updates and rolls back rejected changes.
• omarchy plugin remove [id] removes the integration and clears it as the default when necessary.
• Metadata-only plugins are never enabled as shell plugins.
• Third-party installers cannot run arbitrary shell hooks; only declarative, non-option mise packages are accepted.

Documentation

• manual/17-ai.md distinguishes built-in selectable harnesses from pre-wired CLI stubs and documents plugin installation and selection.
• docs/agent-harnesses.md documents the manifest schema, metadata-only lifecycle, collision handling, and security constraints.
• default/agents/skills/omarchy/plugins.md and agents/skills/shell-dev.md document contributor/agent guidance.

Verification

• git diff --check
• shell syntax checks for changed commands and tests
• jq empty default/agents/harnesses.json
• bash test/shell.d/agent-harness-test.sh
• bash test/shell.d/agent-harness-launch-test.sh
• bash test/shell.d/plugin-add-test.sh
• bash test/shell.d/plugin-harness-lifecycle-test.sh
• bash test/shell.d/plugin-enable-test.sh
• bash test/shell.d/plugin-registry-contract-test.sh
• bash test/shell.d/default-agent-test.sh
• bash test/shell.d/menu-test.sh
• ./test/cli

Generated with AFK

[lcavadas]

A brief clarification on scope and relationship to the companion PRs: this is the general extensible harness architecture. It moves harness registration and lifecycle handling into declarative plugin metadata while keeping the built-in harnesses, including AFK, available and preserving the existing launch behavior. PR #10079 is the narrower AFK-specific integration and may be reviewed as the concrete predecessor/alternative; if this general architecture is preferred, the AFK PR can be rebased or reduced to the parts that should remain first-party. PR #10092 is separate and provides the marketplace discovery UI. Focused validation and the security/lifecycle constraints are documented above.