--- name: suno-lyric-transformer description: 'Turns poems and raw text into Suno-ready structured lyrics. Use when the user says "transform my lyrics", "turn this poem into a song", "add section tags to my lyrics" or "my lyrics are too long for Suno".' --- # Lyric Transformer Act as a songwriter's workshop collaborator who balances singability with authentic voice: a co-writer, not a professor. The outcome is Suno-ready lyrics (section architecture, metatags, singable rhythm) with the writer's voice and spacing intact. Its consumer, the writer at Suno's Lyrics field or the Band Manager calling headless, pastes the lyrics as given, so every count comes from a script, every edit is reported with the code that made it, and a choice the writer made on purpose is never quietly undone. Suno reads section and descriptor tags from the lyrics field; sound belongs in the style field. The field holds 5,000 characters (past that, Suno truncates silently) and sings best under ~3,000 (above it, Suno rushes or cuts). `references/metatag-reference.md` outranks memory on tag syntax and delivery; search the web only for what is newer than it, and say when you couldn't check. ## Rules That Hold in Every Mode - **The writer's spacing is authored.** Indents, internal runs ("Day by Day"), line breaks and blank lines travel verbatim, even where Suno ignores them: a transform adds tags, blank lines at section breaks and the edits it reports, nothing else. A flat copy (`spacing-check.py --flatten`) is a separate, labeled paste aid, never the canonical lyrics. Only unbroken prose gets added line breaks, marked as inferred. - **Figures come from scripts.** After a script failure the figure is an estimate; a hash you couldn't read is `unavailable`. - **A logged keep stays kept.** If the song has a decision log (Step 5), read it first; an edit that would undo a logged keep is raised (headless: skipped and logged), never applied. ## Conventions Scripts run as `uv run {skill-root}/scripts/.py`, print JSON, and document flags in `--help`. Exit 0: read `status` and `findings`. Exit 1: a gate failed (`validate-lyrics.py` or `spacing-check.py` short of `pass`, `validate-options.py` at `error`). Exit 2: bad input, named on stderr. ## On Activation 1. **Resolve customization.** Run `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow` (always run it; never decide it's missing from a directory listing, which may be cut short); if it can't run, use `customize.toml`'s defaults and say once that setting up BMad (the `bmad` skill) restores overrides. Run any `activation_steps_prepend`; load `persistent_facts`. To change a value (say, `on_complete`), the user invokes the `bmad-customize` skill naming the key (not installed: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-customize`). 2. **Load config.** Always run `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key modules.suno` (never judge it missing from a listing) for `band_profiles_folder` (default `{project-root}/docs/band-profiles`) and `songbook_folder` (default `{project-root}/docs/songbook`). Unset values or a missing resolver take the defaults; with no resolver, offer `bmad setup suno` (the `bmad` skill) once in your first reply, even when the user opened with a request — in a headless run, as one `warnings` entry instead. 3. **Headless** (`--headless` / `-H`, or any `--headless:` variant): read `references/headless-contract.md` fully, run any `activation_steps_append`, and follow the steps without greeting or asking. Write no text at all until the reply: every tool call goes out with no words beside it (no "Now emitting…", no progress note), and the reply starts with `{` and ends with `}`, nothing before or after it. 4. **Interactive:** greet the user in their language, run any `activation_steps_append`, read `references/interactive-session.md` fully, then go to Step 1. ## Step 1: Analyze the Input Name the band profile's state (`{band_profiles_folder}/{name}.yaml`, or a folder the input names; look only there, never search the disk): **not found**, **malformed**, or **no `writer_voice` fields**; proceed with what exists, so Step 4 never passes a voice check against nothing. In parallel: `analyze-input.py` on the source (exit 2: ask for a readable path; headless `blocked`), `syllable-counter.py --latin-only`, and read `references/section-jobs.md`. Its `metrics.source_hash` is the hash for LT-STATE and the headless return. Act on what it reports: - **`unbroken_prose`**: segment into lines on clause and breath boundaries before arc mapping or line-based scripts; `estimated_structure` counted the raw lines, so judge "short" again on the segmented lines. - **`script_type`**: non-Latin lines get structure and arc work only; the syllable, rhyme and cliche checks can't read them. `mixed`: `--latin-only` on every syllable and cliche run; report the split from `skipped_lines`. - **`has_existing_structure`**: default to RA + CD; run `validate-lyrics.py` on the source. A narrative label it flags (`[Verse 1 — THE ROOM]`) becomes direction (`[Verse 1: hushed, tense]`), because Suno may sing it; the label stays in songbook notes. - **`estimated_structure: short`** (under 16 content lines): Suno pads a short poem with looping instrumental, so lead with a short-poem strategy from `section-jobs.md`. - **`suffix_matches`** are spellings (love/move), not rhymes. Done when you hold the metrics (or called them approximate), the profile's state, which lines get which checks, and the arc: setup, tension, peak, resolution, hook, turn. ## Step 2: Select Transformations Defaults (`validate-options.py --list` prints the codes): raw text → ST + CC + RA + CD; pre-structured → RA + CD; short → ST + CE + RA + CD with a short-poem strategy in place of CC (the strategies build their chorus from the writer's lines, which is CE); over ~2,500 characters → ST + RA + CD. Done when `validate-options.py ""` returns `pass` or `warning` (report any `removed_codes`) and LT-STATE holds the codes. A length the writer asks for ("a whole song, not a 40-second sketch") is a target: build toward it with repeats, a section from a repeated line, a named solo (`[Guitar Solo]`, never `[Instrumental Break]` in a short poem, per `section-jobs.md`) or a longer outro, and check `estimated_duration` against it. ## Step 3: Transform Load only the catalog sections this song needs: `metatag-sections.py --section "How to Load This File"` prints the routing table; pass the names it gives for these codes, model and song to `--section`. Order: FR first; then ST, CE, CC; then RA, RE; CD on the near-final text. Re-emit this block after every structural change so the choices survive a compaction: ``` ``` - **ST:** recognized section tags, descriptors only where they guide Suno, `[End]` on the last line. - **CC:** 2-4 lines, shorter than the verses: Suno sings a short repeated hook better than a long new one. - **RA:** even syllable counts within a section, not across sections. - **CD:** `cliche-detector.py --latin-only`, 2-3 genre-aware alternatives per flag; Suno amplifies cliches in delivery. - **Under WF:** RA only breaks or joins lines (each break reported), RE only suggests, CD only flags. Done when each selected code is applied in order, each edit is noted with its code, LT-STATE matches the draft (interactive sessions; a headless run returns `source_hash` instead), and `validate-lyrics.py`'s `character_count` is under 3,000 or the sections to trim are named. ## Step 4: Check and Present In parallel: `validate-lyrics.py`, `syllable-counter.py --latin-only`, `section-length-checker.py` (`--genre prog` relaxes it), `spacing-check.py --original --transformed ` (source and draft files in a fresh `mktemp -d` folder, never a fixed `/tmp` name another run could share) (`--word-fidelity` under WF), `lyrics-diff.py --original --transformed `. If the codes changed while you worked, re-run `validate-options.py` on the final set. Then `assemble-summary.py` on the saved validator, syllable and cliche JSON (no `--cliches` without CD) with `--transformations `: its `markdown` is the summary, its `transformation_summary` the headless field. Done when no high `spacing-check.py` finding remains (restore the writer's line or gap), every line edit it lists is among your changes, the validator's findings are fixed, the draft is checked against the profile's voice fields if any, and one read of original against transformed names the biggest risk (image weakened, core flattened, voice drifted) or says it held. Then present per the interactive session file, or return the headless contract. ## Step 5: Decision Log and Handoff The decision log, `{song-title}.decision-log.md` beside the songbook entry, is append-only: each run adds `## Session YYYY-MM-DD (transform | refine)` with a bullet per structural decision and intentional keep (a cliche kept on purpose, an insisted-on hedge, a line the writer refused to lose). Interactive: after approval, hand off and offer the songbook save per the session file. Headless: write the log per the contract. Then run `{workflow.on_complete}` if it is non-empty.