forgecraft-mcp 0.1.0

package/templates/infra/review.yaml

@@ -0,0 +1,65 @@
+tag: INFRA
+section: review
+blocks:
+  - id: infra-architecture-review
+    tier: recommended
+    dimension: architecture
+    title: "Infrastructure Architecture Review"
+    description: |
+      Evaluate IaC patterns, resource organization, and environment management.
+    checklist:
+      - id: iac-all-resources
+        description: "All production resources defined in IaC. No manually created resources."
+        severity: critical
+      - id: module-reuse
+        description: "Common patterns (VPC, database, service) extracted into reusable modules, not copy-pasted."
+        severity: important
+      - id: environment-isolation
+        description: "Environments fully isolated: separate state files, separate accounts/projects where possible."
+        severity: critical
+      - id: blast-radius
+        description: "Stacks/modules scoped to limit blast radius. A bad deploy to one stack doesn't affect others."
+        severity: important
+
+  - id: infra-security-review
+    tier: recommended
+    dimension: code-quality
+    title: "Infrastructure Security Review"
+    description: |
+      Evaluate network security, access control, and secrets management.
+    checklist:
+      - id: least-privilege
+        description: "IAM roles use minimum required permissions. No wildcard actions on production."
+        severity: critical
+      - id: no-public-exposure
+        description: "Databases and application servers in private subnets. Only load balancers are publicly accessible."
+        severity: critical
+      - id: secrets-managed
+        description: "All secrets in a secrets manager with rotation. No hardcoded credentials in IaC files."
+        severity: critical
+      - id: encryption-at-rest
+        description: "Storage volumes, databases, and backups encrypted at rest. KMS keys managed per environment."
+        severity: important
+
+  - id: infra-ops-review
+    tier: recommended
+    dimension: performance
+    title: "Infrastructure Operations Review"
+    description: |
+      Evaluate monitoring, cost management, and operational readiness.
+    checklist:
+      - id: resource-limits
+        description: "CPU and memory limits defined for all containers. No unbounded resource consumption."
+        severity: critical
+      - id: auto-scaling
+        description: "Auto-scaling configured with sensible min/max. Tested under load."
+        severity: important
+      - id: cost-tagging
+        description: "Every resource tagged with Environment, Service, Owner. Untagged resources flagged in CI."
+        severity: important
+      - id: monitoring-alerting
+        description: "Dashboards and alerts for all services. Every alert has a runbook link and clear ownership."
+        severity: important
+      - id: backup-tested
+        description: "Backup and restore procedures tested. RPO/RTO validated against targets."
+        severity: critical

package/templates/infra/structure.yaml

@@ -0,0 +1,25 @@
+tag: INFRA
+section: structure
+entries:
+  - path: terraform/
+    description: "Terraform root — one directory per stack/environment"
+  - path: terraform/modules/
+    description: "Reusable Terraform modules (VPC, ECS, RDS, etc.)"
+  - path: terraform/environments/
+    description: "Per-environment tfvars: dev.tfvars, staging.tfvars, prod.tfvars"
+  - path: cdk/
+    description: "CDK app (if using CDK instead of Terraform)"
+  - path: cdk/lib/
+    description: "CDK stack definitions — one file per stack"
+  - path: cdk/bin/
+    description: "CDK app entry point"
+  - path: docker/
+    description: "Dockerfiles and docker-compose for local development"
+  - path: docker/docker-compose.yml
+    description: "Local development stack: app + backing services"
+  - path: scripts/
+    description: "Operational scripts: deploy, migrate, seed, rotate-secrets"
+  - path: .github/workflows/
+    description: "CI/CD pipeline definitions (GitHub Actions)"
+  - path: docs/runbooks/
+    description: "Operational runbooks: incident response, failover, scaling"

package/templates/library/claude-md.yaml

@@ -0,0 +1,36 @@
+tag: LIBRARY
+section: claude-md
+blocks:
+  - id: library-standards
+    tier: recommended
+    title: "Library Standards"
+    content: |
+      ## Library / Package Standards
+
+      ### Public API
+      - Clear, minimal public API surface. Export only what consumers need.
+      - Barrel file (index.ts / __init__.py) defines the public API explicitly.
+      - Internal modules prefixed with underscore or in internal/ directory.
+      - Every public API has JSDoc/docstring with examples.
+
+      ### Versioning & Compatibility
+      - Semantic versioning: MAJOR.MINOR.PATCH.
+      - MAJOR: breaking API changes. MINOR: new features, backward compatible. PATCH: bug fixes.
+      - CHANGELOG.md maintained with every release.
+      - Deprecation warnings before removal (minimum 1 minor version).
+
+      ### Distribution
+      - Package includes only dist/ and necessary runtime files.
+      - Types included (declaration files for TypeScript).
+      - Peer dependencies used for framework integrations.
+      - Minimize runtime dependencies — every dep is a risk.
+
+      ### Testing
+      - Test against the public API, not internals.
+      - Test with multiple versions of peer dependencies.
+      - Integration tests simulate real consumer usage patterns.
+
+      ### Documentation
+      - README with: install, quick start, API reference, examples.
+      - Usage examples for every major feature.
+      - Migration guide for every major version bump.

package/templates/library/review.yaml

@@ -0,0 +1,56 @@
+tag: LIBRARY
+section: review
+blocks:
+  - id: library-architecture-review
+    tier: recommended
+    dimension: architecture
+    title: "Library Architecture Review"
+    description: |
+      Evaluate public API surface, backward compatibility, and consumer ergonomics.
+    checklist:
+      - id: public-api-surface
+        description: "Public API is minimal and intentional. Every export has a reason. Internal modules are not leaked."
+        severity: critical
+      - id: backward-compatibility
+        description: "Semantic versioning enforced. Breaking changes gated behind major version bumps."
+        severity: critical
+      - id: tree-shaking
+        description: "Package supports tree-shaking: named exports, sideEffects: false, ESM output."
+        severity: important
+      - id: type-exports
+        description: "TypeScript types exported and documented. Declaration files (.d.ts) ship with the package."
+        severity: important
+
+  - id: library-code-quality-review
+    tier: recommended
+    dimension: code-quality
+    title: "Library Code Quality Review"
+    description: |
+      Evaluate API consistency, documentation, and error messages for consumers.
+    checklist:
+      - id: api-consistency
+        description: "Consistent naming conventions and parameter ordering across all public methods."
+        severity: important
+      - id: jsdoc-coverage
+        description: "100% JSDoc coverage on all public APIs with typed params, returns, and examples."
+        severity: critical
+      - id: error-messages
+        description: "Error messages are actionable for consumers: what went wrong, what they should do."
+        severity: important
+
+  - id: library-test-review
+    tier: recommended
+    dimension: tests
+    title: "Library Test Review"
+    description: |
+      Evaluate public API contract tests and cross-environment compatibility.
+    checklist:
+      - id: contract-tests
+        description: "Every public API method has contract tests verifying inputs, outputs, and error cases."
+        severity: critical
+      - id: cross-env-testing
+        description: "Tests run in target environments (Node versions, browser if applicable)."
+        severity: important
+      - id: example-tests
+        description: "README examples are executable tests that stay in sync with the API."
+        severity: nice-to-have

package/templates/library/structure.yaml

@@ -0,0 +1,19 @@
+tag: LIBRARY
+section: structure
+language: typescript
+entries:
+  - path: src/index.ts
+    type: file
+    description: "Public API barrel — exports only what consumers need"
+  - path: src/shared
+    type: directory
+    description: "Shared internal utilities"
+  - path: dist
+    type: directory
+    description: "Compiled output (not committed)"
+  - path: README.md
+    type: file
+    description: "Install, quick start, API reference"
+  - path: CHANGELOG.md
+    type: file
+    description: "Release history"

