interface:
  display_name: "Appllama research"
  short_description: "Study screens, flows and paywalls from top-grossing iOS apps, then build from what wins."

dependencies:
  tools:
    - type: "mcp"
      value: "appllama"
      description: "Appllama, the design library of top-grossing mobile apps"
      transport: "streamable_http"
      url: "https://mcp.appllama.io/mcp"

# Playbook: build an app from scratch

The user says "build me a habit tracker" (or any category). This is the full
loop. Do not stop early: the goal is a finished app where every screen is
verified better-than-reference in the simulator — not a scaffold.

## Phase 1 — Find the winners

1. Translate the user's need and priorities into 1–3 `search_apps` queries
   ("habit tracker", "habit tracker with streaks and social accountability").
   Add filters that encode the user's ambitions — e.g. `revenue_min` to bias
   toward proven money-makers, `launched_after` for modern design language.
2. From the results, shortlist the **top 5** by a blend of revenue,
   rating, downloads, and fit to the user's brief — not revenue alone.
   The flow lists in the results tell you a lot before you even open an
   app: one with `Paywall: 9` screens has a monetization story worth
   studying; one with `Onboarding: 25` is quiz-onboarding heavy.
3. `get_app` each shortlisted app. Record metrics + flows in
   `research/<category>/apps.md`.

## Phase 2 — Study every screen of the top 5

For each shortlisted app, walk `list_app_screens` page by page — ALL of it,
in journey order, and look at every image. Design language lives in the
pixels, not the metadata. As you go, build the app's `screens.md`: screen
id, name, flow, notable elements, palette — and download the screens so you
can read the journey side by side.

You are extracting the **category's design language**, so read across apps,
not just within one:

- What does the first-open moment look like in this category?
- How long is onboarding, and what does each step *earn* (permission,
  personalization data, commitment)?
- Where does the paywall sit, and what's on it (trial framing, price
  anchoring, feature grid, social proof)?
- What's the home-screen information hierarchy? What's one tap away?
- What do empty states, streaks/progress, and notifications look like?

Write the synthesis into `patterns.md`: the psychology of the category —
what every winner does (table stakes), what only the best do (edge), and
what all of them do badly (your opening).

## Phase 3 — Frame-by-frame on the top 3

Pick the 3 strongest apps and re-walk their decisive flows screen by screen
(`list_app_screens` with `flow=` filters; `get_screen` on pivotal screens to
see similar-screen alternatives across the library). For each screen answer:
what is its ONE job, what makes it work, what would you change. This is
where you stop being a catalog and start being a design director.

## Phase 4 — Design the feature set

From `patterns.md`, write the app's spec: the best features across all
studied apps, minus the bloat, plus the opening you found. Screen list with
flows, in journey order — and the **navigation map**: for every screen, what
it *is* (push, modal with its own stack, form sheet, full-screen modal,
overlay, tab root) and what back does from it, including the one-way doors
(sign-in, onboarding done, purchase, finished session) where back must not
re-enter the old state. The grammar comes from appllama-app-design-skill's
Navigation laws; the evidence comes from the flows you walked —
note whether each winner presents its composer as a modal, its filters as a
sheet, its detail as a push, and copy that consistency. Get user sign-off on
the spec if they're present; otherwise state your choices and proceed.

## Phase 5 — Build screen by screen

For EVERY screen, in journey order:

1. Re-open your references for that screen type (your local board first;
   `search_screens` for gaps — both modes, they surface different screens).
2. Build it following **appllama-app-design-skill** end to end (HIG fidelity,
   semantic colors, native controls, motion laws, state architecture).
3. Generate image assets with the best image model available (imagegen /
   Higgsfield MCP or CLI / whatever is present) at the highest quality — one
   style system for the whole app, per appllama-app-design-skill's
   references/image-assets.md.
4. **Simulator loop until flawless**: run on the iOS Simulator (or Android
   emulator), screenshot, actually look, exercise the motion frame by frame,
   check the Dynamic Island / safe areas / dark mode / Dynamic Type, fix,
   repeat. The checklist lives in appllama-app-design-skill's
   references/simulator-loop.md. A screen isn't done because it compiles —
   it's done when you can't find a flaw and it stands next to the top-3
   references without embarrassment.
5. State management stays boring and strong (server state / client state /
   ephemeral separation per the design skill). Motion is tracked and
   verified, not assumed.

## Phase 6 — The bar

Walk the whole app in the simulator as a new user, three times: happy path,
skeptic path (skip everything skippable), abuse path (bad input, offline,
interrupt mid-flow, and every back path — chevron, edge swipe, Android
hardware back, active-tab re-tap — especially right after sign-in,
onboarding, a purchase and a finished session, where back must fail to
re-enter the old state). Compare each flow against the best reference you
studied. If any screen of yours is worse than the best equivalent screen in
your research, it goes back into the loop. **You cannot declare the build
finished until every screen holds that comparison.**

# Playbook: make an existing screen better

The user has a screen (code, screenshot, or a live app) and wants it better.
"Better" means: measurably closer to the best equivalent screens shipped by
top-grossing apps — in hierarchy, motion, and feel — verified in the
simulator, not eyeballed in code.

## 1. Diagnose before you search

