mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/dmux-workflows/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: dmux-workflows
+version: 1.0.0
+min_mindforge_version: 10.0.5
+status: stable
+triggers: dmux, parallel agents, multi-model orchestration, tmux agents, worktree parallel, parallel panes, concurrent execution, multi-harness, orchestrate workers, split work, fan out, parallel branches
+---
+
+# Skill — Dmux Workflows (Multi-Agent Parallel Execution)
+
+## When this skill activates
+
+When executing multiple independent tasks simultaneously using parallel agent
+instances, tmux panes, or git worktrees. Use when facing 2+ tasks that have no
+shared state, no sequential dependencies, and would benefit from concurrent
+execution. Handles isolation, coordination, and merge strategies for parallel work.
+
+Core principle: **Independence before parallelism** — never parallelize tasks that
+touch the same files or depend on each other's output.
+
+## Mandatory actions when this skill is active
+
+### Before parallel execution begins
+
+1. **Task decomposition:**
+   - List all subtasks in the current work item
+   - For each pair of subtasks, verify: do they touch the same files? (NO required)
+   - For each pair, verify: does one depend on the other's output? (NO required)
+   - If ANY dependency exists: serialize those tasks, parallelize the rest
+
+2. **Worker definition:**
+   ```json
+   {
+     "session": "dmux-[feature-name]",
+     "workers": [
+       {
+         "name": "worker-1-description",
+         "task": "specific task instructions",
+         "model": "sonnet|opus|haiku",
+         "branch": "feat/[feature]-[subtask]",
+         "files": ["list", "of", "files", "this", "worker", "touches"],
+         "timeout_minutes": 30
+       }
+     ]
+   }
+   ```
+
+3. **Independence verification matrix:**
+   - Create file-touch matrix: workers (rows) x files (columns)
+   - If any column has more than one worker marked: STOP, restructure tasks
+   - This is the critical safety check — skip it and you get merge conflicts
+
+4. **Select execution pattern:**
+
+   | Pattern | Workers | Use when |
+   |---------|---------|----------|
+   | Research + Implement | 2 | One explores options, other builds after |
+   | Multi-file | 2-4 | Each worker owns distinct files |
+   | Test + Fix | 2 | Watcher finds bugs, fixer resolves them |
+   | Cross-model review | 3 | Security + perf + coverage perspectives |
+   | Fan-out gather | 3-5 | Same prompt, different models, best-of-N |
+
+### During parallel execution
+
+**Launch protocol:**
+1. Create tmux session: `tmux new-session -d -s dmux-[name]`
+2. For each worker beyond the first: `tmux split-window` or `tmux new-window`
+3. Set up git worktree for each pane:
+   ```bash
+   git worktree add ../worktree-[worker-name] -b [worker-branch]
+   ```
+4. Launch agent in each pane with task-specific instructions
+5. Maximum 5-6 panes (beyond this, coordination overhead exceeds benefit)
+
+**Isolation guarantees:**
+- Each worker operates in its own worktree (filesystem isolation)
+- Each worker has its own branch (git isolation)
+- No worker reads files that another worker writes
+- Workers do NOT communicate during execution (no shared state)
+
+**Monitoring during execution:**
+- Check pane output periodically for errors or stalls
+- If a worker finishes early: do NOT reassign it (avoid introducing dependencies)
+- If a worker fails: note the failure, continue others, address in merge phase
+- Track wall-clock time per worker for future estimation
+
+**Resource constraints:**
+- Max 5-6 concurrent panes (token budget and context limits)
+- Each worker should complete within its timeout
+- If total token usage exceeds budget: kill lowest-priority worker first
+- Prefer fewer workers with clear tasks over many workers with vague tasks
+
+### After parallel execution
+
+1. **Merge strategy (sequential, NOT parallel):**
+   - Review each worker's output independently
+   - Verify each worker stayed within its file boundaries
+   - Merge workers one at a time into the integration branch:
+     ```bash
+     git checkout main-feature-branch
+     git merge worktree-[worker-1-branch] --no-ff
+     # verify tests pass
+     git merge worktree-[worker-2-branch] --no-ff
+     # verify tests pass
+     # repeat for each worker
+     ```
+   - Run full test suite after all merges
+
+2. **Conflict resolution:**
+   - If merge conflict occurs: investigate which worker violated boundaries
+   - Resolve manually (do not auto-resolve — understand the conflict)
+   - Add the conflicting files to a "shared files" list for future runs
+
+3. **Cleanup:**
+   - Remove all worktrees: `git worktree remove ../worktree-[name]`
+   - Delete worker branches if fully merged
+   - Close tmux session: `tmux kill-session -t dmux-[name]`
+   - Consolidate results into a single summary
+
+4. **Results consolidation:**
+   ```
+   ## Dmux Execution Report
+   - Session: dmux-[name]
+   - Workers: N launched, M succeeded, F failed
+   - Wall-clock time: X minutes (vs estimated Y sequential)
+   - Speedup factor: sequential_time / parallel_time
+   - Conflicts: [none | list with resolution]
+   - Output: [summary of what each worker produced]
+   ```
+
+## Self-check before task completion
+
+Before marking a parallel execution task done:
+
+- [ ] Did I verify task independence (no shared files, no output dependencies)?
+- [ ] Did I use git worktrees for filesystem isolation?
+- [ ] Did I stay within the 5-6 pane maximum?
+- [ ] Did I review each worker's output independently before merging?
+- [ ] Did I run full tests after all merges completed?
+- [ ] Did I clean up worktrees and close the tmux session?
+- [ ] Did I document the speedup factor and any conflicts encountered?

