mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/ai-agent-deployment/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: ai-agent-deployment
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: ai agent deployment, agent hosting, agent scaling, agent versioning, agent A/B testing, agent monitoring production, agent rollback, agent health check, agent cost production, agent performance monitoring, agent canary, agent shadow testing
+compose: deployment-workflow
+---
+
+# Skill — AI Agent Deployment
+
+## When this skill activates
+Any task involving deploying AI agents to production, versioning agent configurations,
+A/B testing agent variants, monitoring agent quality in production,
+or managing the operational lifecycle of AI agents.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Define the agent version tuple: model + prompt + tools + config (all pinned together).
+2. Identify success metrics (quality, latency, cost, user satisfaction).
+3. Plan rollback strategy (instant version pointer switch).
+4. Design monitoring (token usage, error rate, quality signal).
+
+### During implementation
+- Package agent as a versioned, immutable deployment artifact.
+- Implement health check endpoint (synthetic task probe).
+- Add structured logging for every agent action (input, output, tools used, tokens).
+- Build traffic splitting capability for A/B and canary.
+- Instrument cost tracking per-task and per-user.
+- Implement graceful degradation (fallback to simpler model on failure).
+
+### After implementation
+- Verify shadow test shows no regression vs current version.
+- Confirm monitoring dashboards capture all key metrics.
+- Test rollback procedure end-to-end.
+- Validate cost projections against actual usage.
+- Run synthetic probes for health verification.
+
+## Versioning Strategy
+
+### Agent Version = Immutable Tuple
+```json
+{
+  "version": "agent-v2.3.1",
+  "model": "claude-sonnet-4-20250514",
+  "prompt_hash": "sha256:abc123...",
+  "tools": ["search_v2", "code_exec_v1", "web_browse_v3"],
+  "config": {
+    "temperature": 0.3,
+    "max_tokens": 4096,
+    "timeout_ms": 30000
+  }
+}
+```
+
+### Rules
+- Changing ANY component = new version.
+- Never mutate a deployed version in place.
+- Keep previous N versions warm for instant rollback.
+- Version string includes all components for traceability.
+
+## Hosting Patterns
+
+### Containerized (Recommended)
+- Docker container with model client, prompt, tool implementations.
+- Auto-scale on queue depth (not CPU — agents are I/O bound).
+- GPU allocation only if running local inference.
+- Isolate per-tenant for data separation.
+
+### Scaling Signals
+| Signal | Scale Direction | Reason |
+|--------|----------------|--------|
+| Queue depth increasing | Scale up | Work is backing up |
+| P95 latency rising | Scale up | Capacity insufficient |
+| Queue empty for 5min | Scale down | Over-provisioned |
+| Error rate > 5% | Pause scaling | Fix errors first |
+
+## A/B Testing
+
+### Setup
+1. Define hypothesis (e.g., "new prompt reduces hallucination by 20%").
+2. Split traffic (e.g., 90/10 control/experiment).
+3. Run for statistical significance (typically 1000+ samples per variant).
+4. Measure: quality score, latency, cost, user feedback.
+
+### Metrics to Compare
+- Task success rate (did the agent complete the task correctly?).
+- Token usage (cost proxy).
+- Latency p50/p95/p99.
+- Tool failure rate.
+- User satisfaction signal (thumbs up/down, follow-up corrections).
+- Hallucination rate (if measurable via ground truth).
+
+### Graduation Criteria
+- Improvement statistically significant (p < 0.05).
+- No regression in any critical metric.
+- Cost increase acceptable (<20% for same quality).
+
+## Shadow Testing
+
+### Pattern
+```
+User Request → Production Agent (responds to user)
+            → Shadow Agent (runs silently, output logged)
+```
+
+### Purpose
+- Test new version against real traffic without user impact.
+- Compare outputs offline (human eval or automated scoring).
+- Detect regressions before any user sees them.
+
+### Rules
+- Shadow agent output never reaches the user.
+- Shadow uses same input but may have different model/prompt/tools.
+- Compare at scale (1000+ requests) before promoting.
+- Track divergence rate and categorize differences.
+
+## Monitoring
+
+### Key Metrics (Real-Time Dashboard)
+| Metric | Alert Threshold | Action |
+|--------|----------------|--------|
+| Token usage/task | >2x baseline | Check for loops/verbose output |
+| Latency p95 | >30s | Scale up or investigate bottleneck |
+| Tool failure rate | >5% | Check tool availability |
+| Hallucination rate | >3% | Rollback, investigate prompt |
+| User negative feedback | >10% | Investigate, consider rollback |
+| Cost per task | >$0.50 | Check for inefficiency |
+
+### Structured Logging
+Every agent invocation must log:
+- Request ID, user ID, agent version.
+- Input (sanitized of PII).
+- Output summary.
+- Tools invoked and their results.
+- Token counts (input, output, total).
+- Latency breakdown (thinking, tool calls, generation).
+- Success/failure determination.
+
+## Rollback
+
+### Instant Rollback
+- Version pointer in config store (not redeployment).
+- Switch pointer → immediate traffic to previous version.
+- Keep N previous versions warm (containers running, ready).
+- Rollback decision within 5 minutes of detecting regression.
+
+### Rollback Triggers (Automatic)
+- Error rate > 10% for 3 consecutive minutes.
+- P95 latency > 60s for 5 minutes.
+- User negative feedback spike (3x normal rate).
+
+## Health Checks
+
+### Synthetic Probes
+- Run a known-good task against the agent every 5 minutes.
+- Verify output matches expected structure.
+- Check latency within bounds.
+- Alert if probe fails 2 consecutive times.
+
+### Probe Design
+- Task must be deterministic (or have verifiable structure).
+- Must exercise core capabilities (reasoning + at least one tool).
+- Must complete within health check timeout (10s recommended).
+- Results logged for trend analysis.
+
+## Self-check
+- [ ] Agent version tuple defined (model + prompt + tools + config).
+- [ ] Health check probes running every 5 minutes.
+- [ ] Monitoring covers: tokens, latency, errors, quality, cost.
+- [ ] Rollback tested and confirmed instant.
+- [ ] Shadow test shows no regression.
+- [ ] A/B framework ready for future experiments.
+- [ ] Cost per task tracked and within budget.
+- [ ] Graceful degradation implemented for failures.

