bitwize-music-studio/claude-ai-music-skills / skills/session-start
session-start
VerifiedRuns the session startup procedure - verifies setup, loads config and state, checks skill models, and reports project status. Use at the beginning of a fresh session.
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 bareimport mcp: 2.x servesMCPServerfrommcp.server.mcpserverand 1.x servesFastMCPfrommcp.server.fastmcp, and the server accepts either — but a bareimport mcpsucceeds even when neither module is present, reporting healthy on an install the server cannot boot on - If config missing (
~/.bitwize-music/config.yamldoesn'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 silentlystatus: "stale"→ warn with mismatches and fix command, continue sessionstatus: "no_venv"→ stop and suggest/bitwize-music:setupstatus: "error"→ warn and continue
Skill registration results (from result.skills):
status: "ok"→ continue silentlystatus: "stale"→ warn: list missing and ghost skill names, show fix messagestatus: "no_cache"→ warn that plugin cache not found, continue
Album slug collision results (from result.collisions):
status: "ok"→ continue silentlystatus: "collision"→ warn: list each slug with its kept and shadowed genres, show the fix (rename one album with/bitwize-music:renameor move its directory, then runrebuild_state), continue session
Step 1.6: Suno MCP (optional)
Two facts decide the Suno line: whether a Suno MCP server is connected (a tool named audio-create exists on any connected MCP server), and whether one is registered (the suno section of the health_check result from Step 1.5: status is configured or missing, with servers[0].name, reminder and fix). The server is optional, so none of this is a warning and none of it stops the session.
-
Connected → read
account-usageonce (free) and show the plan and the downloads left:Suno: connected — Premier Plan, 15 downloads left(suno_account.plan.name,suno_account.download_credits_remaining). If that call fails, justSuno: connected -
Registered but not connected →
Suno: configured as "<servers[0].name>" but not connected — run /mcp and sign in -
Missing,
reminder: true→ show how to add it, as its own short block after the Setup lines:Suno: not connected. /bitwize-music:generate and /bitwize-music:listen need Suno's MCP server. Add it once: claude mcp add --transport http suno https://api.suno.com/mcp then run /mcp and sign in. Add --scope user to have it in every project. (Hide this with generation.suno_mcp_reminder: false in your config.)Use the
fixfields from the result rather than retyping them. In Codex, give the link infix.other_assistantsinstead of theclaudecommand. -
Missing,
reminder: false→Suno: not connected (optional)
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
Query state through the MCP tools rather than reading files:
get_config— confirm the config loadedlist_albums— album statusesget_ideas— idea countsget_pending_verifications(summary_only=True)— pending source verifications (count only)get_session— the last session's context
If a tool reports a missing or stale cache (or the cache is corrupted, has a schema mismatch, or the config changed), rebuild it with rebuild_state() and query again. Only when the MCP server is unavailable, read ~/.bitwize-music/cache/state.json directly.
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.
- If
pendingis empty (reason: "current", orreason: "unknown"when the installed version can't be read from plugin.json): No action needed. - If
pendingis non-empty (reason: "upgrade"or"untracked"): For each migration, process itsactionsin order:auto: Execute silently (runcheckfirst — skip if it returns 0)action: Show description, ask the user to confirm before executinginfo: Display to the usermanual: Show the instruction to the user
- 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. - 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 byacknowledge_migrations. Do NOT just rebuild state to clear migrations — a rebuild preserves the pending status; onlyacknowledge_migrationsrecords that you processed them.
Step 5: (Removed)
Skill model checking is no longer part of session start. 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 manual model checking is needed when new Claude models are released.
Step 6: Report From State Cache
Using the results of Step 4, report:
Album Ideas
From get_ideas — show count by status (Pending, In Progress, etc.)
In-Progress Albums
From list_albums, the albums with status "In Progress", "Research Complete" or "Complete"
For each, show:
- Album name, genre, status
- Track progress (completed/total)
Pending Source Verifications
From get_pending_verifications(summary_only=True)
If any found, warn: "These tracks have unverified sources — generation is blocked until verified."
Last Session Context
From get_session:
- Last album worked on
- Last phase
- Pending actions
Step 7: Show Contextual Tips
Based on state, show ONE relevant tip:
| Condition | Tip |
|---|---|
| No albums exist | "Try /bitwize-music:tutorial to create your first album" |
| Ideas exist but no albums | "You have album ideas! Use /bitwize-music:album-ideas list to review them" |
| In-progress albums exist | "Resume where you left off: /bitwize-music:resume <album-name>" |
| Overrides loaded | "Custom overrides loaded from {overrides}/" |
| Overrides missing | "Customize your workflow with override files — see /reference/overrides/" |
| Pending verifications | "Source verification needed before generation can proceed — run /bitwize-music:verify-sources" |
Also show one random general tip (rotate through these):
- "Ask 'what should I do next?' for workflow guidance"
- "Use
/bitwize-music:resumeto quickly jump back into an album" - "The researcher skill coordinates 10 specialized sub-skills for deep research"
- "Check pronunciation before generating — Suno can't infer from context"
- "Use
/bitwize-music:clipboardto copy lyrics/prompts for Suno" - "With Suno's MCP server connected,
/bitwize-music:generatemakes the track from here and/bitwize-music:listenopens the takes for you" - "Master your audio with
/bitwize-music:mastering-engineerfor professional results"
Step 8: Ask
End with: "What would you like to work on?"
Report Format
SESSION START
=============
Setup: MCP ready, config loaded
Health: [venv ok, skills ok, no collisions | warnings listed]
Suno: [connected | not connected (optional)]
Overrides: [loaded from {path} | not found (optional)]
State: [loaded | rebuilt | error]
ALBUM IDEAS
Pending: X | In Progress: Y
IN-PROGRESS ALBUMS
[album-name] (genre) - Status [X/Y tracks]
[album-name] (genre) - Status [X/Y tracks]
PENDING VERIFICATIONS
[album-name]: track-01, track-05
LAST SESSION
Album: [name] | Phase: [phase]
Pending: [actions]
TIP: [contextual tip]
What would you like to work on?
Remember
- Don't skip steps — Each step matters for session integrity
- Rebuild state if needed — Stale state leads to wrong recommendations
- Be concise — This is a status report, not a conversation
- Warn about verifications — Unverified sources block generation
- One tip, not five — Pick the most relevant tip for the current state
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |