@zhixuan92/multi-model-agent 5.1.0 → 5.2.1

package/dist/skills/mma-context-blocks/SKILL.md

@@ -12,7 +12,7 @@ when_to_use: >-
   Register once here, then pass the ID via `contextBlockIds` on mma-delegate /
   mma-execute-plan / mma-audit / mma-review / mma-debug / mma-investigate.
   Cheaper and faster than inlining the same content N times.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-context-blocks
@@ -56,7 +56,7 @@ Store large documents once; reference them by ID in subsequent `mma-*` calls via
 | Field | Type | Required | Notes |
 |---|---|---|---|
 | `content` | string | yes | Document content (min 1 char, max 50 MiB) |
-| `ttlMs` | number | no | Time-to-live in ms; omit for idle-expiry (default 24 h idle). A block that is not referenced by any active batch for 24 h is eligible for eviction. |
+| `ttlMs` | number | no | Time-to-live in ms; omit for idle-expiry (default 24 h idle). A block that is not referenced by any active task for 24 h is eligible for eviction. |
 
 #### Response (201)
 
@@ -70,7 +70,7 @@ Use this `id` as a `contextBlockIds` entry in any `mma-*` skill that supports it
 
 `DELETE /context-blocks/:id?cwd=<abs-path>`
 
-Returns `200 { ok: true }` on success. Returns `409 pinned` if the block is held by one or more active batches — wait for those batches to complete before deleting.
+Returns `200 { ok: true }` on success. Returns `409 pinned` if the block is held by one or more active tasks — wait for those tasks to complete before deleting.
 
 ## Full example
 
@@ -90,11 +90,11 @@ curl -f --show-error -s -X POST \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d "{\"tasks\":[
+  -d "{\"type\":\"delegate\",\"tasks\":[
     {\"prompt\":\"Implement section 3 per spec\",\"contextBlockIds\":[\"$ID\"]},
     {\"prompt\":\"Implement section 4 per spec\",\"contextBlockIds\":[\"$ID\"]}
   ]}" \
-  "http://localhost:$PORT/delegate?cwd=/project"
+  "http://localhost:$PORT/task?cwd=/project"
 ```
 
 ## v5 wire shape (register-context-block route)
@@ -125,7 +125,7 @@ This skill is the cross-cutting state mechanism described in `multi-model-agent`
 - **Recipe A — Audit-iterate-clean.** Register the doc once before round 1; pass round-N's findings block ID into round N+1.
 - **Recipe B — Debug-fix-verify.** Register the failing test output / reproduction log before the debug call; reuse on verify.
 - **Recipe C — Investigate-plan-execute.** Register the plan file before `mma-execute-plan`.
-- **Recipe D — Plan-execute-retry.** No new registration needed — `mma-retry` inherits the original batch's `contextBlockIds`.
+- **Recipe D — Plan-execute-retry.** No new registration needed — `mma-retry` inherits the original task's `contextBlockIds`.
 
 Anti-pattern alert: **`re-inlined-shared-content`** (AP3). Pasting the same spec into 5 task prompts costs N× tokens. Register once; pass `contextBlockIds`.
 
@@ -137,12 +137,12 @@ Anti-pattern alert: **`re-inlined-shared-content`** (AP3). Pasting the same spec
 N×50KB transmissions; main context burns through tokens. **Fix:** register the spec once, pass `contextBlockIds: ["cb_xxx"]` to each task.
 
 ❌ **Forgetting to delete unused blocks**
-Blocks count against the project's context-block quota (`maxEntries` 500). **Fix:** explicitly `DELETE` after the dependent batches finish — or let idle expiry (24 h) evict them.
+Blocks count against the project's context-block quota (`maxEntries` 500). **Fix:** explicitly `DELETE` after the dependent tasks finish — or let idle expiry (24 h) evict them.
 
 ❌ **Trying to update a block's content**
 Blocks are immutable. **Fix:** register a new block with the new content; switch the `contextBlockIds` to the new ID.
 
-❌ **Deleting a block while a batch still references it**
-Returns `409 pinned`. **Fix:** poll the dependent batches to terminal first, then delete.
+❌ **Deleting a block while a task still references it**
+Returns `409 pinned`. **Fix:** poll the dependent tasks to terminal first, then delete.
 
 @include _shared/error-handling.md

package/dist/skills/mma-debug/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   read files, reproduce, trace — OR a methodology skill
   (superpowers:systematic-debugging) points at the investigation step. Delegate
   the read/reproduce/trace; the main agent stays on the hypothesis and the fix.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-debug
@@ -36,7 +36,7 @@ Submit a problem, context, and hypothesis to a worker for focused debugging. Unl
 
 ## Endpoint
 
-`POST /debug?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -44,10 +44,8 @@ Submit a problem, context, and hypothesis to a worker for focused debugging. Unl
 
 ```json
 {
-  "problem": "POST /login returns 500 when password contains special characters",
-  "context": "Regression introduced in commit abc123; only affects production config",
-  "hypothesis": "The bcrypt binding fails on non-ASCII input in the Docker image",
-  "subtype": "default",
+  "type": "debug",
+  "errorMessage": "POST /login returns 500 when password contains special characters",
   "filePaths": [
     "/project/src/auth/login.ts",
     "/project/src/auth/password.ts"
@@ -58,9 +56,7 @@ Submit a problem, context, and hypothesis to a worker for focused debugging. Unl
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `problem` | string | yes | What is broken (one sentence; concrete symptom) |
-| `context` | string | no | Background — what changed recently, what works, what doesn't |
-| `hypothesis` | string | no | Your initial theory; worker tests it first, then explores |
+| `errorMessage` | string | yes | What is broken (one sentence; concrete symptom) |
 | `subtype` | `'default'` | no (defaults to `'default'`) | Reserved for future criteria sets; only `default` is wired today. |
 | `filePaths` | string[] | no | All files investigated together (cross-file reasoning) |
 | `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` (e.g. error logs, traces) |
@@ -70,14 +66,14 @@ Submit a problem, context, and hypothesis to a worker for focused debugging. Unl
 ## Full example
 
 ```bash
