music-assistant/docs/TASKS.md

Agent Task Plan --- AI Music Studio macOS

Operating Rule

Work incrementally. Do not invent product requirements. When a requirement is missing and blocks implementation, record it in OPEN_QUESTIONS.md instead of silently deciding it.

Phase 0 --- Repository Foundation

• Inspect existing repository and document current state.
• Create/confirm native macOS project structure.
• Establish clear Presentation / Domain / Services / Integrations / Persistence boundaries.
• Add configuration strategy for development secrets without committing keys.
• Add basic unit-test target.
• Ensure project builds cleanly.

Phase 1 --- Domain Model

• Implement SongProject and supporting models from DATA_MODEL.md.
• Model genres/styles as multi-select.
• Model song sections with order and optional timestamps.
• Model instruments, variants, roles and placements.
• Model multiple vocalists and section assignments.
• Model language/dialect and Arabic pronunciation settings.
• Model BPM, key, scale and maqam with Manual/Auto state.
• Model emotional arc and production directions.
• Add serialization tests.

Phase 2 --- Project Persistence & Versions

• Create new/open/save song projects locally.
• Implement project list.
• Implement immutable or snapshot-based version history.
• Restore a previous version without destroying later versions.
• Add autosave strategy that does not create excessive versions.

Phase 3 --- Core macOS UI

• Build project browser.
• Build natural chat workspace as the primary entry point.
• Build editable project inspector for duration, genres, instruments, vocals and language.
• Build song structure editor.
• Build arrangement editor supporting section-based and timestamp-based placement.
• Add Manual/Auto toggles for supported controls.
• Build final review screen where every generated field can be edited.

Phase 4 --- OpenAI Integration

• Create provider-independent AIService interface.
• Implement OpenAI client.
• Define private application-rule injection mechanism.
• Define structured AI response schema for SongProject updates.
• Implement idea → complete project generation.
• Implement existing lyrics → correction/improvement flow.
• Implement Auto mode for structure, arrangement, BPM/key/maqam and production decisions.
• Implement optional Discuss mode.
• Enforce user-lock/manual-value precedence over AI output.
• Add error, retry, cancellation and rate-limit handling.

Phase 5 --- Arabic Lyrics Processing

• Add Arabic-specific settings UI.
• Support diacritics/harakat/tanween processing.
• Preserve intentional spelling/dialect choices where possible.
• Allow user to compare/edit processed Arabic before Suno handoff.
• Add Arabic test fixtures covering multiple dialects.

Phase 6 --- Instrument Selector & Catalog

• Create structured catalog models for instrument id, name, family/category, optional region/origin and aliases/search terms.
• Provide large worldwide catalog data covering Western, Middle Eastern, African, South Asian, East Asian, Southeast Asian, Latin American, traditional, folk, orchestral, electronic and modern instruments.
• Keep catalog data out of SwiftUI views.
• Build searchable instrument browser.
• Add browsing/filtering by family/category.
• Add browsing/filtering by region/origin where useful.
• Add checkbox-based multi-select and deselect behavior.
• Persist selected instruments on the current Song Project.
• Make selected instruments available to OpenAI/song-generation logic for arrangement, roles, entry/exit timing, relevant structure decisions and Suno Style Prompt generation.
• Preserve existing Manual/Auto arrangement behavior.
• Add tests for catalog search, category/region filtering, selection persistence and SongProject serialization.

Phase 7 --- Prompt Compiler

• Create deterministic compiler from approved SongProject → Suno output.
• Generate lyrics text with section/performance directives where appropriate.
• Generate style prompt from genre blend, instrumentation, vocals, tempo, harmony, emotion and production instructions.
• Validate output before handoff.
• Keep compiler independent from UI and OpenAI client.

Phase 8 --- Suno Handoff

• Implement explicit Send to Suno action.
• Open the appropriate Suno creation surface.
• Fill supported fields with approved project output.
• Never trigger Generate automatically.
• Detect/report when fields cannot be filled rather than silently failing.
• Keep integration isolated because Suno UI can change.

Phase 9 --- Quality

• Add validation for contradictory/invalid project settings.
• Add loading, offline and provider-error states.
• Add accessibility labels and keyboard navigation.
• Test project/version recovery.
• Test AI output against locked user choices.
• Test selected instruments influence compiled song-generation context.
• Test Suno handoff without generation.

Definition of MVP Done

A user can create a macOS song project through chat, manually or automatically configure the agreed song parameters, generate/edit lyrics and song planning through OpenAI, select instruments, review the complete project, save versions, and send the approved lyrics/style data to Suno where the app fills fields without initiating generation.