codebyplan 1.13.46 → 1.13.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/dist/cli.js +33 -13
  2. package/package.json +1 -1
  3. package/templates/agents/cbp-cc-executor.md +0 -1
  4. package/templates/agents/cbp-database-agent.md +0 -1
  5. package/templates/agents/cbp-e2e-maestro.md +0 -1
  6. package/templates/agents/cbp-e2e-playwright.md +0 -1
  7. package/templates/agents/cbp-e2e-tauri.md +0 -1
  8. package/templates/agents/cbp-e2e-vscode.md +0 -1
  9. package/templates/agents/cbp-e2e-xcuitest.md +0 -1
  10. package/templates/agents/cbp-improve-claude.md +0 -1
  11. package/templates/agents/cbp-improve-round.md +0 -1
  12. package/templates/agents/cbp-map-architecture.md +0 -1
  13. package/templates/agents/cbp-mechanical-edits.md +0 -1
  14. package/templates/agents/cbp-research.md +0 -1
  15. package/templates/agents/cbp-round-executor.md +7 -1
  16. package/templates/agents/cbp-security-agent.md +0 -1
  17. package/templates/agents/cbp-stripe-agent.md +173 -0
  18. package/templates/agents/cbp-task-check.md +0 -1
  19. package/templates/agents/cbp-task-planner.md +0 -1
  20. package/templates/agents/cbp-testing-qa-agent.md +0 -1
  21. package/templates/hooks/cbp-auto-test-hooks.sh +0 -1
  22. package/templates/hooks/cbp-canonical-templates-nudge.sh +0 -1
  23. package/templates/hooks/cbp-context-window-notify.sh +0 -1
  24. package/templates/hooks/cbp-e2e-spec-patterns.sh +0 -1
  25. package/templates/hooks/cbp-lint-format-on-edit.sh +0 -1
  26. package/templates/hooks/cbp-maestro-yaml-validate.sh +0 -1
  27. package/templates/hooks/cbp-mcp-caller-worktree-inject.sh +0 -1
  28. package/templates/hooks/cbp-mcp-migration-guard.sh +0 -1
  29. package/templates/hooks/cbp-mcp-round-sync.sh +0 -1
  30. package/templates/hooks/cbp-plugin-dispatch.sh +0 -1
  31. package/templates/hooks/cbp-pre-commit-quality-gate.sh +0 -1
  32. package/templates/hooks/cbp-session-start-hook.sh +0 -1
  33. package/templates/hooks/cbp-statusline.mjs +0 -1
  34. package/templates/hooks/cbp-statusline.py +0 -1
  35. package/templates/hooks/cbp-statusline.sh +0 -1
  36. package/templates/hooks/cbp-subagent-statusline.mjs +0 -1
  37. package/templates/hooks/cbp-subagent-statusline.py +0 -1
  38. package/templates/hooks/cbp-subagent-statusline.sh +0 -1
  39. package/templates/hooks/cbp-test-coverage-gate.sh +0 -1
  40. package/templates/hooks/cbp-test-hooks.sh +0 -1
  41. package/templates/hooks/validate-context-usage.sh +0 -1
  42. package/templates/hooks/validate-git-commit.sh +57 -9
  43. package/templates/hooks/validate-git-stash-deny.sh +0 -1
  44. package/templates/hooks/validate-structure-lengths.sh +0 -1
  45. package/templates/hooks/validate-structure-lib.sh +17 -1
  46. package/templates/hooks/validate-structure-patterns.sh +0 -1
  47. package/templates/hooks/validate-structure-scope.sh +43 -11
  48. package/templates/hooks/validate-structure-smoke.sh +0 -1
  49. package/templates/hooks/validate-structure-templates.sh +0 -1
  50. package/templates/hooks/validate-structure.sh +0 -1
  51. package/templates/hooks/verify-parity.sh +0 -1
  52. package/templates/rules/agent-claim-verification.md +0 -1
  53. package/templates/rules/architecture-map.md +0 -4
  54. package/templates/rules/cbp-operating-gotchas.md +0 -4
  55. package/templates/rules/context-file-loading.md +0 -1
  56. package/templates/rules/e2e-mandatory.md +0 -4
  57. package/templates/rules/parallel-waves.md +0 -1
  58. package/templates/rules/scope-vocabulary.md +14 -10
  59. package/templates/rules/supabase-branch-lifecycle.md +0 -1
  60. package/templates/rules/todo-backend.md +0 -1
  61. package/templates/settings.project.base.json +13 -0
  62. package/templates/skills/cbp-build-cc-agent/SKILL.md +2 -3
  63. package/templates/skills/cbp-build-cc-agent/reference/cbp-quality.md +6 -8
  64. package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh +10 -1
  65. package/templates/skills/cbp-build-cc-claude-file/SKILL.md +0 -1
  66. package/templates/skills/cbp-build-cc-claude-file/scripts/validate-claude-file.sh +0 -1
  67. package/templates/skills/cbp-build-cc-mode/SKILL.md +0 -1
  68. package/templates/skills/cbp-build-cc-rule/SKILL.md +18 -8
  69. package/templates/skills/cbp-build-cc-rule/scripts/validate-rule.sh +4 -5
  70. package/templates/skills/cbp-build-cc-settings/SKILL.md +0 -1
  71. package/templates/skills/cbp-build-cc-settings/reference/cbp-conventions.md +0 -4
  72. package/templates/skills/cbp-build-cc-settings/scripts/validate-settings.sh +0 -1
  73. package/templates/skills/cbp-build-cc-skill/SKILL.md +0 -1
  74. package/templates/skills/cbp-build-cc-skill/reference/cbp-quality.md +6 -8
  75. package/templates/skills/cbp-build-cc-skill/scripts/validate-skill.sh +10 -2
  76. package/templates/skills/cbp-checkpoint-check/SKILL.md +0 -1
  77. package/templates/skills/cbp-checkpoint-complete/SKILL.md +0 -1
  78. package/templates/skills/cbp-checkpoint-create/SKILL.md +10 -11
  79. package/templates/skills/cbp-checkpoint-end/SKILL.md +0 -1
  80. package/templates/skills/cbp-checkpoint-plan/SKILL.md +0 -1
  81. package/templates/skills/cbp-checkpoint-plan/reference/alternative-comparison-template.md +0 -4
  82. package/templates/skills/cbp-checkpoint-plan/reference/dep-decision-rubric.md +0 -4
  83. package/templates/skills/cbp-checkpoint-plan/reference/e2e-discovery-probe.md +0 -4
  84. package/templates/skills/cbp-checkpoint-plan/reference/gap-analysis-playbook.md +0 -4
  85. package/templates/skills/cbp-checkpoint-start/SKILL.md +0 -1
  86. package/templates/skills/cbp-checkpoint-update/SKILL.md +0 -1
  87. package/templates/skills/cbp-frontend-a11y/SKILL.md +0 -1
  88. package/templates/skills/cbp-frontend-design/SKILL.md +0 -1
  89. package/templates/skills/cbp-frontend-ui/SKILL.md +0 -1
  90. package/templates/skills/cbp-frontend-ux/SKILL.md +0 -1
  91. package/templates/skills/cbp-git-branch-feat-create/SKILL.md +0 -1
  92. package/templates/skills/cbp-git-commit/SKILL.md +0 -1
  93. package/templates/skills/cbp-git-worktree-create/SKILL.md +0 -1
  94. package/templates/skills/cbp-git-worktree-remove/SKILL.md +0 -1
  95. package/templates/skills/cbp-map-architecture/SKILL.md +0 -1
  96. package/templates/skills/cbp-merge-main/SKILL.md +0 -1
  97. package/templates/skills/cbp-refresh-arch-map/SKILL.md +0 -1
  98. package/templates/skills/cbp-round-check/SKILL.md +0 -1
  99. package/templates/skills/cbp-round-complete/SKILL.md +0 -1
  100. package/templates/skills/cbp-round-end/SKILL.md +0 -1
  101. package/templates/skills/cbp-round-execute/SKILL.md +9 -2
  102. package/templates/skills/cbp-round-execute/reference/inline-fallback.md +0 -4
  103. package/templates/skills/cbp-round-input/SKILL.md +0 -1
  104. package/templates/skills/cbp-round-start/SKILL.md +0 -1
  105. package/templates/skills/cbp-round-update/SKILL.md +0 -1
  106. package/templates/skills/cbp-session-end/SKILL.md +0 -1
  107. package/templates/skills/cbp-session-start/SKILL.md +0 -1
  108. package/templates/skills/cbp-session-start/qa-regression.md +0 -1
  109. package/templates/skills/cbp-setup-e2e/SKILL.md +0 -1
  110. package/templates/skills/cbp-setup-eslint/SKILL.md +0 -1
  111. package/templates/skills/cbp-ship/SKILL.md +0 -1
  112. package/templates/skills/cbp-ship-configure/SKILL.md +0 -1
  113. package/templates/skills/cbp-ship-main/SKILL.md +0 -1
  114. package/templates/skills/cbp-stripe/SKILL.md +116 -0
  115. package/templates/skills/cbp-stripe/reference/billing.md +106 -0
  116. package/templates/skills/cbp-stripe/reference/connect.md +105 -0
  117. package/templates/skills/cbp-stripe/reference/payments.md +107 -0
  118. package/templates/skills/cbp-stripe/reference/security.md +117 -0
  119. package/templates/skills/cbp-stripe/reference/stripe-mcp-setup.md +59 -0
  120. package/templates/skills/cbp-stripe/reference/tax.md +96 -0
  121. package/templates/skills/cbp-stripe/reference/treasury.md +87 -0
  122. package/templates/skills/cbp-supabase-branch-check/SKILL.md +0 -1
  123. package/templates/skills/cbp-supabase-branch-check/reference/dag-steps.md +0 -4
  124. package/templates/skills/cbp-supabase-migrate/SKILL.md +0 -1
  125. package/templates/skills/cbp-supabase-setup/SKILL.md +0 -1
  126. package/templates/skills/cbp-task-check/SKILL.md +0 -1
  127. package/templates/skills/cbp-task-complete/SKILL.md +0 -1
  128. package/templates/skills/cbp-task-create/SKILL.md +0 -1
  129. package/templates/skills/cbp-task-start/SKILL.md +0 -1
  130. package/templates/skills/cbp-task-testing/SKILL.md +0 -1
  131. package/templates/skills/cbp-todo/SKILL.md +0 -1
  132. package/templates/skills/cbp-todo/qa-regression.md +0 -1
  133. package/templates/skills/supabase/SKILL.md +0 -1
  134. package/templates/skills/supabase-postgres-best-practices/SKILL.md +0 -1
