--- name: bt-start description: Route vague Basis Theory requests to the right skill and mode. license: MIT metadata: tier: core last_verified: '2026-09-25' --- # Basis Theory implementation router You are assisting with a Basis Theory integration in the user's coding session. First classify the goal, decide whether planning is needed, ask only architecture-changing questions, and load the skill that matches the work. ## Step 0 — Safety gate (before classifying anything) If the request or the repository contains an exposed live credential — a production API key pasted into the chat, a secret committed to code — or the user asks you to hardcode, echo, or work around credential safety, stop before doing anything else: 1. Say plainly that the credential is exposed and must be rotated/revoked now; never echo or embed it. 2. Make **no repository changes** until that safety problem is acknowledged — refusal is read-only (see conventions below). Urgency ("just do it", "demo in an hour") does not change this order. 3. Once acknowledged, continue the underlying ask with placeholders (``) against a test tenant. Also stop read-only when the user asks to weaken validation or tenant behavior for convenience — for example "configure the test tenant to accept any invalid card number." Do not mutate tenant settings, repository code, fixtures, or validation logic to make arbitrary invalid PANs pass. Say that validation exists to keep test evidence meaningful, then recommend documented Basis Theory test cards/test scenarios and PSP sandbox decline cases instead (route details to `bt-test-debug` if needed). ## Step 1 — Classify the goal Map the ask to a skill. Load only what the task needs. | Goal sounds like | Skill | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Add a card form", "collect cards / bank accounts / sensitive data", "Elements", "tokenize", "token intent", "we have our own card forms", "we won't use iframes", "let a browser agent fill the card form", "WebMCP / agent tools on checkout", "dual writing to our processor" | `bt-collect` (agent tools are a merchant checkout surface; Agentic Payments credentials are `bt-agentic`) | | "Plan Basis Theory for this repo", "add Basis Theory here", "make payments portable", "reduce PCI scope", "audit/design this integration", plan/design/rollout/audit a feature program, underspecified architecture ask | `bt-plan` first, then the selected feature skill | | "Write an integration design document", "specify the agreed implementation for customer sign-off", "document our flows, resources, configuration and reasons" | `bt-integration-design` after decisions are made; `bt-plan` first only when architecture is still undecided | | "Token types", "token schema", "masks", "fingerprints", "search", "token reference", "expression safety" | `bt-tokens` | | "Charge / verify / refund a card", "process payments through Stripe/Adyen/Checkout.com/any PSP", "payment SDK" | `bt-payments` | | "Multi-PSP", "provider generation", "PSP mapping", "failover", "least cost", "portable payment client" | `bt-payments` + `bt-psp-orchestration` | | "Proxy", "send tokenized data to a third party", "receive sensitive data inbound", "detokenize and forward", "proxy transform / expression" | `bt-proxy` | | "Reactor", "Proxy/transforms cannot safely express this", "must run programmable branching/orchestration on detokenized data inside Basis Theory" | `bt-architecture` first, then `bt-reactors` only if Proxy/direct do not fit | | "3DS", "3D Secure", "SCA", "challenge flow", "authentication before charge" | `bt-3ds` | | "Network tokens", "cryptogram", "DPAN", "network-token enrollment" | `bt-card-lifecycle` + `bt-network-tokens` | | Precise Account Updater mechanics, "cards keep expiring", "reissued cards", "updater result codes" | `bt-card-lifecycle` + `bt-account-updater` | | "authorization rates", "recurring / subscription card health" | `bt-card-lifecycle` + at least one mechanics overlay: `bt-network-tokens` or `bt-account-updater` | | "Apple Pay", "Google Pay", "wallet payments" | `bt-wallets` | | "Issue cards", "display full PAN to users/agents", "set card PIN" | `bt-issuing` | | "Store SSNs / PII / documents", "search encrypted data", "mask / reveal / audit access", "data residency" | `bt-pii` | | "How should we structure tenants / applications / keys / permissions", "platform with sub-merchants", "proxy vs reactor vs direct" | `bt-architecture` | | "Migrate from/to a PSP", "import / export cards", "leave Stripe", "backup tokens", "vault portability" | `bt-migrate` | | "It's broken", "4xx/5xx", "webhook not verifying", "works in test not prod", "sandbox testing setup" | `bt-test-debug` | | "Go live", "production checklist", "key rotation", "IP allowlist", "SSO / MFA" | `bt-production` | | "Agentic commerce", "AI agent payments", "allowance", "payment method", "agentic credential", "ACP", legacy "agents / enrollments / instructions" | `bt-agentic` (verify against current docs; legacy terms are maintenance-only) | | "Card-present", "in-person", "terminal", "POS card capture" | No dedicated public docs surface today — say so honestly. Patterns are processor- and file-exchange-specific; keep Basis Theory at the narrowest sensitive-data boundary if it fits, and route specifics to Basis Theory (https://basistheory.com/contact) rather than generalizing from e-commerce guidance. | Disambiguation rules (implementation patterns that prevent common mis-routing): - "Charge a card" routes to `bt-payments` even though the implementation usually rides the proxy. `bt-proxy` is for proxy-as-a-primitive questions. - "Should I use a proxy or a reactor?" is a judgment question → `bt-architecture` (primitive selection), not the mechanics skills. - "My proxy call fails / destination returns 4xx" → `bt-test-debug` first (boundary proof), then `bt-proxy` for the fix. - "Collect and charge" (the most common combined ask) → `bt-collect` then `bt-payments`, in sequence; keep this router's mode decision resident across both. - "Add Basis Theory to this repo", "reduce PCI scope", or "make payments portable" without an explicit approved build slice → `bt-plan` first in plan-only mode. Inspect the repo before asking questions and do not mutate product code yet. - A vague **feature program** ask combines a planning verb or program-level noun (`plan`, `design`, `rollout`, `audit`, `review`, `program`) with a feature lifecycle. Route `bt-plan` first and the feature skill second. For example, "plan a card refresh program for expiring cards" routes `bt-plan` → `bt-account-updater`. A precise request to implement one already-decided updater API call or result-code handler routes directly to `bt-account-updater`; do not turn every concrete feature implementation into planner work. - Lifecycle overlays are required reads, not concepts to mention. A recurring/subscription card-health plan routes `bt-plan` → `bt-card-lifecycle` → at least one of `bt-network-tokens` or `bt-account-updater`. A concrete network-token request routes `bt-card-lifecycle` + `bt-network-tokens`. Open every skill in the selected route before answering. - Refund lifecycle reviews mentioning replay, idempotency, a changed amount/payload, or distinct refunds route to `bt-payments` or `bt-test-debug`, even when the prompt does not name Basis Theory. The selected skill must inspect the framework's real caller. - "Show full card numbers to agents" → `bt-issuing` if the cards were issued by the customer's program; `bt-pii` reveal patterns if they are stored third-party cards. - Greenfield or topology asks add `bt-architecture`; "we're on X today" asks add `bt-migrate`; "it's broken" asks add `bt-test-debug`; go-live asks add `bt-production`. Load at most one judgment skill alongside the feature skill. ## Step 1.5 — Check for the hidden decision (implementation patterns) Many asks are mislabeled on arrival; answering only the surface ticket leaves the failure mode in place. Six repeats: 1. Onboarding/setup asks that are really **tenant & merchant design** → surface hierarchy and credential ownership before setup steps (`bt-architecture`). 2. Test-vs-prod questions that are really **parity and rollout risk** → answer the environment model, not the local question (`bt-production`). 3. Debugging asks that are really **wrong-primitive selection** → boundary-proof first, then challenge the primitive (`bt-test-debug` → `bt-architecture`). 4. Token-type questions that are really **lifecycle/sequencing** → reframe around store-now-vs-defer, auth-first-vs-retention-first (`bt-collect`). 5. Access/setup friction that is really **key-type, permission, or environment mismatch** → check scope before assuming product limitation (`bt-architecture`). 6. "How do we make this fast enough?" asked about an async chain on a synchronous path — token → webhook → reactor → UI polling for checkout — is really **wrong-primitive selection**. The latency is the design, not a tuning knob, so do not answer it from `bt-reactors` alone; load `bt-architecture` for the primitive rubric and move the critical path to a synchronous call (`bt-proxy` when the job is forwarding, synchronous reactor invocation when plaintext logic is genuinely required), leaving webhooks for work that is not checkout-critical. When one fires, name the surface ask, name the hidden decision, then recommend — and say what would change the answer. ## Step 2 — Ask only what changes the architecture Implementation pattern: the smallest set of clarifying questions that change the recommendation, nothing more. For most implementation asks these four cover it: 1. **Who touches card/sensitive data today?** (their servers, their frontend, a processor iframe, nobody yet) — decides collection pattern and PCI-scope story. 2. **Which PSP(s) or downstream systems?** One PSP, several, or undecided — decides source-type mapping and whether multi-PSP portability matters. 3. **Existing vault/integration or greenfield?** — decides migration sequencing vs fresh implementation. 4. **Web, mobile, or API-only?** — decides SDK surface. If the answers are already evident from the repo or the ask, do not ask — state them as assumptions and proceed. ## Step 3 — State the mode Say explicitly which mode the work runs in: - **Plan-only**: for "plan", "sketch", "audit", "review", "tell me", "specify", "what must", "should we", bare "add Basis Theory", bare "reduce PCI scope", and bare "make payments portable" asks. Inspect and answer with evidence; do not mutate product code or create docs files unless the user asks for an artifact. - **Plan-and-build**: for explicit vague build asks after `bt-plan` has produced slices and the user approves the bounded first slice. - **Existing-code implementation**: inspect the user's repository, explain the recommended pattern, make bounded changes that preserve their architecture, add tests, and report honestly what remains. - **POC scaffold**: generate a bounded reference implementation from explicit requirements (structure defined in [references/poc-conventions.md](references/poc-conventions.md)). A POC is a reference, not a production system, and is never represented as production-ready. - **Explain**: for an integration goal named without an explicit build instruction — "add Apple Pay to our checkout", "charge stored cards through Adyen and fall back to Braintree". Lead with the decision that gates the work (ownership, primitive choice, whether the PSP has a verified mapping), then say what you would build once it is settled, and offer to scaffold a POC. Do not answer an approach question by generating an implementation. When the workspace is empty or a placeholder there is no architecture to preserve, so scaffolding does not make a bounded change — it invents a design and pre-commits the user to it before the gating decision is made. That is also how invented integrations get shipped: a PSP with no verified Basis Theory mapping (see the `verification` field on each mapping in `bt-payments`) turns into confident-looking code for an interface nobody checked. Say the mapping is unverified and what it would take to verify it. Implementation modes — existing-code, POC scaffold, and plan-and-build — end with a clear final report: what is done, what was assumed, what proof ran, and what remains customer-owned. Remaining production items usually include real PSP accounts and credentials, production tenant setup, compliance review, and the `bt-production` checklist. ## Step 4 — Load and go Load the target skill(s) and follow their customer-facing guidance. The full page→skill map for Basis Theory docs is in [references/docs-map.md](references/docs-map.md); the long-form labeling and safety conventions are in [references/customer-safe-conventions.md](references/customer-safe-conventions.md). `bt-start` is a router, not a substitute for the selected feature skill. After classifying, open every selected skill before answering; for lifecycle/idempotency tests, this means `bt-payments` or `bt-test-debug`, not `bt-start` alone. Planning and implementation hardening references: - Planner/preflight: `bt-plan` and [../\_shared/references/host-framework-preflight.md](../_shared/references/host-framework-preflight.md) - Credential boundary: [../\_shared/references/credential-boundary.md](../_shared/references/credential-boundary.md) - Proxy destination trust: [../\_shared/references/proxy-destination-trust.md](../_shared/references/proxy-destination-trust.md) - Lifecycle/idempotency: [../\_shared/references/lifecycle-idempotency.md](../_shared/references/lifecycle-idempotency.md) General API facts that belong to no single feature skill (link canonically rather than restating): - API reference index: https://developers.basistheory.com/docs/api/ - Authentication and key types: https://developers.basistheory.com/docs/api/authentication - Pagination: https://developers.basistheory.com/docs/api/pagination - SDK catalog (server-side, web, mobile, Terraform, CLI): https://developers.basistheory.com/docs/sdks/ - CLI: https://developers.basistheory.com/docs/sdks/cli/ ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/index.md` - `../_shared/references/implementation-guidance/concept-routing.md` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.