Setup

OPS ► SETUP WIZARD

Load ops-rules before acting. Public repo (no personal data). Outbound: one draft → one approval → one send. If AskUserQuestion / Workflow are missing, follow Rule 10 in ops-rules (Hermes: numbered options / two-turn Telegram card; delegate_task).

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 ops-wa-accounts --list 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 — leave empty ({"mcpServers":{}}). MCP servers start on demand in host config, not at plugin load. 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.

Arguments

The setup wizard accepts these flags (parsed from $ARGUMENTS):

• --fast — Zero-prompt fast path. When credentials are found by the Universal Credential Auto-Scan, auto-select "Configure all" / "Set up everything" everywhere without asking. Only fall back to interactive prompts when a section has no credentials at all.
• --profile <name> — Pre-select a curated integration subset. Valid names:
  • developer — GitHub, AWS, Sentry, Linear, Doppler, Daemon.
  • founder — All comms (Telegram, WhatsApp, Email, Slack, Calendar), plus Doppler, Linear, Daemon.
  • marketer — Klaviyo, Meta Ads, GA4, Search Console, Shopify, Email (sending), Doppler.
• --re-setup — Skip Step 1's "what do you want to configure" prompt and route directly to broken/unconfigured sections based on /ops:status. Equivalent to auto-detected incremental mode.

Precedence: --profile narrows the section set first, --fast then auto-confirms within those sections, --re-setup further filters to only broken/unconfigured ones.

Profile → sections mapping

Incremental re-setup

When Step 0b detects an existing $PREFS_PATH with ≥1 configured section AND no explicit arguments were passed, default Step 1's prompt to "Re-setup broken only" (instead of "Set up everything"). Skip every section where /ops:status reports green for that section's key integrations.

Progress panel

After every section completes (or is skipped), print a single line progress panel:

Progress: {configured}/{total} configured · {working} working · {pending} pending

Where:

• configured = sections where credentials are present in preferences.json.
• working = configured sections whose most recent /ops:status smoke test returned green.
• pending = sections the user selected but hasn't configured yet.
• total = total sections considered for this run (filtered by --profile if used).

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:

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.