package/.mindforge/skills/dns-architecture/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: dns-architecture
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: dns architecture, dns load balancing, dns failover, GeoDNS, TTL strategy, dns service discovery, dns-based routing, dns health check, dns propagation, anycast dns, dns caching layer, dns resolution chain
+---
+
+# Skill — DNS Architecture
+
+## When this skill activates
+Any task involving DNS-based traffic management, load balancing via DNS,
+failover strategies, GeoDNS routing, service discovery using DNS,
+or TTL optimization for high-availability systems.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Map the DNS resolution chain (client → resolver → authoritative → response).
+2. Identify failover requirements (RTO target determines TTL).
+3. Decide routing strategy (round-robin, weighted, latency, geo, failover).
+4. Determine health check mechanism for DNS-managed endpoints.
+
+### During implementation
+- Set TTL appropriate to failover speed requirements.
+- Implement health checks for all DNS-managed endpoints.
+- Use anycast for latency-critical global services.
+- Configure both primary and secondary DNS providers for resilience.
+- Document propagation delays for operational runbooks.
+- Never rely on DNS as sole load balancer for sub-second failover.
+
+### After implementation
+- Verify health checks remove unhealthy endpoints within TTL window.
+- Test failover scenario end-to-end (kill primary, measure recovery time).
+- Confirm GeoDNS routes correctly from each target region.
+- Monitor DNS resolution latency and error rates.
+- Validate TTL behavior in major resolvers (Google, Cloudflare, ISP).
+
+## DNS Load Balancing
+
+### Strategies
+| Strategy | How It Works | Best For |
+|----------|-------------|----------|
+| Round-robin | Rotate through A records | Simple distribution |
+| Weighted | Assign weight per endpoint | Canary, capacity differences |
+| Latency-based | Route to lowest-latency endpoint | Global services |
+| Failover | Primary/secondary with health check | HA with clear primary |
+| Geo | Route by resolver geography | Data sovereignty, latency |
+
+### Limitations
+- DNS caching means changes take TTL seconds to propagate.
+- Client-side caching may ignore TTL (some browsers cache 60s minimum).
+- Cannot do sub-second failover via DNS alone.
+- Resolver location != user location (use EDNS Client Subnet to improve).
+
+## GeoDNS
+
+### How It Works
+1. DNS query arrives at authoritative server.
+2. Server determines resolver's geographic location (via IP geolocation).
+3. Returns IP address of nearest datacenter.
+4. EDNS Client Subnet (ECS) improves accuracy by passing client subnet.
+
+### Configuration
+```
+# Example GeoDNS policy
+api.example.com:
+  default: us-east-1.api.example.com
+  EU: eu-west-1.api.example.com
+  APAC: ap-southeast-1.api.example.com
+  fallback: us-east-1.api.example.com  # if region unhealthy
+```
+
+### Considerations
+- Resolver location != user location (corporate DNS, VPN users).
+- ECS support improves accuracy but not universally supported.
+- Always have fallback for unresolvable regions.
+- Test from each target region to verify correct routing.
+
+## TTL Strategy
+
+### TTL Decision Framework
+| Scenario | Recommended TTL | Reason |
+|----------|----------------|--------|
+| Fast failover needed | 30-60 seconds | Quick removal of unhealthy |
+| Normal operation | 300 seconds (5 min) | Balance between freshness and cache |
+| Static content CDN | 3600 seconds (1 hour) | Rarely changes, maximize cache |
+| During migration | 60 seconds | Prepare for cutover |
+| After migration stable | 300-3600 seconds | Return to normal caching |
+
+### TTL Trade-offs
+- **Low TTL (30s)**: Fast failover, more DNS queries, higher authoritative load.
+- **High TTL (3600s)**: Fewer queries, better cache hit rate, slow failover.
+- **Strategy**: Lower TTL before planned changes, raise after stability confirmed.
+
+### Propagation Reality
+- TTL expiry != instant propagation.
+- Some resolvers enforce minimum TTL (30s-60s).
+- Browser DNS cache may ignore TTL entirely.
+- Java apps cache DNS indefinitely by default (set `networkaddress.cache.ttl`).
+
+## Service Discovery via DNS
+
+### Internal Service Discovery
+- Use internal DNS zone (e.g., `service.internal`).
+- SRV records provide port discovery alongside host.
+- Short TTL (5-15s) for dynamic service registration.
+
+### SRV Records
+```
+_http._tcp.api.internal. 15 IN SRV 10 100 8080 api-pod-1.internal.
+_http._tcp.api.internal. 15 IN SRV 10 100 8080 api-pod-2.internal.
+```
+
+### Kubernetes DNS
+- Service discovery built-in: `service-name.namespace.svc.cluster.local`.
+- Headless services return individual pod IPs.
+- ExternalName services alias external endpoints.
+
+## Anycast DNS
+
+### How It Works
+- Multiple servers advertise the same IP address via BGP.
+- Network routes traffic to the nearest server (by BGP path).
+- If one server goes down, BGP re-routes to next nearest.
+
+### Use Cases
+- Authoritative DNS servers (Cloudflare, Route53).
+- CDN edge nodes.
+- DDoS mitigation (absorb attack across multiple PoPs).
+
+### Considerations
+- Failover speed depends on BGP convergence (seconds to minutes).
+- TCP connections break on route change (DNS is UDP, so usually fine).
+- Not suitable for stateful protocols without session persistence.
+
+## Health Checks
+
+### DNS Health Check Pattern
+1. Health checker probes endpoints at regular intervals (10-30s).
+2. If endpoint fails N consecutive checks, remove from DNS response.
+3. Continue probing. If endpoint recovers, add back after M consecutive successes.
+4. Removal takes effect within TTL seconds (resolver cache expiry).
+
+### Health Check Types
+| Type | Checks | Use For |
+|------|--------|---------|
+| TCP | Port open | Basic availability |
+| HTTP | Status 200 + body match | Application health |
+| HTTPS | Valid cert + status | Full stack health |
+| Custom | Business logic probe | Application-specific |
+
+### Timing
+- Check interval: 10-30 seconds.
+- Failure threshold: 2-3 consecutive failures.
+- Recovery threshold: 2-3 consecutive successes.
+- Effective failover time: check_interval × failure_threshold + TTL.
+
+## Self-check
+- [ ] TTL set appropriate to failover speed requirement.
+- [ ] Health checks configured for all DNS-managed endpoints.
+- [ ] Failover tested end-to-end (measured recovery time).
+- [ ] GeoDNS verified from target regions.
+- [ ] Secondary DNS provider configured for resilience.
+- [ ] Propagation delays documented in runbook.
+- [ ] Client-side DNS caching behavior accounted for.
+- [ ] Monitoring in place for resolution latency and errors.

package/.mindforge/skills/ecommerce-architecture/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ecommerce-architecture
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: ecommerce architecture, shopping cart design, checkout flow optimization, inventory management system, pricing engine, order lifecycle management, marketplace architecture, product catalog design, ecommerce platform, fulfillment system, order routing, dynamic pricing
+compose: caching-strategies
+---
+
+# Skill — Ecommerce Architecture
+
+## When this skill activates
+This skill activates when designing shopping cart flows, checkout experiences, inventory management systems, pricing engines, order lifecycle workflows, product catalog architectures, marketplace platforms, or fulfillment/logistics systems for ecommerce.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design cart and checkout state machine: anonymous cart → logged-in cart (merge/replace strategy), cart → checkout (address validation), checkout → payment → order confirmation, with explicit timeout handling for abandoned carts (30 min session, 7 day recovery email)
+2. Model inventory architecture: real-time available-to-promise (ATP) calculation across warehouses, reserved inventory during checkout (soft hold 15 min, hard hold at payment), backorder handling, and oversell prevention with pessimistic locking
+3. Map order lifecycle stages: order placed → payment authorized → fraud screening → fulfillment assigned → picked → packed → shipped → delivered → returns window, with event-driven state transitions and webhook notifications at each stage
+
+### During implementation
+- Implement cart persistence with multi-device sync: store cart in database (not just sessions), deduplicate items by SKU+options hash, handle quantity updates with stock validation, expire abandoned carts after 30 days, support guest cart migration to user account on login
+- Build pricing engine with rule evaluation: base price → promotional discounts (BOGO, percentage off, fixed amount) → coupon codes (stackable/non-stackable) → volume discounts → tax calculation (Avalara/TaxJar API), with price display consistency (cart/checkout/confirmation must match)
+- Design inventory reservation system: when checkout starts, create soft reservation (pessimistic lock), release on timeout or explicit cancel, convert to hard reservation on payment success, allocate to specific warehouse based on proximity to shipping address and stock availability
+- Implement order routing logic: evaluate fulfillment options (ship from warehouse, dropship from vendor, ship from store), calculate shipping cost and delivery ETA per option, optimize for cost vs speed vs carbon footprint, handle split shipments when inventory spans locations
+- Build product catalog with faceted search: index products in Elasticsearch/Algolia with attributes (category, brand, color, size, price), support filters (multi-select facets), range queries (price slider), text search with typo tolerance, and sort options (relevance, price, rating, recency)
+
+### After implementation
+- Validate checkout flow conversion: measure cart abandonment rate by stage (cart → checkout → payment → confirmation), identify friction points (shipping cost surprise, account creation forced, payment failure), implement address autocomplete (Google Places API), express checkout options (Apple Pay, Shop Pay)
+- Test inventory consistency under load: simulate concurrent purchases of last item in stock (race condition), verify oversell prevention, validate soft reservation expiry releases inventory back to available pool, confirm hard reservation deducts from ATP correctly
+- Execute fraud screening integration: verify address verification system (AVS) checks, CVV validation, velocity checks (too many orders from same IP/card), device fingerprinting (Sift/Forter), manual review queue for high-risk orders
+
+## Self-check before task completion
+- [ ] Cart supports guest and logged-in users, syncs across devices, handles item updates with real-time stock validation
+- [ ] Pricing engine evaluates all discount layers (promotions → coupons → volume → tax) with consistent display across cart/checkout/confirmation
+- [ ] Inventory reservation implemented: soft hold during checkout (15 min timeout), hard hold post-payment, pessimistic locking prevents oversell
+- [ ] Checkout flow optimized: address autocomplete, saved payment methods, express checkout options (Apple Pay), progress indicator
+- [ ] Order lifecycle event-driven: state machine with webhook notifications (order placed, shipped, delivered), customer email templates
+- [ ] Product catalog searchable: faceted filters, text search with typo tolerance, sort options, pagination or infinite scroll
+- [ ] Fraud screening integrated: AVS/CVV checks, velocity limits, device fingerprinting, manual review queue for high-risk transactions

