Refactor: Unified overrides directory (0.7.1) (#3)

* refactor: replace custom fields with unified overrides directory

Replace individual customization config fields with single overrides directory:

**Before (0.7.0):**
- paths.custom_instructions: ~/music-projects/CUSTOM_CLAUDE.md
- paths.custom_pronunciation: ~/music-projects/CUSTOM_PRONUNCIATION.md

**After (0.7.1):**
- paths.overrides: ~/music-projects/overrides/
  - CLAUDE.md (workflow instructions)
  - pronunciation-guide.md (phonetic spellings)
  - explicit-words.md (future)
  - lyric-writing-guide.md (future)

**Benefits:**
- Single config field for all customizations
- Self-documenting (file names match what they override)
- Easy discovery (ls overrides/)
- Future-proof (new overrides without config changes)
- Convention over configuration

**Changes:**
- config/config.example.yaml: Replace two fields with paths.overrides
- config/README.md: Replace two sections with "Overrides System" guide
- CLAUDE.md: Update session start to load from overrides directory
- skills/configure/SKILL.md: Single prompt for overrides directory
- skills/pronunciation-specialist/SKILL.md: Load from {overrides}/pronunciation-guide.md

**Migration:**
Automatic - skills check {overrides}/[file].md with fallback to base.
Old config fields removed from examples but would still work in user configs.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: release 0.7.1

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: bitwize-music

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "bitwize-music",
       "description": "AI music generation workflow for Suno - album concepts, lyrics, prompts, mastering, release",
-      "version": "0.7.0",
+      "version": "0.7.1",
       "source": "./"
     }
   ]

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bitwize-music",
   "description": "AI music generation workflow for Suno - album concepts, lyrics, prompts, mastering, release",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "author": {
     "name": "bitwize-music"
   },

CHANGELOG.md

