/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 res