@adnova-group/muster

Muster

Glass-box, multi-domain agentic orchestrator for Claude Code. Give it an outcome; it assembles the right crew and shows its reasoning before it acts.

📖 Documentation: adnova-group.github.io/muster

What it is

Muster turns an outcome into finished work. It detects your project, discovers the capabilities you already have installed, picks the best tool for each piece of the job, and runs a crew of specialists toward your success criteria. Every decision is inspectable: which role resolved to which provider, on which model, and why.

It runs on bare Claude Code with no extra services and no separate model API, and it gets better as you install more tools. The work is not limited to code. Product, business, content, and operations are first-class.

Quickstart

npx -y @adnova-group/muster install

install mutates nothing in your ~/.claude. It just prints the steps it cannot do for you, because registering a plugin is a Claude Code action:

/plugin marketplace add Adnova-Group/muster  # register the marketplace
/plugin install muster@muster                # install the plugin

Muster's glass-box output style ships inside the plugin and applies automatically when the plugin is enabled (force-for-plugin), so there is no command to run. Plugin install is a Claude Code action, so the running session picks Muster up only after you (re)install it through /plugin. Restart or /clear, then run your first outcome:

/muster:run Add rate limiting to the public API with tests

The seven modes

Mode	Command	What it does
Run	/muster:run <outcome>	Plans, shows the crew manifest and plan (tasks may carry owns/frozen/forbiddenActions fences and the manifest an overall mergeDisposition), then stops for your approval. Approve & run chains into autopilot in-session; Adjust and Cancel stay plan-only.
Autopilot	/muster:autopilot <outcome>	Hands-off lifecycle: branch, route, run waves, commit per wave, present the merge. Stops only for the merge decision or an escalation.
Diagnose	/muster:diagnose <symptom>	Failure-first bug fix: reproduce, find root cause, fix, add a regression test, verify. No symptom-patching.
Audit	/muster:audit [path]	Breadth-first whole-codebase review and fix across six dimensions (seven when the project builds prompts or agents), then fixes everything with tests and verifies.
Sprint	/muster:sprint <backlog ref>	Batch verb: runs the full autopilot lifecycle sequentially over every item in a backlog, ticking each off as it completes, re-resolving the backlog after each item (drain mode) so newly added items join the running batch. An escalated item never aborts the sprint; one attended stop at the end for the batch report.
Runner	/muster:runner [source]	Unattended one-cycle work-picker for a Claude Code Routine or cron: resumes an answered blocked item or claims exactly one available item, drives it through the full autopilot lifecycle force-coerced to a pr disposition, leaves a receipt, and stops. The schedule provides the loop, not the verb.
Capture	/muster:capture [hint]	Conversation-to-backlog generator: mines the session's discussion (findings, decisions, review residuals, an explicit directive) into backlog items via the same extract/validate/dedupe/write machinery, gated by your approval before anything is written. Writes only .muster/backlog.md -- it never assembles a crew or runs work itself.

