---
phase: 01-foundation
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - reference/README.md
  - reference/glossary.md
  - reference/suno/format.md
  - reference/templates/.gitkeep
  - artists/README.md
autonomous: true

must_haves:
  truths:
    - "reference/suno/format.md documents Suno V5.5 Custom Mode with correct limits (1000 char style, 5000 char lyrics)"
    - "reference/suno/format.md includes the complete metatag inventory (structure + vocal + dynamics + negative)"
    - "reference/suno/format.md includes the style prompt 5-part formula with ordering guidance"
    - "reference/suno/format.md includes a copy-paste template for Custom Mode"
    - "reference/README.md lists every reference file with a one-line description"
    - "artists/README.md documents per-artist folder conventions and bible format summary"
    - "reference/glossary.md defines music terms in English universally"
    - "All reference files follow the template: metadata header, Purpose, Rules, Examples, Notes"
  artifacts:
    - path: "reference/suno/format.md"
      provides: "Comprehensive Suno V5.5 Custom Mode technical reference"
      contains: "1,000"
    - path: "reference/README.md"
      provides: "Index of all reference files"
      contains: "format.md"
    - path: "reference/glossary.md"
      provides: "Music terminology glossary"
      contains: "Verse"
    - path: "artists/README.md"
      provides: "Artist folder conventions and bible format"
      contains: "bible.md"
    - path: "reference/templates/.gitkeep"
      provides: "Placeholder for templates directory"
  key_links:
    - from: "reference/README.md"
      to: "reference/suno/format.md"
      via: "index entry with description"
      pattern: "suno/format\\.md"
    - from: "reference/README.md"
      to: "reference/glossary.md"
      via: "index entry with description"
      pattern: "glossary\\.md"
---

<objective>
Create the reference file structure, the comprehensive Suno V5.5 format reference, the glossary, the reference index, and the artists README.

Purpose: These files form the knowledge base that Claude consults during all production workflows. The Suno format reference is the single most complex deliverable in Phase 1 — it must be exhaustive and accurate per the research findings.
Output: `reference/suno/format.md`, `reference/README.md`, `reference/glossary.md`, `reference/templates/.gitkeep`, `artists/README.md`
</objective>

<execution_context>
@C:/Users/zekho/.claude/get-shit-done/workflows/execute-plan.md
@C:/Users/zekho/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-foundation/01-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create the comprehensive Suno V5.5 format reference</name>
  <files>reference/suno/format.md</files>
  <action>
Create `reference/suno/format.md` — the single comprehensive Suno V5.5 Custom Mode reference. This is the largest and most critical reference file. Create the `reference/suno/` directory as needed.

**File structure** (following the reference file template with metadata header):

```
---
last-updated: 2026-04-10
source: Suno API docs, Suno Help Center, HookGenius, Blake Crosley, Musci.io, OpenMusicPrompt
---
```

**Sections to include:**

### Purpose
One-line: Reference complete pour la creation musicale en Suno V5.5 Custom Mode.

### Limites de Caracteres
Table with V5.5 limits:
- Style Prompt: 1,000 chars (hard limit), 200-500 chars (sweet spot — earlier tags carry more weight, beyond 500 chars tags have diminishing impact)
- Lyrics: 5,000 chars (hard limit), 2,000-3,000 chars (sweet spot — beyond ~3,000 Suno rushes or skips sections)
- Title: 100 chars (hard limit), 30-50 chars (sweet spot — display only)

### Formule du Style Prompt
Document the 5-part formula in order of priority (Suno weighs earlier tags more):
1. Genre + Sous-genre (1-2 tags) — foundation, always first
2. Mood / Energie (1-2 descriptors) — emotional direction
3. Direction Vocale (1-2 tags) — gender, tone, delivery style
4. Instrumentation (2-3 instruments) — key sounds
5. Production + Tempo (1-2 tags) — mix aesthetic, BPM

Include: optimal tag count (8-15), comma-separated format, no full sentences, use BPM numbers ("128 BPM") not descriptors. No negative prompting (Suno does not support "don't do X").

Example: `Dark Trap, Aggressive, Male Vocals, Raspy, 808 Bass, Hi-Hats, Dark Synth Pads, Lo-Fi Production, 140 BPM`

