CLAUDE.md · bitwize-music-studio/claude-ai-music-skills

Sections

1. ⚠️ CRITICAL: Finding Albums When User Mentions Them
2. Configuration & Path Resolution
3. MCP Server — Preferred Data Access
4. Session Start
5. Core Principles
6. Workflow Overview
7. Content Structure
8. Versioning & Development
9. Mid-Session Rules

First lines (shown under the repo's CC0-1.0 license)

# AI Music Skills - Claude Instructions

This is an AI music generation workflow using Suno. Skills contain domain expertise; this file contains workflow rules and structure that apply every session.

---

## ⚠️ CRITICAL: Finding Albums When User Mentions Them

**WHENEVER the user mentions an album name**, use the resume skill:
```
/bitwize-music:resume my-album
```

**If skill unavailable**, manual approach:
1. Read `~/.bitwize-music/cache/state.json` — search `state.albums` keys (case-insensitive)
2. If cache missing/stale: read config → glob `{content_root}/artists/{artist}/albums/*/*/README.md` → rebuild cache with `rebuild_state()` MCP tool

**DO NOT**: search from cwd, use complex globs, assume paths, or use `ls`/`find`.

Album slugs are globally unique across genres; if `health_check` reports a slug collision, resolve it (rename or move the directory, then rebuild) before trusting lookups.

---

## Configuration & Path Resolution

Config is **always** at: `~/.bitwize-music/config.yaml`

**ALWAYS read config fresh before** moving/creating files, resolving path variables, or using artist name in paths. Never assume or remember values.

**Path variables** (from config):
- `{content_root}` = `paths.content_root`
- `{audio_root}` = `paths.audio_root`
- `{documents_root}` = `paths.documents_root`
- `{tools_root}` = `~/.bitwize-music`
- `{plugin_root}` = the directory containing this CLAUDE.md file (= `${CLAUDE_PLUGIN_ROOT}` in skills)
- `[artist]` = `artist.name`

**IMPORTANT — Mirrored path structure**:
```
{content_root}/artists/[artist]/albums/[genre]/[album]/   # Album files (in git)
{audio_root}/artists/[artist]/albums/[genre]/[album]/     # Mastered audio
{documents_root}/artists/[artist]/albums/[genre]/[album]/ # PDFs (not in git)
```
Audio and document paths include `[artist]/` after the root. Common mistake: omitting the artist folder.

First-time setup: `cp config/config.example.yaml ~/.bitwize-music/config.yaml` — see `config/README.md`.

---

## MCP Server — Preferred Data Access

The `bitwize-music-mcp` server is the **preferred way to query project state**. Use MCP tools instead of reading files directly — they're faster (single call vs multiple file reads) and return structured data.

**Use MCP tools for:**
- **Albums/tracks** → `list_albums`, `find_album`, `get_track` (not reading state.json or globbing for READMEs)
- **Skills** → `list_skills`, `get_skill` (not reading individual SKILL.md files)
- **Ideas** → `get_ideas` (not reading IDEAS.md)
- **Pending verifications** → `get_pending_verifications`
- **Config** → `get_config` (not reading config.yaml for simple lookups)
- **Session context** → `get_session`, `update_session`
- **Cross-scope search** → `search`
- **Stale cache** → `rebuild_state`

**Fall back to direct file access only when:** MCP server is unavailable, you need to edit files (MCP is read-only), or you need raw file content not exposed through MCP (e.g., full lyrics, research docs).

---

## Session Start

At the beginning of a fresh session:

1. **Verify setup** — Quick dependency check:
   ```bash
   ~/.bitwize-music/venv/bin/python3 -c "import mcp.server.mcpserver" 2>/dev/null || ~/.bitwize-music/venv/bin/python3 -c "import mcp.server.fastmcp" 2>/dev/null && echo "✅ MCP ready" || echo "❌ MCP unusable"        # macOS/Linux/WSL
   ~/.bitwize-music/venv/Scripts/python.exe -c "import mcp.server.mcpserver" 2>/dev/null || ~/.bitwize-music/venv/Scripts/python.exe -c "import mcp.server.fastmcp" 2>/dev/null && echo "✅ MCP ready" || echo "❌ MCP unusable" # Windows (Git Bash; cmd/PowerShell: %USERPROFILE%\.bitwize-music\venv\Scripts\python.exe)
   ```
   - If MCP unusable → **Stop immediately** and suggest: `/bitwize-music:setup mcp` (the SDK is missing or predates 1.28.1). Probe both server modules, never bare `import mcp`: 2.x serves `MCPServer` from `mcp.server.mcpserver` and 1.x serves `FastMCP` from `mcp.server.fastmcp`, and the server accepts either — but a bare `import mcp` succeeds even when neither module is present, reporting healthy on an install the server cannot boot on
   - If config missing → suggest: `/bitwize-music:configure`
   - Don't proceed with session start until setup is complete
1.5. **Health check** — Use `health_check` MCP tool (checks venv + skill registration):
   - Venv `status: "ok"` → continue silently
   - Venv `status: "stale"` → warn with mismatches and fix command, continue session
   - Venv `status: "no_venv"` → **stop** and suggest `/bitwize-music:setup`
   - Venv `status: "error"` → warn and continue
   - Skills `status: "ok"` → continue silently
   - Skills `status: "stale"` → warn with missing/ghost skill names and fix message, continue session
   - Skills `status: "no_cache"` → warn (plugin may not be installed via marketplace), continue
   - Collisions `status: "collision"` → warn listing each slug + genres and the fix (rename one album with `/bitwize-music:rename` or move the directory, then `rebuild_state`), continue session
2. **Load config** — Read `~/.bitwize-music/config.yaml`. If missing, tell user to run `/bitwize-music:configure`.
3. **Load overrides** — Check `paths.overrides` (default: `{content_root}/overrides`):
   - `{overrides}/CLAUDE.md` → incorporate instructions
   - `{overrides}/pronunciation-guide.md` → merge with base guide
   - Skip silently if missing (overrides are optional)
4. **Load state via MCP** — Use MCP tools to query project state:
   - `get_config` → verify config is loaded
   - `list_albums` → get album statuses
   - `get_ideas` → get idea counts
   - `get_pending_verifications(summary_only=True)` → check for pending source verifications (count only)
   - `get_session` → resume last session context
   - If MCP returns errors about missing/stale cache → `rebuild_state()` MCP tool
4.5. **Check for plugin upgrades** — Call the `get_pending_migrations` MCP tool (compares the installed version against state's `last_migrated_version`, not `plugin_version`):
   - `pending` empty (`reason: "current"`, or `"unknown"` when plugin.json is unreadable) → no action
   - `pending` non-empty (`reason: "upgrade"` or `"untracked"`) → process each note's actions in order, then call `acknowledge_migrations` to record them as done
   - Never clear migrations by rebuilding state — a rebuild preserves pending status; only `acknowledge_migrations` advances `last_migrated_version`
5. _(Removed — skills use tier aliases (`opus`/`sonnet`/`haiku`) that auto-track the frontier model, and the test suite (`/bitwize-music:test`) enforces model/effort hygiene, so no action is needed on new releases.)_
6. **Report from MCP state**:
   - Health warnings (from step 1.5 — omit if ok):
     - Venv stale: "⚠️ Venv has N outdated package(s): pkg1 (1.0.0 → 1.1.0), ... Run: `<venv check's fix field from health_check>`" (already the correct command for the user's OS)
     - Skills stale: "⚠️ N skill(s) missing from Claude Code, N ghost — run: `claude plugin update bitwize-music`"
   - Album ideas (from `get_ideas`)
   - In-progress albums (status: "In Progress", "Research Complete", "Complete")
   - Pending source verifications (from `get_pending_verifications(summary_only=True)`)
   - Last session context (from `get_session`)
7. **Show contextual tips** based on state:
   - No albums → suggest `/bitwize-music:tutorial`
   - Ideas exist → suggest `/bitwize-music:album-ideas list`
   - In-progress albums → suggest `/bitwize-music:resume [album-name]`
   - Overrides loaded → note it; missing → suggest creating them (see `config/README.md` for override file reference)
   - Pending verifications → warn and suggest `/bitwize-music:verify-sources`
   - One contextual tip from: resume, researcher, pronunciation, clipboard, mastering (pick based on most relevant album state)
8. **Ask**: "What would you like to work on?"

---

## Core Principles

**Be a collaborator, not a yes-man.** Push back when ideas don't work. The goal is good music, not agreement.

**Preserve exact casing and spelling.** "bitwize" stays "bitwize" — never auto-capitalize user-provided names, titles, or text.

**Ask when unsure.** Word choice, style, structure, Suno settings — don't guess.

**Pronunciation hard rule**: Suno CANNOT infer pronunciation from context. When any homograph is found (live, read, lead, wound, close, bass, tear, wind, etc.), **ASK** the user which pronunciation is intended — never assume. Fix with phonetic spelling in Suno lyrics only. See `/skills/lyric-writer/SKILL.md` and `/reference/suno/pronunciation-guide.md` for full rules.

**After writing or revising lyrics**, run the 13-point quality checklist from `/skills/lyric-writer/SKILL.md`. Report violations without being asked.

**When user says "let's work on [track]"**, scan full lyrics for issues BEFORE doing anything else: weak lines, prosody problems, POV/tense inconsistencies, twin verses, missing hook, factual errors, flow/pronunciation risks.

---

## Workflow Overview

Concept → Research → Write (+Suno Prompt) → [Refine] → QC/Verify → Generate → [Polish] → Master → Promo Videos (optional) → Promo Copy (optional) → **Release**

**Critical**: Research must complete before writing for source-based content. Human source verification is required before generation — never skip this gate.

### Key Routing Rules

- **Album mentioned** → `/bitwize-music:resume`
- **"Make a new album"** → IMMEDIATELY use `/bitwize-music:new-album` BEFORE any discussion
- **"Turn idea into album" / "promote [idea]"** → `/bitwize-music:promote-idea "<idea title>"` (one-shot: creates album from a Pending idea, injects concept, updates status)
- **Writing lyrics** → apply `/bitwize-music:lyric-writer` expertise (auto-invokes suno-engineer)
- **Refining/polishing lyrics** → `/bitwize-music:lyric-refiner` (post-writing multi-pass refinement)
- **Planning album** → apply `/bitwize-music:album-conceptualizer` (7 planning phases required)
- **Suno prompts** → apply `/bitwize-music:suno-engineer` expertise (usually auto-invoked by lyric-writer; use directly only for re-prompting)
- **Research needed** → apply `/bitwize-music:researcher` standards
- **Polishing audio / fixing Suno artifacts** → apply `/bitwize-music:mix-engineer` expertise
- **Mastering audio** → polish first via `/bitwize-music:mix-engineer`, then apply `/bitwize-music:mastering-engineer` standards. Skip polish only if: (a) user says "master only", "skip polish", or "already polished"; or (b) polished audio already exists at `{audio_root}/artists/[artist]/albums/[genre]/[album]/polished/`. Applies equally to single-track and whole-album mastering.
- **Album art** → apply `/bitwize-music:album-art-director`
- **Writing promo copy** → apply `/bitwize-music:promo-writer` expertise