package/templates/ml/claude-md.yaml

@@ -0,0 +1,42 @@
+tag: ML
+section: claude-md
+blocks:
+  - id: training-pipelines
+    tier: recommended
+    title: "Model Training & Experiment Tracking"
+    content: |
+      ## Model Training & Experiment Tracking
+
+      - Track every experiment with a tool like MLflow, Weights & Biases, or DVC. Log hyperparameters, metrics, dataset versions, and the git commit hash for full reproducibility.
+      - Pin all dependencies (Python version, library versions, CUDA version) in a lockfile or Docker image. A training run from six months ago must be reproducible today.
+      - Separate data preprocessing, feature engineering, model training, and evaluation into distinct pipeline stages with clear interfaces.
+      - Use configuration files (YAML/TOML) for hyperparameters rather than hard-coding them. Support overrides via CLI arguments for sweep runs.
+      - Always hold out a test set that is never used during training or hyperparameter tuning. Report final metrics exclusively on this set.
+      - Version datasets alongside code. Use content-addressable storage or DVC to track dataset lineage and detect drift between training runs.
+      - Set random seeds for all sources of non-determinism (NumPy, PyTorch, TensorFlow, data shuffling) to ensure reproducible results on the same hardware.
+
+  - id: feature-engineering
+    tier: recommended
+    title: "Feature Engineering & Data Preparation"
+    content: |
+      ## Feature Engineering & Data Preparation
+
+      - Build a centralized feature store (or at minimum a shared feature module) to avoid duplicating feature logic across training and serving.
+      - Document every feature: its definition, data source, expected range, update frequency, and any known caveats or biases.
+      - Compute feature statistics (mean, std, min, max, null rate) on the training set and persist them. Apply the same transformations at inference time using these saved statistics—never recompute from inference data.
+      - Handle missing values explicitly. Choose an imputation strategy per feature (mean, median, mode, sentinel value, or model-based) and document the rationale.
+      - Detect and handle data leakage: ensure no future information leaks into features, and that train/validation/test splits respect temporal or entity boundaries.
+      - Monitor feature distributions in production. Alert when serving-time distributions diverge significantly from training-time distributions (data/concept drift).
+
+  - id: model-deployment
+    tier: recommended
+    title: "Model Versioning & Deployment"
+    content: |
+      ## Model Versioning & Serving
+
+      - Store trained model artifacts in a model registry with semantic versioning. Tag each artifact with the training run ID, dataset version, and evaluation metrics.
+      - Serve models behind a versioned API endpoint. Support A/B testing and canary rollouts by routing a percentage of traffic to a new model version.
+      - Define minimum performance thresholds (accuracy, latency p99, throughput) as promotion gates. A model must pass automated evaluation before being promoted to production.
+      - Implement shadow mode: run a new model in parallel with the current production model, compare outputs, and alert on significant divergence before cutting over.
+      - Log all predictions with input features, model version, and timestamp. This enables debugging, bias auditing, and retraining on production data.
+      - Set up automated retraining triggers based on performance degradation, data drift detection, or a fixed schedule. Ensure the retraining pipeline is fully automated end-to-end.

package/templates/ml/nfr.yaml

