Skip to content
Skills Library
AI & agents · Tool integration

orchestrate

/orchestrate

Use when a frontend workflow needs a high-quality LLM brain for orchestration — send a structured prompt, get a structured response, reuse the session across workflow phases

Licence
MIT
Last repository change
29.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a frontend workflow needs a high-quality LLM brain for orchestration — send a structured prompt, get a structured response, reuse the session across workflow phases

Original author description

Use when a frontend workflow needs a high-quality LLM brain for orchestration — send a structured prompt, get a structured response, reuse the session across workflow phases

How it works

  1. Overview
  2. When to Use
  3. Dispatch
  4. Session Reuse
  5. Response shapes
Original SKILL.md headings · 220 lines, 1,523 words
SKILL.md preview
---
name: orchestrate
description: Use when a frontend workflow needs a high-quality LLM brain for orchestration — send a structured prompt, get a structured response, reuse the session across workflow phases
when_to_use: A multi-phase workflow (explore → spec → plan → execute) needs an intelligent orchestrator that maintains session context across phases. Each call sends a self-contained prompt; the agent processes it and returns structured output the calling system parses directly.
version: "0.0.0-unreleased"
---

# mma:orchestrate

## Overview

The orchestrate endpoint provides a session-persistent, high-quality LLM agent for multi-phase workflow orchestration. Unlike worker routes (audit, delegate, review), the orchestrate agent has no reviewer, no commit, and no findings structure — it takes a prompt and returns the output the caller needs.

**Core principle:** The frontend owns the workflow state; MMA provides the LLM continuity. Each prompt is self-contained; session reuse provides project context across phases.

## When to Use

**Use when:**
- A multi-step workflow needs an intelligent brain across phases
- The calling system constructs structured prompts and expects structured responses
- Session continuity across workflow phases improves output quality
- The task requires synthesis, analysis, or decision-making — not file writing

**Don't use when:**
- You need file modifications → use `mma:delegate`
- You need structured code review → use `mma:review`
- You need document auditing → use `mma:audit`
- A single API call suffices — orchestrate is for when you need tool use + reasoning

## Dispatch

Call the `mma_run` MCP tool with `cwd` and this `request` body. If the `mma_run` MCP tool is not
available in this session, run `mma clients`.

```json
{
  "cwd": "/project",
  "request": {
    "type": "orchestrate",
    "prompt": "Synthesize the exploration results into a requirements specification...",
    "outputFormat": "json"
  }
}
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `type` | `"orchestrate"` | yes | Discriminator |
| `prompt` | string | yes | The full instruction for this workflow phase |
| `outputFormat` | string | no | Hint for desired output format (e.g. `"json"`, `"markdown"`) |
| `sessionIds` | object | no | `{ implementer: "<session-id>" }` — reuse a prior session |
| `contextBlockIds` | string[] | no | IDs from `mma:context-blocks` (max 2) |

> Worker tier defaults to `main` — the model driving mma. `agents.main` is required in the config and the daemon refuses to start without it, so there is no substitution to another tier. Send `agentTier` to run on `standard` or `complex` instead. Review is always skipped — there is no reviewer phase.

## Session Reuse

To maintain context across workflow phases, capture the session ID from the first response and pass it back:

```json
// Phase 1: Exploration
{ "cwd": "/project", "request": { "type": "orchestrate", "prompt": "Explore the codebase for auth patterns..." } }
// -> read execution.sessions.implementer from the terminal envelope as sessionId

