codebyplan 1.13.46 → 1.13.49

package/templates/skills/cbp-build-cc-skill/reference/cbp-quality.md

@@ -1,24 +1,22 @@
----
-scope: org-shared
----
-
 # Skill Authoring Quality
 
 Quality expectations and structure for `/.claude/skills/{name}/SKILL.md` files. This file adds CBP-specific constraints on top of the official Claude Code skills spec.
 
-## Required CBP Frontmatter
+## CBP Frontmatter — the `scope:` marker
+
+`scope:` is a CBP structural marker (not read by Claude Code itself). It is **required only on user-created skills** — ones the `codebyplan` package does NOT distribute. A package-managed skill (one with a template twin under `templates/skills/`) is `org-shared` by default and needs **no** marker; an explicit `scope: org-shared` on it is redundant. See `rules/scope-vocabulary.md`.
 
-Every skill MUST have `scope:` in addition to the Claude Code native fields:
+For a user-created skill, add a marker alongside the Claude Code native fields:
 
 ```yaml
 ---
-scope: org-shared # structural marker: org-shared | project-shared | repo-only:<repo-name>
+scope: project-shared # or: repo-only:<repo-name> (user-created skills only)
 name: cbp-skill-name
 description: One sentence — shown in skill list and used for auto-matching
 ---
 ```
 
-`scope:` is a CBP structural marker — not read by Claude Code itself. Missing `scope:` fails validation (`validate-skill.sh` / `validate-structure-scope.sh`).
+`validate-skill.sh` validates the value when present but does not require the key; `codebyplan claude verify-parity` is the central enforcer of the user-created requirement (and warns on a redundant `org-shared` marker on a managed skill).
 
 ## What Skills Are
 

package/templates/skills/cbp-build-cc-skill/scripts/validate-skill.sh

@@ -46,8 +46,16 @@ fi
 # Description recommended
 grep -qE '^description:\s*' <<< "$fm" || echo "  WARN: no description — Claude will use first paragraph" >&2
 
-# CBP scope required
-grep -qE '^scope:\s*' <<< "$fm" || err "missing CBP required field: scope (org-shared|project-shared|repo-only:<repo-name>)"
+# CBP scope: OPTIONAL. Required only on user-created assets (no template twin) —
+# that requirement is enforced centrally by `codebyplan claude verify-parity`.
+# Package-managed skills default to org-shared (markerless). Here we only validate
+# the VALUE when a marker is present.
+if grep -qE '^scope:\s*' <<< "$fm"; then
+  scope_val=$(grep -E '^scope:' <<< "$fm" | head -1 | sed -E 's/^scope:[[:space:]]*//; s/[[:space:]]*$//')
+  if ! [[ "$scope_val" =~ ^(org-shared|project-shared|repo-only:[a-z0-9]([a-z0-9-]*[a-z0-9])?)$ ]]; then
+    err "scope value '$scope_val' is not a valid enum value (org-shared|project-shared|repo-only:<slug>)"
+  fi
+fi
 
 # Model — skills MUST NOT pin a model. A skill's inline turn runs in the user's
 # active session, so it inherits the session model. Pinning one forces a model the

package/templates/skills/cbp-checkpoint-check/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-check
 description: Full re-evaluation of a checkpoint with before/after comparison
 argument-hint: [CHK-NNN]

package/templates/skills/cbp-checkpoint-complete/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-complete
 description: Complete a checkpoint after all tasks are done
 argument-hint: [checkpoint-number]

package/templates/skills/cbp-checkpoint-create/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-create
 description: Mechanical checkpoint creation — capture the user's description, infer title + goal, dedup against existing modules, create the checkpoint row + feat branch, then hand off to /cbp-checkpoint-plan for deep planning. Creates ZERO tasks.
 argument-hint: [checkpoint description]
@@ -67,24 +66,24 @@ Ask the user via AskUserQuestion whether to claim this checkpoint now:
 - **Claim for me + this worktree** (default) — resolve `npx codebyplan resolve-worktree 2>/dev/null` and set it as the checkpoint `worktree_id` at create. The creator carries momentum straight through plan → start.
 - **Leave it open** — create with `worktree_id` null so anyone free can claim it later via `/cbp-checkpoint-start`.
 