### Sweet Spots de Longueur
Document the effect of style prompt length on quality:
- < 100 chars: trop generique, Suno improvise trop
- 100-200 chars: bon pour des styles simples et directs
- 200-500 chars: sweet spot — assez de detail pour guider sans surcharger
- 500-800 chars: fonctionne mais les tags en fin de prompt ont moins d'impact
- 800-1000 chars: risque de contradictions et dilution

### Tags de Structure (Section Metatags)
**Primary Structure** — table with Tag, Purpose, Mapping to song structure:
[Intro], [Verse]/[Verse 1]/[Verse 2], [Pre-Chorus], [Chorus], [Post-Chorus], [Bridge], [Outro], [End]

**Special Structure** — table:
[Instrumental], [Interlude], [Break], [Drop], [Build]/[Build-Up], [Hook], [Refrain], [Solo]/[Guitar Solo], [Breakdown]

Note: Use [Verse 1], [Verse 2] to signal melody variation. Identical [Chorus] tags encourage melodic repetition.

### Metatags de Delivery Vocal
Organize by category (from research). Each category as a subsection with the tags listed:
- Volume et Intensite: [Whispered], [Soft], [Gentle], [Quiet], [Spoken], [Spoken Word], [Powerful], [Belted], [Shouted], [Screamed], [Growled], [Intense]
- Style Vocal: [Falsetto], [Head Voice], [Chest Voice], [Breathy], [Raspy], [Smooth], [Soulful], [Operatic], [Nasal], [Airy], [Crooning]
- Techniques Vocales: [Harmonies], [Ad-libs], [Vocal Run], [Melisma], [Vibrato], [Staccato], [Legato], [Call and Response], [Chant], [Choir], [A cappella], [Humming], [Backing Vocals], [Scat]
- Delivery Rap et Hip-Hop: [Rapped], [Fast Rap], [Slow Flow], [Melodic Rap], [Trap Flow], [Boom Bap Flow], [Mumble Rap], [Double Time]
- Effets Vocaux: [Reverb], [Delay], [AutoTune], [No AutoTune], [Distorted Vocals], [Filtered Vocals], [Vocoder], [Telephone Effect]
- Emotion Vocale: [Vulnerable], [Powerful], [Soft], [Aggressive], [Melancholic], [Joyful], [Sultry], [Defiant]
- Dynamiques (V5+): [Fade In], [Fade Out], [Swell], [Crescendo], [Decrescendo]
- Negatifs (V5+): [no vocals], [no autotune], [no reverb], [no falsetto], [no choir], [no drums], [no synths], [no distortion], [no electronic elements]

Placement rule: tags on their own line before the lyrics they affect. One primary delivery cue per section. Avoid stacking multiple cues.