package/.mindforge/skills/edge-computing/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: edge-computing
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: edge computing, edge function, CDN compute, edge worker, latency optimization, data locality, edge caching, cloudflare workers, deno deploy, edge runtime, compute at edge, edge-first architecture
+---
+
+# Skill — Edge Computing
+
+## When this skill activates
+Any task involving moving computation closer to users at the network edge,
+designing edge functions, optimizing latency through geographic distribution,
+or evaluating edge vs origin placement decisions.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify latency-sensitive paths that benefit from edge execution.
+2. Decide edge vs origin for each operation using the decision matrix:
+   - Latency-sensitive reads → edge
+   - Data-heavy computation → origin
+   - Personalization with small state → edge
+   - Writes requiring strong consistency → origin
+3. Document runtime constraints (time limits, memory, bundle size).
+
+### During implementation
+- Keep edge function bundles small (<1MB) to minimize cold starts.
+- Avoid heavy imports — each dependency adds cold start latency.
+- Use stale-while-revalidate for cache coordination.
+- Handle edge-to-origin fallback gracefully.
+- Never rely on persistent connections at edge (stateless by design).
+- Implement proper cache-control headers at every layer.
+
+### After implementation
+- Measure actual latency improvement from edge deployment.
+- Verify data locality compliance (GDPR region constraints).
+- Test cold start performance under real traffic patterns.
+- Monitor edge function error rates per region.
+
+## Edge vs Origin Decision Framework
+
+| Signal | Edge | Origin |
+|--------|------|--------|
+| Latency-critical (<50ms target) | Yes | No |
+| Heavy computation (>50ms CPU) | No | Yes |
+| Personalization (small state) | Yes | No |
+| Database writes | No | Yes |
+| Static asset serving | Yes | No |
+| Auth token validation | Yes | No |
+| Complex business logic | No | Yes |
+
+## Platform Patterns
+
+### Cloudflare Workers
+- V8 isolate model (no container cold start).
+- KV for eventual-consistent edge state.
+- Durable Objects for strong consistency at edge.
+- R2 for edge-local object storage.
+
+### Vercel Edge Functions
+- Runs on Cloudflare infrastructure.
+- Streaming responses supported.
+- Middleware pattern for auth/redirects.
+
+### Deno Deploy
+- Global V8 isolates with zero cold start.
+- Built-in KV for edge state.
+- Native Web APIs (fetch, streams, crypto).
+
+## Caching Strategy at Edge
+- `Cache-Control: public, max-age=60, stale-while-revalidate=300` for dynamic content.
+- `Cache-Control: public, max-age=31536000, immutable` for hashed static assets.
+- Purge on deploy for cache invalidation.
+- Use cache tags for granular invalidation.
+
+## Limitations to Always Consider
+- Time limits (typically 30s-50ms CPU time depending on platform).
+- Memory limits (128MB typical).
+- No persistent connections (WebSocket requires special handling).
+- Bundle size constraints (1-10MB depending on platform).
+- Limited Node.js API compatibility at edge.
+- Eventual consistency for distributed edge state.
+
+## Self-check
+- [ ] Edge vs origin decision documented for each function.
+- [ ] Cold start measured and acceptable (<50ms target).
+- [ ] Bundle size within platform limits.
+- [ ] Fallback to origin implemented for edge failures.
+- [ ] Data locality compliant with regulatory requirements.
+- [ ] Cache headers set correctly at every layer.

