Skip to content

Melvynx/saveit.now / .agents/skills/ns

Route NowStack Mobile lifecycle goals across setup, product planning, verification, live Simulator preview, security, analytics, email, web, iOS, Android, production audits, and release. Use for `/ns` commands or natural-language product goals.

FileKindSize
README.mdmarkdown6.4 KB
SKILL.mdskill md17.9 KB
---
name: ns
description: "Route NowStack Mobile lifecycle goals across setup, product planning, verification, live Simulator preview, security, analytics, email, web, iOS, Android, production audits, and release. Use for `/ns` commands or natural-language product goals."
argument-hint: "[onboard|app-onboarding|create-app|prd|architecture|tasks|doctor|accounts|setup|check|verify|preview|security|launch-audit|analytics|email|google-auth|apple-auth|set-admin|dev|setup-expo|stripe|r2|notification|screenshots|icon|images|docs|optimize|release|ios ...|android ...|web ...|status] or a goal in natural language"
---

# NowStack - Product CLI

One command for the whole app lifecycle. This skill is the INDEX that ROUTES and SEQUENCES — each workflow is its own standalone `ns-*` skill (auto-invocable on its own, e.g. "deploy my app" can trigger `ns-web-deploy` / `ns-ios-distribute` directly). Never duplicate their content here; invoke or read the target skill.

## Platform Build Routing

For every mobile build, beta, TestFlight, Play, release, or store-submission workflow, detect the user's OS before choosing a build path:

```bash
uname -s   # Darwin = macOS; Linux = Linux; Windows = use PowerShell/Node platform checks
```

- **macOS / Darwin**: local build paths are allowed for both iOS and Android (`eas build --local`, Xcode, Gradle/Android Studio). Prefer local builds by default when signing/tooling is available.
- **Windows or Linux**: do not attempt local iOS or Android production builds. Load/follow `.agents/skills/ns-setup-expo/SKILL.md` first, verify `eas-cli`, `eas whoami`, linked `easProjectId`, and `expo-doctor`, then use EAS cloud builds for the build artifact.
- If `uname` is unavailable, detect with `node -p "process.platform"` or PowerShell. Treat `darwin` as macOS; treat `win32` and `linux` as EAS-cloud-only for production mobile builds.

Parse `$ARGUMENTS`:
1. Starts with a known subcommand → route per the tables below; the rest of the line is context for the target workflow.
2. `help`, or a question about the CLI itself ("what can you do?") → explain yourself: one line on what /ns is, the subcommand tables below with their one-line purposes, then a one-line lifecycle status with the recommended next command.
3. Empty or `status` → Lifecycle Status below.
4. Anything else (e.g. "deploy l'application web et l'application ios") → Natural-Language Mode below.

## Subcommands

| Subcommand | What it does | Follow this file |
| --- | --- | --- |
| `onboard` | **First-run wizard.** Chains the whole initial setup: tools → accounts → Convex → your own clean Git repo → product brief → rebrand → finish | `.agents/skills/ns-onboard/SKILL.md` |
| `doctor` | Install the developer CLIs this machine needs (eas, vercel, gpc, asc, fastlane, bun, gcloud) via brew/npm; offer Xcode/Android Studio. Run before `accounts` | `.agents/skills/ns-doctor/SKILL.md` |
| `accounts` | Create + connect external accounts (Convex, Expo/EAS, Apple, Vercel, Stripe, Play). Verifies, logs in, writes credentials. Skippable per account | `.agents/skills/ns-setup-accounts/SKILL.md` |
| `google-auth` (alias `setup-google-auth`) | Create and verify deployment-specific Google OAuth credentials; pass `--prod` for production | `.agents/skills/ns-setup-google-auth/SKILL.md` |
| `apple-auth` (alias `setup-apple-auth`) | Configure Apple Services ID + signed client-secret JWT; pass `--prod` for production rotation | `.agents/skills/ns-setup-apple-auth/SKILL.md` |
| `setup` | Initialize/rebrand the boilerplate as a real product (site-config, copy, Convex env) | `.agents/skills/ns-init-project/SKILL.md` |
| `check` | Strict read-only configuration/account/production readiness contract with JSON output | `.agents/skills/ns-check-setup/SKILL.md` |
| `verify` | Cross-surface runtime proof for web, iOS, Android, and Convex | `.agents/skills/ns-verify/SKILL.md` |
| `preview` (alias `show`) | Mirror one explicit iOS Simulator into a live browser preview through `serve-sim`, then drive the app from that browser | `.agents/skills/ns-preview/SKILL.md` |
| `security` (alias `security-audit`) | Audit and remediate auth, payment, data, native-client, upload, and abuse boundaries | `.agents/skills/ns-security-audit/SKILL.md` |
| `launch-audit` (alias `audit-launch`) | Read-only fail-closed GO/NO-GO audit across every launch surface | `.agents/skills/ns-launch-audit/SKILL.md` |
| `app-onboarding` (alias `setup-app-onboard`) | Design and verify the end-user activation journey; distinct from first-clone `onboard` | `.agents/skills/ns-setup-app-onboard/SKILL.md` |
| `analytics` | Privacy-safe PostHog event, consent, identity, and environment ownership across mobile/web | `.agents/skills/ns-analytics/SKILL.md` |
| `email` (alias `setup-email`) | Configure and prove Resend/Convex transactional email for the selected deployment | `.agents/skills/ns-setup-email/SKILL.md` |
| `set-admin` | Grant admin access to a user by email (Convex `isAdmin`). Fixes `/admin` denial / infinite loader | `.agents/skills/ns-set-admin/SKILL.md` |
| `dev` | Run the app locally | inline, see Dev below |
| `stripe` | Configure Stripe payments (web/Android) | `.agents/skills/ns-setup-stripe/SKILL.md` |
| `r2` | Set up Cloudflare R2 image/file uploads (bucket, S3 creds, Convex env) | `.agents/skills/ns-setup-r2/SKILL.md` |
| `notification` (alias `notifications`, `push`) | Set up iOS/APNs-oriented Expo push notifications with Convex tokens/preferences/logs and admin tests | `.agents/skills/ns-ios-notification/SKILL.md` |
| `setup-ios` | Legacy alias for `ios local-setup` | `.agents/skills/ns-ios-setup/SKILL.md` |
| `setup-android` | Set up the **local** Android dev env (Android Studio, SDK tools, JDK 17, Pixel AVD) and run the first `npm run android` in the emulator. macOS local path; Windows/Linux release builds route through EAS. NOT the Play internal/production release setup — that's `android beta` / `android distribute` | `.agents/skills/ns-setup-android/SKILL.md` |
| `setup-expo` | Set up the **Expo/EAS platform** layer: eas-cli, log into the Expo account, link the EAS project (writes `easProjectId` into `site-config.ts`), validate with `expo-doctor`. Required before Windows/Linux cloud builds. NOT the local Mac toolchain (`ios local-setup`) nor the build itself (`ios testflight`) | `.agents/skills/ns-setup-expo/SKILL.md` |
| `screenshots` | Generate store screenshots | `.agents/skills/ns-generate-store-screenshots/SKILL.md` |
| `icon` (alias `app-icon`, `logo`) | Generate the **app icon/logo system**: exactly 8 different iOS-quality icon candidates first, one polished final iOS icon next, then Android adaptive + favicon/web logo assets. REQUIRES an image-generation tool (Codex/gpt-image); other agents follow its fallback | `.agents/skills/ns-icon/SKILL.md` |
| `images` | Generate onboarding backgrounds, splash, brand art (NOT the icon — that's `icon`). REQUIRES an image-generation tool (Codex/gpt-image); other agents follow its fallback | `.agents/skills/ns-images/SKILL.md` |
| `docs` | Write/update repo docs in `docs/` (house style, real paths, verified commands) | `.agents/skills/ns-add-documentation/SKILL.md` |
| `optimize` | Performance/quality pass across Convex, Expo, and TanStack Start | `.agents/skills/ns-optimizer/SKILL.md` |
| `release` | Cut a release: bump version, generate changelog, promote the latest TestFlight + Play-internal build to production (no rebuild) | `.agents/skills/ns-release/SKILL.md` |
| `status` | Where is this app in the lifecycle? What's next? | inline, below |

### `planning` pipeline (mobile-aware PRD → architecture → tasks)

`create-app` runs the whole pipeline in one flow; or call a single step. Each step reads the previous doc. Feeds `/ns setup` (config values) and implementation (`apex`/`oneshot`).

| Subcommand | What it does | Follow this file |
| --- | --- | --- |
| `create-app` | **One command: idea → build-ready plan.** Orchestrates PRD → architecture → tasks, then offers `/ns setup` + hands off to `apex`/`oneshot`. Use to start a new product | `.agents/skills/ns-create-app/SKILL.md` |
| `prd` | Interactive discovery → `.agents/plan/PRD.md` (vision, personas, onboarding/paywall flow, platforms, IAP/subscription monetization, metrics, MVP scope) | `.agents/skills/ns-prd/SKILL.md` |
| `architecture` | `.agents/plan/PRD.md` → `.agents/plan/ARCHITECTURE.md` mapped onto the fixed stack (Convex schema/indexes/functions, Expo screens, Better Auth, IAP/Stripe, R2, ADRs, build order) | `.agents/skills/ns-architecture/SKILL.md` |
| `tasks` | PRD + ARCHITECTURE → `.agents/plan/tasks/*.md` + README — autonomous 1–3h vertical slices with verification commands | `.agents/skills/ns-tasks/SKILL.md` |

### `ios` namespace

| Subcommand | What it does | Follow this file |
| --- | --- | --- |
| `ios local-setup` (alias `setup-ios`) | Set up the **local** iOS dev env (Xcode license/CLT/first-launch, Simulator runtime, CocoaPods, Watchman, deps) and run the first `npm run ios` in the Simulator. macOS only. NOT the TestFlight signing setup — that's `ios setup` | `.agents/skills/ns-ios-setup/SKILL.md` |
| `ios setup` | EAS project init + Convex prod wiring + Apple signing credentials (everything BEFORE the first build) | `.agents/skills/ns-ios-testflight/SKILL.md` phases A-D only — stop before the build and report readiness |
| `ios audit` | Read-only App Store Review Guideline audit before submission (IAP/Restore, in-app account deletion, Sign in with Apple parity, permission strings, privacy/AI disclosure, export compliance) → triaged blockers/warnings/manual-gates report | `.agents/skills/ns-ios-audit/SKILL.md` |
| `ios testflight` | OS-aware production build + TestFlight upload: macOS defaults to local `eas build --local`; Windows/Linux must run `ns-setup-expo` then use EAS cloud | `.agents/skills/ns-ios-testflight/SKILL.md` end to end |
| `ios distribute` | TestFlight build → screenshots, metadata, IAP, compliance, review submission | `.agents/skills/ns-ios-distribute/SKILL.md` |
| `ios verification` (alias `verify`) | Verify a `mobile-app/**` change in the Simulator via `xcrun simctl` — single-agent (one Metro on 8081) or parallel multi-agent (dedicated Simulator + Metro port per agent), deep-link nav, temp preview route, programmatic OTP test login (`appstoretest@email.com` / `123456`) | `.agents/skills/ns-ios-verification/SKILL.md` |
| `ios preview` | Open the current iOS Simulator as a live local browser mirror through `serve-sim` | `.agents/skills/ns-preview/SKILL.md` |
| `ios deeplink` (alias `deeplink`, `universal-links`) | Fix and verify iOS Universal Links, TestFlight deeplinks, AASA, associated domains, and auth return flows | `.agents/skills/ns-ios-deeplink/SKILL.md` |
| `ios notification` (alias `notifications`, `push`) | Set up iOS/APNs-oriented Expo push notifications and verify delivery with EAS/TestFlight constraints | `.agents/skills/ns-ios-notification/SKILL.md` |

`testflight` alone = `ios testflight` (`ns-ios-testflight`). `distribute` alone = `ios distribute` (`ns-ios-distribute`). `audit` alone = `ios audit` (`ns-ios-audit`) — run it before `distribute` to clear predictable App Store rejections. `preview` alone = `ios preview` (`ns-preview`). For asc-level store details: `.agents/skills/ns-ios-deploy-app/SKILL.md`.

> **`ios setup` (signing) vs `ios local-setup` (local dev) — don't confuse them.** `ios setup` wires EAS project metadata, production Convex URLs, and Apple **signing** credentials for TestFlight. `ios testflight` chooses the build path from the OS: local on macOS, EAS cloud on Windows/Linux after `ns-setup-expo`. `ios local-setup` sets up Xcode, Simulator, and CocoaPods so `npm run ios` previews the dev build on this Mac. `setup-ios` remains a legacy alias.

### `android` namespace

Mirrors iOS: `setup` is local development, `beta` is the testing-track (TestFlight-equivalent) surface, `distribute` is the production release.

| Subcommand | What it does | Follow this file |
| --- | --- | --- |
| `android setup` | Android Studio + SDK + latest practical Pixel emulator + local Expo Android development build | `.agents/skills/ns-setup-android/SKILL.md` |
| `android beta` | OS-aware signed AAB + Play **internal** track upload: macOS can build locally; Windows/Linux must run `ns-setup-expo` then use EAS cloud | `.agents/skills/ns-android-beta/SKILL.md` |
| `android play-console-release` | Finish Play Console setup and internal-track upload when `gpc` hits rejected-update or commit timing bugs | `.agents/skills/ns-android-play-console-release/SKILL.md` |
| `android distribute` | Promote the tested internal build to **production** → listing, Data safety, content rating, staged rollout | `.agents/skills/ns-android-distribute/SKILL.md` (deep gpc details: `.agents/skills/ns-deploy-android-app/SKILL.md`) |

### `web` namespace

| Subcommand | What it does | Follow this file |
| --- | --- | --- |
| `web landing-page` (aliases `web landing`, `landing-page`) | Refresh the public landing page style using live reference screenshots, user keep/change direction, and web screenshot verification | `.agents/skills/ns-web-landing-page/SKILL.md` |
| `web deploy` | Deploy the web app to Vercel with Convex shipped alongside (deploy key + env wiring) | `.agents/skills/ns-web-deploy/SKILL.md` |

Unknown subcommand → show these tables, then run Lifecycle Status.

## Natural-Language Mode

When the user states a goal ("/ns deploy the web app and the iOS app", "get my app reviewed"), do this — properly, end to end:

1. **Diagnose**: run the Lifecycle Status checks to learn what is already done (config? Convex prod? EAS project? credentials? build on TestFlight? listing state?).
2. **Plan**: map the goal to an ordered chain of subcommands, skipping what's done. Dependencies are strict:
   - `check` clean → before anything that ships.
   - `web deploy` → before `ios distribute` / `android distribute` (privacy/terms URLs must be live for review).
   - `ios setup` → `ios testflight` → `ios audit` (clear blockers) → `ios distribute`, in that order.
   - `android beta` → `android distribute`, in that order (beta build verified before promoting to production).
   - `release` is the version-cut layer: it runs AFTER a build is on TestFlight + Play internal, and chains into `ios distribute` / `android distribute` with a version bump + changelog. Use it for "ship the latest TestFlight version".
   - Example for "deploy web + iOS": `check` → `web deploy` → `ios setup` → `ios testflight` → `ios distribute` (screenshots + metadata + review included).
   - Example for "release the update everywhere": `release` (bump + changelog) → `ios distribute` + `android distribute`.
3. **Confirm once**: show the plan with what each step will mutate (Vercel deploy, local signed iOS build, EAS build credits only when `--expo` is used, App Store uploads, review submission). Get ONE explicit user confirmation for the externally-visible steps, then execute the chain without re-asking between steps — but ALWAYS stop and ask before the final review submission.
4. **Execute**: follow each target file in order. If a step fails, stop, report precisely where the chain stands and what remains, fix or ask.
5. **Report**: per step — done/skipped(already)/failed, plus the final state (URLs, build number, TestFlight group, listing status) and any remaining manual gates (e.g. App Privacy questionnaire is web-only).

## Dev (`/ns dev`)

```bash
npm run start-all          # Convex + web + mobile, one terminal
# or separately: npx convex dev (root) + cd mobile-app && npm run ios
```

- Payments/Apple Sign In need a development build (`npm run ios`), not Expo Go.
- Second Expo app running? Use `npx expo start --port 8082`.
- Anything broken → `docs/troubleshooting.md`.

## Lifecycle Status (`/ns status`)

Run these checks IN ORDER; the first one that fails is where the user is. Report the stage, what's done, and the exact next command.

```bash
node scripts/check-setup.mjs --accounts      # parse service|status lines: any todo?
node scripts/check-setup.mjs --skip-convex   # parse: errors vs warnings
grep -m1 'title:' site-config.ts             # still "NowStack" -> setup not done
grep -m1 'easProjectId:' site-config.ts      # placeholder -> pre-TestFlight
```

| Stage | Signal | Next step |
| --- | --- | --- |
| 0. Fresh clone | repo still points at `Melvynx/nowstack-mobile`, nothing set up | `/ns onboard` (runs the whole first-run wizard) |
| 0a. No CLIs | required CLIs missing (`command -v eas/vercel/asc` fail) | `/ns doctor` |
| 0b. No accounts | `check-setup --accounts` reports required `todo` (Convex not logged in) | `/ns accounts` |
| 1. Not initialized | `site-config.ts` title is still "NowStack" / placeholder URLs | `/ns setup` |
| 2. Config incomplete | `check-setup` reports errors (.env, Convex env vars) | `/ns check` |
| 3. Local dev | config clean, no EAS project (`easProjectId` placeholder) | build the product, then `/ns ios setup` |
| 4. Beta-ready | EAS project/signing exists; check TestFlight with `asc status --app <id> --output table` or local/cloud build history with `cd mobile-app && npx eas-cli@latest build:list --limit 1 --json --non-interactive` | `/ns ios testflight` (iOS) / `/ns android beta` (Android) |
| 5. Store submission | build on TestFlight / Play internal; check listing: `asc status --app <id> --output table` (needs `ASC_*`; skip if unavailable) | `/ns ios distribute` + `/ns android distribute` |
| 6. Live | version released | `/ns release` to cut the next version (bump + changelog + promote), `/ns web deploy` for web, `/ns screenshots` to refresh listings |

Keep the status report short: current stage, 2-3 bullet facts, one recommended next command.

## Rules

- Read the matching `.agents/rules/*.md` before acting (the target workflows list them).
- Store mutations (builds, uploads, submissions) always require explicit user confirmation — in Natural-Language Mode, the single upfront plan confirmation covers the chain EXCEPT the final review submission, which always gets its own confirmation.
- Convex backend work is NOT part of this CLI — route backend tasks to `.agents/skills/ns-convex/SKILL.md` as usual.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall