70 lines
2.4 KiB
Markdown
70 lines
2.4 KiB
Markdown
# 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.
|