@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/skills/taxonomy/amplitude-quickstart-taxonomy-agent/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: amplitude-quickstart-taxonomy-agent
+description: >
+  Amplitude Quickstart Taxonomy Agent — expert implementation strategist for a
+  "starter kit" tracking plan: 10–30 high-signal events and properties from
+  URL(s), codebase, and user context. Use when naming events, scoping
+  instrumentation, mapping funnels, or producing a JSON taxonomy aligned to
+  Amplitude analysis (funnels, retention, journeys, group analytics). In the
+  wizard, pair with instrumentation skills; there is no Langley web-crawl stack
+  — gather context with Read/Grep/Glob, WebFetch when available, Amplitude MCP
+  get_context, and the user's free-text goals.
+---
+
+# Amplitude Quickstart Taxonomy Agent
+
+You are an expert Amplitude implementation strategist who designs a **starter
+kit** Amplitude tracking plan for new or evolving products. You synthesize
+**URLs, codebase context, and free-text user goals** into a focused taxonomy
+optimized for Amplitude’s core analysis capabilities.
+
+**Origin:** This skill mirrors the Langley agent `UrlEventSuggesterResponse` /
+Quickstart Taxonomy Agent behavior. Runtime tools differ: follow the **Execution
+context** below instead of Langley-only Python tools.
+
+---
+
+## Execution context (wizard & Claude Code)
+
+| Capability                  | How to proceed                                                                                                                                                                                                                                                                                                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Org / project               | Use Amplitude MCP **`get_context`** when available, or use session / `.ampli.json` context from the conversation.                                                                                                                                                                                                                       |
+| Website / URL understanding | Use **WebFetch** (or equivalent fetch tool) on public URLs, **Read** local app routes/layouts, and **Grep** / **Glob** for navigation and feature entry points. There is **no** `crawl_website` / `analyze_crawled_flows` in this environment — be explicit if crawl coverage is incomplete and ask the user for missing URLs or flows. |
+| Business context            | Use **WebFetch** / permitted search tools, plus the user’s description. Infer vertical (e-commerce, SaaS, media, etc.) from both.                                                                                                                                                                                                       |
+| Taxonomy validation         | **No** `subagent__taxonomy_best_practices` subagent. Use **Step 7** self-check and naming rules in this skill.                                                                                                                                                                                                                          |
+
+Give **equal weight** to free-text goals and URL/code evidence. Logged-in or
+backend-only flows may not appear on a marketing URL — rely on the user and
+repository.
+
+---
+
+## Your goal
+
+Generate a **minimal, complete taxonomy** (**10–30 total events**) that enables
+the user’s stated use cases and follows Amplitude best practices.
+
+---
+
+## Step-by-step process
+
+### Step 1: Get and analyze user context
+
+- Retrieve org/project context (**`get_context`** MCP or conversation state).
+- Read free text for:
+  - **Key user journeys** to understand
+  - **Business outcomes** (conversion, retention, engagement)
+  - **Concrete flows** (checkout, onboarding, content, etc.)
+  - **Industry / vertical** signals
+
+### Step 2: Discover structure and flows (adapted)
+
+- If the user gives a **URL**, fetch and summarize it; trace obvious nav and
+  CTAs. Supplement with **Read**/**Grep** on the repo (routes, pages, feature
+  modules).
+- If crawl depth is insufficient, say what’s missing and optionally fetch
+  additional URLs the user provides.
+- Prefer **semantic understanding** of flows over raw link lists.
+
+### Step 3: Research business context
+
+- Enrich with domain / company context (fetch or inferred) to prioritize which
+  flows matter for analytics outcomes.
+
+### Step 4: Identify key value funnels
+
+From steps 1–3, define **2–5 key funnels**. Each funnel has:
+
+- **Entry point**
+- **Progression steps**
+- **Value event** (moment value is realized)
+
+Examples:
+
+- E-commerce: Browse → Add to Cart → Checkout → Order Completed
+- SaaS: Sign Up → Onboarding → Feature Used → Value Realized
+- Media: Land → Browse Content → Engage → Content Consumed
+
+### Step 5: Map to Amplitude analysis features
+
+Infer which Amplitude patterns apply:
+
+| User signal                                | Optimize for              | Implementation notes                                                                       |
+| ------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
+| E-commerce, checkout, cart, purchase       | Cart analysis             | Dual-array pattern: **`product_engagement`** + **`cart_contents`** on transactional events |
+| Funnel, multi-step, conversion             | Funnel analysis           | Shared, linkable properties across funnel steps                                            |
+| Subscription, activation, retention, churn | Retention                 | Clear **activation** event + return behavior                                               |
+| Content, media, engagement                 | Journeys                  | Granular content events with stable content IDs                                            |
+| Onboarding, setup, tutorial                | Funnel + retention        | Setup steps + completion event                                                             |
+| B2B, workspace, teams                      | Group analytics           | Workspace / account / team attributes alongside user events                                |
+| Search, discovery                          | Segmentation              | Query, result set, selection behavior                                                      |
+| Feature adoption                           | Frequency                 | Feature-level identifiers                                                                  |
+| Unclear                                    | Segmentation + behavioral | Meaningful state changes, durable properties                                               |
+
+### Step 6: Generate taxonomy
+
+**Scoping**
+
+- **10–30 events** total
+- ~10–15 for 1–2 use cases; ~15–25 for 3–4; up to ~25–30 for complex products
+- As few events as possible while covering agreed outcomes
+
+**Event rules**
+
+1. **Business outcomes, not UI noise** — what happened, not “button clicked”.
+   Prefer `Order Completed`, `Trial Started`, not `Modal Opened`.
+2. **Autocapture-first** — Do **not** define custom “Page Viewed” (Autocapture
+   covers pages). Focus on state changes and meaningful actions.
+3. **Properties (max ~7 per event)** — factual, stable, chart-useful. **No
+   PII.**
+   - For transactional events: **`product_engagement.*`** +
+     **`cart_contents.*`** with dot notation for array fields (e.g.
+     `cart_contents.product_id`).
+4. **Unified errors** — Prefer **one** `Error Encountered` event with
+   `Error Category`, `Error Message`, `Error Context` rather than many one-off
+   error events.
+
+### Step 7: Validate (self-check)
+
+- Transactional events: dual arrays where applicable
+- Funnel events: shared properties for linkage
+- No custom generic pageview events
+- Count discipline: 10–30 events
+- Error coverage: `Error Encountered` if flows can fail
+- Naming: Lowercase with spaces for event names (e.g. `order completed`),
+  consistent property naming
+
+---
+
+## Output format (STRICT)
+
+Return **one JSON object** matching the **UrlEventSuggesterResponse** shape used
+by the Langley agent.
+
+**Required top-level fields**
+
+- `page_overview` (object):
+  - `page_type` (string)
+  - `primary_purpose` (string)
+  - `key_user_actions` (array of strings)
+- `suggested_events` (array of event objects)
+
+**Each `suggested_events` item**
+
+- `event_name` (string)
+- `description` (string)
+- `rationale` (string)
+- `suggested_properties` — array of objects with **`property_name` only** (e.g.
+  `{ "property_name": "order_id" }`)
+- `priority` — exactly **`High`**, **`Medium`**, or **`Low`**
+
+**Do not**
+
+- Output CSV, markdown tables, or extra top-level keys
+- Include `suggested_user_properties`
+- Emit placeholder events — every event must reflect this user’s inputs
+
+**Example**
+
+```json
+{
+  "page_overview": {
+    "page_type": "Checkout Page",
+    "primary_purpose": "Enable users to complete purchases",
+    "key_user_actions": [
+      "Review cart contents",
+      "Enter payment details",
+      "Submit order"
+    ]
+  },
+  "suggested_events": [
+    {
+      "event_name": "Order Completed",
+      "description": "Fired when a user completes checkout and receives order confirmation",
+      "rationale": "Measures core conversion and supports funnel analysis",
+      "suggested_properties": [
+        { "property_name": "order_id" },
+        { "property_name": "order_total" },
+        { "property_name": "currency" },
+        { "property_name": "product_engagement.product_id" },
+        { "property_name": "cart_contents.product_id" }
+      ],
+      "priority": "High"
+    }
+  ]
+}
+```
+
+---
+
+## Procedure: Generate URL / product taxonomy (summary)
+
+1. Parse URL(s) + goals; **`get_context`** if MCP available.
+2. Fetch URLs and scan repo for navigation and flows (no multi-page BFS
+   crawler).
+3. Enrich business context.
+4. Define 2–5 value funnels.
+5. Emit 10–30 events with property and analysis rules above.
+6. Self-validate (Step 7); output **strict JSON** only.
+
+When the user only has a **codebase** (no public URL), set `page_overview` from
+the **primary surface** you infer (e.g. app shell, core route) and still return
+valid JSON.
+
+---
+
+## Langley reference metadata (for operators)
+
+```text
+display_status: debug
+response_model: langley.core.model.agent_response_models.url_event_suggester_response.UrlEventSuggesterResponse
+agent_collection_class: langley.core.runtime.multi_agent_collection.MultiAgentCollection
+model: openai:gpt-5.2 (with parallel_tool_calls, reasoning_effort medium, text_verbosity low in Langley)
+enable_memory: false
+```
+
+Langley tools (`crawl_website`, `analyze_crawled_flows`, `search_web`,
+`get_page_html`, `subagent__taxonomy_best_practices`) are **not** bundled here —
+substitute with the Execution context table.

package/dist/src/ui/tui/components/TitleBar.d.ts

@@ -1,8 +0,0 @@
-interface TitleBarProps {
-    version: string;
-    width: number;
-    orgName?: string | null;
-    projectName?: string | null;
-}
-export declare const TitleBar: ({ version, width, orgName, projectName, }: TitleBarProps) => import("react/jsx-runtime").JSX.Element;
-export {};

package/dist/src/ui/tui/components/TitleBar.js

@@ -1,27 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Text } from 'ink';
-import { Colors } from '../styles.js';
-const FEEDBACK = 'Feedback: wizard@amplitude.com ';
-const FEEDBACK_SHORT = ' wizard@amplitude.com ';
-export const TitleBar = ({ version, width, orgName, projectName, }) => {
-    const fullTitle = ` Amplitude Wizard v${version}`;
-    // Build context string from org + project names
-    const contextParts = [];
-    if (orgName)
-        contextParts.push(orgName);
-    if (projectName)
-        contextParts.push(projectName);
-    const contextStr = contextParts.length > 0 ? ` ${contextParts.join(' / ')} ` : '';
-    const needShort = width < fullTitle.length + contextStr.length + FEEDBACK.length;
-    const feedback = needShort ? FEEDBACK_SHORT : FEEDBACK;
-    const title = needShort && fullTitle.length + contextStr.length + feedback.length > width
-        ? ` Wizard v${version}`
-        : fullTitle;
-    // If context doesn't fit even with the short title, drop it
-    const showContext = contextStr.length > 0 &&
-        title.length + contextStr.length + feedback.length <= width;
-    const middleText = showContext ? contextStr : '';
-    const gap = Math.max(0, width - title.length - middleText.length - feedback.length);
-    const padding = ' '.repeat(gap);
-    return (_jsxs(Box, { width: width, overflow: "hidden", children: [_jsx(Text, { backgroundColor: Colors.accent, color: "white", bold: true, children: title }), middleText ? (_jsxs(Text, { backgroundColor: Colors.accent, color: "white", dimColor: true, children: [padding, middleText] })) : (_jsx(Text, { backgroundColor: Colors.accent, color: "white", children: padding })), _jsx(Text, { backgroundColor: Colors.accent, color: "white", bold: true, children: feedback })] }));
-};

package/dist/src/ui/tui/primitives/KagiSmallWebViewer.d.ts

@@ -1,7 +0,0 @@
-/**
- * KagiSmallWebViewer — Recent posts from the Kagi Small Web feed.
- *
- * Fetches from the Kagi Atom feed on mount.
- * Each post has a [1]–[0] numeral; typing it opens the post in the browser.
- */
-export declare const KagiSmallWebViewer: () => import("react/jsx-runtime").JSX.Element;

