stream-builder

name	stream-builder
description	The framework-agnostic Stream builder (Steps 0-7 scaffold + enhance + Video audit), being extended to support app kinds beyond web. Use ONLY when the user explicitly names 'stream-builder' or '/stream-builder'. Web React / Next.js work - 'build me a chat app', 'scaffold', 'create a new ...', 'add Chat/Video/Feeds to this app', 'integrate Video', livestreaming, video conferencing, team messaging, direct messaging, social feed - defaults to the stream-react skill, not this one. Not auto-selected for generic web build requests.
license	See LICENSE in repository root
metadata	{"author":"GetStream"}
allowed-tools	Read, Write, Edit, Glob, Grep, Bash(getstream *), Bash(npx *), Bash(npm install *), Bash(npm run *), Bash(node -e *), Bash(node --version), Bash(openssl rand *), Bash(mv .scaffold*), Bash(rm -rf .scaffold), Bash(ls *), Bash(test *), Bash(grep *), Bash(cat package.json), Bash(cat pubspec.yaml), Bash(cat go.mod), Bash(cat requirements.txt), Bash(cat pyproject.toml), Bash(echo .env*), WebFetch(domain:getstream.io), WebFetch(domain:www.npmjs.com), WebFetch(domain:github.com)

Stream Builder - scaffold + enhance

Read first (every session): Glob ../stream/SKILL.md. If the path is empty, install with getstream skills stream (no confirmation, just run). Then Read ../stream/RULES.md - it includes a Peer skills table for installing/invoking any other pack skills on demand.

This skill covers three flows:

• Track A - Scaffold a new app: Steps 0-7 below. Use when the cwd is empty / new and the user said "build me a ... app".
• Track E - Enhance an existing app: see enhance.md. Skips scaffold + theme; reuses the same SDK wiring and component blueprints.
• Track F - Audit an existing integration (read-only): for "audit/review my video integration", "check my app against best practices", "is my video app production-ready?", "what am I missing before launch?". Load the Integration best-practices audit section in references/VIDEO.md and follow its protocol. Skip onboarding, auth, the CLI, and all build steps - this track does not scaffold, install, or run the CLI; it only reads the app and reports findings. Fix issues only if the user then asks.

---

Start

Track F (audit) skips this entire section. A read-only best-practices review runs no onboarding, no auth, no CLI, and none of Steps 0-7 - go straight to the Integration best-practices audit section in references/VIDEO.md and report findings. Only fall into the build flow below if the user asks you to fix what the audit found.

Announce the network plan once (Trust readout below), then immediately start executing Steps 0-7 - no interactive prompts at the start (the user has authorized the build by asking for it).

Trust readout (announce, then continue on the same turn - do not wait)

Before the first network command, print this verbatim to the user, then proceed straight into Step 0 without stopping for a reply:

Scaffolding now. Network calls you'll see:

