@coralai/sps-cli 0.42.0 → 0.44.0

package/skills/mobile/references/performance.md

@@ -0,0 +1,152 @@
+# Mobile — Performance
+
+Startup, frame rate, memory, battery, app size.
+
+## Measure first
+
+- **iOS**: Xcode Instruments — Time Profiler, Allocations, Energy Log, App Launch template.
+- **Android**: Android Studio Profiler, Macrobenchmark, Perfetto, Battery Historian.
+- **Cross-platform**: framework-specific profilers (React Native Flipper, Flutter DevTools).
+
+No optimization without a profile. Anecdotes lie; flame graphs don't.
+
+## Startup
+
+Cold start = process launch → first meaningful screen. Budget:
+- iOS: < 400 ms to first frame (Apple's guideline).
+- Android: < 5 s for cold start acceptable; < 2 s is good.
+
+Common startup killers:
+- Synchronous work in `Application` / `AppDelegate` init (SDK init, network pings).
+- Excessive DI graph construction at cold start.
+- Loading a huge JSON on the main thread.
+- First screen fetching data sequentially.
+
+Strategy:
+1. **Do nothing on launch** that isn't required to render the first screen.
+2. **Defer SDK init** (analytics, crash reporter) using platform idle callbacks.
+3. **Show a real UI fast** — skeleton, cached content, progressive hydration.
+4. **Parallelize first-screen data fetches.**
+
+## Frame rate — 60 fps / 120 fps
+
+16.67 ms per frame at 60 Hz; 8.33 ms at 120 Hz. A frame budget missed = visible jank.
+
+- **Never block the UI thread** with disk, network, JSON parsing, or big computations.
+- **Measure jank** with the platform tool (Choreographer on Android, Core Animation FPS on iOS).
+- **Move work off-main**:
+  - Android: coroutines on `Dispatchers.Default` / `IO`; Compose's `LaunchedEffect`.
+  - iOS: `Task.detached(priority: .utility)` / async functions.
+  - Cross-platform: web workers, Dart isolates.
+
+## Lists — virtualize
+
+Any list with > ~50 items should virtualize (render only what's visible).
+
+- **iOS**: `UITableView` / `UICollectionView` already do; `LazyVStack` in SwiftUI; avoid mapping huge arrays into `ForEach` inside `ScrollView`.
+- **Android**: `RecyclerView` / `LazyColumn` (Compose). Set `contentType` / `key` for recycling.
+- **React Native**: `FlatList` / `SectionList` with `keyExtractor` and `getItemLayout`.
+- **Flutter**: `ListView.builder` / `SliverList`.
+
+Rules:
+- Every row has a stable key.
+- `shouldRecompose` / `areItemsTheSame` return correctly.
+- Avoid inline lambdas that change identity every render.
+
+## Images
+
+Biggest single memory user in typical apps.
+
+- Use a cached image loader (Coil, Glide, SDWebImage, Kingfisher, FastImage for RN).
+- Decode to the display size, not the source size. A 4000 × 3000 photo in a 300-pt avatar is a memory bomb.
+- Cache policies: memory (tight), disk (generous, bounded), TTL for dynamic URLs.
+- Placeholders + fade-in; avoid layout shift.
+
+## Memory
+
+- Hold what you're rendering. Let the rest evict.
+- Bitmap-heavy screens (photo grids, video thumbnails) need aggressive recycling.
+- Watch for retain cycles (iOS) / context leaks (Android). A ViewModel holding a View, a Handler with an activity reference — standard leaks.
+- Detekt / leak-detection tools: LeakCanary (Android), Instruments Leaks (iOS), profile before release.
+
+## Battery
+
+Users notice battery drain. What costs most:
+- **Network chatter** (small requests often > big requests rarely).
+- **Wakeups** (alarms, background fetches, location).
+- **Sensors** (GPS, accelerometer, BT scan) when used continuously.
+- **Bad CPU loops** (unnecessary re-renders, background polling).
+
+Rules:
+- Batch network calls where you can.
+- Use platform background scheduler (`WorkManager`, `BGTaskScheduler`) — they batch across apps.
+- Respect Doze / Low Power Mode signals.
+- Don't hold wake locks or background location without a visible reason.
+
+## App size
+
+Each MB costs downloads, installs, abandonment. Rough targets:
+- < 50 MB initial download is great.
+- Over 100 MB, users on cellular are warned.
+
+Tools:
+- Android App Bundle splits by ABI / language / density.
+- iOS: App Thinning, on-demand resources.
+- Strip debug symbols in release.
+- Audit deps — one chart library can add 5 MB of unused code.
+
+## Package size audit
+
+Largest offenders, in order:
+1. Unstripped native libraries (x86 + arm + arm64 + armv7).
+2. Bundled fonts / images / videos.
+3. Heavy SDKs (ads, analytics) that ship more than they use.
+4. Translations (if your app ships without user-language stripping).
+5. Debug info left in release.
+
+## Launch / anim / transition perf
+
+- Launch screen: show the UI immediately (Asset catalog on iOS, splash theme on Android). Don't build your own splash from a UIKit / Activity — it's slower.
+- Transitions: use platform defaults; they're hardware-accelerated. Custom animations often miss frames on low-end devices.
+- Prefer `transform` / `opacity` equivalents over layout-triggering properties.
+
+## Network
+
+- HTTP/2 or HTTP/3 → multiplexing reduces handshake cost.
+- Response compression (gzip / brotli) on.
+- Cache-Control on static assets; ETag for dynamic.
+- Retry with backoff on failures.
+- Consider **delta** payloads for large lists (send only what changed).
+
+## Ahead-of-time vs JIT
+
+- Android R8 / ProGuard: enable in release. Strips unused code and shrinks bundles.
+- iOS: always AOT; no JIT. Focus on link-time optimization (`-Os`, whole-module).
+- Cross-platform: Hermes (RN), Flutter AOT — verify you're in release mode.
+
+## Benchmarks in CI
+
+Macrobenchmark (Android) or Instruments via XCTest (iOS) can run critical-flow timing on every merge. Fail builds on regression beyond threshold.
+
+```
+@Test
+fun startup() = benchmarkRule.measureRepeated(
+    packageName = PACKAGE,
+    metrics = listOf(StartupTimingMetric()),
+) { pressHome(); startActivityAndWait() }
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Loading full profile on every screen | Cache; invalidate on change |
+| Images served at 4K for 400 px displays | Server-side resizing or loader |
+| Launch SDK initialization chain takes 2 seconds | Defer; init on first use |
+| Rendering a grid without virtualization | Use the platform list |
+| Polling for notifications every 10 seconds | Push / long-poll |
+| JSON parse on main thread for big payloads | Background + stream |
+| Keeping full Log / PDF in memory | Stream; flush |
+| Shipping debug logs in release | Strip |
+| Background location for features that don't need it | Request only when needed |
+| Running animations during heavy scroll | Throttle or pause |

package/skills/mobile/references/platform.md

@@ -0,0 +1,166 @@
+# Mobile — Platform
+
+Permissions, notifications, background tasks, biometrics, secure storage.
+
+## Permissions
+
+Request at the moment of need, not upfront.
+
+```
+User taps "Add photo" → now request camera / library permission.
+```
+
+Flow:
+1. Check current status.
+2. If not determined: show an in-app primer ("to attach photos we need access to…"), then prompt.
+3. If denied: show clear "open Settings" guidance; don't re-prompt (iOS won't show the sheet again anyway).
+
+Never:
+- Ask for all permissions on first launch.
+- Block the app on denied permissions (degrade gracefully).
+- Auto-grant — users must choose.
+
+Required: `NSUsageDescription` (iOS) / permission declarations (Android) with accurate copy. App stores reject vague ones.
+
+## Sensitive permissions
+
+| Permission | Treat as |
+|---|---|
+| Location (especially background) | Justify prominently, explain precisely how it's used |
+| Camera / microphone | Visible indicator while active (OS usually does this) |
+| Contacts / Photos / Calendar | Scoped access preferred (iOS 14+, Android 13+) |
+| Notifications (iOS) | Explicit opt-in; user deciding = one chance on iOS |
+| Accessibility services (Android) | High review bar; stores scrutinize |
+
+## Notifications
+
+### Local
+
+For time / event reminders the device can schedule.
+
+```
+schedule(id, triggerDate, contentTitle, contentBody)
+```
+
+Rules:
+- Idempotent id — rescheduling replaces.
+- Cancel stale notifications on state change (task done → remove reminder).
+- Respect quiet hours / Focus / DND.
+
+### Push
+
+Server-driven. Flow:
+1. App requests token (APNs on iOS, FCM on Android).
+2. Token sent to server, associated with user.
+3. Server delivers payloads via APNs / FCM.
+
+Content types:
+- **Alert / default** — visible to user.
+- **Silent / data-only** — wakes app to sync; no UI. Limited budget; iOS throttles.
+
+Handle:
+- Token rotation (OS may refresh; always sync to server).
+- Logout: unregister token.
+- Quiet / opt-out preferences server-side.
+
+## Background tasks
+
+Apps don't run in the background forever. Platforms give scheduled, constrained windows.
+
+- **iOS**: `BGAppRefreshTask`, `BGProcessingTask` via `BGTaskScheduler`. Short windows, system-decided.
+- **Android**: `WorkManager` — one API, handles Doze / idle batching. Avoid `AlarmManager` for modern apps.
+- **Cross-platform**: framework wrappers around the above.
+
+Rules:
+- Keep work short and idempotent.
+- Don't assume a window will run at a specific time.
+- Don't rely on background work for correctness — network may be off.
+
+## Biometrics
+
+```
+if canAuth(.biometrics):
+    await authenticate(reason: "Unlock your vault")
+else:
+    await authenticate(.passcode)    // fallback
+```
+
+- iOS: `LocalAuthentication` / `LAContext`.
+- Android: `BiometricPrompt`.
+
+Never store actual biometric data. Use it to gate access to a key in Keychain / Keystore.
+
+## Secure storage
+
+| Need | Store |
+|---|---|
+| API tokens, refresh tokens | Keychain (iOS) / EncryptedSharedPreferences / DataStore with a master key (Android) |
+| Encryption keys | Keychain / Keystore, hardware-backed where available |
+| User preferences (non-sensitive) | UserDefaults / DataStore |
+| Caches | App sandbox directory; wipe on logout |
+
+Never:
+- Tokens in `UserDefaults` / `SharedPreferences`.
+- Plain-text credentials anywhere.
+- Logging full tokens (even at DEBUG).
+
+## Network security
+
+- HTTPS with modern TLS (1.2 minimum, 1.3 preferred).
+- **ATS** on iOS — use default settings; exceptions require justification.
+- **Network Security Config** on Android — restrict cleartext.
+- **Certificate pinning** for high-value endpoints. Pin the intermediate or leaf; plan the rotation.
+
+## App Transport / Deep Link security
+
+- Validate deep-link parameters; treat them as user input.
+- Never execute code based on query string (e.g., "open this URL in WebView" without allow-list).
+- For login-via-deep-link, verify signature; intermediaries may tamper.
+
+## Web views
+
+Minimize them. When unavoidable:
+- Use `WKWebView` (iOS) / `WebView` with hardened settings (Android).
+- Disable `allowFileAccess`, `javascriptEnabled` unless required.
+- Never inject tokens into URLs loaded in web views.
+
+For OAuth / in-app browser tabs (SFSafariViewController / Chrome Custom Tabs) — safer than a generic WebView because cookies and saved passwords work.
+
+## Hardware surveys
+
+When using camera / sensors / Bluetooth:
+- Check availability (`AVCaptureDevice`, hardware feature on Android).
+- Fail gracefully on missing hardware.
+- Release resources on background / pause.
+- Don't leave LEDs on or Bluetooth scanning when the feature is closed.
+
+## Accessibility at the platform level
+
+- iOS: VoiceOver, Dynamic Type, Reduce Motion, Bold Text, Smart Invert.
+- Android: TalkBack, font scale, color correction, reduce animations.
+
+Use the platform's semantic accessibility APIs, not custom text-to-speech.
+
+Test at 200% font scale. Layout should expand gracefully, not truncate.
+
+## Crash reporting
+
+- Firebase Crashlytics, Sentry, BugSnag, custom — pick one.
+- Capture: stack trace, device, OS version, app version, user id (hashed or opt-in).
+- Log breadcrumbs — screen views, key user actions — to reconstruct what happened.
+- De-symbolicate iOS crashes with dSYMs uploaded in CI. Android: ProGuard mapping files.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Requesting all permissions upfront | Ask at point of need |
+| Tokens in UserDefaults / SharedPreferences | Keychain / Keystore |
+| Background location without clear benefit | Foreground only |
+| Polling in the background for "real-time" | Push notifications / WebSockets (when foreground) |
+| Running as foreground service to bypass Doze | Violates Play Store policy |
+| Opening external URLs in an in-app WebView with cookies | Use in-app browser tab |
+| Using the older / deprecated `AlarmManager` for everything | WorkManager on modern Android |
+| Stripping ATS / NSC to "make it easier" | Fix the server; don't open cleartext in prod |
+| Hard-coded production API keys | Environment-specific config; rotate on leak |
+| Silent push used for analytics (abuses the privilege) | Real notification or in-app event |

package/skills/mobile/references/state-and-data.md

@@ -0,0 +1,174 @@
+# Mobile — State & Data
+
+Local store, sync, offline-first, optimistic updates, reactive streams.
+
+## Offline-first
+
+Network is the slow, unreliable layer. Design the app so the local store is the fast path; the network syncs in the background.
+
+```
+UI ──reads──▶ Local Store ◀──writes sync── API
+      ──writes──▶ Local Store + Outbox ──drain──▶ API
+```
+
+Benefits:
+- Cold start without network → user still sees cached content.
+- Actions feel instant (optimistic + outbox).
+- Seamless reconnection; app doesn't die on Wi-Fi flip.
+
+## Local storage choices
+
+| Store | Platform / Cross | Shape |
+|---|---|---|
+| SQLite (direct) | All | Relational, battle-tested |
+| Room | Android | SQLite ORM; compile-time query checking |
+| Core Data / SwiftData | iOS | Object graph |
+| Realm | Cross | Object DB, live objects |
+| SQLDelight | KMP / cross | SQL-first, multiplatform |
+| MMKV / DataStore | Key-value | Simple prefs, fast, typed |
+| Keychain / Keystore | All | Secrets |
+
+Rule: one primary store per domain. Mixing Room + Realm + a JSON cache for the same data creates reconciliation hell.
+
+## Cache + network reconcile
+
+### Stale-while-revalidate
+
+Return cached data immediately; refresh in the background.
+
+```
+suspend fun getUser(id: String): Flow<User> = flow {
+    emit(cache.get(id))                       // instant
+    try {
+        val fresh = api.getUser(id)
+        cache.put(id, fresh)
+        emit(fresh)                            // update UI
+    } catch (_: IOException) {
+        // offline; keep showing cached
+    }
+}
+```
+
+### Freshness policy
+
+Some data is OK to show even if hours old (product catalog); some must be current (bank balance). Per-type policy:
+
+```
+policy[User]        = staleAfter(5.minutes)
+policy[ProductList] = staleAfter(24.hours)
+policy[Balance]     = alwaysRefresh
+```
+
+## Optimistic updates + outbox
+
+For user-driven writes, show the expected result immediately; queue the server call; reconcile.
+
+```
+place_order(order):
+    local.insert(order.copy(status=PENDING))
+    outbox.enqueue(PostOrder(order.id))
+    return order.id                             # UI navigates away instantly
+```
+
+The outbox worker:
+1. Reads next job.
+2. Calls the server (with retry + backoff).
+3. On success: update local row (`status=CONFIRMED`), remove job.
+4. On permanent failure: mark local row (`status=FAILED`), notify user, drop job.
+
+Conflict strategy when the server returns a different truth (e.g., order replaced due to out-of-stock): domain decides — replace, merge, prompt user.
+
+## Queue vs. sync protocol
+
+Simple apps: an outbox table with next-id, retry count, last-error. Good enough.
+
+Complex sync (collaborative editing, multi-device): use a sync framework (CRDTs, Yjs, Automerge, Firebase, CouchDB). Implementing one by hand is a trap.
+
+## Reactive streams everywhere
+
+Mobile UIs love reactivity because the underlying data changes often.
+
+| Tech | Stream type |
+|---|---|
+| Kotlin | `Flow`, `StateFlow`, `SharedFlow` |
+| Swift (Apple) | `Publisher` (Combine), `AsyncStream`, `Observable` |
+| RxJava / RxSwift | `Observable`, `Flowable` |
+| React Native | Hooks + state libs |
+
+Your repository exposes a stream. The ViewModel transforms. The view collects.
+
+```
+// Kotlin
+val user: StateFlow<User?> = userRepo.observe(id)
+    .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+```
+
+`WhileSubscribed(5_000)`: keeps the upstream alive 5s after the last subscriber — survives rotation without a cold re-fetch.
+
+## Pagination
+
+Two patterns:
+
+### Offset / page
+
+Simple but breaks when rows are inserted during paging. OK for static lists.
+
+### Cursor / keyset
+
+Opaque cursor that points to the last-seen item. Stable across inserts.
+
+```
+interface OrderApi {
+    suspend fun list(cursor: String?, limit: Int): Page<Order>
+}
+
+data class Page<T>(val data: List<T>, val nextCursor: String?)
+```
+
+Platform paging libs (Jetpack Paging, TCA Pagination) handle prefetch, retry, error states. Use them; rolling your own is a maintenance burden.
+
+## Forms & input
+
+- **Draft persistence**: save form input to local store keyed by form id. Survive process death.
+- **Validation**: same schema on client and server (share via contract or mirror carefully).
+- **Submit**: optimistic + outbox if idempotent; otherwise show submitting state.
+
+## Images
+
+The single biggest memory user and jank source in mobile.
+
+- Use the platform image loader (Coil / Glide on Android, SDWebImage / Kingfisher on iOS).
+- Resize to the display size **on the server** (API returns `url?w=400`) or via the loader.
+- Cache aggressively; size the cache (e.g. 100 MB disk, 50 MB memory).
+- Placeholders + cross-fade; never show a flash of broken image.
+
+## Real-time updates
+
+- **Polling**: simple, works offline, battery-expensive. OK for low-urgency data.
+- **WebSockets / SSE**: real-time, drains battery if poorly scoped. Tear down in background.
+- **Push notifications**: for out-of-app updates. Use silent push to wake and sync.
+
+Rule: subscribe only when the user is looking. Unsubscribe on background / detached views.
+
+## Data security
+
+See `security.md` for the big picture. Quick must-dos:
+
+- Tokens / secrets → Keychain (iOS) or EncryptedSharedPreferences / Keystore (Android).
+- Never log full tokens.
+- HTTPS only. Pin certificates for critical endpoints where your threat model warrants.
+- Wipe sensitive caches on logout.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Fetching on every screen entry | Cache + observe; fetch only when stale |
+| Syncing all data up-front on login | Lazy load; fetch on demand |
+| Outbox without retry / backoff | Loop; drain with exponential backoff |
+| Showing "please wait, syncing…" for every write | Optimistic + outbox |
+| Global mutable store for server data | Repository + reactive stream |
+| Ignoring background / killed state | Persist enough state to resume |
+| Unbounded memory caches | Set a size cap with LRU eviction |
+| Network-only fallback for offline | Degrade: cached data + "offline" banner |
+| Duplicate local schemas (Room + SwiftData with different shapes on same domain) | One domain model; platform stores map to it |

package/skills/python/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: python
+description: Python language skill — idioms, type hints, error handling, testing, async, packaging. Language-focused. Combine with end skills (`backend`, `frontend`, `mobile`) for architecture, and with persona skills (`backend-architect`, `code-reviewer`) for mindset.
+origin: ecc-fork (https://github.com/affaan-m/everything-claude-code, MIT)
+---
+
+# Python
+
+Pythonic idioms, typing, error handling, async, testing, packaging. **Language-focused only**. Architecture decisions belong to end skills (`backend`, `frontend`, `mobile`); general principles (TDD cycle, "specific exceptions only", "tests before code") live in `coding-standards`.
+
+## When to load
+
+- Task is a Python project (primary language)
+- Reviewing Python code
+- Setting up Python project structure, packaging, or tests
+- Writing Python-specific logic (generators, decorators, context managers, type hints, async)
+
+## Core principles (The Zen of Python, abridged)
+
+1. **Readability counts** — clear > clever
+2. **Explicit over implicit** — no hidden side effects
+3. **EAFP** (Easier to Ask Forgiveness Than Permission) — prefer `try/except` over pre-checks
+4. **Type hints on public APIs** — modern 3.9+ syntax (`list[str]` not `List[str]`); 3.12+ PEP 695 where available
+5. **Immutable defaults** — never `def f(x=[])`; use `None` + `x or []` or `frozenset` / `tuple`
+6. **Pathlib over os.path** — modern filesystem access
+7. **f-strings** over `.format()` / `%` formatting
+8. **`pyproject.toml` only** — no `setup.py`, no `requirements.txt` for libraries
+
+## How to use references
+
+Load detailed references on demand based on the task:
+
+| Reference | When to load |
+|---|---|
+| [`references/idioms.md`](references/idioms.md) | Core language idioms: EAFP, comprehensions, generators, decorators, context managers, match/case, walrus |
+| [`references/typing.md`](references/typing.md) | Type hints, generics (PEP 695), protocols, type aliases, `Self`, `@override`, `ParamSpec` |
+| [`references/error-handling.md`](references/error-handling.md) | Exception hierarchy, chaining, custom exceptions, exception groups / `except*` |
+| [`references/async.md`](references/async.md) | `asyncio`, `TaskGroup`, timeouts, cancellation, offloading blocking code |
+| [`references/testing.md`](references/testing.md) | pytest, fixtures, parametrization, mocking, coverage, `hypothesis` |
+| [`references/packaging.md`](references/packaging.md) | `pyproject.toml`, `uv`, `venv`, project layout, publishing |
+
+## Forbidden patterns (auto-reject)
+
+- Mutable default arguments (`def f(x=[])`) — use `None` sentinel
+- `except:` without exception type — always name it
+- `import *` — explicit imports only
+- `time.sleep()` / blocking calls inside `async def` — use `await asyncio.sleep()` or `asyncio.to_thread`
+- Swallowing `asyncio.CancelledError` without re-raising
+- `setup.py` in new projects — use `pyproject.toml`
+- Committing `.venv/` or mixing envs with system Python
+- Dynamic typing in public APIs without type hints

package/skills/python/THIRD_PARTY.md

@@ -0,0 +1,14 @@
+# Third-Party Attribution
+
+This skill integrates content from:
+
+## everything-claude-code (Affaan Mustafa)
+
+- URL: https://github.com/affaan-m/everything-claude-code
+- License: MIT
+- Files used:
+  - `skills/python-patterns/SKILL.md` → split into `references/idioms.md`, `references/typing.md`, `references/error-handling.md`
+  - `skills/python-testing/SKILL.md` → `references/testing.md`
+- Adaptation: content restructured into multiple reference files (thin SKILL.md entry + topic-specific references), some sections condensed, Pythonic/language-neutral line drawn (language-specific content stays here, architecture moves to `backend` / `frontend` skills).
+
+The MIT license notice is preserved in [LICENSE-MIT-everything-claude-code](https://github.com/affaan-m/everything-claude-code/blob/main/LICENSE).