Imported from marrrkkk/requo (.agents/skills/requo-repo-guide/SKILL.md). Install upstream with npx skills add marrrkkk/requo --skill requo-repo-guide. Copyright stays with the author.

Requo Repo Guide

Read these sources first when relevant:

• ../../../DESIGN.md for UI work
• ../../../docs/architecture/requo-architecture.md for structure
• ../../../app/globals.css for semantic tokens, surfaces, and motion utilities
• ../../../components/shared/dashboard-layout.tsx, ../../../components/shared/form-layout.tsx, and ../../../components/shared/page-header.tsx for shared layout patterns
• ../../../app/onboarding/page.tsx and ../../../lib/auth/config.ts for current auth and onboarding behavior

Working Defaults

• Inspect existing files before editing.
• Keep diffs small and feature-scoped.
• Keep app/ focused on routes, layouts, loading states, and route handlers.
• Keep business logic, validation, queries, actions, and mutations in features/.
• Keep provider integrations and shared utilities in lib/.
• Stay within current product scope: owner-first service-business workflows with workspace billing and light role-based membership. Do not add marketplace, live chat, mobile app, dispatch, payroll, invoicing, or advanced team collaboration unless explicitly requested.

UI System

• Treat DESIGN.md as the canonical UI system.
• Reuse shared wrappers and components/ui/* primitives before building custom markup.
• Prefer semantic utilities and tokens such as surface-*, control-*, overlay-*, table-*, meta-label, hero-panel, section-panel, and soft-panel.
• Preserve the calm, modern, minimalist Requo visual language.
• Do not copy legacy raw status colors or space-y-* stacks from older files into new work.

Auth, Data, And Providers

• Use Better Auth only. Do not introduce Supabase Auth.
• Signup creates the user and profile. Onboarding creates the first business. Additional businesses are explicit business flows.
• Enforce business ownership through scoped queries and business-aware helpers.
• Keep private asset access server-side.
• Validate external input with Zod.
• Keep provider boundaries narrow:
  • Better Auth for sessions and password flows
  • Supabase for storage and realtime-backed notification plumbing
• Resend for transactional email (Mailtrap/Brevo fallback)
• Groq, Cerebras, Gemini, Mistral, Cloudflare Workers AI, NVIDIA NIM, and OpenRouter through lib/ai for server-side AI
• Polar for card subscriptions (multi-currency, merchant of record)

Billing

• Subscriptions are business-scoped.
• business_subscriptions is authoritative; businesses.plan is a denormalized read cache.
• lib/billing/subscription-service.ts is the single write path for subscription mutations.
• lib/billing/webhook-processor.ts records provider events in billing_events for idempotency.
• lib/billing/refunds.ts is the single path for Polar refund requests.
• Polar webhook route: app/api/billing/polar/webhook/route.ts.

Testing

• Test behavior and product risk, not implementation details.
• Backend permission tests are required for business/workspace access changes.
• Prefer DB-backed integration tests for server actions, route handlers, workflow mutations, billing webhooks, and authorization-sensitive behavior.
• Keep component tests for meaningful interaction only. Avoid shallow render checks and snapshots.

Verification

• Docs-only changes: read through the edited files and run targeted grep checks.
• Most code changes: run npm run check.
• Logic, validation, or component changes: also run npm run test.
• Server action, route handler, billing, authz, or DB-backed changes: also run npm run test:integration.
• Route, layout, or system wiring changes: also run npm run build.
• Covered user-flow changes: run the relevant npm run test:e2e:smoke; use npm run test:e2e for broader browser journeys.
• CI baseline is lint, typecheck, unit/component tests, build, DB-backed integration tests, and Playwright smoke coverage.

Loading Skeletons & Tours

• A route loading.tsx mirrors its page's Static Shell: the same PageHeader (eyebrow/title/description/actions), tab bars, grid column counts, and section order as the page it loads. When a page's structure changes, its loading file changes in the same commit.
• If a page renders its PageHeader synchronously, the loading file must render it too (same copy) so navigation never pops a header in after the content.
• Prefer reusing colocated *Fallback exports from feature components and shared skeletons in components/shell/ and components/shared/; add a new shared skeleton only when two or more routes need it.
• Keep the two product tours in sync with the product surface:
  • Dashboard Tour (features/onboarding/components/dashboard-tour.tsx) walks the sidebar nav order (Home, Inquiries, Quotes, Follow-ups, Assistant, Services, Products, Members, Analytics) — non-nav deep-dives (e.g. "Draft with AI") sit directly beside the nav item they extend, so the sidebar highlight never moves backwards — previews live in features/onboarding/components/tour-modal.tsx.
  • Form Editor Tour (features/onboarding/components/form-editor-tour.tsx) mirrors the Service editor tabs (Form | Service page | Settings).

Optimistic CRUD UI

Use the shared optimistic stack for dashboard create/update/delete flows:

• List surfaces: hooks/use-animated-list.ts with .motion-list-item and data-motion-state from app/globals.css.
• Single-record toggles or kanban moves: useOptimistic directly or hooks/use-optimistic-mutation.ts.
• Forms and server-action buttons: components/shared/server-action-button.tsx with optional optimistic callbacks; prefer useDeferredRefresh() over immediate router.refresh().
• Temporary create IDs: lib/optimistic/id.ts (createOptimisticId, isOptimisticId).

Standard mutation flow:

1. Apply optimistic UI immediately inside startTransition.
2. Await the existing Server Action in the background.
3. On success, replace temp IDs when the action returns entity.id, then schedule deferred refresh.
4. On failure, revert optimistic state and show toast.error; do not refresh.

Keep server-side cache tag invalidation in actions unchanged. Client refresh is reconciliation, not the primary UX update.