setup

# OPS ► SETUP WIZARD You are running an **interactive configuration wizard** for the `claude-ops` plugin. The user wants you to walk them through every step needed to get the plugin working: installing CLIs, setting env vars, configuring channels, populating the project registry, and saving preferences. --- **RULE ZERO — EVERY BASH CALL USES `run_in_background: true`** This is non-negotiable. EVERY SINGLE Bash tool call in this entire setup wizard MUST set `run_in_background: true`. There are ZERO exceptions. This applies to: - Credential scans, CLI installs, OAuth flows, npm/brew installs - Daemon starts, daemon reloads, launchctl commands - Keychain writes, Doppler queries, Chrome history queries - Autolink scripts, sync/backfill, smoke tests - File writes, config writes, env appends - ANY command, no matter how fast you think it will be While background commands run, immediately continue to the next independent step or ask the user the next question. Handle results when the `<task-notification>` arrives. The setup wizard must NEVER show `(ctrl+b to run in background)` — if the user sees that prompt, you violated this rule. **RULE ONE — SILENT BASH CALLS** Every Bash tool call MUST include a short `description` parameter (5-10 words, e.g. "Install missing CLIs", "Scout keychain for Telegram creds", "Reload daemon"). This is what the user sees instead of the raw command. Keep setup clean and quiet — the user should see progress titles, not shell scripts. --- **Other hard rules:** - This is a _conversation_, not a script dump. Use `AskUserQuestion` for every decision — never ask in prose when a structured selector will do. - Confirm actions via `AskUserQuestion` where the user hasn't already opted in (e.g., "Configure all" covers everything — no per-action confirmation needed after that). - Skip sections the user declines. Don't nag. - **NEVER auto-skip a channel or integration.** Every channel/service the user selected must get an explicit `AskUserQuestion` with skip as one of the options. If a credential isn't found, present the [Paste manually] / [Deep hunt] / [Skip] options. If a smoke test fails, ask the user whether to retry, reconfigure, or skip. The ONLY acceptable way to skip is the user choosing a "Skip" option. Do not silently move past a service because scanning found nothing — that's when the user needs to be asked the most. - Show what's already configured first, so the user only fills gaps. - **Never show the user's real name or email in output unless the user explicitly provided it in THIS session.** Do not read from memory, existing configs, or environment variables to populate display names. - **Max 4 options per `AskUserQuestion` call.** The tool schema enforces `<=4` items in the `options` array. When a step lists >4 choices, filter already-configured items first, then batch the rest into multiple sequential calls of <=4 options each, grouped logically. Use `[More options...]` as the last option to bridge between batches. - Run ALL diagnostic/probe commands in parallel when possible. Use multiple Bash tool calls in a single message. Never run sequential probes when they're independent (e.g., `gog auth status` AND `wacli doctor` AND keychain scouts should all run simultaneously). - All writes go to one of these paths — and nothing else: - **`$PREFS_PATH`** — per-user preferences + secrets. Resolves to `${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json`. Lives in Claude Code's plugin data dir so it survives plugin reinstalls and version bumps. Never committed to git. - **`${CLAUDE_PLUGIN_ROOT}/scripts/registry.json`** — per-user project registry (gitignored in the source repo). `mkdir -p` its parent if missing. - **`${CLAUDE_PLUGIN_ROOT}/.mcp.json`** — only to add `${user_config.*}` placeholders, never hardcoded tokens. - The user's shell profile (`~/.zshrc` etc.) — append-only, never rewrite. - At the top of every wizard step, make sure `$PREFS_PATH`'s parent directory exists: `mkdir -p "$(dirname "$PREFS_PATH")"`. Claude Code creates `~/.claude/plugins/data/ops-ops-marketplace/` on plugin install but don't assume. --- ## Agent Teams support If `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set, use **Agent Teams** when multiple "Deep hunt" credential agents are needed simultaneously. This enables: - Credential scouts run in parallel across Doppler, keychains, browser profiles, and password managers - Agents share findings (e.g., Doppler agent finds a partial config → keychain agent knows to skip that service) - You can steer mid-hunt: "found the Telegram token, stop hunting for that one" **Team setup** (only when flag is enabled, multiple deep hunts triggered): ``` TeamCreate("setup-hunters") Agent(team_name="setup-hunters", name="hunt-telegram", model="haiku", ...) Agent(team_name="setup-hunters", name="hunt-sentry", model="haiku", ...) Agent(team_name="setup-hunters", name="hunt-shopify", model="haiku", ...) ``` Each agent reports back its findings. Merge results and present to the user for confirmation. If the flag is NOT set, use independent fire-and-forget subagents with `run_in_background: true`. --- ## Setup agent delegation pattern When the user asks a complex integration-specific question during setup (e.g., "how does /ops:ecom handle multi-store setups?"), the setup agent can load the related skill's SKILL.md for deeper context: ```bash cat "${CLAUDE_PLUGIN_ROOT}/skills/ops-ecom/SKILL.md" ``` Each sub-step below includes a `> **Deep-dive:**` pointer to the related skill file. Follow these pointers instead of duplicating operational details in this wizard. --- ## Step 0 — Preflight (runs in background while you read) ```! ${CLAUDE_PLUGIN_ROOT}/bin/ops-setup-preflight &>/dev/null & ``` **Preflight data**: All probe results are cached at `/tmp/ops-preflight/`. Before running ANY diagnostic command, check if the result already exists there: - CLI status: `cat /tmp/ops-preflight/clis.txt` - Slack: `cat /tmp/ops-preflight/slack.json` - Telegram: `cat /tmp/ops-preflight/telegram.txt` - gog/Gmail: `cat /tmp/ops-preflight/gog-gmail.json` - gog/Calendar: `cat /tmp/ops-preflight/gog-cal.json` - WhatsApp: `cat /tmp/ops-preflight/wacli-doctor.json` and `wacli-chats.json` - MCP servers: `cat /tmp/ops-preflight/mcp-servers.txt` - GitHub: `cat /tmp/ops-preflight/gh-auth.txt` - AWS: `cat /tmp/ops-preflight/aws-identity.json` - Projects: `cat /tmp/ops-preflight/projects.txt` - Existing registry: `cat /tmp/ops-preflight/existing-registry.json` - Existing prefs: `cat /tmp/ops-preflight/existing-prefs.json` - Doppler: `cat /tmp/ops-preflight/doppler.json` Wait for `/tmp/ops-preflight/.complete` to exist before reading (it should be ready within 2-3 seconds). NEVER re-run a probe that already has cached results — read the cache file instead. --- ## Step 0b — Detect current state Run the detector and parse its JSON output (or read from preflight cache if available): ```! ${CLAUDE_PLUGIN_ROOT}/bin/ops-setup-detect 2>/dev/null ``` If `CLAUDE_PLUGIN_ROOT` is unset, fall back to the latest installed cache dir at `~/.claude/plugins/cache/ops-marketplace/ops/<latest-version>/`. Store the resolved path as `PLUGIN_ROOT` for the rest of the session. Also resolve `PREFS_PATH` once and reuse it everywhere: ```bash PREFS_PATH="${CLAUDE_PLUGIN_DATA_DIR:-$HOME/.claude/plugins/data/ops-ops-marketplace}/preferences.json" mkdir -p "$(dirname "$PREFS_PATH")" ``` Print a compact status header to the user, one line per category: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OPS ► SETUP WIZARD ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Shell: zsh → ~/.zshrc Core CLIs: ✓ jq ✓ git ✓ gh ✓ aws ✓ node Channels: ✓ wacli ✓ gog ○ telegram (no token) Secrets: ✓ doppler (project: my-app, config: dev) MCPs: ✓ linear ✓ sentry ○ slack ○ vercel Registry: 19 projects Preferences: not set ────────────────────────────────────────────────────── ``` Use `✓` for present/set, `○` for missing/unset, `✗` for broken. --- ## Step 1 — Ask which sections to configure First, offer a quick "set up everything" option: ``` How would you like to run setup? [Set up everything — install CLIs, configure all channels, MCPs, registry, daemon, preferences (Recommended)] [Pick sections — choose which parts to configure] [Re-run a specific section — I know what I need] ``` If the user selects "Set up everything", select ALL sections across all batches and run them in order (Step 2 → 2b → 2c → 3 → 4 → 5 → 5b → 6 → 7), skipping any already fully configured. Within each step, use the "Configure all" fast-path where available. If the user selects "Re-run a specific section", show a single `AskUserQuestion` listing the section names (cli, daemon, channels, mcp, registry, prefs, env, ecom, mktg, voice, revenue) and jump directly to that step. If the user selects "Pick sections", proceed with the batched selection below. Use `AskUserQuestion` with `multiSelect: true`. Offer **only sections that need attention** (skip ones already green). Because AskUserQuestion allows max 4 options, batch into logical groups: **Batch 1 — Core setup (run early so the daemon can pre-warm caches while you finish):** | Option | Header | Description | | ------------------ | -------- | ----------------------------------------------------------------------------- | | Install CLIs | cli | Install missing command-line tools via Homebrew | | Background daemon | daemon | Install ops-daemon early — pre-warms briefing cache while remaining setup runs | | Configure MCPs | mcp | Enable Linear, Sentry, Vercel, Gmail MCP servers | | Build registry | registry | Register projects Claude should manage | **Batch 2 — Channels & plugins:** | Option | Header | Description | | ------------------ | -------- | ------------------------------------------------------------- | | Configure channels | channels | Set tokens for Telegram, WhatsApp, Email, Slack | | Companion plugins | plugins | Install GSD for project roadmap tracking | | Save preferences | prefs | Owner name, timezone, default priorities | | Shell env | env | Export `CLAUDE_PLUGIN_ROOT` in shell profile | **Batch 3 — Extras (only show if not already configured):** | Option | Header | Description | | ------------------- | -------- | ------------------------------------------------------------- | | Configure ecommerce | ecom | Set Shopify store URL + admin token, ShipBob | | Configure marketing | mktg | Set Klaviyo, Meta Ads, GA4, Search Console keys | | Configure voice | voice | Set Bland AI, ElevenLabs, Groq API keys | | Configure revenue | revenue | Set Stripe + RevenueCat keys for live MRR tracking | Present each batch as a separate `AskUserQuestion` call. Skip batches where all items are already green. Collect all selections across batches and run each selected section in order. --- ## Step 2 — Install CLIs (if selected) If multiple CLIs are missing, offer a bulk install first: ``` Missing CLIs detected: jq, gh, wacli. What would you like to do? [Install all missing CLIs (Recommended)] [Pick which to install] [Skip CLI installation] ``` If the user selects "Install all", install every missing tool in sequence without further prompts. If "Pick which to install", ask per tool: ``` Install jq? [Yes, install now] [Skip] Install gh? [Yes, install now] [Skip] Install wacli? [Yes, install now] [Skip — manual install required] ``` For each `Yes`, run: ```bash ${PLUGIN_ROOT}/bin/ops-setup-install <tool> ``` Report success/failure. If Homebrew is missing on macOS, stop and tell the user to install it from https://brew.sh first — do not attempt to install brew automatically. After installation, re-run `ops-setup-detect` to refresh status before continuing. --- ## Step 2b — Companion plugins (if selected) ### GSD (Get Shit Done) GSD is a third-party Claude Code plugin that adds project roadmap tracking. When installed, claude-ops dashboards (`/ops:go`, `/ops:projects`, `/ops:next`, `/ops:yolo`) automatically show active phases, progress, and next actions per project. Without it, those sections are simply omitted. Check if GSD is already installed: ```bash find ~/.claude -name "gsd-progress" -path "*/skills/*" 2>/dev/null | head -1 | grep -q . && echo "installed" || echo "not_installed" ``` If not installed, ask via `AskUserQuestion`: ``` GSD adds project roadmap tracking to your ops dashboards. /ops:go shows active phases and progress per project /ops:projects shows GSD state alongside CI/PR status /ops:next factors in GSD work priority [Install GSD (latest)] [Skip — I don't need roadmap tracking] ``` On install, run the commands directly — do NOT tell the user to run them manually: ```bash # Install GSD in one shot — no user intervention needed claude plugin marketplace add gsd-build/get-shit-done 2>/dev/null && \ claude plugin install gsd@gsd-build-get-shit-done 2>/dev/null ``` If `claude` CLI is not available in the path, fall back to the plugin cache mechanism: ```bash # Direct marketplace clone fallback GSD_MARKETPLACE_DIR="$HOME/.claude/plugins/marketplaces/gsd-build-get-shit-done" if [ ! -d "$GSD_MARKETPLACE_DIR" ]; then git clone https://github.com/gsd-build/get-shit-done.git "$GSD_MARKETPLACE_DIR" 2>/dev/null fi ``` Report success/failure. Record `plugins.gsd = "installed"` in `$PREFS_PATH`. If they skip: ``` Skipped GSD. Install later with: /plugin marketplace add gsd-build/get-shit-done ``` --- ## Step 2c — Background Daemon (early install, pre-warm caches) **Why install the daemon this early?** Running the daemon in parallel with the rest of setup lets it start pre-warming the briefing cache (`ops-gather` results for infra/git/PRs/CI), so by the time the user reaches Step 7 and runs `/ops:go`, the briefing is already cached and loads in under 3 seconds instead of 10. Channel-dependent services (wacli-sync, message-listener, inbox-digest, store-health) are added later in Step 5b once their channels are configured. ### Platform support The background daemon ships with a `launchd` integration (macOS only). Detect the platform before attempting install: ```bash case "$(uname -s)" in Darwin) OS=macos ;; Linux) grep -qi microsoft /proc/version 2>/dev/null && OS=wsl || OS=linux ;;