feat: implement async loop mode, milestone tracking, and referral system

Author: Bharath-code

AGENTS.md

@@ -19,15 +19,17 @@ node packages/cli/dist/index.js --help
 
 ```
 packages/cli/src/
-  commands/        ← one file per command (init, track, ship, pulse, loop, auth, celebrate, telemetry, radar, keywords, timing, coach)
-  analytics/       ← telemetry, benchmarks, dna, oracle, churn, autoLoop, predictor, competitorRadar, keywordFinder, marketTiming, patterns, peers, coach
+  commands/        ← one file per command (init, track, ship, pulse, loop, auth, celebrate, telemetry, radar, keywords, timing, coach, revenue, remind, aliases)
+  analytics/       ← telemetry, benchmarks, dna, oracle, churn, autoLoop, predictor, competitorRadar, keywordFinder, marketTiming, patterns, peers, coach, score
   templates/       ← project template scaffolds (saas, api, mobile, cli, newsletter, agency, open-source, marketplace, ai-wrapper)
   ai/prompts/      ← system prompts
   ai/client.ts     ← generateStructured() wrapper (with cache + resolveAuth)
   storage/local.ts ← all .loopkit/ file I/O
-  storage/sync.ts  ← CLI → Convex push (loop logs + ship logs + radar + timing)
+  storage/sync.ts  ← CLI → Convex push (loop logs + ship logs + radar + timing + milestone + win)
   storage/cache.ts ← AI result cache (hash-based, 7-day TTL)
   ui/theme.ts      ← terminal colors/UI helpers
+  cron/            ← cron job installer for Friday reminder
+  notifications/   ← terminal notification system (macOS/Linux/Windows)
 
 packages/shared/src/index.ts  ← ALL Zod schemas (single source of truth)
 
@@ -98,7 +100,7 @@ const result = await generateStructured({
 - Team collaboration
 - Mobile app / VS Code extension
 - Zapier/Make integrations
-- Any 14th command beyond the current 13 (init/track/ship/pulse/loop/auth/celebrate/telemetry/radar/keywords/timing/coach/revenue)
+- Any 16th command beyond the current 15 (init/track/ship/pulse/loop/auth/celebrate/telemetry/radar/keywords/timing/coach/revenue/remind/aliases)
 - New npm deps that duplicate existing functionality
 
 ## Approved Extensions (user-approved, April 2026)
@@ -109,6 +111,7 @@ const result = await generateStructured({
 | **Proof Card** | `ui/proof-card.ts` | Shareable weekly card, clipboard auto-copy |
 | **Daily Standup** | `loopkit track --stand` | Flag on existing `track` command |
 | **Revenue Tracker** | `loopkit revenue` (13th command) | Structured MRR records, switching-cost feature |
+| **Growth Loops** | Milestone system, Friday reminder, validation, aliases, async loop, referral, public wins | Habit-forming infrastructure for retention and growth (Phase 13) |
 
 ---
 

CLAUDE.md

@@ -95,29 +95,39 @@ src/
 │   ├── keywords.ts       # loopkit keywords
 │   ├── timing.ts         # loopkit timing
 │   ├── coach.ts          # loopkit coach
-│   └── revenue.ts        # loopkit revenue
+│   ├── revenue.ts        # loopkit revenue
+│   ├── remind.ts         # loopkit remind:friday (cron-triggered)
+│   └── aliases.ts        # loopkit aliases (shell shortcuts)
 ├── analytics/
 │   ├── telemetry.ts      # Opt-in usage collection (on/off/export/delete)
 │   ├── dna.ts            # Shipping DNA profile (founder pattern detection)
 │   ├── benchmarks.ts     # Smart percentile rankings vs baseline
 │   ├── oracle.ts         # Snooze completion probability oracle
 │   ├── churn.ts          # Churn Guardian: declining score, skipped loops, override rate
 │   ├── autoLoop.ts       # Auto-Loop: missed Sunday detection + auto-draft
-│   └── predictor.ts      # Success Predictor: revenue probability heuristic
+│   ├── predictor.ts      # Success Predictor: revenue probability heuristic
+│   ├── score.ts          # LoopKit Score™ calculation
+│   └── patterns.ts       # Pattern detection for coaching moments
 ├── ai/
 │   ├── client.ts         # generateStructured() wrapper (resolveAuth + cache)
 │   └── prompts/
 │       ├── init.ts       # System prompt + few-shot examples
 │       ├── ship.ts       # Launch copy system prompt
 │       ├── pulse.ts      # Clustering system prompt
 │       ├── loop.ts       # Weekly synthesis system prompt
-│       └── unstuck.ts    # Micro-task generation prompt
+│       ├── unstuck.ts    # Micro-task generation prompt
+│       └── validation.ts # Devil's advocate validation prompt
 ├── storage/
 │   ├── local.ts          # All .loopkit/ file operations
-│   ├── sync.ts           # CLI → Convex sync for loop/ship/radar/timing
+│   ├── sync.ts           # CLI → Convex sync for loop/ship/radar/timing/milestone/win
 │   └── cache.ts          # AI result cache (hash-based, 7-day TTL)
+├── cron/
+│   └── installer.ts      # Cron job installer for Friday reminder
+├── notifications/
+│   └── terminal.ts      # Terminal notification system (macOS/Linux/Windows)
 └── ui/
-    └── theme.ts           # Colors, scoreBar, box, header helpers
+    ├── theme.ts           # Colors, scoreBar, box, header helpers
+    └── proof-card.ts     # Proof card generation and clipboard copy
 ```
 
 ### Critical: Local Storage Layout