// Phase 2: Specification (reuse session)
{ "cwd": "/project", "request": { "type": "orchestrate", "prompt": "Based on your exploration, write a spec...", "sessionIds": { "implementer": "<sessionId from phase 1>" } } }
```

## Response shapes

### mma_run — dispatch

Short tasks return the terminal envelope (below) inline, in the tool result. Longer-running
tasks return a handle instead:

```json
{ "executionId": "<uuid>", "type": "<route>", "cwd": "<abs path>" }
```

Use `executionId` to poll with `mma_execution_get`, block with `mma_execution_wait`, or stop the
work with `mma_execution_cancel`.

### A long dispatch outlives your turn; your polling does not

The execution runs in the mma daemon, not in your session. It keeps going regardless of what your
side is doing, and its terminal envelope is persisted — `mma_execution_get` returns it later even
after a daemon restart. **Nothing is lost if you stop watching.**

What stops is your polling. `mma_execution_wait` blocks for at most its timeout and then returns a
running snapshot; "call again" only happens while your turn is active. Your client is never told
that an mma execution finished — the execution belongs to the daemon, not to your client's own task
tracking — so no notification will arrive to bring you back.

For work that outlasts a turn, hand the waiting to something your client DOES track. If it can run
a command as a tracked background job, wrap the poll in one: a job that blocks until the execution
is terminal and whose exit your client notices. Completion then re-enters your session instead of
depending on you still being mid-turn. Without that, a long dispatch looks stalled while it is in
fact running — and the result is sitting in the store whenever you next ask for it.

### mma_execution_get / mma_execution_wait — poll

A still-running execution returns identity plus progress (`status: "running"`, `phase`,
`elapsedMs`, `runningHeadline`, …) — not the shape below. A terminal execution returns the
full envelope — these 5 top-level fields:

```json
{
  "execution": {
    "executionId": "<uuid>",
    "type": "<route>",
    "subtype": "<subtype or absent>",
    "status": "done | done_with_concerns | failed | cancelled | interrupted",
    "sessions": { "implementer": "<session-id>", "reviewer": "<session-id or null>" },
    "worktree": null,
    "dirtyAtDispatch": false
  },
  "output": {
    "summary": { /* refiner JSON — shape varies by route, see below */ },
    "filesChanged": ["src/foo.ts", "src/bar.ts"],
    "contextBlockId": "<string or null>",
    "reviewerNote": null
  },
  "metrics": {
    "totalDurationMs": 12400,
    "totalCostUsd": 0.08,
    "implementer": { "durationMs": 8000, "costUsd": 0.05, "usage": { "inputTokens": 1200, "outputTokens": 800, "cachedReadTokens": 0, "cachedNonReadTokens": 0 } },
    "reviewer":     { "durationMs": 4000, "costUsd": 0.03, "usage": { "inputTokens": 900, "outputTokens": 400, "cachedReadTokens": 0, "cachedNonReadTokens": 0 } }
  },
  "raw": {
    "implementer": "<raw text output>",
    "reviewer": "<raw text output or null>"
  },
  "error": null
}
```

`execution` is the ONE merged top-level section — there is no separate `task` section. It
carries the execution's own identity (`executionId`, `type`, `status`) alongside what used to
live in a distinct `execution` block (`sessions`, `worktree`, `dirtyAtDispatch`). `subtype`
(audit's criteria set) is optional — read it defensively.

### How to read the envelope

**Step 1 — check `error`:**

| Shape | Meaning |
|---|---|
| `error` is `null` | Task succeeded — read `output` |
| `error` is `{ "code": "...", "message": "..." }` | Task failed — read `error.code` + `error.message` |

`interrupted` is the fifth terminal status: boot reconciliation writes it when a daemon restart
orthaned a running execution. It carries a non-null `error` with a retryable reason
(`daemon_restarted`), so Step 1 still reads correctly — but a consumer switching on only the other
four hits an unhandled state after any restart.

**Step 2 — extract the result from `output.summary`:**

`output.summary` is the **parsed JSON** from the refiner (reviewer). Its internal shape varies by route — see the per-skill "Reading the output" section for the exact fields. Common patterns:

| Route family | What `output.summary` contains |
|---|---|
| Read routes (audit, review, investigate, debug, research) | `{ findings: [...], criteriaCovered: [...], ... }` — findings array is the main payload |
| Write routes (delegate, execute_plan) | `{ status: 'done'\|'failed', notes }` or `{ tasks: [...], notes }` |
| Spec / Plan | `{ specPath, sections, acceptanceCriteriaCount, notes }` or `{ planPath, taskCount, tasks, notes }` |
| Journal recall | `{ answer, criteriaCovered, findings: [{ weight, category, claim, evidence, topic, fallback, nodeId, nodePath }] }` |
| Journal record | `{ recorded: [...], failed: [...] }` |

**Step 3 — for read routes, extract findings:**

```
response.output.summary.findings   ← the findings array
response.output.summary.findings[i].weight      ← "critical" | "high" | "medium" | "low"
response.output.summary.findings[i].category
response.output.summary.findings[i].claim       ← one-sentence summary
response.output.summary.findings[i].evidence    ← grounding text
response.output.summary.findings[i].suggestion  ← fix recommendation (some routes omit this)
```

**Step 4 — for write routes, read files changed:**

```
response.output.filesChanged       ← array of relative paths modified by the worker
response.output.contextBlockId     ← non-null for READ-ONLY types (audit/review/debug/investigate/
                                     research/journal_recall); null for spec and plan too, which
                                     read but are cwd-only (reusable in contextBlockIds)
