Session Start

Your Task

Run the full session start procedure and report project status to the user.

Session Start Skill

You perform the 8-step session startup procedure that initializes a working session.

Step 1: Verify Setup

Quick dependency check:

~/.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 (~/.bitwize-music/config.yaml doesn't exist): suggest /bitwize-music:configure
• Don't proceed until setup is complete

Step 1.5: Health Check

Use the health_check MCP tool (checks venv packages + skill registration + album slug collisions in one call):

Venv results (from result.venv):

• status: "ok" → continue silently
• status: "stale" → warn with mismatches and fix command, continue session
• status: "no_venv" → stop and suggest /bitwize-music:setup
• status: "error" → warn and continue

Skill registration results (from result.skills):

• status: "ok" → continue silently
• status: "stale" → warn: list missing and ghost skill names, show fix message
• status: "no_cache" → warn that plugin cache not found, continue

Album slug collision results (from result.collisions):

• status: "ok" → continue silently
• status: "collision" → warn: list each slug with its kept and shadowed genres, show the fix (rename one album with /bitwize-music:rename or move its directory, then run rebuild_state), continue session

Step 2: Load Config

Read ~/.bitwize-music/config.yaml.

If missing, tell user to run /bitwize-music:configure.

Step 3: Load Overrides

Read paths.overrides from config (default: {content_root}/overrides):

• Check for {overrides}/CLAUDE.md — incorporate instructions if found
• Check for {overrides}/pronunciation-guide.md — note if found
• Skip silently if missing (overrides are optional)

Step 4: Load State Cache

Read ~/.bitwize-music/cache/state.json:

• If missing, corrupted, schema mismatch, or config changed: rebuild via MCP

  rebuild_state()

Step 4.5: Check for Plugin Upgrades

Call the get_pending_migrations MCP tool. It compares the installed plugin version against last_migrated_version in state (the last version whose migrations were processed — distinct from plugin_version, which only records the installed version for display) and returns the pending notes already parsed and sorted.

1. If pending is empty (reason: "current", or reason: "unknown" when the installed version can't be read from plugin.json): No action needed.
2. If pending is non-empty (reason: "upgrade" or "untracked"): For each migration, process its actions in order:
   • auto: Execute silently (run check first — skip if it returns 0)
   • action: Show description, ask the user to confirm before executing
   • info: Display to the user
   • manual: Show the instruction to the user
3. After processing all notes, call acknowledge_migrations (no argument acknowledges everything up to the installed version) so the same notes do not surface again next session.
4. Report: "Upgraded to Y" with a summary of the actions taken.

reason: "untracked" means the state predates migration tracking; the full backlog up to the installed version is surfaced once, then cleared by acknowledge_migrations. Do NOT just rebuild state to clear migrations — a rebuild preserves the pending status; only acknowledge_migrations records that you processed them.