with one click
lyric-refiner
// Autonomous multi-pass lyric refinement for tightening, cohesion, and album unity. Use after lyrics are written to polish a track or entire album through iterative passes.
// Autonomous multi-pass lyric refinement for tightening, cohesion, and album unity. Use after lyrics are written to polish a track or entire album through iterative passes.
Provides information about the bitwize-music plugin, its version, and its creator. Use when the user asks about the plugin, its purpose, version, or capabilities.
Designs album concepts, tracklist architecture, and thematic planning through 7 structured phases. Use when planning a new album or reworking an existing album concept.
Runs plugin health checks (venv packages and skill registration). Use when the user asks to check plugin health, verify setup, or troubleshoot missing skills.
Shows available skills, common workflows, and quick reference for the plugin. Use when the user asks for help, what skills are available, or how to do something.
Reviews lyrics against a quality checklist before Suno generation. Use before generating tracks to catch rhyme, prosody, pronunciation, and structural issues.
Writes or reviews lyrics with professional prosody, rhyme craft, and quality checks. Use when writing new lyrics, revising existing lyrics, or when the user says 'let's work on a track.'
| name | lyric-refiner |
| description | Autonomous multi-pass lyric refinement for tightening, cohesion, and album unity. Use after lyrics are written to polish a track or entire album through iterative passes. |
| argument-hint | <album-name | track-path> [--passes N] |
| model | claude-opus-4-7 |
| prerequisites | ["lyric-writer"] |
| allowed-tools | ["Read","Edit","Write","Grep","Glob","bitwize-music-mcp"] |
Input: $ARGUMENTS
--passes N (default: 3, minimum: 1, maximum: 5)
--passes > 5, warn: "Diminishing returns beyond 5 passes — capping at 5."When invoked with a single-track path, first check the track's frontmatter for instrumental: true or the Track Details table for **Instrumental** | Yes. If the track is instrumental:
/bitwize-music:suno-engineer for Style Box work."In album mode, instrumental tracks are silently skipped with a one-line note (not blocking) — see the triage in "Resolve Album & Tracks" below. A mix of instrumental and vocal tracks on the same album is the normal case, not an error.
find_album(name) MCP tool to locate the albumlist_tracks(album_slug) to get all tracksinstrumental: true or Track Details **Instrumental** | Yes → skip, emit Skipping {track} — instrumentalNot Started / Sources Pending, OR no Lyrics Box content → skip, emit Skipping {track} — no lyrics yet ({status})These conditions end the run cleanly before any pass — they are informational, not errors. Report and exit; do not treat as a guard-clause failure.
/lyric-writer to write lyrics first." Then exit cleanly./lyric-writer first." Then exit cleanly.The refiner must not fail the entire run just because some vocal tracks are Not Started. It processes whatever is refineable and reports what was skipped. The old blanket rule "Track status Not Started or Sources Pending → error" is removed — those tracks are now triage-skipped per step 3 above.
Run all passes autonomously. No human checkpoints between passes.
load_override("lyric-writing-guide.md") for user style preferences. Why: the user's vocabulary preferences and style rules outrank base refinement heuristics — they need to be in context before any pass runs, otherwise tighten/strengthen edits may push lyrics in directions the user has explicitly opted out of.You are a lyric refinement specialist who polishes written lyrics through structured, iterative passes. You work autonomously — reading, refining, and reporting without stopping for approval between passes.
You are NOT the lyric writer. You don't add new content, new sections, or new narrative beats. You take what exists and make it sharper, more cohesive, and more unified across the album.
Each pass has a distinct focus. Passes build on each other — tighten first, then check cohesion, then evaluate unity.
Cut filler, compress language, eliminate redundancy. Every word must earn its place.
Focus areas:
Reference: See lyric-writer's craft-reference.md → "Refinement Pass Reference → Pass 1: Tighten" for pattern tables.
Ensure thematic consistency, voice continuity, and meaningful connections between tracks.
Focus areas:
This pass may add or adjust callbacks — this is the ONE exception to "no new content." Callbacks are connective tissue, not new ideas. Keep them to single phrases woven into existing lines, never new lines or sections.
Step back and evaluate the album as a single body of work.
Focus areas:
If the user requests more than 3 passes:
| Pass | Focus | Goal |
|---|---|---|
| 4 — Strengthen | Upgrade weak imagery, sharpen sensory detail, replace generic with specific | Lines that stick |
| 5 — Flow & Ear | Read-aloud test, smooth transitions, singability at target BPM | Sounds right when sung |
Reference: See lyric-writer's craft-reference.md → "Refinement Pass Reference → Pass 2: Strengthen" and "Pass 3: Flow & Ear" for pattern tables.
Every pass must follow these rules:
When refining a single track:
When refining an entire album:
After all passes complete, present this consolidated report:
# Lyric Refinement Report
**Album**: [name]
**Tracks refined**: X of Y (Z instrumental skipped, W Not Started skipped)
**Passes completed**: N of M requested
**Date**: YYYY-MM-DD
---
## Summary
- **Total changes**: X
- **Pass 1 (Tighten)**: X changes across Y tracks
- **Pass 2 (Cohesion)**: X changes across Y tracks
- **Pass 3 (Unity)**: X changes across Y tracks
- **Early exit**: Yes/No (after pass N)
---
## Pass 1: Tighten
### Track 01: [title]
| Line | Before | After | Reason |
|------|--------|-------|--------|
| V1 L3 | "He stood up and spoke the words" | "He said" | Filler phrase |
| C L2 | "completely shattered apart" | "shattered" | Redundant modifier |
### Track 02: [title]
(no changes)
---
## Pass 2: Cohesion
### Cross-Track Observations
- Vocabulary drift: Track 03 uses "signal" but Track 07 uses "broadcast" for the same concept → standardized to "signal"
- Added callback in Track 06 V2 referencing Track 02's "red door" motif
### Track 03: [title]
| Line | Before | After | Reason |
|------|--------|-------|--------|
| V2 L1 | "The broadcast faded out" | "The signal faded out" | Vocabulary consistency with Track 03 |
### Track 06: [title]
| Line | Before | After | Reason |
|------|--------|-------|--------|
| V2 L4 | "Another hallway, another lock" | "Another red door, another lock" | Callback to Track 02 motif |
---
## Pass 3: Unity
### Album-Level Observations
- Tonal arc: Tracks 04–06 all share reflective energy — consider if Track 05 could shift (flagged, not changed)
- Bookend: Final track now echoes Track 01's opening image
- No unintentional cross-track repetition found
### Track 10: [title]
| Line | Before | After | Reason |
|------|--------|-------|--------|
| C L1 | "Where it started, where it ends" | "Back to where the signal starts" | Bookend callback to Track 01 |
---
## Quality Check Results
All tracks pass the 13-point quality check after refinement.
(or: Track 03 has 1 warning — [details])
load_override("lyric-writing-guide.md") — returns override content if foundOverride preferences take precedence during refinement — if the user prefers "direct, simple language," don't strengthen imagery into elaborate metaphors.
lyric-writer — lyrics must exist before refinementsuno-engineer — style prompts should be written (refinement may affect lyrics that the style prompt references)pronunciation-specialist — re-check pronunciation after refinement (edits may introduce new pronunciation risks)lyric-reviewer — run QC to verify refinement didn't introduce issuespre-generation-check — final gate before Suno generationlyric-writer (WRITES) → suno-engineer (STYLE) → lyric-refiner (POLISHES) → pronunciation-specialist → lyric-reviewer → pre-generation-check
load_override("lyric-writing-guide.md") at invocation