@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.
- package/README.md +51 -1
- package/bin/awk.js +2 -2
- package/core/GEMINI.md +45 -7
- package/package.json +8 -5
- package/skill-packs/neural-memory/skills/nm-memory-sync/SKILL.md +14 -1
- package/skills/ab-test-store-listing/SKILL.md +220 -0
- package/skills/android-aso/SKILL.md +197 -0
- package/skills/app-analytics/SKILL.md +210 -0
- package/skills/app-clips/SKILL.md +163 -0
- package/skills/app-icon-optimization/SKILL.md +170 -0
- package/skills/app-launch/SKILL.md +153 -0
- package/skills/app-marketing-context/SKILL.md +129 -0
- package/skills/app-store-featured/SKILL.md +213 -0
- package/skills/apple-search-ads/SKILL.md +205 -0
- package/skills/asc-metrics/SKILL.md +157 -0
- package/skills/aso-audit/SKILL.md +179 -0
- package/skills/competitor-analysis/SKILL.md +163 -0
- package/skills/competitor-tracking/SKILL.md +185 -0
- package/skills/crash-analytics/SKILL.md +181 -0
- package/skills/gitnexus-intelligence/SKILL.md +224 -0
- package/skills/in-app-events/SKILL.md +176 -0
- package/skills/keyword-research/SKILL.md +141 -0
- package/skills/localization/SKILL.md +165 -0
- package/skills/market-movers/SKILL.md +137 -0
- package/skills/market-pulse/SKILL.md +170 -0
- package/skills/metadata-optimization/SKILL.md +170 -0
- package/skills/monetization-strategy/SKILL.md +175 -0
- package/skills/onboarding-optimization/SKILL.md +194 -0
- package/skills/orchestrator/SKILL.md +306 -25
- package/skills/press-and-pr/SKILL.md +204 -0
- package/skills/rating-prompt-strategy/SKILL.md +184 -0
- package/skills/retention-optimization/SKILL.md +165 -0
- package/skills/review-management/SKILL.md +154 -0
- package/skills/screenshot-optimization/SKILL.md +167 -0
- package/skills/seasonal-aso/SKILL.md +141 -0
- package/skills/spec-gate/SKILL.md +312 -0
- package/skills/subscription-lifecycle/SKILL.md +206 -0
- package/skills/swiftui-pro/references/design.md +44 -0
- package/skills/symphony-enforcer/SKILL.md +92 -11
- package/skills/symphony-orchestrator/SKILL.md +9 -7
- package/skills/systematic-debugging/SKILL.md +32 -7
- package/skills/ua-campaign/SKILL.md +207 -0
- package/skills/verification-gate/SKILL.md +23 -2
- package/workflows/gitnexus.md +123 -0
- package/symphony/LICENSE +0 -21
- package/symphony/README.md +0 -178
- package/symphony/app/api/agents/route.js +0 -152
- package/symphony/app/api/events/route.js +0 -22
- package/symphony/app/api/knowledge/route.js +0 -253
- package/symphony/app/api/locks/route.js +0 -29
- package/symphony/app/api/notes/route.js +0 -125
- package/symphony/app/api/preflight/route.js +0 -23
- package/symphony/app/api/projects/route.js +0 -116
- package/symphony/app/api/roles/route.js +0 -134
- package/symphony/app/api/skills/route.js +0 -82
- package/symphony/app/api/status/route.js +0 -18
- package/symphony/app/api/tasks/route.js +0 -157
- package/symphony/app/api/workflows/route.js +0 -61
- package/symphony/app/api/workspaces/route.js +0 -15
- package/symphony/app/globals.css +0 -2605
- package/symphony/app/layout.js +0 -20
- package/symphony/app/page.js +0 -2122
- package/symphony/cli/index.js +0 -1060
- package/symphony/core/agent-manager.js +0 -357
- package/symphony/core/context-bus.js +0 -100
- package/symphony/core/db.js +0 -223
- package/symphony/core/file-lock-manager.js +0 -154
- package/symphony/core/merge-pipeline.js +0 -234
- package/symphony/core/orchestrator.js +0 -236
- package/symphony/core/task-manager.js +0 -335
- package/symphony/core/workspace-manager.js +0 -168
- package/symphony/jsconfig.json +0 -7
- package/symphony/lib/core.mjs +0 -1034
- package/symphony/mcp/index.js +0 -29
- package/symphony/mcp/server.js +0 -110
- package/symphony/mcp/tools/context.js +0 -80
- package/symphony/mcp/tools/locks.js +0 -99
- package/symphony/mcp/tools/status.js +0 -82
- package/symphony/mcp/tools/tasks.js +0 -216
- package/symphony/mcp/tools/workspace.js +0 -143
- package/symphony/next.config.mjs +0 -7
- package/symphony/package.json +0 -53
- package/symphony/scripts/postinstall.js +0 -49
- 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
|