Run and Autopilot accept a GitHub issue reference (a bare number, #123, or an issues URL) as the outcome. A thin outcome gets refined first: muster assess does a deterministic gap-check, and if the outcome is vague, an interview skill asks one question at a time behind an approval gate before any crew is assembled. An outcome that decomposes into independent parts can instead be written to a sprint backlog (.muster/backlog.md) for /muster:sprint to run as a batch; /muster:audit backlog [path] fills the same backlog from audit's findings, sweeping read-only instead of fixing them inline; /muster:capture [hint] fills it a third way, mining a conversation's findings and decisions instead of an audit sweep or an interview decomposition. A backlog item annotated with {id}/{deps} switches /muster:sprint into wave mode: pr/keep items in a wave dispatch as parallel worktree-isolated runners capped by MUSTER_SPRINT_PARALLEL, while merge-local/merge-push items serialize at the wave barrier. Sprint and Runner share a coordination skill (claim/receipt/ledger discipline) so a scheduled Runner and an attended Sprint can safely work the same backlog or issues:<label> at once.

How it works

The novel core is a capability and domain router. Muster names a fixed vocabulary of roles (the kinds of work a crew might need), and each role resolves through a ladder, best available first:

• An installed external provider (a plugin, agent, or MCP server you already have)
• A Muster built-in agent
• A Muster built-in skill
• Inline (the model does it directly)

muster capabilities walks this ladder for every role and reports the winner, the full fallback chain, installable recommendations, and the chosen model. Because the chain always ends at inline, every role resolves to something, so Muster works on bare Claude Code and improves as you add tools.

The role set is fixed but the provider set is not. When an outcome does not fit a named role, description-search bridges the gap: muster match "<task>" ranks every catalog provider by deterministic token overlap (no model call), so "audit this code for security vulnerabilities" surfaces the security specialist even though it never names a role.

Each role also carries a model picked to fit the work: mechanical roles run on Haiku, the default is Sonnet, and heavy judgment runs on Fable (degrades to Opus when unavailable on the plan). Muster composes the tools you already have and falls back to its own. For the full design, see the architecture reference (or docs/architecture.md in-repo).

Always-on guidance

Muster ships four plugin-native hooks that work together to keep the session anchored:

• SessionStart: prepends muster's working principles, the six verbs, a one-line project detect, and the default-routing directive at the start of every session, so the session opens with full context and a clear posture for routing actionable prompts through muster. Capture is deliberately not among the six -- it is a backlog generator, not a routed outcome-runner (see The seven modes).
• UserPromptSubmit: fires before each user turn and re-injects a short drift-reinforcement nudge every N turns (default 3) and the full principles payload every N*K turns (default 9), so the session does not revert to default inline Claude behavior over time. A directive-shaped prompt (an imperative verb like fix/build/implement, optionally after a polite lead-in; declaratives like "Update:"/"Fix for" and questions are excluded) also fires the routing-policy reminder immediately the first time it lands with no active muster run -- once per session, then never again until /clear re-arms it -- independent of the periodic cadence above.
• PreToolUse: wave-guard + post-run scale gate + action-class fence. While a wave is active (.muster/wave-active present), denies main-loop Edit/Write/NotebookEdit and Bash file-write patterns so the orchestrator's iron rule (dispatch via Agent tool, never edit inline) is enforced at the harness level. After a run ends (no marker), the advisory nudge alone can't stop drift, so a per-turn scale gate denies the 3rd distinct inline file write in a single turn (MUSTER_INLINE_SCALE, default 3), counting both editor tools and high-confidence Bash writes so the shell path isn't an escape hatch. Trivial 1-2 file turns fall through; orchestration-scale work is routed back to a verb. A cumulative cross-turn counter tracks distinct inline-edited files across turns too (not just within a turn), warning once per session (never denying) once the running total reaches the same threshold -- catching careful 1-2-file-per-turn drift the per-turn gate never sees; it survives /compact and resume, and resets at SessionStart (fresh session / /clear) and while a run is active. Independently of wave state, whenever .muster/run-active and .muster/forbidden-actions both exist, the same hook classifies the tool call against the manifest's declared forbiddenActions (send/sign/submit/publish/purchase/delete-remote) and denies a match, honoring MUSTER_ACTION_GUARD (off/warn/deny-by-default); the wave-guard, scale-gate, and action-fence checks all honor their own guard variables independently.
• PreToolUse on Task/Agent (todo-driving gate): during a live run (.muster/run-active present), denies a subagent-wave dispatch unless a native todo list was written since the run started, so plan progress stays visible in Claude Code's todo UI. Biased hard toward allow -- any uncertainty (missing marker, unreadable transcript, unreadable timestamps) allows; honors MUSTER_TODO_GATE (off/warn/deny).

All four hooks live inside the plugin, so they activate when muster is enabled and go away when muster is disabled. They do not write to your ~/.claude/CLAUDE.md or settings.json and create no global files. Each hook is fail-safe: any error falls back to an empty result and never blocks a session from starting.

Pipelines

A pipeline is a phased, gated recipe for producing one kind of artifact. Each declares a domain, an ordered list of phases, and a gate. Gating uses a floor principle: the weakest dimension must clear the floor and the total must clear a pass threshold, so a strong average cannot rescue one weak dimension.

The set spans software and knowledge work. A few examples: PRD, business-case, launch-plan, executive-summary, OKRs, AI implementation spec, competitive-battlecard, blog-post, case-study, runbook, video-content, and book (fiction and non-fiction). Roadmap prioritization is one to call out: goals go in, and a RICE-ranked now/next/later roadmap comes out, with the model estimating the factors and the CLI doing the arithmetic. Human-facing pipelines end with a humanize phase that strips em-dashes, AI-tell words, and robotic cadence. Content pipelines that name an audience or a voice resolve a named profile from docs/profiles/AUDIENCES.md/VOICE.md (creating or extending it on first use) and calibrate depth/jargon/altitude and register/rhythm to it; a docs/profiles/BRAND.md anchors image-prompt and publish-phase visuals to a shared palette.

Prompt evaluation

Muster can lint, eval, and optimize prompts, including the prompts an application generates at runtime to build agents and agentic workflows, and prompts found in a codebase Muster is working in. The deterministic core runs offline; a built-in skill (muster-prompt-smith, the prompt-quality role) supplies the model calls for empirical eval.

• Lint (muster prompt lint <file|->) is a no-LLM structural check that enforces Anthropic's best practices (role, XML tags, multishot examples, explicit output format, positive framing) and the agent/guardrail rules (imperative tool framing, stop conditions, "I don't know" allowance, citations, input separation). Every finding cites the doc rule it comes from and suggests a fix; the rubric is gated by the same floor principle as pipelines. Pass --agent --tools for runtime agent prompts.
• Eval (muster prompt eval <suite.json>) grades outputs against a test dataset with code graders (json/regex/python) plus an LLM-judge, and reports accuracy.
• Optimize (muster prompt variations then muster prompt optimize) generates technique-driven variations, re-scores them, and keeps the winner via the tournament floor, flagging a regression when nothing beats the baseline.
• Scan (muster prompt scan <dir>) walks a repo for prompts (markdown skill/agent/command docs, .prompt files, code assignments) and lints each; it powers the conditional prompt-quality audit dimension.

The linter is genre-aware (--system relaxes task-only rules for instruction prompts), ignores code fences across languages, and lets a prompt opt out of a rule inline (<!-- prompt-lint-disable RULE: reason -->). A prompt with zero findings scores a perfect 15/15.

# lint a runtime agent prompt piped straight from your app
your-app --print-agent-prompt | npx @adnova-group/muster prompt lint - --agent --tools

See the commands reference for the full surface.

Configuration

Muster's runtime behavior can be tuned with environment variables:

Variable	Default	Semantics
MUSTER_NUDGE_EVERY	3	Inject a short drift-reinforcement nudge every N turns.
MUSTER_PRINCIPLES_EVERY	3	Inject the full principles + verbs every N*K turns (K = this value; at defaults: nudge every 3, full every 9).
MUSTER_WAVE_GUARD	deny	PreToolUse hook enforcement while a wave is active: deny blocks inline edits, warn allows with a reminder, off disables the guard.
MUSTER_MAX_TIER	(unset)	Caps the model tier policy (e.g. opus disables Fable, sonnet for budget mode); unset = no cap. Note: static agent frontmatter pins (e.g. muster-strategist) are not affected on direct invocation; in muster runs the dispatch override honors the cap.
MUSTER_ENABLE_FABLE	(unset)	Opts back into the Fable tier for peak-judgment roles (the tournament judge, architecture-review, improve, advisor). Unset (or 0/false) degrades Fable to Opus deterministically, since the tier can be disabled platform-wide; 1/true re-enables it once the tier is available.
MUSTER_INLINE_SCALE	3	Post-run scale gate threshold. The Nth distinct file write in a single turn with no active wave is denied and routed to a verb (1-2 file turns fall through). Also the cumulative cross-turn threshold: the same count of distinct files edited inline across turns with no active run triggers a one-time per-session warning.
MUSTER_TODO_GATE	deny	Todo-driving gate on Task/Agent dispatch during a live run: deny blocks a subagent-wave dispatch until a native todo list is written, warn allows with a note, off disables the gate.
MUSTER_ACTION_GUARD	deny	Action-class fence on PreToolUse while .muster/forbidden-actions is present: deny blocks a matching send/sign/submit/publish/purchase/delete-remote tool call, warn allows with a reminder, off disables the fence.
MUSTER_ADVISOR_MAX_CONSULTS	3	Maximum advisor consults per run. Bounds the cost of workers escalating to the advisor role. Set to 0 to disable advisor consults.
MUSTER_FUSE_TOPK	3	Maximum number of tournament candidates passed to the fusion synthesizer. Must be >= 1.
MUSTER_FUSE_MIN_DISAGREEMENT	1	Minimum disagreement score required to activate fusion synthesis. Below this threshold muster fuse falls back to the single best candidate. Set to 0 to always fuse when >= 2 candidates pass.
MUSTER_SPRINT_PARALLEL	3	Max concurrent item-runner subagents per wave in /muster:sprint wave mode; hard ceiling 8 (higher values clamp, 0 is invalid; concurrency is never unbounded). Read by the sprint mode's orchestration protocol, not by library code.

Built on

Muster's design was inspired by atomic-claude, superpowers, and gsd-core. It vendors a curated set of MIT-licensed skills and agents, with every source and item recorded for attribution:

Source	License	Provides
obra/superpowers	MIT	Brainstorming, planning, TDD, code-review, debugging, verification skills
wshobson/agents	MIT	Software and knowledge-work agents across many specialties
open-gsd/gsd-core	MIT	Plan, execute, and verify workflow phases

Alongside the vendored material, Muster ships its own clean-room specialists, authored fresh from the role concept. Full provenance lives in NOTICE.

Contributing and license

Contributions are welcome. See CONTRIBUTING.md to get started.

Muster is licensed under Apache-2.0. See LICENSE and NOTICE.