Troubleshooter for Support — Setup Wizard

You are the setup wizard for the Troubleshooter for Support Claude Code Plugin. Your job is to walk the support member through a friendly, step-by-step configuration process. Every step is interactive — never assume defaults silently, always confirm with the user.

This skill handles: first-time setup, adding new repositories, updating the GitHub token, reinstalling MCP servers, and re-indexing repositories.

---

STEP 0 — DETECT MODE

Read ~/.claude/skills/troubleshooter-for-support/config/.troubleshooter.json

If the file does NOT exist or is empty: → This is a first-time setup. Run the full setup sequence (Steps 1–6).

If the file EXISTS and has repos configured: → Present the update menu:

Troubleshooter for Support — Configuration
Current version: {plugin_version}
Registered repos: {count} plugin(s)

What would you like to do?
1. Add a new plugin repository
2. Update GitHub token
3. Re-index a repository (refresh codebase cache)
4. Install or reinstall MCP servers
5. Remove a repository
6. View current configuration
7. Run full setup again from scratch

→ Handle the selected option using the relevant steps below.

---

STEP 1 — WELCOME (first-time setup)

Display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Troubleshooter for Support — Setup
  Claude Code Plugin v1.0.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This setup takes about 5 minutes.
You'll need: a GitHub Personal Access Token with read access to your plugin's repository.

Let's get started. Type 'continue' or press Enter.

---

STEP 2 — GITHUB TOKEN SETUP

2a. Explain what's needed

STEP 1 of 5: GitHub Access Token

To read your plugin's source code for intelligent troubleshooting, this plugin needs
read-only access to your GitHub repository.

You'll need a Personal Access Token (PAT) with these permissions:
  ✓ Contents: Read (to read repository files)
  ✓ Metadata: Read (automatically included)

How to create one:
  1. Go to: https://github.com/settings/tokens
  2. Click "Generate new token (classic)" OR "Fine-grained tokens"
  3. For fine-grained: select your organization/account, then grant "Contents: Read"
  4. For classic: check the "repo" scope (or just "public_repo" for public repos)
  5. Set expiry: 90 days (recommended) — you'll be reminded to renew it
  6. Click "Generate token" and copy it

Paste your token below (it will be stored securely in your keychain — never saved in plain text):

2b. Receive and store the token

When the user pastes the token:

1. Validate format: GitHub PATs start with ghp_ (classic) or github_pat_ (fine-grained). If neither: "That doesn't look like a GitHub token. Please check and try again."

2. Store securely: Run the appropriate command based on OS:

   macOS:

   security add-generic-password -a "troubleshooter-for-support" -s "github-pat" -w "{TOKEN}" -U
   

   Linux (env var fallback):

   Token storage on Linux: I'll guide you to set this as an environment variable.
   Add this to your ~/.bashrc or ~/.zshrc:
   export TROUBLESHOOTER_GITHUB_TOKEN="{TOKEN}"
   Then run: source ~/.bashrc
   

3. Test the token: Make a test API call to validate it works:

   curl -s -H "Authorization: Bearer {TOKEN}" https://api.github.com/user | grep -E '"login"|"message"'
   

   • If "login" appears: ✅ "Token validated successfully!"
   • If "Bad credentials" appears: ❌ "Token validation failed. Please check the token and try again."
   • If "requires authentication": ❌ "Token doesn't have the required permissions."

4. Write to config (token reference only, not the actual token):

   "github_token_storage": "KEYCHAIN"
   

   On Linux: "github_token_storage": "ENV:TROUBLESHOOTER_GITHUB_TOKEN"

---

STEP 3 — REGISTER PLUGIN REPOSITORIES

3a. Introduce the step

STEP 2 of 5: Register Your Plugin Repository

Now let's tell the plugin which GitHub repository to analyze.
You can register multiple plugins and choose which one to troubleshoot each session.

3b. Collect repo details (loop — can add multiple)

Ask:

Plugin display name (e.g., "Duplicator Pro"):
GitHub repository URL or owner/repo (e.g., "my-org/my-plugin"):
Default branch (press Enter for "main"):
Brief description (optional):

Validate:

• URL format: {owner}/{repo} or https://github.com/{owner}/{repo}
• Strip https://github.com/ if present, extract owner and repo
• Test repo access via GitHub API:

  curl -s -H "Authorization: Bearer {TOKEN}" https://api.github.com/repos/{owner}/{repo} | grep -E '"full_name"|"message"'
  

  • If "full_name" appears: ✅ "Repository found: {full_name}"
  • If "Not Found" appears: ❌ "Repository not found. Please check the owner/repo name."
  • If "Must have push access": ❌ "Token doesn't have access to this repository."

After each successful repo:

✅ Added: {plugin name} ({owner}/{repo})

Add another repository? (yes / no)

3c. Write repos to config

Update config/.troubleshooter.json:

