@zhixuan92/multi-model-agent 4.9.0 → 5.0.0

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

@@ -1,216 +0,0 @@
----
-name: mma-delegate
-description: >-
-  Use when you have one or more ad-hoc implementation or research tasks WITHOUT
-  a plan file on disk and you want them to run on cheap workers in parallel
-  instead of consuming main-context tokens
-when_to_use: >-
-  You have ad-hoc implementation or research tasks (no plan file on disk) AND
-  mmagent is running. Prefer this over inline Agent dispatches or
-  superpowers:dispatching-parallel-agents — workers are cheaper, parallel-safe,
-  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: 4.9.0
----
-
-# mma-delegate
-
-## Overview
-
-Dispatch one or more ad-hoc tasks to workers concurrently. Each task is an independent instruction with optional file scope, acceptance criteria, and context blocks.
-
-**Core principle:** Workers run on cheap providers; the main agent consumes only the structured per-task report. Parallelize freely as long as tasks don't write the same files.
-
-## When to Use
-
-**Use when:**
-- 2+ unrelated implementation tasks (parallel speedup)
-- A research task you'd otherwise spend tokens reading and grepping
-- A focused refactor that fits in one prompt
-- The task does NOT match audit / review / verify / debug / investigate (those have specialized skills)
-
-**Don't use when:**
-- A plan file exists on disk → `mma-execute-plan` (descriptors auto-match plan headings)
-- Two tasks write the same file → dispatch sequentially, not in one batch (workers race)
-- The work needs to read across many files for synthesis only → `mma-investigate` is cheaper (read-only)
-
-## Endpoint
-
-`POST /delegate?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Request body
-
-```json
-{
-  "tasks": [
-    {
-      "prompt": "Add input validation to the login handler",
-      "agentType": "standard",
-      "filePaths": ["/project/src/auth/login.ts"],
-      "done": "All inputs validated; unit tests pass",
-      "contextBlockIds": ["cb_abc123"]
-    }
-  ]
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `tasks` | array | yes | At least one task |
-| `tasks[].prompt` | string | yes | The task instruction |
-| `tasks[].agentType` | `"standard"` / `"complex"` | no | Worker tier. Default `"standard"`. Pick `"complex"` when the task is ambiguous, security-sensitive, touches many files, or a prior standard run came back with `filesWritten: 0` / hit `incompleteReason: "turn_cap"`. |
-| `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"` |
-
-@include _shared/review-policy.md
-
-## Full example
-
-```bash
-BATCH=$(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')
-```
-
-@include _shared/polling.md
-
-## Response shapes
-
-### POST /delegate?cwd=<abs> — dispatch response (202)
-
-```json
-{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
-```
-
-Use `batchId` to poll. `statusUrl` is a convenience pointer.
-
-### GET /batch/:id — 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 |
-| `404` / `401` / `5xx` | Error — see Error response below; stop polling |
-
-### GET /batch/:id?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.
-
-### Reading the task result
-
-Each task result is the per-task wire object (`ComposePayload`):
-
-```json
-{
-  "completed": true,
-  "message": "Task completed; tests passed; one file changed.",
-  "findings": [
-    {
-      "id": "F1",
-      "severity": "high",
-      "category": "correctness",
-      "claim": "The function does not handle empty input",
-      "evidence": "function foo() { ... } // no null check",
-      "suggestion": "Add an explicit null guard at the top",
-      "source": "reviewer"
-    }
-  ],
-  "summary": "Refactored utils.ts — removed 3 dead branches, added JSDoc",
-  "filesChanged": ["/project/src/utils.ts"],
-  "commitSha": "abc123def",
-  "blockId": null,
-  "telemetry": {
-    "totalDurationMs": 12400,
-    "totalCostUSD": 0.08,
-    "workerSelfAssessment": "done",
-    "reviewVerdict": "approved",
-    "commitOutcome": "committed",
-    "stopReason": "normal",
-    "haltedStage": null,
-    "stages": [
-      { "name": "prepare",        "outcome": "advance", "durationMs": 2,    "costUSD": 0 },
-      { "name": "register-block", "outcome": "skip",    "comment": "register-block does not apply to route=delegate", "durationMs": 0, "costUSD": 0 },
-      { "name": "implement",      "outcome": "advance", "durationMs": 8900, "costUSD": 0.05 },
-      { "name": "review",         "outcome": "advance", "durationMs": 2100, "costUSD": 0.02 },
-      { "name": "rework",         "outcome": "skip",    "comment": "rework skipped because review approved", "durationMs": 0, "costUSD": 0 },
-      { "name": "commit",         "outcome": "advance", "durationMs": 340,  "costUSD": 0 },
-      { "name": "annotate",       "outcome": "advance", "durationMs": 890,  "costUSD": 0.01 },
-      { "name": "compose",        "outcome": "advance", "durationMs": 68,   "costUSD": 0 },
-      { "name": "terminal",       "outcome": "advance", "durationMs": 100,  "costUSD": 0 }
-    ]
-  }
-}
-```
-
-**Top-level fields to read for the main-agent verdict:**
-
-| Field | When `true` / populated |
-|---|---|
-| `completed: true` | Task succeeded. `message` is the summary; `findings` are post-review issues (if any). |
-| `completed: false` | Task did not complete. `message` names the blocking gate or finding; `findings` carry any discovered issues. |
-| `findings` | Issues surfaced by the worker or reviewer. `severity` = `critical` \| `high` \| `medium` \| `low`. `source` = `implementer` \| `reviewer`. |
-| `filesChanged` | File paths modified (empty for read-only routes). |
-| `commitSha` | Git SHA of the committed diff; `null` for read-only routes or when commit was skipped. |
-
-`blockId` is not used for the delegate route — it is always `null`, as is `contextBlockId` (write routes register no terminal block). To carry inputs forward, register them explicitly via `mma-context-blocks` and pass `contextBlockIds`.
-
-**The stages array** (always 9 rows) is the canonical telemetry log. `outcome` is one of:
-- `advance` — stage ran and produced its payload
-- `skip` — stage did not run; `comment` explains why
-- `halt` — stage stopped the chain; `comment` is the failure message
-- `not_run` — stage was not reached because a prior stage halted
-
-Use `telemetry.haltedStage` to find the first halt; `telemetry.stopReason` to find why.
-
-### Error response (4xx / 5xx)
-
-```json
-{
-  "error": "<code>",
-  "message": "<human-readable>",
-  "details": { /* optional structured context, e.g. fieldErrors for 400 */ }
-}
-```
-
-`details` is optional and present only when the server has structured additional context.
-
-## Best practices
-
-This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-delegate`:
-
-- **Recipe A (the fix step).** Between audit rounds, `mma-delegate` applies the fix when the change is more than 1-2 lines. Register the spec/audit findings as a context block; pass via `contextBlockIds`.
-- **Recipe B (the apply-fix step).** After `mma-debug` returns a hypothesis, `mma-delegate` applies the fix. Same context block carries forward to a follow-up `mma-review` if you want acceptance-criteria checking.
-
-Anti-pattern alert: **`inline-labor-leakage`** (AP2). If you're reading 3+ files or grepping in main context before dispatching, you're paying flagship-model tokens for labor. Pass the file paths to `mma-delegate` and let the worker read.
-
-## Common pitfalls
-
-❌ **Two tasks writing the same file in one batch**
-> tasks: [{prompt:"add JWT to login.ts"}, {prompt:"add logging to login.ts"}]
-
-Workers run concurrently and race on the file. **Fix:** dispatch sequentially, or merge into one prompt.
-
-❌ **Two tasks writing the same file in one batch**
-N tasks × 50KB = N transmissions. **Fix:** register the doc once via `mma-context-blocks`, pass the `contextBlockIds` to each task.
-
-❌ **Reading the worker's diff inline before review**
-The reviewer sees the full diff with the original prompt as context. Reading inline burns main-context tokens for no quality gain.
-
-## Terminal context block
-
-Write-route tasks (delegate / execute-plan / retry) do NOT register a terminal context block — their durable record is the commit (`commitSha` + changed files). The per-task result's `contextBlockId` is always `null` for these routes. Read routes (audit / review / debug / investigate / research) return a non-null `contextBlockId`; see those skills for the delta-follow-up recipe.
-
-
-@include _shared/error-handling.md

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

@@ -1,214 +0,0 @@
----
-name: mma-execute-plan
-description: >-
-  Use when a plan or spec file exists on disk (any markdown with numbered task
-  headings — docs/superpowers/plans/*.md, a TODO list, a spec doc) and you need
-  to implement one or more tasks from it on cheap workers in parallel
-when_to_use: >-
-  A plan file exists on disk AND you need to implement one or more tasks from it
-  AND mmagent is running. Prefer this over inline Agent dispatches or
-  superpowers:subagent-driven-development / superpowers:executing-plans —
-  workers are cheaper and don't pollute main context. Task descriptors must
-  match plan headings verbatim.
-version: 4.9.0
----
-
-# mma-execute-plan
-
-## Overview
-
-Dispatch named tasks from a plan file to workers. Each `taskDescriptors` string must match a heading in the plan verbatim (e.g. `"1. Setup database schema"`). All tasks run in parallel; duplicate descriptors are rejected.
-
-**Core principle:** The plan IS the prompt. Workers re-read the plan file in-process and find their named task — you don't need to inline the task body.
-
-## When to Use
-
-**Use when:**
-- A plan/spec markdown exists with numbered task headings
-- You want to dispatch a subset (or all) of those tasks
-- Tasks are mostly independent (parallel-safe)
-
-**Don't use when:**
-- No plan file → `mma-delegate` (pass the prompt directly)
-- Tasks form a hard linear sequence (later tasks depend on earlier ones' outputs) → dispatch in order, one batch each
-- The "plan" is in conversation only, not on disk → write it to disk first, or use `mma-delegate`
-
-## Endpoint
-
-`POST /execute-plan?cwd=<abs-path>`
-
-@include _shared/auth.md
-
-## Request body
-
-```json
-{
-  "taskDescriptors": [
-    "1. Add input validation to login handler",
-    "2. Write unit tests for the auth module"
-  ],
-  "filePaths": [
-    "/project/docs/plan.md"
-  ],
-  "contextBlockIds": []
-}
-```
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| `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"` |
-| `cwd` | string | no | Override the `?cwd=` query param value at the body level (rare; usually pass via query) |
-
-@include _shared/review-policy.md
-
-> **No `agentType` here.** Worker tier is hardcoded to `standard` for every plan task; sending `agentType` (top-level or per-task) is rejected with HTTP 400. For tasks that need `complex` tier, dispatch via `mma-delegate` with the plan task as the prompt and `agentType: "complex"`.
-
-## Full example
-
-```bash
-BATCH=$(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')
-```
-
-@include _shared/polling.md
-
-## Response shapes
-
-### POST /execute-plan?cwd=<abs> — dispatch response (202)
-
-```json
-{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
-```
-
-Use `batchId` to poll. `statusUrl` is a convenience pointer.
-
-### GET /batch/:id — 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 |
-| `404` / `401` / `5xx` | Error — see Error response below; stop polling |
-
-### GET /batch/:id?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.
-
-### Reading the task result
-
-Each task result is the per-task wire object (`ComposePayload`):
-
-```json
-{
-  "completed": true,
-  "message": "Task completed; tests passed; one file changed.",
-  "findings": [
-    {
-      "id": "F1",
-      "severity": "high",
-      "category": "correctness",
-      "claim": "The function does not handle empty input",
-      "evidence": "function foo() { ... } // no null check",
-      "suggestion": "Add an explicit null guard at the top",
-      "source": "reviewer"
-    }
-  ],
-  "summary": "Refactored utils.ts — removed 3 dead branches, added JSDoc",
-  "filesChanged": ["/project/src/utils.ts"],
-  "commitSha": "abc123def",
-  "blockId": null,
-  "telemetry": {
-    "totalDurationMs": 12400,
-    "totalCostUSD": 0.08,
-    "workerSelfAssessment": "done",
-    "reviewVerdict": "approved",
-    "commitOutcome": "committed",
-    "stopReason": "normal",
-    "haltedStage": null,
-    "stages": [
-      { "name": "prepare",        "outcome": "advance", "durationMs": 2,    "costUSD": 0 },
-      { "name": "register-block", "outcome": "skip",    "comment": "register-block does not apply to route=execute-plan", "durationMs": 0, "costUSD": 0 },
-      { "name": "implement",      "outcome": "advance", "durationMs": 8900, "costUSD": 0.05 },
-      { "name": "review",         "outcome": "advance", "durationMs": 2100, "costUSD": 0.02 },
-      { "name": "rework",         "outcome": "skip",    "comment": "rework skipped because review approved", "durationMs": 0, "costUSD": 0 },
-      { "name": "commit",         "outcome": "advance", "durationMs": 340,  "costUSD": 0 },
-      { "name": "annotate",       "outcome": "advance", "durationMs": 890,  "costUSD": 0.01 },
-      { "name": "compose",        "outcome": "advance", "durationMs": 68,   "costUSD": 0 },
-      { "name": "terminal",       "outcome": "advance", "durationMs": 100,  "costUSD": 0 }
-    ]
-  }
-}
-```
-
-**Top-level fields to read for the main-agent verdict:**
-
-| Field | When `true` / populated |
-|---|---|
-| `completed: true` | Task succeeded. `message` is the summary; `findings` are post-review issues (if any). |
-| `completed: false` | Task did not complete. `message` names the blocking gate or finding; `findings` carry any discovered issues. |
-| `findings` | Issues surfaced by the worker or reviewer. `severity` = `critical` \| `high` \| `medium` \| `low`. `source` = `implementer` \| `reviewer`. |
-| `filesChanged` | File paths modified (empty for read-only routes). |
-| `commitSha` | Git SHA of the committed diff; `null` for read-only routes or when commit was skipped. |
-| `blockId` | Always `null` (execute-plan is a write route; `contextBlockId` is `null` too — no terminal block). |
-
-**The stages array** (always 9 rows) is the canonical telemetry log. `outcome` is one of:
-- `advance` — stage ran and produced its payload
-- `skip` — stage did not run; `comment` explains why
-- `halt` — stage stopped the chain; `comment` is the failure message
-- `not_run` — stage was not reached because a prior stage halted
-
-Use `telemetry.haltedStage` to find the first halt; `telemetry.stopReason` to find why.
-
-### Error response (4xx / 5xx)
-
-```json
-{
-  "error": "<code>",
-  "message": "<human-readable>",
-  "details": { /* optional structured context, e.g. fieldErrors for 400 */ }
-}
-```
-
-`details` is optional and present only when the server has structured additional context.
-
-## Best practices
-
-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.
-
-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.
-
-## Common pitfalls
-
-❌ **Task descriptor doesn't match plan heading verbatim**
-> taskDescriptors: ["Migrate db schema"]    ← plan heading is "3. Migrate database schema"
-
-Worker rejects with "no matching task" or matches the wrong one. **Fix:** copy the heading from the plan, including the leading number.
-
-❌ **Forgetting the plan file in `filePaths`**
-> filePaths: ["/project/src/db/schema.sql"]    ← no plan file
-
-Worker can't read the task body. **Fix:** always include the plan path: `filePaths: ["/project/docs/plan.md", "/project/src/db/schema.sql"]`.
-
-❌ **Dispatching dependent tasks in one batch**
-Task 5 depends on Task 4's output → workers race; Task 5 might run before Task 4 finishes. **Fix:** dispatch Task 4, wait for terminal, then dispatch Task 5.
-
-## Terminal context block
-
-Write-route tasks (delegate / execute-plan / retry) do NOT register a terminal context block — their durable record is the commit (`commitSha` + changed files). The per-task result's `contextBlockId` is always `null` for these routes. Read routes (audit / review / debug / investigate / research) return a non-null `contextBlockId`; see those skills for the delta-follow-up recipe.
-
-
-@include _shared/error-handling.md

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

@@ -1,190 +0,0 @@
----
-name: mma-explore
-description: >-
-  Use when about to brainstorm or plan and need a divergent landscape scan —
-  orchestrates parallel internal-codebase investigation + external multi-source
-  research + prior-learnings recall from the project journal, then synthesises
-  3–5 distinct directions. Not for "where is X" single-answer questions (use
-  mma-investigate).
-when_to_use: >-
-  You are about to brainstorm or plan and need a broad landscape scan before
-  narrowing. The question is exploratory ("what are our options", "what
-  approaches exist", "survey how others handle"). The skill instructs you to fan
-  out mma-investigate (internal), mma-research (external), and
-  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: 4.9.0
----
-
-# mma-explore
-
-## Overview
-
-Codebase + external sources + prior learnings, synthesised into 3–5 distinct
-directions. Three delegated calls run in parallel — `mma-investigate` (internal
-codebase), `mma-research` (external sources), and `mma-journal-recall` (what
-this project already learned/decided, from the `.mmagent/journal/` graph) —
-and **you** synthesise their results into the final output.
-
-**Core principle:** Exploration is divergent (survey, enumerate, compare).
-Synthesis turns raw threads into ranked, citable directions. The three legs
-are delegated; the synthesis is your judgment work and stays in main context.
-The journal leg is what keeps you from re-proposing a direction the project
-already tried and dropped — it grounds the scan in your own history, not just
-the code and the outside world.
-
-## When to Use
-
-First decision — output shape:
-- Want **one** synthesised answer with citations? → use `mma-investigate` (don't continue here)
-- Want **multiple** distinct directions to weigh (3–5 threads + cross-thread synthesis)? → continue here
-
-Internal-vs-external is not your decision; explore always runs both.
-
-```dot
-digraph when_to_use {
-    "Exploratory question?" [shape=diamond];
-    "Convergent single-answer?" [shape=diamond];
-    "About to brainstorm/plan?" [shape=diamond];
-    "mma-explore" [shape=box];
-    "mma-investigate" [shape=box];
-    "Inline search (1–2 queries)" [shape=box];
-
-    "Exploratory question?" -> "Convergent single-answer?";
-    "Convergent single-answer?" -> "mma-investigate" [label="yes"];
-    "Convergent single-answer?" -> "About to brainstorm/plan?";
-    "About to brainstorm/plan?" -> "mma-explore" [label="yes"];
-    "About to brainstorm/plan?" -> "Inline search (1–2 queries)" [label="no — narrow enough"];
-}
-```
-
-## How to run
-
-Dispatch ALL THREE in ONE message (parallel tool use):
-
-1. `mma-investigate` — internal codebase research
-   - You MAY skip this only if the question is unambiguously greenfield (no
-     codebase touch-points exist). When in doubt, run it.
-2. `mma-research` — external multi-source research
-3. `mma-journal-recall` — prior learnings/decisions from the project journal
-   - Always run it. If the project has no journal yet (or nothing relevant),
-     it returns zero findings — a valid result you handle with the
-     `(no prior learning)` sentinel. Never skip it to "save a call": a
-     superseded prior decision is exactly the signal you most want before
-     brainstorming.
-
-Wait for all legs to return. Do NOT proceed to synthesis until you have every
-result (or have decided to skip investigate as greenfield).
-
-## Endpoint
-
-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.
-
-## Request body
-
-(Not applicable — this skill orchestrates three other skills.) See
-[`mma-investigate`](../mma-investigate/SKILL.md),
-[`mma-research`](../mma-research/SKILL.md), and
-[`mma-journal-recall`](../mma-journal-recall/SKILL.md) for their request bodies.
-
-## Full example
-
-The main agent (you) issues a single message with three parallel tool calls:
-
-```
-[parallel tool use]
-  mma-investigate    { question: "How does our streaming JSON parser handle backpressure?", filePaths: ["src/parsers/"] }
-  mma-research       { researchQuestion: "State-of-the-art streaming JSON parsers with backpressure?", background: "We use a single-pass push parser." }
-  mma-journal-recall { query: "what have we learned about streaming-parser backpressure or buffering tradeoffs?" }
-```
-
-## Reading the leg results
-
-All three legs (`mma-investigate`, `mma-research`, `mma-journal-recall`) return the v5 wire envelope (see `mma-investigate/SKILL.md` → "v5 wire shape"). Each sub-task result is a `ComposePayload` with the standard seven fields. The authoritative citation source is **`results[0].findings`** — an array of `{ id, severity, category, claim, evidence, suggestion, source }`.
-
-Explore top-level orchestration aggregates sub-task results into a valid `ImplementPayload` (read-route shape) before the final `annotate` stage runs. Each sub-task follows the same v5 wire shape; the top-level result is a composition of those sub-tasks.
-
-| Check | How |
-|---|---|
-| Did the leg succeed? | `results[0].completed === true` — findings may be zero on a read route; finding nothing wrong is a valid completion |
-| Internal citation source | `results[0].findings[i].claim` plus a `file:LINE` token from `results[0].findings[i].evidence` (workers style them as `` `path:LINE` `` markdown-linked refs) |
-| External citation source | `results[0].findings[i].claim` plus a source name / URL from `results[0].findings[i].evidence` |
-| Prior-learning source | `results[0].findings[i].claim` plus a journal node id from `results[0].findings[i].evidence` (recall cites `` `.mmagent/journal/nodes/NNNN-…` `` or `node NNNN`). Watch the node's status: a **superseded** learning is a "we tried this and moved on" signal — surface it, don't bury it |
-| Divergence axis | `results[0].findings[i].category` groups findings by criterion — pick across categories so threads don't collapse onto one axis |
-
-Apply a sentinel only when `findings` is empty AND `results[0].message` contains no finding-level content — i.e., the worker genuinely returned nothing. Do NOT apply a sentinel just because `results[0].message` reads tersely or `results[0].telemetry.workerSelfAssessment === 'failed'` — a worker can say `'failed'` with usable partial findings.
-
-## Per-task report shape
-
-Synthesis output (REQUIRED — your reply MUST contain these):
-
-Produce **3–5 threads**. Each thread MUST have:
-
-- A **title** and **one-paragraph summary**.
-- One **internal citation** (from investigate) — `file/path.ts:LINE — claim`.
-  - Pick from `results[0].findings`: take `claim` as the citation claim and pull a `file:LINE` token out of `evidence`.
-  - Use the sentinel `(no internal anchor — fully greenfield)` ONLY when investigate was skipped, or `results[0].findings` is empty AND `results[0].message` contains no finding-level content. The top-level `message` alone is not evidence — see "Reading the leg results" above.
-- One **external citation** (from research) — `<source> — claim`.
-  - Pick from `results[0].findings`: take `claim` as the citation claim and pull a source name / URL out of `evidence`.
-  - Use the sentinel `(no external source found)` only when `results[0].findings` is empty for the research leg.
-- One **prior-learning citation** (from journal-recall) WHEN a relevant node exists — `(journal) node NNNN — claim`.
-  - Pick from the recall leg's `results[0].findings`: take `claim` as the citation and pull the node id out of `evidence`.
-  - If the cited node is **superseded**, say so inline (e.g. `(journal) node 0012 [superseded by 0013] — …`) so the thread carries the "we already moved past this" signal.
-  - Use the sentinel `(no prior learning)` when the recall leg returned no relevant node — most threads on a young project will use this, and that's fine.
-- A **one-line divergence reason** — what makes this thread different from
-  the others. No two threads may share the same divergence axis.
-
-If the recall leg surfaced a learning that **invalidates** a direction (a
-superseded or dropped decision that maps onto a thread you'd otherwise
-propose), do not silently omit it — keep the thread but mark it
-`⚠ already explored — see (journal) node NNNN` and weight it down in the
-recommendation. Prior learnings prune the search; they don't just decorate it.
-
-End with `## Recommended next step` — one paragraph naming which thread to
-pursue first and why. If a prior learning rules a thread in or out, cite it here.
-
-## Best practices
-
-This skill is one step in the larger flow described in `multi-model-agent` →
-"Best practices". Use this BEFORE `superpowers:brainstorming` when the
-brainstorming would otherwise start cold — divergent threads ground the
-brainstorming in real code + real prior art.
-
-## Common pitfalls
-
-❌ **Do not dump the two raw reports back to the user.** The synthesis IS the
-output; the raw reports are inputs you reason over. **Fix:** synthesise into
-3–5 threads with citations from BOTH legs (or sentinels) and a recommended
-next step.
-
-❌ **Skipping `mma-investigate` for convenience.** "Greenfield" must be
-unambiguous. When in doubt, run it. **Fix:** only skip if the question is
-unambiguously greenfield (no codebase touch-points).
-
-❌ **Inventing citations.** Every citation must trace back to one of the two
-delegated reports or to a sentinel. **Fix:** if a thread has no usable
-citation from a leg, use the sentinel — do not fabricate.
-
-❌ **Padding to hit 5 threads.** ONE thread with high-confidence citations is
-better than 5 watery ones. **Fix:** stop at the natural number of distinct
-directions in the data.
-
-## Failure handling
-
-| Scenario | What to do |
-|---|---|
-| `mma-research` failed | Use `(no external source found)` sentinel on every external line. If `mma-investigate` also failed, do NOT synthesise — surface both errors to the user. |
-| `mma-investigate` failed | Treat as greenfield — use `(no internal anchor — fully greenfield)` sentinel. |
-| `mma-journal-recall` failed OR returned 0 findings | Use the `(no prior learning)` sentinel on every prior-learning line and continue — the journal leg is additive, never blocking. A young project with an empty journal hits this every time; it is not an error. |
-| All three failed | Report all errors to the user. Do NOT fabricate threads. |
-| Both investigate and research failed | Report both errors to the user. Do NOT fabricate threads. |
-| Investigate returned `needsCallerClarification: true` | Pause — surface the clarification need to the user. Do NOT synthesise over an unfinished investigation. |
-| Research returned 0 usable sources | Sentinel on external lines. Add a one-line note in synthesis preamble: *"External research returned no usable sources — threads anchor on internal findings only."* |
-| Investigate headline reads "0 citations" / "confidence unparseable" but `results[0].findings.length > 0` | Known stage-sync noise — IGNORE the headline. The leg succeeded; read `results[0].findings` directly. |
-
-See `superpowers:brainstorming` as the natural follow-up — convergent narrowing
-on a chosen thread.