# Song Planner LLM Contract

Updated: 2026-06-19

## Product Role

Song Planner is the user's durable workspace for AI-assisted music creation. It combines:

- a public genre encyclopedia;
- a private authenticated planner;
- structured creation records for song plans, research notes, lyric drafts, prompt attempts, generation attempts, source checks, and agent runs.

The app owns memory, permissions, workflow state, source/provenance records, and user review. The assistant owns reasoning, research, synthesis, drafting, browser work, and judgment. External services such as Suno are only operated when the user has access and explicitly asks the assistant to use them.

## Account And Auth Expectations

Private planner data requires a signed-in Song Planner account through Clerk. Backend functions derive owner/account identity from the authenticated caller. Clients and agents must not send or choose owner IDs or user IDs.

Remote MCP/OAuth is planned but is not a verified public setup yet. Do not tell users that a remote MCP endpoint, OAuth client setup, or hosted tool list is ready until this file names the endpoint and verified clients.

The planned tool contract draft is available at `/mcp-tool-contract.txt`. Treat it as an implementation contract, not a live endpoint.

## First Workflow

1. Open `/planner` and sign in.
2. Choose the project that owns the song idea.
3. Create or open a song plan in the Agent creation workspace.
4. Save research notes with source limits and uncertainty.
5. Save lyric drafts in the correct creation mode.
6. Save prompt attempts with style prompt, genre recipe, settings, and target platform.
7. Log generation attempts with Suno/audio URLs when available.
8. Use the planner table to review generated versions, ratings, picks, rejections, and album decisions.

## Creation Modes

- `exact-public-domain`: preserve public-domain lyrics exactly because that is the user's goal.
- `adapted-public-domain`: transform public-domain lyrics while keeping source lineage visible.
- `scripture-idea`: write from scripture, themes, or ideas rather than copying a song text.
- `original`: create a complete original song.

## Current Durable Records

- `songPlan`: the main durable idea and workflow status.
- `songResearchNote`: source notes, constraints, genre references, and uncertainty.
- `songLyricDraft`: draft lyrics, source alignment, rationale, and mode.
- `songPromptAttempt`: style prompt, target platform, genre recipe, settings, and prompt status.
- `songGenerationAttempt`: Suno or other external generation result, links, status, notes, and rating.
- `songSourceCheck`: source status, query used, summary, limitations, and section coverage.
- `agentRun`: summary and stats for an assistant work session.

## Planned MCP Tool Families

These names describe the intended remote tool surface. Treat them as planned unless the live MCP docs later mark them verified.

- `songplanner_get_workspace_context`
- `songplanner_list_projects`
- `songplanner_get_project_context`
- `songplanner_get_song_plan_context`
- `songplanner_upsert_song_plan`
- `songplanner_write_research_note`
- `songplanner_upsert_lyric_draft`
- `songplanner_upsert_prompt_attempt`
- `songplanner_log_generation_attempt`
- `songplanner_log_source_check`
- `songplanner_save_creation_result`
- `songplanner_get_genre_recipe`

Tool design rule: prefer workflow tools and one-call saves over raw database CRUD. Writes should be idempotent by project key, plan key, section key, draft key, attempt key, or source-check key.

Detailed draft schemas and verification requirements: `/mcp-tool-contract.txt`.

## Genre Recipe Guidance

Use the public genre encyclopedia for style ingredients: instrumentation, rhythm, vocal style, production texture, era markers, mood, and related subgenres. Avoid prompting that copies a protected artist identity. Prefer generic style language and blended genre ingredients.

## Suno Guidance

Song Planner can store Suno prompts and generated results. It does not itself control Suno in V1. An assistant may use Suno through the user's browser or other approved workflow only when the user has access and asks for that operation. Save result URLs, audio URLs, titles, notes, failures, retries, and selected takes back into Song Planner.

## Safety Rules

- Do not export private workspace data.
- Do not perform destructive actions in V1.
- Do not change auth, billing, secrets, or external accounts without explicit user approval.
- Do not claim copyright/public-domain certainty unless a source check supports it.
- Record uncertainty, source limitations, and blocked/gated source access.
- Do not scrape private user data or unrelated browser/account content.
- Do not create public links or exports of private work unless the user asks.

## Reconnect Guidance

If future MCP tools appear stale in an assistant client, reconnect the client, refresh the tool list, and then call the workspace context tool first. Until a verified MCP endpoint is published, use the authenticated web UI and Convex-backed creation workspace.