suno-lyric-transformer git:20261015.a87d44fA

Immutable. This exact content never changes and is served at /api/v1/blob/ed6873efc9be390e.

---
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/<name>.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`; 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.** Run `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key modules.suno` 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.
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.
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`): **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.
- **`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 + a short-poem strategy instead of CC; over ~2,500 characters → ST + RA + CD. Done when `validate-options.py "<codes>"` returns `pass` or `warning` (report any `removed_codes`) and LT-STATE holds the codes.

## 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:

```
<!-- LT-STATE: source_hash={analyze-input.py}, draft_hash={analyze-input.py on the draft}, transforms={codes}, profile={name|none}, voice_constraints={key patterns}, emotional_core={1 sentence}, character_budget=3000, version={n} -->
```

- **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, 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 <source> --transformed <draft>` (`--word-fidelity` under WF), `lyrics-diff.py`. Then `assemble-summary.py` on the saved validator, syllable and cliche JSON (no `--cliches` without CD) with `--transformations <codes>`: 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.