-Record the choice; it drives both the create call (Step 8) and the plan→start routing in `/cbp-checkpoint-plan`.
+Record the choice; it drives both the create call (Step 7) and the plan→start routing in `/cbp-checkpoint-plan`.
 
-### Step 7: Determine Next Checkpoint Number
-
-Scan `.codebyplan/state/checkpoints/*.json` for the highest `number` field + 1. If state dir is absent, run `npx codebyplan sync` once. Break-glass fallback: MCP `get_checkpoints` when sync fails.
-
-### Step 8: Create Checkpoint Row
+### Step 7: Create Checkpoint Row
 
 `codebyplan checkpoint create` (CLI write-through: writes `.codebyplan/state/checkpoints/<id>.json` + REST). Pass flags:
-- `--repo-id` (from `.codebyplan/repo.json`), `--number`, `--title`, `--goal`, `--deadline`, `--status pending`
+- `--repo-id` (from `.codebyplan/repo.json`), `--title`, `--goal`, `--deadline`, `--status pending`
 - `--ideas` JSON `[{ description: <raw user text> }]`
 - `--worktree-id` the resolved worktree **only if the user chose "claim"**; omit when "leave open"
 
-Break-glass fallback: MCP `create_checkpoint` when the CLI is unavailable.
+Do **not** pass `--number` — the database auto-assigns the next per-repo checkpoint number via a `BEFORE INSERT` trigger (advisory-locked `MAX(number)+1` scoped to `repo_id`). The DB-assigned number comes back on the created row (and is written into `.codebyplan/state/checkpoints/<id>.json`); read it for the branch slug (Step 8) and the result display (Step 9).
+
+Break-glass fallback: MCP `create_checkpoint` (also omit `number`) when the CLI is unavailable.
 
 This is the first identity-stamping point — when claiming, passing `worktree_id` here engages the CHK-104 hard-lock from birth. No `context`, `research`, `plan`, or tasks are written here.
 
-### Step 9: Create + Switch to Feat Branch
+### Step 8: Create + Switch to Feat Branch
+
+`{NNN}` below is the DB-assigned checkpoint number read back from the Step 7 `codebyplan checkpoint create` response.
 
 Read `.codebyplan/git.json` `branch_config.production` (default `"main"`) as `BASE`. codebyplan repos are main-only — never create or branch from a `development`/integration branch.
 
@@ -107,7 +106,7 @@ Persist the branch via `codebyplan checkpoint update --id <checkpoint-id> --bran
 
 **Note — Supabase preview branch**: no Supabase branch is created here. Creation is lazy — it happens on the first DB change when `/cbp-supabase-migrate` runs on this feat branch, which provisions a Supabase branch named identically to the git branch. See `cbp-supabase-migrate` Step 2.3 for the creation protocol.
 
-### Step 10: Show Result + Auto-Trigger Plan
+### Step 9: Show Result + Auto-Trigger Plan
 
 ```
 ## Checkpoint Created

package/templates/skills/cbp-checkpoint-end/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-end
 description: Single point for all shipment — branch promotion to main via /cbp-ship-main, runtime deploy via /cbp-ship, branch cleanup, summary. Standalone tasks bypass shipment entirely.
 effort: xhigh

package/templates/skills/cbp-checkpoint-plan/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-plan
 description: Deep inline planning for a checkpoint — assess, gap-analyse, decide dependencies, compare alternatives, optionally e2e-probe a suspected-broken area, then create tasks as vertical slices. Runs after /cbp-checkpoint-create (mechanical) and before /cbp-checkpoint-start (activate + claim). Does NOT activate or claim.
 argument-hint: [checkpoint-number]

package/templates/skills/cbp-checkpoint-plan/reference/alternative-comparison-template.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Alternative Comparison Template
 
 Loaded by `/cbp-checkpoint-plan` Step 6. Use when a meaningful design fork has more than one viable answer. Surfacing the alternatives — instead of silently picking one — is what lets the user redirect before tasks are created.

package/templates/skills/cbp-checkpoint-plan/reference/dep-decision-rubric.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Dependency Decision Rubric
 
 Loaded by `/cbp-checkpoint-plan` Step 5. Use when an idea could be built by extending something already installed OR by pulling in a new dependency. The goal is a deliberate, recorded choice — never a silent `pnpm add`.

