# Project Research Summary

**Project:** AI Artiste -- Virtual Music Artist Creation System
**Domain:** Markdown-based AI workflow system for virtual music artist creation and production
**Researched:** 2026-04-10
**Confidence:** MEDIUM-HIGH

## Executive Summary

AI Artiste is not a software application -- it is a structured markdown workflow system executed by Claude Code. The product creates and manages virtual AI music artists: fictional identities with genre, vocal style, emotion palettes, and lore, then produces Suno-ready track production briefs with linguistically verified lyrics. The recommended approach is zero-code, zero-runtime: Claude Code `.claude/skills/` wizards drive interactive creation, artist data lives in flat-file markdown folders, and the system output is copy-pasteable text for Suno Custom Mode. This approach is validated by an active open-source reference project (bitwize-music-studio/claude-ai-music-skills) and is the most natural fit for Claude native reading and file-writing capabilities.

The critical design insight from research is that this system lives or dies on two axes: lyric linguistic quality and artist identity coherence. For lyrics, French syllabification and rhyme classification are meaningfully different from English -- French requires explicit rule-based verification covering e muet elision, dierese/synerese decisions, and phonetic (not spelling-based) rhyme quality classification across four tiers (pauvre/suffisante/riche/richissime). For coherence, research confirms that LLMs exhibit measurable identity drift across multi-session workflows even with persona prompts, and that larger models drift more, not less. Both problems are solvable only through structured verification steps embedded in the workflow -- not by trusting Claude intuition.

The primary risk is building workflows that produce outputs that look correct but fail silently in practice: Suno truncating style prompts without error, wrong French syllable counts accepted as verified, and identity drift accumulating undetected across tracks. The mitigation strategy is consistent: separate generation from verification, enforce hard constraints in templates (character counts, schema validation), and build discography tracking from the first track -- not after drift becomes visible.

## Key Findings

### Recommended Stack

The system runs on Claude Code as the execution engine with `.claude/skills/` as the workflow definition format. Suno V5.5 (March 2026) is the unambiguous primary choice for music generation: it leads the market on vocal realism, supports Custom Mode with separate style prompt and lyrics fields, includes the Voices feature for voice consistency across tracks (Pro plan, $10/mo), and has established commercial rights through its Warner Music partnership. No other platform (Udio, ElevenLabs Music, AIVA) matches Suno combination of vocal quality, format control, and licensing clarity for this use case.

Lyric verification is handled by Claude native analysis using structured step-by-step checklists -- not external APIs or NLP tools, which would violate the zero-code constraint. French linguistic rules (e muet, elision, liaison, dierese/synerese) are embedded directly in reference markdown files and loaded on demand by verification steps. Artist data is stored as markdown with YAML frontmatter in per-artist folder structures, which Claude reads natively and users can edit without tooling.

**Core technologies:**
- Claude Code `.claude/skills/`: Workflow execution engine -- the system IS Claude following markdown skill instructions
- Suno V5.5 Custom Mode: Primary music generation -- style prompt (200-1000 chars) + lyrics (3000 chars) + metatags (300+ supported)
- Suno Voices (V5.5): Voice consistency across tracks -- built into Pro/Premier, no external tools needed
- Markdown + YAML frontmatter: Artist data storage -- natively readable by Claude and humans, git-versionable
- Claude native verification: Lyric quality checking -- structured checklist prompts, no runtime dependencies
- `.claude/CLAUDE.md`: Project-level instruction layer -- reference files flagged as authoritative over training data

### Expected Features

**Must have (table stakes):**
- Interactive artist creation wizard -- step-by-step UX is mandatory for a no-code system; dumping all fields at once causes abandonment
- Artist bible in markdown -- the foundational identity document; everything downstream depends on it being complete
- Artist folder structure (`artists/{slug}/`) -- predictable, navigable, Claude-loadable
- Track creation workflow -- second core wizard; produces the system primary deliverable
- Complete lyrics generation -- full singable lyrics with Suno section tags ([Verse], [Chorus], [Bridge], etc.)
- Style prompt construction -- auto-generated from bible; 5-8 tags, genre-first ordering, under character limits
- Suno metatag integration -- structural and vocal delivery tags embedded in lyrics at correct positions
- Basic artist-track coherence check -- genre, vocal style, emotion, theme alignment against the bible
- Multilingual support (FR/EN) -- language selection drives different rhyme rules, syllable rules, and verification paths
- Basic discography tracking -- append each track to `discography.md`; required to detect drift from track 2 onward

