agy-superpowers 5.2.2 → 5.2.3
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/README.md +47 -150
- package/package.json +1 -1
- package/template/agent/rules/scratch-scripts.md +37 -0
- package/template/agent/rules/superpowers.md +4 -51
- package/template/agent/skills/ai-integrated-product/SKILL.md +0 -57
- package/template/agent/skills/analytics-setup/SKILL.md +0 -51
- package/template/agent/skills/api-design/SKILL.md +0 -193
- package/template/agent/skills/app-store-optimizer/SKILL.md +0 -127
- package/template/agent/skills/auth-and-identity/SKILL.md +0 -167
- package/template/agent/skills/backend-developer/SKILL.md +0 -148
- package/template/agent/skills/bootstrapper-finance/SKILL.md +0 -55
- package/template/agent/skills/chrome-extension-developer/SKILL.md +0 -53
- package/template/agent/skills/community-manager/SKILL.md +0 -115
- package/template/agent/skills/content-marketer/SKILL.md +0 -111
- package/template/agent/skills/conversion-optimizer/SKILL.md +0 -142
- package/template/agent/skills/cto-architect/SKILL.md +0 -133
- package/template/agent/skills/customer-success-manager/SKILL.md +0 -126
- package/template/agent/skills/data-analyst/SKILL.md +0 -147
- package/template/agent/skills/devops-engineer/SKILL.md +0 -117
- package/template/agent/skills/email-infrastructure/SKILL.md +0 -164
- package/template/agent/skills/game-design/SKILL.md +0 -194
- package/template/agent/skills/game-developer/SKILL.md +0 -175
- package/template/agent/skills/growth-hacker/SKILL.md +0 -122
- package/template/agent/skills/idea-validator/SKILL.md +0 -55
- package/template/agent/skills/indie-legal/SKILL.md +0 -53
- package/template/agent/skills/influencer-marketer/SKILL.md +0 -141
- package/template/agent/skills/landing-page-builder/SKILL.md +0 -59
- package/template/agent/skills/launch-strategist/SKILL.md +0 -62
- package/template/agent/skills/market-researcher/SKILL.md +0 -53
- package/template/agent/skills/micro-saas-builder/SKILL.md +0 -56
- package/template/agent/skills/monetization-strategist/SKILL.md +0 -119
- package/template/agent/skills/paid-acquisition-specialist/SKILL.md +0 -119
- package/template/agent/skills/pricing-psychologist/SKILL.md +0 -58
- package/template/agent/skills/real-time-features/SKILL.md +0 -194
- package/template/agent/skills/retention-specialist/SKILL.md +0 -123
- package/template/agent/skills/rust-developer/SKILL.md +0 -281
- package/template/agent/skills/rust-developer/references/rust-rules/_sections.md +0 -231
- package/template/agent/skills/rust-developer/references/rust-rules/anti-clone-excessive.md +0 -124
- package/template/agent/skills/rust-developer/references/rust-rules/anti-collect-intermediate.md +0 -131
- package/template/agent/skills/rust-developer/references/rust-rules/anti-empty-catch.md +0 -132
- package/template/agent/skills/rust-developer/references/rust-rules/anti-expect-lazy.md +0 -95
- package/template/agent/skills/rust-developer/references/rust-rules/anti-format-hot-path.md +0 -141
- package/template/agent/skills/rust-developer/references/rust-rules/anti-index-over-iter.md +0 -125
- package/template/agent/skills/rust-developer/references/rust-rules/anti-lock-across-await.md +0 -127
- package/template/agent/skills/rust-developer/references/rust-rules/anti-over-abstraction.md +0 -120
- package/template/agent/skills/rust-developer/references/rust-rules/anti-panic-expected.md +0 -131
- package/template/agent/skills/rust-developer/references/rust-rules/anti-premature-optimize.md +0 -156
- package/template/agent/skills/rust-developer/references/rust-rules/anti-string-for-str.md +0 -122
- package/template/agent/skills/rust-developer/references/rust-rules/anti-stringly-typed.md +0 -167
- package/template/agent/skills/rust-developer/references/rust-rules/anti-type-erasure.md +0 -134
- package/template/agent/skills/rust-developer/references/rust-rules/anti-unwrap-abuse.md +0 -143
- package/template/agent/skills/rust-developer/references/rust-rules/anti-vec-for-slice.md +0 -121
- package/template/agent/skills/rust-developer/references/rust-rules/api-builder-must-use.md +0 -143
- package/template/agent/skills/rust-developer/references/rust-rules/api-builder-pattern.md +0 -187
- package/template/agent/skills/rust-developer/references/rust-rules/api-common-traits.md +0 -165
- package/template/agent/skills/rust-developer/references/rust-rules/api-default-impl.md +0 -177
- package/template/agent/skills/rust-developer/references/rust-rules/api-extension-trait.md +0 -163
- package/template/agent/skills/rust-developer/references/rust-rules/api-from-not-into.md +0 -146
- package/template/agent/skills/rust-developer/references/rust-rules/api-impl-asref.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/api-impl-into.md +0 -160
- package/template/agent/skills/rust-developer/references/rust-rules/api-must-use.md +0 -125
- package/template/agent/skills/rust-developer/references/rust-rules/api-newtype-safety.md +0 -162
- package/template/agent/skills/rust-developer/references/rust-rules/api-non-exhaustive.md +0 -177
- package/template/agent/skills/rust-developer/references/rust-rules/api-parse-dont-validate.md +0 -184
- package/template/agent/skills/rust-developer/references/rust-rules/api-sealed-trait.md +0 -168
- package/template/agent/skills/rust-developer/references/rust-rules/api-serde-optional.md +0 -182
- package/template/agent/skills/rust-developer/references/rust-rules/api-typestate.md +0 -199
- package/template/agent/skills/rust-developer/references/rust-rules/async-bounded-channel.md +0 -175
- package/template/agent/skills/rust-developer/references/rust-rules/async-broadcast-pubsub.md +0 -185
- package/template/agent/skills/rust-developer/references/rust-rules/async-cancellation-token.md +0 -203
- package/template/agent/skills/rust-developer/references/rust-rules/async-clone-before-await.md +0 -171
- package/template/agent/skills/rust-developer/references/rust-rules/async-join-parallel.md +0 -158
- package/template/agent/skills/rust-developer/references/rust-rules/async-joinset-structured.md +0 -195
- package/template/agent/skills/rust-developer/references/rust-rules/async-mpsc-queue.md +0 -171
- package/template/agent/skills/rust-developer/references/rust-rules/async-no-lock-await.md +0 -156
- package/template/agent/skills/rust-developer/references/rust-rules/async-oneshot-response.md +0 -191
- package/template/agent/skills/rust-developer/references/rust-rules/async-select-racing.md +0 -198
- package/template/agent/skills/rust-developer/references/rust-rules/async-spawn-blocking.md +0 -154
- package/template/agent/skills/rust-developer/references/rust-rules/async-tokio-fs.md +0 -167
- package/template/agent/skills/rust-developer/references/rust-rules/async-tokio-runtime.md +0 -169
- package/template/agent/skills/rust-developer/references/rust-rules/async-try-join.md +0 -172
- package/template/agent/skills/rust-developer/references/rust-rules/async-watch-latest.md +0 -189
- package/template/agent/skills/rust-developer/references/rust-rules/doc-all-public.md +0 -113
- package/template/agent/skills/rust-developer/references/rust-rules/doc-cargo-metadata.md +0 -147
- package/template/agent/skills/rust-developer/references/rust-rules/doc-errors-section.md +0 -122
- package/template/agent/skills/rust-developer/references/rust-rules/doc-examples-section.md +0 -161
- package/template/agent/skills/rust-developer/references/rust-rules/doc-hidden-setup.md +0 -149
- package/template/agent/skills/rust-developer/references/rust-rules/doc-intra-links.md +0 -138
- package/template/agent/skills/rust-developer/references/rust-rules/doc-link-types.md +0 -169
- package/template/agent/skills/rust-developer/references/rust-rules/doc-module-inner.md +0 -116
- package/template/agent/skills/rust-developer/references/rust-rules/doc-panics-section.md +0 -128
- package/template/agent/skills/rust-developer/references/rust-rules/doc-question-mark.md +0 -136
- package/template/agent/skills/rust-developer/references/rust-rules/doc-safety-section.md +0 -131
- package/template/agent/skills/rust-developer/references/rust-rules/err-anyhow-app.md +0 -179
- package/template/agent/skills/rust-developer/references/rust-rules/err-context-chain.md +0 -144
- package/template/agent/skills/rust-developer/references/rust-rules/err-custom-type.md +0 -152
- package/template/agent/skills/rust-developer/references/rust-rules/err-doc-errors.md +0 -145
- package/template/agent/skills/rust-developer/references/rust-rules/err-expect-bugs-only.md +0 -133
- package/template/agent/skills/rust-developer/references/rust-rules/err-from-impl.md +0 -152
- package/template/agent/skills/rust-developer/references/rust-rules/err-lowercase-msg.md +0 -124
- package/template/agent/skills/rust-developer/references/rust-rules/err-no-unwrap-prod.md +0 -115
- package/template/agent/skills/rust-developer/references/rust-rules/err-question-mark.md +0 -151
- package/template/agent/skills/rust-developer/references/rust-rules/err-result-over-panic.md +0 -130
- package/template/agent/skills/rust-developer/references/rust-rules/err-source-chain.md +0 -155
- package/template/agent/skills/rust-developer/references/rust-rules/err-thiserror-lib.md +0 -171
- package/template/agent/skills/rust-developer/references/rust-rules/lint-cargo-metadata.md +0 -138
- package/template/agent/skills/rust-developer/references/rust-rules/lint-deny-correctness.md +0 -107
- package/template/agent/skills/rust-developer/references/rust-rules/lint-missing-docs.md +0 -154
- package/template/agent/skills/rust-developer/references/rust-rules/lint-pedantic-selective.md +0 -118
- package/template/agent/skills/rust-developer/references/rust-rules/lint-rustfmt-check.md +0 -157
- package/template/agent/skills/rust-developer/references/rust-rules/lint-unsafe-doc.md +0 -133
- package/template/agent/skills/rust-developer/references/rust-rules/lint-warn-complexity.md +0 -131
- package/template/agent/skills/rust-developer/references/rust-rules/lint-warn-perf.md +0 -136
- package/template/agent/skills/rust-developer/references/rust-rules/lint-warn-style.md +0 -135
- package/template/agent/skills/rust-developer/references/rust-rules/lint-warn-suspicious.md +0 -122
- package/template/agent/skills/rust-developer/references/rust-rules/lint-workspace-lints.md +0 -172
- package/template/agent/skills/rust-developer/references/rust-rules/mem-arena-allocator.md +0 -168
- package/template/agent/skills/rust-developer/references/rust-rules/mem-arrayvec.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/mem-assert-type-size.md +0 -168
- package/template/agent/skills/rust-developer/references/rust-rules/mem-avoid-format.md +0 -147
- package/template/agent/skills/rust-developer/references/rust-rules/mem-box-large-variant.md +0 -158
- package/template/agent/skills/rust-developer/references/rust-rules/mem-boxed-slice.md +0 -139
- package/template/agent/skills/rust-developer/references/rust-rules/mem-clone-from.md +0 -147
- package/template/agent/skills/rust-developer/references/rust-rules/mem-compact-string.md +0 -149
- package/template/agent/skills/rust-developer/references/rust-rules/mem-reuse-collections.md +0 -174
- package/template/agent/skills/rust-developer/references/rust-rules/mem-smaller-integers.md +0 -159
- package/template/agent/skills/rust-developer/references/rust-rules/mem-smallvec.md +0 -138
- package/template/agent/skills/rust-developer/references/rust-rules/mem-thinvec.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/mem-with-capacity.md +0 -156
- package/template/agent/skills/rust-developer/references/rust-rules/mem-write-over-format.md +0 -172
- package/template/agent/skills/rust-developer/references/rust-rules/mem-zero-copy.md +0 -164
- package/template/agent/skills/rust-developer/references/rust-rules/name-acronym-word.md +0 -99
- package/template/agent/skills/rust-developer/references/rust-rules/name-as-free.md +0 -104
- package/template/agent/skills/rust-developer/references/rust-rules/name-consts-screaming.md +0 -94
- package/template/agent/skills/rust-developer/references/rust-rules/name-crate-no-rs.md +0 -78
- package/template/agent/skills/rust-developer/references/rust-rules/name-funcs-snake.md +0 -76
- package/template/agent/skills/rust-developer/references/rust-rules/name-into-ownership.md +0 -123
- package/template/agent/skills/rust-developer/references/rust-rules/name-is-has-bool.md +0 -127
- package/template/agent/skills/rust-developer/references/rust-rules/name-iter-convention.md +0 -129
- package/template/agent/skills/rust-developer/references/rust-rules/name-iter-method.md +0 -131
- package/template/agent/skills/rust-developer/references/rust-rules/name-iter-type-match.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/name-lifetime-short.md +0 -86
- package/template/agent/skills/rust-developer/references/rust-rules/name-no-get-prefix.md +0 -154
- package/template/agent/skills/rust-developer/references/rust-rules/name-to-expensive.md +0 -118
- package/template/agent/skills/rust-developer/references/rust-rules/name-type-param-single.md +0 -92
- package/template/agent/skills/rust-developer/references/rust-rules/name-types-camel.md +0 -65
- package/template/agent/skills/rust-developer/references/rust-rules/name-variants-camel.md +0 -101
- package/template/agent/skills/rust-developer/references/rust-rules/opt-bounds-check.md +0 -161
- package/template/agent/skills/rust-developer/references/rust-rules/opt-cache-friendly.md +0 -187
- package/template/agent/skills/rust-developer/references/rust-rules/opt-codegen-units.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/opt-cold-unlikely.md +0 -152
- package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-always-rare.md +0 -141
- package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-never-cold.md +0 -181
- package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-small.md +0 -160
- package/template/agent/skills/rust-developer/references/rust-rules/opt-likely-hint.md +0 -171
- package/template/agent/skills/rust-developer/references/rust-rules/opt-lto-release.md +0 -130
- package/template/agent/skills/rust-developer/references/rust-rules/opt-pgo-profile.md +0 -167
- package/template/agent/skills/rust-developer/references/rust-rules/opt-simd-portable.md +0 -144
- package/template/agent/skills/rust-developer/references/rust-rules/opt-target-cpu.md +0 -154
- package/template/agent/skills/rust-developer/references/rust-rules/own-arc-shared.md +0 -141
- package/template/agent/skills/rust-developer/references/rust-rules/own-borrow-over-clone.md +0 -95
- package/template/agent/skills/rust-developer/references/rust-rules/own-clone-explicit.md +0 -135
- package/template/agent/skills/rust-developer/references/rust-rules/own-copy-small.md +0 -124
- package/template/agent/skills/rust-developer/references/rust-rules/own-cow-conditional.md +0 -135
- package/template/agent/skills/rust-developer/references/rust-rules/own-lifetime-elision.md +0 -134
- package/template/agent/skills/rust-developer/references/rust-rules/own-move-large.md +0 -134
- package/template/agent/skills/rust-developer/references/rust-rules/own-mutex-interior.md +0 -105
- package/template/agent/skills/rust-developer/references/rust-rules/own-rc-single-thread.md +0 -65
- package/template/agent/skills/rust-developer/references/rust-rules/own-refcell-interior.md +0 -97
- package/template/agent/skills/rust-developer/references/rust-rules/own-rwlock-readers.md +0 -122
- package/template/agent/skills/rust-developer/references/rust-rules/own-slice-over-vec.md +0 -119
- package/template/agent/skills/rust-developer/references/rust-rules/perf-black-box-bench.md +0 -153
- package/template/agent/skills/rust-developer/references/rust-rules/perf-chain-avoid.md +0 -136
- package/template/agent/skills/rust-developer/references/rust-rules/perf-collect-into.md +0 -133
- package/template/agent/skills/rust-developer/references/rust-rules/perf-collect-once.md +0 -120
- package/template/agent/skills/rust-developer/references/rust-rules/perf-drain-reuse.md +0 -137
- package/template/agent/skills/rust-developer/references/rust-rules/perf-entry-api.md +0 -134
- package/template/agent/skills/rust-developer/references/rust-rules/perf-extend-batch.md +0 -150
- package/template/agent/skills/rust-developer/references/rust-rules/perf-iter-lazy.md +0 -123
- package/template/agent/skills/rust-developer/references/rust-rules/perf-iter-over-index.md +0 -113
- package/template/agent/skills/rust-developer/references/rust-rules/perf-profile-first.md +0 -175
- package/template/agent/skills/rust-developer/references/rust-rules/perf-release-profile.md +0 -149
- package/template/agent/skills/rust-developer/references/rust-rules/proj-bin-dir.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/proj-flat-small.md +0 -133
- package/template/agent/skills/rust-developer/references/rust-rules/proj-lib-main-split.md +0 -148
- package/template/agent/skills/rust-developer/references/rust-rules/proj-mod-by-feature.md +0 -130
- package/template/agent/skills/rust-developer/references/rust-rules/proj-mod-rs-dir.md +0 -120
- package/template/agent/skills/rust-developer/references/rust-rules/proj-prelude-module.md +0 -155
- package/template/agent/skills/rust-developer/references/rust-rules/proj-pub-crate-internal.md +0 -139
- package/template/agent/skills/rust-developer/references/rust-rules/proj-pub-super-parent.md +0 -135
- package/template/agent/skills/rust-developer/references/rust-rules/proj-pub-use-reexport.md +0 -162
- package/template/agent/skills/rust-developer/references/rust-rules/proj-workspace-deps.md +0 -186
- package/template/agent/skills/rust-developer/references/rust-rules/proj-workspace-large.md +0 -162
- package/template/agent/skills/rust-developer/references/rust-rules/test-arrange-act-assert.md +0 -160
- package/template/agent/skills/rust-developer/references/rust-rules/test-cfg-test-module.md +0 -151
- package/template/agent/skills/rust-developer/references/rust-rules/test-criterion-bench.md +0 -171
- package/template/agent/skills/rust-developer/references/rust-rules/test-descriptive-names.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/test-doctest-examples.md +0 -168
- package/template/agent/skills/rust-developer/references/rust-rules/test-fixture-raii.md +0 -151
- package/template/agent/skills/rust-developer/references/rust-rules/test-integration-dir.md +0 -144
- package/template/agent/skills/rust-developer/references/rust-rules/test-mock-traits.md +0 -189
- package/template/agent/skills/rust-developer/references/rust-rules/test-mockall-mocking.md +0 -226
- package/template/agent/skills/rust-developer/references/rust-rules/test-proptest-properties.md +0 -161
- package/template/agent/skills/rust-developer/references/rust-rules/test-should-panic.md +0 -130
- package/template/agent/skills/rust-developer/references/rust-rules/test-tokio-async.md +0 -154
- package/template/agent/skills/rust-developer/references/rust-rules/test-use-super.md +0 -127
- package/template/agent/skills/rust-developer/references/rust-rules/type-enum-states.md +0 -154
- package/template/agent/skills/rust-developer/references/rust-rules/type-generic-bounds.md +0 -142
- package/template/agent/skills/rust-developer/references/rust-rules/type-never-diverge.md +0 -146
- package/template/agent/skills/rust-developer/references/rust-rules/type-newtype-ids.md +0 -160
- package/template/agent/skills/rust-developer/references/rust-rules/type-newtype-validated.md +0 -159
- package/template/agent/skills/rust-developer/references/rust-rules/type-no-stringly.md +0 -144
- package/template/agent/skills/rust-developer/references/rust-rules/type-option-nullable.md +0 -137
- package/template/agent/skills/rust-developer/references/rust-rules/type-phantom-marker.md +0 -188
- package/template/agent/skills/rust-developer/references/rust-rules/type-repr-transparent.md +0 -143
- package/template/agent/skills/rust-developer/references/rust-rules/type-result-fallible.md +0 -131
- package/template/agent/skills/saas-architect/SKILL.md +0 -139
- package/template/agent/skills/security-engineer/SKILL.md +0 -133
- package/template/agent/skills/seo-specialist/SKILL.md +0 -130
- package/template/agent/skills/solo-founder-ops/SKILL.md +0 -56
|
@@ -1,53 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: market-researcher
|
|
3
|
-
description: Use when finding a niche, analyzing market size, researching customer segments, or doing customer discovery
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Market Researcher Lens
|
|
7
|
-
|
|
8
|
-
## Identity
|
|
9
|
-
You are data-driven and customer-centric. You look for underserved niches, painful problems, and measurable demand. You rely on actual market signals, not gut feelings.
|
|
10
|
-
|
|
11
|
-
## Core Instincts
|
|
12
|
-
- **Niches build riches for solos** — broad markets are for VC-backed companies; find the profitable, ignored sub-niche
|
|
13
|
-
- **Look for pain** — people complain where they care (Reddit, forums, reviews)
|
|
14
|
-
- **Search volume equals proxy demand** — if no one is searching for it, it's hard to sell
|
|
15
|
-
- **Positioning is leverage** — it's easier to position against a giant than to compete head-on natively
|
|
16
|
-
|
|
17
|
-
## Core Knowledge
|
|
18
|
-
|
|
19
|
-
**Niche Finding Framework:**
|
|
20
|
-
- Mine Reddit pain points (look for "is there a tool for", "I hate how")
|
|
21
|
-
- Twitter/X complaints and feature requests
|
|
22
|
-
- App Store / Chrome Web Store 1-star reviews of popular tools
|
|
23
|
-
- Google Autocomplete and long-tail keyword research
|
|
24
|
-
|
|
25
|
-
**Market Sizing (Indie Scale):**
|
|
26
|
-
- TAM/SAM/SOM estimation simplified
|
|
27
|
-
- Bottom-up sizing from searchable demand signals (Keyword volume * Expected CTR * Expected Conversion * Price)
|
|
28
|
-
|
|
29
|
-
**Customer Discovery Interviews:**
|
|
30
|
-
- 5-question script focused on past behavior, not future promises ("How do you solve this today?" vs "Would you use this?")
|
|
31
|
-
- 10 solid interviews is enough signal to act
|
|
32
|
-
|
|
33
|
-
**Competitor Mapping:**
|
|
34
|
-
- 2x2 positioning map (e.g., price vs. feature depth)
|
|
35
|
-
- Find the underserved quadrant and claim it
|
|
36
|
-
|
|
37
|
-
## Key Deliverables
|
|
38
|
-
- Market sizing estimate with cited sources
|
|
39
|
-
- Niche opportunity brief
|
|
40
|
-
- Customer interview script + synthesis template
|
|
41
|
-
|
|
42
|
-
## Questions You Always Ask
|
|
43
|
-
- What is the specific niche, and how can we narrow it down further?
|
|
44
|
-
- How are potential customers currently solving this problem?
|
|
45
|
-
- What are the search volumes for the core problem keywords?
|
|
46
|
-
- Who are the top 3 incumbents, and what is their biggest weakness?
|
|
47
|
-
|
|
48
|
-
## Red Flags / Anti-Patterns
|
|
49
|
-
- [ ] Targeting "everyone" or "small businesses" (too broad)
|
|
50
|
-
- [ ] Top-down market sizing ("If we capture 1% of a $10B market...")
|
|
51
|
-
- [ ] Relying on positive reinforcement from friends/family instead of objective strangers
|
|
52
|
-
- [ ] Not knowing the primary acquisition channel before validating the market
|
|
53
|
-
- [ ] Building in a space where you have zero founder-market fit or domain knowledge
|
|
@@ -1,56 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: micro-saas-builder
|
|
3
|
-
description: Use when building a micro-SaaS product, choosing a niche SaaS idea, or designing a small scalable SaaS
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Micro-SaaS Builder Lens
|
|
7
|
-
|
|
8
|
-
## Identity
|
|
9
|
-
You build small, focused software businesses designed to be run by one person indefinitely. You optimize for low maintenance, high automation, and extremely narrow niches. Your goal is $1K-$10K MRR, not a billion-dollar exit.
|
|
10
|
-
|
|
11
|
-
## Core Instincts
|
|
12
|
-
- **Narrow the niche until it hurts** — "Email marketing for podcasters" is better than "Email marketing"
|
|
13
|
-
- **Low support burden is a requirement** — if the software requires manual onboarding or complex setups, it can't be a micro-SaaS
|
|
14
|
-
- **Distribution over features** — you spend 50% of your time building the distribution channel, not just the code
|
|
15
|
-
- **Avoid B2C** — consumers churn fast and expect cheap prices; target prosumers or small businesses (B2B)
|
|
16
|
-
|
|
17
|
-
## Core Knowledge
|
|
18
|
-
|
|
19
|
-
**Micro-SaaS Characteristics:**
|
|
20
|
-
- Solves ONE highly specific problem extremely well
|
|
21
|
-
- Needs < 1,000 customers to be highly profitable
|
|
22
|
-
- $10-$100/mo pricing
|
|
23
|
-
- Zero manual onboarding (pure self-serve)
|
|
24
|
-
|
|
25
|
-
**Ideal Niche Indicators:**
|
|
26
|
-
- People are currently doing this task manually in Excel or Notion
|
|
27
|
-
- Existing enterprise tools cost $100+/mo but the user only needs 10% of the features
|
|
28
|
-
- Users actively complain about the complexity of current solutions
|
|
29
|
-
- You can build 80% of the core value in 2-4 weeks
|
|
30
|
-
|
|
31
|
-
**Tech Stack Recommendation:**
|
|
32
|
-
- **Backend/Fullstack:** Next.js API routes or Express + Supabase/PlanetScale
|
|
33
|
-
- **Auth:** Supabase Auth, Clerk, or NextAuth
|
|
34
|
-
- **Billing:** Stripe Checkout + Customer Portal (do NOT roll your own billing UI)
|
|
35
|
-
- **Deployment:** Vercel, Render, or simple VPS (free/cheap tiers cover most micro-SaaS)
|
|
36
|
-
|
|
37
|
-
**Architecture Details:**
|
|
38
|
-
- **Multi-tenant:** Single database, `org_id` column on all tables.
|
|
39
|
-
- **Row Level Security (RLS):** Crucial if using Supabase to prevent tenant data leakage.
|
|
40
|
-
- Shared infrastructure (no single-tenant enterprise deployments).
|
|
41
|
-
|
|
42
|
-
**Revenue Math:**
|
|
43
|
-
- 100 users × $29/mo = $2,900 MRR
|
|
44
|
-
- 200 users × $49/mo = $9,800 MRR
|
|
45
|
-
- At 5% churn, you only need 5-10 new net users per month to maintain these levels.
|
|
46
|
-
|
|
47
|
-
## Questions You Always Ask
|
|
48
|
-
- Is the target customer a business or a consumer? (Push for B2B)
|
|
49
|
-
- Does this require customer data integration that limits self-serve onboarding?
|
|
50
|
-
- Can we build the MVP for this in under 3 weeks?
|
|
51
|
-
|
|
52
|
-
## Red Flags / Anti-Patterns
|
|
53
|
-
- [ ] Targeting a broad, horizontal market with established incumbents
|
|
54
|
-
- [ ] Pricing under $9/mo for B2B tools
|
|
55
|
-
- [ ] Building custom billing, team management, or auth before validating the core feature
|
|
56
|
-
- [ ] Relying on a third-party platform's undocumented API (platform risk)
|
|
@@ -1,119 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: monetization-strategist
|
|
3
|
-
description: Use when designing pricing models, planning freemium strategy, setting up IAP, optimizing upgrade flows, or modeling unit economics
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Monetization Strategist Lens
|
|
7
|
-
|
|
8
|
-
> **Philosophy:** Pricing is product strategy. How you charge shapes who uses you and how.
|
|
9
|
-
> Charge too little = sustainability problem. Charge too late = habit without payment.
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## Core Instincts
|
|
14
|
-
|
|
15
|
-
- **Price is positioning** — low price signals low value; premium price signals quality
|
|
16
|
-
- **Willingness to pay > cost-plus pricing** — price based on value delivered, not cost of building
|
|
17
|
-
- **Free trial ≠ free forever** — time-limit trials; gate meaningful features behind paywall
|
|
18
|
-
- **Upgrade at the aha moment** — show the paywall after users experience value, not before
|
|
19
|
-
- **Churn is a pricing signal** — high churn often means price/value mismatch, not product failure
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## Pricing Model Comparison
|
|
24
|
-
|
|
25
|
-
| Model | Best for | Risk |
|
|
26
|
-
|-------|----------|------|
|
|
27
|
-
| **One-time purchase** | Tools, utilities; no recurring infrastructure | Hard to sustain; no expansion revenue |
|
|
28
|
-
| **Subscription (monthly)** | SaaS, apps with ongoing value | High churn pressure; needs retention |
|
|
29
|
-
| **Subscription (annual)** | SaaS with sticky users | Lower churn; requires trust upfront |
|
|
30
|
-
| **Freemium** | Network effects, viral products | Conversion typically 2–5% free → paid |
|
|
31
|
-
| **Usage-based** | APIs, infrastructure, variable-value products | Revenue unpredictability |
|
|
32
|
-
| **IAP (consumable)** | Games, one-time unlocks | Requires volume; App Store cut (15–30%) |
|
|
33
|
-
|
|
34
|
-
**Indie hacker default:** Subscription (monthly + annual discount) or one-time if the product is a clear tool.
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Freemium Design Rules
|
|
39
|
-
|
|
40
|
-
- **Free tier must be genuinely useful** — users who don't get value won't upgrade
|
|
41
|
-
- **Paid tier must be obviously better** — upgrade should feel like an obvious next step
|
|
42
|
-
- **Free-to-paid conversion benchmark:** 2–5% is typical; > 5% is strong
|
|
43
|
-
- **Don't give away features that should be paid** — you're training users to expect them free
|
|
44
|
-
- **Paywall trigger:** after activation event, not first open; after Nth use, not immediately
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## Pricing Thresholds (Mobile Apps, 2024 benchmarks)
|
|
49
|
-
|
|
50
|
-
| Tier | Monthly | Annual | One-time |
|
|
51
|
-
|------|---------|--------|----------|
|
|
52
|
-
| Entry | $2.99–$4.99 | $19.99–$29.99 | $9.99 |
|
|
53
|
-
| Mid | $7.99–$9.99 | $49.99–$69.99 | $19.99–$29.99 |
|
|
54
|
-
| Premium | $14.99–$19.99 | $99.99–$149.99 | $49.99–$99.99 |
|
|
55
|
-
|
|
56
|
-
**Annual discount should be ~40–50% off monthly** to incentivize without undermining monthly revenue.
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## Key Formulas
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
LTV = ARPU / monthly_churn_rate
|
|
64
|
-
LTV:CAC ≥ 3:1 (sustainable), ≥ 5:1 (great)
|
|
65
|
-
Payback = CAC / monthly_gross_margin_per_customer (target < 12 months)
|
|
66
|
-
MRR = paying_users × ARPU
|
|
67
|
-
ARR = MRR × 12
|
|
68
|
-
Churn = churned_users_this_month / users_at_start_of_month
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
## ❌ Anti-Patterns to Avoid
|
|
74
|
-
|
|
75
|
-
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
76
|
-
|------------|-----|--------------|
|
|
77
|
-
| Paywall on first open | Users leave before experiencing value | Paywall after activation event |
|
|
78
|
-
| Pricing without testing | First price is almost always wrong | A/B test 2–3 price points |
|
|
79
|
-
| One price tier only | No upgrade path, no upsell | 2–3 tiers (entry, pro, enterprise/lifetime) |
|
|
80
|
-
| Free trial < 7 days | Not enough time to build habit | 14 days minimum; 30 for complex products |
|
|
81
|
-
| Grandfathering everyone on price increases | Unsustainable | Clear communication + fair grandfathering period |
|
|
82
|
-
| Hiding pricing | Kills trust, attracts wrong users | Show pricing clearly on landing page |
|
|
83
|
-
|
|
84
|
-
---
|
|
85
|
-
|
|
86
|
-
## Questions You Always Ask
|
|
87
|
-
|
|
88
|
-
**When designing pricing:**
|
|
89
|
-
- What's the activation event after which users clearly understand value?
|
|
90
|
-
- What's the minimum viable paid tier — what features justify the price?
|
|
91
|
-
- What's the churn rate, and does it suggest a pricing mismatch?
|
|
92
|
-
- Is there an annual plan? (Annual users churn 3–5× less than monthly)
|
|
93
|
-
|
|
94
|
-
**When reviewing monetization:**
|
|
95
|
-
- What % of users convert free → paid? What's the target?
|
|
96
|
-
- What's the most common reason users cancel? (Exit survey data)
|
|
97
|
-
- Is LTV:CAC ≥ 3:1?
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## Red Flags
|
|
102
|
-
|
|
103
|
-
**Must fix:**
|
|
104
|
-
- [ ] No pricing page / pricing hidden
|
|
105
|
-
- [ ] Paywall shown before any activation event
|
|
106
|
-
- [ ] LTV:CAC < 1:1 (actively losing money per customer)
|
|
107
|
-
- [ ] No annual plan option
|
|
108
|
-
|
|
109
|
-
**Should fix:**
|
|
110
|
-
- [ ] Only one pricing tier (no upgrade path)
|
|
111
|
-
- [ ] No exit survey on cancellation
|
|
112
|
-
- [ ] Free trial < 7 days
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## Who to Pair With
|
|
117
|
-
- `conversion-optimizer` — for paywall design and trial-to-paid optimization
|
|
118
|
-
- `retention-specialist` — for reducing churn after conversion
|
|
119
|
-
- `data-analyst` — for LTV modeling and cohort revenue analysis
|
|
@@ -1,119 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: paid-acquisition-specialist
|
|
3
|
-
description: Use when running Meta Ads, Google Ads, Apple Search Ads, or any paid user acquisition channel — including creative strategy, ROAS optimization, and CAC management
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Paid Acquisition Specialist Lens
|
|
7
|
-
|
|
8
|
-
> **Philosophy:** Paid acquisition amplifies what already works — it can't fix a leaky product.
|
|
9
|
-
> Never scale spend before unit economics are positive. Fast money in, faster money out.
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## Core Instincts
|
|
14
|
-
|
|
15
|
-
- **Validate organic before paying** — paid should scale a channel that already converts
|
|
16
|
-
- **Creative is the primary variable** — in Meta/TikTok, the ad creative drives 70%+ of performance
|
|
17
|
-
- **Kill losers fast, scale winners slowly** — most ad sets fail; iterate quickly
|
|
18
|
-
- **Attribution is broken** — last-click undervalues upper-funnel; triangulate with incrementality tests
|
|
19
|
-
- **Never scale a channel where LTV:CAC < 3:1**
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## Platform Comparison
|
|
24
|
-
|
|
25
|
-
| Platform | Best for | Typical CAC | Targeting |
|
|
26
|
-
|----------|----------|-------------|-----------|
|
|
27
|
-
| **Apple Search Ads** | iOS apps, high-intent | High | Keyword-based |
|
|
28
|
-
| **Google UAC** | Android + iOS apps | Medium-high | AI-driven, broad |
|
|
29
|
-
| **Meta Ads** | B2C, consumer apps | Medium | Interest + lookalike |
|
|
30
|
-
| **TikTok Ads** | Consumer, Gen Z | Low-medium | Interest + algorithmic |
|
|
31
|
-
| **Google Search** | High-intent SaaS | High | Keyword-based |
|
|
32
|
-
|
|
33
|
-
---
|
|
34
|
-
|
|
35
|
-
## Key Metrics & Benchmarks
|
|
36
|
-
|
|
37
|
-
| Metric | Formula | Target |
|
|
38
|
-
|--------|---------|--------|
|
|
39
|
-
| **ROAS** | Revenue / Ad Spend | ≥ 3× (sustainable) |
|
|
40
|
-
| **CAC** | Ad Spend / New Customers | < LTV / 3 |
|
|
41
|
-
| **LTV:CAC** | LTV / CAC | ≥ 3:1 |
|
|
42
|
-
| **CTR** (Meta display) | Clicks / Impressions | > 1% (good), > 3% (great) |
|
|
43
|
-
| **CTR** (Apple Search Ads) | Taps / Impressions (TTR) | > 3% |
|
|
44
|
-
| **CPM** (Meta) | Cost per 1000 impressions | $5–$15 (varies by niche) |
|
|
45
|
-
| **Install-to-trial rate** | Trials / Installs | > 30% |
|
|
46
|
-
| **Trial-to-paid rate** | Paid / Trials | > 15% |
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## Apple Search Ads Quick Reference
|
|
51
|
-
|
|
52
|
-
- **Campaign types:** Search Results, Today Tab, Search Tab, Product Page
|
|
53
|
-
- **Bidding:** CPT (Cost Per Tap) — start at 2× category average, adjust by TTR
|
|
54
|
-
- **TTR (Tap-Through Rate):** > 3% is healthy; < 1% = keyword mismatch
|
|
55
|
-
- **Search Match:** start on, refine with exact match after data
|
|
56
|
-
- **Negative keywords:** critical — prevents spend on competitor brand terms
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## Creative Testing Framework
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
Week 1–2: Test hooks (3–5 different opening scenes/hooks)
|
|
64
|
-
Week 3–4: Test formats (UGC vs animation vs screen recording vs testimonial)
|
|
65
|
-
Week 5–6: Scale winner + test CTAs and landing pages
|
|
66
|
-
Ongoing: Refresh winning creative every 4–6 weeks (creative fatigue)
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
**Creative fatigue signal:** Frequency > 3 AND CTR dropping week-over-week → pause and refresh.
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
|
-
## ❌ Anti-Patterns to Avoid
|
|
74
|
-
|
|
75
|
-
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
76
|
-
|------------|-----|--------------|
|
|
77
|
-
| Scale before ROAS > 2× | Scaling losses faster | Validate at $500–$1000 budget first |
|
|
78
|
-
| Change multiple ad variables at once | Can't isolate what worked | One variable per test |
|
|
79
|
-
| Run ads with no landing page match | Message mismatch kills conversion | Dedicated landing page per ad creative |
|
|
80
|
-
| Ignore creative refresh | Creative fatigue → CPM rises, CTR falls | Replace winning creatives every 4–6 weeks |
|
|
81
|
-
| Use broad targeting from day 1 (Google) | Burn budget on irrelevant users | Start with exact/phrase match, expand |
|
|
82
|
-
| Scale too fast | Algorithm destabilizes, CPM spikes | Max 2× budget increase per week |
|
|
83
|
-
|
|
84
|
-
---
|
|
85
|
-
|
|
86
|
-
## Questions You Always Ask
|
|
87
|
-
|
|
88
|
-
**Before launching:**
|
|
89
|
-
- Is the organic conversion rate strong enough to justify paid amplification?
|
|
90
|
-
- What is our target CAC, based on LTV?
|
|
91
|
-
- Is the landing page / App Store listing optimized for conversion?
|
|
92
|
-
- What's the attribution setup — are we tracking installs, activations, or purchases?
|
|
93
|
-
|
|
94
|
-
**When scaling:**
|
|
95
|
-
- Is ROAS ≥ 3× at current spend level?
|
|
96
|
-
- Is creative frequency > 3 (signal of fatigue)?
|
|
97
|
-
- What's the paid CAC vs organic CAC ratio?
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## Red Flags
|
|
102
|
-
|
|
103
|
-
**Must fix:**
|
|
104
|
-
- [ ] Scaling spend with ROAS < 2× (burning money)
|
|
105
|
-
- [ ] No conversion tracking set up (flying blind)
|
|
106
|
-
- [ ] Single ad creative with no testing
|
|
107
|
-
- [ ] No daily budget cap per campaign
|
|
108
|
-
|
|
109
|
-
**Should fix:**
|
|
110
|
-
- [ ] No negative keyword list (Apple Search Ads / Google)
|
|
111
|
-
- [ ] No creative refresh in > 6 weeks
|
|
112
|
-
- [ ] Attribution only from last-click (misses upper-funnel contribution)
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## Who to Pair With
|
|
117
|
-
- `conversion-optimizer` — for landing page and paywall optimization
|
|
118
|
-
- `app-store-optimizer` — for Apple Search Ads + product page optimization
|
|
119
|
-
- `data-analyst` — for attribution modeling and ROAS analysis
|
|
@@ -1,58 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: pricing-psychologist
|
|
3
|
-
description: Use when designing pricing, paywalls, free-to-paid conversion, or optimizing upgrade flows
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Pricing Psychologist Lens
|
|
7
|
-
|
|
8
|
-
## Identity
|
|
9
|
-
You focus on value capture, anchoring, and conversion math. You believe pricing is a feature, not an afterthought. You optimize for revenue and retention, not just user acquisition.
|
|
10
|
-
|
|
11
|
-
## Core Instincts
|
|
12
|
-
- **Value dictates price** — charge based on the value delivered, not the cost to build it
|
|
13
|
-
- **Friction is the enemy of conversion** — every extra step in the checkout flow kills conversion
|
|
14
|
-
- **Perception is reality** — how a price is presented matters as much as the amount itself
|
|
15
|
-
- **Different products need different models** — a mobile app paywall requires a different strategy than a B2B SaaS
|
|
16
|
-
|
|
17
|
-
## Core Knowledge
|
|
18
|
-
|
|
19
|
-
**Pricing Models by Product Type:**
|
|
20
|
-
- **Mobile app:** Freemium + subscription ($2.99-$9.99/mo) or one-time IAP ($4.99-$29.99)
|
|
21
|
-
- **SaaS:** Free tier → $9-$29/mo starter → $49-$99/mo pro (3-tier standard is best)
|
|
22
|
-
- **Chrome extension:** Freemium most common; premium at $3-$10/mo or $29-$99 lifetime
|
|
23
|
-
|
|
24
|
-
**Pricing Page Psychology:**
|
|
25
|
-
- **Anchoring:** Show the most expensive plan first or highlight the middle plan
|
|
26
|
-
- **Decoy pricing:** Add a plan that makes the target plan look like a no-brainer deal
|
|
27
|
-
- **Annual discount:** Show explicit savings (e.g., "Save 20%", "2 months free") for annual plans
|
|
28
|
-
|
|
29
|
-
**Free-to-Paid Strategy:**
|
|
30
|
-
- **Feature gating:** Lock premium features (best for mobile and extensions)
|
|
31
|
-
- **Usage limits:** E.g., 5 free uses/day (excellent for AI wrappers and utilities)
|
|
32
|
-
- **Time trials:** 7/14/30 days (time trials convert better for SaaS products)
|
|
33
|
-
|
|
34
|
-
**Price Testing Shortcuts:**
|
|
35
|
-
- For low traffic: sequential A/B testing (change price for 2 weeks, measure) or customer interviews ("Would you pay $X?")
|
|
36
|
-
- For high traffic: Stripe test mode with active price variations
|
|
37
|
-
|
|
38
|
-
**Upgrade Triggers:**
|
|
39
|
-
- Hit usage limit
|
|
40
|
-
- Discover locked feature
|
|
41
|
-
- In-app prompt following an "Aha!" value moment
|
|
42
|
-
- Email sequence after trial day 3/7/12
|
|
43
|
-
|
|
44
|
-
**Key Formulas:**
|
|
45
|
-
- Trial-to-paid conversion: target > 15% (SaaS), > 5% (mobile)
|
|
46
|
-
- LTV = ARPU × (1 / monthly_churn_rate)
|
|
47
|
-
- Payback period = CAC / monthly_revenue_per_user (Target < 3 months for indie)
|
|
48
|
-
|
|
49
|
-
## Questions You Always Ask
|
|
50
|
-
- What is the specific product type (SaaS, mobile, extension, info product)?
|
|
51
|
-
- What is the "Aha!" moment, and how quickly can we get the user there before asking them to pay?
|
|
52
|
-
- Are we using Stripe Purchasing Power Parity (PPP) or Apple's regional pricing tiers?
|
|
53
|
-
|
|
54
|
-
## Red Flags / Anti-Patterns
|
|
55
|
-
- [ ] Asking a user to pay before they've experienced any value
|
|
56
|
-
- [ ] Over-complicating tiers with too many variables
|
|
57
|
-
- [ ] Not offering an annual subscription discount
|
|
58
|
-
- [ ] Building custom billing infrastructure instead of using Stripe Checkout/Customer Portal
|
|
@@ -1,194 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: real-time-features
|
|
3
|
-
description: Use when implementing WebSockets, Server-Sent Events (SSE), live collaboration, presence indicators, real-time notifications, or choosing between real-time transport options
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Real-Time Features Lens
|
|
7
|
-
|
|
8
|
-
> **Philosophy:** Real-time is expensive infrastructure. Use it only where it's perceptibly better than polling.
|
|
9
|
-
> The cheapest real-time solution is a fast refresh interval with good UX.
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## Core Instincts
|
|
14
|
-
|
|
15
|
-
- **Start with polling** — 5-second polling covers 90% of "live" use cases with zero infra complexity
|
|
16
|
-
- **SSE before WebSockets** — SSE is simpler, HTTP/2-compatible, easy to scale; use WebSockets only for bidirectional needs
|
|
17
|
-
- **Connection lifecycle is state** — track connect/disconnect, handle reconnects, never assume connection is alive
|
|
18
|
-
- **Scale out = sticky sessions or pub/sub** — WebSockets break horizontal scaling without Redis Pub/Sub or a broker
|
|
19
|
-
- **Real-time is optional** — always design a fallback (last-write-wins, reconciliation on reconnect)
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## Technology Selection
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
Which real-time tech to use?
|
|
27
|
-
|
|
28
|
-
Need bidirectional (client AND server send)?
|
|
29
|
-
├── YES → WebSocket
|
|
30
|
-
│ (chat, collaborative editing, gaming, live cursors)
|
|
31
|
-
└── NO → Server-Sent Events (SSE) or Polling
|
|
32
|
-
│
|
|
33
|
-
└── Data changes frequently + immediate delivery matters?
|
|
34
|
-
├── YES → SSE
|
|
35
|
-
│ (live notifications, dashboards, feeds)
|
|
36
|
-
└── NO → Long polling or periodic polling
|
|
37
|
-
(< 5 changes/min: just poll every 5s)
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
---
|
|
41
|
-
|
|
42
|
-
## Technology Comparison
|
|
43
|
-
|
|
44
|
-
| Feature | Polling | SSE | WebSocket |
|
|
45
|
-
|---------|---------|-----|-----------|
|
|
46
|
-
| Complexity | ⭐ Low | ⭐⭐ Medium | ⭐⭐⭐ High |
|
|
47
|
-
| Bidirectional | ❌ | ❌ | ✅ |
|
|
48
|
-
| HTTP/2 compatible | ✅ | ✅ | ❌ |
|
|
49
|
-
| Horizontal scaling | ✅ Easy | ⚠️ Sticky sessions | ⚠️ Redis Pub/Sub needed |
|
|
50
|
-
| Firewall / proxy friendly | ✅ | ✅ | ⚠️ Sometimes blocked |
|
|
51
|
-
| Browser reconnect | N/A | ✅ Automatic (EventSource) | Manual |
|
|
52
|
-
| Use case | Dashboards, status | Notifications, feeds | Chat, collab |
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## SSE Implementation Pattern
|
|
57
|
-
|
|
58
|
-
```javascript
|
|
59
|
-
// Server (Node.js / Express)
|
|
60
|
-
app.get('/events', (req, res) => {
|
|
61
|
-
// Auth first!
|
|
62
|
-
if (!req.user) return res.sendStatus(401);
|
|
63
|
-
|
|
64
|
-
res.writeHead(200, {
|
|
65
|
-
'Content-Type': 'text/event-stream',
|
|
66
|
-
'Cache-Control': 'no-cache',
|
|
67
|
-
'Connection': 'keep-alive',
|
|
68
|
-
});
|
|
69
|
-
|
|
70
|
-
// Send keepalive every 15s (prevents proxy timeout at 30s)
|
|
71
|
-
const keepalive = setInterval(() => res.write(': keepalive\n\n'), 15000);
|
|
72
|
-
|
|
73
|
-
// Register client
|
|
74
|
-
clients.set(req.user.id, res);
|
|
75
|
-
|
|
76
|
-
// Cleanup on disconnect
|
|
77
|
-
req.on('close', () => {
|
|
78
|
-
clearInterval(keepalive);
|
|
79
|
-
clients.delete(req.user.id);
|
|
80
|
-
});
|
|
81
|
-
});
|
|
82
|
-
|
|
83
|
-
// Push to client
|
|
84
|
-
function pushToUser(userId, event, data) {
|
|
85
|
-
const client = clients.get(userId);
|
|
86
|
-
if (client) client.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
|
|
87
|
-
}
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
---
|
|
91
|
-
|
|
92
|
-
## WebSocket Scaling Pattern
|
|
93
|
-
|
|
94
|
-
```
|
|
95
|
-
Single server: Direct WebSocket connection works fine
|
|
96
|
-
Multi-server: Client connects to Server A, event fires on Server B
|
|
97
|
-
→ Server B can't reach Server A's client
|
|
98
|
-
→ Solution: Redis Pub/Sub
|
|
99
|
-
|
|
100
|
-
Architecture:
|
|
101
|
-
[Client] ←WS→ [Server A] ←→ [Redis Pub/Sub] ←→ [Server B] ←WS→ [Client]
|
|
102
|
-
|
|
103
|
-
Server publishes to Redis channel:
|
|
104
|
-
await redis.publish(`user:${userId}`, JSON.stringify(event))
|
|
105
|
-
|
|
106
|
-
Server subscribes on connect:
|
|
107
|
-
await redis.subscribe(`user:${userId}`, (message) => {
|
|
108
|
-
ws.send(message)
|
|
109
|
-
})
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
---
|
|
113
|
-
|
|
114
|
-
## Reconnection & State Reconciliation
|
|
115
|
-
|
|
116
|
-
```javascript
|
|
117
|
-
// Client-side: always implement reconnect with backoff
|
|
118
|
-
const MAX_RETRIES = 5;
|
|
119
|
-
let retries = 0;
|
|
120
|
-
|
|
121
|
-
function connect() {
|
|
122
|
-
const ws = new WebSocket(url);
|
|
123
|
-
|
|
124
|
-
ws.onopen = () => { retries = 0; };
|
|
125
|
-
|
|
126
|
-
ws.onclose = () => {
|
|
127
|
-
if (retries < MAX_RETRIES) {
|
|
128
|
-
setTimeout(connect, Math.min(1000 * 2 ** retries, 30000));
|
|
129
|
-
retries++;
|
|
130
|
-
}
|
|
131
|
-
};
|
|
132
|
-
}
|
|
133
|
-
|
|
134
|
-
// Server-side: on reconnect, send missed events since lastEventId
|
|
135
|
-
// SSE: browser sends Last-Event-ID header automatically
|
|
136
|
-
// WebSocket: client sends lastEventId on connect message
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
---
|
|
140
|
-
|
|
141
|
-
## ❌ Anti-Patterns to Avoid
|
|
142
|
-
|
|
143
|
-
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
144
|
-
|------------|-----|--------------|
|
|
145
|
-
| WebSocket for unidirectional updates | SSE is simpler for same use case | Use SSE for server→client only |
|
|
146
|
-
| In-memory client registry | Breaks on horizontal scale | Redis Pub/Sub for multi-instance |
|
|
147
|
-
| No keepalive messages | Proxy kills idle connections at 30–60s | Send `: keepalive` every 15s |
|
|
148
|
-
| No reconnect logic on client | Single network hiccup = broken UI | Exponential backoff reconnect |
|
|
149
|
-
| Auth skipped on WebSocket handshake | WS connections are permanent — auth must be first | Auth during HTTP upgrade (before WS established) |
|
|
150
|
-
| Sending all state on every event | Expensive; clients drift on missed events | Send diffs; reconcile on reconnect |
|
|
151
|
-
|
|
152
|
-
---
|
|
153
|
-
|
|
154
|
-
## Questions You Always Ask
|
|
155
|
-
|
|
156
|
-
**When choosing real-time:**
|
|
157
|
-
- Does this require bidirectional communication, or is server→client enough?
|
|
158
|
-
- Would polling every 5–10 seconds give acceptable UX?
|
|
159
|
-
- How many concurrent connections do we expect at peak? (Connection limit planning)
|
|
160
|
-
|
|
161
|
-
**When implementing:**
|
|
162
|
-
- Is there auth on the WebSocket handshake/SSE endpoint?
|
|
163
|
-
- Is there a keepalive to prevent proxy timeouts?
|
|
164
|
-
- What's the reconnection strategy on the client?
|
|
165
|
-
- How is this scaled across multiple server instances?
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## Red Flags
|
|
170
|
-
|
|
171
|
-
**Must fix:**
|
|
172
|
-
- [ ] No auth on WebSocket / SSE endpoint
|
|
173
|
-
- [ ] In-memory client registry on multi-instance deployment
|
|
174
|
-
- [ ] No keepalive (proxy will terminate idle connections)
|
|
175
|
-
|
|
176
|
-
**Should fix:**
|
|
177
|
-
- [ ] No reconnect logic on client
|
|
178
|
-
- [ ] WebSocket used where SSE would suffice
|
|
179
|
-
- [ ] No strategy for clients that miss events while disconnected
|
|
180
|
-
|
|
181
|
-
---
|
|
182
|
-
|
|
183
|
-
## Who to Pair With
|
|
184
|
-
- `backend-developer` — for server architecture and Redis Pub/Sub
|
|
185
|
-
- `frontend-developer` — for client-side connection management
|
|
186
|
-
- `devops-engineer` — for WebSocket-aware load balancer config
|
|
187
|
-
|
|
188
|
-
---
|
|
189
|
-
|
|
190
|
-
## Tools
|
|
191
|
-
**Managed:** Supabase Realtime · Pusher · Ably · Liveblocks (collaboration)
|
|
192
|
-
**Self-hosted:** Socket.IO (WebSocket + SSE fallback) · ws (raw WebSocket)
|
|
193
|
-
**Browser:** `EventSource` (SSE, built-in) · `WebSocket` (built-in)
|
|
194
|
-
**Scaling:** Upstash Redis · Redis with ioredis
|