@@ -171,6 +181,8 @@ src/
 | `churn.ts` | `detectChurnRisk()`, `renderChurnWarning()` — declining score, skipped loops, overrides |
 | `autoLoop.ts` | `checkMissedSunday()`, `saveAutoLoopDraft()` — Monday auto-draft generation |
 | `predictor.ts` | `predictSuccess()`, `renderPrediction()` — 8-week revenue probability heuristic |
+| `score.ts` | `computeLoopKitScore()`, `renderLoopKitScore()` — LoopKit Score™ calculation |
+| `patterns.ts` | `detectPatterns()`, coaching moment detection |
 | `cache.ts` | `getCachedResult()`, `setCachedResult()` — hash-based AI result reuse, 7-day TTL |
 
 ### AI Usage Pattern
@@ -220,7 +232,10 @@ Schemas defined:
 - `PulseClusterSchema` — AI clustering output
 - `LoopSynthesisSchema` — week win + one thing + BIP post + founder note
 - `LoopLogSchema` — weekly proof metrics (`previousScore`, `currentScore`, `scoreDelta`, `weeksActive`, `decisionsMade`, `feedbackResponses`, `feedbackActedOn`)
-- `ConfigSchema` — user config
+- `ConfigSchema` — user config (includes `aliasesInstalled`, `referralShown`, `referralCode`)
+- `ValidationQuestionsSchema` — devil's advocate validation output (3 questions + encouragement)
+- `RevenueEntrySchema` — MRR tracking records
+- `StandupLogSchema` — daily standup logs
 - Helpers: `slugify()`, `getWeekNumber()`, `formatDate()`
 
 ---
@@ -341,6 +356,7 @@ When adding a new AI feature:
 | 10 — Analytics Phase 1 | ✅ Done | Telemetry, Shipping DNA, Benchmarks CLI, Snooze Oracle |
 | 11 — Analytics Phase 2 | ✅ Done | CSRF, resolveAuth, AI cache, git hook opt, Archetypes, Churn, Auto-Loop, Predictor |
 | 12 — Growth Features | ✅ Done | LoopKit Score, Proof Card, Daily Standup, Revenue Tracker |
+| 13 — Growth Loops | ✅ Done | Milestone system, Friday reminder, validation mode, shell aliases, async loop, referral system, public wins |
 
 ---
 

README.md

@@ -39,6 +39,8 @@ These commands support the loop, but they are not the product's center of gravit
 | `loopkit timing`               | Market timing signal — is your space heating up?         |
 | `loopkit coach`                | AI coaching based on your shipping patterns              |
 | `loopkit revenue`              | Track structured MRR/ARR records                         |
+| `loopkit celebrate`            | ASCII confetti + shareable proof card                    |
+| `loopkit aliases`             | Manage shell aliases for faster commands                |
 | `loopkit init --template <id>` | Pre-fill & AI-personalize tasks with 9 project templates |
 
 ## Quick Start
@@ -83,6 +85,9 @@ Five questions. AI scoring. A brief that stings when it should.
 - Riskiest assumption named explicitly
 - One async validation action you can do tonight
 - **Sunday Reminder**: Provides a helpful hint to set a recurring calendar event or cron job to close your week
+- **Friday Reminder**: `--cron` flag installs a cron job that reminds you to ship every Friday at 4 PM
+- **Validation Mode**: `--validate` flag runs a devil's advocate AI to stress-test your brief before building
+- **Shell Aliases**: Prompted on first run to install shortcuts (lk, lks, lkl, lkt) for faster commands
 
 ### `loopkit track` — zero-overhead task management
 
@@ -93,6 +98,7 @@ Five questions. AI scoring. A brief that stings when it should.
 - Cut tasks archived to `cut.md` — never silently deleted
 - Shipping score: tasks completed / tasks planned
 - **Daily Standup**: `loopkit track --stand` prompts for your #1 focus today and logs it to track daily momentum
+- **Almost There Nudge**: When shipping score is 50-70% with 2 tasks left, suggests completing them to hit 80%
 
 ### `loopkit ship` — never stare at a blank tweet again
 
@@ -125,8 +131,39 @@ Five questions. AI scoring. A brief that stings when it should.
 - Context-aware upgrade prompts at week 4 or 8
 - Override rate tracked — warns if you're overriding AI > 50% of the time
 - Generates a build-in-public post (280-char checked)
+- **Async Mode**: `--async` flag allows running loop any day within a 7-day window without breaking streak
+- **Milestone System**: Detects and celebrates key moments (first week, month 1, first revenue, streak breaks, pricing signals)
+- **Referral Prompt**: At streak ≥4, prompts to share LoopKit with friends for 1-month free credit
 - One decision. One post. Week done.
 
+### `loopkit celebrate` — celebrate your wins
+
+- ASCII confetti burst for visual celebration
+- Displays your shipping score, streak, and rank title
+- **LoopKit Score™** breakdown
+- Revenue display if MRR > 0
+- Shareable proof card auto-copies to clipboard
+- **Public Wins**: `--share` flag posts your win to the public feed at loopkit.dev/wins for accountability and discovery
+
+### `loopkit aliases` — faster commands
+
+- Installs shell shortcuts for common commands (lk, lks, lkl, lkt)
+- Supports zsh, bash, and fish shells
+- Prompted on first run after `loopkit init`
+- Remove with `loopkit aliases --remove`
+
+## Growth & Retention Features
+
+LoopKit includes several features designed to build habits and drive retention:
+
+- **Milestone System**: Automatically detects and celebrates 5 key moments (first week, month 1, first revenue, streak breaks, pricing signals) with encouraging messages
+- **Friday Reminder**: Cron job (`loopkit init --cron`) reminds you to ship every Friday at 4 PM with terminal notifications
+- **Async Loop Mode**: `--async` flag allows flexible scheduling without breaking your streak
+- **Almost There Nudge**: Encourages completion when you're at 50-70% shipping score with 2 tasks remaining
+- **Referral System**: Share your referral link (at streak ≥4) to earn 1-month free credits
+- **Public Wins Feed**: Share your wins to the community for accountability and discovery
+- **Validation Mode**: `--validate` flag runs a devil's advocate AI to stress-test your brief before building
+
 ## Pricing
 
 | Tier | Price      | Includes                                             |

docs/QUICK_START.md

@@ -22,6 +22,10 @@ loopkit init my-project
 
 Answer 5 questions. Be specific. The AI will give you the first value fast: one uncomfortable truth, a scored bet, and a validation action you can do tonight.
 
+**Optional flags:**
+- `--cron` — Install a Friday reminder cron job (4 PM)
+- `--validate` — Run devil's advocate AI to stress-test your brief
+
 **Tip:** If your ICP score is < 7, narrow your target customer. "Freelance designers in Berlin" beats "creative professionals."
 
 ---
@@ -86,6 +90,8 @@ loopkit loop
 
 Review your week. LoopKit shows what moved forward, proof this week (score delta, weeks active, decisions made, feedback acted on), and the AI's recommendation for next week. Share your build-in-public post.
 
+**Optional flag:** `--async` — Run loop any day within a 7-day window without breaking your streak
+
 **Do this every Sunday.** This is the habit that separates founders who ship from founders who don't.
 
 ---
@@ -116,11 +122,14 @@ Review your week. LoopKit shows what moved forward, proof this week (score delta
 ```bash
 # Define
 loopkit init my-project
+loopkit init --cron                    # Install Friday reminder cron
+loopkit init --validate                # Run devil's advocate validation
 
 # Develop
 loopkit track                          # View board
 loopkit track --add "Task title"       # Add task
 loopkit track --project other-project  # Switch project
+loopkit track --stand                  # Daily standup (60s)
 
 # Deliver
 loopkit ship                           # Generate launch copy
@@ -132,6 +141,11 @@ loopkit pulse                          # View clusters
 
 # Iterate
 loopkit loop                           # Weekly synthesis
+loopkit loop --async                  # Run any day within 7-day window
+
+# Celebrate
+loopkit celebrate                      # Show shipping score + confetti
+loopkit celebrate --share              # Post win to public feed
 
 # Auth
 loopkit auth                           # Log in
@@ -146,8 +160,13 @@ loopkit timing --category "saas"       # Check timing for a specific category
 loopkit telemetry on                   # Opt-in to anonymous usage data
 loopkit telemetry off                  # Opt-out
 loopkit telemetry status               # Check current status
+
+# Utilities
+loopkit aliases                        # Manage shell shortcuts
+loopkit aliases --remove               # Remove shell shortcuts
+loopkit revenue                        # Track MRR milestones
 ```
 
 ---
 
-*Last updated: April 2026 · v0.1.0 (Sharp v1 refinement: fast init, uncomfortable truth, proof loops, Sunday reward, upgrade-intent probes · IE-7 through IE-17 shipped)*
+*Last updated: April 2026 · v0.1.0 (Sharp v1 refinement: fast init, uncomfortable truth, proof loops, Sunday reward, upgrade-intent probes · IE-7 through IE-17 shipped · Phase 13 growth loops: milestones, Friday reminder, validation, aliases, async loop, referral, public wins)*