mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/context-engineering/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: context-engineering
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: context engineering, context window management, context token budget, context priority ordering, compaction strategy, context freshness, context allocation, what to include in context, context optimization strategy, retrieval augmentation design, context pruning, context budget allocation
+---
+
+# Context Engineering
+
+## When this skill activates
+
+This skill activates when designing what information to feed into an LLM context window, how to prioritize it, and how to manage context across long-running sessions or multi-turn conversations. It applies to system prompt design, RAG pipeline tuning, agent memory management, and any scenario where token budget allocation determines output quality.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Measure the budget** — Determine the total context window size for the target model. Subtract the expected output length. The remainder is your input budget.
+2. **Identify the task** — Classify the task type (code generation, analysis, Q&A, creative). Different tasks require different context compositions.
+3. **Inventory available context** — List all potential context sources: files, conversation history, retrieved documents, instructions, examples, metadata.
+4. **Assess current context health** — If modifying an existing system, measure current context utilization. Identify waste (irrelevant content consuming tokens).
+
+### During
+
+#### What to Include vs Exclude
+
+**Include (high signal):**
+- Task-relevant source code (the files being modified or referenced)
+- Explicit constraints and requirements
+- Relevant examples demonstrating desired behavior
+- Error messages and stack traces when debugging
+- Schema definitions and type signatures
+- User preferences and project conventions
+
+**Exclude (low signal, high cost):**
+- Irrelevant conversation history from earlier turns
+- Verbose log output (summarize instead)
+- Unrelated files that happen to be nearby
+- Redundant information already stated elsewhere
+- Boilerplate code that follows obvious patterns
+- Full file contents when only a function is relevant
+
+#### Priority Ordering (Attention Distribution)
+
+- **Position 1 (highest attention): Instructions and constraints** — System prompts, role definitions, mandatory rules. Models attend most strongly to the beginning and end of context.
+- **Position 2: Task-specific content** — The code, document, or data being directly worked on.
+- **Position 3: Examples and references** — Few-shot examples, related patterns, documentation excerpts.
+- **Position 4: Background context** — Project structure, historical decisions, tangential information.
+- **Recency bias** — Models attend more to recent content. Place the most critical dynamic content last (just before the query).
+- **Primacy effect** — System instructions at the very start receive elevated attention. Never bury critical rules in the middle.
+
+#### Token Budget Allocation Framework
+
+| Category | Allocation | Purpose |
+|----------|-----------|---------|
+| Task-relevant content | 60% | Code, data, documents being worked on |
+| Constraints and instructions | 20% | Rules, format requirements, boundaries |
+| Examples | 10% | Few-shot demonstrations, reference patterns |
+| Meta and buffer | 10% | Conversation scaffolding, safety margin |
+
+- **Adapt per task** — Code generation: increase task-relevant to 70%, reduce examples to 5%. Creative tasks: increase examples to 20%.
+- **Never fill 100%** — Leave 10-15% buffer for the model's response and unexpected context needs.
+- **Track token counts** — Use tokenizer libraries (tiktoken, Anthropic tokenizer) to measure precisely. Estimates drift.
+
+#### Compaction Strategy
+
+- **Summarize old context** — Replace verbose conversation history with structured summaries. Keep decisions and outcomes; discard deliberation.
+- **Keep recent verbatim** — The last 2-3 turns should remain uncompacted. Recent context drives current behavior.
+- **Progressive summarization** — As context ages: verbatim (0-2 turns) → detailed summary (3-10 turns) → bullet points (10+ turns) → drop entirely.
+- **Checkpoint key decisions** — Extract and preserve: architectural decisions, user preferences, constraints discovered mid-conversation. These never compact.
+- **Lossy is acceptable** — Perfect recall is not the goal. Relevant recall is. Aggressively prune low-value history.
+
+#### Context Freshness
+
+- **Re-read files before acting** — Never rely on file content from earlier in the conversation if the file may have changed. Always re-read.
+- **Invalidate on mutation** — After any write operation, treat previously-read versions of affected files as stale.
+- **Timestamp awareness** — When including retrieved documents, note their freshness. Flag content older than the relevance threshold.
+- **Session drift** — Long sessions accumulate stale assumptions. Periodically re-ground by re-reading source-of-truth files.
+
+#### RAG Integration (Retrieval Augmented Generation)
+
+- **Chunk size** — 500-1000 tokens per chunk for code; 200-500 for prose. Smaller chunks = more precise retrieval but less surrounding context.
+- **Retrieve selectively** — Max 3-5 chunks (3-5K tokens total). More retrieved content dilutes attention on each piece.
+- **Relevance threshold** — Set a similarity score cutoff. Irrelevant retrieved content is worse than no retrieval.
+- **Cite sources** — Always attribute retrieved content to its source. This helps the model (and user) assess reliability.
+- **Hybrid search** — Combine semantic (embedding) search with keyword (BM25) search. Neither alone is sufficient.
+- **Re-ranking** — Apply a cross-encoder re-ranker after initial retrieval to improve precision before injection.
+
+#### Context Pruning Techniques
+
+- **Sliding window** — Drop oldest turns when approaching limits. Simple but lossy.
+- **Relevance scoring** — Score each context block against the current query. Drop lowest-scoring blocks first.
+- **Deduplication** — Detect and merge repeated information. Common in multi-turn conversations.
+- **Structural pruning** — Remove comments, whitespace, and formatting from code context. Preserve semantics, reduce tokens.
+- **Selective inclusion** — For large files, include only the relevant functions/classes, not the entire file.
+
+### After
+
+1. **Measure utilization** — Calculate what percentage of context was actually relevant to the output. Target >70% relevance.
+2. **Evaluate output quality** — Compare outputs with full context vs pruned context. If quality is maintained, the pruning strategy is sound.
+3. **Document the strategy** — Record the context composition pattern for this use case so it can be replicated and improved.
+4. **Monitor drift** — Track context composition over time. If quality degrades, context may have drifted from optimal allocation.
+
+## Self-check before task completion
+
+- [ ] Token budget is explicitly allocated across categories
+- [ ] Instructions and constraints occupy the highest-attention positions (start and end)
+- [ ] No irrelevant content consuming tokens (verbose logs, unrelated files, redundant info)
+- [ ] Compaction strategy handles long conversations without losing key decisions
+- [ ] File content is fresh (re-read if potentially stale)
+- [ ] RAG retrieval is limited to 3-5 relevant chunks with similarity threshold
+- [ ] At least 10% token buffer remains for response generation
+- [ ] Context composition is documented and reproducible

package/.mindforge/skills/continuous-learning/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: continuous-learning
+version: 1.0.0
+min_mindforge_version: 10.0.3
+status: stable
+triggers: instinct, learned behavior, pattern detection, evolve, auto-learn, skill promotion, confidence, observation, habit, adaptation
+---
+
+# Skill — Continuous Learning
+
+## When this skill activates
+When discussing learned behaviors, instinct management, pattern capture,
+or skill evolution. Also activates during session-end reviews where patterns
+may be captured.
+
+## Mandatory actions when this skill is active
+
+### Understanding the Instinct System
+MindForge automatically observes sessions and captures behavioral patterns as
+"instincts" — lightweight learned behaviors that may evolve into full skills.
+
+**Instinct lifecycle:**
+```
+Observation -> Instinct (confidence: 0.5)
+                  | applied successfully
+              Confidence grows (0.5 -> 0.6 -> 0.7 -> ...)
+                  | confidence >= 0.85 AND applied 5+ times
+              Promotion candidate
+                  | user approves
+              Full SKILL.md created and registered
+```
+
+### Auto-Capture (Always Active)
+The instinct engine runs in auto-capture mode, watching for:
+
+1. **User corrections** -> instinct created at confidence 0.6
+   - "No, always use X instead of Y" -> captures the preference
+2. **Repeated patterns (3+)** -> instinct created at confidence 0.4
+   - Same action pattern 3 times in a session -> probably intentional
+3. **Successful outcomes** -> instinct created at confidence 0.5
+   - Non-obvious action followed by verification pass -> worth remembering
+
+### Managing Instincts
+
+**View active instincts:**
+- Check `.mindforge/engine/instincts/instinct-store.jsonl`
+- Use `/mindforge:status` which includes instinct summary
+
+**Manually capture:**
+- Use `/mindforge:learn-instinct "observation" --behavior "what to do"`
+- Manual instincts start at confidence 0.7 (user-stated = higher trust)
+
+**Promote to skills:**
+- Use `/mindforge:evolve-skills` to review mature instincts
+- Candidates: confidence >= 0.85 AND times_applied >= 5
+- Promotion creates a full SKILL.md and registers in MANIFEST.md
+
+**Deprecate/Prune:**
+- Instincts below 0.2 confidence after 10+ applications are auto-pruned
+- Instincts inactive for 30 days are auto-pruned
+- User can manually deprecate any instinct
+
+### During any task (passive observation)
+- Note patterns that repeat across tasks
+- When user corrects behavior: acknowledge and create instinct
+- At session end: report any new instincts captured
+- Never let instinct count exceed 100 per project (prune lowest confidence)
+
+### After session
+Report instinct activity:
+```
+Instincts this session:
+  [NEW] "Pattern observed" (confidence: 0.5)
+  [REINFORCED] "Existing pattern" (0.6 -> 0.7)
+  [READY] "Mature pattern" -- eligible for promotion
+  
+Active: 47/100 | Promotion candidates: 3
+```
+
+## Self-check before task completion
+- [ ] Did I report any new instincts captured this session?
+- [ ] Did I verify instinct count remains under 100 for this project?
+- [ ] Did I check for promotion candidates meeting the threshold?
+- [ ] Did I confirm captured instincts are project-scoped (not leaking to other projects)?