**Should have (differentiators):**
- Linguistic verification engine -- rhyme quality, syllable counts, structure validation; the key differentiator vs. generic AI lyric tools
- French rhyme quality scoring -- pauvre/suffisante/riche classification; no competitor does this
- Emotion palette enforcement -- warn when tracks over-index on one emotion or leave the defined range
- Suno prompt optimization -- subgenre specificity, conflict detection, front-loaded critical tags
- Vocal delivery metatag suggestions -- [Whispered], [Belted], [Raspy] mapped to artist vocal_style and section emotion
- Structure template library -- 5-10 pre-built song structures by genre, with metatag placement

**Defer (v2+):**
- Cross-track narrative coherence -- meaningful only after 5+ tracks exist
- Lore-lyrics integration -- complex creative feature that needs a mature bible system
- Visual prompt generation -- explicitly deferred per project constraints
- Album/EP planning workflow -- requires single-track workflow to be mature first
- Artist evolution system -- needs deep discography and mature coherence system

### Architecture Approach

The system uses a three-layer architecture: Workflow Layer (Claude skills that drive interactive wizards), Knowledge Layer (reference markdown files with rules, templates, and Suno format specs), and Data Layer (generated `artists/` folders with per-artist and per-track markdown files). Workflows read from the Knowledge Layer on demand (per-step, not all at once) and write to the Data Layer. This separation keeps context windows lean, makes rules independently updatable, and ensures artist data is human-readable without tooling.

**Major components:**
1. `.claude/skills/create-artist/` -- Interactive wizard that collects identity data and writes structured artist folder; user-triggered, never auto-invoked (`disable-model-invocation: true`)
2. `.claude/skills/create-track/` -- Track creation wizard that loads artist context, generates lyrics, runs verification, and outputs a Suno-ready production brief
3. `reference/` -- Knowledge layer: linguistic rules per language, Suno format specs, templates, rhyme scheme library; loaded on demand by specific workflow steps
4. `artists/{slug}/` -- Data layer: per-artist flat-file database with `bible.md`, `vocal.md`, `visual.md`, `lore.md`, `personality.md`, and `tracks/` subfolder
5. Coherence engine -- inline verification steps within `create-track` that read the artist bible + last 3-5 tracks before generation

**Key patterns:**
- Wizard skill with step files: SKILL.md orchestrates; each step file contains focused instructions loaded on demand
- Coherence-by-reference: always load artist context before generating; never generate blind
- Structured markdown as data: headings define schema, YAML frontmatter provides machine-parseable metadata
- Suno-ready production brief as terminal output: the final step always produces copy-pasteable text within Suno exact constraints

### Critical Pitfalls

1. **French syllable counting applied as English counting** -- French e muet, dierese, and hiatus rules are non-negotiable and differ completely from English. Build explicit step-by-step verification forcing Claude to show its work (list each word, mark e muets, flag dierese candidates, then count). Embed plint rule set in `reference/linguistic/rules-fr.md`. Address in Phase 1.

2. **Spelling-based rhyme verification instead of phonetic** -- French rhyme quality (pauvre/suffisante/riche) requires phonetic comparison, not visual similarity. Words that look alike may not rhyme; words that look different may. Include multi-step phonetic check: identify last stressed vowel + following phonemes, classify quality, check rhyme gender (masculine/feminine), verify alternation. Address in Phase 1.

3. **Suno format mismatch renders production briefs useless** -- Suno silently truncates style prompts beyond limits without error. Hard-code constraints in the production brief template: style prompt under 200 chars (safe) or 1000 chars (max), lyrics under 3000 chars, one metatag cue per section, blank lines between sections. Always front-load genre/vocal/mood since truncation cuts from the end. Address in Phase 1.