package/.mindforge/skills/ai-cost-management/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ai-cost-management
+version: 1.0.0
+min_mindforge_version: 10.5.0
+status: stable
+triggers: AI cost management, token budget optimization, model cost selection, LLM response caching, batch inference processing, AI infrastructure cost, token usage monitoring, cost-aware model routing, inference cost reduction, GPU utilization optimization, AI spend tracking, cost per query optimization
+compose:
+  - llm-cost-optimization
+---
+
+# AI Cost Management & Optimization
+
+## When this skill activates
+
+This skill activates when optimizing AI inference costs, implementing token budgeting, designing cost-aware model routing, or tracking AI spending at scale. It applies to production AI systems where compute costs are significant (>$10K/month) and must be controlled without degrading user experience.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. **Establish cost baseline** — Measure current costs per dimension: cost per request, cost per user, cost per model, cost per task type. Identify cost drivers: which models, which tasks, which users consume the most budget. Focus optimization efforts on the top 20% of cost drivers (Pareto principle).
+2. **Set cost budgets and alerts** — Define acceptable cost thresholds per day, per week, per month. Set up alerts when spending exceeds thresholds (50%, 80%, 100%). Alerts prevent runaway costs from unexpected usage spikes or inefficient code.
+3. **Design cost attribution model** — Assign costs to cost centers: per-team, per-product, per-customer tier (free vs. paid). Enables chargeback (internal teams pay for their usage) and informs product decisions (should free tier have lower model quality to reduce costs?).
+4. **Identify optimization opportunities** — Rank opportunities by potential savings: caching (30-70% reduction for repetitive queries), model downgrade (10-50% reduction with minimal quality loss), batching (20-40% reduction via throughput optimization), prompt compression (10-30% reduction by reducing tokens).
+
+### During implementation
+
+- **Implement aggressive response caching** — Cache LLM responses keyed by prompt hash + model + hyperparameters. Cache hit rate >50% is achievable for many use cases. Use Redis or Memcached for low-latency lookups (<1ms). Set TTL based on content freshness requirements (hours for news, days for documentation, indefinite for static content).
+- **Design cost-aware routing** — Route requests to the cheapest model that meets quality requirements. Example: simple classification → Haiku ($0.25/MTok), complex reasoning → Opus ($15/MTok). Measure quality degradation when downgrading models. If accuracy drop is <2%, downgrade is safe.
+- **Compress prompts aggressively** — Remove filler words, use abbreviations, compress whitespace. Test that compressed prompts produce equivalent outputs. Measure compression ratio (original tokens / compressed tokens). Target: 20-50% compression with <1% quality loss.
+- **Batch inference for throughput** — Group requests into batches (10-100 per batch) to maximize GPU utilization. Batching increases throughput (requests/second) and reduces cost per request (amortize fixed overhead). Trade-off: higher latency (wait for batch to fill) for lower cost.
+- **Implement prompt caching (for supported models)** — Use prompt caching for repeated prompt prefixes (system message, context). Claude and GPT-4 support prompt caching. Reduces cost by 90% for cached tokens. Ensure prompts are structured with stable prefixes and variable suffixes.
+- **Track token usage per request** — Log input tokens, output tokens, and total cost per request. Aggregate by model, task type, user, and time. Identify outliers: queries with unusually high token counts (may indicate inefficient prompts or bugs). Set up monitoring dashboards.
+
+### After implementation
+
+- **Measure cache hit rate** — Track % of requests served from cache. Target: >50% hit rate for production systems with repetitive queries. If lower, analyze cache misses: are prompts subtly different (normalize prompts), is TTL too short (increase TTL), or is traffic too diverse (caching won't help)?
+- **Validate quality after cost optimization** — Compare model accuracy, user satisfaction, or business metrics before and after optimization. Acceptable thresholds: <2% accuracy drop, <5% user satisfaction drop. If degradation is higher, roll back optimizations.
+- **Benchmark cost reduction** — Measure cost per request after optimizations vs. baseline. Target: 30-50% cost reduction from caching + routing + compression. Document savings in $/month and ROI (developer time spent vs. cost saved).
+- **Monitor for cost anomalies** — Set up alerts for sudden cost spikes (>2x daily average) or unusual patterns (single user consuming 10x typical usage). Anomalies indicate bugs (infinite loops, retry storms) or abuse (attackers exploiting free tier).
+
+## Self-check before task completion
+
+- [ ] Cost baseline is measured per request, user, model, and task type
+- [ ] Cost budgets are set with alerts at 50%, 80%, 100% thresholds
+- [ ] Cost attribution model assigns costs to teams, products, or customer tiers
+- [ ] Optimization opportunities are ranked by potential savings and effort
+- [ ] Response caching is implemented with cache hit rate tracked (target >50%)
+- [ ] Cost-aware routing selects cheapest model that meets quality requirements
+- [ ] Prompt compression achieves 20-50% token reduction with <1% quality loss
+- [ ] Batch inference is implemented for throughput optimization (10-100 requests per batch)
+- [ ] Prompt caching (if supported) reduces cost by 90% for repeated prompt prefixes
+- [ ] Token usage is logged per request and aggregated by model, task, user, time
+- [ ] Cache hit rate is validated at >50% for production systems with repetitive queries
+- [ ] Model quality is validated post-optimization (<2% accuracy drop, <5% satisfaction drop)
+- [ ] Cost reduction is benchmarked (target 30-50% reduction from baseline)
+- [ ] Cost anomaly alerts are configured for spikes (>2x daily average) and abuse patterns

package/.mindforge/skills/ai-safety-alignment/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ai-safety-alignment
+version: 1.0.0
+min_mindforge_version: 10.5.0
+status: stable
+triggers: AI safety implementation, AI alignment technique, output filtering AI, content moderation AI, bias detection model, AI guardrail implementation, harmful content prevention, AI red teaming, model safety evaluation, AI ethics implementation, alignment testing, responsible AI deployment
+compose:
+  - guardrails-and-safety
+---
+
+# AI Safety & Alignment
+
+## When this skill activates
+
+This skill activates when implementing output filters, content moderation systems, bias detection, adversarial robustness, or alignment techniques for AI systems. It applies when deploying AI in production environments where safety failures have legal, reputational, or ethical consequences.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. **Define harm taxonomy** — Categorize potential harms specific to your domain: toxic content, misinformation, bias (demographic, cultural), privacy leaks, prompt injection, jailbreaks, copyright violations. Prioritize by severity and likelihood. Not all harms are equal.
+2. **Establish safety thresholds** — Define numeric thresholds for each harm category: toxicity score <0.3, PII detection confidence >0.9, bias parity ratio 0.8-1.2. Thresholds must be tuned on representative data, not arbitrary guesses.
+3. **Select detection models** — Choose specialized classifiers per harm type: Perspective API or custom models for toxicity, named entity recognition for PII, fairness metrics for bias. General-purpose LLMs are too slow and expensive for real-time safety filtering.
+4. **Design layered defense** — Implement multiple safety layers: input validation (reject malicious prompts), model guardrails (constrain model behavior), output filtering (catch harmful completions), monitoring (detect safety failures post-deployment). Single-layer defense is insufficient.
+
+### During implementation
+
+- **Implement input sanitization first** — Validate all user inputs before reaching the model. Reject or sanitize: SQL injection patterns, prompt injection attempts (ignore previous instructions), PII in prompts, excessive length, special characters that break parsing. Log rejected inputs for analysis.
+- **Apply constitutional AI principles** — Constrain model behavior via system prompts: "You are a helpful assistant. You must not generate harmful, biased, or illegal content. If asked to do so, politely refuse and explain why." Test refusal behavior extensively.
+- **Use classifier-guided generation** — For high-risk domains, run a safety classifier on every output before returning to the user. If toxicity/bias/PII is detected above threshold, retry generation with a modified prompt or return a safe default response.
+- **Implement red-teaming as tests** — Create automated adversarial tests: jailbreak attempts, bias triggers, edge cases designed to elicit failures. Run these tests in CI/CD. Safety regressions must block deployment.
+- **Log all safety events** — Record every safety filter activation: input rejected, output filtered, threshold exceeded. Include context: user ID, timestamp, input/output text, classifier scores. This data is critical for tuning thresholds and identifying attack patterns.
+- **Design graceful degradation** — When safety filters trigger, provide user-friendly explanations: "I can't generate that content because [reason]." Do not expose internal classifier scores or filter logic (attackers use this to evade detection).
+
+### After implementation
+
+- **Validate safety coverage** — Test the system with a held-out safety dataset: known toxic examples, bias triggers, jailbreak prompts. Measure recall (% of harmful content caught) and precision (% of flagged content that is truly harmful). Target: recall >95%, precision >90%.
+- **Measure bias across demographics** — Evaluate model outputs for demographic parity, equalized odds, and calibration across protected attributes (race, gender, age). Use fairness toolkits (Fairlearn, AI Fairness 360). Bias gaps >20% require mitigation.
+- **Conduct human red-teaming** — Hire external red-teamers to attempt jailbreaks and adversarial attacks. Automated tests miss creative attack vectors. Budget 20-40 hours of red-teaming per major release.
+- **Monitor safety in production** — Track safety metrics over time: filter activation rate, false positive rate, user complaints about incorrect filtering. Safety degrades as attackers adapt and user behavior shifts.
+
+## Self-check before task completion
+
+- [ ] Harm taxonomy is defined with severity ratings and likelihood estimates
+- [ ] Safety thresholds are set per harm type and validated on representative data
+- [ ] Input sanitization rejects malicious prompts before reaching the model
+- [ ] Output filtering runs on every completion with <100ms latency overhead
+- [ ] Constitutional AI constraints are embedded in system prompts and tested
+- [ ] Automated red-teaming tests run in CI/CD and block deployment on failures
+- [ ] Safety events are logged with full context for post-hoc analysis
+- [ ] Bias is measured across demographics with fairness parity within acceptable bounds
+- [ ] Human red-teaming has been conducted with documented attack attempts and mitigations
+- [ ] Production monitoring tracks filter activation rate and false positive trends

package/.mindforge/skills/analytics-instrumentation/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: analytics-instrumentation
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: analytics instrumentation, event taxonomy, tracking plan, data layer architecture, privacy-aware analytics, funnel measurement, event naming convention, analytics schema, user journey tracking, conversion tracking, analytics governance, event validation
+---
+
+# Skill — Analytics Instrumentation (Privacy-Aware Event Architecture)
+
+## When this skill activates
+When designing event tracking systems, building data layers, creating tracking plans,
+instrumenting user journeys, or establishing analytics governance. Use for any task
+that involves measuring user behavior in a structured, privacy-respecting way.
+
+Core principle: **Track intent, not surveillance** — measure what users DO to improve
+what you BUILD, never to manipulate or over-collect.
+
+## Mandatory actions when this skill is active
+
+### Event Taxonomy Design
+
+1. **Naming convention (object_action format):**
+   ```
+   Format: [object]_[action]
+   Examples:
+   - button_clicked
+   - form_submitted
+   - page_viewed
+   - cart_item_added
+   - search_performed
+   - error_encountered
+   ```
+
+   Rules:
+   - Always past tense for the action (clicked, not click)
+   - Lowercase with underscores (snake_case)
+   - Object first, action second (noun_verb)
+   - Maximum 3 words total (object can be compound: cart_item_added)
+   - Never include PII in event names
+   - Never include dynamic values in event names (no "product_12345_viewed")
+
+2. **Event property schema:**
+   ```json
+   {
+     "event": "button_clicked",
+     "properties": {
+       "button_id": "string (required) — unique identifier",
+       "button_text": "string (required) — visible label",
+       "page_path": "string (required) — current URL path",
+       "section": "string (optional) — page section containing button",
+       "variant": "string (optional) — A/B test variant if applicable"
+     },
+     "context": {
+       "timestamp": "ISO-8601 (auto)",
+       "session_id": "string (auto)",
+       "device_type": "string (auto)",
+       "viewport_width": "number (auto)"
+     }
+   }
+   ```
+
+   Rules:
+   - Separate event-specific properties from auto-collected context
+   - Mark each property as required or optional
+   - Include data type and brief description
+   - Never include PII in properties without explicit consent flag
+
+### Tracking Plan
+
+3. **Tracking plan structure (source of truth):**
+   ```
+   | Event Name       | Trigger                    | Properties         | Owner    | Status       |
+   |------------------|----------------------------|--------------------|----------|--------------|
+   | page_viewed      | Page load complete         | page_path, title   | @fe-team | Implemented  |
+   | button_clicked   | Any tracked button click   | button_id, text    | @fe-team | In Review    |
+   | form_submitted   | Form submission success    | form_id, fields    | @fe-team | Planned      |
+   ```
+
+   Rules:
+   - Every event MUST have an owner (team or individual)
+   - Status lifecycle: Planned → In Review → Implemented → Validated → Deprecated
+   - Review tracking plan quarterly: deprecate unused events
+   - New events require tracking plan entry BEFORE implementation
+
+### Data Layer Architecture
+
+4. **Data layer implementation:**
+   ```javascript
+   // Structured data layer (consumed by analytics tools)
+   window.dataLayer = window.dataLayer || [];
+
+   // Push events with standard structure
+   window.dataLayer.push({
+     event: 'button_clicked',
+     properties: {
+       button_id: 'cta-signup-hero',
+       button_text: 'Start Free Trial',
+       page_path: '/pricing'
+     }
+   });
+   ```
+
+   Rules:
+   - Data layer is the SINGLE source of truth (analytics tools consume it, don't instrument directly)
+   - Never push to data layer before consent is granted
+   - Validate data layer pushes against schema in CI
+   - Data layer must be populated server-side for critical events (don't rely solely on client JS)
+
+### Privacy-Aware Analytics
+
+5. **Privacy requirements (non-negotiable):**
+   - Obtain consent BEFORE any tracking fires (banner/modal with granular choices)
+   - Honor Do Not Track (DNT) header — respect user preference
+   - Anonymize by default: no full IP, no fingerprinting, no cross-site tracking
+   - Data retention: define maximum retention per event type (default 13 months for GDPR)
+   - Right to deletion: ensure analytics pipeline can purge by user ID
+   - Consent categories: necessary (no consent needed) | analytics (consent required) | marketing (separate consent)
+
+6. **Consent implementation:**
+   ```javascript
+   // Only track if user has consented to analytics category
+   if (consentManager.hasConsent('analytics')) {
+     dataLayer.push({ event: 'page_viewed', properties: {...} });
+   }
+   ```
+
+### Funnel Measurement
+
+7. **Funnel definition:**
+   ```
+   Funnel: [name]
+   Steps:
+   1. page_viewed (page_path = '/pricing')     → Entry
+   2. button_clicked (button_id = 'select-plan') → Intent
+   3. form_submitted (form_id = 'payment')     → Commitment
+   4. purchase_completed                        → Conversion
+
+   Metrics per step:
+   - Volume (count)
+   - Conversion rate (step N / step N-1)
+   - Drop-off rate (1 - conversion rate)
+   - Time between steps (median, p95)
+   ```
+
+   Rules:
+   - Define funnels for every critical user journey
+   - Segment funnels by: device, acquisition source, user cohort, experiment variant
+   - Alert on significant drop-off changes (>10% deviation from baseline)
+   - Funnel steps must use the same event taxonomy
+
+### Analytics Governance
+
+8. **Governance processes:**
+   - **Schema validation in CI**: every new event must match the tracking plan schema
+   - **Unused event cleanup**: quarterly audit, deprecate events with <100 fires/month
+   - **Naming review**: new events require team lead approval (prevents drift)
+   - **Data quality monitoring**: alert on sudden volume spikes/drops (instrumentation bugs)
+   - **Documentation**: tracking plan is the living doc, not code comments
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I follow the object_action naming convention?
+- [ ] Is every event documented in the tracking plan with owner and status?
+- [ ] Does the data layer implementation gate on user consent?
+- [ ] Are PII fields excluded from event properties (or flagged for special handling)?
+- [ ] Did I define funnels for critical user journeys with per-step metrics?
+- [ ] Is there a governance process for event lifecycle management?
+- [ ] Can the schema be validated in CI (preventing undocumented events)?
+- [ ] Is data retention defined and compliant with privacy regulations?

package/.mindforge/skills/api-gateway-patterns/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: api-gateway-patterns
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+compose: api-design
+triggers: api gateway, gateway rate limiting, request routing, auth offloading, response transformation, backend for frontend, gateway circuit breaker, request aggregation, api composition, gateway caching, gateway throttling, gateway authentication
+---
+
+# Skill — API Gateway Patterns
+
+## When this skill activates
+Any task involving API gateway configuration, gateway rate limiting, request
+routing, authentication offloading, BFF patterns, or gateway-level caching.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify which cross-cutting concerns belong at the gateway vs service level.
+2. Define rate limiting strategy (algorithm, limits, granularity).
+3. Determine if BFF pattern is needed (multiple client types).
+
+### During implementation
+- Keep gateway logic stateless (no session state in gateway).
+- Implement circuit breakers per downstream service.
+- Add request correlation IDs at the gateway for distributed tracing.
+
+### After implementation
+- Load test rate limiting configuration.
+- Verify circuit breaker thresholds with failure injection.
+- Document gateway routing rules in ARCHITECTURE.md.
+
+## Rate Limiting Algorithms
+
+### Token Bucket
+- Bucket holds N tokens, refills at constant rate.
+- Each request consumes one token.
+- Allows bursts up to bucket capacity.
+- Best for: APIs that need burst tolerance.
+
+### Sliding Window
+- Count requests in rolling time window.
+- Smoother than fixed window (no boundary burst issue).
+- Best for: strict per-second/minute rate enforcement.
+
+### Fixed Window
+- Count requests per calendar interval (e.g., per minute).
+- Simple to implement, but allows 2x burst at window boundary.
+- Best for: simple use cases where boundary bursts are acceptable.
+
+### Rate Limit Granularity
+- **Per-user**: fairest, prevents one user from affecting others.
+- **Per-IP**: catches unauthenticated abuse, but shared IPs cause issues.
+- **Per-endpoint**: different limits for reads vs writes.
+- **Per-plan**: higher limits for premium tier customers.
+
+### Response Headers
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 847
+X-RateLimit-Reset: 1623456789
+Retry-After: 30
+```
+
+## Authentication Offloading
+
+### Pattern
+1. Client sends request with auth token to gateway.
+2. Gateway validates JWT signature and expiration.
+3. Gateway extracts claims (user_id, roles, permissions).
+4. Gateway passes claims as trusted headers to downstream services.
+5. Downstream services trust headers (internal network only).
+
+### Benefits
+- Auth logic in one place, not duplicated across services.
+- Downstream services are simpler (no JWT library needed).
+- Token refresh/rotation handled centrally.
+
+### Security Considerations
+- Strip incoming trust headers from external requests (prevent spoofing).
+- Internal services MUST reject requests without gateway headers.
+- Gateway must validate token on every request (no caching of auth decisions).
+
+## Backend for Frontend (BFF)
+
+### Pattern
+- One gateway per client type: web, mobile, third-party.
+- Each BFF tailored to client needs (field selection, aggregation).
+- Mobile BFF: fewer fields, compressed responses, batch endpoints.
+- Web BFF: full responses, pagination, real-time subscriptions.
+- Third-party BFF: stable API, versioned, rate-limited.
+
+### When to Use BFF
+- Different clients need different data shapes.
+- Mobile clients need response optimization (bandwidth).
+- Third-party API needs different auth and rate limiting.
+
+## Request Aggregation
+
+### Pattern
+- Client sends one request to gateway.
+- Gateway fans out to multiple backend services.
+- Gateway combines responses into single response.
+- Returns aggregated result to client.
+
+### Best Practices
+- Set timeout per downstream call (don't wait forever).
+- Return partial results if some backends fail (degrade gracefully).
+- Cache individual backend responses independently.
+- Use async/parallel calls to backends (not sequential).
+
+## Circuit Breaking (Per-Route)
+
+### States
+- **Closed**: requests flow normally, failures counted.
+- **Open**: requests immediately fail (503), no backend calls.
+- **Half-Open**: allow one probe request to test recovery.
+
+### Configuration Per Downstream
+```yaml
+payment-service:
+  failure_threshold: 5       # failures before opening
+  timeout: 10s               # time in open state before half-open
+  success_threshold: 3       # successes in half-open to close
+
+inventory-service:
+  failure_threshold: 10
+  timeout: 30s
+  success_threshold: 5
+```
+
+### Fallback Strategies
+- Return cached response (stale but functional).
+- Return default/empty response with degraded flag.
+- Route to alternative backend (failover service).
+
+## Gateway Caching
+
+### What to Cache
+- GET responses with stable data (product catalog, configuration).
+- Use ETag/Last-Modified for conditional requests.
+- Cache per-user or per-role (never cache authenticated data globally).
+
+### What NOT to Cache
+- POST/PUT/DELETE responses.
+- Responses with `Cache-Control: no-store`.
+- Responses containing PII without per-user isolation.
+
+### Cache Invalidation at Gateway
+- TTL-based (simple, eventual consistency).
+- Purge API (explicit invalidation from backend on mutation).
+- Surrogate keys (tag responses, purge by tag).
+
+## Response Transformation
+
+### Appropriate at Gateway
+- Field filtering (client requests specific fields).
+- Pagination wrapping (add metadata to list responses).
+- Format conversion (JSON to XML for legacy clients).
+- Header manipulation (add CORS, security headers).
+
+### NOT Appropriate at Gateway
+- Business logic transformation.
+- Data enrichment from other services.
+- Complex aggregation with business rules.
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I read the full SKILL.md before starting? (Not just the triggers)
+- [ ] Is gateway logic stateless?
+- [ ] Are rate limits per-user (not just per-IP)?
+- [ ] Are circuit breakers configured per downstream service?
+- [ ] Is auth offloading stripping external trust headers?
+- [ ] Is business logic kept out of the gateway?
+- [ ] Are request correlation IDs generated at the gateway?