### Bibliotheque de Tags
Organize by functional category (Claude's discretion from research):

**Genre Tags** — organized by family:
- Electronic et Dance: EDM, House, Deep House, Tech House, Techno, Trance, Drum and Bass, Dubstep, Future Bass, Ambient, Lo-Fi, Synthwave, Retrowave, Chillwave, Downtempo, Trip-Hop, IDM, Garage, UK Garage, Breakbeat, Hardstyle, Jungle
- Hip-Hop et R&B: Hip-Hop, Trap, Boom Bap, Lo-Fi Hip-Hop, Cloud Rap, Drill, Grime, R&B, Neo-Soul, Alternative R&B, Funk
- Rock et Alternative: Rock, Indie Rock, Alternative Rock, Punk Rock, Post-Punk, Grunge, Shoegaze, Dream Pop, Psychedelic Rock, Progressive Rock, Hard Rock, Metal, Heavy Metal, Emo, Pop Punk, Garage Rock, Surf Rock, Stoner Rock
- Pop: Pop, Synth-Pop, Electro-Pop, Indie Pop, Art Pop, Dark Pop, Bedroom Pop, K-Pop, City Pop, Bubblegum Pop, Power Pop
- Country et Folk: Country, Americana, Folk, Indie Folk, Bluegrass, Country Rock, Alt-Country
- Jazz et Blues: Jazz, Smooth Jazz, Bebop, Bossa Nova, Blues, Delta Blues, Chicago Blues, Soul, Gospel
- World et Latin: Reggaeton, Latin Pop, Afrobeats, Dancehall, Reggae, Samba, Cumbia, Flamenco, Celtic, Bollywood
- Classique et Orchestral: Classical, Orchestral, Cinematic, Neoclassical, Chamber Music, Opera
- Autres: Spoken Word, Experimental, Noise, Industrial, Vaporwave, Chiptune, Video Game Music

**Mood et Energy Tags:**
- Mood: Dark, Melancholic, Ethereal, Dreamy, Nostalgic, Romantic, Haunting, Eerie, Aggressive, Rebellious, Triumphant, Uplifting, Playful, Sensual, Vulnerable, Introspective, Euphoric, Bittersweet, Serene, Tense
- Energy: High Energy, Low Energy, Chill, Laid-Back, Intense, Explosive, Building, Hypnotic, Driving, Pulsating, Groovy, Bouncy, Floating, Heavy, Light

**Instrument Tags** — organized by family:
- Claviers: Piano, Electric Piano, Rhodes, Organ, Hammond Organ, Synth, Analog Synth, Digital Synth, Modular Synth, Wurlitzer, Harpsichord, Clavinet
- Cordes: Acoustic Guitar, Electric Guitar, Bass Guitar, Violin, Viola, Cello, Double Bass, Harp, Banjo, Mandolin, Ukulele, Sitar
- Percussions: Drums, 808 Bass, 808 Hi-Hats, Trap Drums, Boom Bap Drums, Live Drums, Drum Machine, Congas, Bongos, Tabla, Marimba, Vibraphone, Timpani
- Vents et Cuivres: Saxophone, Trumpet, Trombone, French Horn, Clarinet, Flute, Oboe, Harmonica, Accordion, Bagpipes
- Electronique: Synth Pads, Synth Lead, Synth Bass, Arpeggiator, Sequencer, Vocoder, Sampler, Glitch, Bitcrushed

**Production et Texture Tags:**
- Production: Lo-Fi, Hi-Fi, Polished, Raw, Overdriven, Clean, Compressed, Spacious, Intimate, Warm, Cold, Crispy, Muddy, Saturated, Dry, Wet
- Texture: Atmospheric, Ambient, Layered, Minimalist, Dense, Sparse, Lush, Gritty, Smooth, Distorted, Reverb-Drenched, Delay-Heavy, Filtered, Granular

### Gestion de la Langue
- Detection: Suno infere la langue depuis le texte des lyrics. Pas de selecteur explicite.
- Pour le francais: ajouter "All lyrics in French" ou "Sung in French" dans le style prompt pour eviter la derive linguistique en cours de track.
- Le style prompt est TOUJOURS en anglais, quelle que soit la langue des lyrics.
- Une langue par section recommandee. Ne pas melanger dans un meme Verse.
- Prononciation: Suno predit depuis les patterns d'orthographe. Pour les mots mal prononces, les epeler phonetiquement. Garder les lignes de longueur moderee — les lignes denses en syllabes (12+) causent du slurring aux tempos rapides.
- Langues bien supportees: francais parmi les meilleures apres l'anglais (avec espagnol, portugais, japonais, coreen, mandarin).

### Tempo et BPM
- Utiliser la notation BPM explicite: "128 BPM" pas "medium tempo"
- Le BPM est un guidage approximatif, pas un metronome exact
- Ranges par genre (table):
  Lo-fi / Chill: 60-85 | Ballad: 60-80 | R&B / Neo-Soul: 70-100 | Pop: 100-130 | Rock: 110-140 | House / Dance: 120-130 | Techno: 125-150 | Drum and Bass: 160-180 | Trap / Hip-Hop: 130-170 (half-time feel)

### Controle de la Duree
- V5.5: jusqu'a 4 minutes par generation (chainable via Extend pour atteindre 12+ minutes sur plan Premier)
- Plus de lyrics = contenu vocal plus dense, risque de delivery rushee
- Moins de lyrics avec des breaks [Instrumental] = respiration, rendu naturel
- Sweet spot pratique: 2-4 minutes pour une generation unique

### Voices (ex-Personas)
Brief mention per locked decision:
- Captures vocal timbral qualities from reference audio
- Each artist gets one Voice profile for vocal consistency across tracks
- Acces: Pro ($10/mo) et Premier ($30/mo) uniquement
- Fonctionne avec les metatags de delivery ([Whispered], [Belted], etc.)
- Audio Influence slider controle la fidelite au profil vocal

### Template Copier-Coller
Include the visual copy-paste template from the research showing the Suno Custom Mode interface layout (Title, Style of Music, Lyrics fields with limits indicated).

### Notes
- Front-loader les tags importants dans le style prompt (les premiers tags ont plus de poids)
- Les tags en fin de prompt ont un impact decroissant
- Eviter les contradictions (ex: "Aggressive" et "Gentle" dans le meme prompt)
- Pas de prompting negatif — etre specifique sur ce qu'on veut, pas sur ce qu'on ne veut pas
  </action>
  <verify>Verify file exists and contains: "1,000" (style limit), "5,000" (lyrics limit), "[Verse]", "[Chorus]", "[Whispered]", "128 BPM", copy-paste template section. Count that all 6 vocal delivery categories are present.</verify>
  <done>reference/suno/format.md exists as a comprehensive Suno V5.5 Custom Mode reference with correct V5.5 limits, complete metatag inventory, style prompt formula, tag library organized by category, language handling, tempo guidance, duration control, Voices mention, and copy-paste template.</done>
</task>

<task type="auto">
  <name>Task 2: Create reference index, glossary, templates placeholder, and artists README</name>
  <files>reference/README.md, reference/glossary.md, reference/templates/.gitkeep, artists/README.md</files>
  <action>
Create four files. Create directories as needed (`reference/`, `reference/templates/`, `reference/linguistic/french/`, `reference/linguistic/english/`, `artists/`).

**1. `reference/README.md`** — Index of all reference files:

```
---
last-updated: 2026-04-10
---

# Reference

Index de tous les fichiers de reference du projet. Ces fichiers font autorite sur les connaissances internes de Claude.

## Index

| Fichier | Description |
|---------|-------------|
| `suno/format.md` | Reference complete Suno V5.5 Custom Mode (limites, metatags, formule style prompt, tags) |
| `linguistic/french/syllables.md` | Regles de comptage des syllabes en francais (e muet, dierese, synerese) |
| `linguistic/french/rhymes.md` | Classification des rimes francaises (pauvre, suffisante, riche, richissime) |
| `linguistic/french/pronunciation.md` | Prononciation francaise pour generation IA (pieges, liaisons, nasales) |
| `linguistic/english/syllables.md` | Regles de comptage des syllabes en anglais (stress patterns, exceptions) |
| `linguistic/english/rhymes.md` | Classification des rimes anglaises (perfect, slant, near, eye) |
| `glossary.md` | Glossaire des termes musicaux (anglais universel avec equivalents francais) |
| `templates/` | Templates de structure de chanson par genre (peuple en Phase 3) |

## Convention

Chaque fichier de reference suit le template: metadata header (last-updated, source), Purpose, Rules, Examples, Notes.
```

**2. `reference/glossary.md`** — Music terms glossary using English terms universally:

Follow the reference file template (metadata header, Purpose, Rules, Examples, Notes).

Purpose: Glossaire des termes musicaux utilises dans le projet. Les termes anglais sont canoniques — utilises partout, meme dans les fichiers en francais.

Rules section contains a table mapping English term (canonical) -> French equivalent -> Definition:
- Verse -> Couplet -> Main narrative section of a song
- Chorus -> Refrain -> Repeated hook section, emotional peak
- Pre-Chorus -> Pre-refrain -> Tension-building section before chorus
- Post-Chorus -> Post-refrain -> Extension after chorus, sustains energy
- Bridge -> Pont -> Contrasting section providing emotional/stylistic pivot
- Hook -> Accroche -> Short catchy phrase, often the most memorable part
- Intro -> Introduction -> Opening section, sets atmosphere
- Outro -> Conclusion -> Closing section, resolution
- Interlude -> Interlude -> Short musical break between sections
- Drop -> Drop -> EDM-style energy release after build
- Breakdown -> Breakdown -> Deconstructed beat/stripped arrangement
- Build-Up -> Montee -> Rising intensity leading to climax
- Refrain -> Refrain -> Repeated line, shorter than a full chorus
- Bar/Measure -> Mesure -> Rhythmic unit (typically 4 beats)
- Beat -> Temps -> Single rhythmic pulse
- BPM -> BPM -> Beats per minute, tempo measurement
- Flow -> Flow -> Rhythmic delivery pattern (especially in rap)
- Cadence -> Cadence -> Rhythmic pattern and pacing of delivery
- Rhyme Scheme -> Schema de rimes -> Pattern of rhyming line endings (AABB, ABAB, etc.)
- Syllable -> Syllabe -> Unit of pronunciation
- Slant Rhyme -> Rime approximative -> Partial sound match between words
- Perfect Rhyme -> Rime parfaite -> Identical sounds from stressed vowel to end
- Internal Rhyme -> Rime interne -> Rhyme occurring within a single line
- Metatag -> Metatag -> Suno formatting tag ([Verse], [Chorus], etc.)
- Style Prompt -> Style Prompt -> Suno field for genre/mood/production direction
- Production Brief -> Fiche de production -> Complete track specification ready for Suno
- Artist Bible -> Bible d'artiste -> Comprehensive artist identity document

Examples section: show how terms are used in context ("Le [Verse 1] avance la narration..." not "Le Couplet 1...").

Notes: "Les termes anglais sont utilises dans tous les fichiers du projet, y compris les fichiers en francais, pour eviter toute ambiguite."

**3. `reference/templates/.gitkeep`** — Empty file. Just create the directory with a .gitkeep placeholder.

**4. `artists/README.md`** — Per-artist folder conventions and bible format summary:

Follow the reference file template (metadata header, Purpose, Rules, Examples, Notes).

Purpose: Convention de structure des dossiers artistes et resume du format de la bible.

Rules:
- Chaque artiste a un dossier dedie: `artists/[nom-en-kebab-case]/`
- Structure obligatoire d'un dossier artiste:
  ```
  artists/[nom]/
  +-- bible.md          # Bible complete de l'artiste
  +-- discography.md    # Log automatique de tous les tracks
  +-- tracks/
      +-- 01-titre.md   # Fiches de production individuelles
      +-- 02-titre.md
  ```
- Nommage des tracks: `[numero-sequentiel]-[titre-en-kebab-case].md`
- La bible est la source de verite pour l'identite de l'artiste

Bible format summary (sections attendues):
- Identite (nom, genre principal, sous-genres)
- Style Vocal (timbre, techniques, registre, delivery)
- Palette Emotionnelle (emotions primaires, secondaires, interdites)
- Themes (sujets recurrents, univers thematique)
- Lore (histoire, personnalite, background)
- Direction Visuelle (mots-cles pour imagerie)
- Influences (artistes de reference, pas pour copier mais pour situer)

Examples: show a sample folder structure for a fictional artist.

Notes: "Le workflow de creation d'artiste genere automatiquement cette structure. Ne pas creer les dossiers manuellement."

**Important:** Also create the empty directories `reference/linguistic/french/` and `reference/linguistic/english/` so Plan 01-03 can populate them directly.
  </action>
  <verify>Verify all files exist: `reference/README.md`, `reference/glossary.md`, `reference/suno/format.md`, `reference/templates/.gitkeep`, `artists/README.md`. Verify directories exist: `reference/linguistic/french/`, `reference/linguistic/english/`. Verify README.md index lists all reference files.</verify>
  <done>Reference directory structure is complete with index, glossary, Suno format reference, templates placeholder, artists README, and empty linguistic subdirectories ready for Plan 01-03.</done>
</task>

</tasks>

<verification>
- reference/suno/format.md contains V5.5 limits (1000 style, 5000 lyrics), NOT V4 limits (200/3000)
- reference/suno/format.md contains all metatag categories (structure, vocal, dynamics, negative)
- reference/suno/format.md contains the 5-part style prompt formula
- reference/suno/format.md contains the copy-paste template
- reference/README.md lists every reference file (suno/format.md, linguistic/french/*, linguistic/english/*, glossary.md, templates/)
- reference/glossary.md uses English terms as canonical with French equivalents
- artists/README.md documents folder conventions and bible format summary
- All reference files have metadata headers with last-updated date
- All reference files follow the template: Purpose, Rules, Examples, Notes
- Directories exist: reference/linguistic/french/, reference/linguistic/english/
</verification>

<success_criteria>
- reference/suno/format.md is a comprehensive, accurate Suno V5.5 Custom Mode reference
- reference/README.md indexes all reference files
- reference/glossary.md defines music terms with English as canonical language
- artists/README.md explains folder conventions and bible format
- All directories needed for Phase 1 exist
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation/01-02-SUMMARY.md`
</output>
