@sylphx/flow 2.6.0 → 2.7.0
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.
- package/CHANGELOG.md +6 -0
- package/assets/slash-commands/saas-auth.md +78 -0
- package/assets/slash-commands/saas-billing.md +68 -0
- package/assets/slash-commands/saas-discovery.md +135 -0
- package/assets/slash-commands/saas-growth.md +94 -0
- package/assets/slash-commands/saas-i18n.md +66 -0
- package/assets/slash-commands/saas-platform.md +87 -0
- package/assets/slash-commands/saas-review.md +140 -237
- package/assets/slash-commands/saas-security.md +108 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# @sylphx/flow
|
|
2
2
|
|
|
3
|
+
## 2.7.0 (2025-12-17)
|
|
4
|
+
|
|
5
|
+
### ✨ Features
|
|
6
|
+
|
|
7
|
+
- **commands:** split saas-review into domain-specific commands ([bef500f](https://github.com/SylphxAI/flow/commit/bef500f1eeb450ee6790084354ff015ad6179f7d))
|
|
8
|
+
|
|
3
9
|
## 2.6.0 (2025-12-17)
|
|
4
10
|
|
|
5
11
|
### ✨ Features
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-auth
|
|
3
|
+
description: SaaS identity review - SSO, passkeys, verification, account security
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Identity & Account Security Review
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Review identity systems: authentication methods, SSO providers, passkeys/WebAuthn, verification flows, session management, and account security surfaces.
|
|
12
|
+
|
|
13
|
+
## Specification
|
|
14
|
+
|
|
15
|
+
### Identity Providers (SSO)
|
|
16
|
+
|
|
17
|
+
* SSO providers (minimum): **Google, Apple, Facebook, Microsoft, GitHub** (prioritize by audience).
|
|
18
|
+
* If provider env/secrets are missing, **hide** the login option (no broken/disabled UI).
|
|
19
|
+
* Allow linking multiple providers and safe unlinking; server-enforced and abuse-protected.
|
|
20
|
+
|
|
21
|
+
### Passkeys (WebAuthn)
|
|
22
|
+
|
|
23
|
+
* Passkeys are first-class with secure enrollment/usage/recovery.
|
|
24
|
+
* Must support cross-device authentication where platform allows.
|
|
25
|
+
|
|
26
|
+
### Verification
|
|
27
|
+
|
|
28
|
+
* **Email verification is mandatory** baseline for high-impact capabilities.
|
|
29
|
+
* **Phone verification is optional** and used as risk-based step-up (anti-abuse, higher-trust flows, recovery); consent-aware and data-minimizing.
|
|
30
|
+
|
|
31
|
+
### Membership and Entitlements
|
|
32
|
+
|
|
33
|
+
* Membership is entitlement-driven and server-enforced.
|
|
34
|
+
* All authorization/entitlements are **server-enforced**; no client-trust.
|
|
35
|
+
|
|
36
|
+
### Account Security Surface
|
|
37
|
+
|
|
38
|
+
* Provide a dedicated **Account Security** surface.
|
|
39
|
+
* **Minimum acceptance criteria**:
|
|
40
|
+
* Session/device visibility and revocation
|
|
41
|
+
* MFA/passkey management
|
|
42
|
+
* Linked identity provider management
|
|
43
|
+
* Key security event visibility (and export where applicable)
|
|
44
|
+
* All server-enforced and auditable.
|
|
45
|
+
|
|
46
|
+
### Session Management
|
|
47
|
+
|
|
48
|
+
* Session/device visibility + revocation available to user.
|
|
49
|
+
* Security event visibility with clear audit trail.
|
|
50
|
+
* Recovery governance (including support-assisted recovery) with strict audit logging.
|
|
51
|
+
* Step-up authentication for sensitive actions.
|
|
52
|
+
|
|
53
|
+
### Password Security
|
|
54
|
+
|
|
55
|
+
* Password UX: masked + temporary reveal option.
|
|
56
|
+
* No plaintext passwords in logs/returns/storage/telemetry.
|
|
57
|
+
* MFA required for Admin/SUPER_ADMIN; step-up for high-risk actions.
|
|
58
|
+
|
|
59
|
+
## Domain Discovery
|
|
60
|
+
|
|
61
|
+
After reviewing compliance with spec, explore improvements:
|
|
62
|
+
|
|
63
|
+
* **Onboarding friction**: Is sign-up flow optimized? Too many steps? Missing social providers for target market?
|
|
64
|
+
* **Security vs UX balance**: Are step-up challenges appropriate? Too frequent? Too rare?
|
|
65
|
+
* **Recovery flows**: Is account recovery secure yet accessible? Support burden from lockouts?
|
|
66
|
+
* **Modern auth**: Are passkeys properly promoted? Is passwordless an option?
|
|
67
|
+
* **Trust signals**: Are verified badges shown? Does verification unlock features appropriately?
|
|
68
|
+
|
|
69
|
+
## Domain Gates
|
|
70
|
+
|
|
71
|
+
* [ ] All SSO providers working (or hidden if unconfigured)
|
|
72
|
+
* [ ] Passkey enrollment/usage/recovery tested
|
|
73
|
+
* [ ] Email verification enforced for high-impact actions
|
|
74
|
+
* [ ] Account security surface complete (sessions, MFA, providers, events)
|
|
75
|
+
* [ ] Session revocation works correctly
|
|
76
|
+
* [ ] No client-trust for authorization decisions
|
|
77
|
+
* [ ] Step-up auth for sensitive actions
|
|
78
|
+
* [ ] No plaintext passwords anywhere
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-billing
|
|
3
|
+
description: SaaS billing review - Stripe, webhooks, pricing governance, ledger
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Billing & Payments Review
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Review all payment and billing systems: Stripe integration, webhook handling, pricing governance, subscription state machine, and financial-grade ledger (if applicable).
|
|
12
|
+
|
|
13
|
+
## Specification
|
|
14
|
+
|
|
15
|
+
### Billing State Machine (Hard Requirement)
|
|
16
|
+
|
|
17
|
+
* **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.
|
|
18
|
+
* UI must only present interpretable, non-ambiguous states derived from server-truth.
|
|
19
|
+
* **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.
|
|
20
|
+
|
|
21
|
+
### Stripe Integration
|
|
22
|
+
|
|
23
|
+
* Support subscriptions and one-time payments as product needs require.
|
|
24
|
+
* Tax/invoicing and refund/dispute handling must be behaviorally consistent with product UX and entitlement state.
|
|
25
|
+
|
|
26
|
+
### Webhook Handling (Hard Requirement)
|
|
27
|
+
|
|
28
|
+
* Webhooks must be idempotent, retry-safe, out-of-order safe, auditable; billing UI reflects server-truth state without ambiguity.
|
|
29
|
+
* **Webhook trust is mandatory (high-risk)**: 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.
|
|
30
|
+
* **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), and must define final-state decision rules.
|
|
31
|
+
|
|
32
|
+
### Pricing Governance (Stripe-first, not Dashboard-first)
|
|
33
|
+
|
|
34
|
+
* Stripe is the system-of-record for products, prices, subscriptions, invoices, and disputes; internal systems must not contradict Stripe truth.
|
|
35
|
+
* Pricing changes must be performed by creating new Stripe Prices and updating the "active sellable price" policy; historical prices must remain immutable for existing subscriptions unless an approved migration is executed.
|
|
36
|
+
* Default pricing change policy is **grandfathering**: existing subscribers keep their current price; new customers use the currently active sellable price.
|
|
37
|
+
* An operational-grade **Pricing Admin** must exist to manage creation of new Stripe Prices, activation/deactivation of sellable prices, and (optionally) controlled bulk subscription migrations; all actions must be governed by RBAC, step-up controls, and audit logs.
|
|
38
|
+
* Stripe Dashboard is treated as monitoring/emergency access; non-admin Stripe changes must be detectable (drift), alertable, and remediable.
|
|
39
|
+
|
|
40
|
+
### Financial-Grade Balance System (Only if "balance/credits/wallet" exists)
|
|
41
|
+
|
|
42
|
+
* Any balance concept must be implemented as an **immutable ledger** (append-only source of truth), not a mutable balance field.
|
|
43
|
+
* Deterministic precision (no floats), idempotent posting, concurrency safety, transactional integrity, and auditability are required.
|
|
44
|
+
* Monetary flows must be currency-based and reconcilable with Stripe; credits (if used) must be governed as non-cash entitlements.
|
|
45
|
+
|
|
46
|
+
### Auditability
|
|
47
|
+
|
|
48
|
+
* **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.
|
|
49
|
+
|
|
50
|
+
## Domain Discovery
|
|
51
|
+
|
|
52
|
+
After reviewing compliance with spec, explore improvements:
|
|
53
|
+
|
|
54
|
+
* **Conversion optimization**: Are there friction points in the checkout flow? Missing payment methods for target markets?
|
|
55
|
+
* **Churn reduction**: Is dunning (failed payment retry) properly configured? Are there win-back opportunities?
|
|
56
|
+
* **Pricing opportunities**: Are tiers properly differentiated? Is there usage-based pricing potential?
|
|
57
|
+
* **Trial optimization**: Is trial-to-paid conversion measured and optimized?
|
|
58
|
+
* **Upgrade/downgrade UX**: Is plan switching seamless? Prorated correctly?
|
|
59
|
+
|
|
60
|
+
## Domain Gates
|
|
61
|
+
|
|
62
|
+
* [ ] Stripe state machine fully mapped and documented
|
|
63
|
+
* [ ] Webhook handlers are idempotent and out-of-order safe
|
|
64
|
+
* [ ] Signature verification implemented and tested
|
|
65
|
+
* [ ] Pricing admin exists with RBAC and audit
|
|
66
|
+
* [ ] No dual-write violations
|
|
67
|
+
* [ ] Ledger is append-only (if balance exists)
|
|
68
|
+
* [ ] Billing UI reflects server-truth only
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-discovery
|
|
3
|
+
description: SaaS strategic discovery - features, pricing, competitive research
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Strategic Discovery & Opportunities
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Cross-domain strategic exploration: identify new feature opportunities, optimize pricing/packaging, and conduct competitive research. This is NOT compliance checking — it's creative/strategic work to improve the product.
|
|
12
|
+
|
|
13
|
+
## Mandate
|
|
14
|
+
|
|
15
|
+
* **Exploration required**: identify improvements for competitiveness, completeness, usability, reliability, and monetization within fixed constraints.
|
|
16
|
+
* Think beyond current implementation — what's missing? What would make users love this product?
|
|
17
|
+
* Convert insights into **testable acceptance criteria**, not vague suggestions.
|
|
18
|
+
|
|
19
|
+
## Feature Discovery
|
|
20
|
+
|
|
21
|
+
### Process
|
|
22
|
+
|
|
23
|
+
1. **Audit current capabilities**: What does the product do today?
|
|
24
|
+
2. **Identify gaps**: What's missing that users expect?
|
|
25
|
+
3. **Prioritize by impact**: What would move the needle most?
|
|
26
|
+
4. **Define success criteria**: How would we know the feature works?
|
|
27
|
+
|
|
28
|
+
### Areas to Explore
|
|
29
|
+
|
|
30
|
+
* **User workflows**: Are there manual steps that could be automated?
|
|
31
|
+
* **Integrations**: What third-party services should we connect to?
|
|
32
|
+
* **Data/insights**: What data do we have that users would value seeing?
|
|
33
|
+
* **Collaboration**: Are there multi-user/team features missing?
|
|
34
|
+
* **Mobile**: Is the mobile experience feature-complete or degraded?
|
|
35
|
+
* **API/Developer**: Should there be a public API? Webhooks for users?
|
|
36
|
+
* **AI/Automation**: Where could AI add value without being gimmicky?
|
|
37
|
+
|
|
38
|
+
### Output Format
|
|
39
|
+
|
|
40
|
+
For each feature opportunity:
|
|
41
|
+
```markdown
|
|
42
|
+
**Feature**: [Name]
|
|
43
|
+
**Problem**: [What user problem does this solve?]
|
|
44
|
+
**Impact**: [High/Medium/Low] — [Why?]
|
|
45
|
+
**Effort**: [High/Medium/Low] — [Why?]
|
|
46
|
+
**Success Criteria**: [How do we measure success?]
|
|
47
|
+
**Acceptance Criteria**:
|
|
48
|
+
- [ ] [Specific, testable requirement]
|
|
49
|
+
- [ ] [Another requirement]
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Pricing & Monetization Discovery
|
|
53
|
+
|
|
54
|
+
### Process
|
|
55
|
+
|
|
56
|
+
1. **Audit current pricing**: Tiers, features per tier, price points
|
|
57
|
+
2. **Analyze value alignment**: Does pricing match perceived value?
|
|
58
|
+
3. **Identify friction**: Where do users hesitate to pay?
|
|
59
|
+
4. **Explore models**: Subscription, usage-based, hybrid, freemium
|
|
60
|
+
|
|
61
|
+
### Areas to Explore
|
|
62
|
+
|
|
63
|
+
* **Tier differentiation**: Are tiers clearly differentiated? Is there a "trapped middle"?
|
|
64
|
+
* **Feature gating**: Are the right features gated? Too much in free? Too little?
|
|
65
|
+
* **Price anchoring**: Is there a decoy tier? Is the recommended tier obvious?
|
|
66
|
+
* **Trial optimization**: Is trial length optimal? What converts?
|
|
67
|
+
* **Upgrade triggers**: What signals readiness to upgrade? Are we acting on them?
|
|
68
|
+
* **Annual discounts**: Is annual pricing compelling enough?
|
|
69
|
+
* **Add-ons**: Are there features that should be add-ons rather than tier-gated?
|
|
70
|
+
* **Usage-based**: Would pay-per-use work for any features?
|
|
71
|
+
|
|
72
|
+
### Output Format
|
|
73
|
+
|
|
74
|
+
For each pricing opportunity:
|
|
75
|
+
```markdown
|
|
76
|
+
**Change**: [What to change]
|
|
77
|
+
**Rationale**: [Why this improves monetization]
|
|
78
|
+
**Expected Impact**: [Conversion? ARPU? Retention?]
|
|
79
|
+
**Risk**: [What could go wrong?]
|
|
80
|
+
**Test Plan**: [How to validate before full rollout]
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Competitive Research
|
|
84
|
+
|
|
85
|
+
### Process
|
|
86
|
+
|
|
87
|
+
1. **Identify competitors**: Direct and indirect (alternative solutions)
|
|
88
|
+
2. **Analyze features**: What do they have that we don't?
|
|
89
|
+
3. **Analyze pricing**: How do they package and price?
|
|
90
|
+
4. **Analyze UX**: What do they do better? Worse?
|
|
91
|
+
5. **Synthesize insights**: What should we adopt? Avoid? Differentiate on?
|
|
92
|
+
|
|
93
|
+
### Areas to Explore
|
|
94
|
+
|
|
95
|
+
* **Feature parity**: What table-stakes features are we missing?
|
|
96
|
+
* **Differentiation**: What do we do uniquely well? How to amplify?
|
|
97
|
+
* **Pricing position**: Are we premium, mid-market, or budget? Is that intentional?
|
|
98
|
+
* **UX patterns**: What onboarding/guidance patterns work well elsewhere?
|
|
99
|
+
* **Growth tactics**: How do competitors acquire and retain users?
|
|
100
|
+
* **Market gaps**: What's everyone missing that we could own?
|
|
101
|
+
|
|
102
|
+
### Output Format
|
|
103
|
+
|
|
104
|
+
For each competitive insight:
|
|
105
|
+
```markdown
|
|
106
|
+
**Competitor**: [Name]
|
|
107
|
+
**Observation**: [What we learned]
|
|
108
|
+
**Implication**: [What this means for us]
|
|
109
|
+
**Action**: [Specific recommendation]
|
|
110
|
+
**Priority**: [High/Medium/Low]
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Synthesis
|
|
114
|
+
|
|
115
|
+
After exploring all areas, produce a prioritized roadmap:
|
|
116
|
+
|
|
117
|
+
### Immediate Wins (Do Now)
|
|
118
|
+
High impact + Low effort opportunities
|
|
119
|
+
|
|
120
|
+
### Strategic Investments (Plan Carefully)
|
|
121
|
+
High impact + High effort opportunities
|
|
122
|
+
|
|
123
|
+
### Quick Wins (When Available)
|
|
124
|
+
Low impact + Low effort opportunities
|
|
125
|
+
|
|
126
|
+
### Deprioritized (Defer/Skip)
|
|
127
|
+
Low impact + High effort — document why not pursuing
|
|
128
|
+
|
|
129
|
+
## Exit Criteria
|
|
130
|
+
|
|
131
|
+
* [ ] Feature gaps identified with acceptance criteria
|
|
132
|
+
* [ ] Pricing optimization opportunities documented
|
|
133
|
+
* [ ] Competitive landscape analyzed
|
|
134
|
+
* [ ] Prioritized roadmap produced
|
|
135
|
+
* [ ] All recommendations have testable success criteria
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-growth
|
|
3
|
+
description: SaaS growth review - onboarding, referral, retention, guidance
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Growth Systems Review
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Review growth systems: onboarding flows, referral program, retention mechanics, viral/sharing features, and user guidance.
|
|
12
|
+
|
|
13
|
+
## Specification
|
|
14
|
+
|
|
15
|
+
### Growth System Foundation
|
|
16
|
+
|
|
17
|
+
* The system must produce a coherent, measurable growth system for activation, sharing/virality, and retention, aligned with compliance and anti-abuse constraints.
|
|
18
|
+
|
|
19
|
+
### Onboarding
|
|
20
|
+
|
|
21
|
+
* Onboarding must be **outcome-oriented** (guide to first value, not just feature tour).
|
|
22
|
+
* Localized for all supported locales.
|
|
23
|
+
* Accessible (WCAG AA).
|
|
24
|
+
* Instrumented (track completion, drop-off points).
|
|
25
|
+
* Progressive disclosure — don't overwhelm new users.
|
|
26
|
+
|
|
27
|
+
### Sharing/Virality
|
|
28
|
+
|
|
29
|
+
* Sharing must be **consent-aware** (no spam, no dark patterns).
|
|
30
|
+
* Abuse-resistant with rate limiting and detection.
|
|
31
|
+
* Measurable end-to-end (share → click → signup → conversion).
|
|
32
|
+
* Platform-appropriate sharing (native share sheet on mobile, copy link on desktop).
|
|
33
|
+
|
|
34
|
+
### Retention
|
|
35
|
+
|
|
36
|
+
* Retention must be **intentionally engineered**, not accidental.
|
|
37
|
+
* Monitored with cohort analysis.
|
|
38
|
+
* Protected against regressions (alert on retention drops).
|
|
39
|
+
* Re-engagement flows (email, push) must be consent-governed.
|
|
40
|
+
|
|
41
|
+
### Referral Program (Anti-Abuse Baseline Required)
|
|
42
|
+
|
|
43
|
+
* Referral must be measurable, abuse-resistant, and governed:
|
|
44
|
+
* Clear attribution semantics (who referred whom, when)
|
|
45
|
+
* Reward lifecycle governance (pending → approved → paid, including revocation/clawbacks)
|
|
46
|
+
* Anti-fraud measures
|
|
47
|
+
* Admin reporting and audit capabilities
|
|
48
|
+
* Localized and instrumented
|
|
49
|
+
|
|
50
|
+
* **Referral anti-fraud minimum baseline is mandatory**:
|
|
51
|
+
* Define minimum set of risk signals and enforcement measures
|
|
52
|
+
* Velocity controls (rate limiting referrals)
|
|
53
|
+
* Account/device linkage posture (detect self-referral)
|
|
54
|
+
* Risk-tiered enforcement (high-risk delays, low-risk instant)
|
|
55
|
+
* Reward delay/hold/freeze capabilities
|
|
56
|
+
* Clawback conditions clearly defined
|
|
57
|
+
* Auditable manual review/appeal posture where applicable
|
|
58
|
+
|
|
59
|
+
### Support and Communications
|
|
60
|
+
|
|
61
|
+
* Support/Contact surface must be discoverable, localized, WCAG AA, SEO-complete, privacy-safe, and auditable where relevant.
|
|
62
|
+
* Newsletter subscription/preferences must be consent-aware; unsubscribe enforcement must be reliable and immediate.
|
|
63
|
+
|
|
64
|
+
### Admin Platform (Growth-Related)
|
|
65
|
+
|
|
66
|
+
* **Admin analytics and reporting are mandatory**:
|
|
67
|
+
* Comprehensive dashboards/reports for business, growth, billing, referral, support, and security/abuse signals
|
|
68
|
+
* Governed by RBAC
|
|
69
|
+
* Reporting must be consistent with system-of-record truth and auditable
|
|
70
|
+
|
|
71
|
+
## Domain Discovery
|
|
72
|
+
|
|
73
|
+
After reviewing compliance with spec, explore improvements:
|
|
74
|
+
|
|
75
|
+
* **Activation optimization**: What's the "aha moment"? How fast do users reach it? What's blocking them?
|
|
76
|
+
* **Viral loops**: Are there natural sharing moments? Can product usage generate invites?
|
|
77
|
+
* **Retention hooks**: What brings users back? Email? Push? In-app value?
|
|
78
|
+
* **Referral improvements**: Is the reward compelling? Is sharing frictionless? What's the k-factor?
|
|
79
|
+
* **Churn analysis**: Why do users leave? Exit surveys? Behavioral patterns before churn?
|
|
80
|
+
* **Expansion revenue**: Are there upsell opportunities? Usage-based triggers?
|
|
81
|
+
|
|
82
|
+
## Domain Gates
|
|
83
|
+
|
|
84
|
+
* [ ] Onboarding tracks completion and drop-off
|
|
85
|
+
* [ ] Onboarding is localized and accessible
|
|
86
|
+
* [ ] Sharing respects consent and has rate limits
|
|
87
|
+
* [ ] Sharing is measurable end-to-end
|
|
88
|
+
* [ ] Retention cohorts are tracked
|
|
89
|
+
* [ ] Retention regression alerts exist
|
|
90
|
+
* [ ] Referral attribution is accurate
|
|
91
|
+
* [ ] Referral has anti-fraud controls
|
|
92
|
+
* [ ] Reward lifecycle is auditable
|
|
93
|
+
* [ ] Support surface is discoverable and localized
|
|
94
|
+
* [ ] Newsletter unsubscribe works immediately
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-i18n
|
|
3
|
+
description: SaaS internationalization review - locales, routing, canonicalization, hreflang
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Internationalization & Routing Review
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Review internationalization systems: locale support, URL routing strategy, canonicalization, hreflang implementation, and UGC handling across languages.
|
|
12
|
+
|
|
13
|
+
## Specification
|
|
14
|
+
|
|
15
|
+
### Supported Locales
|
|
16
|
+
|
|
17
|
+
`en`, `zh-Hans`, `zh-Hant`, `es`, `ja`, `ko`, `de`, `fr`, `pt-BR`, `it`, `nl`, `pl`, `tr`, `id`, `th`, `vi`
|
|
18
|
+
|
|
19
|
+
### URL Strategy: Prefix Except Default
|
|
20
|
+
|
|
21
|
+
* English is default and **non-prefixed**.
|
|
22
|
+
* `/en/*` must **not exist**; permanently redirect to non-prefixed equivalent.
|
|
23
|
+
* All non-default locales are `/<locale>/...`.
|
|
24
|
+
|
|
25
|
+
### Globalization Rules
|
|
26
|
+
|
|
27
|
+
* Use Intl APIs for formatting (dates, numbers, currencies).
|
|
28
|
+
* Explicit fallback rules for missing translations.
|
|
29
|
+
* **Missing translation keys must fail build** — no silent fallbacks in production.
|
|
30
|
+
* No hardcoded user-facing strings outside localization system.
|
|
31
|
+
|
|
32
|
+
### UGC Canonicalization
|
|
33
|
+
|
|
34
|
+
* Separate UI language from content language.
|
|
35
|
+
* Exactly one canonical URL per UGC resource determined by content language.
|
|
36
|
+
* No indexable locale-prefixed duplicates unless primary content is truly localized; otherwise redirect to canonical.
|
|
37
|
+
* Canonical/hreflang/sitemap must reflect only true localized variants.
|
|
38
|
+
|
|
39
|
+
### SEO Requirements
|
|
40
|
+
|
|
41
|
+
* `hreflang` tags with `x-default` pointing to non-prefixed (English) version.
|
|
42
|
+
* `sitemap.xml` containing only true localized variants.
|
|
43
|
+
* Canonical URLs properly set per page.
|
|
44
|
+
* No duplicate content across locale paths.
|
|
45
|
+
|
|
46
|
+
## Domain Discovery
|
|
47
|
+
|
|
48
|
+
After reviewing compliance with spec, explore improvements:
|
|
49
|
+
|
|
50
|
+
* **Market expansion**: Are high-value markets missing? (e.g., Arabic RTL, Hindi)
|
|
51
|
+
* **Translation quality**: Are translations professional or machine-generated? User complaints?
|
|
52
|
+
* **Locale detection**: Is auto-detection helpful or annoying? Is manual switching easy?
|
|
53
|
+
* **Regional pricing**: Does i18n support regional pricing display? Currency localization?
|
|
54
|
+
* **Legal localization**: Are terms/privacy properly localized per jurisdiction?
|
|
55
|
+
* **Date/time handling**: Timezone-aware displays? User preference respected?
|
|
56
|
+
|
|
57
|
+
## Domain Gates
|
|
58
|
+
|
|
59
|
+
* [ ] All supported locales have complete translations
|
|
60
|
+
* [ ] `/en/*` returns 301 redirect to non-prefixed
|
|
61
|
+
* [ ] Missing translation keys fail build
|
|
62
|
+
* [ ] hreflang tags present and correct
|
|
63
|
+
* [ ] x-default points to non-prefixed version
|
|
64
|
+
* [ ] Sitemap contains only true localized pages
|
|
65
|
+
* [ ] UGC has single canonical URL per content
|
|
66
|
+
* [ ] No hardcoded strings in components
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-platform
|
|
3
|
+
description: SaaS frontend review - design system, SEO, PWA, performance, accessibility
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Frontend & Platform Review
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Review frontend systems: design system, SEO implementation, PWA capabilities, performance optimization, and accessibility compliance.
|
|
12
|
+
|
|
13
|
+
## Specification
|
|
14
|
+
|
|
15
|
+
### Design System & UX
|
|
16
|
+
|
|
17
|
+
* Design-system driven UI (tokens for colors, spacing, typography).
|
|
18
|
+
* Dark/light theme support with user preference persistence.
|
|
19
|
+
* **WCAG AA** accessibility compliance.
|
|
20
|
+
* CLS-safe (no layout shift).
|
|
21
|
+
* **Mobile-first** responsive design; desktop-second.
|
|
22
|
+
* Iconify for icons; no emoji in UI content.
|
|
23
|
+
|
|
24
|
+
### SEO Requirements
|
|
25
|
+
|
|
26
|
+
* **SEO-first + SSR-first** for indexable/discovery pages.
|
|
27
|
+
* Required metadata:
|
|
28
|
+
* Title and description (unique per page)
|
|
29
|
+
* Open Graph tags (og:title, og:description, og:image)
|
|
30
|
+
* Favicon (multiple sizes)
|
|
31
|
+
* Canonical URL
|
|
32
|
+
* robots meta tag
|
|
33
|
+
* `schema.org` structured data where applicable.
|
|
34
|
+
* `sitemap.xml` (auto-generated, up-to-date).
|
|
35
|
+
* `robots.txt` properly configured.
|
|
36
|
+
|
|
37
|
+
### PWA Capabilities
|
|
38
|
+
|
|
39
|
+
* Web app manifest with proper icons and theme colors.
|
|
40
|
+
* Service worker with explicit cache correctness.
|
|
41
|
+
* Push notifications using VAPID where applicable.
|
|
42
|
+
* **Service Worker caching boundary is mandatory**: service worker must not cache personalized/sensitive/authorized content.
|
|
43
|
+
* Authenticated and entitlement-sensitive routes must have explicit cache-control and SW rules.
|
|
44
|
+
* SW caching boundaries must be validated by tests to prevent stale or unauthorized state exposure.
|
|
45
|
+
|
|
46
|
+
### Performance
|
|
47
|
+
|
|
48
|
+
* Performance must be **measurable and regression-resistant**:
|
|
49
|
+
* Define and enforce performance budgets for key journeys
|
|
50
|
+
* Define caching boundaries and correctness requirements across SSR/ISR/static and service worker behavior
|
|
51
|
+
* Monitor Core Web Vitals and server latency; alert on regressions
|
|
52
|
+
* Target metrics:
|
|
53
|
+
* LCP < 2.5s
|
|
54
|
+
* FID < 100ms
|
|
55
|
+
* CLS < 0.1
|
|
56
|
+
* TTFB < 600ms
|
|
57
|
+
|
|
58
|
+
### Guidance System
|
|
59
|
+
|
|
60
|
+
* Guidance is mandatory for all user-facing features and monetization flows.
|
|
61
|
+
* Must be: discoverable, clear, dismissible with re-entry option.
|
|
62
|
+
* Localized and measurable (track engagement).
|
|
63
|
+
* Governed by eligibility and frequency controls.
|
|
64
|
+
|
|
65
|
+
## Domain Discovery
|
|
66
|
+
|
|
67
|
+
After reviewing compliance with spec, explore improvements:
|
|
68
|
+
|
|
69
|
+
* **Performance wins**: Are there obvious bundle size reductions? Lazy loading opportunities? Image optimization?
|
|
70
|
+
* **SEO gaps**: Missing structured data? Pages not indexed? Slow crawl rate?
|
|
71
|
+
* **PWA enhancement**: Is offline experience meaningful? Are push notifications valuable?
|
|
72
|
+
* **Accessibility**: Beyond AA compliance, are there UX improvements for assistive tech?
|
|
73
|
+
* **Design consistency**: Are there inconsistencies in the design system usage? Rogue styles?
|
|
74
|
+
* **Mobile experience**: Is mobile-first truly implemented? Touch targets adequate?
|
|
75
|
+
|
|
76
|
+
## Domain Gates
|
|
77
|
+
|
|
78
|
+
* [ ] Design tokens used consistently (no hardcoded values)
|
|
79
|
+
* [ ] Dark/light theme works correctly
|
|
80
|
+
* [ ] WCAG AA compliance verified
|
|
81
|
+
* [ ] All pages have unique title/description/OG tags
|
|
82
|
+
* [ ] Sitemap.xml exists and is current
|
|
83
|
+
* [ ] Schema.org markup present
|
|
84
|
+
* [ ] Service worker doesn't cache authenticated content
|
|
85
|
+
* [ ] Core Web Vitals within targets
|
|
86
|
+
* [ ] Performance budgets defined and enforced
|
|
87
|
+
* [ ] Guidance system implemented for key flows
|
|
@@ -1,275 +1,178 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: saas-review
|
|
3
|
-
description: Full-stack SaaS product review -
|
|
3
|
+
description: Full-stack SaaS product review - master orchestrator
|
|
4
4
|
agent: coder
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# SaaS Product Review — Master Orchestration
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Mandate
|
|
10
10
|
|
|
11
|
-
* Perform a complete end-to-end review across product, engineering, security, compliance, growth, operations, and UX.
|
|
11
|
+
* Perform a **complete end-to-end review** across product, engineering, security, compliance, growth, operations, and UX.
|
|
12
12
|
* **Delegate work to multiple workers; you act as the final gate to improve quality.**
|
|
13
|
-
* Deliverables must be stated as **standards, constraints, and acceptance criteria
|
|
14
|
-
* **Single-pass delivery**: no roadmap, no phasing, no deferrals; deliver an integrated outcome
|
|
15
|
-
* **Exploration required**: the review must not be limited to this document; identify additional improvements for competitiveness, completeness, usability, reliability, and monetization within fixed constraints.
|
|
13
|
+
* Deliverables must be stated as **standards, constraints, and acceptance criteria**.
|
|
14
|
+
* **Single-pass delivery**: no roadmap, no phasing, no deferrals; deliver an integrated outcome.
|
|
16
15
|
|
|
17
|
-
##
|
|
16
|
+
## Non-Negotiable Engineering Principles
|
|
18
17
|
|
|
19
18
|
* No workarounds, hacks, or TODOs.
|
|
20
19
|
* Feature-first with clean architecture; designed for easy extension; no "god files".
|
|
21
20
|
* Type-first, strict end-to-end correctness (**DB → API → UI**).
|
|
22
|
-
* Serverless-first
|
|
21
|
+
* Serverless-first; edge-compatible where feasible without sacrificing correctness, security, or observability.
|
|
23
22
|
* Mobile-first responsive design; desktop-second.
|
|
24
23
|
* Precise naming; remove dead/unused code.
|
|
25
24
|
* Upgrade all packages to latest stable; avoid deprecated patterns.
|
|
26
25
|
|
|
27
|
-
##
|
|
26
|
+
## Fixed Platform & Stack (Locked)
|
|
28
27
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
28
|
+
| Layer | Technology |
|
|
29
|
+
|-------|------------|
|
|
30
|
+
| Platform | Vercel |
|
|
31
|
+
| Framework | Next.js (SSR-first) |
|
|
32
|
+
| API | tRPC |
|
|
33
|
+
| i18n | next-intl |
|
|
34
|
+
| Database | Neon (Postgres) |
|
|
35
|
+
| ORM | Drizzle |
|
|
36
|
+
| Auth | better-auth |
|
|
37
|
+
| Payments | Stripe |
|
|
38
|
+
| Email | Resend |
|
|
39
|
+
| Observability | Sentry |
|
|
40
|
+
| Analytics | PostHog |
|
|
41
|
+
| Cache/Workflows | Upstash Redis + Workflows + QStash |
|
|
42
|
+
| Storage | Vercel Blob |
|
|
43
|
+
| Tooling | Bun, Biome, Bun test |
|
|
44
|
+
| Tag Management | GTM (marketing only) |
|
|
43
45
|
|
|
44
|
-
##
|
|
46
|
+
## Review Execution
|
|
45
47
|
|
|
46
|
-
###
|
|
48
|
+
### Phase 1: Domain Reviews (Parallel)
|
|
47
49
|
|
|
48
|
-
|
|
49
|
-
* All authorization/entitlements are **server-enforced**; no client-trust.
|
|
50
|
-
* Runtime constraints (serverless/edge) must be explicit and validated.
|
|
51
|
-
* **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).
|
|
52
|
-
* **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.
|
|
53
|
-
* **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.
|
|
54
|
-
* **Server-truth is authoritative**: UI state must never contradict server-truth. Where asynchronous confirmation exists, UI must represent that state unambiguously and remain explainable.
|
|
55
|
-
* **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.
|
|
56
|
-
|
|
57
|
-
### 4.2 Drizzle Migrations (Non-Negotiable)
|
|
58
|
-
|
|
59
|
-
* Migration files must exist, be complete, and be committed.
|
|
60
|
-
* Deterministic, reproducible, environment-safe; linear/auditable history; no drift.
|
|
61
|
-
* CI must fail if schema changes are not represented by migrations.
|
|
62
|
-
|
|
63
|
-
### 4.3 Financial-Grade Balance System (Only if "balance/credits/wallet" exists)
|
|
64
|
-
|
|
65
|
-
* Any balance concept must be implemented as an **immutable ledger** (append-only source of truth), not a mutable balance field.
|
|
66
|
-
* Deterministic precision (no floats), idempotent posting, concurrency safety, transactional integrity, and auditability are required.
|
|
67
|
-
* Monetary flows must be currency-based and reconcilable with Stripe; credits (if used) must be governed as non-cash entitlements.
|
|
68
|
-
|
|
69
|
-
### 4.4 Vercel Blob Upload Governance (Hard Requirement)
|
|
70
|
-
|
|
71
|
-
* All uploads must be **intent-based and server-verified**.
|
|
72
|
-
* The client must upload to Vercel Blob first using short-lived, server-issued authorization (e.g., signed upload URL / token), then call a server finalize endpoint to persist the resulting Blob URL/key.
|
|
73
|
-
* The server must validate the Blob URL/key ownership and namespace, and must match it against the originating upload intent (who/what/where/expiry/constraints) before attaching it to any resource.
|
|
74
|
-
* The system must support safe retries and idempotent finalize; expired/abandoned intents must be cleanable and auditable.
|
|
75
|
-
|
|
76
|
-
## 5) Internationalization, Routing, and Canonicalization (Keep Precise)
|
|
77
|
-
|
|
78
|
-
### 5.1 Supported Locales
|
|
79
|
-
|
|
80
|
-
`en`, `zh-Hans`, `zh-Hant`, `es`, `ja`, `ko`, `de`, `fr`, `pt-BR`, `it`, `nl`, `pl`, `tr`, `id`, `th`, `vi`
|
|
81
|
-
|
|
82
|
-
### 5.2 URL Strategy: Prefix Except Default
|
|
83
|
-
|
|
84
|
-
* English is default and non-prefixed.
|
|
85
|
-
* `/en/*` must not exist; permanently redirect to non-prefixed equivalent.
|
|
86
|
-
* All non-default locales are `/<locale>/...`.
|
|
87
|
-
|
|
88
|
-
### 5.3 Globalization Rules
|
|
89
|
-
|
|
90
|
-
* Intl formatting; explicit fallback rules.
|
|
91
|
-
* Missing translation keys must fail build.
|
|
92
|
-
* No hardcoded user-facing strings outside localization.
|
|
93
|
-
|
|
94
|
-
### 5.4 UGC Canonicalization
|
|
95
|
-
|
|
96
|
-
* Separate UI language from content language.
|
|
97
|
-
* Exactly one canonical URL per UGC resource determined by content language.
|
|
98
|
-
* No indexable locale-prefixed duplicates unless primary content is truly localized; otherwise redirect to canonical.
|
|
99
|
-
* Canonical/hreflang/sitemap must reflect only true localized variants.
|
|
100
|
-
|
|
101
|
-
## 6) Product Systems (Capabilities + Governance)
|
|
102
|
-
|
|
103
|
-
### 6.1 Membership and Account Security
|
|
104
|
-
|
|
105
|
-
* Membership is entitlement-driven and server-enforced.
|
|
106
|
-
* Provide a dedicated **Account Security** surface.
|
|
107
|
-
* **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.
|
|
108
|
-
|
|
109
|
-
### 6.2 Identity, Verification, and Sign-in
|
|
110
|
-
|
|
111
|
-
* SSO providers (minimum): **Google, Apple, Facebook, Microsoft, GitHub** (prioritize by audience).
|
|
112
|
-
* If provider env/secrets are missing, **hide** the login option (no broken/disabled UI).
|
|
113
|
-
* Allow linking multiple providers and safe unlinking; server-enforced and abuse-protected.
|
|
114
|
-
* Passkeys (WebAuthn) are first-class with secure enrollment/usage/recovery.
|
|
115
|
-
* Verification:
|
|
50
|
+
Delegate each domain to a worker agent. Workers should review compliance with spec AND identify domain-specific improvement opportunities.
|
|
116
51
|
|
|
117
|
-
|
|
118
|
-
|
|
52
|
+
| Worker | Command | Focus |
|
|
53
|
+
|--------|---------|-------|
|
|
54
|
+
| Billing | `/saas-billing` | Stripe, webhooks, pricing governance, ledger |
|
|
55
|
+
| Auth | `/saas-auth` | SSO, passkeys, verification, sessions, account security |
|
|
56
|
+
| i18n | `/saas-i18n` | Locales, routing, canonicalization, hreflang |
|
|
57
|
+
| Platform | `/saas-platform` | Design system, SEO, PWA, performance, a11y |
|
|
58
|
+
| Security | `/saas-security` | OWASP, privacy, consent, observability, operability |
|
|
59
|
+
| Growth | `/saas-growth` | Onboarding, referral, retention, guidance |
|
|
119
60
|
|
|
120
|
-
###
|
|
61
|
+
### Phase 2: Strategic Discovery
|
|
121
62
|
|
|
122
|
-
|
|
123
|
-
* **Billing state machine follows §4.1 mapping requirements**; UI must only surface explainable, non-ambiguous states aligned to server-truth.
|
|
124
|
-
* Webhooks must be idempotent, retry-safe, out-of-order safe, auditable; billing UI reflects server-truth state without ambiguity.
|
|
125
|
-
* **Webhook trust is mandatory (high-risk)**: 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.
|
|
126
|
-
* **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), and must use the §4.1 consistency model to define final-state decision rules.
|
|
127
|
-
* Tax/invoicing and refund/dispute handling must be behaviorally consistent with product UX and entitlement state.
|
|
128
|
-
* **Stripe pricing governance is mandatory (Stripe-first, not Dashboard-first)**:
|
|
63
|
+
After domain reviews complete, run cross-domain strategic analysis:
|
|
129
64
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
* An operational-grade Pricing Admin must exist to manage creation of new Stripe Prices, activation/deactivation of sellable prices, and (optionally) controlled bulk subscription migrations; all actions must be governed by RBAC, step-up controls, and audit logs.
|
|
134
|
-
* Stripe Dashboard is treated as monitoring/emergency access; non-admin Stripe changes must be detectable (drift), alertable, and remediable.
|
|
65
|
+
| Worker | Command | Focus |
|
|
66
|
+
|--------|---------|-------|
|
|
67
|
+
| Discovery | `/saas-discovery` | Feature opportunities, pricing optimization, competitive research |
|
|
135
68
|
|
|
136
|
-
###
|
|
69
|
+
### Phase 3: Final Gate (You)
|
|
137
70
|
|
|
138
|
-
|
|
139
|
-
* Admin bootstrap must not rely on file seeding:
|
|
71
|
+
Synthesize all domain findings and discovery insights:
|
|
140
72
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
* **Configuration management is mandatory**:
|
|
73
|
+
1. **Aggregate findings** from all workers
|
|
74
|
+
2. **Resolve conflicts** between domains
|
|
75
|
+
3. **Verify delivery gates** (below)
|
|
76
|
+
4. **Produce integrated report** with prioritized actions
|
|
146
77
|
|
|
147
|
-
|
|
148
|
-
* Secrets/credentials are environment-managed only; admin may expose safe readiness/health visibility, not raw secrets.
|
|
149
|
-
* **Admin analytics and reporting are mandatory**:
|
|
78
|
+
## Architecture Foundations (All Domains)
|
|
150
79
|
|
|
151
|
-
|
|
152
|
-
* Reporting must be consistent with system-of-record truth (billing/webhooks, ledger, entitlements) and auditable when derived from privileged actions.
|
|
153
|
-
* **Admin operational management is mandatory**:
|
|
80
|
+
These principles apply across all domain reviews:
|
|
154
81
|
|
|
155
|
-
|
|
156
|
-
* Actions affecting access, money/credits, or security posture require appropriate step-up controls and must be fully auditable; reversibility must follow domain rules.
|
|
82
|
+
### Server Enforcement
|
|
157
83
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
* Support/Contact surface must be discoverable, localized, WCAG AA, SEO-complete, privacy-safe, and auditable where relevant.
|
|
161
|
-
* Newsletter subscription/preferences must be consent-aware; unsubscribe enforcement must be reliable.
|
|
162
|
-
|
|
163
|
-
### 6.6 Referral (Anti-Abuse Baseline Required)
|
|
164
|
-
|
|
165
|
-
* Referral must be measurable, abuse-resistant, and governed:
|
|
166
|
-
|
|
167
|
-
* attribution semantics, reward lifecycle governance (including revocation/clawbacks), anti-fraud, admin reporting/audit,
|
|
168
|
-
* localized and instrumented.
|
|
169
|
-
* **Referral anti-fraud minimum baseline is mandatory**:
|
|
170
|
-
|
|
171
|
-
* define a minimum set of risk signals and enforcement measures, including velocity controls, account/device linkage posture, risk-tiered enforcement, reward delay/hold/freeze, clawback conditions, and an auditable manual review/appeal posture where applicable.
|
|
172
|
-
|
|
173
|
-
## 7) UX, Design System, and Guidance
|
|
174
|
-
|
|
175
|
-
* Design-system driven UI (tokens), dark/light theme, WCAG AA, CLS-safe, responsive.
|
|
176
|
-
* Iconify; no emoji in UI content.
|
|
177
|
-
* Guidance is mandatory for all user-facing features and monetization flows: discoverable, clear, dismissible with re-entry, localized and measurable, governed by eligibility and frequency controls.
|
|
178
|
-
|
|
179
|
-
## 8) Web Platform: SEO, PWA, Performance
|
|
180
|
-
|
|
181
|
-
* SEO-first + SSR-first for indexable/discovery.
|
|
182
|
-
* Required: metadata + Open Graph + favicon; canonical; hreflang + x-default; schema.org; sitemap.xml; robots.txt.
|
|
183
|
-
* PWA: manifest, service worker with explicit cache correctness; push notifications using VAPID where applicable.
|
|
184
|
-
* **Service Worker caching boundary is mandatory**: service worker must not cache personalized/sensitive/authorized content. Authenticated and entitlement-sensitive routes must have explicit cache-control and SW rules, and must be validated by tests to prevent stale or unauthorized state exposure.
|
|
185
|
-
* Performance must be **measurable and regression-resistant**:
|
|
186
|
-
|
|
187
|
-
* define and enforce performance budgets for key journeys,
|
|
188
|
-
* define caching boundaries and correctness requirements across SSR/ISR/static and service worker behavior,
|
|
189
|
-
* monitor Core Web Vitals and server latency; alert on regressions.
|
|
190
|
-
|
|
191
|
-
## 9) Growth System (Onboarding, Share/Viral, Retention)
|
|
192
|
-
|
|
193
|
-
* The review must produce a coherent, measurable growth system for activation, sharing/virality, and retention, aligned with compliance and anti-abuse constraints.
|
|
194
|
-
* Onboarding must be outcome-oriented, localized, accessible, and instrumented.
|
|
195
|
-
* Sharing/virality must be consent-aware, abuse-resistant, and measurable end-to-end.
|
|
196
|
-
* Retention must be intentionally engineered, monitored, and protected against regressions.
|
|
197
|
-
|
|
198
|
-
## 10) Trust, Safety, Security, Privacy, Compliance, and Operability
|
|
199
|
-
|
|
200
|
-
* **Behavioral consistency is required**: policy and disclosures must match actual behavior across UI, data handling, logging/observability, analytics, support operations, and marketing tags; mismatches are release-blocking.
|
|
201
|
-
* **Consent governance is mandatory (release-blocking)**:
|
|
202
|
-
|
|
203
|
-
* Analytics (PostHog) and marketing/newsletter communications (Resend) must be governed by consent and user preferences.
|
|
204
|
-
* Marketing tags (including GTM and Google Ads) must not load or fire without the appropriate consent.
|
|
205
|
-
* Without consent, tracking and marketing sends must not occur, except for strictly necessary service communications.
|
|
206
|
-
* Event schemas and attributes must follow data minimization, with explicit PII classification and handling rules.
|
|
207
|
-
* **Marketing attribution and conversions are governed (hard requirement)**:
|
|
208
|
-
|
|
209
|
-
* GTM may be used **only** for marketing tags and attribution; it must not become the primary product analytics system (PostHog remains the product analytics source).
|
|
210
|
-
* Conversions representing monetary value or entitlement changes must be **server-truth aligned**, **idempotent**, and **deduplicated**; client-side tags may exist for attribution but must not become the authoritative source of billing/entitlement truth.
|
|
211
|
-
* **PII and sensitive data controls apply everywhere (hard requirement)**:
|
|
212
|
-
|
|
213
|
-
* PII rules apply to logs, Sentry, PostHog, support tooling, email systems, and marketing tags/conversion payloads.
|
|
214
|
-
* A consistent scrubbing/redaction standard must exist, and must be covered by automated tests to prevent leakage to third parties.
|
|
215
|
-
* Data lifecycle must be explicit and enforceable:
|
|
216
|
-
|
|
217
|
-
* define deletion/deactivation semantics, deletion propagation, export where applicable, DR/backup posture aligned with retention,
|
|
218
|
-
* **define data classification, retention periods, deletion propagation to third-party processors, and explicit exceptions** (legal/tax/anti-fraud), and ensure external disclosures match behavior.
|
|
219
|
-
* Abuse/fraud posture (especially referral/UGC/support): define prevention and enforcement measures; risk signals trigger protective actions and step-up verification where appropriate.
|
|
220
|
-
* Account/session security management: session/device visibility + revocation, security event visibility, recovery governance (including support-assisted recovery) with strict audit logging; step-up for sensitive actions.
|
|
221
|
-
* **Async/workflows are governed (hard requirement)**:
|
|
222
|
-
|
|
223
|
-
* define idempotency and deduplication posture,
|
|
224
|
-
* define controlled retries/backoff,
|
|
225
|
-
* **dead-letter handling must exist and be observable and operable**,
|
|
226
|
-
* **safe replay must be supported**,
|
|
227
|
-
* side-effects (email/billing/ledger/entitlements) must be governed such that they are either proven effectively-once or safely re-entrant without duplicated economic/security consequences.
|
|
228
|
-
* Release safety: define safe rollout posture with backward compatibility and rollback expectations for billing/ledger/auth changes.
|
|
229
|
-
* **Observability and alerting are mandatory (hard requirement)**:
|
|
230
|
-
|
|
231
|
-
* structured logs and correlation IDs must exist end-to-end (request/job/webhook) with consistent traceability,
|
|
232
|
-
* define critical-path SLO/SLI posture,
|
|
233
|
-
* define actionable alerts for webhook failures, ledger/entitlement drift, authentication attacks, abuse spikes, and drift detection.
|
|
234
|
-
* **Configuration and secrets governance is mandatory**:
|
|
235
|
-
|
|
236
|
-
* required configuration must fail-fast at build/startup,
|
|
237
|
-
* strict environment isolation (dev/stage/prod),
|
|
238
|
-
* rotation and incident remediation posture must be auditable and exercisable.
|
|
239
|
-
* **Drift detection must be remediable (hard requirement)**:
|
|
240
|
-
|
|
241
|
-
* drift alerts must have a defined remediation playbook (automated fix or operator workflow),
|
|
242
|
-
* each remediation must be auditable and support post-incident traceability.
|
|
243
|
-
* Security baseline:
|
|
84
|
+
* All authorization/entitlements are **server-enforced**; no client-trust.
|
|
85
|
+
* **Server-truth is authoritative**: UI state must never contradict server-truth.
|
|
244
86
|
|
|
245
|
-
|
|
246
|
-
* Password UX masked + temporary reveal; no plaintext passwords in logs/returns/storage/telemetry.
|
|
247
|
-
* MFA for Admin/SUPER_ADMIN; step-up for high-risk.
|
|
248
|
-
* Risk-based anti-bot for auth and high-cost endpoints; integrate rate limits + consent gating.
|
|
249
|
-
* Baseline controls: CSP/HSTS/headers, CSRF where applicable, Upstash-backed rate limiting, PII scrubbing, supply-chain hygiene, measurable security.
|
|
250
|
-
* **Security controls must be verifiable**: CSP/HSTS/security headers and CSRF (where applicable) must be covered by automated checks or security tests and included in release gates.
|
|
87
|
+
### Consistency Model
|
|
251
88
|
|
|
252
|
-
|
|
89
|
+
* For billing, entitlements, ledger, admin privileges, and security posture: define explicit consistency model (source-of-truth, delay windows, retry handling).
|
|
253
90
|
|
|
254
|
-
|
|
255
|
-
* Pricing/monetization review: packaging/entitlements, lifecycle semantics, legal/tax/invoice implications; propose conversion/churn improvements within constraints.
|
|
256
|
-
* Competitive research: features, extensibility, guidance patterns, pricing/packaging norms; convert insights into testable acceptance criteria.
|
|
91
|
+
### Drizzle Migrations
|
|
257
92
|
|
|
258
|
-
|
|
93
|
+
* Migration files must exist, be complete, and be committed.
|
|
94
|
+
* Deterministic, reproducible, environment-safe; linear/auditable history; no drift.
|
|
95
|
+
* CI must fail if schema changes are not represented by migrations.
|
|
259
96
|
|
|
260
|
-
|
|
97
|
+
### Vercel Blob Upload Governance
|
|
261
98
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
*
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
99
|
+
* All uploads must be **intent-based and server-verified**.
|
|
100
|
+
* Client uploads via short-lived, server-issued authorization, then calls server finalize endpoint.
|
|
101
|
+
* Server validates Blob URL/key ownership and matches against originating intent before attaching to any resource.
|
|
102
|
+
* Support safe retries and idempotent finalize; expired/abandoned intents must be cleanable and auditable.
|
|
103
|
+
|
|
104
|
+
### Auditability
|
|
105
|
+
|
|
106
|
+
* For any high-value mutation: who/when/why, before/after state, and correlation to triggering request/job/webhook must be recorded and queryable.
|
|
107
|
+
|
|
108
|
+
## Delivery Gates (Release-Blocking)
|
|
109
|
+
|
|
110
|
+
CI must block merges/deploys when failing:
|
|
111
|
+
|
|
112
|
+
### Code Quality
|
|
113
|
+
- [ ] Biome lint/format passes
|
|
114
|
+
- [ ] Strict TypeScript typecheck passes
|
|
115
|
+
- [ ] Unit + E2E tests pass (Bun test)
|
|
116
|
+
- [ ] Build succeeds
|
|
117
|
+
|
|
118
|
+
### Data Integrity
|
|
119
|
+
- [ ] Migration integrity checks pass
|
|
120
|
+
- [ ] No schema drift
|
|
121
|
+
|
|
122
|
+
### Internationalization
|
|
123
|
+
- [ ] Missing translation keys fail build
|
|
124
|
+
- [ ] `/en/*` returns 301 redirect
|
|
125
|
+
- [ ] hreflang/x-default correct
|
|
126
|
+
- [ ] Sitemap contains only true localized pages
|
|
127
|
+
|
|
128
|
+
### Performance
|
|
129
|
+
- [ ] Performance budgets enforced
|
|
130
|
+
- [ ] Core Web Vitals within targets
|
|
131
|
+
- [ ] Regression detection active
|
|
132
|
+
|
|
133
|
+
### Security
|
|
134
|
+
- [ ] CSP/HSTS/security headers verified
|
|
135
|
+
- [ ] CSRF protection tested
|
|
136
|
+
- [ ] Consent gates analytics/marketing
|
|
137
|
+
|
|
138
|
+
### Operability
|
|
139
|
+
- [ ] Observability configured for critical paths
|
|
140
|
+
- [ ] Alerting defined for anomalies
|
|
141
|
+
- [ ] DLQ is operable with safe replay
|
|
142
|
+
|
|
143
|
+
### Release Criteria
|
|
144
|
+
- [ ] Required configuration fails fast if missing
|
|
145
|
+
- [ ] All domain gates pass
|
|
146
|
+
- [ ] No TODOs/hacks/workarounds/dead code
|
|
147
|
+
|
|
148
|
+
## Output Format
|
|
149
|
+
|
|
150
|
+
### Executive Summary
|
|
151
|
+
- Overall health assessment
|
|
152
|
+
- Critical blockers (must fix before release)
|
|
153
|
+
- High-priority improvements
|
|
154
|
+
|
|
155
|
+
### Domain Reports
|
|
156
|
+
For each domain, summarize:
|
|
157
|
+
- Compliance status (pass/fail with details)
|
|
158
|
+
- Improvement opportunities discovered
|
|
159
|
+
- Recommended actions with priority
|
|
160
|
+
|
|
161
|
+
### Strategic Opportunities
|
|
162
|
+
From discovery phase:
|
|
163
|
+
- Feature roadmap (prioritized)
|
|
164
|
+
- Pricing optimizations
|
|
165
|
+
- Competitive positioning
|
|
166
|
+
|
|
167
|
+
### Delivery Gate Status
|
|
168
|
+
Checklist with pass/fail for each gate
|
|
169
|
+
|
|
170
|
+
## Completion Criteria
|
|
171
|
+
|
|
172
|
+
Complete only when:
|
|
173
|
+
- [ ] All domain reviews finished
|
|
174
|
+
- [ ] Discovery phase completed
|
|
175
|
+
- [ ] All findings synthesized
|
|
176
|
+
- [ ] Delivery gates verified
|
|
177
|
+
- [ ] Integrated report produced
|
|
178
|
+
- [ ] No deferrals — everything addressed in single pass
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: saas-security
|
|
3
|
+
description: SaaS security review - OWASP, privacy, consent, observability, operability
|
|
4
|
+
agent: coder
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Security, Privacy & Compliance Review
|
|
8
|
+
|
|
9
|
+
## Scope
|
|
10
|
+
|
|
11
|
+
Review security posture, privacy compliance, consent governance, observability systems, and operational readiness.
|
|
12
|
+
|
|
13
|
+
## Specification
|
|
14
|
+
|
|
15
|
+
### Security Baseline
|
|
16
|
+
|
|
17
|
+
* **OWASP Top 10:2025** taxonomy awareness and mitigation.
|
|
18
|
+
* **OWASP ASVS** (L2/L3) verification baseline.
|
|
19
|
+
* Baseline controls:
|
|
20
|
+
* CSP (Content Security Policy) properly configured
|
|
21
|
+
* HSTS with appropriate max-age
|
|
22
|
+
* Security headers (X-Frame-Options, X-Content-Type-Options, etc.)
|
|
23
|
+
* CSRF protection where applicable
|
|
24
|
+
* Upstash-backed rate limiting
|
|
25
|
+
* Supply-chain hygiene (dependency audits)
|
|
26
|
+
* **Security controls must be verifiable**: CSP/HSTS/security headers and CSRF must be covered by automated checks or security tests and included in release gates.
|
|
27
|
+
* Risk-based anti-bot for auth and high-cost endpoints; integrate rate limits + consent gating.
|
|
28
|
+
|
|
29
|
+
### Consent Governance (Release-Blocking)
|
|
30
|
+
|
|
31
|
+
* **Behavioral consistency is required**: policy and disclosures must match actual behavior across UI, data handling, logging/observability, analytics, support operations, and marketing tags; mismatches are release-blocking.
|
|
32
|
+
* Analytics (PostHog) and marketing/newsletter communications (Resend) must be governed by consent and user preferences.
|
|
33
|
+
* Marketing tags (including GTM and Google Ads) must not load or fire without appropriate consent.
|
|
34
|
+
* Without consent, tracking and marketing sends must not occur, except for strictly necessary service communications.
|
|
35
|
+
* Event schemas and attributes must follow data minimization, with explicit PII classification and handling rules.
|
|
36
|
+
|
|
37
|
+
### Marketing Attribution (Hard Requirement)
|
|
38
|
+
|
|
39
|
+
* GTM may be used **only** for marketing tags and attribution; it must not become the primary product analytics system (PostHog remains the product analytics source).
|
|
40
|
+
* Conversions representing monetary value or entitlement changes must be **server-truth aligned**, **idempotent**, and **deduplicated**; client-side tags may exist for attribution but must not become the authoritative source of billing/entitlement truth.
|
|
41
|
+
|
|
42
|
+
### PII and Sensitive Data (Hard Requirement)
|
|
43
|
+
|
|
44
|
+
* PII rules apply to logs, Sentry, PostHog, support tooling, email systems, and marketing tags/conversion payloads.
|
|
45
|
+
* A consistent scrubbing/redaction standard must exist, and must be covered by automated tests to prevent leakage to third parties.
|
|
46
|
+
|
|
47
|
+
### Data Lifecycle
|
|
48
|
+
|
|
49
|
+
* Define deletion/deactivation semantics and deletion propagation.
|
|
50
|
+
* Export capability where applicable.
|
|
51
|
+
* DR/backup posture aligned with retention.
|
|
52
|
+
* **Define data classification, retention periods, deletion propagation to third-party processors, and explicit exceptions** (legal/tax/anti-fraud).
|
|
53
|
+
* External disclosures must match actual behavior.
|
|
54
|
+
|
|
55
|
+
### Async/Workflows Governance (Hard Requirement)
|
|
56
|
+
|
|
57
|
+
* Define idempotency and deduplication posture.
|
|
58
|
+
* Define controlled retries/backoff.
|
|
59
|
+
* **Dead-letter handling must exist and be observable and operable**.
|
|
60
|
+
* **Safe replay must be supported**.
|
|
61
|
+
* Side-effects (email/billing/ledger/entitlements) must be governed such that they are either proven effectively-once or safely re-entrant without duplicated economic/security consequences.
|
|
62
|
+
|
|
63
|
+
### Observability and Alerting (Hard Requirement)
|
|
64
|
+
|
|
65
|
+
* Structured logs and correlation IDs must exist end-to-end (request/job/webhook) with consistent traceability.
|
|
66
|
+
* Define critical-path SLO/SLI posture.
|
|
67
|
+
* Define actionable alerts for: webhook failures, ledger/entitlement drift, authentication attacks, abuse spikes, and drift detection.
|
|
68
|
+
|
|
69
|
+
### Configuration and Secrets
|
|
70
|
+
|
|
71
|
+
* Required configuration must fail-fast at build/startup.
|
|
72
|
+
* Strict environment isolation (dev/stage/prod).
|
|
73
|
+
* Rotation and incident remediation posture must be auditable and exercisable.
|
|
74
|
+
|
|
75
|
+
### Drift Detection (Hard Requirement)
|
|
76
|
+
|
|
77
|
+
* Drift alerts must have a defined remediation playbook (automated fix or operator workflow).
|
|
78
|
+
* Each remediation must be auditable and support post-incident traceability.
|
|
79
|
+
|
|
80
|
+
### Abuse/Fraud Posture
|
|
81
|
+
|
|
82
|
+
* Define prevention and enforcement measures for referral/UGC/support abuse.
|
|
83
|
+
* Risk signals trigger protective actions and step-up verification where appropriate.
|
|
84
|
+
|
|
85
|
+
## Domain Discovery
|
|
86
|
+
|
|
87
|
+
After reviewing compliance with spec, explore improvements:
|
|
88
|
+
|
|
89
|
+
* **Attack surface reduction**: Are there unused endpoints? Overly permissive APIs?
|
|
90
|
+
* **Monitoring gaps**: What security events aren't being tracked? Alert fatigue issues?
|
|
91
|
+
* **Compliance readiness**: Is SOC2/GDPR/CCPA posture documented? Audit-ready?
|
|
92
|
+
* **Incident response**: Is there a playbook? Has it been tested?
|
|
93
|
+
* **Third-party risk**: Are vendor dependencies assessed? Data processing agreements in place?
|
|
94
|
+
* **Security UX**: Are security features discoverable? Do they create unnecessary friction?
|
|
95
|
+
|
|
96
|
+
## Domain Gates
|
|
97
|
+
|
|
98
|
+
* [ ] CSP/HSTS/security headers configured and tested
|
|
99
|
+
* [ ] CSRF protection implemented where needed
|
|
100
|
+
* [ ] Rate limiting active on sensitive endpoints
|
|
101
|
+
* [ ] Consent governs all analytics/marketing
|
|
102
|
+
* [ ] PII scrubbing verified (logs, Sentry, PostHog)
|
|
103
|
+
* [ ] Data deletion propagates to third parties
|
|
104
|
+
* [ ] DLQ exists and is operable
|
|
105
|
+
* [ ] Correlation IDs present end-to-end
|
|
106
|
+
* [ ] Critical alerts defined and tested
|
|
107
|
+
* [ ] Config fails fast on missing required values
|
|
108
|
+
* [ ] Drift detection has remediation playbook
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sylphx/flow",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.7.0",
|
|
4
4
|
"description": "One CLI to rule them all. Unified orchestration layer for Claude Code, OpenCode, Cursor and all AI development tools. Auto-detection, auto-installation, auto-upgrade.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|