4. **Identity drift accumulating undetected across multiple tracks** -- LLM research confirms persona drift is real, larger models drift more, and bible context alone does not prevent it. From track 2 onward, the Create Track workflow must load a discography summary and compare new content against the last 3 tracks. Define explicit drift-detection criteria in the bible: forbidden themes, required vocabulary patterns, emotional range boundaries. Address in Phase 2.

5. **Context window exhaustion as artist corpus grows** -- At 70% context utilization Claude loses precision; at 85%+ hallucinations increase. A full artist corpus (bible + 10 tracks + rules + workflow) can easily exceed 20K tokens before creative work begins. Use tiered context: always load bible core fields and current track brief; load previous tracks as 2-3 line summaries (not full lyrics); load linguistic rules only in the verification step; never load visual identity or full lore during track creation. Address in Phase 2.

6. **Suno French pronunciation failures despite correct lyrics** -- Suno has no phonetic dictionary and predicts pronunciation from spelling patterns, guessing poorly for French silent letters, liaisons, and nasal vowels. Add a pronunciation guide section to French production briefs flagging high-risk words. Include "All lyrics in French" in every French-language style prompt. Build a tested-vocabulary list from real Suno outputs. Address from Phase 1, grow through Phase 2.

## Implications for Roadmap

Based on combined research, the dependency map is clear: artist identity is the foundation for everything; linguistic verification is the quality differentiator; multi-track coherence management is the scaling challenge. The build order flows naturally from these dependencies.

### Phase 1: Foundation and Core Workflows

**Rationale:** Artist bible creation must come first -- it is the prerequisite for every other feature. Track creation must come second -- it is the system primary value delivery. Both must include their quality gates from day one, because retrofitting verification after tracks exist means re-verifying everything already produced.

**Delivers:** A working end-to-end system: create an artist, create a verified track, receive a Suno-ready production brief.

**Features addressed:**
- Interactive artist creation wizard
- Artist bible in markdown
- Artist folder structure
- Track creation workflow
- Complete lyrics generation (FR/EN)
- Style prompt construction
- Suno metatag integration
- Basic artist-track coherence check
- Basic discography tracking
- Multilingual support (FR/EN)

**Pitfalls to prevent in this phase:**
- French syllable counting rules embedded in `reference/linguistic/rules-fr.md` from the start
- Phonetic rhyme verification built into the track workflow verification step
- Production brief template with hard-coded character limits and front-loaded style prompt ordering
- Suno French pronunciation guide section added to every French production brief

**Architecture work:** Set up the three-layer structure (`reference/`, `artists/`, `.claude/skills/`), write CLAUDE.md, create bible template and track template, write linguistic rule files for French and English, write Suno format reference.

**Research flag:** Standard patterns -- Claude Skills documentation is official and well-documented. Suno format constraints are cross-verified across multiple community sources. Linguistic rules are authoritative from plint. No additional research-phase needed.

### Phase 2: Linguistic Quality and Multi-track Management

**Rationale:** Once the core workflows are validated with real usage, add the quality layer that turns the system from "functional" to "professional." This phase also addresses the two scaling problems that only become visible after multiple tracks: identity drift and context window exhaustion.

**Delivers:** Linguistically verified lyrics with French rhyme quality scoring, emotion palette enforcement, drift detection, and context management for growing discographies.

**Features addressed:**
- Linguistic verification engine (formalized rhyme checking, syllable counts, structure validation)
- French rhyme quality scoring (pauvre/suffisante/riche classification)
- Emotion palette enforcement
- Suno prompt optimization (subgenre specificity, conflict detection)
- Vocal delivery metatag suggestions

**Pitfalls to prevent in this phase:**
- Identity drift detection: discography summary consulted and updated each track; blind-test after 5 tracks
- Context window management: tiered loading strategy established before corpus grows past 5 tracks per artist
- Bible bloat prevention: satellite documents (vocal.md, visual.md, lore.md) absorb growth; bible stays under 200 lines

**Architecture work:** Add `artists/{slug}/tracks/index.md` as a running track summary for coherence checks. Add emotion palette tracking to discography. Split create-track workflow into clearly separated generation and verification steps with focused context per step. Add `reference/linguistic/common-schemes.md` with rhyme scheme classification examples.

**Research flag:** Standard patterns for most of this phase. The French phonetic rhyme classification is the most nuanced area -- plint and drime documentation is authoritative, but real-world testing with Claude will reveal edge cases. Flag for validation during implementation.

### Phase 3: Enhanced Creation Experience and Utility Skills

**Rationale:** Once the core workflows are stable and the quality system is working, add features that improve the creation experience and enable more sophisticated use cases.

**Delivers:** Richer song structure options, utility skills for navigating the artist library, and preparation for v2 features.

**Features addressed:**
- Structure template library (5-10 pre-built song structures by genre)
- `list-artists` utility skill
- `review-artist` utility skill
- Production brief versioning (track iteration tracking)

**Pitfalls to prevent in this phase:**
- Reference file drift: add "Last verified" dates to all reference files; CLAUDE.md instructs Claude to treat reference files as authoritative over training data

**Architecture work:** Add `.claude/skills/list-artists/` and `.claude/skills/review-artist/`. Add `reference/suno/structure-templates.md` with genre-specific song structures. Establish versioning convention for track iteration files.

**Research flag:** Standard patterns -- this phase is primarily content creation (writing templates and utility skills) rather than novel architecture work.

### Phase 4: Cross-track Narrative and Advanced Coherence (v2 boundary)

**Rationale:** Cross-track narrative coherence and lore-lyrics integration require a mature discography (5+ tracks per artist) and a stable identity system. These are deferred until the system is proven and the artist catalog is rich enough for the features to be meaningful.

**Delivers:** Full narrative arc tracking across a discography, lore-informed lyric generation, and artist evolution controls.

**Features addressed:**
- Cross-track narrative coherence
- Lore-lyrics integration
- Artist evolution system (controlled genre/style shifts across eras)
- Album/EP planning workflow

**Research flag:** These features have sparse documentation -- the intersection of AI identity systems, narrative coherence, and music production is not well-studied. Recommend `/gsd:research-phase` before planning this phase. Lore integration in particular is a novel capability without established patterns to follow.

### Phase Ordering Rationale

- Artist bible must exist before tracks can be created (hard dependency from FEATURES.md dependency map)
- Linguistic rules must exist before track verification can run (hard dependency)
- Discography must accumulate before cross-track coherence is meaningful (data dependency)
- Phase 1 delivers complete end-to-end value immediately; all later phases are improvements on a working system
- Phases 1 and 2 address all six critical pitfalls from PITFALLS.md; Phases 3-4 build on a stable base
- Context management (Phase 2) must be established before the corpus grows past 5 tracks -- waiting longer makes it harder to retrofit

### Research Flags

Phases needing deeper research during planning:
- **Phase 4:** Cross-track narrative coherence and lore integration have no established implementation patterns in this domain. Research needed before detailed planning.
- **Phase 2 (French phonetics):** While rules are documented, Claude real-world application of French rhyme phonetics needs validation testing during Phase 1 before Phase 2 doubles down on it.

Phases with standard patterns (skip research-phase):
- **Phase 1:** Claude Skills format is official and well-documented. Suno constraints are cross-verified. Linguistic rules come from authoritative tools (plint). Well-understood territory.
- **Phase 3:** Template writing and utility skills are standard workflow work. No novel architecture.

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | Claude Code Skills and Suno V5.5 are both well-documented with official sources. Platform choice is unambiguous. |
| Features | HIGH | Dependency map is clear, MVP scope is well-defined, competitor analysis validates the approach. |
| Architecture | HIGH | Three-layer pattern is proven. Build order is clearly derived from hard dependencies. Scaling strategies are explicitly addressed. |
| Pitfalls | MEDIUM-HIGH | Suno format pitfalls cross-verified across multiple community sources. French linguistic pitfalls backed by authoritative tools (plint, drime) and academic references. Identity drift backed by peer-reviewed research. |

**Overall confidence:** MEDIUM-HIGH

### Gaps to Address

- **French phonetic rhyme verification in practice:** The rules are documented but Claude reliability in applying phonetic (not spelling-based) French rhyme analysis is untested. Validate during Phase 1 implementation with known rhyme pair test sets before building Phase 2 classification system on top of it.