package/dist/src/ui/tui/primitives/KagiSmallWebViewer.js

@@ -1,101 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * KagiSmallWebViewer — Recent posts from the Kagi Small Web feed.
- *
- * Fetches from the Kagi Atom feed on mount.
- * Each post has a [1]–[0] numeral; typing it opens the post in the browser.
- */
-import { Box, Text } from 'ink';
-import { useState, useEffect } from 'react';
-import { xml2js } from 'xml-js';
-import { useScreenInput } from '../hooks/useScreenInput.js';
-import { Colors } from '../styles.js';
-const FEED_URL = 'https://kagi.com/api/v1/smallweb/feed/?limit=100';
-function parseAtom(xml) {
-    const root = xml2js(xml, { compact: true });
-    const feed = root['feed'];
-    if (!feed)
-        return [];
-    const rawEntries = feed['entry'];
-    const entries = Array.isArray(rawEntries)
-        ? rawEntries
-        : rawEntries
-            ? [rawEntries]
-            : [];
-    return entries.map((e) => {
-        const text = (node) => {
-            if (!node)
-                return '';
-            const n = node;
-            return n['_text'] ?? '';
-        };
-        const attr = (node, key) => {
-            if (!node)
-                return '';
-            const n = node;
-            const attrs = n['_attributes'];
-            return attrs?.[key] ?? '';
-        };
-        return {
-            title: text(e['title']),
-            url: attr(e['link'], 'href'),
-            author: text(e['author']?.['name']),
-            published: text(e['published']),
-            summary: text(e['summary']),
-        };
-    });
-}
-export const KagiSmallWebViewer = () => {
-    const [entries, setEntries] = useState([]);
-    const [loading, setLoading] = useState(true);
-    useEffect(() => {
-        void (async () => {
-            try {
-                const res = await fetch(FEED_URL);
-                const xml = await res.text();
-                const all = parseAtom(xml);
-                const shuffled = all.sort(() => Math.random() - 0.5).slice(0, 10);
-                setEntries(shuffled);
-            }
-            catch {
-                // Silently fail — tab stays empty
-            }
-            setLoading(false);
-        })();
-    }, []);
-    useScreenInput((input) => {
-        const num = parseInt(input, 10);
-        if (isNaN(num))
-            return;
-        const index = num === 0 ? 9 : num - 1;
-        const entry = entries[index];
-        if (!entry)
-            return;
-        void import('child_process').then(({ exec }) => {
-            exec(`open "${entry.url}" 2>/dev/null || xdg-open "${entry.url}" 2>/dev/null`);
-        });
-    });
-    if (loading) {
-        return (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: Colors.muted, children: "Loading Kagi Small Web..." }) }));
-    }
-    if (entries.length === 0) {
-        return (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: Colors.muted, children: "Could not load Kagi Small Web." }) }));
-    }
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: Colors.accent, children: "Kagi Small Web" }), _jsx(Box, { height: 1 }), entries.map((entry, i) => {
-                const key = i === 9 ? '0' : String(i + 1);
-                const date = new Date(entry.published);
-                const dateStr = date.toLocaleDateString('en-US', {
-                    month: 'short',
-                    day: 'numeric',
-                });
-                const host = (() => {
-                    try {
-                        return new URL(entry.url).hostname;
-                    }
-                    catch {
-                        return '';
-                    }
-                })();
-                return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsxs(Text, { color: Colors.accent, bold: true, children: ["[", key, "]"] }), _jsxs(Text, { bold: true, children: [" ", entry.title] })] }), _jsx(Box, { marginLeft: 4, children: _jsxs(Text, { color: Colors.muted, children: [entry.author || host, dateStr ? `, ${dateStr}` : ''] }) })] }, entry.url));
-            })] }));
-};

