Integrate with an agent
Three sequenced prompts, and how to review what they build.
The intended path. Hand your agent the prompts below, review the diff, ship.
Works with Claude Code, Cursor, Codex, Windsurf or anything else that can read files in your repo.
Before you start
Install the packages and put your environment values in .env. The agent needs the packages present, because the files it reads ship inside them.
What the agent reads
node_modules/@xborglabs/fanbase-react/llms.txt
node_modules/@xborglabs/fanbase-react/quest.md
node_modules/@xborglabs/fanbase-react/bind.md
node_modules/@xborglabs/fanbase-react/prize.md
node_modules/@xborglabs/fanbase-react/battlepass.md
node_modules/@xborglabs/fanbase-react/store.md
node_modules/@xborglabs/fanbase-react/newsfeed.md
node_modules/@xborglabs/fanbase-react/leaderboard.md
node_modules/@xborglabs/fanbase-react/prompt.md
node_modules/@xborglabs/fanbase-react/skills/fanbase/SKILL.mdllms.txt is the entry point. Each of the feature files covers one feature end to end, and each one ends with a "Done when" the agent can check itself against. They ship inside the package, so they always match the version you installed.
After upgrading the packages, have the agent re-copy skills/fanbase/SKILL.md. A skill left over from an older version can miss features that llms.txt lists.
Order
Three prompts, run in sequence. Sign-in first, questing second, then any other feature, one at a time. Do not combine them. A working sign-in is what makes everything after it verifiable, and an agent given everything at once tends to stub the auth and produce something that looks finished and is not.
Prompt 1: sign-in
Implement Fanbase OAuth in this app.
Read node_modules/@xborglabs/fanbase-react/llms.txt first, sections
Portal, FanbaseProvider, OAuth and Env. Do not invent APIs. If something
is not in that file, stop and ask.
Install if missing: @xborglabs/fanbase-core and @xborglabs/fanbase-react.
This app owns its QueryClient.
Wrap the app in FanbaseProvider with:
- tenant, slug, appId
- httpOptions: { gamerBaseUrl, locale }
- a session adapter { get, set, clear }, localStorage is fine
- our queryClient
Read config from these env keys, see .env:
VITE_FANBASE_TENANT
VITE_FANBASE_COMMUNITY_SLUG
VITE_FANBASE_APP_ID
VITE_FANBASE_GAMER_BASE_URL
VITE_FANBASE_LOCALE
VITE_FANBASE_OAUTH_PROXY_URL
VITE_FANBASE_OAUTH_PROXY_SECRET
VITE_FANBASE_OAUTH_REDIRECT_URL
Sign-in:
1. buildOAuthProxyUrl({ oauthProxyUrl, proxySecret })
2. buildLoginUrl({ oauthProxyUrl, provider, redirectUrl })
provider is one of google, discord, twitter, twitch. It is the
identity provider. Never pass a tenant or community slug here.
3. Carry the provider forward on the redirect as ?provider= and in
sessionStorage. The proxy returns only ?token=.
Callback page, at the exact URL in VITE_FANBASE_OAUTH_REDIRECT_URL:
- Wait for useFanbase().state.ready before doing anything
- parseOAuthCallbackToken(window.location.href)
- actions.loginWithToken({ provider, token })
- Handle a missing token with a message, not an endless spinner
- Replace the history entry after success, the token is single use
Logout is actions.logout().
Done when: the callback exchanges ?token= using the same provider that
started sign-in, state.session has accessToken and refreshToken, a page
refresh keeps the fan signed in, and logout clears the adapter.Prompt 2: questing
Run after sign-in works end to end.
Implement Fanbase questing in this app.
Read, in this order:
- node_modules/@xborglabs/fanbase-react/llms.txt
- quest.md, the whole quest feature, including its reward catalog
- quest-templates.md, for requirement UI and submit payloads
- quest-description.md, for Parser, Quest.Description and the theme object
- bind.md, for linking an account a quest needs
- prize.md, for prize detail forms and the lootbox claim
- skills/fanbase/SKILL.md, an agent skill. If your tool loads skills from the
project, it finds this one and follows `llms.txt` without being told to.
Do not invent template names or payload shapes. If a template is not in
quest-templates.md, route it to the default empty-body branch.
List page:
- useQuestsList() only. One GET /v1/quests for the whole page.
- No per-quest detail calls and no allocation fetches for cards.
- Render our own card component from each row.
- Resolve quest status through resolveMessage('Quests.status.' + status).
Never render the raw enum, INACTIVE does not mean what it looks like.
Detail page:
- Quest.Provider with questId, and quest={row} seeded from the list.
Let the provider own that row. Do not copy it into local state.
- Pass fetchRewards, a flag, so the claim button knows a reward is waiting.
- Pass authProfile={{ socials, wallets }}. socials from useLinkedSocials(),
never from the profile, which omits expiry dates. wallets from
GET /v1/user/profile. Without it, gated quests stay disabled.
- Pass claimPayload, built with toAllocationClaimPayload, when a prize
requires details such as an email.
- Quest.Frame wraps our UI.
- Quest.Description with a theme object mapping to our classes.
- Requirement UI switched on a family you map from template.name, using the
Catalog in quest.md. Never switch on getApiType or getQuestType: they return
the submit path and a number, not a family.
- typed families (text, answer, prediction, quiz, poll, email, wallet,
image) use actions.submit(payload), not Quest.Submit
- empty-body families (visit, bind, progress, auto, unknown) use
Quest.Submit
- visit: an outbound <a target="_blank">, then a CTA bound to
state.canSubmit. Do not build a separate enabled flag.
- bind: a plain <a> to buildBindUrl, carrying the account type in the
redirect URL, plus the CTA. The callback redeems with useBind() within
five minutes. Follow bind.md.
- CTA copy comes from state.buttonLabel. Disabled state comes from
state.canSubmit or state.canClaim. Show state.disabledReasonLabel when
the fan cannot act.
Rewards:
- resolveQuestRewardChrome({ reward, quest }) for presentation. It returns
undefined for an unknown slug: render nothing then.
- Show rewards before completion, from quest.rewards, not only after
- Claim with Quest.Claim or actions.claimAllAllocated(), never actions.claim()
alone, which claims a single allocation and leaves the rest
- give_lootboxes: after claim, poll getQuestRewardAllocations until
lootboxOpening.selectedItem appears, then useLootboxes for the possible
items and resolveLootboxSelectedItem for the winner. Cover the wait with
an animation and cap it with a timeout.
- Only call claimLootbox when resolvePrizeClaimState says
REQUIREMENTS_REQUIRED.
Use our existing design system components and class names throughout.
Add no CSS of your own.
Done when: the list issues exactly one GET /v1/quests, a signed-in fan
can submit and claim at least one quest, statuses render as readable
labels, the description renders through Quest.Description, and a lootbox
claim opens a reveal.Prompt 3: one more feature
Run once questing works, once per feature. Replace FEATURE with one of battlepass, store, newsfeed or leaderboard.
Implement the Fanbase FEATURE feature in this app.
Read node_modules/@xborglabs/fanbase-react/FEATURE.md in full before
writing anything, then the Membership section of llms.txt. Do not invent
APIs, fields or reason codes. If something is not in those files, stop
and ask.
Follow the file's Process section in order. Each step ends with a
"Done when". Do not move to the next step until the current one holds.
Rules that apply to every feature:
- Never pass a communityId, containerId or COMMUNITY_ID. The SDK resolves
the community from the slug on FanbaseProvider.
- Render the gate and reason values the SDK computes. Never recompute
membership, stock, balance or lock state yourself.
- Name the membership tier that would unlock something, from
requiredTierName. Never write a generic "Premium".
- Structured descriptions go through Parser, plain on cards.
- Every write is already optimistic and already invalidates what it
touched. Do not add your own setQueryData or refetch calls.
Use our existing design system components and class names throughout.
Add no CSS of your own.
Done when: every "Done when" in FEATURE.md holds, and every item in its
Smoke list passes.The feature guides on this site cover the same ground for a person reading: Battlepass, Store, Newsfeed, Leaderboard.
Reviewing what it built
Agents get this mostly right. The things worth checking by hand:
- Request count. Open the network tab on the list page. One
GET /v1/quests. Fanning out per card is the most common thing to fix. - Status labels. Any raw
INACTIVEon screen meansresolveMessagewas skipped. - The detail page after a submit. Submit a quest and watch the label and status change without a refresh. If they freeze, the row was mirrored into local state.
- A social-gated quest signed in. If it is disabled with no explanation,
authProfileis not being passed. - A premium item as a free fan. A battlepass tier, a store listing or a post. It should be locked and name the tier. If it shows a claim or buy button, the gate is being skipped.
- A store purchase that fails. Check the retry path never mints a new nonce. That is the one mistake that charges a fan twice.
- No hardcoded community id. Search the diff for
communityIdandcontainerId. Neither should be a literal. - Typecheck. On a Vite app,
npx tsc -p tsconfig.app.json --noEmit. The root config is references-only and exits 0 having checked nothing. - Your CSS. No new stylesheet should have appeared.
When the agent gets stuck
The prompts say to stop and ask rather than invent. If yours asks a question, the answer is usually in Quest templates or Hooks. If it is in neither, send it to us, because a question an agent has to ask is a page we owe you.