---
name: external-agents
description: >
  Controls whether external CLI agents (Codex, Gemini) are used for testing,
  validation, and debugging tasks during this session. Use when the user says
  "use Codex for testing", "delegate validation to Gemini", "turn off external
  agents", "let Claude decide on external agents", or asks to configure which
  tasks should be outsourced to external models.
user-invocable: true
---

# GMD External Agents Skill

You manage the `.claude/external-agents.json` control file to configure whether
Codex CLI or Gemini CLI are used as external reviewers for testing, validation,
and debugging tasks in this session.

## Control file location

`.claude/external-agents.json` in the project root (or `CLAUDE_PROJECT_DIR`).

## Schema

```json
{
  "enabled": true | false,
  "default_agent": "codex" | "gemini",
  "mode": "auto" | "always" | "off",
  "block_on_risk": true | false,
  "tasks": {
    "testing":            { "enabled": true | false, "agent": "codex" | "gemini" | null },
    "validation":         { "enabled": true | false, "agent": "codex" | "gemini" | null },
    "debugging":          { "enabled": true | false, "agent": "codex" | "gemini" | null },
    "pre_run_validation": { "enabled": true | false, "agent": "codex" | "gemini" | null }
  }
}
```

## Field meanings

- `enabled` -- master switch. false = hooks read the file but do nothing.
- `default_agent` -- fallback agent used when a task's `agent` field is null. Must be installed: `codex --version` or `gemini --version`.
- `mode` -- informational only (hooks use task flags, not mode). Reserved for future use.
- `block_on_risk` -- if true, the PreToolUse hook can block a test/build command
  when the external agent detects critical issues. Default false (safer).
- `tasks.*.enabled` -- whether this task type is active.
- `tasks.*.agent` -- agent override for this specific task. null means inherit `default_agent`.
- `tasks.testing` -- PostToolUse: after file writes, ask the agent for missing tests.
- `tasks.validation` -- PostToolUse: after file writes, ask the agent for validation issues.
- `tasks.debugging` -- PostToolUse: after file writes, ask the agent for debug risks.
- `tasks.pre_run_validation` -- PreToolUse: before test/build commands, ask the agent
  for pre-run risk assessment. More intrusive -- only enable when needed.

## Your behavior when this skill is invoked

1. Parse the user's intent from `$ARGUMENTS` or from the conversation context.
2. Read the current control file. If missing, seed it from `~/.claude/templates/external-agents.json` (NEW object schema; all tasks `{enabled:false, agent:null}`; `default_agent:"codex"`). If the existing file uses the old boolean task format (e.g. `"testing": true`), migrate each task in-place to `{ "enabled": <value>, "agent": null }` before applying changes.
3. Update only the fields the user specified. When updating a task, preserve sibling keys — changing `tasks.testing.agent` must not wipe `tasks.testing.enabled`, and vice versa.
4. Write the updated JSON back to `.claude/external-agents.json`.
5. Confirm what changed in one sentence.

## "status" intent — surface the full wiring picture

When the user types `status`, `what is the current config?`, or asks "is cross-model on?", show ALL THREE layers of state, because cross-model has multiple gates and any one disabled silently mutes the feature:

1. **GMD config gate** (`config.components.crossmodel.enabled`). Read via `node ~/.claude/get-magic-done/bin/lib/config.js` or by parsing `~/.claude/get-magic-done/config.json`. If `false`, ALL three external-agent hooks early-exit before reading `.claude/external-agents.json`.
2. **Project control file** (`.claude/external-agents.json`). Read and report `enabled`, `default_agent`, and each task's `{enabled, agent}`. If file is missing, say so explicitly — that means validate/test hooks silently no-op even if GMD's crossmodel gate is on.
3. **Hook wiring** in `~/.claude/settings.json`. Confirm the three hooks are present:
   - `gmd-codex-review-hook.js` under PostToolUse with `matcher: "Write|Edit"` (Bug 1 fix; ungated firing on every tool call indicates an unpatched install)
   - `gmd-external-validate-hook.js` under PreToolUse with `matcher: "Bash"`
   - `gmd-external-test-hook.js` under PostToolUse with `matcher: "Write|Edit"`

Report concisely. Example:
```
Cross-model status:
  GMD gate (crossmodel.enabled):  ON
  Project file:                    .claude/external-agents.json present, enabled=true
    testing:            enabled, agent=codex
    validation:         disabled
    debugging:          disabled
    pre_run_validation: disabled
  Hook wiring (~/.claude/settings.json): 3/3 wired
```

## Example intents and the changes to make

| User says | Changes |
|-----------|---------|
| "use Codex for testing" | enabled=true, default_agent=codex, tasks.testing={enabled:true, agent:codex} |
| "use Gemini for validation and debugging" | enabled=true, tasks.validation={enabled:true, agent:gemini}, tasks.debugging={enabled:true, agent:gemini} |
| "enable all tasks with Codex" | enabled=true, default_agent=codex, all tasks={enabled:true, agent:codex} |
| "use Codex for testing and Gemini for validation" | enabled=true, tasks.testing={enabled:true, agent:codex}, tasks.validation={enabled:true, agent:gemini} |
| "use Gemini for everything except testing, use Codex for that" | enabled=true, default_agent=gemini, tasks.testing={enabled:true, agent:codex}, all other tasks agent=gemini |
| "switch validation to Codex" | tasks.validation.agent=codex (preserve tasks.validation.enabled) |
| "turn off external agents" | enabled=false (preserve all other fields) |
| "disable pre-run checks" | tasks.pre_run_validation.enabled=false |
| "let Claude decide" | enabled=true, mode=auto (Claude uses judgment on each file) |
| "block on risk" | block_on_risk=true |
| "what is the current config?" | Read and display the current file contents clearly |
| "status" | Same as above |

## Autonomous use (Claude decides)

If the user has not specified and asks Claude to decide, use this judgment:
- Enable testing + validation for any session involving new feature work
- Enable debugging for sessions involving bug fixes or refactors
- Keep pre_run_validation off unless the user is on a fragile codebase or has
  had repeated test failures in the current session
- Assign agents per task type: prefer Codex for code-only tasks (testing, debugging);
  prefer Gemini for tasks that benefit from reviewing docs, configs, or mixed assets (validation)
- Set `default_agent` to whichever agent covers the majority of enabled tasks

## Checking agent availability

Before enabling, collect the distinct set of agents referenced across `default_agent` and all `tasks.*.agent` values, then verify each is installed:
- Codex: run `codex --version` via Bash tool
- Gemini: run `gemini --version` via Bash tool

If any required agent is not installed, tell the user which one is missing and do not enable tasks that depend on it.

## Important constraints

- Never set block_on_risk=true without the user explicitly requesting it.
- The pre_run_validation task is more intrusive (it fires before commands run).
  Recommend the user test it on a small session before leaving it always on.
- These settings persist for the project directory. Remind the user they can
  run `/gmd:external-agents off` to disable when switching to a context where
  external agent latency would be disruptive.
