π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(plugin): add ruflo-music plugin for Cognitum Music (cogmusic MCP)
ruvd33ef4bf8ab2
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 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.jsonnew file mode 100644index 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.mdnew file mode 100644index 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++MITdiff --git a/plugins/ruflo-music/agents/music-composer.md b/plugins/ruflo-music/agents/music-composer.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.shnew file mode 100755index 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 1diff --git a/plugins/ruflo-music/skills/music-connect/SKILL.md b/plugins/ruflo-music/skills/music-connect/SKILL.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.