@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/app-store-optimization/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "skill_name": "app-store-optimization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have a new habit tracker launching on the App Store. Draft an ASO plan covering app name/subtitle keyword placement, keyword field priorities, the description hook, first three screenshots, promotional text, custom product pages for ads, in-app events, product page optimization tests, localization, and review prompt timing.",
+      "expected_output": "A complete App Store Optimization plan that separates search visibility from conversion, uses Apple-backed metadata surfaces correctly, and gives practical copy/testing guidance without drifting into App Review compliance or StoreKit implementation depth.",
+      "files": [],
+      "expectations": [
+        "Separates search visibility work from conversion work and prioritizes relevance over high-volume but weakly related keywords.",
+        "Uses app name, subtitle, keyword field, primary category, ratings/reviews, Custom Product Page assigned keywords, and in-app event cards as the main search/visibility surfaces rather than keyword-stuffing the description.",
+        "Recommends a conversion-focused description hook, benefit-oriented first screenshots, current promotional text, and per-locale metadata research.",
+        "Plans Custom Product Pages around audience or acquisition-channel differences and mentions the current 70-page capacity or assigned keyword search visibility.",
+        "Plans Product Page Optimization around one hypothesis at a time while acknowledging up to three treatments and selected localizations.",
+        "Places in-app review prompts only after positive user moments and notes that StoreKit may not show every requested prompt."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this ASO note for accuracy: 'Custom Product Pages are capped at 35 and only work through direct links. Product Page Optimization compares one treatment in the default locale only. Put repeated keywords at the start of the keyword field because position is a ranking factor. Add more keywords to the description. In-app event metadata is indexed like the keyword field. Japan and Korea also index English keyword fields. Ratings below 4.0 always tank conversion.' What should change?",
+      "expected_output": "A correction-focused review that replaces stale or unsupported App Store Optimization claims with current Apple-source-grounded guidance.",
+      "files": [],
+      "expectations": [
+        "Corrects Custom Product Pages to the current 70-page limit and mentions assigned-keyword search visibility in addition to direct URLs.",
+        "Corrects Product Page Optimization to up to three treatments, selectable localizations, and App Analytics confidence/reporting behavior instead of one default-locale treatment.",
+        "Rejects unsupported keyword-position ranking claims and recommends spending keyword-field characters on relevant, non-duplicated terms.",
+        "Keeps the description conversion-focused and avoids adding unnecessary keywords for search ranking.",
+        "Frames in-app event name and short description as visible event-card/search-result copy rather than a hidden keyword field.",
+        "Removes unsupported cross-locale English-indexing and fixed rating-threshold claims while preserving per-market research and ratings/reviews as search and conversion signals."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I need help before submission: my App Store listing has ASO keyword ideas, but also PrivacyInfo.xcprivacy entries, ATT wording, subscription paywall code, and a possible metadata rejection because screenshots show mockups. Which pieces should app-store-optimization own, and where should the rest go?",
+      "expected_output": "A boundary-aware answer that keeps app-store-optimization focused on discoverability and conversion strategy while routing compliance, privacy manifest, ATT, rejection, and StoreKit implementation details to sibling skills.",
+      "files": [],
+      "expectations": [
+        "Keeps app-store-optimization focused on keyword strategy, title/subtitle, description conversion copy, screenshots/captions, promotional text, Custom Product Pages, In-App Events, PPO tests, localization, and ratings strategy.",
+        "Routes App Store rejection risks, screenshot compliance, PrivacyInfo.xcprivacy, metadata policy, and ATT wording to app-store-review rather than solving them in depth.",
+        "Routes subscription paywall code, purchase handling, entitlement checks, and StoreKit product setup to storekit rather than expanding ASO into IAP implementation.",
+        "Still gives the ASO-safe next step: cross-check listing copy and screenshots for both conversion quality and compliance before submission.",
+        "Avoids recommending competitor names, unrelated keywords, or misleading screenshots as ASO tactics."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/app-store-optimization/references/keyword-research-methodology.md

@@ -0,0 +1,174 @@
+# Keyword Research Methodology
+
+Step-by-step process for identifying, scoring, and maintaining the keyword field for App Store search optimization.
+
+## Contents
+
+- [How Apple Indexes Metadata](#how-apple-indexes-metadata)
+- [Research Process](#research-process)
+- [Keyword Scoring Framework](#keyword-scoring-framework)
+- [Slot Allocation Strategy](#slot-allocation-strategy)
+- [Seasonal Keyword Rotation](#seasonal-keyword-rotation)
+- [Before and After Examples](#before-and-after-examples)
+
+## How Apple Indexes Metadata
+
+Apple documents the main App Store search signals as text relevance, including matches for the app title, subtitle, keywords, and primary category, plus user behavior such as downloads, ratings, and reviews. Use this table as a practical planning map, not as a precise ranking-weight model:
+
+| Field | Indexed for search? | Controllable per version? | Notes |
+|-------|---------------------|--------------------------|-------|
+| App name | Yes | Yes (with new version/status permitting) | 30 characters. Choose a distinctive name that hints at what the app does. |
+| Subtitle | Yes | Yes (with new version/status permitting) | 30 characters. Summarize value or typical use in a concise phrase. |
+| Keyword field | Yes | Yes (with new version/status permitting) | Up to 100 bytes. Use comma-separated terms with no spaces after commas. |
+| Primary category | Yes | Yes (with new version/status permitting) | Apple includes the primary category in search relevance. Do not repeat the category name in keywords. |
+| Custom Product Page assigned keywords | Yes, for approved visible pages | Yes (in App Store Connect) | Can route matching searches to a custom page instead of the default product page. |
+| In-app event name and short description | Visible in Search/event cards | Yes (per event) | Use query-relevant language for the event card, but avoid treating event copy as a hidden keyword field. |
+| Description | Conversion-focused | Yes (with new version/status permitting) | Apple's product page guidance says not to add unnecessary keywords to improve search results. |
+| Promotional text | No ranking effect | Yes (anytime) | Apple says promotional text does not affect search ranking. Use it for timely conversion messaging. |
+| Ratings and reviews | Behavior/search signal | Ongoing | Ratings and reviews influence search and conversion, but review text should be used as customer research rather than keyword stuffing. |
+
+### Indexing behavior details
+
+- Avoid plurals of words already included in singular form; Apple treats them as duplicates.
+- Do not repeat words from the app name, subtitle, or category in the keyword field.
+- Use spaces only inside real keyword phrases; do not add spaces after commas.
+- Include separate related terms when both are genuine search terms, such as "photo" and "photography".
+
+## Research Process
+
+### Step 1: Competitor audit
+
+Identify the top 5-10 apps ranking for the primary category terms. For each competitor, note:
+
+- Title and subtitle keywords
+- Visible positioning patterns (terms that appear frequently across top-ranking titles, subtitles, and screenshots)
+- Gaps -- relevant terms that competitors are not targeting
+
+Use App Store search autocomplete to discover what users actually type. Start typing a category term and note the suggested completions.
+
+### Step 2: Category analysis
+
+List every term a user might associate with the app's functionality:
+
+- Primary function terms (what the app does)
+- Use case terms (why a user would want it)
+- Audience terms (who the user is)
+- Adjacent terms (related activities or workflows)
+
+Filter this list against competitor findings. Terms that appear in many competitor titles are high-volume but high-competition. Terms that appear in autocomplete but not in competitor metadata represent opportunities.
+
+### Step 3: Search Ads discovery
+
+Run Apple Search Ads discovery campaigns with broad-match keywords matching the primary function. After 2-4 weeks of data:
+
+- Export the search term report to see actual queries that triggered impressions.
+- Sort by tap-through rate (TTR) to identify high-intent terms.
+- Sort by conversion rate to identify terms where users who find the app actually download it.
+- Add high-performing discovered terms to the keyword field.
+
+### Step 4: Iteration cycle
+
+With each app update:
+
+1. Review App Analytics for keyword impressions, tap-through rates, and conversion rates.
+2. Identify underperforming keywords (low impressions or low TTR) and replace them.
+3. Test new terms discovered through Search Ads or category changes.
+4. Check if competitor metadata has shifted -- new competitors or renamed apps can change the keyword landscape.
+
+## Keyword Scoring Framework
+
+Score each candidate keyword on three dimensions:
+
+| Dimension | Score range | How to assess |
+|-----------|-------------|---------------|
+| **Relevance** | 1-5 | Does the keyword describe what the app actually does? 5 = core function, 1 = tangentially related |
+| **Volume** | 1-5 | Is this term frequently searched? Use Search Ads impression data as a proxy. 5 = high impressions, 1 = minimal |
+| **Difficulty** | 1-5 | How many established apps target this term? 5 = low competition (good), 1 = dominated by major apps |
+
+**Decision rule:** Include a keyword only if Relevance >= 3. Among qualifying keywords, prioritize by (Relevance x 2) + Volume + Difficulty. This weights relevance heavily while still favoring discoverable, winnable terms.
+
+**Disqualify keywords that:**
+- Do not describe the app's actual functionality (Relevance < 3)
+- Are competitor brand names (violates App Store guidelines)
+- Duplicate a word already in the title or subtitle
+- Are the app's primary category name (Apple adds it automatically)
+
+## Slot Allocation Strategy
+
+The 100-character keyword field requires careful allocation. Here are allocation patterns for different app types:
+
+### Example: Fitness tracking app
+
+Title: `FitTrack -- Workout Log` (23 chars used)
+Subtitle: `Exercise & Activity Stats` (25 chars used)
+
+Keyword field strategy -- do not repeat: fittrack, workout, log, exercise, activity, stats
+
+```
+gym,training,health,run,step,calorie,weight,strength,cardio,hiit,yoga,plank,squat,routine,progress
+```
+
+(96 characters -- 4 remaining, all unique against title/subtitle)
+
+### Example: Photo editing app
+
+Title: `PixelPop -- Photo Editor` (24 chars used)
+Subtitle: `Filters & Retouch Tools` (23 chars used)
+
+Keyword field -- do not repeat: pixelpop, photo, editor, filter, retouch, tool
+
+```
+selfie,portrait,collage,crop,blur,preset,enhance,adjust,brightness,contrast,saturation,beauty,skin
+```
+
+(99 characters -- all unique against title/subtitle)
+
+### Allocation principles
+
+- Each comma costs 1 character. Fewer, longer keywords are not inherently better than more, shorter ones -- Apple matches individual words, not phrases.
+- If two terms are searched as a phrase (e.g., "meal prep"), use the phrase when it matches real query behavior; use separate terms when each word is independently valuable.
+- Reserve 5-10 characters for experimental keywords that rotate each release based on performance data.
+
+## Seasonal Keyword Rotation
+
+Some keywords have seasonal search volume spikes. Plan rotation around predictable events:
+
+| Season/Event | Example keywords to add | When to deploy |
+|-------------|------------------------|----------------|
+| New Year | resolution,goal,habit,new year | December release |
+| Back to school | student,school,study,planner | July/August release |
+| Holiday shopping | gift,holiday,deal,wish list | October/November release |
+| Summer fitness | outdoor,running,summer,beach | April/May release |
+| Tax season | tax,receipt,expense,deduction | January/February release |
+
+Rotate 2-3 keyword slots per seasonal cycle. Keep the core 70-80 characters stable and use the remaining 20-30 characters for seasonal experimentation.
+
+## Before and After Examples
+
+### Problem: Wasted characters
+
+**Before:**
+```
+fitness tracker, workout app, best exercise, health and wellness, gym
+```
+Issues: spaces after commas (-5 chars wasted), "fitness" and "tracker" may duplicate title, "best" and "app" have no search value, "and" is a stop word.
+
+**After:**
+```
+gym,health,run,step,calorie,weight,strength,cardio,hiit,yoga,plank,squat,routine,progress,streak
+```
+Fixes: no spaces, no duplicates of title/subtitle, no filler words, all terms are genuine search queries.
+
+### Problem: Duplicate keywords
+
+**Before** (title is "RunMate -- Running Tracker"):
+```
+running,tracker,run,jog,marathon,5k,pace,distance,route,gps,heart,rate,training,fitness,health
+```
+Issues: "running", "tracker", and "run" duplicate the title -- 17 characters wasted.
+
+**After:**
+```
+jog,marathon,5k,pace,distance,route,gps,heart,rate,training,fitness,health,stride,tempo,interval
+```
+Fixes: removed title duplicates, added 3 new high-value terms with the recovered space.

package/pipeline/skills/shared/external/app-store-optimization/references/product-page-variants.md

@@ -0,0 +1,191 @@
+# Product Page Variants
+
+Custom Product Pages, product page optimization (A/B testing), and in-app event configuration for App Store discoverability and conversion.
+
+## Contents
+
+- [Custom Product Pages](#custom-product-pages)
+- [Product Page Optimization Tests](#product-page-optimization-tests)
+- [In-App Event Configuration](#in-app-event-configuration)
+- [Screenshot Caption Copywriting](#screenshot-caption-copywriting)
+
+## Custom Product Pages
+
+### Setup in App Store Connect
+
+1. Navigate to **App Store Connect > App > Custom Product Pages**.
+2. Create a new Custom Product Page -- each page needs a reference name (internal only) and a locale.
+3. Customize screenshots, app preview videos, promotional text, and assigned keywords for the target audience.
+4. Submit the page for review -- Custom Product Pages go through App Review like regular submissions.
+5. Once approved, the page is visible through its unique URL and, if configured, through assigned App Store search keywords.
+
+### URL structure
+
+Custom Product Pages use the format:
+
+```
+https://apps.apple.com/app/id{APP_ID}?ppid={CUSTOM_PAGE_ID}
+```
+
+The `ppid` parameter directs users to the custom page instead of the default product page. Use these URLs in:
+
+- Apple Search Ads ad group URLs
+- Social media campaign links
+- Email marketing campaigns
+- Web landing pages
+- QR codes in physical marketing
+
+### Search visibility and deep links
+
+- You can create up to 70 Custom Product Pages per app.
+- Assign keywords from the latest approved app version to make an approved, visible custom page appear for matching App Store searches instead of the default page.
+- Use unique keyword sets per custom page so App Store search can choose the most relevant page.
+- Optional app deep links can send users on iOS 18 or iPadOS 18 or later to specific in-app content after they tap Open. Deep links must be approved with the custom page before they work for users.
+
+### Campaign-to-page mapping
+
+Plan Custom Product Pages around distinct acquisition channels:
+
+| Channel | Page name convention | Screenshot strategy |
+|---------|---------------------|---------------------|
+| Search Ads -- brand terms | `Search-Brand` | Highlight brand trust and breadth |
+| Search Ads -- feature terms | `Search-{Feature}` | Lead with the specific feature the user searched for |
+| Search Ads -- competitor terms | `Search-Competitor` | Emphasize differentiators vs. category norms |
+| Social -- Instagram/TikTok | `Social-Visual` | Visual-first screenshots matching social creative style |
+| Social -- Twitter/X | `Social-Utility` | Feature-focused, less visual polish |
+| Email -- existing users | `Email-Upgrade` | New feature highlights for re-engagement |
+| Web -- blog/PR | `Web-Editorial` | Award badges, press quotes, credibility signals |
+
+### Management
+
+- Audit Custom Product Pages quarterly. Remove pages for ended campaigns.
+- Track performance per page in App Analytics -- compare conversion rates against the default page.
+- App Analytics reports custom page metrics after the page receives at least five first-time downloads.
+- Custom Product Pages count toward the 70-page limit per app. Reserve capacity for seasonal or ad-hoc campaigns.
+
+## Product Page Optimization Tests
+
+### Test design patterns
+
+Each test compares the original product page against up to three treatments. For clearer results, design each test around one hypothesis even when you create multiple treatments.
+
+#### Icon test
+
+- **Hypothesis:** A revised icon with [specific change] will increase tap-through rate by improving shelf appeal.
+- **Treatment:** Alternate app icon that [describes the specific difference].
+- **Duration:** 7-14 days minimum.
+- **Success metric:** Conversion rate (impressions to first-time downloads).
+
+#### Screenshot order test
+
+- **Hypothesis:** Leading with [screen X] instead of [screen Y] will increase conversion by showing the primary value proposition sooner.
+- **Treatment:** Reorder the first 3 screenshots.
+- **Duration:** 7-14 days minimum.
+- **Success metric:** Conversion rate.
+
+#### Screenshot content test
+
+- **Hypothesis:** Benefit-oriented captions will outperform feature-descriptive captions.
+- **Treatment:** Replace captions on the first 3 screenshots with benefit-focused copy.
+- **Duration:** 7-14 days minimum.
+- **Success metric:** Conversion rate.
+
+### Running a test
+
+1. In App Store Connect, go to **Product Page Optimization**.
+2. Choose up to three treatments and the element to test (icon, screenshots, or preview video).
+3. Upload the treatment assets.
+4. Set the traffic proportion. App Store Connect splits that treatment traffic evenly across treatments.
+5. Select the localizations to include; all supported localizations are selected by default.
+6. Start the test and monitor App Analytics. A test runs for up to 90 days or until manually stopped.
+
+### Interpreting results
+
+- App Store Connect reports conversion rate for control vs. treatment with a confidence interval.
+- Results appear after at least five first-time downloads are associated with the test.
+- Do not apply a treatment until the result shows 90%+ confidence.
+- A 2-5% conversion lift is meaningful at scale -- do not dismiss small wins.
+- If App Store Connect marks a test as likely inconclusive, the current traffic and lift may not be enough to reach confidence within the 90-day window. Consider a stronger creative change or a higher-traffic period.
+- After applying a winner, wait at least one release cycle before starting the next test to establish a clean baseline.
+
+### Limitations
+
+- Only one test at a time per app.
+- Product Page Optimization tests are unavailable for Custom Product Pages, Apple Watch product pages, and iMessage product pages.
+- Low-traffic apps may need longer to reach 90% confidence, and some tests may remain inconclusive.
+- App icons used in treatments must be included in the app binary for the current App Store version. Applying a treatment applies screenshots and previews; make an icon the default in a future app version if that icon should persist broadly.
+
+## In-App Event Configuration
+
+### Event metadata template
+
+| Field | Limit | Guidelines |
+|-------|-------|-----------|
+| **Event name** | 30 chars | Keyword-rich, action-oriented. "Spring Fitness Challenge" not "Our Spring Event" |
+| **Short description** | 50 chars | One compelling sentence visible on the event card |
+| **Long description** | 120 chars | Expand on what the user will experience or win |
+| **Event card image** | 1920x1080 (16:9) | High-contrast, legible at small sizes, no text smaller than 24pt |
+| **Badge** | Preset options | Match badge type to event nature (see SKILL.md table) |
+| **Deep link** | URL | Optional. Links to the in-app event content |
+
+### Scheduling strategy
+
+Plan events to maintain continuous App Store visibility:
+
+```
+Week 1-2:  [Event A -- "Spring Challenge" (Challenge badge)]
+Week 3-4:  [Event B -- "New Workout Library" (Major Update badge)]
+Week 5-6:  [Event C -- "Summer Kickoff" (Special Event badge)]
+```
+
+Overlap the end of one event with the start of the next by 1-2 days. This prevents gaps where the app has no event card in search results.
+
+### Event timing rules
+
+- Events can be published up to 14 days before they start.
+- Events must run at least 15 minutes and can run for up to 31 days.
+- You can publish up to 10 In-App Events on the App Store at a time and keep up to 15 approved events per app in App Store Connect.
+- Events are visible in search results and on the product page during their active window.
+- Ended events are removed from the store automatically.
+- Schedule events around real moments (feature releases, content drops, seasonal relevance) -- manufactured events without real in-app content feel hollow and may be rejected by App Review.
+
+### Maximizing search impact
+
+- Use the event name and short description as visible search-result copy. Include terms that match the event's real content and user intent.
+- Choose a badge type that matches the actual event nature -- the badge appears prominently on the event card.
+- In-app events can appear on the Today tab, in search results, and on the app's product page. Apple's editorial team curates which events are featured.
+
+## Screenshot Caption Copywriting
+
+### Benefit-oriented vs. feature-descriptive
+
+| Feature-descriptive (weak) | Benefit-oriented (strong) |
+|---------------------------|--------------------------|
+| Calendar View | Never miss a deadline |
+| Dark Mode | Easy on your eyes, day or night |
+| Cloud Sync | Your data, everywhere |
+| Analytics Dashboard | See what is working |
+| Collaboration Tools | Build together in real time |
+| Offline Mode | Works without internet |
+| Custom Themes | Make it yours |
+| Push Notifications | Stay in the loop |
+
+### Caption structure
+
+The strongest captions follow one of three patterns:
+
+1. **Outcome-first:** State the result the user gets. "Track every mile" > "GPS Running Tracker".
+2. **Problem-solver:** Name the pain point and imply the solution. "No more forgotten passwords" > "Password Manager".
+3. **Social proof:** Imply scale or trust. "Join 10M users" > "Popular App".
+
+### Per-audience caption variants
+
+Different Custom Product Pages should use different captions for the same screenshots:
+
+| Screenshot | Search Ads -- fitness terms | Social -- visual audience | Email -- lapsed users |
+|-----------|---------------------------|--------------------------|----------------------|
+| Workout screen | "Hit your goals every week" | "Your workout, beautifully tracked" | "We added 50 new workouts" |
+| Progress chart | "See your streak grow" | "Watch your progress unfold" | "Your history is still here" |
+| Social feature | "Challenge your friends" | "Share your wins" | "Your friends are still active" |
+
+Tailor the emotional angle to the acquisition channel while keeping the screenshot content consistent.