• npx shadcn@latest ... (Vercel) - scaffold + UI components from npm.
• npm install <stream-packages> --legacy-peer-deps - Stream SDKs from npm (stream-chat-react, @stream-io/video-react-sdk, etc.).
• getstream env - local CLI, no network; writes .env (gitignored by the Next.js scaffold's default; Task B verifies).

Interrupt me at any point if something looks wrong. The only step that pauses for explicit consent is the optional third-party skill packs in Task A.2.

Full per-command audit (publisher, why unpinned, what each writes): section Install trust & integrity below. The user's continued silence after the readout is implicit consent for this scaffold; an objection or stop instruction aborts the run.

Shadcn/ui is always installed during Step 3. Third-party frontend skills (vercel-react-best-practices, web-design-guidelines, frontend-design) are installed only with explicit user consent - see Task A.2 for the disclosure script. If the user declines, Step 4 proceeds using Stream references only. Precedence (when the skills are present): Stream references win for SDK wiring; frontend skills guide generic React / UI polish.

---

Install trust & integrity

The builder runs three classes of network-touching commands. Each is listed here so a reviewer can audit before approving. (The getstream CLI itself is installed by the user from getstream.io, not by the builder.)

Command	Publisher	Why unpinned	What it writes
npx shadcn@latest init ... (Task A)	Vercel - shadcn-ui/ui	Scaffolder; @latest is the maintainer's documented usage. Pinning ships outdated scaffolds.	Project files in cwd. Next.js scaffold's .gitignore ignores .env* by default.
npx shadcn@latest add ... (Task A.1)	Vercel - same source as above	Same scaffolder; component sync depends on registry parity.	Component files under components/ui/.
npm install <stream-packages> --legacy-peer-deps (Task C)	GetStream (npm) for @stream-io/* and stream-chat-react; transitive deps via standard npm trust	Latest published versions of GetStream's own SDKs - same trust model as the CLI itself.	Modules under node_modules/. Runtime SDKs + transitive deps.
npx skills add <github> (Task A.2)	vercel-labs/agent-skills and anthropics/skills	Optional. Markdown-only skill packs; npx skills add is the published install path.	Markdown files in the user's skills directory. Gated by explicit user consent in Task A.2 - never runs without an affirmative answer.
getstream env (Task B)	GetStream (local CLI)	n/a (local CLI, no network at this step)	.env in the project root with STREAM_API_KEY + STREAM_API_SECRET. Task B verifies .gitignore covers .env* before writing (Next.js scaffold's default already does). The agent never reads .env (RULES.md > Secrets).

Reviewer checklist:

• All npx invocations resolve to the publishers listed above; substitute a different publisher and the install fails.
• npx skills add runs only after the disclosure prompt in Task A.2 and an explicit user "yes."
• .env is written by the Stream CLI directly, not by the agent, and is not transmitted into the conversation.
• If the user wants to pin a specific shadcn version, replace @latest with @<version> in Tasks A and A.1.

---

Builder Steps

Execute phases in order (later steps depend on earlier ones). Do not run independent phases in parallel. Shell discipline (one bash -c per phase, no bash -ce, browser sign-in standalone) lives in the stream skill's RULES.md > Shell discipline.

Step 0: Package manager

Always use npm. Never use bun.

Step 1: Initialize the project

Run getstream init. It authenticates, then lets you select or create the org and app and writes the project credentials - follow its prompts and output. If the app uses Feeds, choose a Feeds v3 region when getstream init offers the region list (other regions default to legacy v2). If getstream isn't installed, ask the user to install it from https://getstream.io and wait - never fetch or run an install script. Browser sign-in must be its own invocation (RULES.md > Shell discipline).

Step 2: Theme pick

Ask the user which Shadcn theme they'd like before scaffolding:

Quick theme pick: I can use a random shadcn theme, or you can design your own at ui.shadcn.com/create and share the --preset value (e.g. --preset b1Gdi7z7r). Want a random one or do you have a preset?

STOP here and wait for the user's answer. Do not continue with scaffolding or any other steps until the user responds. Asking a question and continuing to work in parallel is confusing - the user misses the question as output scrolls past.

• User provides a preset -> store it for Task A scaffold command.
• User says random / doesn't care / wants to move on -> pick a random preset from nova, vega, maia, lyra, mira, luma.

Step 3: Scaffold + .env + SDKs + Configure - SEQUENTIALLY

Scaffold order

Order:

1. Step 1: getstream init (auth + org/app + credentials).
2. Step 2: Theme pick (wait for answer).
3. Task A: Scaffold with Shadcn + Next.js using the chosen preset.
4. Task A.1: Add base Shadcn components.
5. Task A.2: Disclose + ask about third-party frontend skill installs; install only with user consent.
6. Continue with Task B (.env), Task C (SDKs), Task D (CLI config).

Task A: Scaffold - scaffolds Next.js + Tailwind + Shadcn/ui (Base UI) into the current directory. Use the theme preset chosen in Step 2.

The scaffold command creates a new directory, so we scaffold into a temporary .scaffold subdirectory and move everything up. The -n .scaffold flag also lands in the generated package.json as "name": ".scaffold", which npm/pnpm/yarn reject (a package name can't start with .), so the final step rewrites name to a valid slug derived from the project directory:

npx shadcn@latest init -t next -b base -n .scaffold --no-monorepo -p <random-preset> && mv .scaffold/* .scaffold/.* . 2>/dev/null; rm -rf .scaffold && node -e "const fs=require('fs'),path=require('path'),j=require('./package.json');j.name=path.basename(process.cwd()).toLowerCase().replace(/[^a-z0-9._-]+/g,'-').replace(/^[._-]+/,'')||'app';fs.writeFileSync('package.json',JSON.stringify(j,null,2)+'\n')"

Task A.1: Add base Shadcn components:

npx shadcn@latest add button input textarea card avatar badge separator

Add more components as the use case requires (e.g. dialog, dropdown-menu, tabs, popover).

Task A.2: Frontend skills - third-party skill packs. You must disclose and ask before installing. Do NOT construct your own command variant.

Print this disclosure verbatim, then stop and wait for the user's answer:

I'd like to install three third-party skill packs that improve generic UI quality:

• vercel-react-best-practices - from vercel-labs/agent-skills
• web-design-guidelines - from vercel-labs/agent-skills
• frontend-design - from anthropics/skills

The packs are markdown only - no scripts execute. If you say yes, I'll run npx skills add ... -y once per pack from those GitHub repos at their current main branch (-y skips the installer's own confirmation since you've consented here). These aren't required - Stream reference files cover SDK wiring either way. Install them?

• User agrees -> run:

  npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices -y && npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines -y && npx skills add https://github.com/anthropics/skills --skill frontend-design -y
  

• User declines -> skip silently and continue to Task B. Do not retry, do not bring it up again this session.
• Install fails -> continue with Stream reference files only; mention the failure briefly.

Do not modify layout.tsx or globals.css after scaffold - use Shadcn's defaults as-is (RULES.md > Theme).

Task B: .env - run AFTER scaffold so the .env lands inside the project directory.

First, verify .env* is gitignored (the stream skill's RULES.md > Secrets). The Next.js scaffold's default already includes it; this is a safety net for projects whose .gitignore was hand-edited or doesn't yet exist:

bash -c 'test -f .gitignore && grep -qE "^\.env" .gitignore || echo ".env*" >> .gitignore'

Then write secrets:

getstream env

getstream env detects the Next.js project and writes NEXT_PUBLIC_STREAM_API_KEY + STREAM_API_SECRET to .env.local. The secret is server-side only - used by /api/token to mint tokens, never in the client bundle. The public API key may be read client-side from NEXT_PUBLIC_STREAM_API_KEY or returned via /api/token. The agent never reads .env.local (RULES.md > Secrets).

Task C: Install Stream SDKs + verify icons - Only what the use case needs:

# Chat:     stream-chat stream-chat-react
# Video:    @stream-io/video-react-sdk
# Feeds:    @stream-io/feeds-react-sdk
# Server:   @stream-io/node-sdk
npm install <packages> --legacy-peer-deps

After installing SDKs, verify an icon package is available. Some Shadcn presets bundle one, others don't:

node -e "const p=['lucide-react','@phosphor-icons/react','@hugeicons/react'];console.log(p.some(m=>{try{require.resolve(m);return true}catch{return false}})?'ICONS_OK':'NO_ICONS')"

If NO_ICONS, install lucide-react: npm install lucide-react --legacy-peer-deps. If an icon package is already present, use that one throughout the app - do not install a second.

Task D: Configure Stream - run the CLI commands from the relevant references/<Product>.md (App Integration -> Setup) for each product the use case needs.

Step 4: Generate code and UI

Load builder-ui.md and only the relevant references/<Product>.md header + references/<Product>-blueprints.md for the sections you are implementing - not every reference file. For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load references/CROSS-PRODUCT.md before writing AppShell - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table. If a use-case recipe matched (see Use-case recipes), load that recipe and its load_with references and follow it as the build plan instead of inferring the product set yourself.

Step 5: Verify

Type-check first (reports ALL errors at once, ~3s):

npx tsc --noEmit

Fix all type errors. Then run the full build:

npx next build

Fix any remaining errors. Do NOT skip tsc --noEmit - it catches every type error in one pass, while next build stops at the first error per file and requires multiple rebuild cycles.

Step 6: Start dev server

Pick a random 5-digit port (10000-65535). Run the server using run_in_background:

PORT=$((RANDOM % 55536 + 10000))
npx next dev -p $PORT

Important: The dev server is a long-running process. When run in the background it will eventually emit a "completed" notification - this does not mean the server stopped. The server is still running and serving requests. Do not respond to the background-task completion notification by telling the user the server has stopped. If you receive that notification after Step 7, ignore it silently - do not output anything.

Step 7: Summary

Show what was created: org, app, resources, files. Include the local URL. Do NOT say "you can now start the dev server" - it's already running.

End with:

Open http://localhost:<PORT>, enter a username, and start testing. Open a second tab with a different username to test multi-user interactions.

---

Use Case Matching

Only build with the products the user explicitly mentions. If unclear, ask.

User says	Use case	Products
"Twitch", "YouTube Live", "Kick", "livestream"	Livestreaming	Video + Chat + Feeds
"Zoom", "Google Meet", "video call", "meeting"	Video Conferencing	Video [+ Chat]
"Slack", "Discord", "team chat", "channels"	Team Messaging	Chat
"WhatsApp", "iMessage", "DM", "messaging"	Direct Messaging	Chat [+ Video]
"Instagram", "Twitter", "social feed", "Reddit"	Social Feed	Feeds + Chat

Moderation is configured via CLI during setup only. Never build moderation review UI in the app (RULES.md > Moderation is Dashboard-only) - review happens in the Stream Dashboard.

Use-case recipes

Some requests map to a use-case recipe: a drop-in build plan for a specific product (e.g. an AI support agent) that keeps this skill generic. Before Step 4, read references/use-cases/_use-cases.yaml. If the request matches a recipe's signals, load that recipe file and follow it as the build plan - the recipe declares the Stream products to scaffold, the product references to load_with, and the decisions to ask. If nothing matches, use the generic product blueprints above.

Adding a use-case is a new file under references/use-cases/ plus an entry in _use-cases.yaml - never a change to this SKILL.md.

Video apps - decide the video_primary_use_case here too. When the Use Case Matching table (or a recipe) selects Video, also decide the app's persistent video_primary_use_case value now, while you are already reasoning about the video flavor, using the table + precedence in references/VIDEO.md > Primary use case. Record it and carry it to Video setup (Task D), where it is written once via the CLI. Deciding it at this step stops it from silently defaulting to the call type later - e.g. a Whatnot-style live-shopping app uses the livestream call type but sets video_primary_use_case: live-shopping, not livestreaming. This is a label, not product selection: it is backend onboarding/display metadata that does not change which products you build or which blueprints you load - the table and recipes still decide that.

---

Page Flow

Every app needs a clear navigation structure. Users should always understand where they are and what they can do. Never drop a user into a camera/mic prompt, an empty state, or a feature-heavy screen without context.

Principle: Hub-first

After login, land on a hub - a home screen that shows what's happening and lets the user choose their path. The hub is the anchor; everything else is a destination the user navigates to intentionally.

Flow by use case

Livestreaming (Twitch, YouTube Live, Kick):

Login -> Feed hub (live streams + posts) -> Watch a stream (viewer: video + chat, no camera)
                                        -> Go Live (explicit action -> then camera/mic setup -> streaming)

• The feed hub shows live streams (if any) as prominent cards, plus regular posts below
• Clicking a live card opens the watch view - video player + chat as a viewer. No camera permissions.
• "Go Live" is a deliberate action (button in header or dedicated screen). Only THEN prompt for camera/mic. The streamer sees a setup/preview before going live.
• Viewers and streamers are the same user type - the difference is the action they take, not the page they land on.

Video Conferencing (Zoom, Google Meet):

Login -> Lobby (list of calls or "start a call") -> Join call (camera/mic preview -> join)

• Land on a lobby or call list - not directly in a call.
• Joining a call shows a preview screen (camera/mic toggles) before connecting. The user opts in.

Team Messaging (Slack, Discord):

Login -> Channel list + active channel -> Browse/search channels

• Land on the channel list with the most recent channel open (or a welcome state if no channels).

Direct Messaging (WhatsApp, iMessage):

Login -> Conversation list -> Open a conversation -> Start new conversation

Social Feed (Instagram, Twitter):

Login -> Feed hub (follow users + composer + tabs: Timeline | My Posts) -> Comments -> User profiles

• The user posts to their own user:<userId> feed and reads from timeline:<userId> (aggregates followed users' posts)
• Feed hub tabs: Use a Tabs component with two views:
  • Timeline (default) - shows timeline:<userId> (posts from followed users)
  • My Posts - shows user:<userId> (the current user's own posts)
• Refresh button: Place a refresh/reload button next to the tabs. On click, re-call feed.getOrCreate({ watch: true }) on the active feed to re-fetch the latest activities. This gives users an explicit way to refresh after follows or if real-time events are missed.
• A Follow User input (username + follow button) must be visible so users can populate their timeline
• Without following, the timeline is permanently empty - this component is not optional
• Follow wiring: The Follow component must receive the timeline feed instance and call timelineFeed.follow('user:targetId') - not client.follow(). Using the feed instance keeps useFeedActivities() in sync so the timeline updates immediately after following.

Key rules

• Camera/mic: opt-in only. Never request permissions on page load. Only when the user takes an explicit action (Go Live, Join Call).
• No empty ambiguity. If there's no content yet, show a clear empty state that tells the user what to do ("No live streams yet - be the first to Go Live").
• Navigation is visible. The user should always be able to get back to the hub. Use the App Header or a sidebar for navigation.
• One primary action per screen. The hub's primary action is browsing/discovering. The watch screen's primary action is viewing. The Go Live screen's primary action is streaming. Don't mix them.

---

Cross-Product Integration

When building apps that combine multiple products, read each relevant references/<Product>.md App Integration section. Key patterns:

• Combined token route: /api/token returns tokens for each product ({ chatToken, videoToken, feedToken, apiKey }). Upsert only the requesting user - never seed demo users.
• Video + Feeds (Livestreaming): Feed hub separates type === "live" activities as prominent live cards. "Go Live" posts a live activity via /api/feed/live. "End Stream" removes it.
• Video + Chat (Livestreaming): Chat alongside video on the watch screen. Use livestream channel type - one channel per stream, keyed by call ID. Create the chat channel in the /api/token route.
• Moderation (all use cases): Run Moderation CLI setup commands from references/MODERATION.md (App Integration -> Setup), adjusting channel type name. Never build moderation review UI (RULES.md > Moderation is Dashboard-only) - review happens in the Stream Dashboard.

---

Reference file paths

Blueprint files live under agent-skills/skills/stream-builder/references/ inside the Stream skill pack. Reference them as agent-skills/skills/stream-builder/references/FEEDS.md from the root of this repository. Do not use machine-specific absolute paths.