Setup Stripe - Strict NowStack Billing Setup

<strict_order> This workflow MUST follow this order exactly. Do not reorder, merge, or skip steps unless the user explicitly asks to stop or skip the current step.

1. Preflight: verify Convex config, required files, Stripe SDK availability, and current billing plan shape.
2. API keys: collect STRIPE_SECRET_KEY, set it in Convex env, then run the existing webhook helper to create/update the Convex Stripe webhook and set STRIPE_WEBHOOK_SECRET.
3. Plans and prices: ask for the full plan matrix in one structured response.
4. Code update: update convex/billing/plans.ts and UI-only plan features in src/lib/auth/stripe/auth-plans.ts.
5. Stripe creation: create or reuse Stripe Products and recurring Prices in the user's Stripe account from convex/billing/plans.ts, then write the resulting Price IDs into Convex env.
6. Finish: validate, update CHANGELOG.md, clean temporary files, and summarize. </strict_order>

<interaction_rules>

• Never ask for secrets and plan details in the same message.
• Never write Stripe secrets to .env, .env.local, Vercel env, CHANGELOG.md, or any git-tracked file.
• Do not print full secret values. Mask them as sk_test_...1234 / sk_live_...1234.
• Use request_user_input when available and allowed for checkpoint choices. Plain text is the fallback.
• Keep the user's language for prompts and summaries.
• If the user provides a publishable key, only record whether it was provided. Do not store it unless the codebase actually needs VITE_STRIPE_PUBLISHABLE_KEY. </interaction_rules>

<hard_execution_contract> The agent MUST treat this workflow as a gated state machine, not loose guidance.

Before every step, write a compact state summary:

STRIPE STATE: step={current_step}; waiting_for={none|api_keys|plan_matrix}; completed={comma-separated completed gates}

Rules:

• Never execute a step if its gate is missing. Go back to the step that collects the missing input.
• If user input is needed, ask exactly the requested question, then stop.
• If a command fails, do not skip forward. Fix it, retry when safe, or stop with the blocker.
• If the user changes a previous answer, update state and resume from the earliest affected step.
• If conversation context is compacted or unclear, reconstruct state from SETUP_STRIPE_CHECKLIST.md, local files, and the latest user messages before continuing. </hard_execution_contract>

<checklist_protocol> The agent MUST use a temporary root checklist file to force strict ordering.

Checklist file:

• Runtime path: SETUP_STRIPE_CHECKLIST.md at the project root.
• Template path: .agents/skills/setup-stripe/templates/SETUP_STRIPE_CHECKLIST.md.
• Create it in Step 0 before any setup command if it does not exist.
• Update it before and after every step by checking boxes and filling the state fields.
• Update it with normal file edits; do not overwrite the whole checklist unless creating it from the template.
• At the end, after validation and final summary preparation, delete it with trash SETUP_STRIPE_CHECKLIST.md.
• If trash is unavailable, do not delete files; tell the user cleanup could not run. </checklist_protocol>

<stop_gates> These are mandatory stop points:

<gate_matrix>

<state_variables> Persist these values across steps:

<entry_point> Load steps/step-00-preflight.md. </entry_point>

<step_files>

<bundled_resources>

<stack_context> NowStack stores billing definitions in convex/billing/plans.ts. The UI auth plans in src/lib/auth/stripe/auth-plans.ts derive core plan data from that Convex module and only add UI-only features/icons.

Stripe is handled by Convex:

• Checkout and portal flows call Convex actions.
• Webhooks go to https://<deployment>.convex.site/stripe/webhook, mounted in convex/http.ts.
• STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, and STRIPE_*_PLAN_ID values belong in Convex env.
• Stripe Price metadata must include plan: "<plan-name>" because webhook processing reads it. </stack_context>

<important_files> Files this workflow may modify:

Files this workflow reads:

• .agents/rules/stripe-billing.md
• .agents/rules/changelog.md
• convex/billing/plans.ts
• src/lib/auth/stripe/auth-plans.ts
• scripts/setup-stripe-webhook.mjs
• package.json </important_files>

<success_metrics>

• STRIPE_SECRET_KEY is set in Convex env.
• STRIPE_WEBHOOK_SECRET is set in Convex env after the webhook helper runs against VITE_CONVEX_SITE_URL.
• Every paid plan has a Stripe monthly Price ID in Convex env.
• Every paid plan with annual billing has a Stripe annual Price ID in Convex env.
• convex/billing/plans.ts matches the user's plan names, descriptions, limits, trial days, prices, currency, and env var names.
• src/lib/auth/stripe/auth-plans.ts has UI-only feature copy for every visible plan.
• pnpm ts passes, or any failure is documented with the exact blocker.
• CHANGELOG.md has a FEATURE: or CHORE: entry under today's date. </success_metrics>

<failure_modes>

• Writing sk_* secrets to tracked files instead of Convex env.
• Creating Stripe prices before convex/billing/plans.ts reflects the plan matrix.
• Creating live Stripe objects without explicit live-mode confirmation.
• Updating UI features but not convex/billing/plans.ts, which is the source of truth.
• Setting price IDs in local .env only; Convex actions will not see them.
• Forgetting metadata.plan on Stripe Prices, which breaks webhook plan mapping. </failure_modes>

NEXT STEP

Load steps/step-00-preflight.md.