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
- Author
- zhixuan312 ↗
- Repository
- multi-model-agent ↗
- Licence
- MIT
- Last repository change
- 29.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.08.2026, without references to retired models or APIs.
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
- Overview
- When to Use
- Dispatch
- Session Reuse
- Response shapes
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
| Repository | Score | Licence |
|---|---|---|
| This page · zhixuan312/multi-model-agent | 100 | MIT |
| kriegcloud/beep-effect | 100 | Apache-2.0 |
| zahidakhyar/skills | 100 | MIT |
| jkaloger/lazyspec | 100 | MIT |
| superset-sh/superset | 100 | MIT |
| boshu2/agentops | 100 | Apache-2.0 |
| Ovich/charrette | 100 | MIT |
| matthew-eth724/orchestrate | 100 | MIT |
| nickthelegend/nick-skills | 100 | MIT |
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…