@@ -12,7 +12,21 @@ This project uses [Conventional Commits](https://conventionalcommits.org/) and [
 
 ### Fixed
 
-## [0.7.0] - 2026-01-26
+## [0.7.1] - 2026-01-26
+
+### Changed
+- **BREAKING**: Refactored customization system to use unified overrides directory
+  - Replaced `paths.custom_instructions` with `paths.overrides`
+  - Replaced `paths.custom_pronunciation` with `paths.overrides`
+  - Single directory now contains all override files: `~/music-projects/overrides/`
+  - Override files: `CLAUDE.md`, `pronunciation-guide.md`, `explicit-words.md` (future), etc.
+  - Benefits: self-documenting, easy discovery, future-proof, convention over configuration
+  - **Note**: Released immediately after 0.7.0 to fix design before user adoption
+
+### Fixed
+- Config design now scales for future overrides without new config fields
+
+## [0.7.0] - 2026-01-26 **[DEPRECATED - Use 0.7.1]**
 
 ### Added
 - Custom instructions support (`paths.custom_instructions` config field)

CLAUDE.md

@@ -178,12 +178,12 @@ At the beginning of a fresh session:
        Option 2: mkdir -p ~/.bitwize-music && cp config/config.example.yaml ~/.bitwize-music/config.yaml
      ```
 
-1b. **Load custom instructions (if present)** - Check for user's custom Claude instructions:
-   - Read `paths.custom_instructions` from config
-   - If not set, check default location: `{content_root}/CUSTOM_CLAUDE.md`
-   - If file exists, read and incorporate the instructions immediately
-   - If file doesn't exist, skip silently (this is optional)
-   - Custom instructions supplement base CLAUDE.md (they don't override)
+1b. **Load overrides (if present)** - Check for user's override files:
+   - Read `paths.overrides` from config (default: `{content_root}/overrides`)
+   - Check for `{overrides}/CLAUDE.md` - if exists, read and incorporate instructions immediately
+   - Check for `{overrides}/pronunciation-guide.md` - if exists, merge with base pronunciation guide
+   - If override files don't exist, skip silently (overrides are optional)
+   - Override instructions supplement (don't replace) base files
 
 2. **Check skill models** - Run `/bitwize-music:skill-model-updater check` to verify all skills use current Claude models. If any are outdated, offer to update them.
 3. **Check IDEAS.md** - Check `{content_root}/IDEAS.md` for pending album ideas
@@ -269,7 +269,7 @@ Report all issues with proposed fixes, then proceed.
 
 **Pronunciation guides:**
 - Base guide: `/reference/suno/pronunciation-guide.md` (universal rules, common homographs, tech terms)
-- Custom guide: `{content_root}/CUSTOM_PRONUNCIATION.md` (artist names, album-specific terms) - optional, merged at session start
+- Override guide: `{overrides}/pronunciation-guide.md` (artist names, album-specific terms) - optional, merged at session start
 
 **Mandatory**: When using "live" in lyrics, ask which pronunciation (LYVE vs LIV).
 
@@ -359,11 +359,11 @@ For deep research, `/bitwize-music:researcher` coordinates specialists:
 
 Skills can update their own reference documentation when new issues are discovered:
 
-- `/bitwize-music:pronunciation-specialist` → Adds artist/album-specific pronunciations to custom guide (`{content_root}/CUSTOM_PRONUNCIATION.md`), never edits base guide
+- `/bitwize-music:pronunciation-specialist` → Adds artist/album-specific pronunciations to override guide (`{overrides}/pronunciation-guide.md`), never edits base guide
 - `/bitwize-music:suno-engineer` → Updates `/reference/suno/*.md` with new tips, techniques, version changes
 - `/bitwize-music:skill-model-updater` → Updates model references across all skills when new Claude models release
 
-**The rule**: When a skill discovers something new, it should add it to the relevant reference file so future invocations benefit. User-specific content (pronunciations) goes to custom guide to avoid plugin update conflicts.
+**The rule**: When a skill discovers something new, it should add it to the relevant reference file so future invocations benefit. User-specific content (pronunciations) goes to overrides directory to avoid plugin update conflicts.
 
 ### Model Strategy
 

config/README.md

@@ -40,8 +40,7 @@ paths:
   content_root: "~/music-projects"           # Albums, artists, research
   audio_root: "~/music-projects/audio"       # Mastered audio output
   documents_root: "~/music-projects/docs"    # PDFs, primary sources
-  custom_instructions: "~/music-projects/CUSTOM_CLAUDE.md"  # Optional custom workflow instructions
-  custom_pronunciation: "~/music-projects/CUSTOM_PRONUNCIATION.md"  # Optional custom phonetic spellings
+  overrides: "~/music-projects/overrides"    # Optional overrides directory
 
 # Platform URLs
 urls:
@@ -82,8 +81,7 @@ The `~/.bitwize-music/` directory also contains:
 | `paths.content_root` | Yes | Where albums and artists live |
 | `paths.audio_root` | Yes | Where mastered audio goes |
 | `paths.documents_root` | Yes | Where PDFs/sources go |
-| `paths.custom_instructions` | No | Path to markdown file with custom Claude instructions. Defaults to `{content_root}/CUSTOM_CLAUDE.md` if not set. |
-| `paths.custom_pronunciation` | No | Path to markdown file with custom phonetic spellings. Defaults to `{content_root}/CUSTOM_PRONUNCIATION.md` if not set. Merges with base pronunciation guide. |
+| `paths.overrides` | No | Directory containing override files for skills and workflows. Defaults to `{content_root}/overrides` if not set. |
 | `urls.soundcloud` | No | SoundCloud profile URL |
 | `urls.spotify` | No | Spotify artist URL |
 | `urls.bandcamp` | No | Bandcamp URL |
@@ -100,72 +98,106 @@ Config not found. Run:
 Then edit ~/.bitwize-music/config.yaml with your settings.
 ```
 
-## Custom Instructions
-
-You can provide custom Claude instructions to supplement the base CLAUDE.md workflow:
-
-**Setup:**
-1. Set `paths.custom_instructions` in config (or use default)
-2. Create the file with your custom instructions:
-   ```bash
-   touch ~/music-projects/CUSTOM_CLAUDE.md
-   ```
-3. Add your preferences:
-   ```markdown
-   # My Custom Workflow Preferences
-
-   - Always ask before creating new albums
-   - Prefer aggressive industrial sound for electronic tracks
-   - Use British spelling in all documentation
-   ```
-
-**When it loads:**
-- At session start, Claude reads this file if it exists
-- Instructions supplement (don't override) base CLAUDE.md
-- If file doesn't exist, no error - it's optional
-
-**Version control:**
-- Default location (`~/music-projects/CUSTOM_CLAUDE.md`) can be committed with your content
-- Or point to separate repo for shared workflow across projects
-
-## Custom Pronunciation Guide
-
-You can provide custom phonetic spellings to supplement the base pronunciation guide:
-
-**Setup:**
-1. Set `paths.custom_pronunciation` in config (or use default)
-2. Create the file with your custom pronunciations:
-   ```bash
-   touch ~/music-projects/CUSTOM_PRONUNCIATION.md
-   ```
-3. Add your phonetic spellings:
-   ```markdown
-   # Custom Pronunciation Guide
-
-   ## Artist-Specific Terms
-   | Word | Standard | Phonetic | Notes |
-   |------|----------|----------|-------|
-   | BitWize | bitwize | Bit-Wize | Artist name |
-   | ShellNo | shellno | Shell-No | Album title |
-
-   ## Album-Specific Names
-   | Word | Standard | Phonetic | Notes |
-   |------|----------|----------|-------|
-   | Larocca | larocca | Luh-rock-uh | Character name |
-   | Finnerty | finnerty | Finn-er-tee | Character name |
-   ```
-
-**When it loads:**
-- At session start, Claude reads this file if it exists
-- Merges with base pronunciation guide from `/reference/suno/pronunciation-guide.md`
-- Your custom entries take precedence over base guide
-- If file doesn't exist, no error - it's optional
-
-**Why separate from base guide:**
-- Plugin updates won't overwrite your additions
-- Version control your custom pronunciations with your music content
-- Share artist-specific pronunciations across projects
-
-**Version control:**
-- Default location (`~/music-projects/CUSTOM_PRONUNCIATION.md`) can be committed with your content
-- Avoids merge conflicts when plugin updates the base guide
+## Overrides System
+
+The overrides directory lets you customize any skill or workflow without plugin update conflicts.
+
+### How It Works
+
+**Single directory, per-skill files:**
+```bash
+~/music-projects/overrides/
+├── CLAUDE.md                 # Override base workflow instructions
+├── pronunciation-guide.md    # Override base pronunciation guide
+├── explicit-words.md         # Custom explicit word list (future)
+├── lyric-writing-guide.md    # Custom lyric writing preferences (future)
+└── mastering-presets.yaml    # Custom mastering settings (future)
+```
+
+**Each skill checks for its own override:**
+1. Skill reads `~/.bitwize-music/config.yaml` → `paths.overrides`
+2. Checks for `{overrides}/[filename].md`
+3. If exists: merge with base (or replace, depending on skill)
+4. If not exists: use base only (no error)
+
+### Setup
+
+```bash
+# Create overrides directory
+mkdir -p ~/music-projects/overrides
+
+# Add any override files you want
+touch ~/music-projects/overrides/CLAUDE.md
+touch ~/music-projects/overrides/pronunciation-guide.md
+```
+
+### Available Overrides
+
+#### `CLAUDE.md` - Workflow Instructions
+Supplements base CLAUDE.md with your personal workflow preferences.
+
+**Example:**
+```markdown
+# My Custom Workflow Preferences
+
+- Always ask before creating new albums
+- Prefer aggressive industrial sound for electronic tracks
+- Use British spelling in all documentation
+```
+
+**Behavior:** Loaded at session start, supplements (doesn't override) base instructions.
+
+#### `pronunciation-guide.md` - Phonetic Spellings
+Merges with base pronunciation guide for artist-specific terms.
+
+**Example:**
+```markdown
+# Custom Pronunciation Guide
+
+## Artist-Specific Terms
+| Word | Standard | Phonetic | Notes |
+|------|----------|----------|-------|
+| BitWize | bitwize | Bit-Wize | Artist name |
+| ShellNo | shellno | Shell-No | Album title |
+
+## Album-Specific Names
+| Word | Standard | Phonetic | Notes |
+|------|----------|----------|-------|
+| Larocca | larocca | Luh-rock-uh | Character name |
+| Finnerty | finnerty | Finn-er-tee | Character name |
+```
+
+**Behavior:** Loaded by pronunciation-specialist, merged with base guide, custom takes precedence.
+
+#### Future Overrides
+
+These don't exist yet but will follow the same pattern:
+
+- **`explicit-words.md`** - Custom explicit word list for your content
+- **`lyric-writing-guide.md`** - Personal lyric writing style preferences
+- **`mastering-presets.yaml`** - Custom mastering EQ/compression settings
+- **`suno-genre-mappings.md`** - Your preferred Suno genre combinations
+
+### Benefits
+
+**For users:**
+- **One directory** - All customizations in one place
+- **Self-documenting** - File names match what they override
+- **Version control** - Commit overrides with your music content
+- **No conflicts** - Plugin updates won't overwrite your files
+- **Easy discovery** - `ls overrides/` shows what's overrideable
+
+**For skills:**
+- **Convention over configuration** - Skills know where to look
+- **No config proliferation** - No new config field per customization
+- **Future-proof** - New overrides added without touching config
+
+### Version Control
+
+```bash
+# .gitignore (in your content repo)
+# Commit overrides with your content
+!overrides/
+```
+
+Default location (`~/music-projects/overrides/`) can be committed with your music content to share preferences across projects.

config/config.example.yaml

@@ -39,17 +39,17 @@ paths:
   # Structure: {documents_root}/[artist]/[album]/
   documents_root: "~/music-projects/documents"
 
-  # Custom Claude instructions (optional)
-  # File containing additional workflow instructions for Claude
-  # If not set, Claude will check for ~/music-projects/CUSTOM_CLAUDE.md
-  # Set to your content_root or separate repo for version control
-  custom_instructions: "~/music-projects/CUSTOM_CLAUDE.md"
-
-  # Custom pronunciation guide (optional)
-  # File containing your custom phonetic spellings for artist names, album-specific terms
-  # If not set, Claude will check for ~/music-projects/CUSTOM_PRONUNCIATION.md
-  # Merges with base pronunciation guide at session start
-  custom_pronunciation: "~/music-projects/CUSTOM_PRONUNCIATION.md"
+  # Overrides directory (optional)
+  # Directory containing override files for skills and workflows
+  # Each skill checks this directory for its own override file
+  # Examples:
+  #   - CLAUDE.md (overrides base workflow instructions)
+  #   - pronunciation-guide.md (merges with base pronunciation guide)
+  #   - explicit-words.md (custom explicit word list)
+  #   - lyric-writing-guide.md (custom lyric writing preferences)
+  # If not set, defaults to ~/music-projects/overrides
+  # If directory doesn't exist, skills use base files only (no error)
+  overrides: "~/music-projects/overrides"
 
   # tools_root is always ~/.bitwize-music (where this config lives)
   # Contains: mastering-env/, cache/, etc.