Coordinate Agents

---
name: coordinate-agents
description: Route requests that explicitly use Coordinate Agents or operate on its existing Tasks to setup, execution, review, or recovery skills.
---

# Coordinate Agents

Use this router for Coordinate Agents workflows. Ordinary repository edits do
not require this workflow or an external Implementer.

| Intent | Focused skill |
| --- | --- |
| Discover or configure implementation agents | `coordinate-setup` |
| Create, run, inspect, or stop a Task or Task Graph | `coordinate-task` |
| Review a Task implementation or integrated graph | `coordinate-review` |
| Diagnose and resume a failed or stale Task | `coordinate-recover` |

Load only the skill needed for the requested operation. For an active workflow,
use the configured Planner/Implementer/Reviewer roles; the formal Reviewer is
read-only. Resolve the project root from repository context before dispatch and
use Runtime validation of the configured executable, rather than guessing from
its role label.

## Invocation and boundaries

Use structured Coordinate Agents MCP tools. The Task API is the user-facing
surface; Agent Bus is the canonical durable transport. Do not make the user
manage queues or PTY endpoints, create a second Bus, or hand-edit queue files.

Only when MCP is unavailable or debugging is requested, let `<skill-dir>` be the
absolute directory containing this file and use:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" <command> ...
```

The fallback resolves the active payload to `bin/coordinate-agents.mjs`. Do not
silently retry a failed mutation through another transport. Runtime errors stop
the current activation; inspect facts before an authorized recovery. Classify
`AUTH_REQUIRED` only from an explicit authentication failure.

An explicit tool call is not a new user approval gate. Continue the authorized
workflow through relevant verification and review; reuse authorization within
its stated scope. Review approval alone does not authorize release. The exact
`RELEASE_APPROVED` token belongs only to the Coordinate Agents release protocol.

## Read only when needed

- Task Graph operations: [graph workflow](../coordinate-task/references/task-graph.md).
- Session diagnostics: [session runtime](references/session-runtime.md).
  Sessions own persistent PTYs; Tasks only reference `sessionId`. Never control
  unrelated processes or automate the Codex App Terminal UI.
- Adapter authoring or registration: [adapter workflow](references/adapter-workflow.md).
- Bus protocol debugging or the Task release protocol: [protocol](references/protocol.md).
- A specification needing a workflow template: [task templates](references/task-templates.md).

---
name: coordinate-recover
description: >-
  Diagnose and safely resume Coordinate Agents Tasks after executable failure,
  non-zero exit, timeout, stale claim, processing message, or Implementer
  ERROR. Recovery is explicit and never an automatic retry loop.
---

# Coordinate Recover

Use `coordinate_agents_recover_inspect`,
`coordinate_agents_task_status`, and `coordinate_agents_task_resume` for
single-Task recovery. For a Task Graph, use
`coordinate_agents_task_graph_recover`, `coordinate_agents_task_graph_resume`,
`coordinate_agents_task_graph_stop`, and
`coordinate_agents_task_graph_cleanup`. Recovery is facts-first and never an
automatic retry.
If MCP is unavailable, or the user explicitly requests debugging, let
`<skill-dir>` be the absolute directory containing this loaded `SKILL.md` and
use the bundled fallback:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" ...
```

The normal Plugin path starts with `coordinate_agents_recover_inspect`, followed
by `coordinate_agents_task_status` or `coordinate_agents_task_resume` only when
the recovery decision requires them. The following commands are fallback/debug
syntax only:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task status --root "<repository>" --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" status --root "<repository>" --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" agent doctor --root "<repository>" --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task graph-recover --root "<repository>" --id task-... --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task graph-resume --root "<repository>" --id task-... --subtask <subtaskId> --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task graph-stop --root "<repository>" --id task-... --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task graph-cleanup --root "<repository>" --id task-... --json
```

Inspect the Task's `lastError`, the bounded runtime artifact, Agent Bus state,
the `sessionId` Session status/inspect facts, and any matching commit or
evidence. Explain the concrete error code and the smallest repair. Session
inspection is read-only: do not restart, replay input, attach to a different
PID, or resume the Task while collecting facts. Do not claim a missing
capability as a successful result.

When the user has explicitly authorized repair and continuation, invoke:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task resume --root "<repository>" --id task-... --json
```

`task resume` only clears the explicit recovery gate; it does not launch an
Implementer. The same authorization covers the in-scope repair, resume, and
subsequent `task dispatch`; do not ask twice. If the proposed repair exceeds
that authorization, explain the concrete repair and request only the missing
decision. Dispatch performs executable validation, Bus handoff, launch, and
state/error propagation as one operation. If that activation fails, inspect the
new facts and report the blocker instead of automatically repeating recovery.