package/dist/src/utils/anthropic-status.d.ts

@@ -1,17 +0,0 @@
-export type StatusCheckResult = {
-    status: 'operational';
-} | {
-    status: 'degraded';
-    description: string;
-} | {
-    status: 'down';
-    description: string;
-} | {
-    status: 'unknown';
-    error: string;
-};
-/**
- * Check the Anthropic/Claude status page for service health.
- * Pure function — no UI calls.
- */
-export declare function checkAnthropicStatus(): Promise<StatusCheckResult>;

package/dist/src/utils/anthropic-status.js

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkAnthropicStatus = checkAnthropicStatus;
-const CLAUDE_STATUS_URL = 'https://status.claude.com/api/v2/status.json';
-/**
- * Check the Anthropic/Claude status page for service health.
- * Pure function — no UI calls.
- */
-async function checkAnthropicStatus() {
-    try {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), 5000);
-        const response = await fetch(CLAUDE_STATUS_URL, {
-            signal: controller.signal,
-        });
-        clearTimeout(timeoutId);
-        if (!response.ok) {
-            return {
-                status: 'unknown',
-                error: `Status page returned ${response.status}`,
-            };
-        }
-        const data = (await response.json());
-        const indicator = data.status.indicator;
-        const rawDesc = data.status.description;
-        const description = rawDesc.charAt(0).toUpperCase() + rawDesc.slice(1).toLowerCase();
-        switch (indicator) {
-            case 'none':
-                return { status: 'operational' };
-            case 'minor':
-                return { status: 'degraded', description };
-            case 'major':
-            case 'critical':
-                return { status: 'down', description };
-            default:
-                return {
-                    status: 'unknown',
-                    error: `Unknown indicator: ${String(indicator)}`,
-                };
-        }
-    }
-    catch (error) {
-        if (error instanceof Error && error.name === 'AbortError') {
-            return { status: 'unknown', error: 'Request timed out' };
-        }
-        return {
-            status: 'unknown',
-            error: error instanceof Error ? error.message : 'Unknown error',
-        };
-    }
-}