package/.mindforge/skills/contract-testing/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: contract-testing
+version: 1.0.0
+min_mindforge_version: 10.0.8
+status: stable
+triggers: contract testing, consumer driven contract, pact testing, provider verification, contract broker, schema compatibility, contract first, api contract test, consumer contract, provider contract, contract breaking, bilateral contract
+compose: testing-standards
+---
+
+# Contract Testing
+
+## When this skill activates
+
+This skill activates when working with API contract verification between services, consumer-driven contract workflows, schema compatibility checks, or any task involving service boundary agreements. It applies to both synchronous (HTTP/gRPC) and asynchronous (message queue) contracts.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. Identify all parties in the contract relationship (consumers and providers).
+2. Determine the contract format in use (Pact, OpenAPI, AsyncAPI, Protobuf).
+3. Check if a contract broker is already configured (Pactflow, Pact Broker, custom).
+4. Review existing contracts for the affected endpoints or messages.
+5. Confirm the environment supports contract verification (CI pipeline, broker access).
+
+### During
+
+**Consumer-Driven Contract Workflow:**
+- Consumers define the interactions they require (request/response pairs).
+- Consumer tests generate contract files (pact files, schemas).
+- Contracts are published to a broker with version metadata.
+- Providers pull contracts and verify they satisfy all consumer expectations.
+- Verification results are published back to the broker.
+
+**Schema Compatibility Levels:**
+- **Backward compatible**: New schema can read data written by old schema.
+- **Forward compatible**: Old schema can read data written by new schema.
+- **Full compatible**: Both backward and forward (safest for production).
+- Always validate compatibility BEFORE deploying schema changes.
+
+**Breaking Change Detection:**
+- Removing a field consumers depend on = BREAKING.
+- Changing a field type or format = BREAKING.
+- Adding a required field to a request = BREAKING for providers.
+- Adding an optional field = SAFE (backward compatible).
+- Run `can-i-deploy` checks in CI to gate deployments.
+
+**Contract Broker Practices:**
+- Tag contracts with environment names (dev, staging, prod).
+- Use semantic versioning for contract participants.
+- Enable webhook notifications on verification failures.
+- Maintain contract history for rollback capability.
+
+**Pact-Specific Workflow:**
+1. Write consumer test using Pact DSL (define interaction).
+2. Run consumer test to generate `.pact` JSON file.
+3. Publish pact to broker with consumer version.
+4. Provider runs verification against all registered consumer pacts.
+5. Provider publishes verification result to broker.
+6. CI runs `can-i-deploy` before any deployment proceeds.
+
+**CI Integration:**
+- Consumer pipeline: test → generate pact → publish → trigger provider verification.
+- Provider pipeline: pull pacts → verify → publish result → deploy if green.
+- Use pending pacts for new consumers (failures don't block provider).
+- Use WIP pacts for contracts not yet verified on provider's main branch.
+
+### After
+
+1. All contracts are published to the broker with correct version tags.
+2. Verification results are recorded for both consumer and provider.
+3. `can-i-deploy` passes for the target environment.
+4. Breaking changes are flagged and communicated to affected teams.
+5. Contract coverage includes all critical interactions (not just happy paths).
+
+## Self-check before task completion
+
+- [ ] Consumer tests define the minimal required interaction (no over-specification).
+- [ ] Provider verification runs against ALL registered consumer contracts.
+- [ ] Schema changes are validated for the correct compatibility level.
+- [ ] Breaking changes have been identified and a migration plan exists.
+- [ ] Contract broker has up-to-date versions for all participants.
+- [ ] CI pipeline gates deployment on `can-i-deploy` result.
+- [ ] Error scenarios and edge cases are covered in contracts (not just 200 responses).
+- [ ] Contract tests run in isolation (no network calls, no shared state).

package/.mindforge/skills/cost-aware-routing/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cost-aware-routing
+version: 1.0.0
+min_mindforge_version: 10.0.3
+status: stable
+triggers: token budget, model routing, cost optimization, model selection, Haiku, Flash, cheap model, expensive model, cost per token, budget, spend, token usage
+---
+
+# Skill — Cost-Aware Routing
+
+## When this skill activates
+When making model selection decisions, monitoring token spend, optimizing
+for cost-performance tradeoffs, or when budget limits are approaching.
+
+## Mandatory actions when this skill is active
+
+### Model Tier Reference
+
+| Tier | Model | Input/Output per 1M | Best For |
+|------|-------|--------------------:|----------|
+| simple | claude-haiku-4-5 | $0.25 / $1.25 | File reads, simple edits, formatting |
+| standard | claude-sonnet-4-6 | $3 / $15 | Multi-file work, code review, daily tasks |
+| complex | claude-opus-4-7 | $15 / $75 | Architecture, security, hard debugging |
+| research | gemini-2.5-pro | $1.25 / $10 | Web research, long context, synthesis |
+| consult | gpt-4o | $2.50 / $10 | Second opinions, alternative perspectives |
+
+### Routing Rules
+
+**Match task complexity to model tier:**
+- Difficulty 1-3 (single file, obvious change): **simple**
+- Difficulty 3-6 (multi-file, some judgment): **standard**
+- Difficulty 6-8 (cross-system, complex logic): **complex**
+- Difficulty 8-10 (architectural, novel problems): **complex**
+
+**Override rules (always apply):**
+- Security tasks: minimum **standard** (never use simple for auth/payment)
+- Architecture decisions: minimum **complex**
+- File exploration/reading: always **simple**
+- Research requiring web access: **research**
+
+### Cost Optimization Patterns
+
+1. **Start cheap, escalate if needed:**
+   - Try simple tier first for uncertain-complexity tasks
+   - If result quality is insufficient: escalate to next tier
+   - Log escalation with reason
+
+2. **Batch similar tasks:**
+   - 5 simple edits in one call < 5 separate calls
+   - Group related file reads into single exploration
+
+3. **Cache aggressively:**
+   - Prompt caching reduces input costs ~90%
+   - Structure prompts with static context first (cacheable)
+   - Dynamic content last (not cached, but small)
+
+4. **Avoid token waste:**
+   - Don't re-read files already in context
+   - Don't repeat instructions the model already has
+   - Use compaction when context grows large
+
+### Budget Monitoring
+
+Check budget status regularly:
+- Session budget remaining: from token-ledger.jsonl
+- Warning threshold: `[COST_WARN_USD]` from config
+- Hard limit: `[COST_HARD_LIMIT_USD]` from config
+
+**When budget is tight:**
+- Downgrade all tasks one tier (complex→standard, standard→simple)
+- Warn user: "Budget at X% — operating in economy mode"
+- Never exceed hard limit without explicit user approval
+
+### After any task
+- Log actual model used + tokens consumed to token-ledger.jsonl
+- Compare actual vs optimal tier (for future routing accuracy)
+- Report cost in session summary
+
+## Self-check before task completion
+- [ ] Did I log the model routing decision with rationale?
+- [ ] Did I record actual token usage in token-ledger.jsonl?
+- [ ] Did I check remaining budget against session/project limits?
+- [ ] Did I flag any tasks where a cheaper model could have been used?

package/.mindforge/skills/cost-estimation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: cost-estimation
+version: 1.0.0
+min_mindforge_version: 10.0.9
+status: stable
+triggers: cost estimation, cloud cost modeling, finops, reserved instance, spot instance, cost forecast, infrastructure cost, cost per request, pricing model, cost optimization plan, resource right-sizing, cost allocation
+---
+
+# Skill — Cost Estimation
+
+## When this skill activates
+Any task involving cloud cost modeling, FinOps, instance strategy selection,
+cost forecasting, per-request cost analysis, right-sizing, or cost allocation.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Estimate costs BEFORE building: compute + storage + network + managed services.
+2. Identify cost-dominant components (usually storage or network egress).
+3. Define budget constraints and alerting thresholds.
+
+### During implementation
+- Choose instances based on workload profile (compute/memory/IO bound).
+- Implement resource tagging for cost allocation from day one.
+- Use auto-scaling with min/max bounds.
+- Prefer managed services when ops cost exceeds infrastructure savings.
+
+### After implementation
+- Set cost alerts at 50%, 80%, 100% of budget.
+- Create per-service cost dashboard.
+- Schedule monthly cost review for drift and optimization.
+
+## FinOps Phases
+
+- **Inform**: tag all resources, build dashboards, implement showback/chargeback.
+- **Optimize**: right-size, reserve steady workloads, spot for batch, eliminate waste.
+- **Operate**: automate (scheduled scaling, auto-stop dev), embed cost in PR review.
+
+## Cost Modeling
+
+```
+Monthly = Compute + Storage + Network + Managed + Support
+Compute: instances * hours * $/hour
+Storage: GB * $/GB + IOPS * $/IOP
+Network: GB egress * $/GB (ingress usually free)
+Cost/Request: total_monthly / total_requests
+```
+
+## Instance Strategy
+
+| Type | Discount | Use For | Never For |
+|------|----------|---------|-----------|
+| On-Demand | 0% | Variable, dev, testing | Steady production (wasteful) |
+| Reserved (1-3yr) | 30-72% | Steady production (>70% util for 6+ months) | Uncertain workloads |
+| Spot/Preemptible | 60-90% | Batch, CI/CD, fault-tolerant workers | Databases, user-facing |
+
+## Right-Sizing Indicators
+- CPU < 40% consistently = oversized.
+- Memory < 50% consistently = oversized.
+- Process: collect 2-4 weeks metrics → find binding constraint → resize to peak + 20%.
+
+## Cost Allocation Tags (Minimum)
+- `team`, `service`, `environment`, `cost-center`.
+- Optional: `feature` for per-feature attribution.
+- Shared infra: divide proportionally by request count or CPU time.
+
+## Forecasting
+```
+Next Month = Current * (1 + organic_growth) + planned_launch_impact
+```
+- Inputs: historical trend (3-6 months), planned launches, seasonal patterns.
+- Weekly: check for anomalies. Monthly: forecast vs actual. Quarterly: re-evaluate commitments.
+
+## Self-check before task completion
+
+- [ ] Did I estimate costs before proposing infrastructure?
+- [ ] Are resources tagged for cost allocation?
+- [ ] Is instance strategy appropriate (on-demand vs reserved vs spot)?
+- [ ] Are cost alerts configured at budget thresholds?
+- [ ] Is right-sizing based on actual utilization data?
+- [ ] Is there a cost visibility mechanism (dashboard)?
+- [ ] Are managed-vs-self-hosted trade-offs documented?

package/.mindforge/skills/council/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: council
+version: 1.0.0
+min_mindforge_version: 10.0.3
+status: stable
+triggers: council, multi-voice, decision debate, architectural decision, trade-off, ambiguous, contentious, ADR, design decision, breaking change
+---
+
+# Skill — Council (Multi-Voice Decision)
+
+## When this skill activates
+Any ambiguous architectural decision where multiple valid approaches exist,
+when resolving contentious technical choices, or when the Adversarial Decision
+Loop (ADS) produces a split verdict.
+
+## Mandatory actions when this skill is active
+
+### Before invoking council
+1. Verify the decision actually warrants multi-voice debate:
+   - Are there 2+ genuinely viable options? (If one is obviously best, skip council)
+   - Is the decision hard to reverse? (If easily reversible, just pick one and iterate)
+   - Does the decision affect multiple stakeholders or systems?
+2. Frame the decision clearly with: context, options, constraints, and stakes.
+
+### The Four Voices
+
+| Voice | Asks | Bias (intentional) |
+|-------|------|-------------------|
+| **Architect** | "What scales? What's maintainable in 2 years?" | Elegant, extensible systems |
+| **Skeptic** | "What breaks? What haven't we considered?" | Caution, hidden failure modes |
+| **Pragmatist** | "What ships? What delivers value soonest?" | Delivery speed, incrementalism |
+| **Critic** | "What's excellent? What meets our standards?" | Quality, craftsmanship |
+
+### Council Protocol
+1. **Frame** — Present decision with context, options, constraints
+2. **Positions** — Each voice states recommendation + top 3 reasons + confidence (0-1)
+3. **Challenge** — Each voice rebuts the strongest counterargument
+4. **Synthesize** — Produce verdict with consensus score
+5. **Output** — Write to `.planning/decisions/COUNCIL-[timestamp].md`
+
+### Interpreting Results
+
+| Consensus Score | Meaning | Action |
+|----------------|---------|--------|
+| >= 0.85 | Strong agreement | Proceed with confidence |
+| 0.65 - 0.84 | Moderate agreement | Proceed but address dissent concerns |
+| 0.50 - 0.64 | Weak agreement | Seek user input before proceeding |
+| < 0.50 | No consensus | Present all options to user, defer decision |
+
+### Guardrails
+- Council is ADVISORY — user always has final say
+- Maximum 2 rounds (initial + challenge). No infinite debates.
+- Each voice limited to 200 words per round
+- If consensus < 0.5: do NOT auto-select. Report "No consensus" honestly.
+- Always document dissent — suppressed minority opinions create tech debt
+- Use council templates (see `council-templates.md`) for common decision types
+
+### After council
+- Write the decision record to `.planning/decisions/`
+- If the decision creates an ADR: also write to `docs/adr/`
+- Log council invocation and verdict in AUDIT
+- Track the Skeptic's unmitigated risks as action items
+
+## Self-check before task completion
+- [ ] Did I verify the decision warranted a council (not a simple choice)?
+- [ ] Did I document all dissenting opinions (never suppressed)?
+- [ ] Did I write the council verdict to .planning/decisions/?
+- [ ] Did I remind the user that council is advisory (user has final say)?

package/.mindforge/skills/cqrs-event-sourcing/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: cqrs-event-sourcing
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: cqrs, event sourcing, command query separation, event store, projection, eventual consistency, event replay, aggregate root, domain event, event versioning, read model, write model
+---
+
+# Skill — CQRS & Event Sourcing
+
+## When this skill activates
+Any task involving command/query responsibility segregation, event sourcing, event store
+design, projection building, or systems requiring full audit trails and temporal queries.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Validate the need** — Confirm at least one: full audit trail required, temporal queries needed, complex domain with many read views, or high read/write asymmetry.
+2. **Identify aggregates** — Define aggregate roots as consistency boundaries. Each aggregate emits domain events and enforces invariants.
+3. **Map read vs write models** — Document which queries need optimized read models separate from the event stream.
+
+### During
+
+#### Command side (write model)
+- Commands are imperative ("PlaceOrder", "CancelShipment")
+- Command handler validates invariants then emits domain events
+- State is NEVER set directly — it is derived by applying events
+- Aggregate enforces business rules before accepting the command
+
+#### Event store design
+```sql
+CREATE TABLE events (
+  event_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  aggregate_id    UUID NOT NULL,
+  aggregate_type  VARCHAR(100) NOT NULL,
+  event_type      VARCHAR(100) NOT NULL,
+  event_version   INTEGER NOT NULL,
+  sequence_number BIGINT NOT NULL,
+  payload         JSONB NOT NULL,
+  metadata        JSONB NOT NULL,  -- correlation_id, causation_id, actor
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE (aggregate_id, sequence_number)
+);
+```
+- Events are immutable — never update or delete
+- Optimistic concurrency via expected sequence number on write
+- Event names are past tense: `OrderPlaced`, `PaymentCharged`
+- Store both payload and metadata (correlation ID, causation ID, actor)
+
+#### Projections (read models)
+- Each projection materializes a read-optimized view from the event stream
+- Projections are independently rebuildable (replay from event 0)
+- Use checkpointing: store last processed event position
+- Different projections can use different databases (SQL, Elasticsearch, Redis)
+- Mark as "rebuilding" during replay to avoid serving stale data
+
+#### Eventual consistency patterns
+- Causal consistency: return event sequence number from command, poll until projection catches up
+- Read-your-writes: optimistically update client state after command succeeds
+- Subscription-based: clients subscribe to projection update notifications
+
+#### Snapshot strategy
+- Avoid replaying entire history for long-lived aggregates
+- Load latest snapshot + events after snapshot sequence number
+- Snapshot frequency: every 50-100 events per aggregate
+- Snapshots are optimization only — system must work without them
+
+#### Event versioning and upcasting
+- Never modify existing event schemas in-place
+- Add optional fields (backward-compatible) or create new event type
+- Upcasters transform old events to current schema during replay
+- Store schema version with every event for routing to correct upcaster
+
+#### Idempotent handlers
+- Every projection/handler must be safe to process the same event twice
+- Deduplicate by event_id before processing
+- Record checkpoint after successful processing
+
+### After
+
+1. **Verify event completeness** — Every state change captured as a domain event. No silent mutations.
+2. **Test replay** — Rebuild one projection from scratch; confirm data integrity.
+3. **Validate idempotency** — Process same event twice, confirm no side effects.
+4. **Check consistency boundaries** — Each aggregate enforces invariants independently.
+
+## Self-check before task completion
+- [ ] All state changes expressed as immutable domain events
+- [ ] Event store uses optimistic concurrency (sequence number)
+- [ ] Projections independently rebuildable from event stream
+- [ ] Event handlers are idempotent (safe to replay)
+- [ ] Snapshot strategy defined for long-lived aggregates
+- [ ] Event versioning/upcasting handles schema evolution
+- [ ] Eventual consistency communicated to client layer
+- [ ] Correlation and causation IDs propagated through event chain

package/.mindforge/skills/cross-platform-testing/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: cross-platform-testing
+version: 1.0.0
+min_mindforge_version: 10.4.0
+status: stable
+triggers: cross-platform testing, device farm testing, screenshot comparison test, platform-specific testing, mobile CI pipeline, Appium testing, Detox testing, XCTest UITest, mobile test automation, device matrix coverage, mobile E2E testing, visual regression mobile
+---
+
+# Skill — Cross-Platform Mobile Testing
+
+## When this skill activates
+This skill activates when implementing comprehensive mobile testing strategies, including device farm integration, screenshot testing, platform-specific behavior validation, or CI/CD pipelines for mobile apps.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Define device matrix covering target OS versions, screen sizes, and hardware capabilities (prioritize based on user analytics)
+2. Choose testing framework appropriate for platform (XCTest/XCUITest for iOS, Espresso/UIAutomator for Android, Detox/Appium for cross-platform)
+3. Establish screenshot testing baseline images and tolerance thresholds for visual regression detection
+4. Design test data strategy — use factories/fixtures, implement proper setup/teardown, ensure test isolation
+
+### During implementation
+- Write tests at appropriate levels: unit tests for business logic, integration tests for data flows, E2E tests for critical user journeys
+- Implement proper test identifiers (testID, accessibilityIdentifier) in UI components for reliable element selection
+- Use page object pattern or similar abstraction to decouple tests from UI implementation details
+- Configure screenshot testing with proper device/OS-specific baselines to handle platform rendering differences
+- Implement retry logic for flaky tests caused by animation timing, network delays, or platform quirks
+- Set up parallel test execution on device farms (Firebase Test Lab, AWS Device Farm, BrowserStack) for faster feedback
+- Handle platform-specific behaviors explicitly in tests (Android back button, iOS swipe gestures, permission dialogs)
+
+### After implementation
+- Run full test suite on representative device matrix, not just emulators/simulators
+- Review test flakiness rates and fix or quarantine unstable tests
+- Integrate tests into CI pipeline with proper failure reporting and artifact collection (screenshots, logs, videos)
+- Validate test coverage for critical paths and high-risk areas (payments, authentication, data sync)
+
+## Self-check before task completion
+- [ ] Test suite runs reliably across multiple devices and OS versions with <5% flakiness
+- [ ] Screenshot tests catch visual regressions without excessive false positives
+- [ ] Platform-specific behaviors are tested correctly (back button, deep links, system gestures)
+- [ ] CI pipeline provides clear failure reporting with screenshots/videos for debugging
+- [ ] E2E tests cover critical user journeys end-to-end, including error scenarios
+- [ ] Test execution time is reasonable (use parallelization, split test suites if needed)