@@ -0,0 +1,39 @@
+tag: ML
+section: nfr
+blocks:
+  - id: ml-performance
+    tier: recommended
+    title: "ML Model Performance"
+    content: |
+      ## NFR: ML Model Performance
+
+      ### Inference Latency
+      - p50 inference latency: < {{ml_p50_ms | default: 50ms}}.
+      - p99 inference latency: < {{ml_p99_ms | default: 200ms}}.
+      - Batch inference throughput: process {{batch_throughput | default: 10000}} samples/minute.
+
+      ### Model Quality
+      - Primary metric: {{primary_metric | default: accuracy}} ≥ {{primary_threshold | default: 0.90}}.
+      - Model quality regression blocks deployment — automated evaluation in CI/CD.
+      - A/B testing framework for comparing model versions in production.
+
+      ### Data Quality
+      - Data drift detection on model inputs. Alert when distribution shifts beyond threshold.
+      - Schema validation on training and inference data. Reject malformed inputs.
+      - Feature freshness monitored. Stale features flagged.
+
+  - id: ml-reproducibility
+    tier: recommended
+    title: "ML Reproducibility"
+    content: |
+      ## NFR: ML Reproducibility
+
+      ### Experiment Tracking
+      - Every training run logged: hyperparameters, metrics, dataset version, code version.
+      - Experiment tracker (MLflow, Weights & Biases, Neptune) mandatory — not optional.
+      - Model lineage: trace any deployed model back to its training data and code.
+
+      ### Versioning
+      - Datasets versioned (DVC, Delta Lake, or artifact store).
+      - Models versioned with metadata: training date, dataset hash, performance metrics.
+      - Random seeds set and logged for reproducibility.

package/templates/ml/structure.yaml

@@ -0,0 +1,25 @@
+tag: ML
+section: structure
+entries:
+  - path: notebooks/
+    description: "Exploration notebooks — never used in production code"
+  - path: src/data/
+    description: "Data loading, validation, and preprocessing pipelines"
+  - path: src/features/
+    description: "Feature engineering: transformations, feature store connectors"
+  - path: src/models/
+    description: "Model definitions, training loops, evaluation"
+  - path: src/serving/
+    description: "Model serving: API wrappers, batch inference scripts"
+  - path: src/config/
+    description: "Hyperparameters, feature configs, experiment configs (YAML)"
+  - path: tests/
+    description: "Unit tests for data transforms, feature logic, model contracts"
+  - path: tests/data_validation/
+    description: "Data quality tests: schema checks, distribution tests"
+  - path: models/
+    description: "Serialized models and metadata (gitignored, stored in artifact registry)"
+  - path: data/
+    description: "Local data cache (gitignored). Source of truth is remote storage."
+  - path: pipelines/
+    description: "Orchestration definitions: Airflow DAGs, Kubeflow pipelines, or Prefect flows"

package/templates/mobile/claude-md.yaml

