diff --git a/README.md b/README.md index 282ec7c3..5e556297 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,15 @@ In Claude Code: That's it. The MCP server, analysis skills, and post-session hooks are registered automatically. -### 2. First-time setup +### 2. Reload plugins + +After installing, reload plugins so Claude Code picks up the new MCP server and skills: + +``` +/reload-plugins +``` + +### 3. First-time setup On your first Claude Code session after installation, the `bp setup` wizard runs automatically. It verifies your installation, optionally adds a command reference to your CLAUDE.md, and points you toward your first analysis. You can also invoke it manually anytime: @@ -45,7 +53,7 @@ On your first Claude Code session after installation, the `bp setup` wizard runs bp setup ``` -### 3. Run your analysis +### 4. Run your analysis In any Claude Code session, run: @@ -83,7 +91,7 @@ This checks all 8 components (build artifacts, native dependencies, MCP config, | Problem | Fix | |---------|-----| | `better-sqlite3` won't compile | Install build tools: `xcode-select --install` (macOS) or `sudo apt install build-essential python3` (Linux) | -| MCP server not starting | Restart Claude Code after plugin install | +| MCP server not starting | Run `/reload-plugins` in Claude Code, or restart Claude Code | | Rate limits during analysis | Reduce scope: select fewer projects in `bp setup`, or run analysis during off-peak hours | ### Uninstalling diff --git a/docs/agent/PLUGIN.md b/docs/agent/PLUGIN.md index 18c44b27..e2fec99e 100644 --- a/docs/agent/PLUGIN.md +++ b/docs/agent/PLUGIN.md @@ -57,7 +57,7 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook | `lib/native-deps.ts` | Shared `ensureNativeDeps({ pluginRoot?, fatal? })` — installs better-sqlite3 to pluginRoot/node_modules/ for natural Node resolution | | `hooks/session-start-handler.ts` | `SessionStart` hook, first-run detection + queued `bp analyze` context | | `hooks/hooks.json` | Hook registration (`SessionStart` + `SessionEnd`) | -| `skills/bp-setup/SKILL.md` | Guided onboarding wizard skill (7 integer steps, includes project selection) | +| `skills/bp-setup/SKILL.md` | Guided onboarding wizard skill (MCP Readiness Gate + 7 integer steps, includes project selection) | | `skills/bp-analyze/SKILL.md` | Full analysis pipeline orchestrator skill | | `.claude-plugin/plugin.json` | Plugin metadata + config schema | | `.mcp.json` | MCP server config (stdio transport) | diff --git a/docs/agent/TROUBLESHOOTING.md b/docs/agent/TROUBLESHOOTING.md index 07a4588f..e87692b8 100644 --- a/docs/agent/TROUBLESHOOTING.md +++ b/docs/agent/TROUBLESHOOTING.md @@ -4,6 +4,10 @@ Analysis runs locally via the Claude Code plugin (`packages/plugin/`). Finished results sync to the server via `POST /api/analysis/sync`. The server no longer runs its own analysis pipeline. +## Plugin Setup (bp-setup) + +The `bp-setup` wizard includes an MCP Readiness Gate that retries `get_user_prefs` up to 3 times (0s, 3s, 5s backoff) before proceeding. This handles the delay between plugin install/`/reload-plugins` and the MCP server becoming available. If all 3 attempts fail, the wizard exits with a reinstall suggestion. If the gate passes but `scan_sessions` fails in Step 2, setup continues (non-critical) — project selection in Step 3 will retry or offer defaults. + ## Key Files | File | Role | diff --git a/packages/plugin/skills/bp-setup/SKILL.md b/packages/plugin/skills/bp-setup/SKILL.md index 715db62d..65fcb8c1 100644 --- a/packages/plugin/skills/bp-setup/SKILL.md +++ b/packages/plugin/skills/bp-setup/SKILL.md @@ -10,16 +10,45 @@ model: opus You are the **BetterPrompt onboarding assistant**. You guide first-time users through a quick setup that verifies their installation, lets them choose which projects to analyze, optionally integrates a command reference into their project CLAUDE.md, and points them toward their first analysis. The entire process takes about 1 minute. +## MCP Readiness Gate + +The BetterPrompt MCP server may still be starting, especially after first install or `/reload-plugins`. Before proceeding, confirm that MCP tools are available. + +1. Attempt to call `get_user_prefs`. If it succeeds, proceed to the Pre-Check (reuse the result there). +2. If the tool call fails because the tool is **not found or not available** (not a tool execution error): + a. Print: `"[bp] MCP tools are still loading (this is normal on first run)..."` + b. Wait 3 seconds using Bash: `sleep 3` + c. Retry `get_user_prefs`. +3. If the second attempt also fails with tool-not-found: + a. Print: `"[bp] Still waiting for MCP server..."` + b. Wait 5 seconds using Bash: `sleep 5` + c. Retry `get_user_prefs` one final time. +4. If all 3 attempts fail: + - Print: + ``` + [bp] Could not reach BetterPrompt MCP tools after 3 attempts. + + This usually means the plugin was not installed correctly. + Try reinstalling: /plugin install betterprompt@betterprompt + + If the problem persists, check ~/.betterprompt/debug.log for details. + ``` + - Do NOT continue with the remaining wizard steps. Exit gracefully. +5. If the tool call succeeds at any attempt, print: `"[bp] MCP server ready."` and proceed. + +**Important**: If the tool **is found** but returns an error result (e.g., a JSON response with an `error` field), that is NOT a readiness issue -- that is a tool execution error. Do not retry in that case; proceed to the Pre-Check and let it handle the error normally. + ## Pre-Check Before starting the wizard: -1. Call `get_user_prefs` and check `prefs.welcomeCompleted`. -2. If `welcomeCompleted` is already set **and** the user did NOT pass `--force`: +1. Reuse the `get_user_prefs` result from the MCP Readiness Gate above. +2. Check `prefs.welcomeCompleted`. +3. If `welcomeCompleted` is already set **and** the user did NOT pass `--force`: - Tell the user setup was already completed on that date. - Ask: **"Re-run setup?"** / **"Skip"** - If they choose Skip, exit gracefully. -3. If `welcomeCompleted` is not set, or `--force` was passed, proceed to Step 1. +4. If `welcomeCompleted` is not set, or `--force` was passed, proceed to Step 1. ### Explicit Instruction Shortcut @@ -55,18 +84,20 @@ This setup takes about 1 minute. ### Step 2: Verify Environment -Call the `scan_sessions` MCP tool to verify the plugin is working (native deps + MCP connection in one shot). +Call the `scan_sessions` MCP tool to verify the plugin can read session data. - **On success**: Report what was found: - Number of sessions discovered - Date range of sessions - Sources detected (Claude Code, etc.) - List of projects with session counts -- **On failure**: Report the error clearly and suggest the user verify the plugin is installed correctly (`/plugin install betterprompt@betterprompt`). Do not attempt to register via `claude mcp add`. +- **On failure**: Since MCP connectivity was already confirmed by the Readiness Gate, a failure here means `scan_sessions` encountered an error reading session data (no sessions found, permission issue, etc.). Report the error but continue with setup -- Step 2 failure is non-critical. The user can still configure preferences and run analysis later. ### Step 3: Select Projects -Display the project list from Step 2 (name + session count) and let the user choose which projects to include in analysis. +If Step 2 succeeded, display the project list from Step 2 (name + session count) and let the user choose which projects to include in analysis. + +If Step 2 failed (no `scan_sessions` data available), call `scan_sessions` again here. If it still fails, tell the user that project discovery is unavailable and offer two options: **"Analyze all projects"** (sets `selectedProjects: []`) or **"Skip project selection"** (keeps existing selection or sets `selectedProjects: []`). Then proceed to Step 4. If the user's initial prompt already names the projects to include, do **not** call `AskUserQuestion` for this step. Match the requested names against `scan_sessions.allProjects[].name`, confirm the matched canonical names, and persist them directly. @@ -205,6 +236,7 @@ Use `AskUserQuestion` with these options: ## Progress Reporting Print a brief `[bp]` status line before each step: +0. `"[bp] Connecting to MCP server..."` (only shown if readiness gate needs to retry) 1. `"[bp] Step 1: Welcome"` 2. `"[bp] Step 2: Verifying environment..."` 3. `"[bp] Step 3: Project selection"` @@ -215,8 +247,8 @@ Print a brief `[bp]` status line before each step: ## Important Notes -- Never skip Step 2 (verification) -- it confirms the plugin works. +- Always run Step 2 (verification), but its failure is non-critical -- MCP connectivity is already confirmed by the Readiness Gate. - Always write `welcomeCompleted` at the end, even if the user skipped optional steps. - Always use `save_user_prefs` for setup preference updates when available instead of direct file writes. -- If any step fails, log the error but continue to the next step. Do not abort the entire wizard for a non-critical failure (Steps 4, 5 are non-critical). +- If any step fails, log the error but continue to the next step. Do not abort the entire wizard for a non-critical failure (Steps 2, 4, 5 are non-critical). - The CLAUDE.md block uses HTML comment markers (`` / ``) so it can be cleanly replaced or removed later.