repo-doctor

name

repo-doctor

description

Set up, bootstrap, or health-check the ai-asset-registry repo on a machine. Use this whenever the user wants to get the repo working on a new or other computer, load/configure its MCP servers (slack, google-workspace, rhai-tracker), or verify/repair the environment — git submodule, skill symlinks, Jira credentials, the customer-tracker (c-track) clone. Also use it for anything blocking the Slack MCP specifically: "is the slack mcp installed correctly", "slack tools aren't loading", "did podman set up right", "install podman for slack", "my slack tokens expired / invalid_auth", or checking whether the podman engine (not just Podman Desktop) and its machine are ready. Trigger on phrases like "set up this repo", "bootstrap the repo", "load the repo on my other laptop", "check my environment", "is my setup correct", "my MCPs/symlinks/skills are broken", "run the doctor", or "did the .env load everything". Runs an idempotent bootstrap.sh: a read-only health check by default, or a setup mode that writes configs from rhoai-restricted/.env.

repo-doctor

Bootstraps and health-checks this repo on a machine. It wraps bootstrap.sh (in this skill's directory), which does the mechanical, deterministic work so it behaves identically every run. Your job is to run it in the right mode, interpret the output for the user, and handle the judgment calls the script deliberately leaves to a human.

The one thing to understand first

The script has two modes, and the distinction is a safety boundary — treat it as such:

• bash bootstrap.sh check — read-only. Verifies everything and reports pass/warn/fail. Writes nothing. This is the default and is always safe to run.
• bash bootstrap.sh setup — writes files. Initializes the submodule, repairs symlinks, appends a .env-sourcing block to ~/.bashrc (deliberately excluding LLM-provider creds — see below), clones the customer-tracker repo, creates or patches .mcp.json to register the tracker MCP, installs the tracker server's node deps, writes live Slack/Google secrets from rhoai-restricted/.env into the Claude config (~/.claude.json or $CLAUDE_CONFIG_DIR/.claude.json), and — for the Slack MCP's runtime — starts the podman machine and pre-pulls the slack-mcp image. Every file it edits is backed up to *.bak first, and every action is idempotent (safe to re-run). Two things it deliberately does not do: install the podman engine (needs admin/UAC it can't self-elevate to — it prints the winget command instead) and extract Slack tokens (needs an interactive browser login — it points you at the extractor).

Always run check first. Never run setup without explicit user confirmation, because it writes real credentials into config files. Show the user what check found, then ask before running setup.

Workflow

1. Run the check. From the repo root:

   bash .claude/skills/repo-doctor/bootstrap.sh check
   

   Relay the summary (passed / warnings / failed) and walk through anything that isn't green.

2. If there are failures the user wants fixed, confirm, then run setup:

   bash .claude/skills/repo-doctor/bootstrap.sh setup
   

   Before running it, confirm two things with the user (see Gotchas below): which Claude profile they're targeting, and that they're OK with secrets being written into that profile's config.

3. After a setup run, tell the user to restart. MCP servers and shell env vars are loaded at startup — the script prepares them but cannot hot-load them into the running session. They must restart Claude Code and open a new shell for Slack/Google MCP + Jira env to take effect. The script prints a "Restart required" banner when it changed something.

What the script checks / sets up

#	Area	check reports	setup does
1	rhoai-restricted/.env	present?	sources it for the run
2	Submodule vendor/rfe-creator	checked out?	git submodule update --init --recursive
3	Symlinks (.claude/skills/*, scripts)	resolve? core.symlinks?	set core.symlinks true, restore links
4	Shell env	JIRA_* set? .bashrc sources .env (LLM creds excluded)?	append/refresh .env-sourcing block in ~/.bashrc, excluding LLM creds
5	Customer tracker (rhai-tracker MCP)	c-track cloned? registered in .mcp.json? deps installed? server/.env?	clone CTRACK_REPO_URL, create/patch .mcp.json, npm install, scaffold server/.env
6	Claude MCP servers	slack + google-workspace configured?	write server defs + secrets into Claude config
7	Slack MCP runtime (podman)	tokens present? engine installed (vs Desktop-only)? machine running? image pulled?	podman machine start + pre-pull slack-mcp image (install + token extraction stay manual)
8	Connectivity	Jira auth, scripts run?	(check only)

Gotchas (learned the hard way — surface these to the user)

• Profile matters. Section 6 writes to whatever Claude config the current session uses: $CLAUDE_CONFIG_DIR/.claude.json if set, else ~/.claude.json. This user runs a work profile (CLAUDE_CONFIG_DIR=~/.claude, via a claude-work alias) that holds the real Slack/Google servers, and a separate claude-personal profile that does not. If check reports slack/google "not configured", first confirm which profile is active — it may simply be the wrong profile, not a missing setup. Run setup under the profile you actually want the MCP servers in.
• .env must be present. It's gitignored and lives in rhoai-restricted/. On a fresh clone it won't exist until the user transfers it from their secure channel (see docs/setup-guide.md). Without it, secret-dependent steps are skipped — that's expected, not a bug.
• Windows Python. The script auto-detects python/python3/py because Windows ships a broken python3 Store shim. No action needed; just don't be surprised if it uses python.
• The tracker MCP: on disk ≠ functional. Section 5 reports four separate states, and "c-track present" is only the first. For the rhai-tracker MCP to actually load, it also needs: (b) a rhai-tracker entry in the repo-root .mcp.json (gitignored/per-machine — setup creates this file if absent), (c) npm install in c-track/server/, and (d) a server/.env. The .env secrets it needs — GOOGLE_SPREADSHEET_ID, GOOGLE_CLIENT_ID/SECRET, and an AI_PROVIDER — are not in rhoai-restricted/.env; setup scaffolds the template from .env.example and the user must fill them (see the c-track README.md). Don't report the tracker "done" just because it cloned.
• c-track cloning needs Red Hat VPN + an SSH key on GitLab. The URL should be the SSH form ([e-mail]:...); HTTPS clones fail with a self-signed-cert error behind Red Hat's internal CA. If auth fails, the key isn't registered at gitlab.cee.redhat.com/-/user_settings/ssh_keys (or the private key has a passphrase and no agent is loaded). The default CTRACK_DIR is ../c-track (a sibling of this repo); override it in .env if the clone lives elsewhere.
• LLM-provider creds are excluded on purpose. The ~/.bashrc block sources .env but unsets CLAUDE_CODE_USE_VERTEX, ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION, GOOGLE_APPLICATION_CREDENTIALS, ANTHROPIC_API_KEY, and ANTHROPIC_AUTH_TOKEN. Anyone running this already has LLM access via Claude Code/Cursor; exporting these would hijack that auth. If check warns the block is "the old form that exports LLM creds", setup rewrites it. Don't re-add these — it's a deliberate choice, not an omission.
• Podman Desktop is NOT the podman engine. The slack MCP's command is podman run … slack-mcp, so it needs the podman CLI, not the GUI. Installing Podman Desktop (RedHat.Podman-Desktop) alone gives you no podman.exe — and section 6 will still cheerfully report "slack configured", because that only checks the config file, not whether the runtime exists. This is why section 7 was added: it checks the engine separately and calls out the Desktop-only trap. The engine is winget install --id RedHat.Podman -e, which needs an admin shell — the UAC prompt fails silently (winget exit 1602) when driven from Claude Code's non-elevated shell, so hand the user the command to run themselves rather than retrying it here. After install: podman machine start (a podman-machine-default WSL VM usually already exists), and the engine lands on the persisted PATH but not the running shell's — a Claude Code restart is what makes podman resolvable at MCP launch.
• Slack tokens are session tokens that expire. The xoxc/xoxd pair in .env (SLACK_XOXC_TOKEN / SLACK_XOXD_TOKEN) dies on Slack logout or session invalidation. When Slack tools start returning invalid_auth, they must be re-minted with slack-token-extractor (a Python/Playwright tool that opens a browser for interactive login — no script can automate it). Naming gotcha: the extractor writes them as SLACK_MCP_XOXC_TOKEN / SLACK_MCP_XOXD_TOKEN, but .env and the Claude config expect the SLACK_MCP_-less names — rename on paste. Full walkthrough in docs/slack-mcp-install-guide.md.
• Diagnosing "Slack still won't load." When config + engine both look green but Slack tools are absent, run the container by hand to see the real error — this separates a runtime problem from a token problem in one shot:

  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
    | SLACK_XOXC_TOKEN=… SLACK_XOXD_TOKEN=… MCP_TRANSPORT=stdio LOGS_CHANNEL_ID= \
      podman run -i --rm -e SLACK_XOXC_TOKEN -e SLACK_XOXD_TOKEN -e MCP_TRANSPORT -e LOGS_CHANNEL_ID quay.io/redhat-ai-tools/slack-mcp
  

  A jsonrpc result line = the plumbing works (so the issue is a restart or the wrong Claude profile). LOGS_CHANNEL_ID must be passed (empty is fine) — the container KeyErrors without it.
• Secrets never go to the terminal in full. The script writes them into config files, not stdout. Don't echo the .env contents into the chat.

Related

• docs/setup-guide.md — the human-readable companion (prose walkthrough).
• rhoai-restricted/.env — the single source of secrets the script reads.
• rfe-creator.setup skill — deeper repair of the submodule/skill symlinks if section 3 can't fix them.