Run the screen in the simulator and study it against appllama-app-design-skill's
definition-of-done checklist. Name the top 3 deficits precisely ("no visual
hierarchy — three same-weight text rows", "dead motion — modal pops with no
transition", "non-native segmented control"). The research pass is aimed at
these deficits, not at "inspiration".

## 2. The 30 + 30 reference board

Two searches, three pages each (10 per page) — and keep paging past three
if the results are still strong:

- `search_screens(query="<screen type / content words>", mode="keyword")` —
  finds screens NAMED like yours (e.g. "workout summary", "streak stats").
  Add filters that sharpen it: `screen_type`, `flow`, `element`.
- `search_screens(query="<what it should feel like>", mode="semantic")` —
  finds screens that LOOK like the goal ("calm dark stats dashboard with a
  hero number and weekly bars"). Different screens will surface — that's the
  point of running both.

Save all ~60 into a local board (see SKILL.md's structure). Pick the **best
5–8** and say why each earns its place. If one is nearly perfect, pull
`get_screen` on it — its `similar_screens` often surfaces an even better
sibling from another app.

## 3. Extract the pattern

From the picks, write the target: layout skeleton, hierarchy order, control
choices, spacing rhythm, palette role-mapping, motion moments (entrance,
press feedback, data reveal). This is a spec, not a mood board — every line
should be checkable in a screenshot.

## 4. Rebuild and iterate (the loop)

1. Implement against the spec using **appllama-app-design-skill** (typography
   ramp, semantic colors both themes, native controls, Reanimated motion
   with the platform's curves, state kept boring).
2. Asset gaps (illustration, empty-state art, icons beyond the symbol set):
   generate with the best available image model at max quality, one style
   system, per the design skill's image-assets reference.
3. **Simulator loop until perfect**: screenshot → compare side-by-side with
   your top references → fix → repeat. Record the motion and scrub it
   frame by frame. Verify Dynamic Island/safe areas, dark + light, Dynamic
   Type XL, Reduce Motion, 60fps on the interaction.
4. Do not stop at "better than before". Stop when the honest side-by-side
   with the best reference reads **at least as good** — hierarchy, motion,
   font discipline, state handling, everything. If it doesn't, name the gap
   and go around again.

## 5. If the screen is part of a flow

Screens live in journeys. After the screen passes, walk one step before and
one step after it in the simulator: entrance transition, exit transition,
state carried across — and what back does from it on iOS and Android
(appllama-app-design-skill's Navigation laws).
If the screen is a sheet, a modal or a step behind a one-way door, verify
its presentation matches what it *is*, not just how it looks. Use `get_flow_apps` + `list_app_screens(flow=…)` if
you need to see how winners chain the surrounding steps
(references/research-methods.md).

# Research methods: flows, elements, and how to study like a director

## Flow research — study journeys, not screenshots

Flows are where conversion and retention actually live. Use them when the
question is "how do winners structure X?" rather than "what does X look
like?".

1. `list_flows(query="onboarding")` — or browse the taxonomy — to find the
   exact flow names and their footprint (screens/apps counts tell you how
   universal a flow is).
2. `get_flow_apps(flow="Paywall")` — the apps that contain it, top revenue
   first, each with its screen count *inside that flow*. A 9-screen paywall
   flow from a $2M/mo app is a masterclass; read it.
3. `list_app_screens(app_id=…, flow=…)` — the flow itself, in order. Study
   3–5 apps' versions of the same flow side by side and chart the common
   spine: step count, what each step asks vs. gives, where friction is
   deliberately placed, where it's removed — and what each step *is*
   (a pushed screen, a modal with its own steps, a sheet, an overlay),
   which the videos show better than stills. Winners are consistent about
   presentation; that grammar is part of the spec.

High-value flow studies for almost any category: Onboarding (length,
personalization, permission timing), Paywall (placement, trial framing,
price anchoring), Welcome (first 5 seconds), plus the category's signature
flows (Food Logging, Workout Session, Habit Check-in, …).

## Element research — how winners build one component

When the question is component-level ("how should our tab bar / progress
indicator / CTA look?"):

1. `list_ui_elements()` once — the ~38 family catalog with counts and top
   variants (Bottom Tab Bar, Rounded Primary CTA, Top Progress Bar, Skip
   Text Link, …).
2. `get_element_screens(element=…)` — real screens carrying that family.
   Pin a `variant` to narrow to one specific treatment.
3. Also usable as a filter: `search_screens(query=…, element=…)` combines
   content and component ("stats screens that use a Floating Bottom Nav").

Extract the numbers, not the vibe: sizes, placements, label conventions,
active-state treatments, how many items, what gets an icon vs. text.

## Study discipline (what separates research from tourism)

- **Question first.** Every pass answers a named question from your current
  task — "how long is onboarding here", "what does a winning paywall carry".
  Knowing the question is what turns screens into a spec.
- **See everything, in order.** Walk the full screen list of an app you're
  studying and look at every image; the journey is the unit of design, and
  a sampled journey lies. Notes outlive links: media URLs die in ~1 h, but
  screen ids (`app_id/screen_id`) keep any screen one `get_screen` away.
- **Cross-app before in-app.** One app tells you its taste; five apps tell
  you the category's grammar. Divergence between winners = a real choice;
  convergence = a convention you break knowingly or not at all.
- **Revenue is context, not truth.** A $5M/mo app's paywall is evidence
  about paywalls; its settings screen might still be lazy. Weight evidence
  by whether that surface plausibly drives the app's success.
- **Stop at saturation, not before.** A research question is answered when
  new screens stop changing your spec. Until then, keep looking.

## Working with the member's own curation

`list_my_boards()` shows boards the member built on appllama.io;
`get_board(board_id)` reads any of them — screens boards return full screen
payloads with media, apps boards return app profiles, flows boards return
(app, flow) pairs ready for `list_app_screens`. An apps board also works as
a `search_apps(board_id=…)` base. Their taste is a requirement, not a
suggestion — when a board exists for the task, start from it.