music-assistant/AGENTS.md

Agent Guide

This file is the permanent operating guide for any coding agent working on this project.

Project Scope

• This project is a native macOS application.
• The minimum deployment target is macOS 14.0.
• Use Swift and SwiftUI according to the architecture documented for this project.
• Do not invent undocumented features or requirements.
• Any substantial change to the architecture or product scope must be documented before implementation.

Required Reading

Before making significant changes, read:

• docs/PRODUCT.md
• docs/ARCHITECTURE.md
• docs/DATA_MODEL.md
• docs/TASKS.md
• docs/OPEN_QUESTIONS.md

Use these documents as the project references:

• docs/PRODUCT.md is the source of truth for product requirements.
• docs/ARCHITECTURE.md is the reference for architecture decisions.
• docs/DATA_MODEL.md is the reference for data models.
• docs/TASKS.md is the reference for implementation phases and tasks.
• docs/OPEN_QUESTIONS.md contains decisions that are not resolved yet.

Decision Rules

• If documents conflict, do not guess. State the conflict before making a decision.
• Do not decide anything listed in docs/OPEN_QUESTIONS.md on your own.
• Do not automatically move to a new phase in docs/TASKS.md unless explicitly asked.
• Update docs/TASKS.md when tasks are completed.
• Preserve version history and the Song Project concept as documented.

Code Standards

• Write organized code that is maintainable and extensible.
• Keep clear separation between UI, Models, Services, Persistence, and Integrations.
• Keep OpenAI, instrument catalog/selector, and Suno integrations separated from UI logic as much as possible.
• In the current scope, the app prepares and stores final lyrics and style prompts only; it does not open, embed or control an external music-generation website.
• Do not modify files outside the task scope without a clear reason.
• Do not perform a broad refactor while implementing a small task unless it is explicitly required.

Secrets And Configuration

• Do not place API keys, tokens, or secrets in source code or Git.
• Read secrets only from secure environment or configuration mechanisms.
• Do not log secrets.

Verification

• Run a build after code changes.
• Run relevant tests when they are available.
• Do not consider a task complete if the project fails to build because of new changes.