- **Suno metatag effectiveness for French:** Community guides confirm tag behavior for English lyrics. French-specific behavior (language drift prevention, pronunciation effects of vocal cues) needs empirical testing in Phase 1. Build the tested-vocabulary list from real outputs.

- **Suno V5.5 style prompt character limits:** Multiple sources confirm 1000 chars max, but the "safe zone" varies (200-500 chars recommended). The actual truncation threshold should be validated empirically during Phase 1 track generation tests.

- **Distribution platform requirements:** AI music distribution policies are evolving rapidly in 2026. DistroKid and Spotify requirements noted in STACK.md should be re-verified before any release workflow is added to the system.

- **Claude context window degradation thresholds:** The 70%/85%/90% degradation thresholds from PITFALLS.md are research-based estimates. The actual token budget for this system specific mix of content should be monitored empirically during Phase 2.

## Sources

### Primary (HIGH confidence)
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/slash-commands) -- Skills format, frontmatter, $ARGUMENTS, supporting files
- [Suno V5.5 Official Blog](https://suno.com/blog/v5-5) -- Voices, Custom Models, My Taste features
- [Suno Help: V5.5 What's New](https://help.suno.com/en/articles/11362305) -- Official V5.5 changelog
- [plint -- French Poetry Checker](https://plint.a3nm.net/en/about) -- French syllabification rules, e muet, dierese, hiatus
- [Rime riche -- Britannica](https://www.britannica.com/art/rime-riche) -- French rhyme quality classification
- [Examining Identity Drift in LLM Agents (arXiv)](https://arxiv.org/abs/2412.00804) -- Drift research confirming larger models drift more
- [Context Windows -- Claude API Docs](https://docs.anthropic.com/en/docs/build-with-claude/context-windows) -- Official context window documentation
- [bitwize-music-studio/claude-ai-music-skills](https://github.com/bitwize-music-studio/claude-ai-music-skills) -- Reference implementation for Claude + Suno workflows

### Secondary (MEDIUM confidence)
- [HookGenius: Suno Character Limits](https://hookgenius.app/learn/suno-character-limits/) -- 1000 chars style prompt, 3000 chars lyrics
- [HookGenius: Suno Custom Mode Guide](https://hookgenius.app/learn/suno-custom-mode-guide/) -- Style prompt format and templates
- [HookGenius: Suno V5 Complete Guide](https://hookgenius.app/learn/suno-v5-complete-guide/) -- V5 improvements, negative prompting
- [HookGenius: Suno Pronunciation Fix Guide](https://hookgenius.app/learn/fix-suno-pronunciation/) -- Confirms no IPA support, spelling-pattern prediction
- [Jack Righteous: Suno Meta Tags Guide](https://jackrighteous.com/pages/suno-ai-meta-tags-guide) -- Structure/vocal/instrument tags
- [Jack Righteous: Suno V5 Multilingual Guide](https://jackrighteous.com/en-us/blogs/guides-using-suno-ai-music-creation/suno-v5-multilingual-english-pronunciation-guide) -- French language support, drift prevention
- [drime -- French Rhyme Dictionary](https://drime.a3nm.net/) -- Phonetic rhyme matching and quality classification
- [French Alexandrine -- Wikipedia](https://en.wikipedia.org/wiki/French_alexandrine) -- Classical French verse structure and rules
- [RhymeTagger / Multilingual Rhyme Detection (arXiv)](https://arxiv.org/abs/2604.08156) -- Language-independent rhyme detection including French

### Tertiary (LOW confidence, needs validation)
- [DistroKid AI Policy](https://support.distrokid.com/hc/en-us/articles/41182362733715) -- AI music distribution requirements (policies evolving rapidly in 2026)
- [ElevenLabs Music launch](https://techcrunch.com/2026/04/02/elevenlabs-launches-music-generation-app/) -- Emerging Suno alternative (too new to assess reliability)
- [Character Bible for AI Consistency](https://medium.com/@SomethingaboutAI/character-bible-prompts-creating-consistency-anchors-for-ai-novel-generation-724ea9b91c8b) -- Bible as consistency anchor pattern (paywalled, indirect access)

---
*Research completed: 2026-04-10*
*Ready for roadmap: yes*
