Stream Flutter - docs orchestrator for Flutter

This skill is small on purpose. It does not bundle SDK reference dumps - the official Flutter docs are the source of truth and cover the whole surface (Chat UI + core + low-level client, Video calls / ringing / livestream, Feeds).

Your job is to orchestrate: classify the request, point to the exact docs page, fetch it live, and apply it inside the user's project - while obeying the curated rules and pitfalls the docs do not shout about.

Rules (read once per session): RULES.md - non-negotiable rules + Flutter pitfalls. Read before writing any code.

The docs convention (the core mechanism)

Every Stream docs page has a Markdown twin: take the page URL, drop the trailing /, add .md.

https://getstream.io/chat/docs/sdk/flutter/basics/installation/   ->   https://getstream.io/chat/docs/sdk/flutter/basics/installation.md

Always fetch the .md variant - clean Markdown with verbatim code, no page chrome.

Per-product index pages list every page with its .md URL:

URL grounding: only fetch a page URL you got from docs-map.md or from a live index fetch in this conversation. Do not invent doc paths from memory - many look guessable but are wrong. If a page is not in the map, fetch the live index and pick from it.

Step 0: Classify the request (always first)

From the user's words alone - no probes first - resolve three things:

1. Product - Chat, Video (calls, ringing, audio rooms, livestream), Feeds, or a combination.
2. Package / layer - Chat: stream_chat_flutter (pre-built UI, the default) or stream_chat_flutter_core (custom UI - see the strategy decision below). Video: stream_video_flutter. Feeds: stream_feeds (never the deprecated stream_feed).
3. Mode - one of:
   • How-to / reference ("how do I add reactions?", "what does StreamCallContainer do?", "theming", explicit widget/package tokens, "docs") -> go straight to Docs lookup. No setup, no credentials.
   • Integrate ("add Chat to my app", "wire Video into this project") -> run setup.md, then Docs lookup for the feature.
   • New app ("build a Flutter chat app", "create a livestream app", "build a Twitter-style feed") -> setup.md (it scaffolds when asked), then Docs lookup, scoped to the requested screens. Feeds defaults to Twitter-style UI.
   • Setup only ("install Stream", "wire auth/token") -> setup.md and stop.
   • Review / audit ("review / audit / check my Stream integration", "is this ready for production?", "are we ready for the livestream launch?", "prepare for the integration review") -> read-only: skip setup and credentials, follow stream skill's integration-review.md with integration-review.md for the Flutter checks. A livestream or audio-room app also gets stream skill's livestream-review.md. Report first; change code only if asked.
   • Push / ringing ("push notifications", "incoming calls when the app is closed", "CallKit", "FCM", "missed calls") -> push.md (after setup if the app is not wired yet).
   • Advanced Video patterns (TikTok-style livestream feed, 1:1 call while livestreaming, two calls at once, audio-room lobby, shared call state, Chat + Video in one app) -> video-patterns.md plus the docs it routes to.
   • Migrate from Sendbird ("replace sendbird_chat_sdk / sendbird_uikit with Stream", "switch off Sendbird") -> run sendbird-migration.md: detect the Sendbird integration shape, swap packages + init, re-implement each touchpoint while changing as little app code as possible, re-apply theming, and verify design + functional fidelity per screen against the Sendbird original. It reuses setup.md for credentials and the rigor of design-matching.md; when the code migration is verified it asks whether to also migrate the data and hands off to ../stream/sendbird-data-migration.md.
   • AI assistant / LLM chat -> stay on the pre-built Chat components and route through the "AI assistants" docs rows in docs-map.md; the backend contract is ../stream/ai-backend-contract.md (the model runs on a backend agent, never in the app).

Bare /stream-flutter with no args: list the modes briefly and wait. If it is ambiguous between build and how-to, ask one question:

Do you want me to wire this into the project, or just show the Flutter SDK pattern?

Styling-depth flag (orthogonal to the mode)

If the request carries a target appearance - a screenshot, a Figma frame, "make it look like WhatsApp / iMessage / Telegram / Slack / " - then before feature work, first run the strategy decision below:

