feat(skills): add 12 engineering skills across 4 domains (v0.1.41)

High-frequency (6):
- flow-code-observability: structured logging, distributed tracing, metrics (RED/USE)
- flow-code-database: migration safety, N+1 detection, indexing, cursor pagination
- flow-code-error-handling: retry with backoff, circuit breaker, graceful degradation
- flow-code-containerization: multi-stage Docker, K8s probes, security hardening
- flow-code-i18n: ICU messages, Intl APIs, RTL support, locale formatting
- flow-code-state-management: state classification ladder, server state, Context pitfalls

Architecture (6):
- flow-code-realtime: WebSocket/SSE/polling selection, reconnection, heartbeat
- flow-code-auth: OAuth+PKCE, JWT lifecycle, RBAC, resource-level authorization
- flow-code-caching: cache-aside, HTTP caching, TTL/invalidation strategies
- flow-code-monitoring: SLO/SLI, four golden signals, alerting rules, runbook template
- flow-code-documentation: ADRs, README structure, API docs, changelog, doc-as-code
- flow-code-microservices: bounded contexts, saga, event-driven, data ownership

Skill guide updated with categorized table (Core/Frontend/Backend/Infra/Quality).
Total engineering skills: 24. Total plugin skills: 49.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

bin/flowctl

@@ -1,6 +1,6 @@
 [package]
 name = "flowctl-cli"
-version = "0.1.40"
+version = "0.1.41"
 description = "CLI entry point for flowctl"
 edition.workspace = true
 rust-version.workspace = true

flowctl/crates/flowctl-cli/Cargo.toml

