@sylphx/flow 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @sylphx/flow
 
+## 2.10.0 (2025-12-17)
+
+Replace saas-* commands with 24 focused /review-* commands.
+
+Each domain now has a dedicated review command with mandate to delegate to multiple workers for parallel research.
+
+Categories:
+- Core Architecture (4): data-architecture, database, ledger, storage
+- Identity & Security (4): auth, account-security, security, privacy
+- Billing & Commerce (3): billing, pricing, referral
+- Frontend & Experience (5): uiux, i18n, seo, pwa, performance
+- Operations & Management (4): admin, observability, operability, support
+- Growth & Research (2): growth, discovery
+- Quality & Delivery (2): code-quality, delivery
+
+### ✨ Features
+
+- **commands:** replace saas-* with 24 focused /review-* commands ([c2f9eb9](https://github.com/SylphxAI/flow/commit/c2f9eb9bad695714be08645163480b46b9286b99))
+
 ## 2.9.0 (2025-12-17)
 
 Add comprehensive SaaS review command suite with parallel worker delegation.

package/assets/slash-commands/review-account-security.md

@@ -0,0 +1,51 @@
+---
+name: review-account-security
+description: Review account security - sessions, devices, MFA, security events
+agent: coder
+---
+
+# Account Security Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of account security in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Membership and Account Security
+
+* Membership is entitlement-driven and server-enforced.
+* Provide a dedicated **Account Security** surface.
+* **Account Security minimum acceptance**:
+  * Session/device visibility and revocation
+  * MFA/passkey management
+  * Linked identity provider management
+  * Key security event visibility (and export where applicable)
+  * All server-enforced and auditable
+
+### Security Event Management
+
+* Login attempts (success/failure) logged
+* Password changes logged
+* MFA enrollment/removal logged
+* Session creation/revocation logged
+* Suspicious activity detection
+* Security event notifications
+
+### Recovery Governance
+
+* Account recovery flow secure
+* Support-assisted recovery with strict audit logging
+* Step-up verification for sensitive actions
+
+## Verification Checklist
+
+- [ ] Session/device visibility exists
+- [ ] Session revocation works
+- [ ] MFA management available
+- [ ] Identity provider linking visible
+- [ ] Security events logged and visible
+- [ ] Recovery flow is secure and audited

package/assets/slash-commands/review-admin.md

@@ -0,0 +1,54 @@
+---
+name: review-admin
+description: Review admin - RBAC, bootstrap, config management, feature flags
+agent: coder
+---
+
+# Admin Platform Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of the admin platform in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Admin Platform (Operational-Grade)
+
+* Baseline: RBAC (least privilege), audit logs, feature flags governance, optional impersonation with safeguards and auditing.
+
+### Admin Bootstrap (Critical)
+
+* Admin bootstrap must not rely on file seeding:
+  * Use a secure, auditable **first-login allowlist** for the initial SUPER_ADMIN.
+  * Permanently disable bootstrap after completion.
+  * All privilege grants must be server-enforced and recorded in the audit log.
+  * The allowlist must be managed via secure configuration (environment/secret store), not code or DB seeding.
+
+### Configuration Management (Mandatory)
+
+* All **non-secret** product-level configuration must be manageable via admin (server-enforced), with validation and change history.
+* Secrets/credentials are environment-managed only; admin may expose safe readiness/health visibility, not raw secrets.
+
+### Admin Analytics and Reporting (Mandatory)
+
+* Provide comprehensive dashboards/reports for business, growth, billing, referral, support, and security/abuse signals, governed by RBAC.
+* Reporting must be consistent with system-of-record truth and auditable when derived from privileged actions.
+
+### Admin Operational Management (Mandatory)
+
+* Tools for user/account management, entitlements/access management, lifecycle actions, and issue resolution workflows.
+* Actions affecting access, money/credits, or security posture require appropriate step-up controls and must be fully auditable; reversibility must follow domain rules.
+
+## Verification Checklist
+
+- [ ] RBAC implemented (least privilege)
+- [ ] Admin bootstrap secure (not file seeding)
+- [ ] Bootstrap disables after completion
+- [ ] Config management with history
+- [ ] Feature flags governed
+- [ ] Admin dashboards exist
+- [ ] Impersonation has safeguards
+- [ ] All admin actions audited

package/assets/slash-commands/review-auth.md

@@ -0,0 +1,47 @@
+---
+name: review-auth
+description: Review authentication - SSO providers, passkeys, verification, sign-in
+agent: coder
+---
+
+# Authentication Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of authentication in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Identity, Verification, and Sign-in
+
+* SSO providers (minimum): **Google, Apple, Facebook, Microsoft, GitHub** (prioritize by audience).
+* If provider env/secrets are missing, **hide** the login option (no broken/disabled UI).
+* Allow linking multiple providers and safe unlinking; server-enforced and abuse-protected.
+* Passkeys (WebAuthn) are first-class with secure enrollment/usage/recovery.
+
+### Verification Requirements
+
+* **Email verification is mandatory** baseline for high-impact capabilities.
+* **Phone verification is optional** and used as risk-based step-up (anti-abuse, higher-trust flows, recovery); consent-aware and data-minimizing.
+
+### Authentication Best Practices
+
+* Secure session management
+* Token rotation and expiry
+* Brute force protection
+* Account enumeration prevention
+* Secure password reset flow
+* Remember me functionality (secure)
+
+## Verification Checklist
+
+- [ ] All SSO providers implemented
+- [ ] Missing provider secrets hide UI option
+- [ ] Multi-provider linking works safely
+- [ ] Passkeys (WebAuthn) supported
+- [ ] Email verification enforced
+- [ ] Phone verification optional/step-up
+- [ ] Session management secure

package/assets/slash-commands/review-billing.md

@@ -0,0 +1,47 @@
+---
+name: review-billing
+description: Review billing - Stripe integration, webhooks, state machine
+agent: coder
+---
+
+# Billing Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of billing and payments in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Billing and Payments (Stripe)
+
+* Support subscriptions and one-time payments as product needs require.
+* **Billing state machine follows mapping requirements**; UI must only surface explainable, non-ambiguous states aligned to server-truth.
+* Tax/invoicing and refund/dispute handling must be behaviorally consistent with product UX and entitlement state.
+
+### Webhook Requirements (High-Risk)
+
+* Webhooks must be idempotent, retry-safe, out-of-order safe, auditable
+* Billing UI reflects server-truth state without ambiguity
+* **Webhook trust is mandatory**: webhook origin must be verified (signature verification and replay resistance)
+* The Stripe **event id** must be used as the idempotency and audit correlation key
+* Unverifiable events must be rejected and must trigger alerting
+* **Out-of-order behavior must be explicit**: all webhook handlers must define and enforce a clear out-of-order strategy (event ordering is not guaranteed even for the same subscription)
+
+### State Machine
+
+* Define mapping: **Stripe state → internal subscription state → entitlements**
+* Handle: trial, past_due, unpaid, canceled, refund, dispute
+* UI only shows interpretable, non-ambiguous states
+
+## Verification Checklist
+
+- [ ] Billing state machine defined
+- [ ] Webhook signature verification
+- [ ] Idempotent webhook handling (event id)
+- [ ] Out-of-order handling defined
+- [ ] All Stripe states mapped
+- [ ] UI reflects server-truth only
+- [ ] Refund/dispute handling works

package/assets/slash-commands/review-code-quality.md

@@ -0,0 +1,63 @@
+---
+name: review-code-quality
+description: Review code quality - linting, TypeScript, testing, CI
+agent: coder
+---
+
+# Code Quality Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of code quality in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Non-Negotiable Engineering Principles
+
+* No workarounds, hacks, or TODOs.
+* Feature-first with clean architecture; designed for easy extension; no "god files".
+* Type-first, strict end-to-end correctness (**DB → API → UI**).
+* Serverless-first and server-first; edge-compatible where feasible without sacrificing correctness, security, or observability.
+* Mobile-first responsive design; desktop-second.
+* Precise naming; remove dead/unused code.
+* Upgrade all packages to latest stable; avoid deprecated patterns.
+
+### Tooling Baseline
+
+* **Bun** for runtime
+* **Biome** for linting/formatting
+* **Bun test** for testing
+* Strict TypeScript
+
+### CI Requirements
+
+* Biome lint/format passes
+* Strict TS typecheck passes
+* Unit + E2E tests pass
+* Build succeeds
+
+### Code Quality Best Practices
+
+* Consistent code style
+* Meaningful variable/function names
+* Single responsibility principle
+* DRY (Don't Repeat Yourself)
+* SOLID principles
+* No circular dependencies
+* Reasonable file sizes
+* Clear module boundaries
+
+## Verification Checklist
+
+- [ ] Biome lint passes
+- [ ] Biome format passes
+- [ ] TypeScript strict mode
+- [ ] No type errors
+- [ ] Tests exist and pass
+- [ ] Build succeeds
+- [ ] No TODOs/hacks
+- [ ] No dead code
+- [ ] Packages up to date

package/assets/slash-commands/review-data-architecture.md

@@ -0,0 +1,36 @@
+---
+name: review-data-architecture
+description: Review data architecture - boundaries, consistency model, server enforcement
+agent: coder
+---
+
+# Data Architecture Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of data architecture in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Boundaries, Server Enforcement, and Consistency Model (Hard Requirement)
+
+* Define clear boundaries: domain rules, use-cases, integrations, UI.
+* All authorization/entitlements are **server-enforced**; no client-trust.
+* Runtime constraints (serverless/edge) must be explicit and validated.
+* **Consistency model is mandatory for high-value state**: for billing, entitlements, ledger, admin privilege grants, and security posture, the system must define and enforce an explicit consistency model (source-of-truth, allowed delay windows, retry/out-of-order handling, and acceptable eventual consistency bounds).
+* **Billing and access state machine is mandatory**: define and validate the mapping **Stripe state → internal subscription state → entitlements**, including trial, past_due, unpaid, canceled, refund, and dispute outcomes. UI must only present interpretable, non-ambiguous states derived from server-truth.
+* **No dual-write (hard requirement)**: subscription/payment truth must be derived from Stripe-driven events; internal systems must not directly rewrite billing truth or authorize entitlements based on non-Stripe truth, except for explicitly defined admin remediation flows that are fully server-enforced and fully audited.
+* **Server-truth is authoritative**: UI state must never contradict server-truth. Where asynchronous confirmation exists, UI must represent that state unambiguously and remain explainable.
+* **Auditability chain is mandatory** for any high-value mutation: who/when/why, before/after state, and correlation to the triggering request/job/webhook must be recorded and queryable.
+
+## Verification Checklist
+
+- [ ] Clear domain boundaries defined
+- [ ] Server enforcement for all authorization
+- [ ] Explicit consistency model documented
+- [ ] State machine for billing/entitlements exists
+- [ ] No dual-write violations
+- [ ] Auditability chain implemented

package/assets/slash-commands/review-database.md

@@ -0,0 +1,40 @@
+---
+name: review-database
+description: Review database - Drizzle migrations, schema drift, CI gates
+agent: coder
+---
+
+# Database Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of database architecture in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Drizzle Migrations (Non-Negotiable)
+
+* Migration files must exist, be complete, and be committed.
+* Deterministic, reproducible, environment-safe; linear/auditable history; no drift.
+* CI must fail if schema changes are not represented by migrations.
+
+### Database Best Practices
+
+* Schema design follows normalization principles where appropriate
+* Indexes exist for commonly queried columns
+* Foreign key constraints are properly defined
+* No orphaned tables or columns
+* Proper use of data types (no stringly-typed data)
+* Timestamps use consistent timezone handling
+
+## Verification Checklist
+
+- [ ] All migrations committed and complete
+- [ ] No schema drift detected
+- [ ] CI blocks on migration integrity
+- [ ] Indexes cover common queries
+- [ ] Foreign keys properly defined
+- [ ] Data types appropriate

package/assets/slash-commands/review-delivery.md

@@ -0,0 +1,71 @@
+---
+name: review-delivery
+description: Review delivery gates - release blocking checks, verification
+agent: coder
+---
+
+# Delivery Gates Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of delivery gates in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Delivery Gates and Completion
+
+CI must block merges/deploys when failing:
+
+#### Code Quality Gates
+- [ ] Biome lint/format passes
+- [ ] Strict TS typecheck passes
+- [ ] Unit + E2E tests pass (Bun test)
+- [ ] Build succeeds
+
+#### Data Integrity Gates
+- [ ] Migration integrity checks pass
+- [ ] No schema drift
+
+#### i18n Gates
+- [ ] Missing translation keys fail build
+- [ ] `/en/*` returns 301 redirect
+- [ ] hreflang/x-default correct
+- [ ] Sitemap contains only true variants
+
+#### Performance Gates
+- [ ] Performance budget verification for key journeys
+- [ ] Core Web Vitals within thresholds
+- [ ] Release-blocking regression detection
+
+#### Security Gates
+- [ ] CSP/HSTS/security headers verified
+- [ ] CSRF protection tested
+
+#### Consent Gates
+- [ ] Analytics/marketing consent gating verified
+- [ ] Newsletter eligibility and firing rules tested
+
+### Automation Requirement
+
+**All gates above must be enforced by automated tests or mechanized checks (non-manual); manual verification does not satisfy release gates.**
+
+### Configuration Gates
+
+* Build/startup must fail-fast when required configuration/secrets are missing or invalid for the target environment.
+
+### Operability Gates
+
+* Observability and alerting configured for critical anomalies
+* Workflow dead-letter handling is operable, visible, and supports controlled replay
+
+## Verification Checklist
+
+- [ ] All gates automated (no manual)
+- [ ] CI blocks on failures
+- [ ] Config fail-fast works
+- [ ] Operability gates met
+- [ ] No TODOs/hacks/workarounds
+- [ ] No dead/unused code

package/assets/slash-commands/review-discovery.md

@@ -0,0 +1,49 @@
+---
+name: review-discovery
+description: Review discovery - competitive research, features, pricing opportunities
+agent: coder
+---
+
+# Discovery Review
+
+## Mandate
+
+* Perform a **deep, thorough review** to discover opportunities in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Review Requirements: Explore Beyond the Spec
+
+* **Feature design review**: define success criteria, journeys, state model, auth/entitlements, instrumentation; propose competitiveness improvements within constraints.
+* **Pricing/monetization review**: packaging/entitlements, lifecycle semantics, legal/tax/invoice implications; propose conversion/churn improvements within constraints.
+* **Competitive research**: features, extensibility, guidance patterns, pricing/packaging norms; convert insights into testable acceptance criteria.
+
+### Discovery Areas
+
+* What features are competitors offering that we lack?
+* What pricing models are common in the market?
+* What UX patterns are users expecting?
+* What integrations would add value?
+* What automation opportunities exist?
+* What self-service capabilities are missing?
+
+### Analysis Framework
+
+* Market positioning
+* Feature gap analysis
+* Pricing benchmarking
+* User journey optimization
+* Technical debt opportunities
+* Scalability considerations
+
+## Verification Checklist
+
+- [ ] Competitor analysis completed
+- [ ] Feature gaps identified
+- [ ] Pricing reviewed
+- [ ] UX patterns researched
+- [ ] Integration opportunities listed
+- [ ] Recommendations prioritized

package/assets/slash-commands/review-growth.md

@@ -0,0 +1,62 @@
+---
+name: review-growth
+description: Review growth - onboarding, viral mechanics, retention
+agent: coder
+---
+
+# Growth Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of growth systems in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Growth System (Onboarding, Share/Viral, Retention)
+
+* The review must produce a coherent, measurable growth system for activation, sharing/virality, and retention, aligned with compliance and anti-abuse constraints.
+
+### Onboarding
+
+* Onboarding must be:
+  * Outcome-oriented
+  * Localized
+  * Accessible
+  * Instrumented
+
+### Sharing/Virality
+
+* Sharing/virality must be:
+  * Consent-aware
+  * Abuse-resistant
+  * Measurable end-to-end
+
+### Retention
+
+* Retention must be:
+  * Intentionally engineered
+  * Monitored
+  * Protected against regressions
+
+### Growth Best Practices
+
+* Clear value proposition on landing
+* Frictionless signup
+* Time-to-value optimization
+* Activation milestones defined
+* Re-engagement campaigns
+* Churn prediction/prevention
+* NPS/satisfaction tracking
+
+## Verification Checklist
+
+- [ ] Onboarding flow exists
+- [ ] Onboarding instrumented
+- [ ] Sharing mechanisms work
+- [ ] Sharing is consent-aware
+- [ ] Retention metrics tracked
+- [ ] Re-engagement exists
+- [ ] Growth metrics dashboarded

package/assets/slash-commands/review-i18n.md

@@ -0,0 +1,50 @@
+---
+name: review-i18n
+description: Review i18n - locales, routing, canonicalization, UGC
+agent: coder
+---
+
+# Internationalization Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of internationalization in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Supported Locales
+
+`en`, `zh-Hans`, `zh-Hant`, `es`, `ja`, `ko`, `de`, `fr`, `pt-BR`, `it`, `nl`, `pl`, `tr`, `id`, `th`, `vi`
+
+### URL Strategy: Prefix Except Default
+
+* English is default and non-prefixed.
+* `/en/*` must not exist; permanently redirect to non-prefixed equivalent.
+* All non-default locales are `/<locale>/...`.
+
+### Globalization Rules
+
+* Intl formatting for dates, numbers, currency
+* Explicit fallback rules
+* Missing translation keys must fail build
+* No hardcoded user-facing strings outside localization
+
+### UGC Canonicalization
+
+* Separate UI language from content language.
+* Exactly one canonical URL per UGC resource determined by content language.
+* No indexable locale-prefixed duplicates unless primary content is truly localized; otherwise redirect to canonical.
+* Canonical/hreflang/sitemap must reflect only true localized variants.
+
+## Verification Checklist
+
+- [ ] All locales supported
+- [ ] `/en/*` returns 301 redirect
+- [ ] Missing keys fail build
+- [ ] No hardcoded strings
+- [ ] Intl formatting used
+- [ ] UGC has single canonical URL
+- [ ] hreflang tags correct

package/assets/slash-commands/review-ledger.md

@@ -0,0 +1,40 @@
+---
+name: review-ledger
+description: Review ledger - financial-grade balance system, immutable ledger
+agent: coder
+---
+
+# Ledger Review
+
+## Mandate
+
+* Perform a **deep, thorough review** of any balance/credits/wallet system in this codebase.
+* **Delegate to multiple workers** to research different aspects in parallel; you act as the **final gate** to synthesize and verify quality.
+* Deliverables must be stated as **findings, gaps, and actionable recommendations**.
+* **Single-pass delivery**: no deferrals; deliver a complete assessment.
+
+## Review Scope
+
+### Financial-Grade Balance System (Only if "balance/credits/wallet" exists)
+
+* Any balance concept must be implemented as an **immutable ledger** (append-only source of truth), not a mutable balance field.
+* Deterministic precision (no floats), idempotent posting, concurrency safety, transactional integrity, and auditability are required.
+* Monetary flows must be currency-based and reconcilable with Stripe; credits (if used) must be governed as non-cash entitlements.
+
+### Ledger Requirements
+
+* Append-only transaction log
+* Double-entry bookkeeping where applicable
+* Idempotent transaction posting (idempotency keys)
+* Concurrency-safe balance calculations
+* Audit trail for all mutations
+* Reconciliation with external systems (Stripe)
+
+## Verification Checklist
+
+- [ ] Immutable ledger pattern used (not mutable balance)
+- [ ] No floating point for money
+- [ ] Idempotent posting implemented
+- [ ] Concurrency safety verified
+- [ ] Full audit trail exists
+- [ ] Reconciliation with Stripe possible