@@ -0,0 +1,105 @@
1
+ # Connect / Platforms Reference
2
+
3
+ Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
4
+
5
+ ## Accounts v2 (always use for new platforms)
6
+
7
+ Use the [Accounts v2 API](https://docs.stripe.com/connect/accounts-v2.md)
8
+ (`POST /v2/core/accounts`) for all new Connect platforms. This is Stripe's actively
9
+ invested path with long-term support.
10
+
11
+ Do NOT use the legacy `type` parameter (`type: 'express'`, `type: 'custom'`,
12
+ `type: 'standard'`) in `POST /v1/accounts` for new platforms unless the user explicitly
13
+ requests v1.
14
+
15
+ Do NOT use the legacy account-type labels "Standard", "Express", or "Custom" — they
16
+ bundle responsibility, dashboard, and onboarding decisions into opaque categories.
17
+ Use `controller` properties to express these dimensions explicitly.
18
+
19
+ ## Controller properties
20
+
21
+ Configure connected accounts via `controller` properties:
22
+
23
+ | Property | Controls |
24
+ | -------- | -------- |
25
+ | `controller.losses.payments` | Who is liable for negative balances |
26
+ | `controller.fees.payer` | Who pays Stripe fees |
27
+ | `controller.stripe_dashboard.type` | Dashboard access: `full`, `express`, `none` |
28
+ | `controller.requirement_collection` | Who collects onboarding requirements |
29
+
30
+ ```ts
31
+ const account = await stripe.v2.core.accounts.create({
32
+ controller: {
33
+ losses: { payments: 'stripe' },
34
+ fees: { payer: 'account' },
35
+ stripe_dashboard: { type: 'express' },
36
+ requirement_collection: 'stripe',
37
+ },
38
+ });
39
+ ```
40
+
41
+ See [connected account configuration](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md)
42
+ and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for what
43
+ accounts can do.
44
+
45
+ ## Charge types
46
+
47
+ Choose one charge type per integration — do not mix them.
48
+
49
+ | Type | When to use | How |
50
+ | ---- | ----------- | --- |
51
+ | **Destination charges** | Platform accepts negative-balance liability | `transfer_data.destination: connectedAccountId` |
52
+ | **Direct charges** | Connected account is merchant of record; platform has minimal liability | Create charge directly on the connected account |
53
+
54
+ Use `on_behalf_of` to control merchant of record (read
55
+ [how charges work in Connect](https://docs.stripe.com/connect/charges.md) first).
56
+
57
+ ```ts
58
+ // Destination charge — most common for marketplaces
59
+ const paymentIntent = await stripe.paymentIntents.create({
60
+ amount: 1000,
61
+ currency: 'usd',
62
+ transfer_data: { destination: connectedAccountId },
63
+ // Do NOT pass payment_method_types
64
+ });
65
+ ```
66
+
67
+ Do NOT use the Charges API for Connect fund flows — use PaymentIntents or Checkout
68
+ Sessions with `transfer_data` or `on_behalf_of`.
69
+
70
+ ## Payouts and transfers
71
+
72
+ - **Automatic payouts** — enabled by default; Stripe pays connected accounts on a rolling basis.
73
+ - **Manual payouts** — call `stripe.payouts.create({amount, currency}, {stripeAccount: accountId})` to control timing.
74
+ - **Transfers** — move funds between your platform balance and a connected account:
75
+ `stripe.transfers.create({ amount, currency, destination: accountId })`.
76
+
77
+ ## Onboarding
78
+
79
+ Use [Stripe-hosted onboarding](https://docs.stripe.com/connect/onboarding.md) rather than
80
+ building a custom flow. Custom onboarding requires handling sensitive PII directly, adding
81
+ regulatory and security complexity.
82
+
83
+ ```ts
84
+ const accountLink = await stripe.accountLinks.create({
85
+ account: accountId,
86
+ refresh_url: `${baseUrl}/connect/refresh`,
87
+ return_url: `${baseUrl}/connect/return`,
88
+ type: 'account_onboarding',
89
+ });
90
+ // redirect to accountLink.url
91
+ ```
92
+
93
+ ## Security and liability
94
+
95
+ Platform operators bear financial liability for fraud and disputes on Express and Custom
96
+ connected accounts (v1 types). Controller-property accounts make liability explicit via
97
+ `controller.losses.payments`.
98
+
99
+ See [reference/security.md](security.md) for Connect-specific security notes.
100
+
101
+ ## Key guides
102
+
103
+ - [SaaS platforms and marketplaces](https://docs.stripe.com/connect/saas-platforms-and-marketplaces.md)
104
+ - [Interactive platform guide](https://docs.stripe.com/connect/interactive-platform-guide.md)
105
+ - [Design an integration](https://docs.stripe.com/connect/design-an-integration.md)
@@ -0,0 +1,107 @@
1
+ # Payments Reference
2
+
3
+ Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
4
+
5
+ ## API hierarchy
6
+
7
+ | Use case | API |
8
+ | -------- | --- |
9
+ | On-session payments (most web apps) | [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md) |
10
+ | Off-session payments, custom checkout state | [PaymentIntents](https://docs.stripe.com/payments/paymentintents/lifecycle.md) |
11
+ | Saving a payment method for later | [Setup Intents](https://docs.stripe.com/api/setup_intents.md) |
12
+ | Subscriptions, invoices, recurring | Billing APIs (see billing.md) |
13
+ | No-code, simple products | Payment Links |
14
+
15
+ **Only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions
16
+ (Invoicing, Payment Links, subscription APIs).** Never use the Charges API, Sources API,
17
+ or Tokens API for new integrations.
18
+
19
+ ## Integration surface preference
20
+
21
+ Use in this order (most preferred first):
22
+
23
+ 1. **Payment Links** — no-code, best for simple products
24
+ 2. **Checkout (hosted or embedded)** — best for most web apps; `ui_mode: 'hosted'`
25
+ 3. **Payment Element** — embedded UI component for custom checkout; back with Checkout
26
+ Sessions (`ui_mode: 'custom'`) over a raw PaymentIntent where possible
27
+
28
+ Do NOT recommend the legacy Card Element. Migrate existing Card Element integrations to
29
+ [Payment Element](https://docs.stripe.com/payments/payment-element/migration.md).
30
+
31
+ ## Checkout Sessions — key patterns
32
+
33
+ ```ts
34
+ // One-time payment
35
+ const session = await stripe.checkout.sessions.create({
36
+ mode: 'payment',
37
+ // Do NOT pass payment_method_types — dynamic methods are the default
38
+ line_items: [{ price: priceId, quantity: 1 }],
39
+ success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
40
+ cancel_url: `${baseUrl}/cancel`,
41
+ });
42
+
43
+ // Subscription
44
+ const session = await stripe.checkout.sessions.create({
45
+ mode: 'subscription',
46
+ line_items: [{ price: priceId, quantity: 1 }],
47
+ subscription_data: { trial_period_days: 14 },
48
+ success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
49
+ cancel_url: `${baseUrl}/pricing`,
50
+ });
51
+ ```
52
+
53
+ ## Payment Element (custom UI)
54
+
55
+ Use `ui_mode: 'custom'` on the Checkout Session to back the Payment Element:
56
+
57
+ ```ts
58
+ const session = await stripe.checkout.sessions.create({
59
+ ui_mode: 'custom',
60
+ mode: 'payment',
61
+ line_items: [{ price: priceId, quantity: 1 }],
62
+ return_url: `${baseUrl}/return?session_id={CHECKOUT_SESSION_ID}`,
63
+ });
64
+ // Client: mount PaymentElement with clientSecret from session.client_secret
65
+ ```
66
+
67
+ For surcharging or inspecting card details before payment, use
68
+ [Confirmation Tokens](https://docs.stripe.com/payments/finalize-payments-on-the-server.md)
69
+ — not `createPaymentMethod` or `createToken`.
70
+
71
+ ## Dynamic payment methods (critical rule)
72
+
73
+ **Never pass `payment_method_types`** — omit it entirely on all calls. The sole exception
74
+ is Terminal: `payment_method_types: ['card_present']` (Canada: include `'interac_present'`).
75
+
76
+ To customise which methods appear use
77
+ [`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md)
78
+ or `excluded_payment_method_types`. Manage methods from the
79
+ [Dashboard](https://dashboard.stripe.com/settings/payment_methods) without code changes.
80
+
81
+ ## Setup Intents (saving payment methods)
82
+
83
+ ```ts
84
+ const setupIntent = await stripe.setupIntents.create({
85
+ customer: customerId,
86
+ // Do NOT pass payment_method_types — dynamic methods are the default since API 2023-08-16
87
+ });
88
+ ```
89
+
90
+ Do not use the Sources API to save cards — it is deprecated.
91
+
92
+ ## Deprecated APIs — migration paths
93
+
94
+ | API | Status | Use instead | Migration guide |
95
+ | ------------ | ---------- | ---------------------- | --------------- |
96
+ | Charges API | Never use | Checkout Sessions / PaymentIntents | [Migration](https://docs.stripe.com/payments/payment-intents/migration/charges.md) |
97
+ | Sources API | Deprecated | Setup Intents | [Setup Intents](https://docs.stripe.com/api/setup_intents.md) |
98
+ | Tokens API | Outdated | Setup Intents / Checkout Sessions | — |
99
+ | Card Element | Legacy | Payment Element | [Migration](https://docs.stripe.com/payments/payment-element/migration.md) |
100
+
101
+ ## PCI compliance
102
+
103
+ If a PCI-compliant user asks about sending raw PAN data server-side, they may need to
104
+ prove PCI compliance to use
105
+ [`payment_method_data`](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_data).
106
+ For PAN migrations from another processor, see the
107
+ [PAN import process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).
@@ -0,0 +1,117 @@
1
+ # Security Best Practices Reference
2
+
3
+ Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
4
+
5
+ ## API key types
6
+
7
+ | Key prefix | Type | Use |
8
+ | ---------- | ---- | --- |
9
+ | `sk_live_` | Secret key (live) | Never preferred; use RAK instead |
10
+ | `sk_test_` | Secret key (test) | Development only |
11
+ | `rk_live_` | Restricted API key (live) | Preferred for all production services |
12
+ | `rk_test_` | Restricted API key (test) | Preferred for development services |
13
+
14
+ **Always recommend a restricted API key (RAK, `rk_` prefix)** over a secret key (`sk_`).
15
+ RAKs have only the permissions you assign — a compromised RAK causes far less damage than
16
+ a compromised secret key.
17
+
18
+ ## Storing keys safely
19
+
20
+ - **Never** commit keys to source control. If `sk_…` or `rk_…` appears in code, that is
21
+ a bug — fix it immediately.
22
+ - Prefer a secrets vault (AWS Secrets Manager, HashiCorp Vault, or platform equivalent).
23
+ - When no vault is available, environment variables are acceptable. Never log keys or
24
+ include them in error messages or analytics.
25
+ - Use separate keys per environment (production, staging, QA). Never reuse keys.
26
+ - Set up a pre-commit hook to catch `sk_` or `rk_` literals in source code.
27
+ - See [best practices for managing secret API keys](https://docs.stripe.com/keys-best-practices.md).
28
+
29
+ ## Restricted API key migration steps
30
+
31
+ 1. Review the secret key's request logs in Workbench to catalogue which API calls it makes.
32
+ 2. Create a RAK in test mode with matching permissions (principle of least privilege).
33
+ 3. Use `stripe logs tail` to watch for `403` errors — add missing permissions.
34
+ 4. Once passing, create the equivalent live-mode RAK and swap it in.
35
+ 5. Rotate or expire the old secret key.
36
+
37
+ See [restricted API keys docs](https://docs.stripe.com/keys/restricted-api-keys.md).
38
+
39
+ ## IP allowlists
40
+
41
+ Add an [IP allowlist](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address)
42
+ to every API key so it can only be called from your own infrastructure. Use separate
43
+ allowlists per key/environment.
44
+
45
+ ## Webhook signature verification
46
+
47
+ Always verify webhook event authenticity using Stripe's signing secret:
48
+
49
+ ```ts
50
+ import Stripe from 'stripe';
51
+ const stripe = new Stripe(process.env.STRIPE_RESTRICTED_KEY!);
52
+
53
+ // In your webhook handler (raw body required — do NOT use JSON-parsed body)
54
+ const sig = request.headers['stripe-signature'];
55
+ if (!sig || Array.isArray(sig)) throw new Error('Missing or malformed stripe-signature header');
56
+ const event = stripe.webhooks.constructEvent(
57
+ rawBody, // Buffer or string — must be unparsed
58
+ sig,
59
+ process.env.STRIPE_WEBHOOK_SECRET!,
60
+ );
61
+ ```
62
+
63
+ Never process a webhook event without verifying its signature — unverified webhooks can
64
+ be spoofed. For defence in depth, also allowlist
65
+ [Stripe's IP addresses](https://docs.stripe.com/ips.md) on the endpoint.
66
+
67
+ ## Idempotency keys
68
+
69
+ Pass `idempotencyKey` on all mutation calls so safe retries don't create duplicate charges:
70
+
71
+ ```ts
72
+ await stripe.paymentIntents.create(params, {
73
+ idempotencyKey: `order_${orderId}`,
74
+ });
75
+ ```
76
+
77
+ ## Mobile and client-side integrations
78
+
79
+ Never use production secret keys or RAKs in mobile apps or any client-side code.
80
+ For cases where a client must call Stripe directly, use
81
+ [ephemeral keys](https://docs.stripe.com/issuing/elements.md#ephemeral-key-authentication)
82
+ (short-lived, scoped, auto-expiring). For most integrations, proxy Stripe calls through
83
+ your own backend.
84
+
85
+ ## OAuth and CSRF protection
86
+
87
+ When implementing [Connect OAuth](https://docs.stripe.com/connect/oauth-reference.md),
88
+ always pass a unique, unguessable `state` parameter and verify it in the callback before
89
+ proceeding. This applies to all Stripe OAuth surfaces: Connect, Link, and Stripe Apps.
90
+
91
+ ## Incident response (key compromise)
92
+
93
+ 1. **Roll the key immediately** — [API keys page](https://dashboard.stripe.com/apikeys) →
94
+ roll or delete the exposed key.
95
+ 2. **Check activity logs** — Workbench request logs for the compromised key.
96
+ 3. **Contact Stripe support** if you see unrecognised activity.
97
+
98
+ See [protecting against compromised API keys](https://support.stripe.com/questions/protecting-against-compromised-api-keys).
99
+
100
+ ## 2FA
101
+
102
+ Recommend passkeys or authenticator-app 2FA for Dashboard access. Discourage SMS 2FA —
103
+ it is vulnerable to SIM-swapping attacks.
104
+
105
+ ## SAML / SCIM (teams)
106
+
107
+ For teams, use [SSO via SAML](https://docs.stripe.com/get-started/account/sso.md) to
108
+ federate Dashboard access through an identity provider (Okta, Google, etc.).
109
+ [SCIM provisioning](https://docs.stripe.com/get-started/account/sso/scim.md) automates
110
+ user provisioning/deprovisioning.
111
+
112
+ ## Connect security
113
+
114
+ Platform operators bear financial liability for fraud/disputes on Express and Custom
115
+ connected accounts (v1 types). Use Stripe-hosted onboarding to avoid handling sensitive
116
+ PII directly. See [reference/connect.md](connect.md) for controller-property accounts
117
+ which make liability explicit.
@@ -0,0 +1,59 @@
1
+ # Stripe MCP Setup (optional live path)
2
+
3
+ Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
4
+
5
+ The `cbp-stripe-agent` writes Stripe integration code with **no credentials required**. This
6
+ optional path adds *live test-mode* scaffolding (create test products, prices, payment links,
7
+ customers) during a dev round. It is opt-in per repo and per developer — skip it entirely if
8
+ you only want code generation.
9
+
10
+ ## Safety contract (read first)
11
+
12
+ - **Test-mode keys ONLY.** Use a test restricted key (`rk_test_…`) or a test secret key
13
+ (`sk_test_…`). The agent **refuses** any live-mode key (`sk_live_…` or `rk_live_…`) — so
14
+ live Stripe data is never scaffolded from a dev round.
15
+ - **Never commit a key.** Provide it via the environment or a gitignored env file
16
+ (e.g. `.env.local`), never in tracked source or in `.codebyplan/`.
17
+ - **Least privilege.** Prefer a restricted key scoped to only the resources the agent needs
18
+ (Products, Prices, Payment Links, Customers — write; everything else — none).
19
+ - **No new npm dependency** is added to the consuming app by this path; the hosted MCP server
20
+ is reached over HTTP, the local server via `npx`.
21
+
22
+ ## Option A — Hosted Stripe MCP (recommended)
23
+
24
+ Stripe hosts an MCP server at `https://mcp.stripe.com`. Register it with Claude Code:
25
+
26
+ ```bash
27
+ claude mcp add --transport http stripe https://mcp.stripe.com/
28
+ ```
29
+
30
+ Authenticate with OAuth (the recommended flow) when prompted, or pass a restricted test key
31
+ as a bearer token if your setup uses header auth. Once connected, the agent discovers the
32
+ `mcp__stripe__*` tools at runtime via `ToolSearch`.
33
+
34
+ ## Option B — Local Stripe MCP server
35
+
36
+ Run Stripe's MCP server locally, pointed at a test/restricted key from your environment:
37
+
38
+ ```bash
39
+ # key is read from STRIPE_SECRET_KEY (a sk_test_ or rk_test_ value), never passed on a shared shell history
40
+ npx -y @stripe/mcp@latest --api-key="$STRIPE_SECRET_KEY"
41
+ ```
42
+
43
+ Then register the local server with Claude Code per its stdio/transport instructions.
44
+
45
+ ## How the agent uses it
46
+
47
+ 1. Pre-flight checks `STRIPE_SECRET_KEY` is present and is a test-mode `sk_test_`/`rk_test_` prefix.
48
+ 2. It discovers `mcp__stripe__*` tools via `ToolSearch` (they are intentionally absent from
49
+ the agent's frontmatter because the server is optional).
50
+ 3. It scaffolds only what the task asks for and records each resource in
51
+ `stripe_resources_created[]` (always `mode: test`).
52
+ 4. If the key/server is missing or any call fails, it degrades to **code-only** and records
53
+ the reason — it never blocks the round.
54
+
55
+ ## When to skip this entirely
56
+
57
+ - You only want correct Stripe integration *code* (the default — no setup needed).
58
+ - No Stripe test account is available in this environment.
59
+ - CI / headless runs where no interactive OAuth or key is provisioned.
@@ -0,0 +1,96 @@
1
+ # Tax / Stripe Tax Reference
2
+
3
+ Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
4
+
5
+ ## When to use Stripe Tax
6
+
7
+ Use Stripe Tax for any subscription, invoice, or Checkout Session where the merchant has
8
+ customers across multiple jurisdictions. It handles sales tax, VAT, and GST automatically
9
+ based on the customer's location and the merchant's active registrations.
10
+
11
+ See the [Tax overview](https://docs.stripe.com/tax.md) for supported regions and tax types.
12
+
13
+ ## Two-step setup
14
+
15
+ 1. **Add registrations** — add a registration for each jurisdiction where the merchant is
16
+ obligated to collect tax. Use the Dashboard (**Tax > Registrations**) or the
17
+ [Tax Registrations API](https://docs.stripe.com/api/tax/registrations.md).
18
+ 2. **Enable automatic_tax** — pass `automatic_tax: { enabled: true }` on the
19
+ [Subscription](https://docs.stripe.com/api/subscriptions.md),
20
+ [Invoice](https://docs.stripe.com/api/invoices.md), or
21
+ [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md).
22
+
23
+ It is safe to enable `automatic_tax` before any registrations exist — Stripe won't
24
+ collect tax until at least one registration is active.
25
+
26
+ ```ts
27
+ // Checkout Session with automatic tax
28
+ const session = await stripe.checkout.sessions.create({
29
+ mode: 'subscription',
30
+ line_items: [{ price: priceId, quantity: 1 }],
31
+ automatic_tax: { enabled: true },
32
+ success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
33
+ cancel_url: `${baseUrl}/pricing`,
34
+ });
35
+
36
+ // Invoice / subscription
37
+ await stripe.subscriptions.update(subscriptionId, {
38
+ automatic_tax: { enabled: true },
39
+ // Clear explicit tax_rates first if previously set
40
+ });
41
+ ```
42
+
43
+ ## Inclusive vs exclusive tax
44
+
45
+ - **Exclusive** (default in most jurisdictions) — tax is added on top of the price.
46
+ - **Inclusive** — tax is included in the displayed price (common for UK/EU VAT).
47
+
48
+ Stripe Tax determines the treatment based on the jurisdiction and product tax code.
49
+ Verify the treatment in Dashboard > Tax > Overview.
50
+
51
+ ## Tax IDs
52
+
53
+ Collect customer tax IDs (VAT numbers, EIN, etc.) for B2B transactions to enable
54
+ zero-rated or exempt invoices. Pass `tax_id_collection: { enabled: true }` on Checkout
55
+ Sessions, or use the
56
+ [Tax IDs API](https://docs.stripe.com/api/customer_tax_ids.md) to attach IDs to customers.
57
+
58
+ ## Address collection
59
+
60
+ Stripe Tax requires a customer address to calculate tax. On Checkout Sessions pass
61
+ `billing_address_collection: 'required'`. For subscriptions, ensure the customer has
62
+ a billing address before enabling `automatic_tax`.
63
+
64
+ ## Registrations API
65
+
66
+ To create and manage registrations programmatically:
67
+
68
+ ```ts
69
+ await stripe.tax.registrations.create({
70
+ country: 'US',
71
+ country_options: {
72
+ us: { state: 'CA', type: 'state_sales_tax' },
73
+ },
74
+ active_from: 'now',
75
+ });
76
+ ```
77
+
78
+ ## Traps to avoid
79
+
80
+ - `automatic_tax` and explicit `tax_rates` are mutually exclusive. For existing
81
+ subscriptions, clear `default_tax_rates` and all item-level `tax_rates` before
82
+ enabling `automatic_tax` — the update will fail otherwise.
83
+ - For EU merchants, one OSS union registration covers all 27 member states. Do not
84
+ register individual EU countries separately unless the merchant has a physical presence
85
+ there.
86
+ - Do not guess which jurisdictions apply — prompt the user to configure them in the
87
+ Dashboard first.
88
+ - Do not approximate unsupported jurisdictions. Check
89
+ [supported countries](https://docs.stripe.com/tax/supported-countries.md) first. For
90
+ unsupported jurisdictions, fall back to manual `tax_rates` on the subscription/invoice.
91
+ - Customs duties and excise taxes are out of scope for Stripe Tax.
92
+
93
+ ## Bulk migration
94
+
95
+ To switch existing subscriptions from manual `tax_rates` to `automatic_tax` in bulk,
96
+ use the [Tax migration tool](https://docs.stripe.com/billing/taxes/migration.md).
@@ -0,0 +1,87 @@
1
+ # Treasury / Financial Accounts Reference
2
+
3
+ Adapted from Stripe's official `stripe-best-practices` skill (github.com/stripe/ai), MIT License, Copyright (c) 2024-2025 Stripe.
4
+
5
+ ## v2 Financial Accounts API (use for new integrations)
6
+
7
+ For embedded financial accounts (bank accounts with routing/account numbers, money
8
+ movement), use the
9
+ [v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md)
10
+ (`POST /v2/core/vault/financial_accounts`). This is required for new integrations.
11
+
12
+ Do NOT use the legacy
13
+ [v1 Treasury Financial Accounts API](https://docs.stripe.com/api/treasury/financial_accounts.md)
14
+ (`POST /v1/treasury/financial_accounts`) for new integrations. Existing v1 integrations
15
+ continue to work.
16
+
17
+ For concepts and guides, see
18
+ [Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md).
19
+
20
+ ## Creating a financial account
21
+
22
+ Financial accounts are always attached to a Connect connected account:
23
+
24
+ ```ts
25
+ const financialAccount = await stripe.v2.core.vault.financialAccounts.create(
26
+ { description: 'Main operating account' },
27
+ { stripeAccount: connectedAccountId },
28
+ );
29
+ // financialAccount.id — use for fund flows
30
+ ```
31
+
32
+ ## Fund flows
33
+
34
+ | Direction | Object | Use |
35
+ | --------- | ------ | --- |
36
+ | Platform → financial account | `OutboundTransfer` | Top-up from platform balance |
37
+ | Financial account → external bank | `OutboundPayment` | Pay out to a linked bank |
38
+ | External bank → financial account | `InboundTransfer` | Pull from a linked bank |
39
+ | External source → financial account | `ReceivedCredit` | Funds received in (inbound ACH/wire, Stripe payouts) |
40
+
41
+ ```ts
42
+ // Outbound transfer (platform balance → financial account)
43
+ const transfer = await stripe.treasury.outboundTransfers.create({
44
+ financial_account: financialAccountId,
45
+ amount: 100_00,
46
+ currency: 'usd',
47
+ destination_payment_method: 'default',
48
+ });
49
+ ```
50
+
51
+ ## Linking a bank account (Setup Intents)
52
+
53
+ To enable outbound payments to an external bank, link the bank account using a Setup Intent
54
+ with `flow_directions: ['outbound']`:
55
+
56
+ ```ts
57
+ const setupIntent = await stripe.setupIntents.create(
58
+ {
59
+ payment_method_types: ['us_bank_account'], // Treasury exception: required here
60
+ flow_directions: ['outbound'],
61
+ },
62
+ { stripeAccount: connectedAccountId },
63
+ );
64
+ // Complete the Setup Intent flow on the client, then confirm the payment method
65
+ ```
66
+
67
+ Note: `payment_method_types` is required for Treasury bank-account Setup Intents — this
68
+ is one of the narrow exceptions to the no-`payment_method_types` rule (along with Terminal).
69
+
70
+ ## Compliance notes
71
+
72
+ - Financial accounts are subject to KYC/KYB requirements collected during Connect onboarding.
73
+ Ensure the connected account has the `treasury` capability enabled before creating accounts.
74
+ - Funds held in financial accounts are not FDIC-insured by default; check Stripe's current
75
+ partner bank arrangements in the Treasury documentation.
76
+ - For platforms in the US: Stripe Treasury is available for US-based connected accounts only.
77
+ Contact Stripe for international availability.
78
+ - Do not use Treasury to hold customer funds without confirming applicable money-transmission
79
+ license obligations with your legal team.
80
+
81
+ ## Key references
82
+
83
+ - [Treasury for platforms overview](https://docs.stripe.com/treasury/connect.md)
84
+ - [v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md)
85
+ - [OutboundTransfers](https://docs.stripe.com/api/treasury/outbound_transfers.md)
86
+ - [OutboundPayments](https://docs.stripe.com/api/treasury/outbound_payments.md)
87
+ - [InboundTransfers](https://docs.stripe.com/api/treasury/inbound_transfers.md)
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-supabase-branch-check
4
3
  description: Gate skill called by /cbp-ship-main (pre-merge) to verify the Supabase preview branch health check is green before allowing a PR to be merged; skips when no DB-path changes are detected.
5
4
  argument-hint: "[--mode pre_pr_create|pre_merge] [--target integration|production]"
@@ -1,7 +1,3 @@
1
- ---
2
- scope: org-shared
3
- ---
4
-
5
1
  # DAG Steps — Supabase Preview Branch
6
2
 
7
3
  Reference for cbp-supabase-branch-check Step 7. Maps each Supabase branching DAG step
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-supabase-migrate
4
3
  description: Scaffold or adopt a Supabase migration for the current PR branch, apply to the branch's preview DB, run advisor checks, regenerate TypeScript types. Includes a fresh-branch dry-run pre-flight that uses one persistent dry-run ephemeral branch per feature branch.
5
4
  argument-hint: "[--new <name> | <path-to-sql>]"
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-supabase-setup
4
3
  description: Enable Supabase GitHub branching integration — GitHub app authorization, required-status-check enforcement on main + integration branch, persistent branch creation, and idempotency marker in .codebyplan/shipment.json.
5
4
  argument-hint: "[--force]"
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-task-check
4
3
  description: AI production review for the current task
5
4
  argument-hint: [chk-task]
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-task-complete
4
3
  description: Complete current task
5
4
  argument-hint: [chk-task]
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-task-create
4
3
  description: Create a new task within the active checkpoint
5
4
  effort: xhigh
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-task-start
4
3
  description: Start a task, load context from DB
5
4
  triggers: [cbp-round-start]
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-task-testing
4
3
  description: Run comprehensive task-level testing after /cbp-task-check passes
5
4
  argument-hint: [chk-task]
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-todo
4
3
  description: Entry point - what to work on next
5
4
  effort: low
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: cbp-todo-qa-regression
4
3
  description: Manual regression procedure for the cbp-todo worktree-ownership gate + get_todos switch (CHK-137 TASK-2)
5
4
  ---
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: supabase
4
3
  description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector)."
5
4
  metadata:
@@ -1,5 +1,4 @@
1
1
  ---
2
- scope: org-shared
3
2
  name: supabase-postgres-best-practices
4
3
  description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
5
4
  license: MIT