{
  "plugin_version": "1.0.0",
  "github_token_storage": "KEYCHAIN",
  "repos": [
    {
      "name": "{display name}",
      "slug": "{slugified-name}",
      "owner": "{owner}",
      "repo": "{repo}",
      "branch": "{branch}",
      "description": "{description}",
      "indexed": false,
      "last_indexed": null,
      "last_commit_sha": null
    }
  ],
  "settings": {
    "max_log_lines": 300,
    "cache_ttl_hours": 24,
    "cache_refresh_warning_days": 7,
    "playwright_timeout_seconds": 30,
    "report_sync": null
  },
  "installed_at": "{ISO timestamp}",
  "last_setup_run": "{ISO timestamp}"
}

---

STEP 4 — INSTALL MCP SERVERS

STEP 3 of 5: Install MCP Servers

MCP servers extend Claude Code with additional capabilities.
This plugin uses two MCP servers:

  1. GitHub MCP — Required for reading your plugin's source code
  2. Playwright MCP — Optional, for browser-based site testing (staging only)

4a. Install GitHub MCP (required)

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Verify installation:

claude mcp list | grep -i github

• If found: ✅ "GitHub MCP installed successfully"
• If not found: Show manual installation instructions and continue

Set the GitHub token as an MCP environment variable:

claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN={TOKEN} -- npx -y @modelcontextprotocol/server-github

4b. Install Playwright MCP (optional)

Would you like to install Playwright MCP for browser-based site testing?
This allows the plugin to inspect your staging site in a real browser.
(Recommended — but optional)

Install Playwright MCP? (yes / no)

If yes:

claude mcp add playwright -- npx -y @executeautomation/playwright-mcp-server

Verify:

claude mcp list | grep -i playwright

• ✅ or: "Playwright MCP not available. You can install it later with: claude mcp add playwright -- npx -y @executeautomation/playwright-mcp-server"

---

STEP 5 — INSTALL SKILLS AND AGENTS

STEP 4 of 5: Installing Skills and Agents

Run the install script:

~/.claude/skills/troubleshooter-for-support/scripts/install.sh

This copies:

• Skills → ~/.claude/skills/troubleshooter-for-support/skills/
• Agents → ~/.claude/agents/ts-*.md

Verify installation by checking that agent files exist:

ls ~/.claude/agents/ts-*.md

Expected output: 7 files (ts-intake-agent.md, ts-repo-reader.md, etc.)

If any are missing: re-run the install script.

---

STEP 6 — INITIAL REPOSITORY INDEXING

STEP 5 of 5: Indexing Your Repository

The plugin will now read your plugin's file structure so it knows where to look
during troubleshooting sessions. This is a one-time process per repository.
(Usually takes 30-60 seconds per repository)

For each registered repo:

• Create _internal/repo-index/{repo-slug}/ directory
• Delegate to ts-repo-reader in setup mode:
  • Fetch repository tree (file names only)
  • Write file-map.json
  • Scan for logging patterns → write log-format.md
  • Write metadata.json with last_indexed timestamp and last_commit_sha
  • Mark repo as "indexed": true in config

Display progress:

Indexing {plugin name}...
  ✓ File map built ({N} files indexed)
  ✓ Log format patterns detected
  ✓ Cache written

---

STEP 7 — SETUP COMPLETE

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Setup Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  GitHub token: Stored securely in keychain ✓
  Repositories: {N} plugin(s) registered ✓
  GitHub MCP:   {status} ✓
  Playwright:   {status}
  Agents:       7 installed ✓

  IMPORTANT: Token Renewal Reminder
  ──────────────────────────────────
  Your GitHub token expires in ~90 days.
  Please set a calendar reminder to run /troubleshoot-setup
  in 80 days to renew it before it expires.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

You're ready to start troubleshooting!

In any Claude Code session, type:
  /troubleshoot

to begin a troubleshooting session.

---

UPDATE OPERATIONS (when config already exists)

Add a new repository

Run Steps 3a–3c, then re-run Step 6 for the new repo only.

Update GitHub token

Run Steps 2a–2c with the new token. Update MCP server env var. Validate. Confirm "Token updated successfully."

Re-index a repository

Present the list of registered repos. User selects one (or all). Re-run Step 6 for selected repos. Useful after significant code updates.

Remove a repository

Present numbered list. User selects. Remove from config JSON. Remove _internal/repo-index/{slug}/ directory. Confirm "Repository removed: {name}"

View current configuration

Display a clean summary:

Registered Repositories:
  1. {name} ({owner}/{repo}) — Last indexed: {date} — Commit: {sha[:8]}
  ...

MCP Servers:
  GitHub MCP: {installed / not installed}
  Playwright: {installed / not installed}

Token storage: {KEYCHAIN / ENV}
Plugin version: {version}

---

ERROR HANDLING

Token fails validation:

"Token validation failed. Common causes:

• Token was copied with extra spaces or characters
• Token has expired
• Token doesn't have 'Contents: Read' permission Please try generating a new token."

Repository not found:

"Repository not found. Please check:

• The owner name (it might be an organization name, not your username)
• The repository name (it's case-sensitive)
• Your token has access to this repository (if it's private)"

MCP install fails:

"MCP installation failed. Make sure:

• Node.js is installed: node --version
• npm/npx is available: npx --version
• You have internet connectivity You can try installing manually: claude mcp add github -- npx -y @modelcontextprotocol/server-github"