```

**Step 5 — check `output.reviewerNote` (reviewer availability):**

`output.reviewerNote` is `null` on the normal path. When the reviewer ran but its output
couldn't be parsed, the task degrades to `status: "done_with_concerns"` with **`error: null`**
(a reviewer format flake is a concern, not a failure), and `output.summary` falls back to the
**implementer's** answer. `reviewerNote` then carries the reason:

```json
"reviewerNote": { "code": "reviewer_unavailable", "message": "<why the parse failed>" }
```

Treat a non-null `reviewerNote` as advisory: the answer in `output.summary` is the un-refined
implementer output, still usable. Never discard the task on `reviewerNote` alone.

### Common extraction mistakes

❌ **Reading `output.findings`** — this field does NOT exist. Findings are inside `output.summary.findings`.

❌ **Reading `results` or `structuredReport`** — these are legacy field names from older API versions. The current envelope uses `output.summary`.

❌ **Treating `output.summary` as a string** — it is parsed JSON (an object), not a string. If it looks like a string, the underlying output could not be parsed at all — check `output.reviewerNote` and, as a last resort, `raw.implementer`.

❌ **Ignoring `error: null` check** — a `status: "done_with_concerns"` task has `error: null` and is a success (advisory concerns only). Only `error !== null` is a failure. In particular, when a reviewer emits non-JSON, the task is `done_with_concerns` with `error: null`, `output.summary` holds the implementer answer, and `output.reviewerNote` explains the degrade — do NOT treat this as a failure.

### Tool call error

A malformed or unresolvable call (bad `cwd`, unknown `executionId`, failed admission) surfaces as an
MCP tool error rather than a terminal envelope — the tool result carries `isError: true` and this
payload:

```json
{ "error": { "code": "<code>", "message": "<human-readable>" } }
```

This is a different signal than Step 1 above: it means the call itself could not be admitted or
resolved, not that a dispatched task ran and failed. A dispatched task's failure always shows up
in the terminal envelope's `error` field instead.

Versions

RepositoryScoreLicence
This page · zhixuan312/multi-model-agent100MIT
kriegcloud/beep-effect100Apache-2.0
zahidakhyar/skills100MIT
jkaloger/lazyspec100MIT
superset-sh/superset100MIT
boshu2/agentops100Apache-2.0
Ovich/charrette100MIT
matthew-eth724/orchestrate100MIT
nickthelegend/nick-skills100MIT

Database snapshot: 13.11.2026 · package version 1e691d228974 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100mma-orchestrate
    Use when a frontend workflow needs a high-quality LLM brain for orchestration — send a structured prompt, get a structured response, reuse the session across workflow phases
  • 100add-workflow
    TRIGGER when user asks to define a workflow graph, create an agent or agentic workflow, orchestrate tasks, or build a multi-step process. "Agent", "agentic workflow", and "workflow" are interchangeable here - an LLM is not required for a workflow to be an agent (rule-based,…
  • 100plan-orchestrate
    读取计划文档,将其分解为步骤,从 ECC 目录中为每个步骤设计智能体链,并生成可直接粘贴的 /orchestrate 自定义提示。仅生成 —— 从不调用 /orchestrate 本身。当用户有多个步骤的计划并希望通过 orchestrate 驱动而无需手动组合链时使用。
  • 100llm-application-dev-prompt-optimize
    Evaluate and improve LLM prompts using examples, structured instructions, and measured comparisons. Use when refining prompt reliability, output quality, or model-specific behavior.
  • 100codex-workflow
    Run deterministic multi-step agent workflows in Codex - fan-out, parallel, schema-validated structured output - via the codex-workflow MCP orchestrator (run_workflow), with native in-chat fallbacks. Use when you want Claude-Code-Workflow-style orchestration in Codex: 'run a…
  • 95brain-prompt
    Metaprompting assistant — "/brain-prompt <rough idea>" turns a rough ask into "the right prompt": a complete, tuned master prompt with SPARC phases, per-phase rubrics, standing rules, and cost guardrails, ready to paste or run. Use when the user says "/brain-prompt", "brain…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.