@@ -0,0 +1,44 @@
+tag: MOBILE
+section: claude-md
+blocks:
+  - id: responsive-offline
+    tier: recommended
+    title: "Responsive Design & Offline-First"
+    content: |
+      ## Responsive Design & Offline-First Patterns
+
+      - Design mobile-first: start with the smallest viewport and progressively enhance for larger screens. Use CSS media queries or container queries to adapt layout, not separate mobile pages.
+      - Implement an offline-first architecture: the app should be functional without a network connection, using locally cached data, and sync when connectivity is restored.
+      - Use a local database (SQLite, IndexedDB, Realm, WatermelonDB) as the primary data source for the UI. Sync with the server in the background using a conflict resolution strategy (last-write-wins, CRDTs, or manual merge).
+      - Queue mutations (writes, updates, deletes) locally when offline. Process the queue in order when connectivity resumes, handling conflicts and failures for each operation.
+      - Implement a network status indicator in the UI. Clearly communicate to users when they are offline and which features are unavailable or operating on stale data.
+      - Cache API responses with appropriate TTLs. Use stale-while-revalidate patterns to show cached data immediately while fetching fresh data in the background.
+      - Test all user flows in airplane mode and on throttled connections (3G, high latency). Offline behavior should feel intentional, not broken.
+
+  - id: push-lifecycle
+    tier: recommended
+    title: "Push Notifications & App Lifecycle"
+    content: |
+      ## Push Notifications & App Lifecycle
+
+      - Request notification permission contextually—explain the value before prompting. Never request permission on first launch without context; wait until the user encounters a feature that benefits from notifications.
+      - Implement a server-side notification preferences model. Users should control notification categories (marketing, transactional, social) independently, and preferences must be enforced server-side.
+      - Handle notification payloads gracefully in all app states: foreground (in-app banner), background (system notification), and terminated (cold start with deep link to relevant screen).
+      - Use silent/data notifications for background data sync. Keep background execution time under OS limits (< 30 seconds on iOS) to avoid being throttled.
+      - Manage app lifecycle transitions (active → background → suspended → terminated) explicitly. Save unsaved state on `onPause`/`onBackground`, restore it on `onResume`, and release expensive resources (camera, GPS, Bluetooth) when backgrounded.
+      - Handle deep links and universal links with a centralized routing mechanism. Every screen reachable by deep link must handle being the entry point (no assumed navigation stack).
+      - Implement token refresh for push notification services (FCM, APNs). Re-register the device token on every app launch and update the server if it changes.
+
+  - id: platform-performance
+    tier: recommended
+    title: "Platform Patterns & Performance"
+    content: |
+      ## Platform-Specific Patterns & Mobile Performance
+
+      - Respect platform conventions: use platform-native navigation patterns (bottom tabs on iOS, drawer on Android), system fonts, haptic feedback, and gesture behaviors that users expect.
+      - Optimize list rendering: use virtualized/recycled lists (FlatList, RecyclerView, UICollectionView) for any list longer than ~20 items. Never render hundreds of items in a scroll view.
+      - Minimize main thread work. Move file I/O, JSON parsing, image decoding, and network calls off the main/UI thread. Jank-free scrolling requires < 16ms per frame on the UI thread.
+      - Reduce app binary size: use tree shaking, asset compression, on-demand resource loading, and avoid bundling unused native libraries. Monitor binary size in CI and set growth budgets.
+      - Implement graceful permission handling: check permission status before requesting, explain why the permission is needed, handle denial gracefully, and provide a path to re-enable via system settings.
+      - Cache images in memory and on disk with size limits. Use progressive loading (blur placeholder → thumbnail → full resolution) for a smooth visual experience.
+      - Test on real devices across OS versions, screen sizes, and memory configurations. Emulators miss real-world issues like thermal throttling, low memory kills, and vendor-specific OS behaviors.

package/templates/mobile/nfr.yaml

@@ -0,0 +1,49 @@
+tag: MOBILE
+section: nfr
+blocks:
+  - id: mobile-performance
+    tier: recommended
+    title: "Mobile Performance"
+    content: |
+      ## NFR: Mobile Performance
+
+      ### App Size
+      - Initial download: < {{app_size_mb | default: 30}} MB.
+      - On-demand asset downloading for heavy content (maps, ML models, media packs).
+      - Monitor app size in CI — PRs that increase binary > 5% require justification.
+
+      ### Startup
+      - Cold start to interactive: < {{cold_start_ms | default: 2000}} ms.
+      - Lazy-initialize non-critical services. Show skeleton UI immediately.
+      - Splash screen is not a crutch — measure time-to-interactive, not time-to-splash.
+
+      ### Battery & Network
+      - Background work budgeted. No unnecessary wake-locks, polling, or GPS.
+      - Network requests batched where possible. Respect low-data mode settings.
+      - Offline-first: core features work without connectivity. Sync on reconnect.
+
+      ### Runtime
+      - 60 FPS for scrolling and animations. Profile and fix jank.
+      - Memory budget per screen. Monitor for leaks (LeakCanary, Instruments).
+      - No main-thread blocking operations > 16ms.
+
+  - id: mobile-ux
+    tier: recommended
+    title: "Mobile UX Quality"
+    content: |
+      ## NFR: Mobile UX Quality
+
+      ### Platform Compliance
+      - Follow platform guidelines: Material Design (Android), Human Interface Guidelines (iOS).
+      - Support system dark mode, dynamic type / font scaling, and accessibility features.
+      - Deep links and universal links configured and tested.
+
+      ### Crash Rate
+      - Target crash-free rate: ≥ {{crash_free_target | default: 99.5%}}.
+      - Crash reporting (Crashlytics, Sentry) integrated. Crashes triaged within 24 hours.
+      - ANR (Application Not Responding) rate: < 0.5%.
+
+      ### Updates
+      - Over-the-air updates for JS layer (CodePush, Expo Updates) where appropriate.
+      - Force-update mechanism for critical security patches.
+      - Backward-compatible API versioning — old app versions must gracefully degrade.

