plugins/ruflo-music/docs/adrs/0001-music-contract.md
ruflo-music (v0.1.0) wraps the cogmusic MCP server — a hand-rolled JSON-RPC
server at music.cognitum.one/mcp (source: cognitum-one/minimax-music,
services/gateway), reached locally via the cogmusic npm package (a thin
stdio↔HTTP bridge, packages/cogmusic in that repo). This is architecturally
different from most sibling plugins (e.g. ruflo-neural-trader), which wrap a
locally-executed npx <tool> CLI: there is no local compute here. Every real
generation runs on a remote GPU the user does not own or control, authenticated
by a personal access token (cogmcp_...) the user mints themselves at
music.cognitum.one/mcp. This plugin has no way to mint, rotate, or store that
token on the user's behalf — it can only tell them how, and register it locally
via claude mcp add.
list_productions, get_production, create_production, separate_stems,
extract_midi, master. By deliberate design (upstream ADR-0020), no tool
returns audio bytes inline over MCP — list_productions/get_production/
create_production carry an audio_url (upstream ADR-0022, added specifically
so an MCP agent, not just a human at a browser, can retrieve what it
generated) that requires a separate authenticated GET with the same PAT as
Authorization: Bearer. separate_stems/extract_midi/master have no
equivalent audio_url yet — their outputs are dashboard-only today. This is a
real, current gap in the upstream tool surface, not something this plugin can
work around; music-stems/music-midi say so explicitly rather than implying
a capability that doesn't exist.
The GPU inference service behind create_production/separate_stems/
extract_midi/master has a real, documented history of intermittent
cold-start failures (upstream ADR-0022/0023: a sharded model component
silently failing to load, root-caused and fixed across three iterations,
including one fix attempt that itself introduced a worse failure mode before
the actual working fix landed). As of this ADR the fix is deployed and verified
against a real generation. Every skill that calls a generation-class tool
documents "retry once before concluding something's wrong" as the expected,
honest behavior — not silent infinite retry, and not treating a single
transient failure as a hard error.
music-<intent>, per
ruflo-agentdb ADR-0001 §"Namespace convention"):
music-productions — cached production metadata (id, title, audio_url,
prompt, lyrics, duration, processing-step flags) for recall without a
round-trip to list_productions/get_production.music-briefs — the creative brief that produced each production,
keyed by production id, so "make another one like that" can retrieve the
exact prompt/lyrics shape that worked.
All access via memory_* (namespace-routed) — no agentdb_pattern-* or
agentdb_hierarchical-* calls with a namespace argument anywhere in this
plugin.ruflo-neural-trader's per-stage-agent pattern
doesn't fit — this pipeline has two real stages, not four): music-composer
(lyrics + style-prompt writing, no MCP tools) and music-producer (the
actual MCP-tool-driving pipeline entry point, delegates composition to
music-composer).music-connect) that no other sibling plugin needs an equivalent of,
because no other plugin's backing service requires a user-minted,
browser-only PAT.allowed-tools deliberately reference a non-ruflo-core MCP server.
Every sibling plugin's skills reference only mcp__plugin_ruflo-core_ruflo__*
tools (driving external work via Bash instead). This plugin's
music-generate/music-list/music-get/music-stems/music-midi/
music-master skills reference mcp__cogmusic__* directly — the tools of
whatever separately-registered MCP server the user named cogmusic via
claude mcp add cogmusic ... (see music-connect). This is a real, first
instance of the pattern in this marketplace, not an oversight: cogmusic
genuinely is a standalone MCP server the user registers themselves, not a
CLI this plugin shells out to. Live-verified working end to end in the
session that produced this ADR (create_production/list_productions/
get_production all called successfully against a real account).@claude-flow/cli v3.6 major+minor (same convention
as every sibling plugin), plus [email protected] or later specifically —
0.1.0 has no fetch timeout override and fails any create_production
call that runs past Node's ~5-minute undici default, which real generations
routinely do.scripts/smoke.sh — 10 structural checks: version + keywords; all 7
skills present with valid frontmatter; both agents present; command
present; README pins v3.6; README pins [email protected]+; namespace
coordination block present with both namespace claims; known-gap
disclosure (no audio bytes over MCP, stems/MIDI have no audio_url,
reliability history) present in README, not silently omitted; ADR exists
with status Proposed; no wildcard tool grants in any skill.Positive: the plugin is honest about what it can and cannot do — no-audio-bytes-over-MCP, no-stem/MIDI-audio_url, and the real reliability history are all documented rather than discovered the hard way by a future caller. The composer/producer split lets lyric quality improve independently of the MCP-plumbing logic.
Negative: two real, currently-unclosed gaps in the upstream tool surface
(no audio_url for stems/MIDI outputs) that this plugin cannot close on its
own — a future upstream ADR would need to extend the same PAT-authorized-URL
pattern ADR-0022 already established for the primary track to those two
derived-asset endpoints.
bash plugins/ruflo-music/scripts/smoke.sh
# Expected: "10 passed, 0 failed"
cognitum-one/minimax-music docs/adr/0020-mcp-server-and-connector-ui.md — why MCP tools are metadata-only by design, PAT auth schemecognitum-one/minimax-music docs/adr/0022-mcp-audio-url-via-pat.md — the audio_url pattern this plugin depends oncognitum-one/minimax-music docs/adr/0023-transformer-sharded-load-vs-gcsfuse.md — the inference-service reliability history disclosed aboveplugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md — namespace convention this ADR followsplugins/ruflo-neural-trader/docs/adrs/0001-neural-trader-contract.md — closest sibling precedent (external-tool-wrapping plugin contract), diverged from where the shape doesn't fit (local CLI vs. remote PAT-authed MCP server)