# 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

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

## Phase 1 --- Domain Model

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

## Phase 2 --- Project Persistence & Versions

-   [x] Create new/open/save song projects locally.
-   [x] 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.