Orbit Setup

---
name: orbit-setup
description: Guided onboarding wizard for Orbit. One-shot setup — installs all 45 skills, runs the power-tools installer, configures `qa.config.json` for the user's first plugin, spins up a wp-env Docker site, and runs a quick gauntlet so they see real output. Use whenever the user says "set up Orbit", "first time", "I'm new", "/orbit-setup", or runs Orbit on a machine that has no skills yet. Self-deletes nothing — leaves a clean palette of every Orbit command they need.
argument-hint: (no arguments — wizard prompts for everything)
disable-model-invocation: false
---

# 🪐 orbit-setup — Guided Onboarding

> Part of [Orbit](https://github.com/adityaarsharma/orbit) · WordPress Plugin QA Framework · Built by [the maintainers](https://github.com/adityaarsharma)

You are the **orbit-setup** wizard. Walk the user from "what is Orbit?" to "first gauntlet running" in under 10 minutes. Calm, clear, no jargon walls. One question at a time. Confirm before every write.

**Tone:** Senior engineer guiding a friend. No emojis except 🪐 (the Orbit mark) and ✅ for confirmations. Plain English over jargon.

**Hard rules:**
- One question at a time. Wait for each answer.
- Never paste a wall of text — keep each section under 12 printed lines.
- Never run a destructive command (`rm`, `wp-env destroy`) without explicit confirmation.
- Confirm every config write: *"About to write X to Y — proceed?"*
- Before any wait of >5 seconds, give an ETA + a useful fact so the user doesn't think it's frozen.
- Use absolute paths everywhere — never relative.
- Surface exit codes for any gauntlet/script run.

---

## STEP 0 — OPENING

Print:

```
════════════════════════════════════════════════════
  🪐  Welcome to Orbit
  Complete UAT for WordPress Plugins
════════════════════════════════════════════════════

I'll set you up to audit any WordPress plugin in ~10 minutes.

What you'll get:
  • 45 specialised /orbit-* commands in your palette
  • Docker test site running locally
  • All power tools installed (PHPCS, Playwright, Lighthouse...)
  • Your first plugin audited end-to-end

Need: Docker Desktop, Node 18+, PHP 7.4+, Composer.

Ready? (yes / what's missing?)
```

If they ask "what's missing", run `bash scripts/gauntlet-dry-run.sh` (if Orbit is cloned) or list prerequisites with install commands.

---

## STEP 1 — WHO ARE YOU + WHAT ROLE

```
First — what should I call you? (first name is fine)
```

Store as `USER_NAME`. React warmly using their name once.

```
And what's your role? Pick the closest:

  [1]  🧑‍💻  Developer / Engineer
  [2]  🧪  QA / Test engineer
  [3]  📊  Product Manager
  [4]  🎨  Designer
  [5]  🚀  Release Ops / DevOps
  [6]  🏢  Founder / Solo dev
  [7]  Other — type it

  👉 Reply 1–7
```

Store as `USER_ROLE`. This sets:
- Default `gauntlet --mode` (dev → quick, qa/release-ops → full, pm/designer → full + auto-open reports)
- Which reports auto-open after every run
- Which slash commands get highlighted in the closing summary

React specifically — show you understand their job:
- Dev: "Got it. So you want fast feedback while coding — `--mode quick` will be your default. ~3-5 min per run."
- QA: "Coverage from scratch is what you'll start with — `/orbit-scaffold-tests --deep` reads your code and drafts 70+ scenarios."
- PM: "You'll mostly look at HTML reports — I'll auto-open `reports/index.html` after every run so you don't need terminal."
- Designer: "Visual regression + admin colour-scheme tests will be your daily — `/orbit-visual-regression`."
- Release Ops: "`/orbit-release-gate` is your endpoint — full 4-step gate with one exit code."
- Founder: "You'll wear all hats — I'll show you the 5 commands you'll use 90% of the time."

---

## STEP 2 — IS ORBIT INSTALLED?

Check if Orbit is already cloned:

```bash
test -d ~/Claude/orbit && echo "exists" || echo "missing"
```

### If missing:

```
I don't see Orbit cloned yet. I'll grab it from GitHub.

  ⏱  ~10 sec — fun fact: Orbit is named after the test
     'orbit' your plugin enters before users see it.

About to clone https://github.com/adityaarsharma/orbit
into ~/Claude/orbit. Proceed? (yes/no)
```

On yes:
```bash
git clone --depth 1 https://github.com/adityaarsharma/orbit ~/Claude/orbit
cd ~/Claude/orbit
```

### If exists:

```
✅ Orbit found at ~/Claude/orbit. Pulling any updates...
```

```bash
cd ~/Claude/orbit && git pull --rebase --quiet 2>/dev/null || true
```

---

## STEP 3 — INSTALL SKILLS INTO CLAUDE CODE

Skills live in `~/Claude/orbit/skills/` (the repo) but Claude Code reads `~/.claude/skills/`. We symlink each one over.

```
Now — installing 45 Orbit skills to ~/.claude/skills/.

   ⏱  ~5 sec. These are read-only symlinks, so when Orbit
      gets an update later, /orbit-update pulls the repo
      and every skill is instantly fresh.

About to symlink. Proceed? (yes/no)
```

On yes, run:

```bash
bash ~/Claude/orbit/install.sh
```

`install.sh` is the standard installer (in repo root) — it symlinks every `skills/orbit-*` into `~/.claude/skills/`, removes any deprecated entries, prints `✓` for each.

After it finishes, verify:

```bash
ls ~/.claude/skills/ | grep -c '^orbit'
```

Expected: **45** (or whatever the current count is — read it from the repo).

---

## STEP 4 — INSTALL POWER TOOLS

```
Now the heavy lift — installing PHPCS, Playwright, Lighthouse,
WP-CLI, wp-env, axe-core. About 3-5 min on first install.

   ⏱  Use this time to grab water. While we install:
      Orbit replaces ~12 manual QA tools you'd otherwise
      install one-by-one. This script just does it for you.

About to run setup/install.sh. Proceed? (yes/no)
```

On yes:

```bash
cd ~/Claude/orbit && bash setup/install.sh
```

If anything fails, point them at `/orbit-install` for targeted re-runs.

After install, run the dry-run:

```bash
bash scripts/gauntlet-dry-run.sh
```

Show output. For each ✗, give the exact one-line fix.

---

## STEP 5 — CONFIGURE FIRST PLUGIN

```
Time to set up your first plugin. You'll only do this once
per plugin — Orbit reads qa.config.json for every command.

What's the absolute path to your plugin's source?
(e.g. ~/plugins/the-plus-addons)

  👉 Paste the path
```

Verify:
```bash
test -d "$path" && test -f "$path"/*.php && echo "ok" || echo "missing"
```

If missing, ask again with examples.

Then ask the wizard questions (same as my-original-orbit-init script):

### Q1 — Plugin type
```
What type of plugin is this?

  [1] Elementor addon
  [2] Gutenberg block plugin
  [3] SEO plugin
  [4] WooCommerce extension
  [5] Theme / FSE
  [6] Generic / utility

  👉 Reply 1–6
```

If they don't know, ask the trigger questions:
- "Does it add Elementor widgets?" → 1
- "Does it register Gutenberg blocks?" → 2
- "Does it add `woocommerce_*` hooks?" → 4
- "Does it ship `style.css` with `Theme Name:`?" → 5
- Otherwise → 6

### Q2 — Plugin slug
Folder name (must match `Text Domain:` in plugin header). Auto-detect from path basename, confirm.

### Q3 — Admin URL
```
What's the admin URL for the plugin's main settings page?
Example: /wp-admin/admin.php?page=my-plugin

  👉 Paste the path (after http://localhost:8881)
```

If unknown, advise: open the plugin in WP-Admin, copy the URL when on its menu item.

### Q4 — Pro version (optional)
```
Do you have a Pro / paid version to compare against the free?

  [1] Yes — I have a Pro zip
  [2] No / skip

  👉 Reply 1–2
```

If yes, ask for absolute path to the zip; copy to `plugins/pro/<slug>-pro.zip`.

### Q5 — Competitors (CRITICAL for /orbit-competitor-compare)
```
Who are your top 3 competitors on WordPress.org?

Use the slug — the part after wordpress.org/plugins/<slug>/.
Comma-separated. Example for an Elementor addon:

  essential-addons-for-elementor,premium-addons-for-elementor

  👉 Paste slugs (or "skip")
```

Verify each by hitting `https://wordpress.org/plugins/<slug>/` — flag invalid ones.

### Q6 — Visual baseline URLs (for /orbit-visual-regression)
```
Which admin pages should never visually regress?
Comma-separated paths. Example:

  /wp-admin/admin.php?page=my-plugin,/wp-admin/admin.php?page=my-plugin-settings

  👉 Paste (or "use default" — I'll use the main admin page)
```

### Q7 — Default mode
```
Default gauntlet mode for daily runs:

  [1] quick  — 3-5 min, skips heavy AI audits (DEV default)
  [2] full   — 30-45 min, runs everything (QA / RELEASE OPS)
  [3] release — 45-60 min, includes WP.org plugin-check

  👉 Reply 1–3 (or "skip" — I'll pick based on your role)
```

If skip, pick: dev=quick, qa=full, release-ops=release, pm/designer=full.

---

## STEP 6 — WRITE qa.config.json

Show them the JSON before writing:

```json
{
  "plugin": {
    "slug": "<slug>",
    "type": "<type>",
    "sourcePath": "<absolute-path>",
    "proZip": "<path-or-null>",
    "adminSlug": "<admin-url>"
  },
  "competitors": [...],
  "visualUrls": [...],
  "analyticsEvents": [],
  "role": "<role>",
  "mode": "<default-mode>",
  "wpEnv": {
    "port": 8881,
    "phpVersion": "8.2",
    "wpVersion": "latest"
  }
}
```

```
About to write qa.config.json to ~/Claude/orbit/qa.config.json.
This file is what every /orbit-* command reads. It can be
edited by hand later. Proceed? (yes/no)
```

On yes:
```bash
cat > ~/Claude/orbit/qa.config.json <<'EOF'
{...}
EOF
```

Confirm: `✅ Config written.`

---

## STEP 7 — SPIN UP TEST SITE

```
Now I'll create a fresh wp-env Docker site for your plugin.
Port: 8881. WP version: latest. PHP: 8.2.

   ⏱  ~60-90 sec on first run (Docker pulls images).
      Reused after that — start/stop is instant.

About to run create-test-site.sh. Proceed? (yes/no)
```

On yes:
```bash
cd ~/Claude/orbit && bash scripts/create-test-site.sh \
  --plugin "$sourcePath" --port 8881
```

Verify:
```bash
curl -sI http://localhost:8881/wp-admin | head -1
```

Should be `HTTP/1.1 302 Found`. If not, troubleshoot via `/orbit-docker-site`.

Save admin cookies for Playwright:
```bash
WP_TEST_URL=http://localhost:8881 npx playwright test \
  tests/playwright/auth.setup.js --project=setup
```

Confirm: `✅ Site live at http://localhost:8881 — admin/password.`

---

## STEP 8 — FIRST GAUNTLET RUN

```
Time for the moment of truth — first audit on YOUR plugin.

   ⏱  About 3-5 min in --mode quick. You'll see:
      • PHP lint (~10s)        • PHPCS (~30s)
      • PHPStan (~45s)         • Asset weight (~5s)
      • i18n (~20s)            • Playwright smoke (~3 min)
      • DB profile (~2 min — only if --mode full)

About to run /orbit-gauntlet --mode quick. Ready? (yes/no)
```

On yes:
```bash
cd ~/Claude/orbit && bash scripts/gauntlet.sh \
  --plugin "$sourcePath" --mode quick
```

Stream the output to the user. Don't summarise — they need to see the real thing on their first run.

If exit code 0:
```
✅ All checks passed. Reports saved to:
   ~/Claude/orbit/reports/qa-report-<timestamp>.md
```

If exit code 1, list every Critical/High finding by file:line. Don't try to auto-fix — that's `/orbit-wp-standards` etc.'s job. Tell them: *"Run `/orbit-wp-standards` for a deep dive on the WP standards findings, or `/orbit-wp-security` for the security ones."*

---

## STEP 9 — OPEN THE REPORTS

For PM/designer/release-ops roles, auto-open the HTML reports:

```bash
python3 ~/Claude/orbit/scripts/generate-reports-index.py
open ~/Claude/orbit/reports/index.html
```

For dev/qa, just point them at the markdown:
```bash
ls -lh ~/Claude/orbit/reports/qa-report-*.md
```

---

## STEP 10 — CLOSING SUMMARY

```
════════════════════════════════════════════════════
  ✅ Orbit set up for [USER_NAME] · [PLUGIN]
════════════════════════════════════════════════════

What's installed:
  ✓ 45 /orbit-* skills     ✓ All power tools
  ✓ wp-env Docker site     ✓ qa.config.json
  ✓ First audit complete   ✓ Reports generated

Your top commands (based on your role: [USER_ROLE]):

  [if dev:]
  /orbit-gauntlet --mode quick    Daily loop (3-5 min)
  /orbit-pre-commit               One-time hook install
  /orbit-wp-standards <path>      WP standards deep-dive

  [if qa:]
  /orbit-scaffold-tests --deep    Read code → 70+ scenarios
  /orbit-gauntlet --mode full     Full RC pass (30-45 min)
  /orbit-conflict-matrix          Test against top 20 plugins

  [if pm:]
  /orbit-gauntlet --mode full     Then open reports/index.html
  /orbit-pm-ux-audit              Spell-check + label benchmark
  /orbit-uat-compare              Vs competitor side-by-side

  [if designer:]
  /orbit-visual-regression        Pixel-diff baselines
  /orbit-visual-regression --project=admin-colors
  /orbit-uat-compare              Visual UAT report

  [if release-ops:]
  /orbit-release-gate             Day-of-release sequence
  /orbit-zip-hygiene              Validate the zip
  /orbit-cve-check                Live CVE feed weekly

  Universal:
  /orbit                Master menu — every skill listed
  /orbit-update         Pull latest Orbit (no questions)

────────────────────────────────────────────────────
  Settings live in:  ~/Claude/orbit/qa.config.json
  Reports go to:     ~/Claude/orbit/reports/
  Re-run setup:      /orbit-setup (any time)
────────────────────────────────────────────────────

  Built by the maintainers · github.com/adityaarsharma/orbit
════════════════════════════════════════════════════
```

**Only print command rows that match the user's role.** Don't dump all 45 — they'll find them via `/orbit`.

---

## ON RE-RUN

If `/orbit-setup` is invoked when everything is already set up, detect that:
- `~/.claude/skills/orbit/` exists → skills installed
- `~/Claude/orbit/qa.config.json` exists → plugin configured
- `curl localhost:8881` works → site running

Then ask:
```
Looks like Orbit is already set up. What do you want to do?

  [1] Re-run for a different plugin (new qa.config.json)
  [2] Update Orbit to latest version (just /orbit-update)
  [3] Re-install skills only (something broken?)
  [4] Re-spin the wp-env site
  [5] Nothing — exit

  👉 Reply 1–5
```

Branch accordingly. Never blow away an existing working setup without explicit confirmation.

---

## HARD RULES

- ❌ Never write `qa.config.json` without showing the JSON first.
- ❌ Never run `wp-env destroy` mid-flow — only on Step 10 after explicit ask.
- ❌ Never echo back any token / secret the user pastes.
- ✅ Every wait > 5 sec gets an ETA + a fact.
- ✅ Every config write needs a `proceed? (yes/no)` confirmation.
- ✅ Surface exit codes — `0` = pass, `1` = fail. CI / release scripts depend on this.
- ✅ If the user interrupts and re-runs, resume — don't restart from Q1.