@enderfga/claw-orchestrator 7.5.2 → 7.5.4

package/skills/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "hand off", "handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent", "coding session", "session inbox", "grok", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "how much did it cost", "token usage", "spend cap", "budget limit", "maxBudgetUsd", "workflow", "durable workflow", "resume a run", "verify", "verification", "acceptance contract", "evidence", "evidence bundle", "did the tests actually pass", "prove it works", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify".
+description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify".
 metadata:
   {
     'openclaw':
       {
         'emoji': '🤖',
-        'requires': { 'anyBins': ['claude', 'codex', 'agy', 'agent'] },
+        'requires': { 'anyBins': ['claude', 'codex', 'agy', 'grok', 'opencode'] },
         'install':
           [
             {
@@ -60,7 +60,7 @@ session_start({
   name: 'opencode-task',
   cwd: '/path/to/project',
   engine: 'opencode',
-  model: 'anthropic/claude-sonnet-4',
+  model: 'anthropic/claude-sonnet-5',
 });
 
 // 2. Send messages
@@ -78,14 +78,14 @@ session_stop({ name: 'myproject' });
 
 | Parameter        | Description                                                                                                     |
 | ---------------- | --------------------------------------------------------------------------------------------------------------- |
-| `engine`         | `claude` (default), `codex`, `agy`, `cursor`, `opencode`                                                        |
-| `model`          | Model name or alias (`fable`, `opus`, `sonnet`, `haiku`, `gpt-5.5`, `agy-pro`, `composer-2`)                    |
+| `engine`         | `claude` (default), `codex`, `agy`, `grok`, `opencode`, `custom`                                                |
+| `model`          | Model name or alias (`fable`, `opus` → claude-opus-5-5, `sonnet`, `haiku`, `gpt-5.5`, `agy-pro`)                |
 | `permissionMode` | `acceptEdits`, `auto`, `plan`, `bypassPermissions`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
 | `effort`         | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` (each engine clamps to its own ceiling)                |
 | `maxBudgetUsd`   | Cost limit in USD                                                                                               |
 | `allowedTools`   | List of allowed tool names                                                                                      |
 
-### CLI 2.1.111 options
+### Claude-engine options
 
 | Parameter                                         | Description                                                                                                                             |
 | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
@@ -98,17 +98,12 @@ session_stop({ name: 'myproject' });
 | `debug` / `debugFile`                             | Targeted debug output by category (e.g. `"api,mcp"`) and optional file path.                                                            |
 | `fromPr`                                          | Resume a session linked to a GitHub PR number or URL.                                                                                   |
 | `channels` / `dangerouslyLoadDevelopmentChannels` | MCP channel subscriptions (research preview).                                                                                           |
+| `forkSubagent`                                    | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`).                                                        |
+| `enableToolSearch`                                | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`).                                                                             |
+| `otelLogUserPrompts`                              | OpenTelemetry: include user prompts in logs (sets `OTEL_LOG_USER_PROMPTS=1`).                                                           |
+| `otelLogRawApiBodies`                             | OpenTelemetry: include raw API bodies in logs (sets `OTEL_LOG_RAW_API_BODIES=1`). Debug only.                                           |
 
-### CLI 2.1.121 options
-
-| Parameter             | Description                                                                                   |
-| --------------------- | --------------------------------------------------------------------------------------------- |
-| `forkSubagent`        | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`).              |
-| `enableToolSearch`    | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`).                                   |
-| `otelLogUserPrompts`  | OpenTelemetry: include user prompts in logs (sets `OTEL_LOG_USER_PROMPTS=1`).                 |
-| `otelLogRawApiBodies` | OpenTelemetry: include raw API bodies in logs (sets `OTEL_LOG_RAW_API_BODIES=1`). Debug only. |
-
-`stats.pluginErrors` is now populated from the `system/init` event when CLI plugins fail to load due to unmet dependencies.
+`stats.pluginErrors` lists CLI plugins that failed to load (from the `system/init` event).
 
 `TRACEPARENT` / `TRACESTATE` (W3C distributed tracing) are automatically forwarded from parent process env — set them before starting the session and they propagate to the child Claude CLI.
 
@@ -158,7 +153,7 @@ team_send({ name: 'myproject', teammate: 'teammate', message: 'Review this' });
 ## Ultraplan & Ultrareview
 
 - **Ultraplan**: Opus deep planning session (up to 30 min), produces detailed implementation plan
-- **Ultrareview**: Fleet of 5-20 bug-hunting agents reviewing in parallel (security, logic, perf, types, etc.)
+- **Ultrareview**: 1-20 read-only reviewer agents (default 5) running in parallel, each from one angle (security, logic, perf, types, etc.), merged by a synthesis pass
 
 Both are async — start then poll status.
 
@@ -186,17 +181,20 @@ For the full control protocol, registry/resume behavior, and ledger layout, see
 
 ## Tools Overview
 
-| Category          | Tools                                                                                                                                                 |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session Lifecycle | `session_start`, `session_send`, `session_handoff`, `session_stop`, `session_list`, `sessions_overview`                                               |
-| Session Ops       | `coding_session_status`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model`                                            |
-| Inbox             | `session_send_to`, `session_inbox`, `session_deliver_inbox`                                                                                           |
-| Teams             | `coding_agents_list`, `team_list`, `team_send`                                                                                                        |
-| Codex             | `codex_resume`, `codex_review`, `codex_goal_*`, `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_thread_list` |
-| Claude CLI        | `claude_goal_*`, `claude_agents_list`, `plugin_details`                                                                                               |
-| Fan-out           | `fanout_start`, `fanout_status`, `fanout_abort`                                                                                                       |
-| Council           | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject`                            |
-| Ultra             | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status`                                                                      |
+| Category          | Tools                                                                                                                                                                                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Session Lifecycle | `session_start`, `session_send`, `session_handoff`, `session_stop`, `session_list`, `sessions_overview`                                                                                                                                                                                                      |
+| Session Ops       | `coding_session_status`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model`, `project_purge`                                                                                                                                                                                  |
+| Inbox             | `session_send_to`, `session_inbox`, `session_deliver_inbox`                                                                                                                                                                                                                                                  |
+| Teams             | `coding_agents_list`, `team_list`, `team_send`                                                                                                                                                                                                                                                               |
+| Codex             | `codex_resume`, `codex_review`, `codex_goal_*`, `codex_interrupt`, `codex_steer`, `codex_fork`, `codex_rollback`, `codex_models`, `codex_thread_list`                                                                                                                                                        |
+| Claude CLI        | `claude_goal_*`, `claude_agents_list`, `plugin_details`                                                                                                                                                                                                                                                      |
+| Fan-out           | `fanout_start`, `fanout_status`, `fanout_abort`                                                                                                                                                                                                                                                              |
+| Council           | `council_start`, `council_status`, `council_abort`, `council_inject`, `council_review`, `council_accept`, `council_reject`                                                                                                                                                                                   |
+| Ultra             | `ultraplan_start`, `ultraplan_status`, `ultrareview_start`, `ultrareview_status`                                                                                                                                                                                                                             |
+| Autoloop          | `autoloop_start`, `autoloop_chat`, `autoloop_status`, `autoloop_list`, `autoloop_stop`, `autoloop_reset_agent`                                                                                                                                                                                               |
+| Workflow & verify | `workflow_start`, `workflow_status`, `workflow_list`, `workflow_resume`, `workflow_cancel`, `workflow_steer`, `workflow_approve`, `verify_run`                                                                                                                                                               |
+| Ultraapp          | `ultraapp_new`, `ultraapp_answer`, `ultraapp_add_file`, `ultraapp_spec_edit`, `ultraapp_build_start`, `ultraapp_build_cancel`, `ultraapp_status`, `ultraapp_get`, `ultraapp_list`, `ultraapp_feedback`, `ultraapp_promote_version`, `ultraapp_start_container`, `ultraapp_stop_container`, `ultraapp_delete` |
 
 `ultracode` (Claude dynamic workflows) is a `session_start` option, not a separate tool: set
 `ultracode: true` to have Claude orchestrate a JS workflow and fan out to subagents per task.
@@ -208,15 +206,16 @@ For full parameter reference: see [references/tools.md](references/tools.md)
 `clawo acp` (or the `clawo-acp` binary) serves Agent Client Protocol over stdio, so any ACP
 client — Zed, JetBrains, Neovim, Emacs, the VS Code ACP extension, or `dsh` through its
 `subagent-acp` provider — drives the orchestrator as its coding agent. The model selector is
-grouped by engine, so one dropdown spans Claude, Codex and Cursor and switching it switches
-engine mid-session.
+grouped by engine, so one dropdown spans Claude, Codex, Antigravity and Grok, and switching it
+switches engine mid-session.
 
 For setup, the dsh YAML block, and the cancellation/permission limits: see [references/acp.md](references/acp.md)
 
 ## Durable workflows
 
 `workflow_start` runs a declarative graph of `agent` / `fanout` / `council` / `verifier` /
-`human_gate` / `router` / `subflow` nodes. Every state transition is checkpointed to
+`human_gate` / `router` / `subflow` / `autoloop` / `ultraapp_synth` /
+`ultraapp_deploy` nodes. Every state transition is checkpointed to
 `~/.claw-orchestrator/wf/<runId>/`, so a run survives a process restart and `workflow_resume`
 picks it up at the node boundary — nodes already succeeded are not re-run, and the one that
 was in flight is retried because a half-finished node left no result to trust.
@@ -254,7 +253,7 @@ survives restarts, so it answers "what did we run today and what did it cost" af
 sessions are gone.
 
 `maxBudgetUsd` on a session (or per council / fanout agent) is enforced by the runtime, so it
-holds on Codex, Cursor, agy, OpenCode and custom engines too — not just Claude Code. Once
+holds on Codex, agy, Grok, OpenCode and custom engines too — not just Claude Code. Once
 cumulative spend reaches the cap, further sends are refused before the engine is spawned.
 
 Rows carry two different judgements and keep them apart: `ok` is the engine's terminal verdict

package/skills/references/acp.md

@@ -5,15 +5,19 @@ drives over JSON-RPC stdio. Zed, JetBrains IDEs, Neovim, Emacs and the VS Code A
 extension are clients; so is `dsh`, whose `@deepseek-ai/dsh-subagent-acp` provider
 spawns an arbitrary command as a subagent.
 
-Every other agent in the ACP ecosystem is a single agent. This one is a fleet: the
-model selector spans engines, and the session-mode picker is where orchestration
-shapes are chosen.
+The model selector spans several engines, and session modes select the
+orchestration shape: a single agent, a council, a planning pass, or a review.
 
 ```bash
 clawo acp          # or the dedicated binary:
 clawo-acp
+# without a global install:
+npx -y @enderfga/claw-orchestrator acp
 ```
 
+Requires Node ≥ 22 and at least one engine CLI (`claude`, `codex`, `agy`,
+`grok`) installed and logged in.
+
 Both read the protocol from stdin and write it to stdout. **Stdout carries nothing
 but protocol frames** — all logging goes to stderr.
 
@@ -94,13 +98,16 @@ cancelling one abandons the poll rather than stopping the work.
 
 `session/new` also returns a `category: "model"` config option whose values are
 **grouped by engine**, built from the shared registry in `src/models.ts`. One
-dropdown holds Claude, Codex and Grok models at once. Changing it restarts the
-underlying session on the new engine; the ACP session id is unaffected.
+dropdown holds four engine groups at once: Claude Code, Codex, Antigravity and
+Grok Build. Changing it restarts the underlying session on the new engine; the
+ACP session id is unaffected.
 
-Two engines are absent for different reasons:
+Other engines are absent for different reasons:
 
 - **`gemini`** — the Gemini CLI is sunset and superseded by Antigravity. It still
   works for callers that name it directly; it is not offered in a new picker.
+- **`cursor`** — a legacy engine, superseded by Grok Build in this lineup. Same
+  treatment: callers that name it still work.
 - **`opencode`** — its models are open-ended `provider/model` strings passed
   straight through, so there is nothing in the registry to enumerate. An opencode
   session is reachable by naming the model, just not by picking it from this list.
@@ -129,8 +136,7 @@ fresh engine thread.
 The session layer has **no mid-turn cancel** — `stopSession()` is the only lever and
 it destroys the session rather than pausing the turn. So the ACP turn returns
 promptly while the engine subprocess may take a moment longer to die, and any
-partial work in that turn is lost. This is a real limitation, not a detail of the
-current implementation.
+partial work in that turn is lost.
 
 ## Use from `dsh`
 
@@ -152,11 +158,11 @@ ignores tool calls and other updates — and runs a fresh subprocess per run wit
 parent context. The adapter therefore keeps the text stream self-sufficient: an
 engine that never streams still gets its whole answer emitted as one final chunk.
 
-## Verifying a change
+## Development notes
 
 Unit tests cover the translation helpers and the config-option shapes
-(`src/__tests__/acp-server.test.ts`). They cannot catch the failure this protocol
-actually dies of, so also drive the real binary:
+(`src/__tests__/acp-server.test.ts`). They cannot catch a corrupted frame
+stream, so also drive the real binary:
 
 ```bash
 npm run build
@@ -167,29 +173,6 @@ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocol
 Then run a full session and assert **every stdout line parses as JSON**. A single
 stray `console.log` anywhere in the process corrupts the frame stream, and the
 client fails in a way that looks like a protocol bug. Two things prevent it, and
-doing only one is the trap: suppress the embedded HTTP server (whose `start()`
-prints), and hand `SessionManager` an explicit stderr logger — its default
+both are required: suppress the embedded HTTP server (whose `start()` prints),
+and hand `SessionManager` an explicit stderr logger — its default
 `createConsoleLogger` writes `info`/`debug` to stdout.
-
-Verified end to end against the real binary:
-
-- handshake, `session/new` (4 engine groups in the selector), a streamed `single`-mode
-  turn that read a workspace file under `plan` permission and relayed the answer;
-- the mode slash commands: a bare `/ultraplan` switches and reports, `/single <task>`
-  switches back and runs the task in one turn;
-- a cross-engine model switch (`claude-sonnet-4-6` → `gpt-5.5`) answered by Codex;
-- a full `council` run in a git repo — two engines, two rounds to consensus, emitting
-  2 `plan`, 4 `tool_call`, 4 `tool_call_update`, the synthesis as text, and the two
-  gate commands;
-- `usage_update` carrying cross-engine cost;
-- graceful exit on stdin EOF.
-
-Every stdout line parsed as JSON throughout. `/council_accept` and `/council_reject`
-are covered by unit tests against a fake manager but have not been exercised against a
-live parked council.
-
-It was also driven from **VS Code with the ACP Client extension 0.2.0** — the agent
-appears in the agents list beside Copilot, Claude Code and Codex CLI, connects, renders
-the grouped model dropdown and the permission selector, and answered a prompt about a
-workspace file with its tool calls shown as collapsible entries. That run is what
-established that this client does not render modes.