package/.mindforge/skills/edtech-platform/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: edtech-platform
+version: 1.0.0
+min_mindforge_version: 10.2.0
+status: stable
+triggers: edtech platform, learning management system, adaptive learning algorithm, assessment engine, educational content delivery, student progress tracking, course management, LMS architecture, online learning platform, competency framework, learning path design, educational analytics
+---
+
+# Skill — EdTech Platform
+
+## When this skill activates
+This skill activates when building learning management systems (LMS), adaptive learning algorithms, assessment/quiz engines, course content delivery platforms, student progress tracking, competency frameworks, learning path recommendations, or educational analytics dashboards.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Design learning object model: courses → modules → lessons → activities (video, reading, quiz, assignment), with prerequisite dependencies (DAG validation), completion criteria per activity type (watch 80% of video, pass quiz with 70%, submit assignment), and progress rollup to course level
+2. Model assessment engine: question bank with metadata (difficulty, topic tags, bloom's taxonomy level), quiz generation (random selection from pool, fixed seed for consistency), scoring rubrics (multiple choice auto-grade, short answer manual review, peer assessment), and partial credit support
+3. Map adaptive learning logic: knowledge graph (concepts and prerequisite relationships), learner profiling (mastery level per concept, learning velocity, preferred modalities), content recommendation (serve easier/harder content based on performance), and remediation paths (loop back to foundational concepts on failure)
+
+### During implementation
+- Implement content delivery with engagement tracking: video player with playback position persistence (resume from last position), event logging (play, pause, seek, speed change, completion), transcripts with search, captions in multiple languages, quality selection (adaptive bitrate for mobile), and download for offline access
+- Build assessment engine with anti-cheating measures: randomize question order, shuffle answer choices, time limits per question, lockdown browser detection (fullscreen enforcement, tab switch detection), plagiarism detection (Turnitin API, cosine similarity for text), and proctoring integration (webcam monitoring, eye tracking)
+- Design progress tracking with granular analytics: store activity completion events (user_id, activity_id, timestamp, score, time_spent), aggregate to module/course level, calculate metrics (completion rate, average score, time to completion), identify at-risk students (falling behind pace, multiple failed attempts), trigger interventions (reminder emails, instructor notifications)
+- Implement competency-based progression: define competencies with proficiency levels (novice, intermediate, advanced, expert), map learning activities to competencies, assess mastery through multiple evidence points (quiz scores, assignment grades, peer reviews), unlock next level only when threshold met (80% proficiency)
+- Build discussion forums with moderation: threaded conversations, upvote/downvote, instructor endorsements, tag filtering (question, announcement, discussion), spam detection (rate limiting, keyword filters, ML-based flagging), and content moderation queue
+
+### After implementation
+- Validate learning analytics accuracy: verify completion tracking (activity marked complete only when criteria met), score calculation (weighted averages for modules/courses), progress rollup (course progress reflects all module progress), and leaderboard consistency (rank students by total points, handle ties)
+- Test adaptive learning effectiveness: measure learning velocity (time to achieve 80% mastery per concept), retention rate (re-test after 1 week), engagement metrics (video watch time, quiz attempts, forum participation), compare adaptive vs linear paths (A/B test for cohort outcomes)
+- Execute accessibility compliance audit: WCAG 2.1 AA conformance (video captions, keyboard navigation, screen reader support), alternative formats (transcripts, audio descriptions), color contrast checks (4.5:1 for text), and assistive technology testing (NVDA, JAWS)
+
+## Self-check before task completion
+- [ ] Learning object hierarchy implemented: courses → modules → lessons → activities with prerequisite enforcement (DAG validation)
+- [ ] Content delivery tracks engagement: video playback position, event logs, transcript search, adaptive bitrate, offline download
+- [ ] Assessment engine supports multiple question types: multiple choice, short answer, essay, peer assessment, with auto-grading and manual review workflows
+- [ ] Anti-cheating measures active: randomized questions, time limits, lockdown browser, plagiarism detection, proctoring integration
+- [ ] Progress tracking granular: activity-level completion events, aggregate metrics at module/course level, at-risk student identification
+- [ ] Adaptive learning functional: knowledge graph, learner profiling, content recommendation based on mastery, remediation paths
+- [ ] Competency-based progression: proficiency levels, evidence-based mastery assessment, unlock gates for next level
+- [ ] Accessibility compliant: WCAG 2.1 AA (captions, keyboard nav, screen reader), alternative formats, color contrast

package/.mindforge/skills/email-deliverability/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: email-deliverability
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: email deliverability, SPF record, DKIM signing, DMARC policy, email warm-up, sender reputation, bounce handling, complaint loop, email authentication, inbox placement, email throttling, transactional email architecture
+---
+
+# Skill — Email Deliverability (Authentication & Reputation Architecture)
+
+## When this skill activates
+When configuring email sending infrastructure, troubleshooting delivery issues,
+warming up new sending domains/IPs, or architecting transactional vs marketing
+email separation. Use for any task that affects whether emails reach the inbox.
+
+Core principle: **Reputation is everything** — email deliverability is a long game.
+One bad send can destroy months of reputation building. Protect sender reputation
+like you protect production uptime.
+
+## Mandatory actions when this skill is active
+
+### Email Authentication Trio (Non-Negotiable)
+
+1. **SPF (Sender Policy Framework):**
+   ```dns
+   ; Authorize sending IPs/services
+   v=spf1 include:_spf.google.com include:sendgrid.net include:amazonses.com -all
+   ```
+
+   Rules:
+   - List ALL authorized sending services (ESP, transactional provider, corporate mail)
+   - End with `-all` (hard fail) not `~all` (soft fail) for production domains
+   - Maximum 10 DNS lookups (SPF limit) — use `include` sparingly
+   - Audit quarterly: remove services you no longer use
+   - Never authorize `+all` (allows anyone to send as you)
+
+2. **DKIM (DomainKeys Identified Mail):**
+   ```dns
+   ; Public key for signature verification
+   selector1._domainkey.example.com IN TXT "v=DKIM1; k=rsa; p=[public_key]"
+   ```
+
+   Rules:
+   - Every sending service gets its own DKIM selector
+   - Minimum 2048-bit RSA key (1024-bit is deprecated)
+   - Rotate keys annually (publish new key, wait 48h, remove old)
+   - Sign with your own domain (not the ESP's domain) for reputation ownership
+   - Verify signatures are passing: check DKIM alignment in email headers
+
+3. **DMARC (Domain-based Message Authentication, Reporting & Conformance):**
+   ```dns
+   ; Tell receivers what to do with failures
+   _dmarc.example.com IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com; ruf=mailto:dmarc-forensic@example.com; pct=100"
+   ```
+
+   Deployment progression:
+   ```
+   Week 1-2: p=none (monitor only, collect reports)
+   Week 3-4: p=quarantine; pct=10 (quarantine 10% of failures)
+   Week 5-6: p=quarantine; pct=50
+   Week 7-8: p=quarantine; pct=100
+   Week 9+:  p=reject (full enforcement — unauthenticated mail rejected)
+   ```
+
+   Rules:
+   - ALWAYS start at p=none and progress gradually
+   - Monitor DMARC reports (rua) weekly for legitimate sending you missed
+   - Goal state: p=reject (maximum protection against spoofing)
+   - Ensure both SPF and DKIM alignment pass (DMARC requires at least one)
+
+### IP/Domain Warm-Up
+
+4. **Warm-up schedule for new sending infrastructure:**
+   ```
+   Day 1-3:    50 emails/day (to most engaged recipients only)
+   Day 4-7:    100 emails/day
+   Week 2:     200-500/day
+   Week 3:     500-1,000/day
+   Week 4:     1,000-5,000/day
+   Week 5:     5,000-10,000/day
+   Week 6+:    Increase 2x per week until target volume
+   ```
+
+   Rules:
+   - Send to MOST ENGAGED recipients first (opened/clicked in last 30 days)
+   - Monitor bounce rate after each volume increase (must stay <2%)
+   - If bounce rate spikes: stop, investigate, reduce volume
+   - Warm-up separately for each mailbox provider (Gmail, Outlook, Yahoo)
+   - Transactional and marketing should warm up independently
+   - Warm-up takes 6-8 weeks minimum — no shortcuts
+
+### Sender Reputation Monitoring
+
+5. **Key metrics and thresholds:**
+   ```
+   | Metric               | Healthy    | Warning    | Critical   |
+   |----------------------|------------|------------|------------|
+   | Bounce rate          | <1%        | 1-2%       | >2%        |
+   | Complaint rate       | <0.05%     | 0.05-0.1%  | >0.1%      |
+   | Open rate            | >20%       | 10-20%     | <10%       |
+   | Spam trap hits       | 0          | 1-2/month  | >2/month   |
+   | Blacklist presence   | None       | 1 minor    | Major list |
+   ```
+
+   Actions:
+   - Warning threshold: investigate root cause, adjust sending patterns
+   - Critical threshold: STOP marketing sends immediately, fix before resuming
+   - Monitor Google Postmaster Tools, Microsoft SNDS, Yahoo FBL daily
+   - Set up alerts for threshold crossings
+
+### Bounce Handling
+
+6. **Bounce classification and response:**
+   ```
+   Hard bounce (permanent failure):
+   - Invalid address, domain doesn't exist, mailbox doesn't exist
+   - Action: Remove from list IMMEDIATELY (first occurrence)
+   - Never retry a hard bounce
+
+   Soft bounce (temporary failure):
+   - Mailbox full, server temporarily unavailable, message too large
+   - Action: Retry up to 3 times over 72 hours
+   - After 3 soft bounces on same address: treat as hard bounce and suppress
+
+   Complaint (user clicked "spam"):
+   - Action: Suppress IMMEDIATELY, never email again
+   - Process FBL (Feedback Loop) reports within 1 hour
+   - If complaint rate rises: review recent sends for consent issues
+   ```
+
+### List Hygiene
+
+7. **Ongoing list maintenance:**
+   ```
+   - Remove hard bounces: immediately
+   - Suppress complaints: immediately
+   - Remove unengaged: no open/click in 90 days → sunset sequence → remove
+   - Validate on signup: real-time email validation API (catch typos, disposable domains)
+   - Re-validate periodically: quarterly bulk validation of full list
+   - Double opt-in: recommended for all marketing (required in some jurisdictions)
+   ```
+
+### Architecture (Transactional vs Marketing Separation)
+
+8. **Separate sending infrastructure:**
+   ```
+   Transactional email (receipts, password resets, 2FA):
+   - Dedicated IP/subdomain: mail.example.com
+   - Priority: immediate delivery (no batching)
+   - Volume: consistent, predictable
+   - Reputation: protected (never mixed with marketing)
+
+   Marketing email (newsletters, promotions, re-engagement):
+   - Dedicated IP/subdomain: news.example.com
+   - Priority: send-time optimized (batch by timezone/engagement)
+   - Volume: variable, seasonal spikes
+   - Reputation: more volatile (isolated from transactional)
+   ```
+
+   Rules:
+   - NEVER share IPs between transactional and marketing
+   - Transactional emails must not contain marketing content (CAN-SPAM)
+   - If marketing reputation degrades, transactional delivery is unaffected
+   - Use subdomain separation (not just IP) for domain reputation isolation
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Are SPF, DKIM, and DMARC all configured and passing alignment?
+- [ ] Is DMARC at p=quarantine or p=reject (not indefinitely at p=none)?
+- [ ] Is there a warm-up plan for any new IPs/domains (starting at 50/day)?
+- [ ] Are bounce rate (<2%) and complaint rate (<0.1%) being monitored with alerts?
+- [ ] Are hard bounces removed immediately and complaints suppressed?
+- [ ] Is transactional email on a separate IP/subdomain from marketing?
+- [ ] Is there a sunset policy for unengaged recipients (90-day inactivity)?
+- [ ] Are real-time email validation and double opt-in implemented for new signups?