---
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:

```bash
~/.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.

## 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