@leejungkiin/awkit 1.1.6 → 1.1.9

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.
Files changed (84) hide show
  1. package/README.md +51 -1
  2. package/bin/awk.js +2 -2
  3. package/core/GEMINI.md +45 -7
  4. package/package.json +8 -5
  5. package/skill-packs/neural-memory/skills/nm-memory-sync/SKILL.md +14 -1
  6. package/skills/ab-test-store-listing/SKILL.md +220 -0
  7. package/skills/android-aso/SKILL.md +197 -0
  8. package/skills/app-analytics/SKILL.md +210 -0
  9. package/skills/app-clips/SKILL.md +163 -0
  10. package/skills/app-icon-optimization/SKILL.md +170 -0
  11. package/skills/app-launch/SKILL.md +153 -0
  12. package/skills/app-marketing-context/SKILL.md +129 -0
  13. package/skills/app-store-featured/SKILL.md +213 -0
  14. package/skills/apple-search-ads/SKILL.md +205 -0
  15. package/skills/asc-metrics/SKILL.md +157 -0
  16. package/skills/aso-audit/SKILL.md +179 -0
  17. package/skills/competitor-analysis/SKILL.md +163 -0
  18. package/skills/competitor-tracking/SKILL.md +185 -0
  19. package/skills/crash-analytics/SKILL.md +181 -0
  20. package/skills/gitnexus-intelligence/SKILL.md +224 -0
  21. package/skills/in-app-events/SKILL.md +176 -0
  22. package/skills/keyword-research/SKILL.md +141 -0
  23. package/skills/localization/SKILL.md +165 -0
  24. package/skills/market-movers/SKILL.md +137 -0
  25. package/skills/market-pulse/SKILL.md +170 -0
  26. package/skills/metadata-optimization/SKILL.md +170 -0
  27. package/skills/monetization-strategy/SKILL.md +175 -0
  28. package/skills/onboarding-optimization/SKILL.md +194 -0
  29. package/skills/orchestrator/SKILL.md +306 -25
  30. package/skills/press-and-pr/SKILL.md +204 -0
  31. package/skills/rating-prompt-strategy/SKILL.md +184 -0
  32. package/skills/retention-optimization/SKILL.md +165 -0
  33. package/skills/review-management/SKILL.md +154 -0
  34. package/skills/screenshot-optimization/SKILL.md +167 -0
  35. package/skills/seasonal-aso/SKILL.md +141 -0
  36. package/skills/spec-gate/SKILL.md +312 -0
  37. package/skills/subscription-lifecycle/SKILL.md +206 -0
  38. package/skills/swiftui-pro/references/design.md +44 -0
  39. package/skills/symphony-enforcer/SKILL.md +92 -11
  40. package/skills/symphony-orchestrator/SKILL.md +9 -7
  41. package/skills/systematic-debugging/SKILL.md +32 -7
  42. package/skills/ua-campaign/SKILL.md +207 -0
  43. package/skills/verification-gate/SKILL.md +23 -2
  44. package/workflows/gitnexus.md +123 -0
  45. package/symphony/LICENSE +0 -21
  46. package/symphony/README.md +0 -178
  47. package/symphony/app/api/agents/route.js +0 -152
  48. package/symphony/app/api/events/route.js +0 -22
  49. package/symphony/app/api/knowledge/route.js +0 -253
  50. package/symphony/app/api/locks/route.js +0 -29
  51. package/symphony/app/api/notes/route.js +0 -125
  52. package/symphony/app/api/preflight/route.js +0 -23
  53. package/symphony/app/api/projects/route.js +0 -116
  54. package/symphony/app/api/roles/route.js +0 -134
  55. package/symphony/app/api/skills/route.js +0 -82
  56. package/symphony/app/api/status/route.js +0 -18
  57. package/symphony/app/api/tasks/route.js +0 -157
  58. package/symphony/app/api/workflows/route.js +0 -61
  59. package/symphony/app/api/workspaces/route.js +0 -15
  60. package/symphony/app/globals.css +0 -2605
  61. package/symphony/app/layout.js +0 -20
  62. package/symphony/app/page.js +0 -2122
  63. package/symphony/cli/index.js +0 -1060
  64. package/symphony/core/agent-manager.js +0 -357
  65. package/symphony/core/context-bus.js +0 -100
  66. package/symphony/core/db.js +0 -223
  67. package/symphony/core/file-lock-manager.js +0 -154
  68. package/symphony/core/merge-pipeline.js +0 -234
  69. package/symphony/core/orchestrator.js +0 -236
  70. package/symphony/core/task-manager.js +0 -335
  71. package/symphony/core/workspace-manager.js +0 -168
  72. package/symphony/jsconfig.json +0 -7
  73. package/symphony/lib/core.mjs +0 -1034
  74. package/symphony/mcp/index.js +0 -29
  75. package/symphony/mcp/server.js +0 -110
  76. package/symphony/mcp/tools/context.js +0 -80
  77. package/symphony/mcp/tools/locks.js +0 -99
  78. package/symphony/mcp/tools/status.js +0 -82
  79. package/symphony/mcp/tools/tasks.js +0 -216
  80. package/symphony/mcp/tools/workspace.js +0 -143
  81. package/symphony/next.config.mjs +0 -7
  82. package/symphony/package.json +0 -53
  83. package/symphony/scripts/postinstall.js +0 -49
  84. package/symphony/symphony.config.js +0 -41
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: seasonal-aso
3
+ description: When the user wants to optimize their App Store listing for seasonal events, holidays, or trending moments — including keyword opportunities, metadata updates, screenshot theming, and timing strategy. Use when the user mentions "seasonal", "holiday", "Christmas", "New Year", "Valentine's Day", "summer", "back to school", "seasonal keywords", "trending now", "limited time", or wants to capitalize on a calendar event. For general keyword research, see keyword-research. For full metadata rewrites, see metadata-optimization.
4
+ metadata:
5
+ version: 1.0.0
6
+ ---
7
+
8
+ # Seasonal ASO
9
+
10
+ You help the user identify and act on seasonal keyword opportunities and listing optimizations tied to calendar events, holidays, and trending moments.
11
+
12
+ ## Key Principle
13
+
14
+ **Seasonal rankings are competitive and time-sensitive.** Metadata takes 1–3 days to index. Plan changes 2 weeks before the event; revert 3–5 days after peak.
15
+
16
+ ## Seasonal Calendar (iOS — US)
17
+
18
+ | Event | Peak Window | Keywords to target |
19
+ |-------|-------------|-------------------|
20
+ | New Year | Dec 26 – Jan 7 | "new year", "resolution", "goals", "habit", "fresh start" |
21
+ | Valentine's Day | Feb 1–14 | "valentine", "love", "couples", "romantic", "gift" |
22
+ | Spring / Easter | Mar–Apr | "spring", "easter", "refresh", "clean", "declutter" |
23
+ | Mother's Day | May 1–12 | "mom", "mother", "family", "gift for mom" |
24
+ | Summer | Jun–Aug | "summer", "vacation", "travel", "outdoor", "beach" |
25
+ | Back to School | Jul 15 – Sep 10 | "school", "study", "student", "homework", "planner" |
26
+ | Halloween | Oct 1–31 | "halloween", "scary", "spooky", "costume", "trick" |
27
+ | Black Friday | Nov 20–30 | "deal", "sale", "discount", "shopping", "gift" |
28
+ | Christmas | Dec 1–26 | "christmas", "gift", "holiday", "santa", "family" |
29
+ | End of Year | Dec 27–31 | "year review", "recap", "goals 2026", "new year" |
30
+
31
+ ## Workflow
32
+
33
+ ### Step 1 — Identify Relevant Event
34
+
35
+ 1. Check for `app-marketing-context.md`
36
+ 2. Ask: **Which event or season are you targeting?**
37
+ 3. Ask: **What does your app do?** (to assess keyword relevance)
38
+ 4. Determine if the event is a good fit — not every seasonal moment applies
39
+
40
+ ### Step 2 — Research Seasonal Keywords
41
+
42
+ Use Appeeky to find volume on seasonal terms:
43
+
44
+ ```bash
45
+ GET /v1/keywords/metrics?keywords=christmas+planner,holiday+tracker
46
+ GET /v1/keywords/suggestions?term=christmas&country=us
47
+ GET /v1/keywords/trending?country=us&days=7
48
+ ```
49
+
50
+ **Filter by:**
51
+ - Volume spike (compare to baseline 30 days prior)
52
+ - Difficulty < 60 preferred (seasonal keywords are crowded)
53
+ - Relevance to your app's core function
54
+
55
+ ### Step 3 — Plan Metadata Changes
56
+
57
+ **Keyword field (100 chars, iOS):**
58
+ - Swap out low-performing keywords for seasonal terms
59
+ - Add 2–4 seasonal keywords while preserving your best evergreen terms
60
+ - Remove seasonal terms that are irrelevant to your core use case
61
+
62
+ **Subtitle (30 chars):**
63
+ - Consider a seasonal hook if it fits: "Your Holiday Planner" or "New Year Goal Tracker"
64
+ - Only change if the original subtitle is not keyword-critical
65
+
66
+ **Promotional text (170 chars — no review required):**
67
+ - Always update for seasonal events — instant, no review
68
+ - Use for: seasonal call-to-action, limited-time feature highlights, event tie-ins
69
+
70
+ **Screenshots:**
71
+ - Add a seasonal frame or theme to the first 2 screenshots
72
+ - Use `screenshot-optimization` skill for creative guidance
73
+
74
+ ### Step 4 — Timing Checklist
75
+
76
+ ```
77
+ Timeline (count back from event date):
78
+ - [ ] T-14 days: Research keywords, brief creative
79
+ - [ ] T-10 days: Write new metadata + promotional text
80
+ - [ ] T-7 days: Submit screenshot updates (no review needed)
81
+ - [ ] T-5 days: Submit keyword/subtitle update (review time buffer)
82
+ - [ ] T-0: Event peak — monitor rankings daily
83
+ - [ ] T+3 days: Revert metadata to evergreen version
84
+ - [ ] T+5 days: Revert promotional text
85
+ ```
86
+
87
+ ## Output Format
88
+
89
+ ### Seasonal Opportunity Brief
90
+
91
+ ```
92
+ 🎄 Seasonal Opportunity: [Event Name]
93
+ Peak window: [dates]
94
+ Lead time needed: [X days]
95
+
96
+ Keyword Opportunities:
97
+ High priority (volume spike, <60 difficulty):
98
+ - "[keyword]" — vol [N], diff [N]
99
+ - "[keyword]" — vol [N], diff [N]
100
+
101
+ Secondary (relevant but competitive):
102
+ - "[keyword]" — vol [N], diff [N]
103
+
104
+ Metadata Recommendations:
105
+ Keyword field: [current] → [proposed — 100 chars]
106
+ Subtitle: [keep / change to: "..."]
107
+ Promo text: "[seasonal copy — 170 chars]"
108
+
109
+ Screenshots: [suggest seasonal theme or keep as-is]
110
+
111
+ Timeline:
112
+ - Submit metadata by: [date]
113
+ - Submit promo text by: [date]
114
+ - Revert by: [date]
115
+ ```
116
+
117
+ ## Seasonal vs Evergreen Trade-offs
118
+
119
+ | Factor | Seasonal | Evergreen |
120
+ |--------|----------|-----------|
121
+ | Volume | Temporarily very high | Stable |
122
+ | Competition | Very high at peak | Moderate |
123
+ | Risk | Rankings drop after peak | Consistent |
124
+ | Reward | Spike in installs | Sustained growth |
125
+
126
+ **Rule:** Only swap evergreen keywords that are already underperforming. Never sacrifice a high-ranking keyword for seasonal speculation.
127
+
128
+ ## Trending Moments (Non-Calendar)
129
+
130
+ For viral/trending moments (news events, viral content, app store trends):
131
+ 1. Use `GET /v1/keywords/trending?country=us&days=3` to spot emerging terms
132
+ 2. Act within 24–48 hours (trending windows are short)
133
+ 3. Only update promotional text (instant, no review)
134
+ 4. Revert after the trend fades (typically 3–7 days)
135
+
136
+ ## Related Skills
137
+
138
+ - `keyword-research` — Deep keyword analysis for seasonal candidates
139
+ - `metadata-optimization` — Rewrite full metadata with seasonal terms
140
+ - `screenshot-optimization` — Design seasonal screenshot themes
141
+ - `market-pulse` — Spot trending keywords and market movements in real time
@@ -0,0 +1,312 @@
1
+ ---
2
+ name: spec-gate
3
+ description: >-
4
+ Gate 2 — Architecture & Data Design Gate. Chốt thiết kế kỹ thuật (DB Schema,
5
+ API Contract, State Machine) TRƯỚC KHI cho phép code. Bắt buộc user approve
6
+ thiết kế để tránh "vừa làm vừa sửa database". Auto-triggered bởi orchestrator
7
+ khi Gate 2 chưa thỏa mãn.
8
+ metadata:
9
+ stage: core
10
+ version: "1.0"
11
+ tags: [gate, architecture, database, design, spec-first, core]
12
+ requires: orchestrator
13
+ agent: Architect
14
+ trigger: conditional
15
+ invocation-type: auto
16
+ priority: 2
17
+ activation_keywords:
18
+ - "thiết kế database"
19
+ - "schema design"
20
+ - "data model"
21
+ - "API design"
22
+ - "architect"
23
+ ---
24
+
25
+ # Spec Gate v1.0 — Architecture & Data Design Gate
26
+
27
+ > **Purpose:** Chốt thiết kế kỹ thuật (DB Schema, API Contract, State Machine)
28
+ > TRƯỚC KHI viết code. Đảm bảo tất cả persistence changes đã được suy nghĩ kỹ
29
+ > và user đã approve trước khi AI bắt tay implement.
30
+ >
31
+ > **Problem it solves:** "Vừa làm vừa sửa database dẫn tới lung tung"
32
+
33
+ ---
34
+
35
+ ## ⚠️ SCOPE CLARITY
36
+
37
+ | Skill này LÀM | Skill này KHÔNG làm |
38
+ |---------------|---------------------|
39
+ | Phác thảo Data Model (tables, fields, indexes) | Viết code |
40
+ | Thiết kế API Contract (endpoints, request/response) | Tạo BRIEF/spec (việc của brainstorm-agent) |
41
+ | Vẽ State Machine diagram (nếu cần) | Track tasks (việc của symphony-enforcer) |
42
+ | Checklist tự kiểm tra thiết kế | Deploy |
43
+ | Yêu cầu user approve design | Sửa lỗi |
44
+
45
+ ---
46
+
47
+ ## 🚀 ACTIVATION
48
+
49
+ Skill này được kích hoạt bởi:
50
+ 1. **Orchestrator auto-trigger:** Khi Gate 2 check FAIL (không tìm thấy design doc đã approved)
51
+ 2. **Explicit command:** `/architect` hoặc `/design-db`
52
+ 3. **Keyword trigger:** "thiết kế database", "schema design", "data model"
53
+
54
+ ---
55
+
56
+ ## 📋 INPUT REQUIREMENTS
57
+
58
+ Trước khi chạy, PHẢI có:
59
+
60
+ ```
61
+ REQUIRED:
62
+ → docs/specs/<feature>.md HOẶC BRIEF.md (output từ Gate 1)
63
+ → .project-identity (projectId, techStack)
64
+
65
+ OPTIONAL:
66
+ → docs/specs/TECH-SPEC.md (project-level constraints)
67
+ → Existing DB schema (nếu project đã có database)
68
+ → NeuralMemory context (decisions trước đó về architecture)
69
+ ```
70
+
71
+ ---
72
+
73
+ ## 🔄 PROCESS
74
+
75
+ ### Phase 1: Context Gathering (Silent)
76
+
77
+ ```
78
+ 1. Đọc BRIEF.md / spec document → Extract:
79
+ - Core entities (Users, Orders, Products...)
80
+ - Relationships (1-N, N-N)
81
+ - Business rules (unique constraints, validation rules)
82
+ - Flows requiring state tracking
83
+
84
+ 2. Đọc .project-identity → Extract:
85
+ - Tech stack (SQL? NoSQL? ORM?)
86
+ - Coding standards
87
+ - Existing patterns
88
+
89
+ 3. Đọc TECH-SPEC.md nếu có → Extract constraints:
90
+ - Database choice (PostgreSQL, Firestore, GRDB, Realm...)
91
+ - Performance requirements
92
+ - Offline-first requirements
93
+ - Migration strategy
94
+
95
+ 4. NeuralMemory recall → Previous architecture decisions
96
+ ```
97
+
98
+ ### Phase 2: Data Model Design
99
+
100
+ ```
101
+ Cho MỖI entity phát hiện từ spec:
102
+
103
+ TABLE/COLLECTION: <name>
104
+ ├── Fields:
105
+ │ ├── id: <type> (PK)
106
+ │ ├── field_1: <type> [NOT NULL | OPTIONAL]
107
+ │ ├── field_2: <type> [DEFAULT: <value>]
108
+ │ └── ...
109
+ ├── Indexes:
110
+ │ ├── idx_<name>_<field> (purpose)
111
+ │ └── ...
112
+ ├── Relationships:
113
+ │ ├── belongs_to: <table> (FK: <field>)
114
+ │ └── has_many: <table>
115
+ └── Constraints:
116
+ ├── UNIQUE: <fields>
117
+ └── CHECK: <condition>
118
+ ```
119
+
120
+ ### Phase 3: API Contract Design (nếu có API)
121
+
122
+ ```
123
+ Cho MỖI endpoint cần thiết:
124
+
125
+ ENDPOINT: [METHOD] /api/<path>
126
+ ├── Purpose: <mô tả ngắn>
127
+ ├── Auth: <required | optional | public>
128
+ ├── Request:
129
+ │ ├── Headers: <required headers>
130
+ │ ├── Params: <path/query params>
131
+ │ └── Body: { field: type, ... }
132
+ ├── Response:
133
+ │ ├── 200: { field: type, ... }
134
+ │ ├── 400: { error: "validation message" }
135
+ │ └── 500: { error: "server error" }
136
+ └── Notes: <edge cases, rate limiting, etc.>
137
+ ```
138
+
139
+ ### Phase 4: State Machine (nếu có stateful flows)
140
+
141
+ ```
142
+ Cho flows có trạng thái chuyển đổi (order lifecycle, booking flow...):
143
+
144
+ STATE MACHINE: <name>
145
+ [initial] → [state_1] → [state_2] → [final]
146
+ ↓ ↓
147
+ [error] [cancelled]
148
+
149
+ Transitions:
150
+ initial → state_1: trigger=<event>, guard=<condition>
151
+ state_1 → state_2: trigger=<event>
152
+ any → cancelled: trigger=user_cancel
153
+ ```
154
+
155
+ ### Phase 5: Self-Review Checklist
156
+
157
+ **TRƯỚC KHI present cho user, AI PHẢI tự kiểm tra:**
158
+
159
+ ```yaml
160
+ checklist:
161
+ data_integrity:
162
+ - [ ] Mọi entity có Primary Key?
163
+ - [ ] Foreign Keys đúng direction?
164
+ - [ ] Không có circular dependencies?
165
+ - [ ] Cascade delete rules đã define?
166
+
167
+ performance:
168
+ - [ ] Indexes cho frequent queries?
169
+ - [ ] N+1 query potential identified?
170
+ - [ ] Pagination strategy cho list endpoints?
171
+ - [ ] Caching strategy nếu cần?
172
+
173
+ consistency:
174
+ - [ ] Chuẩn với .project-identity tech stack?
175
+ - [ ] Chuẩn với TECH-SPEC.md constraints?
176
+ - [ ] Naming convention thống nhất?
177
+ - [ ] Date/time format thống nhất?
178
+
179
+ edge_cases:
180
+ - [ ] Concurrent access handling?
181
+ - [ ] Null/empty value handling?
182
+ - [ ] Soft delete vs hard delete?
183
+ - [ ] Offline-first sync strategy (nếu mobile)?
184
+
185
+ security:
186
+ - [ ] PII data identified + encrypted?
187
+ - [ ] Auth rules per endpoint?
188
+ - [ ] Input validation cho mọi user input?
189
+ ```
190
+
191
+ ### Phase 6: Present & Approval
192
+
193
+ ```
194
+ Present cho user với format:
195
+
196
+ ───────────────────────────────────
197
+ 📐 ARCHITECTURE DESIGN: <Feature Name>
198
+ ───────────────────────────────────
199
+
200
+ ## Data Model
201
+ [Phase 2 output]
202
+
203
+ ## API Endpoints
204
+ [Phase 3 output — nếu có]
205
+
206
+ ## State Machine
207
+ [Phase 4 output — nếu có]
208
+
209
+ ## Self-Review ✅
210
+ [Phase 5 checklist results]
211
+
212
+ ## Concerns & Trade-offs
213
+ - [Concern 1]: [Mô tả + recommendation]
214
+ - [Concern 2]: [Mô tả + recommendation]
215
+
216
+ ───────────────────────────────────
217
+ ⏳ Chờ anh approve thiết kế này trước khi code nhé.
218
+ Sửa gì cứ nói, tôi update lại.
219
+ ───────────────────────────────────
220
+ ```
221
+
222
+ ### Phase 7: Write Design Doc
223
+
224
+ Sau khi user approve:
225
+
226
+ ```
227
+ 1. Tạo folder nếu chưa có: docs/architecture/
228
+ 2. Write file: docs/architecture/<feature>_design.md
229
+ 3. Nội dung = Phase 6 output + approval marker:
230
+
231
+ ## Status: Approved
232
+ **Approved by:** User
233
+ **Approved at:** <ISO date>
234
+ **Conversation:** <conversation-id>
235
+
236
+ 4. Lưu vào NeuralMemory:
237
+ nmem_remember(
238
+ content="Architecture design for <feature> approved. Schema: <summary>",
239
+ type="decision",
240
+ tags=["architecture", "<projectId>", "<feature>"]
241
+ )
242
+
243
+ 5. Proceed → orchestrator re-checks Gate 2 → PASS → Gate 3
244
+ ```
245
+
246
+ ---
247
+
248
+ ## 🔙 DESIGN DEVIATION PROTOCOL
249
+
250
+ Khi AI đang code (Gate 4) và phát hiện cần sửa schema khác approved design:
251
+
252
+ ```
253
+ 1. ⛔ DỪNG CODE NGAY LẬP TỨC
254
+ 2. Thông báo user:
255
+ "Phát hiện cần thêm/sửa [field/table] ngoài thiết kế đã duyệt.
256
+ Để tôi quay lại update design doc trước nhé."
257
+ 3. Mở lại design doc
258
+ 4. Highlight phần cần thay đổi + lý do
259
+ 5. Yêu cầu user re-approve
260
+ 6. Update marker: "## Status: Approved (Revision 2)"
261
+ 7. Tiếp tục code
262
+ ```
263
+
264
+ ---
265
+
266
+ ## 🗣️ Communication Style
267
+
268
+ ```
269
+ ❌ "Architecture document required. Please provide data model specification."
270
+ ✅ "Đã hiểu yêu cầu! Giờ để tôi phác thảo cấu trúc database cho anh xem
271
+ trước — kinh nghiệm cho thấy nếu chốt DB sớm sẽ tiết kiệm rất nhiều
272
+ thời gian sửa lại sau."
273
+
274
+ ❌ "Design review requires your explicit approval."
275
+ ✅ "Anh xem thiết kế này có ổn không? Sửa gì cứ nói, tôi update lại.
276
+ Chốt xong là bắt tay code luôn."
277
+ ```
278
+
279
+ ---
280
+
281
+ ## 🚫 Anti-Patterns
282
+
283
+ ```yaml
284
+ never_do:
285
+ - Tự approve design (user PHẢI approve)
286
+ - Skip self-review checklist
287
+ - Design quá chi tiết cho trivial features (orchestrator đã filter)
288
+ - Bắt đầu code trước khi có approval marker
289
+ - Phớt lờ TECH-SPEC.md constraints
290
+
291
+ always_do:
292
+ - Đọc ALL input sources trước khi design
293
+ - Chạy self-review checklist 100%
294
+ - Highlight trade-offs và concerns
295
+ - Ghi lại decisions vào NeuralMemory
296
+ - Kiểm tra consistency với existing schema
297
+ ```
298
+
299
+ ---
300
+
301
+ ## 🧩 Skill Relationships
302
+
303
+ ```
304
+ TRIGGERED BY: orchestrator (Gate 2 check fail)
305
+ DEPENDS ON: brainstorm-agent output (Gate 1 must pass first)
306
+ FEEDS INTO: symphony-enforcer (Gate 3 reads design doc to create tasks)
307
+ WORKS WITH: nm-memory-sync (store architectural decisions)
308
+ ```
309
+
310
+ ---
311
+
312
+ *spec-gate v1.0 — Architecture & Data Design Gate for AWKit*
@@ -0,0 +1,206 @@
1
+ ---
2
+ name: subscription-lifecycle
3
+ description: When the user wants to optimize their subscription business end-to-end — from trial start through renewal, cancellation, and win-back. Use when the user mentions "subscription lifecycle", "trial conversion", "churn", "cancellation", "win-back", "lapsed subscribers", "dunning", "billing retry", "grace period", "renewal rate", "subscriber LTV", or "resubscribe". For paywall design and pricing strategy, see monetization-strategy. For subscription analytics dashboards, see app-analytics.
4
+ metadata:
5
+ version: 1.0.0
6
+ ---
7
+
8
+ # Subscription Lifecycle
9
+
10
+ You optimize every stage of the subscription journey: trial → paid → renewal → cancellation recovery → win-back.
11
+
12
+ ## The Subscription Lifecycle
13
+
14
+ ```
15
+ Install → Trial start → [Trial period] → Conversion → Renewal → ... → Cancel → Win-back
16
+ ↓ ↓ ↓ ↓
17
+ No convert Voluntary Involuntary Lapsed
18
+ (nurture) (exit survey) (dunning) (campaign)
19
+ ```
20
+
21
+ ## Key Metrics at Each Stage
22
+
23
+ | Stage | Metric | Formula | Benchmark |
24
+ |-------|--------|---------|-----------|
25
+ | Trial | Trial start rate | Trials / Downloads | > 20% |
26
+ | Trial | Trial-to-paid | Conversions / Trials | 25–40% strong |
27
+ | Retention | Month 1 renewal | M1 renewals / Subscribers | > 70% |
28
+ | Retention | Month 6 renewal | M6 renewals / Subscribers | > 50% |
29
+ | Churn | Monthly churn | Lost subs / Start subs | < 5% good; < 2% excellent |
30
+ | Revenue | MRR | Active subs × monthly price | — |
31
+ | Revenue | LTV | ARPU / Monthly churn rate | — |
32
+ | Recovery | Dunning recovery | Recovered / Failed payments | > 30% |
33
+ | Win-back | Resubscribe rate | Returns / Lapsed | 5–15% |
34
+
35
+ ## Stage 1 — Trial Optimization
36
+
37
+ ### Trial Length
38
+
39
+ | App Type | Recommended trial | Notes |
40
+ |----------|------------------|-------|
41
+ | Simple utility | 3–7 days | Value obvious quickly |
42
+ | Health/fitness | 7–14 days | Habit formation needs time |
43
+ | Productivity | 7–14 days | Workflow integration |
44
+ | Education | 7–14 days | First lesson completion |
45
+ | Entertainment | 7 days | Binge behavior |
46
+
47
+ **Test:** Monthly apps with a 7-day trial vs. 14-day trial — conversion rate may drop slightly but LTV often increases.
48
+
49
+ ### Trial Nurture Sequence
50
+
51
+ Send in-app (or push) messages during the trial to drive activation:
52
+
53
+ ```
54
+ Day 0: Welcome — "Your trial has started. Here's how to get the most from it."
55
+ Day 1: Core feature highlight — "Try [key feature] today"
56
+ Day 3: Progress / social proof — "Users who do X get 3× better results"
57
+ Day 5 (7-day trial): Urgency — "2 days left in your trial"
58
+ Day 6: Value recap — "Here's what you've done / could do with premium"
59
+ Day 7: Last day — "Your trial ends today"
60
+ ```
61
+
62
+ **Rule:** Messages should show value, not just create pressure.
63
+
64
+ ### Trial End — Conversion Moment
65
+
66
+ At trial end, show a paywall that:
67
+ - Recaps what the user achieved during the trial
68
+ - Shows the most-used premium features
69
+ - Offers 3 plan options (monthly / annual / lifetime if applicable)
70
+ - Highlights savings on annual ("Save 40%")
71
+
72
+ See `monetization-strategy` for paywall design details.
73
+
74
+ ## Stage 2 — Reducing Voluntary Churn
75
+
76
+ ### Why Users Cancel (and How to Fix It)
77
+
78
+ | Reason | Signal | Fix |
79
+ |--------|--------|-----|
80
+ | Forgot they subscribed | Low sessions, no activation | Improve onboarding + notification strategy |
81
+ | Not enough value | Low feature usage | Push underused high-value features |
82
+ | Too expensive | Price sensitivity | Introduce lower-tier or pause option |
83
+ | Problem with app | 1-star reviews | Fix the bug, reply to reviews |
84
+ | Found alternative | — | Monitor competitor installs |
85
+ | Seasonal use | Churns at same time yearly | Offer a pause option |
86
+
87
+ ### The Cancellation Flow
88
+
89
+ When a user initiates cancellation (iOS — `ManagedSubscriptionGroup`):
90
+
91
+ 1. **Offer a pause** before full cancel: "Pause for 1–3 months instead of cancelling"
92
+ 2. **Show value recap**: "You've used [feature] X times this month"
93
+ 3. **Offer a discount**: Only as last resort — 20–30% off for 3 months
94
+ 4. **Exit survey**: Always ask "Why are you cancelling?" (1 tap, not an essay)
95
+
96
+ **Cancellation exit survey options:**
97
+ - Too expensive
98
+ - Not using it enough
99
+ - Missing a feature I need
100
+ - Switching to a competitor
101
+ - Technical issues
102
+ - Just taking a break
103
+
104
+ ### Engagement Signals to Watch
105
+
106
+ Users at high churn risk:
107
+ - Sessions < 1 per week (down from higher baseline)
108
+ - Core feature not used in 14+ days
109
+ - Push notifications disabled
110
+ - Last session > 7 days ago
111
+
112
+ Trigger a re-engagement push or in-app message before they cancel.
113
+
114
+ ## Stage 3 — Involuntary Churn (Failed Payments)
115
+
116
+ Involuntary churn accounts for **20–40%** of all subscription cancellations.
117
+
118
+ ### Dunning Strategy
119
+
120
+ | Day | Action |
121
+ |-----|--------|
122
+ | 0 | Payment fails silently — Apple/Google retry |
123
+ | 3 | Apple/Google retry #2 |
124
+ | 7 | Apple/Google retry #3 — show in-app "Update payment method" banner |
125
+ | 10 | Send push: "Your subscription couldn't be renewed — tap to update" |
126
+ | 14 | Grace period ends — subscription suspended |
127
+ | 15 | Final in-app message: "Reactivate to keep access" |
128
+
129
+ **Grace period:**
130
+ - iOS: 6 days (configurable up to 16 in App Store Connect)
131
+ - Android: 3 days (configurable)
132
+
133
+ Maximize grace period length — every extra day recovers more subscribers.
134
+
135
+ ### RevenueCat Integration
136
+
137
+ RevenueCat handles dunning automatically. Key settings:
138
+ - Enable Billing Retry (iOS) / Account Hold (Android)
139
+ - Configure grace period to maximum allowed
140
+ - Use RevenueCat webhooks to trigger in-app messaging at each failure event
141
+
142
+ See `revenuecat.md` integration guide.
143
+
144
+ ## Stage 4 — Win-Back Campaigns
145
+
146
+ Target lapsed subscribers (cancelled or expired in last 30–90 days).
147
+
148
+ ### Win-Back Offer Ladder
149
+
150
+ Start with the softest offer; escalate only if no response:
151
+
152
+ ```
153
+ Week 1 after lapse: "We miss you" — highlight new features added since they left
154
+ Week 3: "Come back for 30% off your first month back"
155
+ Week 6: "3 months at 50% off — best offer we'll make"
156
+ Week 12+: Archive — low conversion probability
157
+ ```
158
+
159
+ ### Win-Back Channels
160
+
161
+ | Channel | How |
162
+ |---------|-----|
163
+ | Push notification | In-app if app still installed |
164
+ | Email | If email was collected |
165
+ | Apple Win-Back Offer | Native iOS win-back offer in StoreKit 2 |
166
+ | Paid retargeting | Meta/Google retargeting to lapsed subscriber list |
167
+
168
+ ### StoreKit 2 Win-Back Offers (iOS 18+)
169
+
170
+ Apple natively supports win-back subscription offers for lapsed subscribers:
171
+ - Set up in App Store Connect → Subscriptions → Win-Back Offers
172
+ - Presented automatically in the App Store to eligible lapsed users
173
+ - No additional code needed beyond StoreKit 2 integration
174
+
175
+ ## Output Format
176
+
177
+ ### Subscription Health Report
178
+
179
+ ```
180
+ Lifecycle Metrics ([period]):
181
+
182
+ Trial start rate: [X]% (benchmark: >20%)
183
+ Trial conversion: [X]% (benchmark: 25-40%)
184
+ M1 renewal: [X]% (benchmark: >70%)
185
+ Monthly churn: [X]% (benchmark: <5%)
186
+ Dunning recovery: [X]% (benchmark: >30%)
187
+ Win-back rate: [X]% (benchmark: 5-15%)
188
+
189
+ LTV (estimated): $[N]
190
+ MRR: $[N]
191
+
192
+ Top issues:
193
+ 1. [Stage] — [metric] is [X]% vs benchmark [Y]% — [recommended fix]
194
+ 2. [Stage] — [metric] is [X]% vs benchmark [Y]% — [recommended fix]
195
+
196
+ Priority action:
197
+ [Single highest-leverage change to implement this week]
198
+ ```
199
+
200
+ ## Related Skills
201
+
202
+ - `monetization-strategy` — Paywall design, pricing tiers, trial setup
203
+ - `retention-optimization` — Engagement strategy to reduce voluntary churn
204
+ - `app-analytics` — Track the metrics above with Firebase + RevenueCat
205
+ - `onboarding-optimization` — Fix early-stage drop-off that prevents trial starts
206
+ - `rating-prompt-strategy` — Satisfied subscribers are your best raters