Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(plugin): add ruflo-music plugin for Cognitum Music (cogmusic MCP)

ruvd33ef4bf8ab2
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d21aaf8505..afac489f39 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -195,6 +195,11 @@
"name": "ruflo-business-pods",
"source": "./plugins/ruflo-business-pods",
"description": "Business-domain pod templates for the federated business autopilot (ADR-164 Phase 2) β€” pod templates plus a dry-run-by-default single-tick runner that validates, reserves budget, and resolves agent roles before posting to the BBS room"
+ },
+ {
+ "name": "ruflo-music",
+ "source": "./plugins/ruflo-music",
+ "description": "AI music generation via Cognitum Music (cogmusic MCP) β€” compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master through your own music.cognitum.one account"
}
]
}
diff --git a/plugins/ruflo-music/.claude-plugin/plugin.json b/plugins/ruflo-music/.claude-plugin/plugin.json
new file mode 100644
index 0000000000..fd7ba55fa1
--- /dev/null
+++ b/plugins/ruflo-music/.claude-plugin/plugin.json
@@ -0,0 +1,24 @@
+{
+ "name": "ruflo-music",
+ "description": "AI music generation via Cognitum Music (cogmusic MCP) β€” compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master through your own music.cognitum.one account",
+ "version": "0.1.0",
+ "author": {
+ "name": "ruvnet",
+ "url": "https://github.com/ruvnet"
+ },
+ "homepage": "https://github.com/cognitum-one/minimax-music",
+ "license": "MIT",
+ "keywords": [
+ "ruflo",
+ "music",
+ "cogmusic",
+ "cognitum",
+ "mcp",
+ "audio",
+ "generation",
+ "minimax-music3",
+ "stems",
+ "midi",
+ "mastering"
+ ]
+}
diff --git a/plugins/ruflo-music/README.md b/plugins/ruflo-music/README.md
new file mode 100644
index 0000000000..ff22e84bf4
--- /dev/null
+++ b/plugins/ruflo-music/README.md
@@ -0,0 +1,115 @@
+# ruflo-music
+
+AI music generation via [Cognitum Music](https://music.cognitum.one) β€” compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master, all through the `cogmusic` MCP server against your own Cognitum account.
+
+## Overview
+
+Wraps the `cogmusic` MCP bridge as a Ruflo plugin with 2 agents, 7 skills, and one dispatcher command. Unlike most sibling plugins, there's no locally-executed CLI runtime here β€” every real generation runs on a remote GPU inference service (MiniMax-Music3), reached over a hand-rolled MCP server your own account authenticates against with a personal access token you mint yourself.
+
+## Prerequisites
+
+- A Cognitum Music account at [music.cognitum.one](https://music.cognitum.one).
+- A `cogmcp_...` personal access token, minted at `music.cognitum.one/mcp` (sign in β†’ "Generate connection token"). Shown exactly once β€” copy it immediately. This plugin cannot mint or rotate this token for you.
+- `[email protected]` or later registered as an MCP server:
+ ```bash
+ claude mcp add cogmusic --env COGMUSIC_TOKEN=cogmcp_... -- npx -y cogmusic@latest
+ ```
+ `0.1.0` has no fetch timeout override and fails any `create_production` call that runs past Node's ~5-minute default β€” real generations routinely take longer. See the `music-connect` skill for the full setup flow.
+
+## Installation
+
+```bash
+claude --plugin-dir plugins/ruflo-music
+```
+
+## MCP Integration (6 Tools)
+
+`cogmusic` exposes 6 tools once registered:
+
+```bash
+claude mcp add cogmusic --env COGMUSIC_TOKEN=cogmcp_... -- npx -y cogmusic@latest
+claude mcp get cogmusic # expect: βœ” Connected
+```
+
+| Tool | Purpose |
+|------|---------|
+| `list_productions` | List saved productions (metadata + `audio_url` each) |
+| `get_production` | Fetch one production's current metadata + `audio_url` |
+| `create_production` | Generate a new track from lyrics + a style prompt (blocks for minutes) |
+| `separate_stems` | 4-stem separation (vocals/drums/bass/other) |
+| `extract_midi` | Pitch-tracked MIDI/score extraction |
+| `master` | LUFS loudness normalization + peak limiting |
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| `music-composer` | Writes structured lyrics + a genre/style prompt from a creative brief. Calls no MCP tools. |
+| `music-producer` | Pipeline entry point β€” delegates composition to `music-composer`, calls `create_production`, caches the result, optionally post-processes, reports the `audio_url`. |
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `music-connect` | One-time setup β€” register the `cogmusic` MCP server |
+| `music-generate` | Generate a track from a fully-specified brief |
+| `music-list` | List all productions in the account |
+| `music-get` | Fetch one production's metadata + `audio_url` |
+| `music-stems` | Run 4-stem separation on an existing production |
+| `music-midi` | Extract MIDI from an existing production |
+| `music-master` | Run a mastering (LUFS) pass on an existing production |
+
+## Commands
+
+```bash
+/music connect [--token cogmcp_...]
+/music generate <brief>
+/music list
+/music get <production-id>
+/music stems <production-id>
+/music midi <production-id>
+/music master <production-id>
+```
+
+## Known gaps (disclosed, not silently omitted)
+
+- **No audio bytes over MCP, by design.** Every tool that returns a production carries an `audio_url`, not the audio itself β€” always a separate authenticated `GET` with the same `cogmcp_` token as `Authorization: Bearer`.
+- **Stems and MIDI have no `audio_url` yet.** `separate_stems`/`extract_midi` confirm what was produced (`has_stems`/`has_midi` via `get_production`), but the derived audio/MIDI files are dashboard-only today β€” the PAT-authorized-URL pattern that already covers the primary track (see Architecture Decisions) hasn't been extended to these two endpoints upstream.
+- **The GPU inference service has a real reliability history.** Intermittent cold-start failures were root-caused and fixed upstream across three iterations (see ADR-0001's Related section) β€” a single retry resolves most transient failures; every generation-class skill documents this rather than treating a first failure as final.
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Runtime:** `[email protected]+` npm package (stdio↔HTTP MCP bridge) registered via `claude mcp add`; no local compute β€” generation runs on a remote GPU service you don't control.
+- **Verification:** `bash plugins/ruflo-music/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns two AgentDB namespaces (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)):
+
+| Namespace | Purpose |
+|-----------|---------|
+| `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 a later "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. Reserved namespaces (`pattern`, `claude-memories`, `default`) are never shadowed.
+
+## Verification
+
+```bash
+bash plugins/ruflo-music/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [ADR-0001](docs/adrs/0001-music-contract.md) β€” plugin contract: PAT auth model, `audio_url` delivery pattern, namespace claims, disclosed reliability posture.
+
+## Related Plugins
+
+- [ruflo-agentdb](../ruflo-agentdb) β€” namespace convention this plugin follows
+- [ruflo-neural-trader](../ruflo-neural-trader) β€” closest sibling precedent for an external-service-wrapping plugin contract (diverged where local-CLI vs. remote-PAT-authed-MCP-server shape doesn't fit)
+
+## License
+
+MIT
diff --git a/plugins/ruflo-music/agents/music-composer.md b/plugins/ruflo-music/agents/music-composer.md
new file mode 100644
index 0000000000..8f441b1219
--- /dev/null
+++ b/plugins/ruflo-music/agents/music-composer.md
@@ -0,0 +1,29 @@
+---
+name: music-composer
+description: Writes structured lyrics and a genre/style prompt from a creative brief (genre, mood, language, BPM, theme) for cogmusic's create_production tool
+model: sonnet
+---
+You write the two inputs `mcp__cogmusic__create_production` needs β€” `lyrics` and `prompt` β€” from whatever creative brief you're given. You do not call any MCP tools yourself; you hand your output to the `music-producer` agent (or directly back to whoever asked, when used standalone).
+
+### Lyrics
+
+- Structure with `[intro]` / `[verse]` / `[chorus]` / `[bridge]` / `[outro]` (and `[interlude]`/`[breakdown]`/`[drop]` for electronic genres) tags, one section heading per line, lyric lines below it.
+- Write in the language the brief asks for. If a language is named, actually write in it β€” don't fall back to English lyrics with a translated title. If no language is named, ask rather than assume, unless the genre itself strongly implies one (e.g. a fado brief implies Portuguese) and getting it right matters more than blocking on a question for a low-stakes creative request β€” use judgment.
+- A chorus reused verbatim across its repeats reads more like a real song than a chorus that drifts each time β€” repeat it exactly.
+- Match tone to genre: a dark house / dubstep brief wants short, punchy, chantable lines; a ballad wants more narrative lines; an instrumental-leaning genre (ambient, most EDM) can carry sparser, more chant/hook-style lyrics rather than a full narrative.
+- Keep total length proportional to the requested `audio_duration` β€” a 30-second clip doesn't need 4 verses.
+
+### Prompt (genre/style/instrumentation)
+
+One dense sentence: genre, BPM (pick something genre-appropriate if not specified β€” house ~120-128, dubstep ~140 or half-time ~70, ballad ~60-80, afrobeat ~110-120), specific instrumentation (name real instruments/techniques, not just "cool sounds" β€” "talking drum, shekere" beats "African percussion"), and the overall energy/mood. If the brief references another artist or track's *style* (a "remix" or "in the style of X" request), describe the sonic characteristics that implies (tempo, instrumentation, mood) rather than the artist's name alone β€” the generation model responds to concrete audio descriptors, not name-recognition.
+
+### Output
+
+Return exactly:
+```
+TITLE: <title>
+LYRICS:
+<the structured lyrics>
+PROMPT: <the one-sentence style prompt>
+DURATION: <suggested audio_duration in seconds>
+```
diff --git a/plugins/ruflo-music/agents/music-producer.md b/plugins/ruflo-music/agents/music-producer.md
new file mode 100644
index 0000000000..c33bf914d1
--- /dev/null
+++ b/plugins/ruflo-music/agents/music-producer.md
@@ -0,0 +1,19 @@
+---
+name: music-producer
+description: Drives the cogmusic MCP pipeline end to end β€” composes (via music-composer), generates, optionally post-processes (stems/MIDI/master), and reports a real audio_url. Pipeline entry point for /music generate
+model: sonnet
+---
+You turn a creative brief into a real, downloadable track through the user's own Cognitum Music account, using the `mcp__cogmusic__*` MCP tools directly (`create_production`, `get_production`, `list_productions`, `separate_stems`, `extract_midi`, `master`).
+
+### Pipeline
+
+1. **Check connectivity.** If `mcp__cogmusic__*` tools aren't loaded, stop and tell the user to run the `music-connect` skill first β€” you cannot register the MCP server yourself.
+2. **Compose.** Send the brief to the `music-composer` agent (or write the lyrics/prompt yourself if the brief already fully specifies them β€” no need to round-trip for a fully-specified request). Parse its `TITLE`/`LYRICS`/`PROMPT`/`DURATION` output.
+3. **Generate.** Call `mcp__cogmusic__create_production` with those fields. This blocks for real minutes β€” do not report back to the user or attempt other work mid-call; just wait for the result. On `isError: true` with "generation failed", retry once (see the reliability notes in the `music-generate` skill) before treating it as a real failure to report.
+4. **Cache.** Store the result in the `music-productions` and `music-briefs` memory namespaces (see `music-generate` skill's caching steps, and the plugin README's Namespace coordination section).
+5. **Post-process, only if asked.** Don't run `separate_stems`/`extract_midi`/`master` unless the user's brief asked for it (each is its own real GPU job on the same shared inference service β€” running it unprompted costs the user time and quota for nothing).
+6. **Report.** Title, duration, style summary (what was requested, not a claim about how it sounds), and the `audio_url` with a reminder that fetching it needs the same `Authorization: Bearer <cogmcp_ token>` header. Never claim to have "listened to" or "heard" the track β€” you generate it, you don't perceive audio.
+
+### Failure handling
+
+If generation fails twice in a row with the same inputs, say so plainly and mention it's very likely the shared GPU inference service, not the brief itself (see [ADR-0001](../docs/adrs/0001-music-contract.md)'s Known reliability notes) β€” don't silently keep retrying, and don't imply the user's request was somehow invalid.
diff --git a/plugins/ruflo-music/commands/music.md b/plugins/ruflo-music/commands/music.md
new file mode 100644
index 0000000000..4765b110f0
--- /dev/null
+++ b/plugins/ruflo-music/commands/music.md
@@ -0,0 +1,29 @@
+---
+name: music
+description: Generate, list, and process music via Cognitum Music (cogmusic MCP)
+---
+$ARGUMENTS
+Manage AI music generation via the `cogmusic` MCP server. Parse subcommand from $ARGUMENTS.
+
+Usage: /music <subcommand> [options]
+
+Subcommands:
+- `connect [--token cogmcp_...]` -- One-time setup: register the cogmusic MCP server (see `music-connect` skill)
+- `generate <brief>` -- Compose lyrics/prompt from a brief and generate a new track (see `music-composer` agent + `music-generate` skill)
+- `list` -- List all productions in the connected account (see `music-list` skill)
+- `get <production-id>` -- Fetch one production's metadata + audio_url (see `music-get` skill)
+- `stems <production-id>` -- Run 4-stem separation (see `music-stems` skill)
+- `midi <production-id>` -- Extract MIDI/score (see `music-midi` skill)
+- `master <production-id>` -- Run a mastering (LUFS) pass (see `music-master` skill)
+
+Steps by subcommand:
+
+**connect**: Follow the `music-connect` skill exactly. Do not skip the "check for an existing, working registration first" step.
+
+**generate**: If the brief needs real lyric/prompt composition (anything beyond a one-line genre tag), delegate to the `music-producer` agent, which itself defers lyric writing to the `music-composer` agent before calling `mcp__cogmusic__create_production`. For a fully-specified brief (explicit lyrics + prompt already given), the `music-generate` skill alone is enough β€” no need to spin up the agent pipeline for that case.
+
+**list**: Run the `music-list` skill directly β€” no agent needed for a read-only listing.
+
+**get / stems / midi / master**: Run the matching skill directly with the given `production-id`. Look it up via `music-list` first if the user gave a title instead of an id.
+
+If no `mcp__cogmusic__*` tools are loaded when any subcommand runs, run `connect` first and tell the user why.
diff --git a/plugins/ruflo-music/docs/adrs/0001-music-contract.md b/plugins/ruflo-music/docs/adrs/0001-music-contract.md
new file mode 100644
index 0000000000..1e1dbd79ed
--- /dev/null
+++ b/plugins/ruflo-music/docs/adrs/0001-music-contract.md
@@ -0,0 +1,126 @@
+---
+id: ADR-0001
+title: ruflo-music plugin contract β€” PAT auth, audio_url delivery, namespace claims, known reliability posture
+status: Proposed
+date: 2026-08-27
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, music, cogmusic, cognitum, mcp, namespace, smoke-test]
+---
+
+## Context
+
+`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`.
+
+### Six MCP tools, one real gap
+
+`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.
+
+### Known reliability history β€” disclosed, not glossed over
+
+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.
+
+## Decision
+
+1. **Namespace claims** (kebab-case `music-<intent>`, per
+ [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)):
+ - `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.
+2. **Two agents**, not four (`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`).
+3. **Seven skills** map directly onto the six MCP tools plus one setup skill
+ (`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.
+4. **`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).
+5. **Compatibility pin**: `@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.
+6. **`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.
+
+## Consequences
+
+**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.
+
+## Verification
+
+```bash
+bash plugins/ruflo-music/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `cognitum-one/minimax-music` `docs/adr/0020-mcp-server-and-connector-ui.md` β€” why MCP tools are metadata-only by design, PAT auth scheme
+- `cognitum-one/minimax-music` `docs/adr/0022-mcp-audio-url-via-pat.md` β€” the `audio_url` pattern this plugin depends on
+- `cognitum-one/minimax-music` `docs/adr/0023-transformer-sharded-load-vs-gcsfuse.md` β€” the inference-service reliability history disclosed above
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention this ADR follows
+- `plugins/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)
diff --git a/plugins/ruflo-music/scripts/smoke.sh b/plugins/ruflo-music/scripts/smoke.sh
new file mode 100755
index 0000000000..2e1b254899
--- /dev/null
+++ b/plugins/ruflo-music/scripts/smoke.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+step() { printf "β†’ %s ... " "$1"; }
+ok() { printf "PASS\n"; PASS=$((PASS+1)); }
+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+step "1. plugin.json declares 0.1.0 with expected keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.1.0" ]]; then bad "expected 0.1.0, got '$v'"; else
+ miss=""
+ for k in cogmusic cognitum mcp; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all 7 skills present with valid frontmatter"
+miss=""
+for s in music-connect music-generate music-list music-get music-stems music-midi music-master; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:' 'allowed-tools:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. both agents present"
+miss=""
+for a in music-composer music-producer; do
+ [[ -f "$ROOT/agents/$a.md" ]] || miss="$miss missing-$a"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. command present"
+[[ -f "$ROOT/commands/music.md" ]] && ok || bad "music command missing"
+
+step "5. README pins @claude-flow/cli to v3.6"
+grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \
+ && ok || bad "v3.6 pin missing"
+
+step "6. README pins cogmusic runtime version"
+grep -qE "cogmusic@0\.1\.1" "$ROOT/README.md" \
+ && ok || bad "[email protected]+ pin missing"
+
+step "7. Namespace coordination block claims both namespaces"
+F="$ROOT/README.md"
+grep -q "Namespace coordination" "$F" \
+ && grep -q "music-productions" "$F" \
+ && grep -q "music-briefs" "$F" \
+ && ok || bad "namespace coordination block incomplete"
+
+step "8. known gaps disclosed (no audio bytes over MCP, no stem/MIDI audio_url, reliability history)"
+F="$ROOT/README.md"
+miss=""
+grep -qi "audio_url" "$F" || miss="$miss audio_url"
+grep -qi "stems and midi have no" "$F" || miss="$miss stems-midi-gap"
+grep -qi "reliability history" "$F" || miss="$miss reliability-history"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-music-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "10. no wildcard tool grants in skills"
+bad_skills=""
+for f in "$ROOT"/skills/*/SKILL.md; do
+ grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
+done
+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-music/skills/music-connect/SKILL.md b/plugins/ruflo-music/skills/music-connect/SKILL.md
new file mode 100644
index 0000000000..720153e573
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-connect/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: music-connect
+description: One-time setup β€” mint a Cognitum Music personal access token and register the cogmusic MCP server with Claude Code
+allowed-tools: Bash WebFetch
+argument-hint: "[--token cogmcp_...]"
+---
+
+# Music Connect
+
+Wires this session up to the user's own Cognitum Music account (music.cognitum.one) via the `cogmusic` MCP bridge. This is a one-time, per-machine/per-project setup β€” run it before any other `music-*` skill if `mcp__cogmusic__*` tools aren't already loaded.
+
+## When to use
+
+- The user asks to generate/produce music and no `mcp__cogmusic__*` tools are visible yet.
+- `claude mcp get cogmusic` reports the server missing, disconnected, or unhealthy.
+- The user is rotating or replacing an expired/revoked token.
+
+## Steps
+
+1. **Check for an existing, working registration first**:
+ ```bash
+ claude mcp get cogmusic
+ ```
+ If it reports `βœ” Connected`, you're already set up β€” stop here.
+
+2. **If no token was provided**, tell the user exactly how to mint one (this step requires their own browser login β€” you cannot do it for them):
+ - Sign in at `https://music.cognitum.one/mcp`
+ - Click "Generate connection token" (label it something recognizable, e.g. "Claude Code")
+ - Copy the raw token β€” it starts with `cogmcp_` and is shown **exactly once**
+
+3. **Register the MCP server** once you have the token (never print the full token back to the user in plain chat if avoidable β€” treat it as a secret; it's fine as a one-time argument to `claude mcp add`, which stores it in local config, not in conversation history):
+ ```bash
+ claude mcp add cogmusic --env COGMUSIC_TOKEN=cogmcp_... -- npx -y cogmusic@latest
+ ```
+ Pin to `[email protected]` or later β€” earlier `0.1.0` has no fetch timeout and fails
+ `create_production` calls that run past Node's ~5-minute default (see
+ [ADR-0001](../../docs/adrs/0001-music-contract.md)).
+
+4. **Verify**:
+ ```bash
+ claude mcp get cogmusic
+ ```
+ Expect `βœ” Connected`. If it shows `CONNECTION_CLOSED` or a 404, the `cogmusic` npm package version pinned in the command may be stale or unpublished β€” check `npm view cogmusic version` and retry with an explicit version.
+
+5. **If registration already exists but is unhealthy**, remove and re-add rather than editing config by hand:
+ ```bash
+ claude mcp remove cogmusic -s local
+ claude mcp add cogmusic --env COGMUSIC_TOKEN=cogmcp_... -- npx -y cogmusic@latest
+ ```
+
+6. Once connected, the `mcp__cogmusic__*` tools (`list_productions`, `get_production`, `create_production`, `separate_stems`, `extract_midi`, `master`) become available β€” proceed to `music-generate` or `music-list`.
+
+## Notes
+
+- The token is a personal access token (PAT) scoped to one Cognitum account, minted and revoked by the user themselves at `music.cognitum.one/mcp` β€” this plugin has no way to mint or revoke one programmatically, and should never attempt to guess, cache elsewhere, or transmit it anywhere other than the local `claude mcp add` registration.
+- A newly-registered MCP server's tools may not appear until the *next* Claude Code session β€” if `mcp__cogmusic__*` tools still aren't listed after a successful `claude mcp get cogmusic`, tell the user to start a fresh session.
diff --git a/plugins/ruflo-music/skills/music-generate/SKILL.md b/plugins/ruflo-music/skills/music-generate/SKILL.md
new file mode 100644
index 0000000000..5a5603d985
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-generate/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: music-generate
+description: Generate a new song from a creative brief (genre, mood, language, BPM, theme) via the cogmusic MCP create_production tool
+allowed-tools: mcp__cogmusic__create_production mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search
+argument-hint: "<brief describing genre/mood/language/theme>"
+---
+
+# Music Generate
+
+Turns a creative brief into a real, playable track through the user's own Cognitum Music account.
+
+## When to use
+
+The user asks to create/generate/produce a song, remix, or track. If `mcp__cogmusic__create_production` isn't loaded, run `music-connect` first.
+
+## Steps
+
+1. **Compose the two required inputs** from the brief (delegate the actual writing to the `music-composer` agent for anything beyond a trivial brief β€” lyrics quality matters more than most callers expect):
+ - `lyrics` β€” structured with `[intro]`/`[verse]`/`[chorus]`/`[bridge]`/`[outro]` tags, one section per line group. Match the language the user asked for; don't default to English if they named another language.
+ - `prompt` β€” genre, BPM, instrumentation, and mood in one dense sentence. Be specific (e.g. "Afrobeat, 116 BPM, talking drum, shekere, horn section" beats "upbeat African music").
+
+2. **Pick `audio_duration`** (seconds, default 30 if unspecified). 90–150s covers a real verse/chorus/bridge structure; don't go far past 150s without the user asking β€” generation time and cost both scale with duration, and the model's documented ceiling is 300s.
+
+3. **Call the tool** β€” it blocks for real minutes, not seconds:
+ ```
+ mcp__cogmusic__create_production({
+ title: "...",
+ lyrics: "...",
+ prompt: "...",
+ audio_duration: 120,
+ })
+ ```
+ Do not poll or retry mid-call β€” the underlying bridge (`[email protected]+`) already carries a long internal timeout. If it returns `{"content":[{"text":"generation failed", ...}],"isError":true}`, this is very likely a transient GPU-inference-service issue (see [ADR-0001](../../docs/adrs/0001-music-contract.md)'s Known reliability notes), not a bad prompt β€” retry once before concluding something is actually wrong with the request itself.
+
+4. **On success**, the result includes `id`, `title`, `audio_duration`, `created_at_unix`, and an `audio_url`. Fetch the audio itself (or hand the URL to the user) with:
+ ```bash
+ curl -H "authorization: Bearer $COGMUSIC_TOKEN" "$AUDIO_URL" -o track.wav
+ ```
+ Audio is never returned inline over MCP by design (see ADR-0001) β€” always a separate authenticated GET.
+
+5. **Cache the result** for later recall (namespace `music-productions`, see the plugin README's Namespace coordination section):
+ ```
+ mcp__plugin_ruflo-core_ruflo__memory_store({
+ key: "production-<id>",
+ value: JSON.stringify({ id, title, audio_url, prompt, lyrics, audio_duration, created_at_unix }),
+ namespace: "music-productions",
+ })
+ ```
+ Also store the brief that produced it (namespace `music-briefs`) so a later "make another one like that" can retrieve the exact prompt/lyrics shape that worked:
+ ```
+ mcp__plugin_ruflo-core_ruflo__memory_store({
+ key: "brief-<id>",
+ value: JSON.stringify({ id, brief: "<the user's original request>", prompt, lyrics }),
+ namespace: "music-briefs",
+ })
+ ```
+
+6. **Report back**: title, duration, the `audio_url`, and a one-line summary of the style. Don't claim the audio "sounds like X" β€” you cannot hear it; describe what was requested, not the result.
+
+## Known reliability notes
+
+The GPU inference service behind Cognitum Music has a real, documented history of intermittent generation failures (cold-start weight-loading races β€” see the upstream repo's ADR-0022/0023). A single retry resolves most transient failures. If two consecutive attempts with the *same* prompt/lyrics both fail, say so plainly rather than silently retrying a third time β€” that's a signal something's actually wrong on the service side, not bad luck.
diff --git a/plugins/ruflo-music/skills/music-get/SKILL.md b/plugins/ruflo-music/skills/music-get/SKILL.md
new file mode 100644
index 0000000000..3f85fab8c6
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-get/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: music-get
+description: Fetch metadata and audio_url for a single production by id
+allowed-tools: mcp__cogmusic__get_production mcp__plugin_ruflo-core_ruflo__memory_retrieve mcp__plugin_ruflo-core_ruflo__memory_search
+argument-hint: "<production-id>"
+---
+
+# Music Get
+
+Looks up one production's current state β€” useful to check whether a `separate_stems`/`extract_midi`/`master` call from earlier in the session actually finished.
+
+## When to use
+
+You have a production `id` (from `music-generate`'s result, `music-list`, or the `music-productions` memory cache) and need its latest metadata.
+
+## Steps
+
+1. Check the `music-productions` namespace cache first if you're only after fields that don't change (title, original prompt/lyrics, `audio_duration`) β€” no need to round-trip if you already have them.
+2. For anything that *can* change (`has_stems`, `has_midi`, `has_mastered`, `lufs_before`/`lufs_after`), call the live tool:
+ ```
+ mcp__cogmusic__get_production({ id: "<production-id>" })
+ ```
+3. If the `id` doesn't exist or belongs to a different account, the call errors β€” don't guess at a substitute id; ask the user to confirm it or run `music-list` to find the right one.
diff --git a/plugins/ruflo-music/skills/music-list/SKILL.md b/plugins/ruflo-music/skills/music-list/SKILL.md
new file mode 100644
index 0000000000..13f74ad014
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-list/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: music-list
+description: List the account's saved music productions with metadata and audio_url
+allowed-tools: mcp__cogmusic__list_productions mcp__plugin_ruflo-core_ruflo__memory_store
+argument-hint: ""
+---
+
+# Music List
+
+Surfaces every production in the connected Cognitum Music account.
+
+## When to use
+
+The user asks what tracks exist, wants to find a track by title, or you need a production `id` for `music-get`/`music-stems`/`music-midi`/`music-master` and don't already have it.
+
+## Steps
+
+1. Call `mcp__cogmusic__list_productions({})` β€” no arguments.
+2. Present results sorted by `created_at_unix` descending (the API already returns them this way): title, duration, `id`, and which processing steps have run (`has_stems`/`has_midi`/`has_mastered`).
+3. If the user is looking for a specific track, match on `title` (case-insensitive substring) rather than asking them to know the `id` up front.
+4. Optionally refresh the `music-productions` memory cache for any entries not already stored there (see `music-generate`'s caching step) β€” useful after a production was created outside this session (e.g. from the web dashboard).
+
+## Notes
+
+This never returns audio bytes β€” only metadata plus each production's `audio_url` for a follow-up authenticated GET. See [ADR-0001](../../docs/adrs/0001-music-contract.md).
diff --git a/plugins/ruflo-music/skills/music-master/SKILL.md b/plugins/ruflo-music/skills/music-master/SKILL.md
new file mode 100644
index 0000000000..3d9cda5454
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-master/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: music-master
+description: Run a mastering pass (LUFS loudness normalization + peak limiting) on an existing production
+allowed-tools: mcp__cogmusic__master mcp__cogmusic__get_production mcp__plugin_ruflo-core_ruflo__memory_store
+argument-hint: "<production-id>"
+---
+
+# Music Master
+
+Applies loudness normalization (default target -14 LUFS, common streaming-platform standard) plus a peak limiter to an already-generated production.
+
+## When to use
+
+The user wants a "radio-ready" or streaming-normalized version of a track they've already generated.
+
+## Steps
+
+1. Call `mcp__cogmusic__master({ id: "<production-id>" })`.
+2. The result includes `lufs_before` and `lufs_after` β€” report both so the user can see the actual loudness change, not just "done."
+3. Update the cached entry in `music-productions` (if one exists) with the new `lufs_before`/`lufs_after`/`has_mastered: true` fields so later lookups don't need a round-trip.
+4. Mastered audio isn't returned inline over MCP β€” point the user at the dashboard. See [ADR-0001](../../docs/adrs/0001-music-contract.md).
diff --git a/plugins/ruflo-music/skills/music-midi/SKILL.md b/plugins/ruflo-music/skills/music-midi/SKILL.md
new file mode 100644
index 0000000000..a60d1db469
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-midi/SKILL.md
@@ -0,0 +1,20 @@
+---
+name: music-midi
+description: Extract MIDI/score from an existing production
+allowed-tools: mcp__cogmusic__extract_midi mcp__cogmusic__get_production
+argument-hint: "<production-id>"
+---
+
+# Music MIDI
+
+Runs pitch-tracked MIDI/score extraction on an already-generated production.
+
+## When to use
+
+The user wants a MIDI file or score from a track they've already generated (transcription, arranging, DAW import). Needs an existing production `id`.
+
+## Steps
+
+1. Call `mcp__cogmusic__extract_midi({ id: "<production-id>" })`. Real GPU work, same reliability profile as `music-stems` and `music-generate` β€” one retry on a transient failure is reasonable before treating it as broken.
+2. Confirm via `mcp__cogmusic__get_production` that `has_midi` is now `true`.
+3. Like stems, the MIDI file itself isn't returned inline over MCP today β€” point the user at the dashboard to download it. See [ADR-0001](../../docs/adrs/0001-music-contract.md).
diff --git a/plugins/ruflo-music/skills/music-stems/SKILL.md b/plugins/ruflo-music/skills/music-stems/SKILL.md
new file mode 100644
index 0000000000..f28ed9fc72
--- /dev/null
+++ b/plugins/ruflo-music/skills/music-stems/SKILL.md
@@ -0,0 +1,20 @@
+---
+name: music-stems
+description: Run 4-stem separation (vocals/drums/bass/other) on an existing production
+allowed-tools: mcp__cogmusic__separate_stems mcp__cogmusic__get_production
+argument-hint: "<production-id>"
+---
+
+# Music Stems
+
+Splits an already-generated production into vocals/drums/bass/other stems.
+
+## When to use
+
+The user wants isolated stems from a track they've already generated (remixing, karaoke tracks, sampling). Needs an existing production `id` β€” run `music-list` first if you don't have one.
+
+## Steps
+
+1. Call `mcp__cogmusic__separate_stems({ id: "<production-id>" })`. This is a real GPU job β€” it takes real time, similar order of magnitude to generation itself, and shares the same underlying inference service as `create_production` (see the reliability notes in `music-generate`'s SKILL.md β€” a transient failure is worth one retry before concluding something's wrong).
+2. **This does not return audio.** The result only confirms which stems were produced. Check `has_stems` via `mcp__cogmusic__get_production` afterward, then point the user at the dashboard (`music.cognitum.one`) to actually listen β€” per [ADR-0001](../../docs/adrs/0001-music-contract.md), the current cogmusic MCP tool surface doesn't expose a stem-level `audio_url` the way the primary production audio has one (only the main track's URL is PAT-authorized today).
+3. If the user specifically needs the stem *bytes* delivered back through this session rather than via the dashboard, say so plainly β€” that's a real gap in the current MCP surface, not something this skill can work around.