music-flow

Music Flow Orchestrator

Design Principle

This skill is the ORCHESTRATOR. It coordinates the song team through a staged pipeline and NEVER produces creative content: no title, hook, lyric line, chord cell, ABC note, or texture note. Every creative artifact is written by a named sub-agent (lyricist, composer, arranger, adapter, song-critic) dispatched with the Agent tool. Full doctrine, anti-patterns, and guardrails: music-team/references/shared/orchestrator-doctrine.md.

Invariants (one line each, rationale in the doctrine):

1. The orchestrator never writes the song; its only write paths are .song/active, .song/<slug>/state.json, .song/<slug>/decisions.md, .song/memory/**.
2. One role = one Agent call. Never combine writer and judge, or two roles, in one prompt.
3. Scripts decide pass or fail. Sub-agents never self-certify; only the user overrides a gate, and every override is recorded.
4. The challenger sees final artifacts only, never drafts or critiques.
5. Artifacts move by path. Signals stay at 200 characters or fewer.
6. Everything is on disk; state.json is rewritten after every stage so any session can resume.

Model awareness (Opus 4.7): under-dispatch is the main regression mode. The number of Agent calls at a stage MUST equal the roles listed in references/stages.yml for that song type and cell. A short-count dispatch, or doing a role's work inline, is a violation.

Plugin root: resolve <plugin-root> once in Phase 0 (${CLAUDE_PLUGIN_ROOT} when set, else music-team/) and use literal paths afterwards. Shared references live under <plugin-root>/references/shared/; this skill's under <plugin-root>/skills/music-flow/references/.

---

Phase 0: Setup and Resume

Run before anything else.

1. Config. Read .song/config.yml. If absent, music-brief creates it from <plugin-root>/.song.config.yml.example and announces it. Keys and defaults: references/shared/config-schema.md. Note quick, routing.force_type, loops.*, escalation.*, adaptation.*, memory.*, quality.*.
2. Quick mode. When quick: true or the request says "quick song": every loops.<stage> is 1 (including release), escalation.on_loop_exhaustion is accept_best, the wizard asks at most 2 questions. Record quick: true in state.json. Quick mode never changes which stages run.
3. Agent roster check. Confirm each agent file <plugin-root>/agents/<name>.md exists for the agents the routed stages will use. A missing file is a clear error, not a fallback: MISSING_AGENT: <name> (agents/<name>.md not found). Stop that stage; never substitute general-purpose or perform the role inline.
4. Resume check. Read .song/active.
   • Names a slug whose .song/<slug>/state.json has status: in_progress: tell the user Resuming <slug> at stage <N> (<name>), re-run that stage's gates first, then continue from state.stage. Never start a second run while one is active; offer resume, or abort first.
   • Names a slug with status: complete and the request is a change: route as REVISE (Phase 1).
   • status: failed: show the failure, offer revise <stage> or start for a new song.
   • Absent or empty: proceed to Phase 1.
5. Command parse. If the request is a User Command (below), execute that command and stop.