@zhixuan92/multi-model-agent 5.0.2 → 5.0.3

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

@@ -0,0 +1,190 @@
+---
+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: 5.0.3
+---
+
+# 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.

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

@@ -0,0 +1,258 @@
+---
+name: mma-investigate
+description: >-
+  Use when you need to answer a question about the codebase ("how does X work",
+  "where is Y called", "what does this directory do") and reading + grepping the
+  codebase yourself would consume main-context tokens
+when_to_use: >-
+  A question about THIS codebase has surfaced — from the user, from a
+  methodology skill, or from your own next-step planning — AND mmagent is
+  running. Delegate the read/grep/synthesis to a worker so the main context
+  stays on judgment. Codebase only — does not perform web research or
+  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.0.3
+---
+
+# mma-investigate
+
+## Overview
+
+Answer a codebase question via a read-only mmagent worker. The worker greps and reads on its cheap budget; you read its synthesis on yours.
+
+**Core principle:** Investigation is labor (read, grep, synthesize). Delegate it. The main agent stays on judgment — deciding what the answer means and what to do with it.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Question about codebase?" [shape=diamond];
+    "About web / git history?" [shape=diamond];
+    "Already have the file in context?" [shape=diamond];
+    "mma-investigate" [shape=box];
+    "Read inline (1–2 reads)" [shape=box];
+    "WebSearch / git log" [shape=box];
+
+    "Question about codebase?" -> "About web / git history?";
+    "About web / git history?" -> "WebSearch / git log" [label="yes"];
+    "About web / git history?" -> "Already have the file in context?" [label="no"];
+    "Already have the file in context?" -> "Read inline (1–2 reads)" [label="yes"];
+    "Already have the file in context?" -> "mma-investigate" [label="no"];
+}
+```
+
+**Use when:**
+- "How does X work in this codebase?"
+- "Where is Y called from?"
+- "What does this directory do?"
+- The answer requires reading 3+ files or grepping
+- Cross-cutting investigations (auth flow across modules, data lineage)
+
+**Don't use when:**
+- The answer is in 1–2 files you already have in context → just `Read`
+- It's about web docs / external APIs → `WebSearch` / `WebFetch`
+- It's about git history → `git log` / `git blame`
+- You need to MODIFY code based on the finding → `mma-delegate` (research + edit)
+- You want to consider multiple distinct directions, not converge on one answer → `mma-explore` (divergent ideation, codebase + web)
+
+## Endpoint
+
+`POST /investigate?cwd=<abs-path>`
+
+@include _shared/auth.md
+
+## Request body
+
+```json
+{
+  "question": "How does the auth middleware handle token refresh?",
+  "subtype": "default",
+  "filePaths": ["/project/src/auth/"],
+  "contextBlockIds": []
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `question` | string | yes | Natural-language investigation question |
+| `subtype` | `'default'` | no (defaults to `'default'`) | Reserved for future criteria sets; only `default` is wired today. |
+| `filePaths` | string[] | no | Anchor paths the worker starts from. Worker may grep beyond. |
+| `contextBlockIds` | string[] | no | IDs from `mma-context-blocks` — enables follow-up / delta investigation |
+| `tools` | `'none' \| 'readonly'` | no | Default `'readonly'`. `'no-shell'` and `'full'` are rejected — investigation is read-only |
+
+> Worker tier for `mma-investigate` is hardcoded to `complex` and is not caller-configurable. Sending `agentType` is rejected with HTTP 400.
+
+**Anchor narrow questions with `filePaths`:**
+
+❌ `{ "question": "Where is parseConfig called?" }` — searches the whole repo
+✅ `{ "question": "Where is parseConfig called?", "filePaths": ["src/"] }` — bounded
+
+**Why:** the worker greps and reads under a turn and wall-clock budget. Without anchors, broad questions exhaust those budgets before they finish.
+
+## 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 '{"question":"How does the auth middleware handle token refresh?"}' \
+  "http://localhost:$PORT/investigate?cwd=/project")
+BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
+```
+
+@include _shared/polling.md
+
+@include _shared/response-shape.md
+
+## Per-task report shape
+
+Each task carries an `investigation` field on its per-task report:
+
+```json
+{
+  "investigation": {
+    "citations": [
+      { "file": "src/auth/refresh.ts", "lines": "45-72", "claim": "Refresh handler reads bearer." }
+    ],
+    "confidence": { "level": "high", "rationale": "All claims directly cited." },
+    "diagnostics": {
+      "malformedCitationLines": 0,
+      "missingRequiredSections": [],
+      "invalidRequiredSections": []
+    }
+  }
+}
+```
+
+The authoritative success signals are `completed`, `message`, and `findings`. See "v5 wire shape" above for the full envelope.
+
+## v5 wire shape (read route)
+
+Every task result is a `ComposePayload` — seven main-agent fields plus a telemetry block.
+The main-agent fields are authoritative; the telemetry block is diagnostics.
+
+```json
+{
+  "completed": true,
+  "message": "Investigation complete; 3 files analysed.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "high",
+      "category": "correctness",
+      "claim": "The refresh handler reads bearer from Authorization header unconditionally.",
+      "evidence": "src/auth/refresh.ts:45-72 — verbatim substring from worker output.",
+      "suggestion": "Add a guard to handle missing Authorization header gracefully.",
+      "source": "implementer"
+    }
+  ],
+  "summary": "...",
+  "filesChanged": [],
+  "commitSha": null,
+  "blockId": null,
+  "telemetry": {
+    "totalDurationMs": 1234,
+    "totalCostUSD": 0.08,
+    "workerSelfAssessment": "done",
+    "reviewVerdict": null,
+    "commitOutcome": "not_applicable",
+    "stopReason": "normal",
+    "haltedStage": null,
+    "stages": [...]
+  }
+}
+```
+
+### Key fields
+
+| Field | When populated | Notes |
+|---|---|---|
+| `completed` | always | `true` when at least one criterion succeeded; `false` on annotator transport failure OR unmet annotate preconditions (e.g. non-`done` worker self-assessment on a read route) |
+| `message` | always | human-readable summary; names blocking gates or finding IDs on failure |
+| `findings` | always | `source: 'implementer'` for investigate; findings are the deliverable on read routes |
+| `workerSelfAssessment` | always | `'done'` or `'failed'` — never `done_with_concerns` |
+| `blockId` | always `null` | investigate is a task route, not register-context-block |
+
+### No second review
+
+The LLM-judge stage (`annotate`) runs once, after the worker's output. Its preconditions for read-route `completed: true`:
+
+```
+gates.implement.outcome === 'advance'
+&& gates.implement.payload.workerSelfAssessment === 'done'
+&& (criteriaSucceeded.length > 0 || criteriaErrors.length === 0)
+```
+
+Findings are the deliverable — a task that surfaces 5 issues is `completed: true`. Finding nothing wrong is also a valid completion.
+
+### `completed: false` — what it means
+
+Only on annotator transport failure. The `message` names the blocking gate. Re-dispatch with tighter `filePaths` if the worker's citations were unusable.
+
+## Best practices
+
+This skill is one step in the larger flow described in `multi-model-agent` → "Best practices". Recipes that involve `mma-investigate`:
+
+- **Recipe C — Investigate-plan-execute.** `mma-investigate` → write the plan → `mma-execute-plan` → `mma-retry`. The investigation produces the synthesis you need to write the plan; the plan becomes a context block for execute-plan.
+
+Anti-pattern alert: **`inline-labor-leakage`** (AP2). If you find yourself reading 3+ files or running any grep in main context, that's the trigger to delegate here instead. Main-context tokens cost ~10× more than worker tokens, and you only need the synthesis, not the raw reads.
+
+## Common pitfalls
+
+❌ **Asking for a fix instead of an answer**
+> question: "Refactor the auth middleware to use JWT"
+
+The investigator can't write — `tools: 'readonly'`. **Fix:** use `mma-delegate` for research-then-edit, or split: investigate first, then dispatch the edit.
+
+❌ **Inline-reading instead of delegating**
+About to `Read` 3+ files just to answer one question? That's the wrong tradeoff — the worker reads on its cheap budget; you read its synthesis on yours.
+
+## Terminal context block
+
+Every completed **read-route** task (audit / review / debug / investigate / research) auto-registers a reusable terminal context block containing its report (headline + findings). The block id is returned on each per-task result as **`contextBlockId`**. Write routes (delegate / execute-plan / retry) return `contextBlockId: null` — their record is the commit, not a block. This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
+
+Use it for delta follow-ups — feed prior results' block ids into a later call's `contextBlockIds`, filtering out nulls:
+
+    contextBlockIds: priorResults.map(r => r.contextBlockId).filter((id) => id !== null)
+
+**Use cases:**
+- Pass investigation results to a downstream planning step
+- Feed codebase findings into `mma-execute-plan` as shared context
+- Carry investigation context forward through the investigate → plan → execute chain
+
+The block is registered server-side at task completion; no caller action is needed to create it. Delete it explicitly via `DELETE /context-blocks/:id` when no longer needed, or let it expire on session teardown.
+
+## Outcome semantics
+
+Every task result carries outcome fields that describe the investigation's conclusion status:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `findingsOutcome` | `'found' \| 'clean' \| 'not_applicable'` | Answers the question: did the investigation produce a substantive result? |
+| `findingsOutcomeReason` | `string \| null` | When `findingsOutcome` is set, this explains why (e.g. "No candidate answers found after perspective 5" or "One clear path identified at high confidence"). |
+| `outcomeInferred` | `boolean` | `true` if the system inferred the outcome from findings count; `false` if the worker explicitly stated it. |
+| `outcomeMalformed` | `boolean` | `true` if the outcome line was malformed and had to be repaired; `false` otherwise. |
+
+### Enum values
+
+- **`found`** — the investigation produced one or more candidate answers (findings) across one or more criteria. This is the success state for a question-answering route.
+- **`clean`** — the investigation completed but produced zero findings. This is valid for issue-hunting routes but unusual for `mma-investigate`, where answering a question always produces at least one candidate.
+- **`not_applicable`** — the investigation could not proceed (e.g., the question was out of scope, the codebase provided no data to work with, or the request preconditions failed). This is the "no answer possible" state.
+
+### Empty findings ≠ failure
+
+A crucial semantic: **empty findings does NOT mean `completed: false` or a failed task.** The presence or absence of findings is orthogonal to task success. An investigation that searches thoroughly and produces zero candidate answers is a valid `completed: true` outcome; it simply answers the question with "I found no evidence for that in the codebase."
+
+### Per-route legal outcomes
+
+The legal outcomes for this route are: `['found', 'not_applicable']`
+
+- **`found`** — one or more candidate answers surfaced via the investigation criteria.
+- **`not_applicable`** — the question was out of scope, unanswerable, or the codebase provided insufficient data.
+
+The outcome `clean` (zero findings + success) is not legal for `mma-investigate` because an investigation answer is always produced in the `found` state or the task is `not_applicable`.
+
+@include _shared/error-handling.md