package/templates/mobile/structure.yaml

@@ -0,0 +1,27 @@
+tag: MOBILE
+section: structure
+entries:
+  - path: src/screens/
+    description: "Screen-level components — one directory per screen"
+  - path: src/components/
+    description: "Shared UI components: buttons, cards, inputs, modals"
+  - path: src/navigation/
+    description: "Navigation configuration: stack, tab, drawer navigators"
+  - path: src/services/
+    description: "API client, storage, auth, push notifications, analytics"
+  - path: src/hooks/
+    description: "Custom React Native hooks"
+  - path: src/store/
+    description: "State management: slices, selectors, async thunks"
+  - path: src/utils/
+    description: "Platform-agnostic utilities and helpers"
+  - path: src/theme/
+    description: "Design tokens, colors, typography, spacing"
+  - path: src/locales/
+    description: "Translation JSON files per locale"
+  - path: assets/
+    description: "Images, fonts, animations (Lottie)"
+  - path: __tests__/
+    description: "Unit and integration tests"
+  - path: e2e/
+    description: "End-to-end tests (Detox, Maestro, or Appium)"

package/templates/realtime/claude-md.yaml

@@ -0,0 +1,42 @@
+tag: REALTIME
+section: claude-md
+blocks:
+  - id: websocket-patterns
+    tier: recommended
+    title: "WebSocket & Connection Management"
+    content: |
+      ## WebSocket & Connection Lifecycle
+
+      - Implement automatic reconnection with exponential backoff and jitter (base 1s, max 30s). Track connection state (connecting, open, closing, closed) and expose it to the UI.
+      - Use heartbeat/ping-pong frames at regular intervals (every 30s) to detect dead connections. Close and reconnect if a pong is not received within the timeout window.
+      - Authenticate WebSocket connections during the handshake (via token in query param or first message). Reject unauthenticated connections immediately—do not allow message exchange before auth.
+      - Assign each connection a unique session ID. Map sessions to user identities server-side for targeted messaging, presence tracking, and connection auditing.
+      - Support graceful degradation: if WebSocket connections fail (corporate proxies, firewalls), fall back to Server-Sent Events or long polling automatically.
+      - Implement connection rate limiting per IP and per user to prevent resource exhaustion from misbehaving clients or attacks.
+      - Buffer outbound messages on the client during disconnection and replay them in order upon reconnection to avoid data loss.
+
+  - id: event-driven-architecture
+    tier: recommended
+    title: "Event-Driven Architecture"
+    content: |
+      ## Event-Driven & Pub/Sub Patterns
+
+      - Use a message broker (Redis Pub/Sub, NATS, Kafka) to fan out events across multiple server instances. Never rely on in-process state for multi-node real-time systems.
+      - Define a clear event schema with versioning. Every event must include: event type, version, timestamp, producer ID, correlation ID, and payload.
+      - Implement topic-based or channel-based subscriptions. Clients should subscribe only to the channels they need to minimize unnecessary message delivery.
+      - Use message acknowledgment for critical events: the consumer must explicitly ack after processing. Unacked messages are redelivered after a timeout.
+      - Deduplicate events on the consumer side using the event ID. Network retries and broker redelivery can produce duplicates that must not cause double-processing.
+      - Separate command messages (requests to change state) from event messages (notifications of state changes). Commands go to a single handler; events fan out to many subscribers.
+
+  - id: backpressure-scaling
+    tier: recommended
+    title: "Backpressure & Scaling"
+    content: |
+      ## Backpressure, Flow Control & Scaling
+
+      - Implement backpressure at every layer. If a consumer cannot keep up, signal the producer to slow down rather than buffering unboundedly and risking OOM.
+      - Set maximum buffer sizes for outbound message queues per connection. If the buffer fills (slow client), drop non-critical messages or disconnect the client with a warning.
+      - Use rate limiting on inbound messages per client (e.g., max 100 messages/second). Reject excess messages with an error code rather than silently dropping them.
+      - Design for horizontal scaling: use sticky sessions or a shared session store so that any server node can handle any client's messages after a reconnection.
+      - Monitor key metrics: active connections, messages per second (in/out), message latency p50/p95/p99, buffer utilization, and reconnection rate. Alert on anomalies.
+      - Load-test real-time features with realistic connection counts (10x expected peak) and message rates to identify bottlenecks before they appear in production.

