Concepts

Muster is a glass-box, multi-runtime, multi-domain agentic orchestrator. This page covers the ideas that make it work. For the full source-level map, see Architecture.

Glass-box

Glass-box is the design constraint that shapes everything else. Every routing decision is inspectable: which role resolved to which provider, on which model, and why. Before any work starts, Muster shows a crew manifest and a plan. Nothing is hidden behind a single opaque prompt.

Two layers

Muster is split into two layers with a hard boundary between them.

Layer	Lives in	Runtime	Talks to a model?
Deterministic CLI	src/*.js	Plain Node ESM	No
Model-facing	plugin/ (commands, skills, agents)	Claude Code	Yes

The CLI layer is ordinary Node with two runtime dependencies, yaml and esbuild. It does the deterministic work: detecting the project, resolving roles to providers, ranking candidates, scoring artifacts against a gate, computing prioritization math, validating pipelines. Anything that can be answered by code is answered by code.

The model-facing layer is markdown that Claude Code loads as a plugin. It instructs the model how to drive a run, calling the CLI for every deterministic decision and using Claude Code's subagent dispatch for the judgment work.

Routing, scoring, and validation are reproducible because code owns them. Drafting, reviewing, and classifying are the model's job.

Roles and the resolution ladder

Muster names a fixed vocabulary of roles, the kinds of work a crew might need (implement, code-review, test-author, debug, security-review, author, research, score, humanize, prompt-quality, improve, image, video, lifecycle, and more — 26 in all). Roles are the stable interface: pipelines and commands ask for a role, not for a specific tool.

Each role resolves through a ladder of provider sources, best available first:

1. An installed external provider (a plugin, agent, or MCP server you already have)
2. A Muster built-in agent
3. A Muster built-in skill
4. Inline (the model does it directly, no specialist attached)

Because the ladder always terminates at inline, every role resolves to something. Muster works on bare Claude Code and gets better as you install more tools.

npx -y @adnova-group/muster capabilities

For each role this reports chosen (the winner), chain (the full fallback list, always ending in inline), recommendations (installable providers that would beat the current fallback), and model.

Description-search

The role enum is fixed, but the set of providers is not, and some specialists do not map cleanly onto a named role. The escape hatch is description-search: a deterministic token-overlap ranker, no LLM call.

npx -y @adnova-group/muster match "audit this code for security vulnerabilities"

It tokenizes the task, scores every catalog provider by overlap (id, roles, and keywords weighted high; the free-text description weighted low), and boosts installed providers so a present tool edges out an equal-scoring fallback. That is how a task surfaces the right specialist even when it never names a role.

Per-role model selection

Each resolved role carries a model picked to fit the work, so quota spend tracks difficulty.

Tier	Roles	Why
scout	code-navigation, docs-research, research	Mechanical locating, gathering, and scanning
core	everything else (the default)	Implementation, review, authoring, and scoring
prime	fallback for apex	Frontier judgment when apex is disabled
apex	the tournament judge, architecture-review, improve, advisor	Rare peak judgment

Harness adapters map the conceptual scout, core, prime, and apex ladder to concrete models.

Compatibility only: legacy input aliases haiku, sonnet, opus, and fable normalize to scout, core, prime, and apex; they are not a second conceptual ladder. MUSTER_ENABLE_FABLE remains an alias for MUSTER_ENABLE_APEX.

The conceptual tier is reported as roles[<role>].model; the orchestrator passes the adjacent harness-concrete model as the dispatch override when it spawns each subagent.

Provider kinds

A provider resolves to one of four kinds, which decides how it is dispatched:

• agent: a subagent definition — dispatched by subagent_type on Claude Code, and through its installed agent_type profile with a bounded context fork on Codex.
• skill: a markdown skill injected into a generic subagent.
• mcp: an installed MCP server, surfaced as a tool.
• inline: no specialist; the model does the work directly.

What happens when a role resolves to an agent whose type is not dispatchable in the running session (for example, plugin agents installed mid-session, before a restart) depends on the harness:

• On Claude Code, the orchestrator falls back to a generic subagent with the resolved provider's brief injected, and records the fallback in the run STATE. The model override still applies, so model selection is never lost on the fallback.
• On Codex, there is no fallback: a non-dispatchable agent profile fails closed with a reinstall/new-session diagnostic, because a generic Codex subagent would silently lose the profile's pinned role and model policy. See Architecture.

Next: The ten modes.