multi-model-agent

Use when a grounded idea needs to be grilled into a formal spec — runs a relentless one-decision-at-a-time requirement interview, resolving mechanical questions via workers and putting only real decisions to the user, then dispatches mma-spec. Not for grounding a raw idea (use mma-explore first) or for work where a spec already exists (use mma-plan).

Use when you have an ad-hoc implementation or research task WITHOUT a plan file on disk and you want it to run on a cheap worker instead of consuming main-context tokens

Use when a plan or spec file exists on disk (any markdown with task headings — .mma/plans/*.md, a TODO list, a spec doc) and you need to implement one or more tasks from it sequentially in one worker session

Use when a raw idea or problem needs grounding before it's designed — captures a braindump, fans out divergent internal-codebase investigation + external research + prior-learnings recall in parallel, then synthesises the results into a written exploration.md (Background · Current State · Rough Direction). Not for "where is X" single-answer questions (use mma-investigate).

Claude Code command: /mma-flow — MMA-native design-to-merged-code SDLC playbook that resumes from durable artifacts

Use when you're about to design or attempt something and want to know what THIS project already learned — ask a vague conceptual question (no tags or keywords needed); a read-only worker searches the learnings graph and returns the relevant prior lessons + how they relate. Fire before re-treading ground that may already have been explored. NOT for recording a new learning (mma-journal-record), codebase questions (mma-investigate), or external research (mma-research).

Use when you've learned something worth remembering — a decision, design rationale, user behavior pattern, process learning, research finding, or style convention. Records it to the persistent team knowledge graph for future sessions.

Use when you have a spec file on disk and need a TDD implementation plan written by a worker — produces ordered tasks with complete code blocks, exact file paths, and verification commands

Use when you have structured design decisions ready and need a formal specification document written by a worker instead of consuming main-context tokens

Use first whenever you're about to delegate any tool-using work — picks the right mma-* skill (audit, review, debug, plan execution, codebase investigation, ad-hoc delegation, retry, context-block reuse) instead of defaulting to inline Agent dispatches

Claude Code command: /mma-breakout — spawn a named expert breakout teammate, keep the deep dialogue isolated, and close with one confirmed journal batch

Use when the user asks to audit a spec / plan / design doc / skill file. The `subtype` field picks the criteria set. `default` (prose-coherence) is the general doc auditor. `plan` verifies a code-execution plan against the actual codebase — run this before any `mma-execute-plan` dispatch. `spec` audits requirement prose for testability and decision-trace. `skill` audits a SKILL.md against reader-effectiveness criteria.

Use when you need external multi-source research with citations — arxiv, semantic_scholar, github_search, brave-with-site:-filters — for a focused question. Worker is bibliographic, not opinionated. Pair with mma-investigate (internal) under mma-explore for divergent landscape scans.

Use when a document larger than ~2 KB will be referenced by 2+ subsequent mma-* calls — register once, pass the returned ID to each call instead of re-uploading the same content. OR a spec / plan / error log was already inlined into one task and is about to be inlined into a second — register on the second reference, never the third.

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

Use when a test fails, a build breaks, or behavior is unexpected AND narrowing the root cause requires reading files, reproducing the failure, or tracing across multiple modules — the worker investigates so the main agent stays on the hypothesis

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

Use when a previous mma-* dispatch returned partial results (some tasks failed or came back incomplete) and you want to re-run JUST the failed indices without re-dispatching the whole task

Use when source code needs a quality / security / correctness pass — pre-merge review, post-implementation sanity check, or focused look at a small file set — and the review can run in parallel per file