package/templates/social/claude-md.yaml

@@ -0,0 +1,43 @@
+tag: SOCIAL
+section: claude-md
+blocks:
+  - id: ugc-moderation
+    tier: recommended
+    title: "User-Generated Content & Moderation"
+    content: |
+      ## User-Generated Content & Moderation
+
+      - Treat all user-generated content (UGC) as untrusted input. Sanitize HTML, validate file types and sizes, and strip EXIF metadata from uploaded images to prevent data leakage.
+      - Implement a multi-layer moderation pipeline: automated filters (keyword blocklists, ML classifiers) → queue for human review → final disposition (approve, reject, escalate).
+      - Use a content status model: all UGC transitions through states (pending → approved / rejected / flagged). Only approved content is visible to other users by default.
+      - Implement user-driven reporting with structured categories (spam, harassment, misinformation, illegal content). Deduplicate reports and escalate based on volume and severity.
+      - Apply rate limiting on content creation: new accounts should have stricter limits (e.g., max 5 posts/day) that relax as the account ages and builds trust.
+      - Maintain appeal workflows: users whose content is removed should be notified with the reason and given a clear path to appeal the decision.
+      - Log all moderation actions (who, what, when, why) for accountability and to train automated classifiers over time.
+
+  - id: feeds-notifications
+    tier: recommended
+    title: "Feeds & Notification Systems"
+    content: |
+      ## Feed Generation & Notifications
+
+      - Use a fan-out-on-write strategy for small-to-medium scale: when a user posts, push the post ID to each follower's feed cache (e.g., Redis sorted set by timestamp).
+      - For high-follower accounts (celebrities), use fan-out-on-read: merge their posts into the feed at read time to avoid writing to millions of follower feeds.
+      - Implement cursor-based pagination for feeds (`?after=<post_id>&limit=20`). Never use offset-based pagination—it produces inconsistent results as new content is inserted.
+      - Separate notification delivery from notification generation. Generate notifications as events, then deliver them through multiple channels (in-app, push, email) based on user preferences.
+      - Batch and debounce notifications to avoid spamming: "5 people liked your post" rather than 5 individual notifications within a minute.
+      - Store notification read/unread state per user. Provide a "mark all as read" endpoint and support real-time badge count updates via WebSocket or SSE.
+
+  - id: privacy-social-graph
+    tier: recommended
+    title: "Privacy & Social Graph"
+    content: |
+      ## Privacy Controls & Social Graph
+
+      - Default to private. New accounts should have restrictive visibility settings that users explicitly open up, not the reverse.
+      - Model privacy as a per-resource, per-audience policy: each piece of content can be visible to `public`, `followers`, `mutual_follows`, `specific_list`, or `only_me`.
+      - Enforce privacy at the data access layer (query filters), not just the UI. A direct API call with a content ID must still respect the viewer's permission relative to the content owner.
+      - Support account blocking and muting as first-class features. Blocked users cannot view the blocker's content, send messages, or appear in their feeds—enforced server-side.
+      - Store the social graph (follow/friend relationships) in a structure optimized for common queries: "does A follow B?" (O(1) lookup), "who does A follow?" (paginated list), "mutual friends of A and B" (set intersection).
+      - Implement data export (GDPR Article 20) and account deletion (GDPR Article 17) as automated, auditable processes. Deletion must cascade to all content, messages, and derived data.
+      - Rate-limit follow/friend actions to prevent spam following. Detect and flag accounts exhibiting bot-like social graph manipulation patterns.