@@ -0,0 +1,185 @@
+---
+name: flow-code-auth
+description: "Use when implementing authentication, authorization, OAuth, JWT, RBAC, or session management. Covers token lifecycle, permission models, and secure session handling."
+tier: 2
+user-invocable: true
+---
+<!-- SKILL_TAGS: auth,authentication,authorization,jwt,oauth,rbac -->
+
+# Authentication & Authorization
+
+## Overview
+
+Authentication (who are you?) and authorization (what can you do?) are separate concerns. Implement them in separate layers, test them independently, and never trust the client.
+
+## When to Use
+
+- Adding login/signup flows
+- Implementing OAuth (Google, GitHub, etc.)
+- Designing role-based access control (RBAC)
+- Managing JWT tokens or sessions
+- Adding API key authentication
+- Implementing multi-tenant access control
+
+## Authentication Patterns
+
+### Session-Based (Server-Side)
+
+```
+Client                    Server
+  │── POST /login ──────>│ Verify credentials
+  │<── Set-Cookie: sid ──│ Create session in store
+  │── GET /api (cookie) ─>│ Lookup session by cookie
+  │<── 200 data ─────────│
+```
+
+**Best for:** Traditional web apps, SSR frameworks (Next.js, Rails, Django).
+
+### Token-Based (JWT)
+
+```
+Client                    Server
+  │── POST /login ──────>│ Verify credentials
+  │<── { accessToken, ──│ Sign JWT
+  │     refreshToken }   │
+  │── GET /api ──────────>│ Verify JWT signature
+  │   Authorization:      │ (no DB lookup needed)
+  │   Bearer <token>      │
+  │<── 200 data ─────────│
+```
+
+**Best for:** APIs, SPAs, mobile apps, microservices.
+
+### Token Lifecycle
+
+```
+Access Token:  short-lived (15 min), stored in memory
+Refresh Token: long-lived (7-30 days), stored in httpOnly cookie
+API Key:       no expiry, stored server-side, revocable
+
+Flow:
+1. Login → get access + refresh tokens
+2. Access token expires → use refresh token to get new pair
+3. Refresh token expires → force re-login
+4. Logout → revoke refresh token server-side
+```
+
+**Rules:**
+- Access tokens in memory (not localStorage — XSS vulnerable)
+- Refresh tokens in httpOnly secure cookies (not accessible to JS)
+- Rotate refresh tokens on every use (detect theft)
+- Maintain a revocation list for compromised tokens
+
+### OAuth 2.0 / OIDC
+
+```
+1. Redirect user to provider: /authorize?client_id=...&redirect_uri=...&scope=openid
+2. User authenticates with provider
+3. Provider redirects back with authorization code
+4. Server exchanges code for tokens (server-to-server, code never exposed to client)
+5. Server creates session or issues own JWT
+```
+
+**Rules:**
+- Always use Authorization Code flow (not Implicit — deprecated)
+- Use PKCE for public clients (SPAs, mobile)
+- Validate `id_token` signature and claims (issuer, audience, expiry)
+- Store provider tokens server-side (never send to client)
+- Request minimum scopes needed
+
+## Authorization Patterns
+
+### RBAC (Role-Based Access Control)
+
+```typescript
+// Define roles and permissions
+const ROLES = {
+  admin:  ['read', 'write', 'delete', 'manage_users'],
+  editor: ['read', 'write'],
+  viewer: ['read'],
+} as const;
+
+// Check permission (not role!)
+function requirePermission(permission: string) {
+  return (req, res, next) => {
+    const userPerms = ROLES[req.user.role];
+    if (!userPerms?.includes(permission)) {
+      return res.status(403).json({ code: 'FORBIDDEN', message: 'Insufficient permissions' });
+    }
+    next();
+  };
+}
+
+// Usage: check permission, not role
+app.delete('/api/posts/:id', requirePermission('delete'), deletePost);
+```
+
+**Rule:** Check permissions, not roles. Roles map to permissions, but code should check `canDelete`, not `isAdmin`.
+
+### Resource-Level Authorization
+
+```typescript
+// ALWAYS check ownership — not just authentication
+async function updatePost(userId: string, postId: string, data: Partial<Post>) {
+  const post = await db.posts.findById(postId);
+  if (!post) throw new NotFoundError();
+  if (post.authorId !== userId && !hasPermission(userId, 'admin')) {
+    throw new ForbiddenError();  // Authenticated but not authorized
+  }
+  return db.posts.update(postId, data);
+}
+```
+
+### Multi-Tenant Isolation
+
+```typescript
+// Every query scoped to tenant
+function getTenantPosts(tenantId: string, userId: string) {
+  return db.posts.findMany({
+    where: { tenantId, authorId: userId },  // Always include tenantId
+  });
+}
+
+// Middleware enforces tenant context
+function tenantMiddleware(req, res, next) {
+  req.tenantId = extractTenantFromToken(req);
+  if (!req.tenantId) return res.status(403).json({ code: 'NO_TENANT' });
+  next();
+}
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "We'll add auth later" | Every unauthenticated endpoint becomes tech debt. Add auth from day one. |
+| "Just check if user is admin" | Check permissions, not roles. Roles change; permissions are the contract. |
+| "JWT in localStorage is fine" | Any XSS vulnerability = stolen tokens. Use httpOnly cookies for refresh tokens. |
+| "OAuth is too complex for now" | OAuth libraries handle the complexity. Don't build your own auth system. |
+| "We trust our API clients" | Never trust clients. Validate permissions server-side for every request. |
+
+## Red Flags
+
+- Passwords stored as plaintext or MD5/SHA1
+- JWT stored in localStorage (XSS-vulnerable)
+- Authorization checks only in the UI (not server-side)
+- Role checks instead of permission checks (`if (user.role === 'admin')`)
+- No refresh token rotation (theft undetectable)
+- OAuth Implicit flow (deprecated, use Authorization Code + PKCE)
+- Missing resource-level auth (authenticated users can access any resource)
+- Hardcoded API keys in source code
+- No session expiry or token expiry
+
+## Verification
+
+- [ ] Authentication and authorization in separate middleware layers
+- [ ] Passwords hashed with bcrypt/scrypt/argon2
+- [ ] Access tokens short-lived (15 min), refresh tokens in httpOnly cookies
+- [ ] OAuth uses Authorization Code + PKCE (not Implicit)
+- [ ] Authorization checks permissions, not roles
+- [ ] Resource-level auth verifies ownership (not just authentication)
+- [ ] Multi-tenant queries always scoped by tenant ID
+- [ ] Token revocation mechanism exists (logout invalidates server-side)
+- [ ] No secrets or tokens in localStorage
+
+**See also:** [Security Checklist](../../references/security-checklist.md) for broader security patterns.

skills/flow-code-auth/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: flow-code-caching
+description: "Use when adding caching layers — HTTP cache, CDN, Redis, in-memory, or application-level. Covers cache invalidation, TTL strategy, and cache-aside patterns."
+tier: 2
+user-invocable: true
+---
+<!-- SKILL_TAGS: caching,redis,cdn,performance -->
+
+# Caching Strategies
+
+## Overview
+
+Caching is a trade-off: speed vs. staleness. Every cache needs an invalidation strategy before it's built. The two hardest problems in computer science: cache invalidation, naming things, and off-by-one errors.
+
+## When to Use
+
+- API responses are slow and data changes infrequently
+- Same data requested by many users (product catalog, config)
+- Expensive computations (aggregations, reports, search results)
+- Static assets (images, CSS, JS bundles)
+- Rate-limited external APIs (cache responses to reduce calls)
+
+**When NOT to use:**
+- Data that must be real-time (financial transactions, live chat)
+- User-specific data that's rarely re-requested
+- Write-heavy workloads (cache invalidation overhead > benefit)
+
+## Cache Layers (Top to Bottom)
+
+```
+Browser Cache ──> CDN ──> Reverse Proxy ──> App Cache ──> Database
+  (client)      (edge)    (nginx/Varnish)   (Redis)      (source)
+```
+
+Each layer closer to the user is faster but harder to invalidate.
+
+## HTTP Caching
+
+```typescript
+// Static assets: long cache + content hash in filename
+res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+// File: /assets/app.a1b2c3.js (hash changes on content change)
+
+// API responses: short cache + revalidation
+res.setHeader('Cache-Control', 'private, max-age=60, stale-while-revalidate=300');
+res.setHeader('ETag', computeETag(data));
+
+// Sensitive data: never cache
+res.setHeader('Cache-Control', 'no-store');
+```
+
+| Directive | Use For |
+|-----------|---------|
+| `public, max-age=31536000, immutable` | Hashed static assets (JS, CSS, images) |
+| `private, max-age=60` | User-specific API data |
+| `public, max-age=300, stale-while-revalidate=3600` | Shared API data (product catalog) |
+| `no-store` | Auth tokens, PII, financial data |
+| `no-cache` | Always revalidate (ETag/Last-Modified) |
+
+## Application Cache (Redis / In-Memory)
+
+### Cache-Aside Pattern
+
+```typescript
+async function getUser(userId: string): Promise<User> {
+  // 1. Check cache
+  const cached = await redis.get(`user:${userId}`);
+  if (cached) return JSON.parse(cached);
+
+  // 2. Cache miss → fetch from DB
+  const user = await db.users.findById(userId);
+  if (!user) throw new NotFoundError();
+
+  // 3. Populate cache with TTL
+  await redis.set(`user:${userId}`, JSON.stringify(user), 'EX', 300);
+  return user;
+}
+
+// Invalidate on write
+async function updateUser(userId: string, data: Partial<User>) {
+  await db.users.update(userId, data);
+  await redis.del(`user:${userId}`);  // Delete, don't update (simpler)
+}
+```
+
+### Write-Through Pattern
+
+```typescript
+// Write to cache AND database together
+async function updateProduct(id: string, data: Partial<Product>) {
+  const product = await db.products.update(id, data);
+  await redis.set(`product:${id}`, JSON.stringify(product), 'EX', 3600);
+  return product;
+}
+```
+
+## Invalidation Strategies
+
+| Strategy | How | Best For |
+|----------|-----|----------|
+| **TTL (Time-to-Live)** | Cache expires after N seconds | Data where staleness is acceptable |
+| **Event-driven** | Invalidate on write/update event | Data that must be fresh after mutation |
+| **Version key** | Append version to cache key | Bulk invalidation (clear all product caches) |
+| **Purge on deploy** | Clear cache on new deployment | Config, templates, feature flags |
+
+**Golden Rule:** `cache.del()` on write is simpler and safer than `cache.set()` on write. Let the next read repopulate.
+
+## Cache Key Design
+
+```typescript
+// Good: predictable, scoped, versioned
+`user:${userId}`
+`products:list:page=${page}:sort=${sort}`
+`config:v${version}:${tenantId}`
+
+// Bad: unpredictable or unbounded
+`data_${Date.now()}`           // Never hit, always miss
+`search:${fullQueryString}`    // Unbounded cardinality
+```
+
+**Rules:**
+- Include all parameters that affect the response
+- Use delimiters consistently (`:` for Redis keys)
+- Set maximum key count (eviction policy: LRU, LFU)
+- Monitor hit rate (< 80% hit rate means cache isn't helping)
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Cache everything" | Caching data that changes every second wastes memory and adds invalidation complexity. |
+| "TTL handles invalidation" | Stale data for the TTL duration may be unacceptable. Use event-driven for critical data. |
+| "We'll figure out invalidation later" | Invalidation IS the design. A cache without an invalidation strategy is a bug factory. |
+| "In-memory cache is enough" | In-memory caches don't survive restarts and aren't shared across instances. Use Redis for shared state. |
+
+## Red Flags
+
+- Cache without TTL or invalidation strategy
+- Caching user-specific data with `public` Cache-Control
+- Cache key doesn't include all varying parameters (serving wrong data)
+- No cache eviction policy (memory grows unbounded)
+- Caching mutable data without write-through or invalidation
+- `no-cache` confused with `no-store` (they're different)
+- Missing `Vary` header for content negotiation (language, encoding)
+
+## Verification
+
+- [ ] Every cache entry has TTL or explicit invalidation strategy
+- [ ] Cache keys include all parameters that affect the response
+- [ ] Write operations invalidate affected cache entries
+- [ ] Static assets use content-hashed filenames + immutable cache
+- [ ] Sensitive data uses `Cache-Control: no-store`
+- [ ] Cache hit rate monitored (target > 80%)
+- [ ] Eviction policy configured (LRU/LFU, max memory)
+- [ ] Graceful degradation when cache is unavailable (fall through to DB)
+
+**See also:** [Performance Checklist](../../references/performance-checklist.md) for broader optimization patterns.