• Components -> run design-matching.md: read its procedure half in full (everything above the # Reference divider - it may span two Reads), then Grep its Reference half per region while implementing.
• Custom (livestream / overlay / bespoke) -> run custom-ui.md instead - same region-by-region rigor, different mechanism.

A reference design is a checklist of regions (header, composer buttons, timestamp + read-receipt placement, bubble shape/tail, date separators, attachments, ...), and most differ from Stream's defaults structurally, not just by color. Decompose every region first (with its dimensions), then route each to theming or widget replacement (RULES.md "Design fidelity"). The match is not done until you run, seed data that triggers every region, compare region by region against the reference on the real navigation path, and iterate (design-matching.md Step 5). Implement every region, the composer included - a region left at the SDK default is a FAIL, not a footnote. Work in batches: ground the pinned SDK version once, read the source you need in one pass, implement all regions, then verify on hot reload.

Chat only: pick the UI strategy first (before any code)

Stream Chat ships two layers, and choosing between them is an architecture decision that dwarfs any styling choice. Default to the pre-built components.

Lean hard toward components. The litmus test: if theming + a few component-builder slots could get there, it is a components job - even strong messenger reskins. Pick custom only when matching the design means replacing the message row, composer, header, AND list at once - using the SDK purely as a data source. Over-choosing custom (rebuilding a worse messenger and losing avatars / grouping / reactions / threads / attachments / typing / receipts / pickers) is the common, expensive mistake. When unsure, build the components version first. Treat "livestream" / "live shopping" as signals, not labels: a livestream app that wants a normal bubble chat panel stays on components.

Workplace / Slack-style is a components job too. The message row is flat and left-aligned (rounded-square avatar, author + status + timestamp line, body, bottom reaction pills, thread-reply summary) with no incoming/outgoing split - override the messageItem component builder (a composite slot - reproduce its sub-features) and customize the header. Workplace apps are thread-first: wire the thread summary and thread screen. Archetype details: design-matching.md.

The strategy also picks the channel type and permission model (messaging membership-gated vs livestream public + anonymous viewers) - see RULES.md "Permissions". If it is genuinely unclear, ask one question:

Does this chat look like a standard messenger (channel list + bubbles), or a bespoke surface like livestream/overlay chat? It decides whether we customize the pre-built components or build custom UI on stream_chat_flutter_core.

Step 1: Docs lookup (every request ends here)

1. Open docs-map.md. Find the row matching product + layer + feature -> it gives the exact .md URL(s).
2. If the feature is not in the map, fetch the live index for the product (table above) and pick the best-matching page.
3. Fetch the .md page(s) with WebFetch. Fetch at most 3 pages per request; if more are needed, hand the user the index URL.
4. Apply the page's guidance to the user's project: use its code where possible, adapting only to the existing app shape (navigation, state management, DI).
5. Cite the page you used: Source: [Title](https://getstream.io/...). Never answer SDK specifics from training data - if you did not fetch it this conversation, fetch it now or say you could not find it.
6. If the docs do not fully cover it - an exact component-builder slot, a theme property, a default widget's sub-features, an undocumented option, real wiring - escalate to the SDK source + example apps at the version pubspec.lock pins (see "When the docs fall short" in docs-map.md). Say where you found it rather than presenting it as documented. For matching a reference design this escalation is the norm: when you override a composite slot, read the default widget's build() and enumerate every sub-feature it renders so you reproduce them instead of silently dropping them.
7. Apply best practices - no query spam, no clients or controllers in build, authenticate once (RULES.md "Mindful API usage"), and read the vertical's best-practices page (e.g. livestream chat) before scaling.

Setup (integrate / new app / migrate)

Run setup.md once per session before feature work. It covers, in order:

1. Project signals - detect the Flutter project / Stream dependencies / empty dir, and the Chat v10 version check.
2. Credentials - API key + user token via the Stream CLI (or pasted), optional seed channels / posts, Feeds self-follow.
3. Install - the right packages with flutter pub add.
4. Platform setup - the iOS / Android / web / macOS steps the docs do not fully cover.
5. Wire the client - initialize once, connect the user.

Then return here for Docs lookup on the specific screens.

What this skill carries

There are no bundled SDK reference or blueprint files - anything that used to live there now comes from the live docs via the map, which keeps the skill current and covers far more. The curated, non-doc content is:

• RULES.md - rules and pitfalls (build-breakers, permissions, v10 / Video / Feeds gotchas).
• docs-map.md - intent -> docs page routing, plus where to read SDK source.
• setup.md - the CLI-driven setup flow.
• push.md - Chat push + Video ringing (CallKit / FCM / Telecom), automating what the docs only describe.
• video-patterns.md - Video patterns with no docs page.
• integration-review.md - Flutter checks for the read-only integration review, livestream checks included.
• design-matching.md - reproducing a reference design with the pre-built components.
• custom-ui.md - the custom stream_chat_flutter_core path.
• sendbird-migration.md - the Sendbird -> Stream Chat migration procedure.