--- name: bt-plan description: Plan architectural or PCI-scope-changing Basis Theory work. license: MIT metadata: tier: core last_verified: '2026-07-22' --- # Implementation planner Use this skill before product-code mutation when the request is vague, architectural, audit-shaped, or could touch PCI scope. ## Modes - **plan-only**: inspect the repository and produce the plan. Do not mutate product code. - **plan-and-build**: after the user approves bounded slices, implement one slice at a time, run proof, review the diff, then continue. Requests containing "plan", "sketch", "audit", "review", "tell me", "specify", "what must", "should we", bare "add Basis Theory", bare "reduce PCI scope", or bare "make payments portable" are **plan-only** unless the user explicitly asks you to implement or build an approved slice. Do not create documentation files as a substitute for answering a plan-only prompt. A vague feature-program ask also starts here: plan/design/rollout/audit/review of a feature lifecycle routes through `bt-plan` before the selected feature skill. In particular, a card-refresh program for expiring cards routes `bt-plan` → `bt-account-updater`. A precise, already-bounded feature implementation still routes directly to its feature skill. A recurring/subscription card-health plan must load `bt-card-lifecycle` and at least one mechanics overlay before answering: `bt-network-tokens` for enrollment, cryptograms, and processor boundaries, or `bt-account-updater` for refresh jobs, result codes, and reconciliation. Listing an overlay in the skill sequence without opening it does not satisfy the route. In plan-only mode, do not edit, create, delete, format, or generate any repository file. Do not run fixers or tests that write snapshots/caches. Do not read `.env*`, credential stores, or secret files; inspect only filenames and documented variable names. Never present compliance certification, production readiness, or live PSP verification as proven. When the ask proposes putting raw card numbers through the customer's backend — "just pass the PAN through for now", "we'll tokenize later" — the plan does not quietly route around it. State the standing default in those words: **`raw_pan` stays disabled unless you explicitly choose PCI-in-scope mode**, and name what choosing it costs them (their servers enter card-data scope, with the assessment, segmentation, logging, and retention obligations that follow). Then plan the path that keeps it disabled. "Do not add a raw PAN source" describes your recommendation; "raw_pan stays disabled" describes the switch the customer actually controls, and only the second tells them a decision is theirs to make rather than yours to have made. ## Inspect before asking Run the host-framework preflight in [../\_shared/references/host-framework-preflight.md](../_shared/references/host-framework-preflight.md). Build a current-state map before asking questions. Name exact file paths and exact symbols/fields/constants from code; do not paraphrase away load-bearing evidence such as `vault_data_card`, `TRUSTED_BT_BASE_URL`, `originator`, or `refundId`. - payment and checkout ownership: app-owned form, PSP-hosted checkout, framework plugin, no payment path, or provider-owned no-code boundary; - credential-bearing variants and data shapes, including metadata and token-shaped fields; - adapter/provider seams and the real caller signature; - persistence, retry, capture, void, refund, webhook, reconciliation, and log paths; - existing PSP, vault, proxy, wallet, framework, and issuer responsibilities; - tests and fixtures that prove the real path. If the inspection shows Basis Theory is not appropriate, say so, and state the operational conclusion literally as a **zero-code conclusion** rather than implying it. Reach it whenever one of these holds: - **No sensitive-data boundary exists for Basis Theory to own** — for example genuinely anonymous telemetry, product analytics events, or aggregate metrics. Write it plainly: **this is a zero-code conclusion; Basis Theory is not appropriate for data with no sensitive-data boundary**. - **Provider-owned hosted checkout** where the customer cannot intercept card data: **this is a zero-code/no-replacement conclusion; I would not replace the provider with Basis Theory unless checkout ownership changes**. - **The ask is only legal or compliance adjudication**, which these skills do not decide. State that conclusion _before_ any conditional design, and name the one condition that would change it. A conditional fit is not a substitute for the plain conclusion about the ask as stated: "Basis Theory would help if those events turn out to carry emails or device IDs" answers a different question than the user asked. Do not present a conditional Basis Theory fit as the answer to the stated ask. Give the conditional design second, clearly marked as contingent on that condition being true. ## Plan-and-build evidence ledger Before the first product-code mutation, record a **Before-mutation evidence ledger** in the working response. It must name, with exact repository evidence: - **Entrypoint and caller/call path**: the inspected repository entrypoint, its symbol, the next caller or endpoint, the adapter/service method reached, and the parameters the host framework actually supplies. - **Credential-bearing fields**: every observed field/variant that can carry a token, card data, credentials, metadata, or destination. - **Persistence/lifecycle paths**: the concrete stores and paths for retries, captures, voids, refunds, webhooks, reconciliation, jobs, and logs, including explicit absences. - **Proof files**: the existing and proposed tests/fixtures that exercise the real path. Do not substitute a generic intended architecture for this ledger. For the bundled mixed-payments context, for example, the real inspected path is `src/checkout.ts::submitCheckout` → `POST /api/payments/authorize` → `src/payments.ts::authorize`; naming only the helper that will be edited is incomplete. Retain the ledger under the exact **Before-mutation evidence ledger** heading in the final completion response so the receipt can be audited against the pre-change evidence. In the final answer, repeat this ledger as the first section even if it already appeared earlier in the working trajectory. Write the four entries as four labeled lines, using these literal labels, so the ledger stays auditable line by line instead of collapsing into prose: ```text Entrypoint and caller/call path: Credential-bearing fields: Persistence and lifecycle paths: Proof files: ``` Keep the lifecycle line even when almost everything on it is absent. An empty lifecycle surface is the finding: it tells the reader that retries, refunds, and webhooks are unbuilt rather than merely unmentioned, and that is what decides whether the next slice is safe. Listing the absences inside the credential-field sentence buries it. ## Decision checkpoint Ask only questions that change the architecture and cannot be answered from code. Batch them once: - Which actor is allowed to own checkout/card collection if the repo currently delegates it? - Which PSPs or downstream systems are in scope for the first slice? - Is the customer explicitly choosing PCI-in-scope raw PAN handling, or should `raw_pan` stay disabled? - Which operation boundary must be preserved first: auth, capture/void, refund, webhook, account updater, network tokens, or migration? If none remain, state assumptions and proceed. ## Plan shape Produce exactly these section labels: 1. **Problem** 2. **Reality (repo evidence)**: concrete files, call paths, config, data variants, ownership, tests. 3. **Assumptions and unresolved decisions** 4. **Direction and boundary diagram in words**: who sends what to whom; where plaintext can and cannot exist. 5. **Implementation slices** 6. **Skill used per slice and what guidance it supplies** 7. **Owners/customer-owned work** 8. **Proof gates and rollback** Do not rename these headings to shorter variants; clear reviews depend on explicit labels. Under section 6, include one explicit line: `Skill sequence: bt-plan → → → bt-test-debug → bt-production` Omit skills that are not needed, but keep `bt-plan` first and name the order the build agent should follow. For plan-and-build, the user's explicit request to build the first bounded slice is approval for that slice. Stop after it, review the diff, and end with exact final-answer subheadings in this order: 1. **Before-mutation evidence ledger** 2. **Done** 3. **Assumed** 4. **Remaining** 5. **Proof** 6. **Review** 7. **Completion receipt** 8. **Rollback** Do not move the ledger after **Review** and do not collapse **Completion receipt** into an inline sentence. **Completion receipt** must be its own clear heading immediately after **Review**. Its first two non-empty body lines must use this template: ```text Entrypoint and caller/call path: Proof file and command: — ``` Copy those as plain lines. Do not add bullets, numbering, blockquotes, or backticks around either line. The receipt must also name what part of that path changed and include proven/unproven accounting in the same receipt body. For the bundled mixed-payments context, write the complete path explicitly on the first template line: `src/checkout.ts::submitCheckout` -> `POST /api/payments/authorize` -> `src/payments.ts::authorize`. Do not require another approval ceremony for work the user already authorized. ## Skill sequencing - Collection or token-intent decisions: `bt-collect` plus `bt-tokens`. - Charges, captures, voids, refunds, PSP source mapping: `bt-payments`; add `bt-psp-orchestration` for multi-PSP/provider-generation work. - Proxy transport or detokenization expressions: `bt-proxy`. - Network-token enrollment, cryptograms, lifecycle: `bt-card-lifecycle` plus `bt-network-tokens`; load both. - Card refresh programs: `bt-card-lifecycle` plus `bt-account-updater`; load both. - 3DS/SCA: `bt-3ds`. - Tenant/app/key topology or primitive choice: `bt-architecture`. - Migration/portability from an existing PSP or vault: `bt-migrate`. - Failure analysis, sandbox, webhooks, idempotency, evidence: `bt-test-debug`. - Go-live readiness: `bt-production`. Use the shared hardening references for implementation-producing slices: [credential boundary](../_shared/references/credential-boundary.md), [proxy destination trust](../_shared/references/proxy-destination-trust.md), [lifecycle and idempotency](../_shared/references/lifecycle-idempotency.md). ## Product diff boundary Exclude local agent configuration, prompts, and evaluation notes from the product diff. State explicitly that they are not product code or implementation evidence of a customer implementation change. ## 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/platform-identity.md` - `../_shared/references/implementation-guidance/tenants-and-access/` - `../_shared/references/implementation-guidance/environment-parity-checklist.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.