# 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.
-   [x] Implement immutable or snapshot-based version history.
-   [x] Restore a previous version without destroying later versions.
-   [x] Add autosave strategy that does not create excessive versions.

## Phase 3 --- Core macOS UI

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

## Phase 4 --- OpenAI Integration

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

## Phase 5 --- Arabic Lyrics Processing

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

## Phase 6 --- Instrument Selector & Catalog

-   [x] Create structured catalog models for instrument id, name,
    family/category, optional region/origin and aliases/search terms.
-   [x] 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.
-   [x] Keep catalog data out of SwiftUI views.
-   [x] Build searchable instrument browser.
-   [x] Add browsing/filtering by family/category.
-   [x] Add browsing/filtering by region/origin where useful.
-   [x] Add checkbox-based multi-select and deselect behavior.
-   [x] Persist selected instruments on the current Song Project.
-   [x] Make selected instruments available to OpenAI/song-generation
    logic for arrangement, roles, entry/exit timing, relevant structure
    decisions and Suno Style Prompt generation.
-   [x] Preserve existing Manual/Auto arrangement behavior.
-   [x] Add tests for catalog search, category/region filtering,
    selection persistence and SongProject serialization.

## Phase 7 --- Prompt Compiler

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

## Removed --- External Generation Handoff

-   [x] Removed opening, embedding and controlling external
    music-generation websites.

## Phase 9 --- Quality

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

## 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 retain the approved final
lyrics and style prompt in the project.

## Current Improvements

-   [x] Add confirmed project deletion from the project browser.
-   [x] Add a worldwide genre and style selector with checkbox multi-select.
-   [x] Add a vocalist preset selector with checkbox multi-select.
-   [x] Add a language selector with checkbox multi-select.