@apex-inc/mcp-server 0.7.0 → 0.9.0

package/skills/apex-spec/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: apex-spec
+description: The Apex Spec — one event vocabulary for a whole business — and the scan-first wiring method. Use whenever you are instrumenting a merchant's codebase with Apex tracking: audit the code for Spec opportunities FIRST, propose the plan, wire each event where the truth lives, then verify your own work.
+---
+
+# Apex Spec — scan-first instrumentation
+
+The Apex Spec is ONE vocabulary for the merchant's whole business.
+`order_placed` is `order_placed` whether it fires from the website,
+the mobile app, or the backend — a data source is WHERE an event
+fires, never a separate plan. Your job when wiring a codebase is to
+find where each business truth already lives and instrument it there.
+
+## The method (always in this order)
+
+1. **Scan before asking.** Never ask the merchant to enumerate their
+   events. Audit the codebase for Spec opportunities:
+   - auth / signup flows → `apex.identify(email, first_name, last_name)` + `user_signed_up`
+   - login flows → `identify` (cross-device stitching)
+   - checkout / payment success paths → `purchase` / `checkout_started` / `order_placed` (server)
+   - in-app purchase / StoreKit / Play Billing → `in_app_purchase`
+   - subscription create / renew / cancel webhooks → `subscription_event`
+   - lead/contact forms → `form_submit`
+   - cart mutations → `add_to_cart`, `remove_from_cart`
+   - search, share, content views → `search`, `share`, `content_view`
+   Fetch the authoritative schema with the `get_event_spec` tool (or
+   `GET /api/spec/events`) before inventing names.
+
+   Report your scan in THREE sections — this exact shape, every time:
+   - **Already wired** — events the repo already instruments. Brownfield
+     repos often have many. Check the SDK is actually configured with a
+     workspace key: wired events with no key never reach Apex, and
+     fixing the config may be the highest-value change in the plan.
+   - **Gaps to wire** — the work you propose, each with the file you'll
+     touch.
+   - **Won't wire + why** — opportunities you're deliberately skipping
+     (a server event with no backend; a form that already fires a
+     richer dedicated event and would double-count).
+
+2. **Propose the plan.** Call the `propose_wiring_plan` tool with the
+   already-wired events (mark them `wired: true`) AND the gaps (event
+   name, surface, where you found it). This populates pending lights on
+   the merchant's setup page — they watch your work land in real time;
+   already-wired events show as "wired — awaiting first event". If the
+   tool is missing (older MCP server), POST the same payload —
+   `{ "events": [{ "name", "surface", "note", "wired" }], "summary" }`
+   — to `POST /api/workspaces/<workspaceKey>/wiring-plan` with the
+   `x-api-key` header. Then ask the merchant to confirm or trim the
+   plan before editing.
+
+3. **Wire each event where the truth lives.** Checkout on the site,
+   IAP in the app, `order_placed` on the backend. Server truth beats
+   client truth when both exist (ad blockers can't touch it). Make the
+   smallest change that works; never commit; never enable test mode in
+   production paths.
+
+4. **Verify your own work.** Call `get_wiring_status` after wiring and
+   iterate until every event you proposed reports `detected`. The
+   merchant's page celebrates each first arrival — your verification
+   loop is their receipt.
+
+## Surfaces
+
+- `web` — apex.js snippet (`apex.track`, `apex.identify`); `page_view` is automatic.
+- `mobile` — Apex SDK (iOS/Android/React Native/Flutter/Capacitor); `app_open` + `screen_view` are automatic. Detect the platform from the repo — never ask.
+- `server` — `POST /api/v1/events` with the workspace's `apex_sk_` key; the ground-truth lane for money events.
+
+## Hard rules
+
+- Identifiers: send raw values only into `identify` / event payloads —
+  Apex hashes (SHA-256) before any third-party egress. Never log them.
+- Custom events are allowed (`apex.track` accepts any snake_case
+  name) but prefer canonical Spec names — they unlock journeys,
+  funnels, and metric chips automatically.
+- Revenue events MUST carry `value` + `currency`, and a stable
+  external id when one exists (order id, invoice id) — dedupe depends
+  on it.