session-start

name	session-start
description	Runs 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.
model	sonnet
effort	low
allowed-tools	["Read","Bash","Glob","Grep","WebSearch","WebFetch","bitwize-music-mcp"]

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" 2>&1 >/dev/null && echo "MCP ready" || echo "MCP missing"        # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/python.exe -c "import mcp" 2>&1 >/dev/null && echo "MCP ready" || echo "MCP missing" # Windows (Git Bash; cmd/PowerShell: %USERPROFILE%\.bitwize-music\venv\Scripts\python.exe)

• If MCP missing: Stop immediately and suggest: /bitwize-music:setup mcp
• 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.

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 data from state.json, report:

Album Ideas

From state.ideas.counts — show count by status (Pending, In Progress, etc.)

In-Progress Albums

Filter state.albums for status: "In Progress", "Research Complete", "Complete"

For each, show:

• Album name, genre, status
• Track progress (completed/total)

Pending Source Verifications

From state.albums — find tracks where sources_verified is "Pending"

If any found, warn: "These tracks have unverified sources — generation is blocked until verified."

Last Session Context

From state.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"

Also show one random general tip (rotate through these):

• "Ask 'what should I do next?' for workflow guidance"
• "Use /bitwize-music:resume to 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:clipboard to copy lyrics/prompts for Suno"
• "Master your audio with /bitwize-music:mastering-engineer for 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]
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

1. Don't skip steps — Each step matters for session integrity
2. Rebuild state if needed — Stale state leads to wrong recommendations
3. Be concise — This is a status report, not a conversation
4. Warn about verifications — Unverified sources block generation
5. One tip, not five — Pick the most relevant tip for the current state