agy-superpowers 5.0.7 → 5.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.0.7",
+  "version": "5.0.8",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/skills/api-design/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: api-design
+description: Use when designing REST or GraphQL APIs, defining versioning strategy, implementing rate limiting, pagination, or writing API documentation
+---
+
+# API Design Lens
+
+> **Philosophy:** An API is a contract. Breaking it breaks your users' production systems.
+> Design APIs for the client's needs, not the server's convenience.
+
+---
+
+## Core Instincts
+
+- **API contracts are forever** — breaking changes in v1 are unforgivable; version aggressively
+- **Design for the consumer** — the client's workflow, not the server's data model, drives resource design
+- **Idempotency is non-negotiable** — safe to retry = safe to build reliable systems on top of
+- **Errors must be informative** — vague errors waste developer hours
+- **Consistency over cleverness** — a boring, predictable API is a beloved API
+
+---
+
+## REST Resource Design Rules
+
+```
+Resource naming:
+  ✅ /users/{id}/projects          (noun, plural, hierarchical)
+  ❌ /getProjectsForUser/{id}      (verb, confusing)
+  ❌ /user-projects/{userId}       (mixed conventions)
+
+HTTP verbs:
+  GET    /resources        → list (paginated)
+  GET    /resources/{id}   → get one
+  POST   /resources        → create
+  PUT    /resources/{id}   → full replace (idempotent)
+  PATCH  /resources/{id}   → partial update
+  DELETE /resources/{id}   → delete (idempotent)
+
+Idempotency:
+  GET, PUT, DELETE = always idempotent
+  POST = not idempotent by default → use Idempotency-Key header
+```
+
+---
+
+## HTTP Status Codes (Precise Usage)
+
+| Status | Use when | Body |
+|--------|----------|------|
+| 200 | Success, returns data | Resource |
+| 201 | Created | Resource + `Location` header |
+| 204 | Success, no body | Empty |
+| 400 | Malformed request / validation failure | Error with field details |
+| 401 | Missing or invalid auth | Error |
+| 403 | Auth valid, no permission | Error (don't reveal resource existence) |
+| 404 | Resource not found | Error |
+| 409 | Conflict (duplicate, state clash) | Error with conflict detail |
+| 422 | Valid format, business rule violation | Error with reason |
+| 429 | Rate limited | Error + `Retry-After` header |
+| 500 | Unexpected server error | Generic error (log full details server-side) |
+
+---
+
+## Error Response Standard (RFC 7807 / Problem Details)
+
+```json
+{
+  "type": "https://docs.myapp.com/errors/validation-failed",
+  "title": "Validation Failed",
+  "status": 422,
+  "detail": "One or more fields are invalid",
+  "errors": [
+    { "field": "email", "message": "Must be a valid email address" },
+    { "field": "name",  "message": "Required" }
+  ],
+  "requestId": "01HX7Y3Z..."
+}
+```
+
+**Always include `requestId`** — allows support to find logs immediately.
+
+---
+
+## Pagination
+
+```
+Offset-based (simple, less scalable):
+  GET /users?page=2&limit=20
+  ✅ Good for: admin UIs, small datasets
+  ❌ Bad for: large datasets (OFFSET N scans N rows)
+
+Cursor-based (scalable, real-time safe):
+  GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
+  Response: { data: [...], nextCursor: "eyJpZCI6MTQzfQ", hasMore: true }
+  ✅ Good for: feeds, large datasets, infinite scroll
+  ❌ Bad for: jump-to-page UI
+
+Default recommendation: Cursor-based with opaque base64 cursors.
+Expose total count only when necessary (expensive for large tables).
+```
+
+---
+
+## Rate Limiting
+
+```
+Strategy: Token bucket or sliding window
+
+Headers to include:
+  X-RateLimit-Limit:     1000    (max requests per window)
+  X-RateLimit-Remaining: 847     (requests left)
+  X-RateLimit-Reset:     1711234567  (Unix timestamp when window resets)
+  Retry-After:           60      (seconds to wait, on 429 only)
+
+Recommended limits for SaaS APIs:
+  Authenticated:   1000 req/min per user
+  Unauthenticated: 60 req/min per IP
+  Sensitive (auth endpoints): 5 req/15min per IP
+```
+
+---
+
+## API Versioning
+
+```
+Strategy options:
+  URL versioning:    /v1/users   ← RECOMMENDED (explicit, cacheable)
+  Header versioning: Accept: application/vnd.myapp.v1+json  (less visible)
+  Query param:       /users?version=1  (ugly, cache issues)
+
+Breaking vs non-breaking changes:
+  Non-breaking (safe without versioning):
+    ✅ Adding new optional fields to response
+    ✅ Adding new optional request parameters
+    ✅ Adding new endpoints
+  
+  Breaking (requires new version):
+    ❌ Removing fields from response
+    ❌ Changing field types
+    ❌ Changing endpoint behavior
+    ❌ Renaming fields
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Return 200 for errors | Clients parse status codes; 200 failure = broken integrations | Use correct status codes |
+| Expose internal IDs (auto-increment integers) | Enumerable, leaks count of records | UUIDs always |
+| Breaking changes without versioning | Clients' production breaks silently | `/v2/` or deprecation period |
+| Unbounded list endpoints | OOM at scale | Always paginate; default limit 20, max 100 |
+| Verbose errors in production | Leaks internals to attackers | Generic message to client; details in server logs only |
+| Synchronous long-running operations | Timeout at 30s+, bad UX | Accept → 202 Accepted → polling or webhook |
+
+---
+
+## Questions You Always Ask
+
+**When designing a new endpoint:**
+- Is this resource name a noun (not a verb)?
+- What's the idempotency story? Can the client safely retry?
+- What's the pagination strategy? What's the max page size?
+- Is this a breaking change to existing consumers?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] `200 OK` returned for error responses
+- [ ] No pagination on list endpoints
+- [ ] Auto-increment integer IDs exposed
+- [ ] Breaking API change without version bump
+
+**Should fix:**
+- [ ] No rate limiting on public endpoints
+- [ ] Error responses without field-level details
+- [ ] No `requestId` in error responses (prevents support lookup)
+- [ ] No OpenAPI/Swagger spec
+
+---
+
+## Who to Pair With
+- `backend-developer` — for implementation of API patterns
+- `auth-and-identity` — for auth design on API endpoints
+- `saas-architect` — for multi-tenant API context
+
+---
+
+## Tools
+OpenAPI / Swagger (spec) · Scalar / Stoplight (docs) · Hono / Fastify / Express (Node.js) · Zod / Joi (validation) · `express-rate-limit` / Upstash Rate Limit · Postman / Insomnia (testing)

package/template/agent/skills/app-store-optimizer/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: app-store-optimizer
+description: Use when working on App Store / Google Play listing optimization, keyword strategy, screenshots, ratings, or app store A/B testing
+---
+
+# App Store Optimizer Lens
+
+> **Philosophy:** ASO is SEO for app stores. Discoverability + conversion = downloads.
+> Most apps lose 60%+ of potential downloads to a weak listing, not a weak product.
+
+---
+
+## Core Instincts
+
+- **Title keyword is the highest-ranking signal** — include your primary keyword in the title
+- **First 3 screenshots convert or kill** — most users never scroll past them
+- **Ratings velocity > average rating** — a burst of fresh 5-stars beats a stale 4.8
+- **Keyword field is invisible to users but critical to ranking** — use every character
+- **Localize for top markets** — EN + your top 3 markets = 80% of opportunity
+
+---
+
+## Platform Limits (Know These Cold)
+
+### iOS App Store
+| Field | Limit | Notes |
+|-------|-------|-------|
+| Title | **30 chars** | Primary keyword weight = 2× |
+| Subtitle | **30 chars** | Secondary keyword, benefit-focused |
+| Keywords | **100 chars** | Comma-separated, no spaces, no repeats from title |
+| Description | **4000 chars** | First **255 chars** shown before "more" |
+| Promo text | **170 chars** | Updates without review; use for time-limited offers |
+| Screenshots | Up to **10** | Sizes vary by device; first 3 drive 80% of conversion |
+| Preview video | **15–30 seconds** | First 3 seconds must hook without sound |
+
+### Google Play
+| Field | Limit | Notes |
+|-------|-------|-------|
+| Title | **30 chars** | Keyword-rich |
+| Short description | **80 chars** | Shown in search; make it scannable |
+| Long description | **4000 chars** | First 167 chars auto-expanded; repeat keyword 3–5× |
+| Screenshots | Up to **8** | 16:9 or 9:16 preferred |
+| Feature graphic | **1024 × 500px** | Shown in featured slots |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Title = just the brand name | Zero keyword signal | Brand + primary keyword (e.g., "Todoist: To-Do List & Tasks") |
+| Leave keywords field blank (iOS) | 100 chars of free ranking wasted | Fill every character with non-title keywords |
+| First screenshot = app logo splash | Users bounce, no context | First screenshot = core value prop as hero text |
+| Ask for review on first open | Users hate it, Apple rejects manipulative prompts | Ask after a success action (task completed, streak hit) |
+| Ignore 1-star reviews | Review responses shown publicly; silence = neglect | Respond within 48h; apologize + explain fix |
+| Use keywords that appear in title (iOS) | Apple ignores duplicates | Every keyword field word must be unique |
+| Generic description | No differentiation, no keywords | Keyword-rich first paragraph, benefit bullets |
+
+---
+
+## Keyword Research Process
+
+1. **Seed keywords** — brainstorm 20–30 relevant terms
+2. **Competitor analysis** — check top 5 competitor titles/subtitles
+3. **Volume + difficulty** — use Sensor Tower / AppTweak / AppFollow to score
+4. **Priority matrix** — High volume + Low difficulty = target first
+5. **Long-tail focus** — easier to rank for "meditation app for anxiety" than "meditation"
+6. **Update every 60–90 days** — track rank changes, iterate
+
+---
+
+## Ratings Strategy
+
+**When to prompt:** After user completes a meaningful success action, NOT on launch.
+- Good triggers: completed task, reached streak, finished session, saved something
+- Bad triggers: app open, screen view, after onboarding
+
+**Target benchmarks:**
+| Metric | Floor | Target |
+|--------|-------|--------|
+| Average rating | > 4.0 | > 4.5 |
+| Review count (for featuring) | > 100 | > 500 |
+| Response rate to 1-star | — | > 80% within 48h |
+
+**Recovering from bad ratings:** Respond to every 1-star, release fix quickly, request updated review from resolved users.
+
+---
+
+## Questions You Always Ask
+
+**When auditing a listing:**
+- Is the primary keyword in the title?
+- Do the first 3 screenshots tell a complete story without reading any text?
+- Is the keyword field 100% utilized (iOS)?
+- What's the current conversion rate from impression to download? (Benchmark: 3–7%)
+
+**When planning ASO strategy:**
+- Which markets are we localizing for?
+- What keywords are competitors ranking for that we're missing?
+- When was the last time we A/B tested screenshots?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Title is brand name only (no keyword)
+- [ ] iOS keyword field < 90 characters used
+- [ ] First screenshot is a splash screen or abstract illustration
+- [ ] No response to 1-star reviews
+
+**Should fix:**
+- [ ] Description first 255 chars (iOS) / 167 chars (Play) not benefit-focused
+- [ ] No preview video
+- [ ] Listing not localized for top 3 markets
+
+---
+
+## Who to Pair With
+- `copywriter` — for listing copy strategy
+- `growth-hacker` — for launch burst strategy (ratings velocity)
+- `conversion-optimizer` — for screenshot A/B testing
+
+---
+
+## Tools
+AppFollow · Sensor Tower · AppTweak · AppFigures · MobileAction · Apple Search Ads Intelligence

package/template/agent/skills/auth-and-identity/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: auth-and-identity
+description: Use when implementing authentication, authorization, SSO/SAML/OIDC, multi-tenant identity, session management, or role-based access control for a SaaS product
+---
+
+# Auth & Identity Lens
+
+> **Philosophy:** Authentication proves who you are. Authorization proves what you can do.
+> Mixing them up is the most common source of privilege escalation bugs.
+
+---
+
+## Core Instincts
+
+- **AuthN ≠ AuthZ** — always handle them as separate concerns
+- **Every request must be authenticated AND authorized** — auth middleware is not authorization
+- **Tenant context must be established on every request** — after AuthN, before any DB query
+- **Fail closed** — when in doubt, deny; never default to permissive
+- **Never roll your own crypto** — use proven libraries and protocols
+
+---
+
+## Multi-Tenant Auth Flow
+
+```
+Request arrives →
+1. Verify token/session (AuthN) → get user_id
+2. Load user + tenant membership → get tenant_id, role
+3. Set tenant context (RLS / app context)
+4. Check permission for this route/resource (AuthZ)
+5. Execute request
+```
+
+**Order matters:** If you skip step 3, RLS doesn't know which tenant. If you skip step 4, any authenticated user can do anything.
+
+---
+
+## Auth Strategy Selection
+
+| Method | Best for | Not for |
+|--------|----------|---------|
+| **JWT (stateless)** | Stateless APIs, microservices | When you need instant revocation |
+| **Session cookie** | Web apps, SSR | Mobile-first or API-only |
+| **API key** | Machine-to-machine, developer APIs | User-facing login |
+| **SAML 2.0** | Enterprise SSO (Okta, Azure AD) | Consumer apps |
+| **OIDC / OAuth 2.0** | Social login, federated identity | Internal-only systems |
+
+**Indie hacker default:** Session cookies for web (HttpOnly, Secure, SameSite=Strict) + JWT for API endpoints.
+
+---
+
+## JWT Rules
+
+```
+Access token:
+- Expiry: 15 minutes (short-lived; compromised → limited damage window)
+- Payload: user_id, tenant_id, role, exp — NO sensitive data
+- Store: Memory (never localStorage) or HttpOnly cookie
+
+Refresh token:
+- Expiry: 7–30 days
+- Store: HttpOnly cookie ONLY
+- Rotate on every use (refresh token rotation)
+- Invalidate all refresh tokens on password change/logout all
+
+Signing:
+- Algorithm: RS256 (asymmetric, allows public verification) or HS256 (simpler, shared secret)
+- Secret: ≥ 32 random bytes; rotate if compromised (support multiple valid secrets during rotation)
+```
+
+---
+
+## RBAC Pattern (Role-Based Access Control)
+
+```typescript
+// Roles per tenant membership (not global)
+type TenantRole = 'owner' | 'admin' | 'member' | 'viewer';
+
+// Permissions defined as capability strings
+const PERMISSIONS = {
+  owner:  ['billing:manage', 'members:manage', 'data:delete', 'data:write', 'data:read'],
+  admin:  ['members:manage', 'data:write', 'data:read'],
+  member: ['data:write', 'data:read'],
+  viewer: ['data:read'],
+} satisfies Record<TenantRole, string[]>;
+
+// Check at every protected route/action
+function can(user: User, permission: string): boolean {
+  return PERMISSIONS[user.tenantRole]?.includes(permission) ?? false;
+}
+```
+
+---
+
+## SSO / SAML Integration (Enterprise)
+
+```
+When to build SAML:
+- Enterprise customers require it (Okta, Azure AD, Google Workspace)
+- Single "SAML" request in a deal is worth building immediately
+
+Implementation options for indie hackers:
+1. WorkOS — $0 to start, pay per enterprise connection; fastest path
+2. Auth0 / Clerk — SAML add-on; higher cost at scale
+3. Roll your own — samlify / passport-saml; significant complexity
+
+SAML Flow:
+  User → Your SP (Service Provider) → IdP (Okta/AzureAD) → SAML assertion → SP → Session
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| JWT in `localStorage` | XSS attack steals token, unlimited access | `HttpOnly` cookie |
+| Long-lived access tokens (> 1 hour) | Compromised token = long exposure window | 15 min expiry + refresh token rotation |
+| Storing passwords as anything but bcrypt/argon2id | Rainbow table crack in seconds | bcrypt cost ≥12 or argon2id |
+| Checking auth at route level only | Bypassed by internal calls | Check permissions at the service/data layer |
+| Global admin role without per-tenant scope | One compromised admin = all tenants affected | Admin role always scoped to a tenant |
+| No rate limiting on auth endpoints | Brute force, credential stuffing | Max 5 attempts / 15 min per IP |
+| Email as unique identifier across tenants | Same email in multiple tenants = collision | `(email, tenant_id)` composite unique |
+
+---
+
+## Questions You Always Ask
+
+**When designing auth:**
+- Is tenant context established before any DB query happens?
+- Does AuthZ happen at the service layer, not just route middleware?
+- Are refresh tokens rotated on every use?
+- What's the logout flow? Does it invalidate server-side session/refresh token?
+
+**When adding a new role or permission:**
+- Is this the least privilege needed for this action?
+- Have we tested that a lower-privileged role cannot access this?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] JWT stored in `localStorage`
+- [ ] No tenant_id in auth context (tenant isolation can't work)
+- [ ] Authorization only checked at route level (not service/data layer)
+- [ ] No rate limiting on `/login`, `/forgot-password`, `/reset-password`
+
+**Should fix:**
+- [ ] Refresh tokens not rotated on use
+- [ ] No MFA option for admin/owner roles
+- [ ] Email uniqueness checked globally (not per-tenant)
+
+---
+
+## Who to Pair With
+- `saas-architect` — for tenant context in data model
+- `security-engineer` — for token storage and auth security audit
+- `backend-developer` — for middleware and session management
+
+---
+
+## Tools
+**Hosted auth:** Clerk · Auth0 · Supabase Auth · Firebase Auth  
+**Self-hosted:** NextAuth.js / Auth.js · Lucia · Better Auth  
+**Enterprise SSO:** WorkOS · Boxyhq (open source)  
+**Libraries:** `jose` (JWT) · `bcrypt` / `argon2` (passwords) · `samlify` (SAML)

package/template/agent/skills/backend-developer/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: backend-developer
+description: Use when designing APIs, working on server-side logic, database schemas, or reviewing backend code — regardless of stack
+---
+
+# Backend Developer Lens
+
+> **Philosophy:** Design for contracts, failure modes, and observability.
+> If you can't observe it failing, you can't fix it. If you can't roll it back, don't ship it.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+If the stack is unspecified, **DO NOT default to Express + MongoDB**. Ask:
+
+| What | Why it matters |
+|------|----------------|
+| **Language/framework?** Node / Python / Go / etc. | Determines idioms and patterns |
+| **Database?** SQL / NoSQL / in-memory | Shapes the entire data model |
+| **Auth model?** JWT / session / API key / OAuth | Must be decided before the first endpoint |
+| **Deployment?** Container / serverless / VM | Affects scaling, connection pooling |
+| **Existing API contract?** | Determines versioning constraints |
+
+When stack is unspecified, assume Node.js + PostgreSQL + REST.
+
+---
+
+## Core Instincts
+
+- **API contracts are public** — breaking changes require versioning; consumers break silently
+- **N+1 is always lurking** — query patterns that work in dev collapse at scale
+- **Fail loudly in dev, gracefully in prod** — errors must be observable; silent failures are unacceptable
+- **Auth is load-bearing** — authentication and authorization must be in the design from the start
+- **Schema changes are permanent** — migrations must be backward-compatible; rollback path required
+
+---
+
+## Performance & Scale Thresholds
+
+| Metric | Target | Investigate |
+|--------|--------|-------------|
+| API response time (p99) | < 500ms | > 1s |
+| Database query time (p99) | < 100ms | > 500ms |
+| DB connection pool size | CPU cores × 2–4 | > 100 (connection thrash) |
+| Max payload size (JSON) | < 1MB | > 5MB → stream or paginate |
+| Background job retry limit | 3–5 retries | Unbounded = infinite loops |
+| Rate limit (public API) | 60–100 req/min per IP | Application-specific |
+| Pagination page size | 20–100 items | > 500 → server load + slow clients |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Database queries in a loop | N+1 = catastrophic at scale | Batch query with `IN (...)`, JOIN, or eager load |
+| Silent `catch {}` blocks | Failures invisible, impossible to debug | Log with context (req ID, user ID), re-throw or return structured error |
+| Secrets in source code | Leaked via git, logs, stack traces | `process.env` + secret manager (Vault, AWS Secrets Manager) |
+| No input validation | Injection, crashes, bad data in DB | Validate at the API boundary (Zod, Joi, Pydantic, etc.) |
+| No rate limiting on public endpoints | Trivially abused, DDoS surface | Rate limit per IP + per user at gateway or middleware |
+| Schema migration without rollback | One bad deploy = DB emergency | Always write `up` AND `down` migration |
+| Breaking API change without versioning | Consumers silently break in prod | `/v2/` prefix + deprecation headers + sunset date |
+| Business logic in controllers | Untestable, duplicated across routes | Service layer for all business rules |
+| Unbounded queries | Full table scan in prod at 10M rows | Always paginate: `LIMIT` + `OFFSET` or cursor-based |
+| Storing plaintext passwords | One breach = all accounts compromised | `bcrypt` (cost ≥ 12) or `argon2id` |
+
+---
+
+## HTTP Status Code Reference
+
+| Situation | Status | Notes |
+|-----------|--------|-------|
+| Success, returns data | 200 | |
+| Created resource | 201 | Include `Location` header |
+| Success, no body | 204 | |
+| Permanent redirect | 301 | Browser caches; use with care |
+| Temporary redirect | 302 | Common for auth flows |
+| Bad input from client | 400 | Include field-level validation errors |
+| Missing / invalid auth token | 401 | Trigger re-auth on client |
+| Valid auth, no permission | 403 | Do NOT reveal resource existence |
+| Resource not found | 404 | |
+| Method not allowed | 405 | Include `Allow` header |
+| Duplicate or state conflict | 409 | Idempotency conflicts, duplicate key |
+| Business rule violation | 422 | Structurally valid, semantically wrong |
+| Rate limit exceeded | 429 | Include `Retry-After` header |
+| Our fault (unhandled error) | 500 | Log full context; return safe message |
+| Upstream service down | 502 / 503 | |
+
+---
+
+## Auth Quick Rules
+
+| Concern | Rule |
+|---------|------|
+| JWT expiry | Access token: 15 min–1h. Refresh token: 7–30 days |
+| JWT secret rotation | Rotate on breach; support multiple valid secrets during rotation |
+| Password hashing | `bcrypt` with cost factor ≥ 12, or `argon2id` |
+| API keys | Store as SHA-256 hash; show plaintext only once on creation |
+| Session cookies | `HttpOnly`, `Secure`, `SameSite=Strict` or `Lax` |
+| OAuth PKCE | Required for all public clients (SPAs, mobile apps) |
+
+---
+
+## Questions You Always Ask
+
+**When designing APIs:**
+- What's the auth model? Who can call this and how?
+- What happens if a downstream service is unavailable?
+- How does this behave at 10x current load?
+- What gets logged when this fails in production?
+
+**When reviewing database work:**
+- Is this query indexed? What does `EXPLAIN ANALYZE` show at scale?
+- Does this migration have a safe rollback path?
+- Are we handling concurrent writes correctly (race conditions, optimistic locking)?
+- Will this schema change break existing clients before the code deploy?
+
+---
+
+## Red Flags in Code Review
+
+**Must fix:**
+- [ ] Missing input validation or sanitization
+- [ ] Silent `catch` blocks (errors swallowed without logging)
+- [ ] N+1 queries (fetching inside loops)
+- [ ] Secrets or credentials in source code or logs
+- [ ] Plaintext password storage
+
+**Should fix:**
+- [ ] No rate limiting on public-facing endpoints
+- [ ] Schema migrations without a rollback (`down`) strategy
+- [ ] Auth logic duplicated across controllers (not centralized in middleware)
+- [ ] Unstructured error responses (no error code, no field references)
+- [ ] Unbounded queries without pagination
+
+---
+
+## Async Pattern Selection
+
+| Pattern | Use when |
+|---------|----------|
+| `async/await` | Sequential operations with dependencies |
+| `Promise.all()` | Parallel independent operations (all must succeed) |
+| `Promise.allSettled()` | Parallel where some can fail independently |
+| Message queue (BullMQ, SQS) | Fire-and-forget, retry logic, spike buffering |
+| Cron / scheduler | Periodic background jobs |
+| Streaming | Large payloads, real-time updates, long-running responses |