package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # E2E Discovery Probe
 
 Loaded by `/cbp-checkpoint-plan` Step 4. The probe answers one question before you plan a fix: **is this area actually broken, and how?** It reuses the config-matched `cbp-e2e-*` specialist (the framework owners of e2e execution) in `whole_checkpoint_mode` rather than introducing a second smoke-test path. See `context/testing/e2e.md` for the dispatch contract that selects which specialist to spawn.

package/templates/skills/cbp-checkpoint-plan/reference/gap-analysis-playbook.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Gap Analysis Playbook
 
 Loaded by `/cbp-checkpoint-plan` Step 3. The job: find what the raw request misses, before any task is created. Most "half-ass" outcomes come from planning only what was literally asked and ignoring the foundations it depends on or the adjacent breakage it sits next to.

package/templates/skills/cbp-checkpoint-start/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-start
 description: Activate a planned checkpoint and claim it for the current user/worktree, then route into task work. Runs after /cbp-checkpoint-plan (which produces tasks but never activates). Refuses to start an unplanned checkpoint.
 argument-hint: [checkpoint-number]

package/templates/skills/cbp-checkpoint-update/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-checkpoint-update
 description: Update checkpoint state (activate, update context, etc.)
 argument-hint: [checkpoint-number]

package/templates/skills/cbp-frontend-a11y/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-frontend-a11y
 description: Pre-implementation accessibility playbook loaded BEFORE writing UI / styling code. Produces a per-component checklist of WCAG 2.1 AA obligations from semantic HTML, ARIA roles/states, keyboard patterns, and contrast requirements.
 effort: xhigh

package/templates/skills/cbp-frontend-design/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-frontend-design
 description: Up-front design playbook loaded BEFORE writing UI / styling code. Detects the stack, loads the matching reference file, commits to an aesthetic direction, and prevents generic AI-slop output. Modelled on Anthropic's frontend-design skill, adapted for CBP repos with existing design systems.
 effort: xhigh

package/templates/skills/cbp-frontend-ui/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-frontend-ui
 description: Visual quality self-review pass invoked twice per round — once by round-executor Step 3.8 (phase 'style_only', no screenshots) for token/spacing/typography/color/cohesion, once by /cbp-round-execute Step 5b (phase 'screenshot_review', with e2e screenshots) for rendered-output review and baseline regressions. Default phase 'full' runs everything for back-compat.
 effort: xhigh

package/templates/skills/cbp-frontend-ux/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-frontend-ux
 description: Interaction-quality self-review pass loaded by round-executor AFTER UI code is written. Catches navigation flow issues, missing feedback states, cognitive-load problems, form usability gaps, and accessibility violations. Auto-applies in-scope mechanical UX fixes within the round's files_changed. Replaces the post-implementation ux-agent spawn with an inline skill invocation.
 effort: xhigh

package/templates/skills/cbp-git-branch-feat-create/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-git-branch-feat-create
 description: Create feature branch from the production branch (main, config-driven)
 argument-hint: "[name] e.g. add-user-auth"

package/templates/skills/cbp-git-commit/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-git-commit
 description: Create scoped commit with conventional format
 argument-hint: "[--task|--all] [type]: [description]"

package/templates/skills/cbp-git-worktree-create/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-git-worktree-create
 description: Create git worktree with clean command setup and register in CodeByPlan
 argument-hint: <branch-name> e.g. codebyplan-app

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-git-worktree-remove
 description: Remove git worktree and deregister from CodeByPlan
 argument-hint: <name> e.g. codebyplan-app

package/templates/skills/cbp-map-architecture/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-map-architecture
 effort: xhigh
 description: Orchestrate architecture map generation for one or all modules. Spawns the cbp-map-architecture agent per module, writes per-module .md files to .claude/architecture/, regenerates INDEX.md and graph.md, and stamps each module via the CLI. Idempotent — safe to re-run.

package/templates/skills/cbp-merge-main/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-merge-main
 description: Merge main into the current feat branch with interactive per-conflict resolution and inline QA re-run
 effort: high

package/templates/skills/cbp-refresh-arch-map/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-refresh-arch-map
 effort: high
 description: Drift-scoped refresh of the .claude/architecture/ map — re-runs the cbp-map-architecture agent for ONLY the modules whose stamped git SHA has changed, regenerates INDEX.md + graph.md, and re-stamps. Idempotent; no-op when no module has drifted.

package/templates/skills/cbp-round-check/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-check
 description: Run automated checks standalone for the current round
 effort: low

package/templates/skills/cbp-round-complete/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-complete
 description: Reconcile user git-add approvals, complete the round, and route to the next step
 argument-hint: [chk-task-round | task-round]

package/templates/skills/cbp-round-end/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-end
 description: Summary wrap-up after testing phase completes
 effort: high

package/templates/skills/cbp-round-execute/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-execute
 description: Execute the approved plan from /cbp-round-start — runs per-wave executors, inline testing-qa per wave, and routes to /cbp-round-end
 effort: xhigh
@@ -119,6 +118,14 @@ If the approved plan includes database schema changes, RLS policies, or type gen
 2. Wait for completion
 3. Merge `files_changed` into executor output
 
+### Step 3b-stripe: Stripe Work (if plan includes Stripe integration)
+
+If the approved plan includes Stripe integration work (files under `stripe/`, or plan steps referencing `payment`, `checkout`, `webhook`, `subscription`, or an explicit `stripe_work: true` flag from the planner):
+
+1. Spawn `cbp-stripe-agent` with Stripe-related steps from the plan and `files_changed_scope` from the executor output
+2. Wait for completion
+3. Merge `files_changed` into executor output
+
 ### Step 3c: Completion Check
 
 - `status: 'completed'` and all deliverables done → proceed to Step 4
@@ -229,7 +236,7 @@ Trigger `/cbp-round-end`.
 
 - **Reads**: `.codebyplan/state/checkpoints/<id>/tasks/<id>.json`, `checkpoints/<id>/tasks/<id>/rounds/<id>.json` (local-first; `npx codebyplan sync` on miss; MCP `get_current_task` / `get_rounds` as break-glass)
 - **Writes**: `codebyplan round update --id <uuid> --task-id <uuid> --checkpoint-id <uuid>` (Steps 6+7 — context with executor_output + testing_qa_output + e2e_eligible + e2e_outputs + frontend_ui_review; break-glass: MCP `update_round`)
-- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-security-agent` (if security review needed)
+- **Spawns**: `cbp-round-executor` (per wave or single), `cbp-testing-qa-agent` (per wave, parallel sibling of the `cbp-e2e-*` specialists), the `cbp-e2e-*` specialists (config-driven dispatch per `context/testing/e2e.md`, one per eligible framework in `.codebyplan/e2e.json`), `cbp-database-agent` (if DB work), `cbp-stripe-agent` (if Stripe work), `cbp-security-agent` (if security review needed)
 - **Skill invocations**: `cbp-frontend-ui` at Step 5b with `phase: 'screenshot_review'` (post-e2e)
 - **Triggers**: `/cbp-round-end` (auto)
 - **Triggered by**: `/cbp-round-start` (auto, after plan approval)

package/templates/skills/cbp-round-execute/reference/inline-fallback.md

@@ -1,7 +1,3 @@
----
-scope: org-shared
----
-
 # Inline-fallback procedures
 
 When `round-executor` or `testing-qa-agent` cannot be spawned (env limits, monthly cap, 5xx, rate limit, context overflow), the orchestrator falls through to an inline procedure that walks the agent's Phase checklist using its own tools.

package/templates/skills/cbp-round-input/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-input
 description: Gather input for a new round with deep analysis of unapproved work
 argument-hint: [chk-task-round | task-round | requirements-text]

package/templates/skills/cbp-round-start/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-start
 description: Start a round — planning phase only
 triggers: [cbp-round-execute]

package/templates/skills/cbp-round-update/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-round-update
 description: Triage a finished round (Claude-only); direct user to run round-complete on a clean round, or trigger round-input when more work is needed
 argument-hint: [chk-task-round | task-round]

package/templates/skills/cbp-session-end/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-session-end
 description: End a development session
 effort: xhigh

package/templates/skills/cbp-session-start/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-session-start
 description: Start a development session
 triggers: [cbp-todo]

package/templates/skills/cbp-session-start/qa-regression.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-session-start-qa-regression
 description: Manual regression procedure for the cbp-session-start worktree-ownership awareness + resolve-worktree distress channel (CHK-137 TASK-3)
 ---

package/templates/skills/cbp-setup-e2e/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-setup-e2e
 description: Detect installed E2E frameworks, ask which to enable, record credentials source (gitignored env-file path + var names only, never secrets), and write/refresh .codebyplan/e2e.json. Interactive, idempotent.
 argument-hint: "[--force]"

package/templates/skills/cbp-setup-eslint/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-setup-eslint
 description: Detect each app's tech stack, resolve matching DB ESLint presets, confirm which to enable per app, run `codebyplan eslint init` to generate eslint.config.mjs, and write/refresh .codebyplan/eslint.json. Interactive, idempotent.
 argument-hint: "[--force]"

package/templates/skills/cbp-ship/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-ship
 description: Orchestrate runtime deployment for a checkpoint — Vercel web, EAS mobile (Expo Go dev build / TestFlight preview), Tauri desktop, npm package publish, VS Code extension, Railway backend, Supabase migrations. Detects configured surfaces, walks the user through what to deploy, executes per-surface deploy steps, verifies each landed.
 effort: xhigh

package/templates/skills/cbp-ship-configure/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-ship-configure
 description: Configure shipment for one or more surfaces in the current repo — Vercel link, EAS project + eas.json scaffold, Apple credentials probe, npm publish auth check (including `codebyplan` asset-publish automation via the publish-on-main workflow), Railway project link, Supabase access token verify; Supabase GitHub branching integration via /cbp-supabase-setup. Interactive step-by-step; never stores credentials in the repo.
 argument-hint: [--surface=<id>]

package/templates/skills/cbp-ship-main/SKILL.md

@@ -1,5 +1,4 @@
 ---
-scope: org-shared
 name: cbp-ship-main
 description: Ship feat branch to production branch via PR — thin wrapper around `codebyplan ship`
 effort: high

package/templates/skills/cbp-stripe/SKILL.md

@@ -0,0 +1,116 @@
+---
+scope: org-shared
+name: cbp-stripe
+description: "Stripe integration guidance — load when implementing or reviewing payments, Checkout, subscriptions/billing, webhooks, Connect, Tax, or Treasury. Encodes the API-selection routing table, the no-payment_method_types rule, restricted-key security, and Stripe SDK conventions."
+effort: xhigh
+---
+
+# Stripe Integration (CBP)
+
+Load this skill before writing or reviewing any Stripe integration code — accepting payments,
+Checkout Sessions, subscriptions, webhooks, marketplaces (Connect), tax compliance, or
+embedded financial accounts (Treasury). It encodes Stripe's current recommended API surface,
+the critical `payment_method_types` prohibition, and CBP-specific conventions.
+
+## Integration routing table
+
+| Building…                                     | Recommended API                     | Reference                         |
+| --------------------------------------------- | ----------------------------------- | --------------------------------- |
+| One-time payments                             | Checkout Sessions                   | [reference/payments.md](reference/payments.md) |
+| Custom payment form with embedded UI          | Checkout Sessions + Payment Element | [reference/payments.md](reference/payments.md) |
+| Saving a payment method for later             | Setup Intents                       | [reference/payments.md](reference/payments.md) |
+| Connect platform or marketplace               | Accounts v2 (`/v2/core/accounts`)   | [reference/connect.md](reference/connect.md)   |
+| Subscriptions or recurring billing            | Billing APIs + Checkout Sessions    | [reference/billing.md](reference/billing.md)   |
+| Sales tax, VAT, or GST compliance             | Stripe Tax + Registrations API      | [reference/tax.md](reference/tax.md)           |
+| Embedded financial accounts / banking         | v2 Financial Accounts               | [reference/treasury.md](reference/treasury.md) |
+| Security (keys, webhooks, OAuth, Connect risk)| Restricted keys + sig verification  | [reference/security.md](reference/security.md) |
+
+Read the relevant reference file before answering any integration question or writing code.
+
+## Critical rules
+
+### Never include `payment_method_types` (except Terminal)
+
+Never pass `payment_method_types` in any Stripe API call. There are two narrow exceptions:
+- **Terminal** (in-person): `payment_method_types: ['card_present']` (Canada: add `'interac_present'`).
+- **Treasury bank-account Setup Intents**: `payment_method_types: ['us_bank_account']` with
+  `flow_directions: ['outbound']` (see [reference/treasury.md](reference/treasury.md)).
+
+Outside those, omit the parameter to enable dynamic payment methods — Stripe evaluates
+100+ signals to surface the most relevant methods and manage them from the Dashboard
+without code changes.
+
+This applies to ALL call sites:
+- `checkout.sessions.create` — omit entirely
+- `paymentIntents.create` — omit; on API versions before 2023-08-16 pass
+  `automatic_payment_methods: { enabled: true }` instead
+- `setupIntents.create` — same as PaymentIntents
+- `subscriptions.create` — omit `payment_settings.payment_method_types`
+
+To restrict or customise payment methods use
+[`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md)
+or `excluded_payment_method_types` — never `payment_method_types`.
+
+### Never use the Charges API
+
+The Charges API is never correct for new integrations. Redirect users to Checkout Sessions
+or PaymentIntents and the
+[migration guide](https://docs.stripe.com/payments/payment-intents/migration/charges.md).
+
+### Never use the Sources API
+
+Sources API is deprecated. Use Setup Intents to save payment methods.
+
+## Security summary
+
+- **Prefer a restricted API key (RAK, `rk_` prefix)** over a secret key (`sk_` prefix).
+  Create a separate RAK per service with minimum required permissions.
+- Test-mode keys: `sk_test_…` (secret) and `rk_test_…` (restricted).
+- **Never commit secrets.** Store in a secrets vault or, at minimum, server-side env vars.
+  Never embed keys in client-side code or mobile apps.
+- **Verify webhook signatures** via `stripe.webhooks.constructEvent(body, sig, secret)`.
+  Never process an unverified webhook event.
+- Use idempotency keys (`idempotencyKey`) on mutation calls to safely retry failures.
+- See [reference/security.md](reference/security.md) for RAK migration steps, IP
+  allowlists, OAuth CSRF protection, and Connect liability notes.
+
+### CBP-specific (Next.js)
+
+Any Next.js API route that imports `stripe` **MUST** export:
+
+```ts
+export const dynamic = 'force-dynamic';
+```
+
+Source: `.claude/skills/cbp-frontend-design/reference/nextjs-scss.md` Rule 6. Without this,
+Next.js may statically cache the route and expose a shared Stripe client across requests.
+
+## SDK and API version
+
+- Latest Stripe API version: **`2026-05-27.dahlia`**
+- Latest SDK major: **v22** (`stripe` npm package)
+- **Version flag**: consuming repos may still run `stripe` **v20.4.1** (per CBP vendor
+  inventory). Always check the installed version (`cat package.json | grep '"stripe"'`)
+  before applying v22-only patterns. Differences surface in TypeScript types and some
+  `configuration` parameter shapes.
+- Always use the latest API version and SDK unless the consuming repo pins otherwise.
+
+## Key documentation
+
+- [Integration Options](https://docs.stripe.com/payments/payment-methods/integration-options.md) — start here for any new integration
+- [API Tour](https://docs.stripe.com/payments-api/tour.md) — overview of Stripe's API surface
+- [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) — review before launch
+
+## Reference files
+
+- [reference/payments.md](reference/payments.md) — Checkout Sessions, Payment Element, PaymentIntents, Setup Intents, deprecated APIs, PCI
+- [reference/billing.md](reference/billing.md) — Subscriptions, invoices, Customer Portal, proration, trials, metered billing
+- [reference/connect.md](reference/connect.md) — Accounts v2, controller properties, charge types, onboarding, fund flows
+- [reference/security.md](reference/security.md) — Restricted keys, webhook signature verification, incident response, OAuth CSRF, Connect security
+- [reference/tax.md](reference/tax.md) — Stripe Tax automatic calculation, Registrations API, inclusive/exclusive, unsupported jurisdictions
+- [reference/treasury.md](reference/treasury.md) — v2 Financial Accounts, fund flows, bank-account Setup Intents, compliance
+- [reference/stripe-mcp-setup.md](reference/stripe-mcp-setup.md) — optional live Stripe MCP setup (test/restricted key) for the cbp-stripe-agent
+
+---
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), used under the MIT License (Copyright (c) 2024-2025 Stripe).

package/templates/skills/cbp-stripe/reference/billing.md

@@ -0,0 +1,106 @@
+# Billing / Subscriptions Reference
+
+Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
+
+## When to use Billing APIs
+
+Use Stripe Billing for any recurring revenue model: subscriptions, usage-based billing,
+seat-based pricing, or metered charges. Do NOT hand-roll renewal loops with raw
+PaymentIntents — Billing handles renewal, retry/dunning, proration, and tax automatically.
+
+References: [Subscription design guide](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) |
+[Use cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) |
+[SaaS guide](https://docs.stripe.com/saas.md)
+
+## Creating a subscription with Checkout
+
+Combine Billing APIs with Checkout Sessions (`mode: 'subscription'`) for the payment
+frontend. Checkout handles the initial payment, trial management, and proration.
+
+```ts
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  // Do NOT pass payment_method_types
+  line_items: [{ price: priceId, quantity: 1 }],
+  subscription_data: { trial_period_days: 14 },
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/pricing`,
+});
+```
+
+## Customer Portal (self-service management)
+
+For upgrades, downgrades, cancellation, and payment method updates, use the
+[Customer Portal](https://docs.stripe.com/customer-management/integrate-customer-portal.md)
+rather than building a custom flow.
+
+```ts
+const portalSession = await stripe.billingPortal.sessions.create({
+  customer: customerId,
+  return_url: `${baseUrl}/account`,
+});
+// redirect to portalSession.url
+```
+
+## Key Billing objects
+
+| Object | Purpose | Docs |
+| ------ | ------- | ---- |
+| `Price` | Unit amount + recurring interval | [Prices API](https://docs.stripe.com/api/prices.md) |
+| `Subscription` | Active recurring agreement | [Subscriptions API](https://docs.stripe.com/api/subscriptions.md) |
+| `Invoice` | Statement + payment trigger | [Invoices API](https://docs.stripe.com/api/invoices.md) |
+| `Customer` | Billing entity with saved methods | [Customers API](https://docs.stripe.com/api/customers.md) |
+
+Do NOT use the deprecated `plan` object — use `Price` instead.
+
+## Proration and upgrades
+
+When changing a subscription's price mid-cycle, Stripe generates proration invoice items
+automatically. Behaviour is controlled by `proration_behavior`:
+- `'create_prorations'` (default) — prorates immediately
+- `'none'` — no proration, change takes effect at next billing date
+- `'always_invoice'` — prorate and invoice immediately
+
+```ts
+await stripe.subscriptions.update(subscriptionId, {
+  items: [{ id: itemId, price: newPriceId }],
+  proration_behavior: 'create_prorations',
+});
+```
+
+## Metered / usage-based billing
+
+1. Create a `Price` with `recurring.usage_type: 'metered'`.
+2. Report usage via `stripe.subscriptionItems.createUsageRecord(itemId, { quantity, timestamp })`.
+3. Stripe aggregates usage and bills at the end of the period.
+
+## Tax integration
+
+Pass `automatic_tax: { enabled: true }` on subscriptions and Checkout Sessions. Clear
+any `default_tax_rates` first — `automatic_tax` and explicit `tax_rates` are mutually
+exclusive. See [reference/tax.md](tax.md) for the full setup.
+
+## Trials
+
+Set `trial_period_days` on `subscription_data` in a Checkout Session, or on the
+subscription directly. After trial ends Stripe automatically charges unless cancelled.
+
+## Webhook events to handle
+
+| Event | Action |
+| ----- | ------ |
+| `customer.subscription.created` | Provision access |
+| `customer.subscription.updated` | Reflect plan change |
+| `customer.subscription.deleted` | Revoke access |
+| `invoice.payment_succeeded` | Extend access period |
+| `invoice.payment_failed` | Send dunning notification |
+
+Always verify webhook signatures — see [reference/security.md](security.md).
+
+## Traps to avoid
+
+- Never hardcode `payment_method_types` on a subscription Checkout Session.
+- Never build manual renewal loops with raw PaymentIntents.
+- Never skip tax setup for multi-jurisdiction merchants — add registrations before
+  enabling `automatic_tax`.
+- Don't use the deprecated `plan` object; use `Price` instead.