For graph recovery, `task graph-recover` inspects durable Session, worktree,
commit, and evidence records and records an interrupted `FAILED` subtask only
when no healthy Session or verified completion exists. It never infers success
from filenames or prose. `task graph-resume` is a separate explicit decision:
it reuses a verified healthy Runtime-owned Session/worktree, or returns an
exited/failed Session to `READY` for a later explicit graph dispatch. Failed
prerequisites keep dependents `BLOCKED` until this valid recovery path runs.
Use `task graph-stop` to mark active graph work `STOPPED` and close only
Runtime-owned Sessions, followed by `task graph-cleanup` when needed. Both
operations use bounded, ownership-checked cleanup and preserve user worktrees,
branches, refs, commits, and evidence; repeated recovery/resume/stop/cleanup
calls are idempotent.

`TASK_NOT_FOUND`, `STALE_CLAIM`, `AGENT_EXIT_NONZERO`, `AGENT_TIMEOUT`, and
`AUTH_REQUIRED` remain facts to report; they do not authorize silent retries.

---
name: coordinate-review
description: >-
  Review a Coordinate Agents implementation as the Codex Reviewer. Verify the
  real commit, diff, tests, validation evidence, and specification without
  modifying the Implementer's product code.
---

# Coordinate Review

Use `coordinate_agents_task_inspect` and
`coordinate_agents_task_review` for normal Plugin review operations. The
Plugin bundles the Runtime and does not require a global `coordinate-agents`
command. If MCP is unavailable, or the user explicitly requests debugging,
let `<skill-dir>` be the absolute directory containing this loaded `SKILL.md`:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" ...
```

Review only observable evidence tied to the current Task and repository:

1. Read `coordinate_agents_task_inspect` and the approved specification.
2. Verify the implementation commit exists and inspect its diff.
3. Check validation evidence for the current commit. Re-run relevant tests when
   evidence is missing, stale, from a different environment, or leaves a concrete
   doubt; independently verify high-risk changes when warranted.
4. Compare every acceptance criterion and negative control.
5. Return exactly one decision: `REVIEW_APPROVED` or `CHANGES_REQUESTED`.
6. Record that decision through the MCP Task API; never edit a task JSON file
or manually send a Bus message. Only when MCP is unavailable, or for explicit
debugging, use this fallback syntax:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task review \
  --root "<repository>" --id task-... --decision REVIEW_APPROVED --json
```

For changes, include concrete feedback. The Runtime preserves it and the next
explicit `task dispatch` includes it in the new `IMPLEMENT` activation. In an
implementation workflow, the coordinator continues authorized rework without
asking again; a review-only request ends after the recorded review. When
the recorded Session is healthy, that activation reuses the same
`ExecutionSession`; review feedback is written into the existing PTY context.
Do not use Codex App Terminal UI automation to reach the Implementer.

The Reviewer does not edit product source, tests, or build configuration. It
does not merge, tag, push, publish, or pass the human release gate.

---
name: coordinate-setup
description: >-
  Discover or configure implementation agents for Coordinate Agents when
  setting up or changing its agent configuration.
---

# Coordinate Setup

Use this skill for first-run onboarding. Use the Coordinate Agents MCP tools
for normal setup operations; do not generate a shell command for the user.
The Plugin bundles the Runtime, but `coordinate-agents` is not guaranteed to be
on `PATH`.

Normal MCP operations:

```text
coordinate_agents_setup_discover
coordinate_agents_setup_configure
```

Only if MCP is unavailable, or if the user explicitly requests debugging, let
`<skill-dir>` be the absolute directory containing this loaded `SKILL.md` and
use the bundled fallback. The following shell syntax is not the normal Plugin
path:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" ...
```

For the normal Plugin path, call `coordinate_agents_setup_discover` with
`{ "root": "<repository>" }` before changing configuration. The equivalent
fallback/debug invocation is:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" setup --root "<repository>" --json
```

It checks `codex`, `claude`, `agy`, `agy-proxy`, and `gemini` by resolving the
actual executable. It reports unavailable commands and distinguishes
`detected-but-not-configured` agents. Detection never writes configuration.
The response also includes the additive `adapters` registry snapshot with each
registered identity, Contract version, capabilities, and configured Agent
facts. A trusted external adapter is represented without launching it; when an
external Agent is already configured, discovery uses only that adapter's
Contract-defined `detect()` operation for availability facts.

When the user chooses an agent, inspect its native help and perform one
high-level setup transaction through `coordinate_agents_setup_configure`. It
writes the machine-specific executable to
`~/.coordinate-agents/config.json`, registers/updates the project Agent,
assigns the workflow role, checks executable availability, and returns READY
facts. Do not manually compose `config set`, `agent add`, workflow editing,
and doctor calls:

An explicitly registered external adapter can be selected with its exact
identity through the same operation. The returned `adapters` snapshot is
additive and keeps Agent identity, Adapter identity, and executable identity
separate. An unavailable or incompatible adapter fails before either the user
configuration or project workflow transaction is committed, and the Runtime
rolls back any partial setup changes.

Fallback/debug syntax only:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" setup configure \
  --agent antigravity --command agy-proxy --adapter antigravity-cli \
  --role implementer --root "<repository>" --json