-BATCH=$(curl -f --show-error -s -X POST \
+RESULT=$(curl -f --show-error -s -X POST \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"problem":"Tests fail on CI only","hypothesis":"Missing env var","filePaths":["/project/src/config.ts"]}' \
-  "http://localhost:$PORT/debug?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  -d '{"type":"debug","errorMessage":"Tests fail on CI only","filePaths":["/project/src/config.ts"]}' \
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md

package/dist/skills/mma-delegate/SKILL.md

@@ -11,7 +11,7 @@ when_to_use: >-
   and keep main context free. If a plan file exists → use mma-execute-plan. If
   the task is audit / review / verify / debug / investigate → use the matching
   specialized skill.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-delegate
@@ -37,7 +37,7 @@ Dispatch one or more ad-hoc tasks to workers concurrently. Each task is an indep
 
 ## Endpoint
 
-`POST /delegate?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -45,6 +45,7 @@ Dispatch one or more ad-hoc tasks to workers concurrently. Each task is an indep
 
 ```json
 {
+  "type": "delegate",
   "tasks": [
     {
       "prompt": "Add input validation to the login handler",
@@ -65,46 +66,46 @@ Dispatch one or more ad-hoc tasks to workers concurrently. Each task is an indep
 | `tasks[].filePaths` | string[] | no | Files the worker focuses on |
 | `tasks[].done` | string | no | Acceptance criteria |
 | `tasks[].contextBlockIds` | string[] | no | IDs from `mma-context-blocks` |
-| `tasks[].reviewPolicy` | `"full"` / `"quality_only"` / `"diff_only"` / `"none"` | no | See review-policy snippet below. Default `"full"` |
+| `tasks[].reviewPolicy` | `"reviewed"` / `"none"` | no | See review-policy snippet below. Default `"reviewed"` |
 
 @include _shared/review-policy.md
 
 ## Full example
 
 ```bash
-BATCH=$(curl -f --show-error -s -X POST \
+RESULT=$(curl -f --show-error -s -X POST \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"tasks":[{"prompt":"Refactor utils.ts to remove dead code","filePaths":["/project/src/utils.ts"]}]}' \
-  "http://localhost:$PORT/delegate?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  -d '{"type":"delegate","tasks":[{"prompt":"Refactor utils.ts to remove dead code","filePaths":["/project/src/utils.ts"]}]}' \
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md
 
 ## Response shapes
 
-### POST /delegate?cwd=<abs> — dispatch response (202)
+### POST /task?cwd=<abs> — dispatch response (202)
 
 ```json
-{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
+{ "taskId": "<uuid>", "statusUrl": "/task/<uuid>" }
 ```
 
-Use `batchId` to poll. `statusUrl` is a convenience pointer.
+Use `taskId` to poll. `statusUrl` is a convenience pointer.
 
-### GET /batch/:id — polling response
+### GET /task/:taskId — polling response
 
 The HTTP status is the state discriminator:
 
 | Status | Meaning |
 |---|---|
 | `202 text/plain` | Still pending — body is the running headline string |
-| `200 application/json` | Terminal — body is the batch envelope below |
+| `200 application/json` | Terminal — body is the task envelope below |
 | `404` / `401` / `5xx` | Error — see Error response below; stop polling |
 
-### GET /batch/:id?taskIndex=N — single task slice
+### GET /task/:taskId?taskIndex=N — single task slice
 
 Same envelope. `results` contains exactly the task at index `N`. Returns `404 unknown_task_index` if `N` is out of range.
 

package/dist/skills/mma-execute-plan/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   superpowers:subagent-driven-development / superpowers:executing-plans —
   workers are cheaper and don't pollute main context. Task descriptors must
   match plan headings verbatim.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-execute-plan
@@ -35,7 +35,7 @@ Dispatch named tasks from a plan file to workers. Each `taskDescriptors` string
 
 ## Endpoint
 
-`POST /execute-plan?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -43,6 +43,7 @@ Dispatch named tasks from a plan file to workers. Each `taskDescriptors` string
 
 ```json
 {
+  "type": "execute_plan",
   "taskDescriptors": [
     "1. Add input validation to login handler",
     "2. Write unit tests for the auth module"
@@ -59,7 +60,7 @@ Dispatch named tasks from a plan file to workers. Each `taskDescriptors` string
 | `taskDescriptors` | string[] | yes | At least one; must be unique; each string matches a plan heading verbatim |
 | `filePaths` | string[] | yes | EXACTLY one entry: the plan markdown file. Source files belong in `contextBlockIds` (registered via `mma-context-blocks`) so workers can grep them on demand without re-inlining into every worker prompt |
 | `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` — the right place for source files referenced by the plan |
-| `perTaskReviewPolicy` | `Record<string, 'full'\|'quality_only'\|'diff_only'\|'none'>` | no | Per-task-index review policy override. Key = task index as string (`"0"`, `"1"`, ...). Default per task: `"full"` |
+| `perTaskReviewPolicy` | `Record<string, 'reviewed'\|'none'>` | no | Per-task-index review policy override. Key = task index as string (`"0"`, `"1"`, ...). Default per task: `"reviewed"` |
 | `cwd` | string | no | Override the `?cwd=` query param value at the body level (rare; usually pass via query) |
 
 @include _shared/review-policy.md
@@ -69,39 +70,39 @@ Dispatch named tasks from a plan file to workers. Each `taskDescriptors` string
 ## Full example
 
 ```bash
-BATCH=$(curl -f --show-error -s -X POST \
+RESULT=$(curl -f --show-error -s -X POST \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"taskDescriptors":["3. Migrate database schema"],"filePaths":["/project/docs/plan.md"]}' \
-  "http://localhost:$PORT/execute-plan?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  -d '{"type":"execute_plan","taskDescriptors":["3. Migrate database schema"],"filePaths":["/project/docs/plan.md"]}' \
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md
 
 ## Response shapes
 
-### POST /execute-plan?cwd=<abs> — dispatch response (202)
+### POST /task?cwd=<abs> — dispatch response (202)
 
 ```json
-{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
+{ "taskId": "<uuid>", "statusUrl": "/task/<uuid>" }
 ```
 
-Use `batchId` to poll. `statusUrl` is a convenience pointer.
+Use `taskId` to poll. `statusUrl` is a convenience pointer.
 
-### GET /batch/:id — polling response
+### GET /task/:taskId — polling response
 
 The HTTP status is the state discriminator:
 
 | Status | Meaning |
 |---|---|
 | `202 text/plain` | Still pending — body is the running headline string |
-| `200 application/json` | Terminal — body is the batch envelope below |
+| `200 application/json` | Terminal — body is the task envelope below |
 | `404` / `401` / `5xx` | Error — see Error response below; stop polling |
 
-### GET /batch/:id?taskIndex=N — single task slice
+### GET /task/:taskId?taskIndex=N — single task slice
 
 Same envelope. `results` contains exactly the task at index `N`. Returns `404 unknown_task_index` if `N` is out of range.
 
@@ -187,7 +188,7 @@ Use `telemetry.haltedStage` to find the first halt; `telemetry.stopReason` to fi
 This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-execute-plan`:
 
 - **Recipe C — Investigate-plan-execute.** `mma-investigate` → write the plan → `mma-execute-plan` → `mma-retry` on failed indices. Register the plan file as a context block before the execute-plan call so it isn't re-inlined into every worker's prompt; retry inherits the same configuration.
-- **Recipe D — Plan-execute-retry (entry point).** `mma-execute-plan` is the producer of the `batchId` that `mma-retry` consumes. When this batch returns mixed `done` / `failed`, the next call is `mma-retry` with failed indices, NOT a re-dispatch.
+- **Recipe D — Plan-execute-retry (entry point).** `mma-execute-plan` is the producer of the `taskId` that `mma-retry` consumes. When this dispatch returns mixed `done` / `failed`, the next call is `mma-retry` with failed indices, NOT a re-dispatch.
 
 Anti-pattern alert: **`full-batch-redispatch`** (AP4). When the batch returns mixed `done` / `failed`, do NOT re-run the whole task list — use `mma-retry` with the failed indices only. Re-running the whole list re-charges every successful task.
 

package/dist/skills/mma-explore/SKILL.md

@@ -14,7 +14,7 @@ when_to_use: >-
   mma-journal-recall (prior learnings/decisions) in parallel and synthesise the
   results yourself. DO NOT use for convergent single-answer questions — those
   are mma-investigate.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-explore
@@ -81,8 +81,9 @@ result (or have decided to skip investigate as greenfield).
 
 This is a main-agent skill — there is no dedicated `/explore` HTTP endpoint.
 Behind the scenes, you dispatch the three delegated tools `mma-investigate`
-(`POST /investigate`), `mma-research` (`POST /research`), and
-`mma-journal-recall` (`POST /journal-recall`) yourself.
+(`POST /task` with `type: "investigate"`), `mma-research` (`POST /task` with
+`type: "research"`), and `mma-journal-recall` (`POST /task` with
+`type: "journal_recall"`) yourself.
 
 ## Request body
 

package/dist/skills/mma-investigate/SKILL.md

@@ -12,7 +12,7 @@ when_to_use: >-
   git-history queries. OR you are about to read 3+ files / run any grep in main
   context — that's the inline-labor-leakage anti-pattern (AP2); delegate to this
   skill instead.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-investigate
@@ -58,7 +58,7 @@ digraph when_to_use {
 
 ## Endpoint
 
-`POST /investigate?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -66,6 +66,7 @@ digraph when_to_use {
 
 ```json
 {
+  "type": "investigate",
   "question": "How does the auth middleware handle token refresh?",
   "subtype": "default",
   "filePaths": ["/project/src/auth/"],
@@ -93,14 +94,14 @@ digraph when_to_use {
 ## Full example
 
 ```bash
-BATCH=$(curl -f --show-error -s -X POST \
+RESULT=$(curl -f --show-error -s -X POST \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"question":"How does the auth middleware handle token refresh?"}' \
-  "http://localhost:$PORT/investigate?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  -d '{"type":"investigate","question":"How does the auth middleware handle token refresh?"}' \
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md

package/dist/skills/mma-journal-recall/SKILL.md

@@ -12,7 +12,7 @@ when_to_use: >-
   A question about THIS project's learnings, before attempting or designing
   something — ask a vague conceptual question; skip if recording a new learning,
   asking the codebase, or researching external docs.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-journal-recall
@@ -39,7 +39,7 @@ Recall relevant project learnings from the journal via a read-only mmagent worke
 
 ## Endpoint
 
-`POST /journal-recall?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -47,6 +47,7 @@ Recall relevant project learnings from the journal via a read-only mmagent worke
 
 ```json
 {
+  "type": "journal_recall",
   "query": "what have we learned about dispatch cancellation reliability?",
   "contextBlockIds": []
 }
@@ -70,14 +71,14 @@ Recall relevant project learnings from the journal via a read-only mmagent worke
 ## Full example
 
 ```bash
-BATCH=$(curl -f --show-error -s -X POST \
+RESULT=$(curl -f --show-error -s -X POST \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"query":"what have we learned about dispatch cancellation reliability?"}' \
-  "http://localhost:$PORT/journal-recall?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  -d '{"type":"journal_recall","query":"what have we learned about dispatch cancellation reliability?"}' \
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md

package/dist/skills/mma-journal-record/SKILL.md

@@ -9,7 +9,7 @@ when_to_use: >-
   hit a blocking constraint, or reached a conclusion worth remembering. NOT for
   recall/investigate/delegate; those are read routes. Journal stores conclusions
   for cross-session reference.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-journal-record
@@ -36,7 +36,7 @@ Record a learning, constraint, or decision outcome to the persistent journal via
 
 ## Endpoint
 
-`POST /journal-record?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -44,20 +44,14 @@ Record a learning, constraint, or decision outcome to the persistent journal via
 
 ```json
 {
-  "learnings": [
-    "Tried worker self-report for grouped-dispatch cancellation; dropped it — git diff is the source of truth. Lesson: use getRealFilesChanged.",
-    "Bun.spawn lacks process groups; keep node:child_process for codex subprocess management."
-  ],
-  "tagHints": ["dispatch", "cancellation"]
+  "type": "journal_record",
+  "entry": "Tried worker self-report for grouped-dispatch cancellation; dropped it — git diff is the source of truth. Lesson: use getRealFilesChanged. Also: Bun.spawn lacks process groups; keep node:child_process for codex subprocess management."
 }
 ```
 
-**Batch your learnings into ONE call.** Collect every learning from the session and send them together in `learnings[]` — do NOT fire multiple concurrent `journal-record` calls. One worker integrates them sequentially in a single pass (fast and collision-free).
-
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `learnings` | string[] | yes | 1–20 entries, each 20–8000 chars. Each is a natural-language entry: what you decided, why, or what you learned. Keep them concrete. |
-| `tagHints` | string[] | no | Optional tags applied across ALL learnings (batch-scoped); the worker revises/normalizes per node. Advisory. |
+| `entry` | string | yes | A natural-language entry: what you decided, why, or what you learned. Keep it concrete (min 1 char). |
 
 **What gets stored & where:**
 
@@ -71,19 +65,17 @@ The worker creates, refines, or supersedes nodes in the graph (never appends bli
 ## Full example
 
 ```bash
-BATCH=$(curl -f --show-error -s -X POST \
+RESULT=$(curl -f --show-error -s -X POST \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "learnings": [
-      "Tried worker self-report for grouped-dispatch cancellation; dropped it — git diff is the source of truth. Lesson: use getRealFilesChanged."
-    ],
-    "tagHints": ["dispatch", "cancellation"]
+    "type": "journal_record",
+    "entry": "Tried worker self-report for grouped-dispatch cancellation; dropped it. Lesson: use getRealFilesChanged."
   }' \
-  "http://localhost:$PORT/journal-record?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md

package/dist/skills/mma-orchestrate/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: mma-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: 5.2.1
+---
+
+# 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 worktree, 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
+
+## Endpoint
+
+`POST /task?cwd=<abs-path>`
+
+```json
+{
+  "type": "main",
+  "prompt": "Synthesize the exploration results into a requirements specification...",
+  "outputFormat": "json"
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `type` | `"main"` | 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` |
+
+> The orchestrate agent always uses the `main` tier (falls back to `complex` if `agents.main` is not configured). 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:
+
+```bash
+# Phase 1: Exploration
+RESULT=$(curl ... -d '{"type":"main","prompt":"Explore the codebase for auth patterns..."}' ...)
+SESSION_ID=$(echo "$RESULT" | jq -r '.sessions.implementer.sessionId')
+
+# Phase 2: Specification (reuse session)
+RESULT=$(curl ... -d '{"type":"main","prompt":"Based on your exploration, write a spec...","sessionIds":{"implementer":"'"$SESSION_ID"'"}}' ...)
+```
+
+@include _shared/auth.md
+@include _shared/polling.md
+@include _shared/response-shape.md

package/dist/skills/mma-research/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   others do, what published methods exist) AND mmagent is running. Delegate the
   multi-source web/adapter research to a worker so the main context stays on
   judgment. NOT for codebase questions — those are mma-investigate.
-version: 5.1.0
+version: 5.2.1
 ---
 
 # mma-research
@@ -43,7 +43,7 @@ mean and which directions to pursue.
 
 ## Endpoint
 
-`POST /research?cwd=<abs-path>`
+`POST /task?cwd=<abs-path>`
 
 @include _shared/auth.md
 
@@ -71,6 +71,7 @@ If the Semantic Scholar API key is not configured:
 
 ```json
 {
+  "type": "research",
   "researchQuestion": "What approaches exist for streaming JSON parsing under 100KB?",
   "background": "We currently use a single-pass push parser; we want to evaluate alternatives.",
   "subtype": "default",
@@ -92,17 +93,18 @@ The `default` subtype's criteria target primary-source preference, practitioner
 ## Full example
 
 ```bash
-BATCH=$(curl -f -sS -X POST \
+RESULT=$(curl -f -sS -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "X-MMA-Client: $MMA_CLIENT" \
   -H "X-MMA-Main-Model: $MMA_MAIN_MODEL" \
   -H "Content-Type: application/json" \
   -d '{
+    "type": "research",
     "researchQuestion": "State-of-the-art SIMD JSON parsers under 100KB?",
     "background": "We use a single-pass push parser; want SIMD alternatives."
   }' \
-  "http://localhost:$PORT/research?cwd=/project")
-BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+  "http://localhost:$PORT/task?cwd=/project")
+TASK_ID=$(echo "$RESULT" | jq -r '.taskId')
 ```
 
 @include _shared/polling.md