refactor(install): prefer native plugin install across targets (#609)

Co-authored-by: John Cavanaugh <cavanaug@users.noreply.github.com>

docs/specs/gemini.md

@@ -1,6 +1,6 @@
-# Gemini CLI Spec (GEMINI.md, Commands, Skills, MCP, Settings)
+# Gemini CLI Spec (GEMINI.md, Commands, Skills, Subagents, Extensions)
 
-Last verified: 2026-02-14
+Last verified: 2026-04-18
 
 ## Primary sources
 
@@ -10,7 +10,9 @@ https://geminicli.com/docs/get-started/configuration/
 https://geminicli.com/docs/cli/custom-commands/
 https://geminicli.com/docs/cli/skills/
 https://geminicli.com/docs/cli/creating-skills/
-https://geminicli.com/docs/extensions/writing-extensions/
+https://geminicli.com/docs/core/subagents/
+https://geminicli.com/docs/extensions/reference/
+https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/
 https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html
 ```
 
@@ -53,7 +55,10 @@ User request: {{args}}
 ## Skills (SKILL.md standard)
 
 - A skill is a folder containing `SKILL.md` plus optional supporting files.
-- Skills live in `.gemini/skills/`.
+- Workspace skills live in `.gemini/skills/` or the `.agents/skills/` alias.
+- User skills live in `~/.gemini/skills/` or the `~/.agents/skills/` alias.
+- Extension skills live in an installed extension's `skills/` directory.
+- Compound Engineering managed Gemini installs should use Gemini-owned roots (`~/.gemini/skills`, `~/.gemini/agents`, `~/.gemini/commands`) rather than `~/.agents/skills`, because `~/.agents/skills` can shadow Copilot plugin skills.
 - `SKILL.md` uses YAML frontmatter with `name` and `description` fields.
 - Gemini activates skills on demand via `activate_skill` tool based on description matching.
 - The `description` field is critical — Gemini uses it to decide when to activate the skill.
@@ -71,6 +76,34 @@ description: Review code for security vulnerabilities and OWASP compliance
 Detailed instructions for security review...
 ```
 
+## Subagents
+
+- Gemini CLI supports custom subagents as Markdown files with YAML frontmatter.
+- Project subagents live in `.gemini/agents/*.md`.
+- User subagents live in `~/.gemini/agents/*.md`.
+- Extension subagents live in an installed extension's `agents/*.md` directory.
+- Current Gemini docs, `/agents reload` command text, and Gemini CLI 0.38.2 implementation name only `.gemini/agents` and `~/.gemini/agents` for local subagent discovery. The `.agents/skills` and `~/.agents/skills` aliases apply to skills; Gemini does not currently read `~/.agents/agents` or `.agents/agents` as subagent discovery paths.
+- Subagents can be invoked explicitly with `@agent-name` or selected automatically by description.
+- Subagents run in isolated context loops and can have restricted tool access.
+- Subagents cannot call other subagents, even if granted wildcard tool access.
+
+Example:
+
+```yaml
+---
+name: security-auditor
+description: Specialized in finding security vulnerabilities in code.
+kind: local
+tools:
+  - read_file
+  - grep_search
+model: inherit
+max_turns: 10
+---
+
+You are a ruthless Security Auditor.
+```
+
 ## MCP server configuration
 
 - MCP servers are configured in `settings.json` under the `mcpServers` key.
@@ -103,8 +136,147 @@ Detailed instructions for security review...
 ## Extensions
 
 - Extensions are distributable packages for Gemini CLI.
-- They extend functionality with custom tools, hooks, and commands.
-- Not used for plugin conversion (different purpose from Claude Code plugins).
+- Install with `gemini extensions install <github-url-or-local-path>`.
+- Unlike `gemini skills install`, current Gemini extension docs and local `gemini extensions install --help` output do not list a `--path` flag for installing an extension from a monorepo subdirectory.
+- Remote extension installs are not local-only. Gemini supports Git repository distribution and GitHub Releases.
+- For public gallery discovery and normal remote install, `gemini-extension.json` must be at the absolute root of the GitHub repository or release archive.
+- Gemini CLI copies installed extensions under `~/.gemini/extensions`.
+- `gemini extensions link <path>` creates a symlink for local development instead of copying the extension.
+- Extension management commands run from the shell, not inside Gemini's interactive mode. Restart the Gemini session after install/update for commands and extension changes to take effect.
+- Extensions can bundle commands, skills, subagents, hooks, MCP servers, context files, policies, settings, and themes.
+- Every extension root must contain `gemini-extension.json`.
+- Extension commands live in `commands/*.toml`.
+- Extension skills live in `skills/<name>/SKILL.md`.
+- Extension subagents live in `agents/*.md`.
+- For Compound Engineering, native extension packaging is now the likely primary Gemini distribution path because it can preserve commands, skills, and subagents. Direct `.gemini/` writes should be treated as a legacy/custom install path unless retained for local development.
+- Because this repo is a monorepo with the plugin under `plugins/compound-engineering/`, public Gemini extension distribution likely needs a generated extension-root source, a dedicated extension repo, or a distribution branch whose root is the Gemini extension root.
+- Interim CE distribution should keep using the Bun installer, but change the writer to install into `~/.gemini/{skills,agents,commands}` with a manifest under `~/.gemini/compound-engineering`.
+
+### Extension root shape
+
+A distributable Gemini extension source should look like:
+
+```text
+gemini-extension.json
+GEMINI.md                    # optional context file
+skills/<skill-name>/SKILL.md
+commands/<command>.toml
+agents/<agent-name>.md
+hooks/hooks.json             # optional
+policies/*.toml              # optional
+package.json                 # optional, if the extension has runtime code
+```
+
+Minimal manifest:
+
+```json
+{
+  "name": "compound-engineering",
+  "version": "1.0.0",
+  "description": "Compound Engineering workflows for Gemini CLI",
+  "contextFileName": "GEMINI.md"
+}
+```
+
+Relevant manifest fields:
+
+- `name`: Required. Local CLI validation allows letters, numbers, and dashes; docs recommend lowercase numbers/dashes and expect the extension directory name to match.
+- `version`: Required. Validation warns if it is not standard semver.
+- `description`: Optional but used by the public gallery.
+- `contextFileName`: Optional. Defaults to `GEMINI.md` when present.
+- `mcpServers`: Optional. Loaded like user `settings.json` MCP servers, except `trust` is ignored for extension MCP config.
+- `settings`: Optional install-time/user configuration prompts; values are stored in extension `.env` or keychain for sensitive values.
+- `excludeTools`, `migratedTo`, `plan`, `themes`: Optional target-specific behavior.
+
+### Install commands
+
+Install from a GitHub repository whose root is the extension root:
+
+```bash
+gemini extensions install https://github.com/EveryInc/compound-engineering-gemini
+```
+
+Install from a branch, tag, or commit:
+
+```bash
+gemini extensions install https://github.com/EveryInc/compound-engineering-gemini --ref stable
+```
+
+Install from a local extension root:
+
+```bash
+gemini extensions install ./dist/gemini-extension
+```
+
+Link a local extension root for development:
+
+```bash
+gemini extensions link ./dist/gemini-extension
+```
+
+Validate a local extension root:
+
+```bash
+gemini extensions validate ./dist/gemini-extension
+```
+
+Uninstall:
+
+```bash
+gemini extensions uninstall compound-engineering
+```
+
+### Release options
+
+Gemini supports two remote release shapes:
+
+1. **Git repository:** Users install the repository URL. The repository root must contain `gemini-extension.json`.
+2. **GitHub Releases:** Users still install the repository URL. Gemini can use the latest release archive or a release tag via `--ref`; custom archives must be self-contained with `gemini-extension.json` at the archive root.
+
+The public Gemini extension gallery indexes public GitHub repositories with the `gemini-cli-extension` topic when `gemini-extension.json` is at the repository or release archive root.
+
+### Compound Engineering packaging implications
+
+The current `plugins/compound-engineering/` source root is not currently a valid Gemini extension root because it lacks `gemini-extension.json`:
+
+```bash
+gemini extensions validate plugins/compound-engineering
+# Configuration file not found at .../plugins/compound-engineering/gemini-extension.json
+```
+
+Adding only that manifest would make the root validate, but it would not be enough for correct agent packaging:
+
+- CE agents currently live in nested category directories such as `agents/review/correctness-reviewer.md`.
+- Gemini's local loader in `@google/gemini-cli` 0.38.2 reads only direct `*.md` files under the extension `agents/` directory.
+- Gemini agent frontmatter is strict. CE's Claude-authored agent frontmatter can include Claude-only fields such as `color`, and some files use Claude string-form `tools: Read, Grep, Glob, Bash`; Gemini expects `tools` to be an array of valid Gemini tool names.
+
+Therefore a proper CE Gemini extension should be generated or normalized, not just the Claude plugin root plus a manifest. This does not mean rewriting agent prompts into bespoke Gemini-only instructions. The agent bodies and most `name`/`description`/`model` frontmatter can usually pass through. The generated extension should:
+
+- Copy pass-through `skills/<skill>/SKILL.md` directories that are not excluded for Gemini.
+- Convert Claude agents into flat Gemini-compatible subagents under `agents/<agent-name>.md`.
+- Strip or translate Claude-only frontmatter fields.
+- Convert Claude tool names to Gemini tool names, or omit tools when there is no reliable mapping.
+- Generate Gemini `commands/*.toml` only if CE ships source commands again.
+- Include a `gemini-extension.json` at the generated extension root.
+- Use `gemini extensions validate <generated-root>` in tests.
+
+The same normalization is needed for the interim Bun installer, except the output root is `~/.gemini` instead of an extension root:
+
+```text
+~/.gemini/skills/<skill-name>/SKILL.md
+~/.gemini/agents/<agent-name>.md
+~/.gemini/commands/*.toml
+~/.gemini/compound-engineering/install-manifest.json
+```
+
+Local smoke test on 2026-04-18 with Gemini CLI 0.38.2:
+
+- A direct extension agent using CE/Claude-style `tools: Read, Grep, Glob, Bash` plus `color: blue` failed to load with Gemini validation errors: `tools: Expected array, received string` and `Unrecognized key(s) in object: 'color'`.
+- A nested extension agent under `agents/review/nested-agent.md` produced no validation error because the loader only scans direct files under `agents/`; it was not discovered.
+
+Do not place CE agents in `~/.agents/agents` as a shared cross-harness agent root. Gemini does not currently read it, and if Gemini adds that alias later, Claude/Copilot-shaped frontmatter could become a compatibility problem. For Gemini, use either a native extension with normalized `agents/*.md` files or a legacy/custom install under `~/.gemini/agents` with cleanup.
+
+If the same Gemini agent name exists in multiple Gemini-read locations, Gemini registers user agents first, project agents next, and extension agents last. Later registrations override earlier ones by name. This avoids duplicate visible agent tools, but stale CE files in `~/.gemini/agents` can still emit validation errors or mask behavior when an extension is disabled, so cleanup remains necessary.
 
 ## Settings.json structure