```

For a generic CLI, pass an explicit argument template containing `{prompt}`
after checking that CLI's own `--help`; otherwise Runtime returns
`UNSUPPORTED_CAPABILITY` rather than claiming that executable detection means
adapter compatibility:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" setup configure \
  --agent claude --command claude --adapter generic-cli \
  --args '["--print","{prompt}"]' --role implementer \
  --root "<repository>" --json
```

User configuration is stored outside the plugin at
`~/.coordinate-agents/config.json` (Windows: `C:\Users\<username>\.coordinate-agents\config.json`).
An explicit project command in `.agent-bus/config.json` takes precedence over
the user file. Setup configure does not write the selected machine path to
project config unless a project override already exists; it refuses to replace
an existing explicit project command. Agent identity, Adapter, and executable
remain separate, so `antigravity` may use `agy-proxy` without falling back to
`agy`.

The selected command is also the persistent Session executable. The Runtime
uses structured argument arrays, bounded PTY I/O, and only the configured
project root; it does not control a Codex App terminal panel or another
desktop window.

---
name: coordinate-task
description: >-
  Create, execute, inspect, or stop Coordinate Agents Tasks when requested,
  or continue an existing Coordinate Agents Task.
---

# Coordinate Task

Use this skill when the user asks Coordinate Agents to implement a feature
or fix a bug. Use MCP tools for the normal workflow and do not make the user construct shell commands:

```text
coordinate_agents_task_create
coordinate_agents_task_dispatch
coordinate_agents_task_status
coordinate_agents_task_inspect
coordinate_agents_task_review
coordinate_agents_task_resume
coordinate_agents_task_stop
```

Only if MCP is unavailable, or if the user explicitly requests debugging, let
`<skill-dir>` be the absolute directory containing this `SKILL.md` and use
the bundled fallback. The following shell syntax is fallback/debug only, not
the normal Plugin path:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" ...
```

Create a Task only for new work; inspect and continue the existing Task otherwise.
For standalone Runtime compatibility or explicit
debugging, use the fallback syntax below; never expose Agent Bus `send`, `wait`,
or `state` operations to the user:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task create --root "<repository>" --title "<task>" --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task dispatch --root "<repository>" --id task-... --spec "<approved specification>" --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task status --root "<repository>" --id task-... --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task inspect --root "<repository>" --id task-... --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task resume --root "<repository>" --id task-... --json
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task stop --root "<repository>" --id task-... --reason "<reason>" --json
```

Task records are persisted under the project-local Agent Bus and contain the
Planner, Implementer, Reviewer, round, specification, commit, evidence,
timestamps, status, last error, and a non-owning `sessionId` reference. The
normal path is:

```text
CREATED/PLANNING -> SPEC_READY -> IMPLEMENTING -> WAITING_IMPLEMENTER
-> REVIEWING -> APPROVED
```

`task dispatch` is the Plugin-facing workflow operation. It validates the
state and approved specification, resolves the workflow Implementer and its
effective command, checks the executable, sends `IMPLEMENT`, then opens or
reuses one healthy persistent Execution Session. The Task stores the returned
`sessionId` but does not own the process. If the adapter did not consume the
initial prompt as launch arguments, dispatch writes it to the Session. A
durable `IMPLEMENTATION_DONE` message maps the Task to `REVIEWING`, including
`implementationCommit` and evidence; otherwise a bounded activation remains
observable as `WAITING_IMPLEMENTER`.

Review feedback may enter `CHANGES_REQUESTED`. A failed activation enters
`ERROR`; follow `coordinate-recover` before another dispatch. Existing explicit
authorization to repair and continue covers resume and the subsequent dispatch
within that scope.
`CHANGES_REQUESTED` is dispatched explicitly with the preserved feedback,
current round, and previous commit/evidence reference. A healthy matching
Session is reused for this rework; an exited/failed Session is replaced only
by that explicit dispatch. Use `task review` for
the Runtime decision operation:

```text
node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" task review \
  --root "<repository>" --id task-... --decision CHANGES_REQUESTED \
  --feedback "<concrete review findings>" --json
```

`REVIEW_APPROVED` changes Task status to `APPROVED`; it never authorizes
merge, push, tag, publish, deploy, or any other release action.

## Completion and authorization

For an implementation request, continue through implementation, relevant
validation, review, and in-scope rework until the acceptance criteria pass.
For inspect, stop, or review-only requests, complete only that operation.
An approved specification means it is within the user's authorized scope;
resolve material ambiguity without imposing a separate approval for routine details.

“Explicit dispatch” means a deliberate coordinator tool call, not a fresh user
confirmation. A bounded graph call ending at integration or review is a tool
boundary: the coordinator continues with the appropriate authorized operation.
Use bounded calls and inspect current state while work is running; do not
redispatch running work or poll unchanged state tightly. Stop for a new material
decision, recovery outside existing authorization, or an unauthorized release.
If repeated rework makes no progress, report the concrete blocker rather than loop.

For dependency-aware Tasks, read [Task Graph workflow](references/task-graph.md).
For Session diagnostics, read [Session runtime](../coordinate-agents/references/session-runtime.md).