package/templates/state-machine/claude-md.yaml

@@ -0,0 +1,42 @@
+tag: STATE-MACHINE
+section: claude-md
+blocks:
+  - id: state-transition-design
+    tier: recommended
+    title: "State Transition Design"
+    content: |
+      ## State Transition Patterns
+
+      - Define all valid states and transitions as an explicit, declarative configuration (object map, table, or DSL)—never as scattered if/else chains across the codebase.
+      - Make the state machine the single source of truth for "what can happen next." UI elements, API validations, and business logic should all derive their behavior from the machine definition.
+      - Every transition should be triggered by a named event. Use past-tense names for events that report something happened (`PAYMENT_RECEIVED`) and imperative names for commands (`SUBMIT_ORDER`).
+      - Model transitions as pure functions: `(currentState, event) → nextState + effects`. Keep the transition logic free of side effects; execute effects (API calls, notifications) separately.
+      - Validate transitions before executing them. If an event is not valid in the current state, reject it with a clear error rather than silently ignoring it.
+      - Persist the current state and a history of transitions (event, from-state, to-state, timestamp, actor) for auditability and debugging.
+      - Visualize the state machine from its definition (e.g., generate a Mermaid or Graphviz diagram). Review the diagram in PRs that modify state logic.
+
+  - id: guards-actions
+    tier: recommended
+    title: "Guards, Actions & Side Effects"
+    content: |
+      ## Guards, Actions & Side Effects
+
+      - Use guard conditions to make transitions conditional: a transition fires only if the guard predicate evaluates to true given the current context.
+      - Keep guards as pure, synchronous predicates. If a guard needs async data, fetch the data before sending the event to the machine—don't make the machine wait on I/O.
+      - Separate actions into three categories: entry actions (run when entering a state), exit actions (run when leaving a state), and transition actions (run during a specific transition).
+      - Actions should be fire-and-forget from the machine's perspective. If an action can fail and the failure matters, model the failure as a new event that the machine handles.
+      - Use the context (extended state) to carry data that influences guards and actions. Update context immutably during transitions to maintain a clear audit trail.
+      - Implement an effect/service layer that the machine invokes but does not depend on directly. This makes the machine testable in isolation without mocking external systems.
+
+  - id: hierarchical-parallel
+    tier: recommended
+    title: "Hierarchical & Parallel States"
+    content: |
+      ## Hierarchical & Parallel State Patterns
+
+      - Use hierarchical (nested) states to avoid transition explosion. Common behaviors shared by sibling states should be defined on the parent state.
+      - Model independent concurrent behaviors as parallel (orthogonal) state regions. For example, a form component might have parallel regions for validation state and submission state.
+      - Define clear entry and exit points for compound states. Use initial states for child regions and final states to signal region completion.
+      - Avoid deeply nested hierarchies (> 3 levels). If nesting grows complex, consider decomposing into separate communicating machines via the actor model.
+      - Use `done` events to coordinate between parallel regions or between parent and child machines. A parent can transition when all child regions reach their final states.
+      - Test state machines exhaustively: cover every state, every transition, every guard branch, and every unreachable-state assertion. Use model-based testing to auto-generate transition paths.