mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/cdn-optimization/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: cdn-optimization
+version: 1.0.0
+min_mindforge_version: 10.1.1
+status: stable
+triggers: cdn optimization, cache hierarchy, cache purge strategy, edge-side includes, origin shielding, cache key design, cdn invalidation, cdn prewarming, stale-while-revalidate cdn, cdn hit ratio, cdn failover, multi-cdn strategy
+compose: caching-strategies
+---
+
+# Skill — CDN Optimization
+
+## When this skill activates
+Any task involving CDN configuration, cache strategy design, cache invalidation,
+origin shielding, cache key optimization, or multi-CDN architecture
+for high-traffic web applications.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify content types and their cacheability (static, dynamic, personalized).
+2. Define cache hierarchy (Edge POP → Regional Shield → Origin).
+3. Design cache keys (URL + Vary headers — don't over-key).
+4. Plan purge/invalidation strategy before enabling caching.
+
+### During implementation
+- Set explicit Cache-Control headers on every response.
+- Enable origin shielding to collapse edge requests.
+- Use stale-while-revalidate for graceful cache refresh.
+- Design cache keys to maximize hit ratio without serving wrong content.
+- Implement tag-based purge for granular invalidation.
+- Never cache responses with `Set-Cookie` headers.
+
+### After implementation
+- Measure cache hit ratio (target: >95% static, >80% dynamic).
+- Verify purge propagates within acceptable time.
+- Test cache behavior with different user contexts (logged in vs anonymous).
+- Monitor origin load (should decrease significantly with CDN).
+- Confirm no stale content is served after deploys.
+
+## Cache Hierarchy
+
+### Three-Tier Architecture
+```
+User → Edge POP (closest) → Regional Shield → Origin Server
+        ↓ cache hit?         ↓ cache hit?      ↓ always fresh
+        serve immediately    serve to edge      generate response
+```
+
+### Benefits
+- **Edge POP**: Sub-10ms latency for cached content.
+- **Regional Shield**: Collapses many edge misses into single origin request.
+- **Origin**: Only handles truly unique/expired requests.
+
+### Origin Shielding (Critical)
+Without shielding: 100 edge POPs × cache miss = 100 origin requests.
+With shielding: 100 edge POPs → 1 shield request → 1 origin request.
+
+## Cache Key Design
+
+### Principles
+- Cache key = what makes a response unique.
+- Over-keying (too many variants) = low hit ratio.
+- Under-keying (too few variants) = serving wrong content.
+
+### Common Cache Key Components
+```
+Default: scheme + host + path + query string
+Add when needed: Accept-Encoding, Accept-Language, device type
+NEVER include: session cookies, random headers, full cookie jar
+```
+
+### Examples
+| Content Type | Cache Key | Vary Header |
+|-------------|-----------|-------------|
+| Static assets | URL (path + hash) | None |
+| API (public) | URL + query params | Accept-Encoding |
+| Localized page | URL + language | Accept-Language |
+| Responsive image | URL + device class | (custom header) |
+
+### Anti-Patterns
+- Including session cookie in cache key (unique per user = 0% hit ratio).
+- Including `Authorization` header for public content.
+- Using full `User-Agent` as variant (thousands of variants).
+
+## Cache-Control Headers
+
+### Static Assets (Hashed Filenames)
+```
+Cache-Control: public, max-age=31536000, immutable
+```
+- One year cache, never revalidate.
+- Safe because filename changes on content change.
+
+### Dynamic Content (Cacheable)
+```
+Cache-Control: public, max-age=60, stale-while-revalidate=300
+```
+- Fresh for 60s, serve stale for 300s while fetching fresh in background.
+- User always gets fast response, content refreshes async.
+
+### Personalized/Private
+```
+Cache-Control: private, no-store
+```
+- Never cache in shared caches (CDN).
+- Only browser can cache.
+
+### API Responses
+```
+Cache-Control: public, max-age=10, stale-while-revalidate=60, stale-if-error=300
+```
+- Short freshness, graceful degradation on origin failure.
+
+## Purge Strategy
+
+### Methods (Ranked by Preference)
+1. **Tag-based purge**: Assign cache tags, purge by tag. Most granular.
+2. **URL-based purge**: Purge specific URL. Precise but doesn't scale to many URLs.
+3. **Prefix purge**: Purge all URLs matching path prefix. Broad but useful for deploys.
+4. **Full purge**: Nuclear option. Purge everything. Avoid in production.
+
+### Purge Triggers
+- Deploy: purge changed assets (tag-based or prefix).
+- Content update: purge specific URLs or tags.
+- Emergency: full purge if stale content is harmful.
+
+### Propagation Time
+- Instant purge at edge: <1 second (Fastly, Cloudflare).
+- Some CDNs: 5-15 minutes propagation.
+- Always verify purge completed before relying on fresh content.
+
+## Stale-While-Revalidate
+
+### How It Works
+1. Request arrives for expired content.
+2. CDN serves stale response immediately (fast!).
+3. CDN fetches fresh content from origin in background.
+4. Next request gets fresh content.
+
+### Benefits
+- User never waits for origin response.
+- Origin gets time to respond without blocking users.
+- Graceful handling of origin slowness or errors.
+
+### Configuration
+```
+Cache-Control: public, max-age=60, stale-while-revalidate=600, stale-if-error=86400
+```
+- Fresh for 60s.
+- Serve stale for up to 600s while revalidating.
+- Serve stale for up to 24h if origin is erroring.
+
+## Hit Ratio Targets
+
+| Content Type | Target Hit Ratio | If Below |
+|-------------|-----------------|----------|
+| Static assets (JS/CSS/images) | >99% | Check cache key, immutable headers |
+| HTML pages (anonymous) | >95% | Check Vary headers, cookie leakage |
+| API responses (public) | >80% | Check TTL, query param diversity |
+| Personalized content | N/A | Should not be cached at CDN |
+
+### Diagnosing Low Hit Ratio
+1. Check `Vary` header — is it over-specifying?
+2. Check cache key — are cookies leaking in?
+3. Check TTL — is content expiring too quickly?
+4. Check query parameters — are tracking params included?
+5. Check purge frequency — are you purging too often?
+
+## Multi-CDN Strategy
+
+### Use Cases
+- Failover (CDN A down → traffic to CDN B).
+- Cost arbitrage (cheaper CDN for bulk, premium for critical).
+- Geographic optimization (CDN A better in region X, CDN B in region Y).
+- Vendor independence (avoid lock-in).
+
+### Implementation
+- DNS-based switching (GeoDNS or failover).
+- Unified purge API across CDN providers.
+- Normalized configuration (cache rules consistent across providers).
+- Monitoring per-CDN performance independently.
+
+## Edge-Side Includes (ESI)
+
+### Pattern
+Compose pages from independently cached fragments:
+```html
+<esi:include src="/header" />
+<main>Page-specific content</main>
+<esi:include src="/footer" />
+```
+
+### Benefits
+- Header/footer cached separately (long TTL).
+- Page content has its own TTL.
+- Reduces full-page cache misses.
+
+### When to Use
+- Pages share common components (header, nav, footer).
+- Components have different cache lifetimes.
+- Personalization is limited to specific fragments.
+
+## Self-check
+- [ ] Cache-Control headers set on every response type.
+- [ ] Origin shielding enabled.
+- [ ] Cache keys designed (not over-keyed or under-keyed).
+- [ ] Purge strategy implemented and tested.
+- [ ] Stale-while-revalidate configured for dynamic content.
+- [ ] Hit ratio >95% for static, >80% for dynamic.
+- [ ] No `Set-Cookie` responses being cached.
+- [ ] Deploy purge automated in CI/CD pipeline.
+- [ ] Origin load reduced significantly vs direct traffic.

package/.mindforge/skills/change-management/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: change-management
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: change management engineering, migration buy-in, deprecation communication, process adoption, resistance handling, technology transition, platform migration communication, developer adoption, breaking change rollout, sunsetting communication, organizational change, migration strategy communication
+---
+
+# Change Management
+
+## When this skill activates
+
+This skill activates when managing technology migrations, communicating deprecations, driving process adoption, handling resistance to change, or rolling out breaking changes. It applies to tech leads, engineering managers, platform engineers, and staff engineers responsible for organizational or technical transitions.
+
+## Mandatory actions when this skill is active
+
+### Before initiating change
+
+1. **Quantify the cost of status quo** — Why is change necessary? What's the cost of not changing? (Technical debt, security risk, developer productivity, scalability ceiling.) Make the pain explicit.
+2. **Identify stakeholders and their incentives** — Who is impacted? What do they care about? Engineers care about productivity. Product cares about velocity. Execs care about risk and cost. Tailor the message to each audience.
+3. **Assess change complexity and risk** — Low-risk, low-effort changes (linter config update) can be rolled out quickly. High-risk, high-effort changes (database migration, language change) require extensive planning and staged rollout.
+4. **Build a coalition of early adopters** — Don't force change top-down. Recruit influential engineers who see the value. Their endorsement accelerates adoption faster than mandates.
+
+### During change rollout
+
+#### Migration Buy-In Strategies
+
+- **Start with the "why," not the "what"** — Don't lead with "We're migrating to Kubernetes." Lead with "Our current deployment process takes 45 minutes and fails 20% of the time. Kubernetes will reduce deploy time to 5 minutes and improve reliability."
+- **Demonstrate quick wins** — Run a pilot project. Show tangible benefits (faster builds, fewer bugs, easier onboarding). Success stories are more persuasive than Powerpoints.
+- **Address objections directly** — Don't dismiss concerns. If someone says "This will slow us down," acknowledge it: "Yes, there's a ramp-up cost. Here's how we're mitigating it with training and pairing."
+- **Make the default path the new path** — Update templates, documentation, and scaffolding tools to reflect the new approach. The path of least resistance should be the desired behavior.
+
+#### Deprecation Communication
+
+- **Announce early and often** — Deprecations should have a 6-12 month runway (depending on impact). Announce in: all-hands, team Slack channels, email, documentation, and in-app warnings (if applicable).
+- **Provide a clear migration path** — Don't just say "Service X is deprecated." Provide a step-by-step guide: (1) Assess usage, (2) Replace with Service Y, (3) Test, (4) Deploy, (5) Remove old code.
+- **Offer migration support** — Host office hours, create migration runbooks, assign a DRI (Directly Responsible Individual) to help teams migrate. Abandoned teams will resist.
+- **Set and enforce deadlines** — Soft deadline (recommended), hard deadline (automatic cutover or feature removal). No deadline = no urgency = no adoption.
+- **Track migration progress** — Publish a dashboard showing which teams have migrated. Social proof accelerates laggards.
+
+#### Process Adoption (e.g., New Code Review Standards, CI/CD Changes)
+
+- **Involve engineers in design** — Don't impose processes unilaterally. If engineers co-design the process, they'll co-own it. Run RFCs, gather feedback, iterate.
+- **Start with opt-in, then default, then mandatory** — Phase 1: Teams can try it. Phase 2: New projects default to it. Phase 3: All projects must use it. Gives people time to adapt.
+- **Automate enforcement where possible** — If you want engineers to write tests, make CI fail without tests. If you want design reviews, make PRs require approval before merge. Manual enforcement is inconsistent.
+- **Measure adoption and impact** — Track: % of teams using the new process, time savings, quality improvements. Share metrics publicly to reinforce value.
+
+#### Resistance Handling
+
+**Common Resistance Patterns and Responses:**
+
+| Resistance | Underlying Concern | How to Address |
+|------------|-------------------|----------------|
+| "We don't have time for this" | Fear of slowing down feature velocity | Show time savings after ramp-up. Provide dedicated migration time in sprint planning. |
+| "The old way works fine" | Comfort with status quo, skepticism of new approach | Quantify pain of old way (incidents, time spent, bugs). Show pilot results. |
+| "This is too complicated" | Lack of understanding or training | Provide training, documentation, pairing sessions. Simplify the onboarding path. |
+| "No one asked us" | Feeling excluded from decision | Involve them in refinement. Acknowledge feedback. Adjust the plan if valid concerns. |
+| "I don't see the value" | Misalignment on priorities | Connect the change to their goals. If they care about velocity, show how this accelerates it. |
+| "We tried this before and it failed" | Historical baggage | Acknowledge past failure. Explain what's different this time. Show evidence of changed conditions. |
+
+**Escalation Path:**
+1. **Listen first** — Understand the root concern. Don't dismiss or argue.
+2. **Address with data** — Use pilot results, benchmarks, or case studies to counter objections.
+3. **Compromise where reasonable** — If they have a valid concern, adjust the plan. Flexibility builds trust.
+4. **Escalate if necessary** — If a team refuses to adopt a mandatory change, escalate to their manager or exec sponsor. But exhaust persuasion first.
+
+#### Technology Transition (e.g., New Language, Framework, Platform)
+
+- **Create a transition plan** — Phases: (1) Pilot project, (2) Documentation and training, (3) New projects use new tech, (4) Migrate existing projects, (5) Deprecate old tech.
+- **Set migration milestones** — Don't mandate "migrate everything by Q4." Break it into incremental milestones: "Migrate 3 services by Q1, 10 by Q2, all by Q3."
+- **Provide dual support during transition** — Support both old and new tech for a grace period (6-12 months). Prevents forcing teams into incomplete migrations.
+- **Document everything** — Migration guides, troubleshooting FAQs, architecture decision records. The more self-service resources, the faster adoption.
+
+#### Breaking Change Rollout
+
+- **Minimize breaking changes** — Can you make it backward-compatible? Use feature flags, versioned APIs, or parallel systems to avoid forcing immediate adoption.
+- **If unavoidable, batch breaking changes** — Don't introduce breaking changes every sprint. Batch them into quarterly releases. Gives teams time to adapt.
+- **Communicate impact explicitly** — Which services/teams are affected? What do they need to do? By when? Who can help? Make it actionable.
+- **Provide tooling for migration** — Codemods, automated refactoring scripts, linters that catch breaking changes. Reduce manual toil.
+- **Test extensively before rollout** — Run the breaking change in staging or canary environments. Catch issues before they hit production.
+
+#### Organizational Change (e.g., New Processes, Roles, Team Structure)
+
+- **Communicate the rationale** — Why is this change happening? What problem does it solve? Connect to business or engineering goals.
+- **Address uncertainty** — Organizational change creates anxiety. Be transparent about what's changing, what's staying the same, and what's still TBD.
+- **Give people time to adapt** — Major changes (team restructuring, new roles) need 30-60 days for people to adjust. Don't rush.
+- **Create feedback loops** — After 30 days, survey the team: "How's the new structure working? What's better? What's worse?" Adjust based on feedback.
+
+### After change rollout
+
+- **Measure success** — Did the change achieve the intended outcome? (Faster deploys, fewer bugs, higher developer satisfaction.) If not, course-correct or roll back.
+- **Celebrate adoption milestones** — When 50% of teams have migrated, announce it publicly. Recognize early adopters. Momentum builds motivation.
+- **Sunset the old system** — Once migration is complete, fully deprecate the old system. Don't maintain dual systems indefinitely. It's expensive and confusing.
+- **Conduct a retrospective** — What went well? What didn't? What would we do differently next time? Document lessons learned for the next change initiative.
+- **Update documentation** — Remove references to the old system. Ensure onboarding docs, runbooks, and templates reflect the new standard.
+
+## Self-check before task completion
+
+- [ ] Cost of status quo is quantified with specific pain points (technical debt, security, productivity)
+- [ ] Stakeholders are identified with tailored messaging (engineers, product, execs)
+- [ ] Migration buy-in strategy starts with "why" and demonstrates quick wins via pilot
+- [ ] Deprecation communication includes early announcement, clear migration path, and deadlines
+- [ ] Process adoption follows opt-in → default → mandatory phasing
+- [ ] Resistance is addressed by listening, providing data, and compromising where reasonable
+- [ ] Breaking changes are batched, communicated with impact analysis, and include migration tooling
+- [ ] Success metrics are defined and measured post-rollout (time savings, quality, adoption rate)

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

@@ -0,0 +1,99 @@
+---
+name: chaos-engineering
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: chaos engineering, controlled failure injection, steady state hypothesis, blast radius containment, game day exercise, resilience verification, circuit breaker testing, chaos monkey experiment, fault tolerance validation, disaster recovery drill, failure mode analysis, controlled outage design
+compose:
+  - observability-stack
+---
+
+# Chaos Engineering
+
+## When this skill activates
+
+This skill activates when the user is designing, implementing, or conducting chaos
+engineering experiments. This includes defining steady-state hypotheses, designing
+controlled failure injection experiments, containing blast radius, planning game day
+exercises, verifying resilience patterns (circuit breakers, retries, bulkheads),
+conducting disaster recovery drills, and analyzing failure modes in distributed systems.
+
+## Mandatory actions
+
+### Before
+
+1. Confirm observability is in place — you cannot measure what you cannot see.
+2. Define the steady-state hypothesis: what does "normal" look like in metrics?
+3. Identify the blast radius boundary for the planned experiment.
+4. Verify a rollback mechanism exists BEFORE injecting any failure.
+5. Ensure stakeholder awareness (announce game days; never surprise production teams).
+6. Check that the system under test has basic resilience patterns (retries, timeouts, circuit breakers).
+
+### During
+
+**Steady-State Hypothesis:**
+- Define "normal" quantitatively before breaking things (p99 latency < 200ms, error rate < 0.1%, throughput > 1000 rps).
+- The experiment succeeds if steady-state is maintained despite failure injection.
+- The experiment reveals a weakness if steady-state degrades beyond acceptable thresholds.
+- Always compare against the baseline, not against zero errors.
+
+**Experiment Design:**
+- Follow the scientific method: hypothesis, inject failure, observe, verify or refute.
+- Document the expected outcome before running the experiment.
+- Define success criteria AND abort criteria before starting.
+- Time-box experiments (auto-revert after N minutes if not manually stopped).
+- Run in progressively broader scope: staging first, then production with minimal blast radius.
+
+**Blast Radius Containment:**
+- Start small: 1 pod, then 1 node, then 1 availability zone. Never start with full chaos.
+- Use feature flags or traffic percentages to limit affected users.
+- Have circuit breakers around the experiment itself (meta-resilience).
+- Production experiments target a single failure mode at a time.
+- Never combine multiple failure injections in the first run.
+
+**Failure Types:**
+- **Network:** Latency injection (add 500ms), packet loss (5-20%), network partition (isolate a service), DNS failure.
+- **Resource:** CPU exhaustion (stress-ng), memory pressure (fill to 90%), disk full, file descriptor exhaustion.
+- **Dependency:** Kill downstream service, return errors from dependency, slow dependency (timeout scenarios).
+- **State:** Corrupt cache entries, stale data injection, clock skew, split-brain simulation.
+- **Infrastructure:** Node termination, AZ failure simulation, control plane unavailability.
+
+**Game Days:**
+- Scheduled, announced, and measured events.
+- Assign roles: experiment lead, observer, incident commander (if things go wrong).
+- Set clear start/end times and communication channels.
+- Capture learnings in a structured report after each game day.
+- Progressively increase difficulty across game days.
+
+**Tooling:**
+- Chaos Monkey / Simian Army (random instance termination).
+- Litmus Chaos / Chaos Mesh (Kubernetes-native experiments).
+- Gremlin (managed chaos platform).
+- Toxiproxy / tc (network fault injection).
+- Custom scripts with automatic rollback timers.
+
+**Rollback:**
+- ALWAYS have a rollback plan documented and tested before injection.
+- Automated rollback on abort criteria breach (metric threshold exceeded).
+- Manual kill switch accessible to experiment lead.
+- Post-rollback verification: confirm steady-state returns to normal.
+
+### After
+
+1. Compare observed metrics against steady-state hypothesis.
+2. Document findings: hypothesis confirmed or refuted, with evidence.
+3. If weakness found: create an action item to improve resilience.
+4. Share results broadly — chaos experiments are learning opportunities.
+5. Update runbooks based on observed failure behavior.
+6. Plan the next experiment (broader scope or different failure mode).
+
+## Self-check before task completion
+
+- [ ] Steady-state hypothesis is defined with quantitative metrics.
+- [ ] Blast radius is contained and progressively expanded.
+- [ ] Rollback mechanism is in place and tested before injection.
+- [ ] Observability confirms the ability to detect impact.
+- [ ] Experiment follows the scientific method (hypothesis, injection, observation, conclusion).
+- [ ] Stakeholders are informed (no surprise chaos in production).
+- [ ] Findings are documented with actionable improvements.
+- [ ] Game day schedule includes progressive difficulty increases.

package/.mindforge/skills/ci-cd-pipeline/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: ci-cd-pipeline
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: ci cd pipeline, pipeline architecture, build stage design, deployment gate, artifact management, environment promotion, parallel jobs optimization, ci caching strategy, secrets in ci, ci rollback automation, github actions pipeline, pipeline stage design
+---
+
+# CI/CD Pipeline
+
+## When this skill activates
+
+This skill activates when designing, implementing, or optimizing continuous integration and continuous deployment pipelines. It covers pipeline architecture, stage design, quality gates, artifact management, caching, parallelism, secrets handling, environment promotion, and rollback strategies. Use this skill whenever build/test/deploy automation is being created or modified.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Map the current workflow** — Document the existing build, test, and deploy steps (even if manual). Understand what exists before automating.
+2. **Identify bottlenecks** — Measure current CI duration. Identify the slowest stages. Optimization targets the bottleneck, not random stages.
+3. **Define deployment targets** — List all environments (dev, staging, production) and their promotion requirements.
+4. **Assess risk tolerance** — How much downtime is acceptable? Zero-downtime deployments require different strategies than maintenance-window deployments.
+
+### During
+
+#### Pipeline Stages (Lint → Build → Unit Test → Integration Test → Security Scan → Package → Deploy)
+
+**Stage 1: Lint** — Linters + type-check first (<60s). Fail fast on errors.
+**Stage 2: Build** — Compile, bundle. Environment-agnostic artifact. Target <3min with cache.
+**Stage 3: Unit Tests** — Coverage reporting. Fail below 80% threshold. Target <5min.
+**Stage 4: Integration Tests** — Real dependencies (testcontainers). Target <10min.
+**Stage 5: Security Scan** — Dependency audit (Snyk/Trivy) + SAST + secret detection. Fail on critical/high.
+**Stage 6: Package** — Create artifact (Docker image/binary). Tag with SHA + semver. Sign and push to registry.
+**Stage 7: Deploy** — Dev → staging → production. Approval gate required for production.
+
+#### Quality Gates (Between Stages)
+
+- **Gate definition** — A gate is a pass/fail checkpoint that blocks pipeline progression.
+- **Automated gates** — Test coverage threshold, zero critical vulnerabilities, all tests passing, build succeeds.
+- **Manual gates** — Production approval, security review sign-off, change management ticket.
+- **Gate principle** — Every gate must have a clear owner and clear criteria. Ambiguous gates become rubber stamps.
+- **Implementation** — Use CI environment protection rules (GitHub Actions `environment` key with required reviewers).
+
+#### Artifact Management
+
+- **Immutability** — Once built, an artifact never changes. The same artifact deployed to staging is promoted to production. Never rebuild for production.
+- **Versioning** — Tag every artifact with: git commit SHA (exact), semantic version (human-readable), build timestamp.
+- **Retention** — Keep the last N production artifacts (minimum 5) for rollback. Auto-expire older artifacts.
+- **Signing** — Sign artifacts with a known key. Verify signatures before deployment. Prevents tampered artifacts from reaching production.
+- **Registry hygiene** — Clean untagged/unused images regularly. Container registries grow unbounded without garbage collection.
+
+#### Caching Strategy
+
+**Dependency cache:**
+- Cache dependencies keyed on lockfile hash. Invalidate only when dependencies change.
+- Use fallback keys for partial cache hits (restore previous deps, update delta only).
+
+**Build cache:**
+- Cache compilation outputs (TypeScript tsbuildinfo, Go build cache, Docker layer cache).
+- For Docker: order Dockerfile instructions from least-changing (base image) to most-changing (source code).
+- Cache test results for unchanged code paths (only re-run tests for changed files in PR pipelines).
+
+**Cache invalidation:**
+- Key on content hashes, not timestamps. Content-addressed caching prevents stale cache bugs.
+- Set TTL: dependency caches (7 days), build caches (1 day), test caches (1 day).
+- Monitor cache hit rates. Below 60% means the cache key strategy needs adjustment.
+
+#### Parallelism and Optimization
+
+- **Independent jobs run simultaneously** — Lint, unit tests, and security scan can all run in parallel if they don't depend on each other.
+- **Matrix builds** — Test across multiple versions/platforms simultaneously (node 18/20/22, ubuntu/macos).
+- **Test splitting** — Distribute test files across N parallel runners based on historical timing data.
+- **Fail-fast** — Cancel remaining matrix jobs when one fails (unless full compatibility reporting needed).
+- **Resource optimization** — Smaller runners for lint/test, larger for build/package.
+
+#### Secrets Management in CI
+
+- **Never in code** — Secrets never appear in source code, Dockerfiles, or CI configuration files.
+- **CI secret stores** — Use platform-native secret management (GitHub Secrets, GitLab CI Variables, AWS Secrets Manager).
+- **Least privilege** — Each job gets only the secrets it needs. Never share production secrets with lint.
+- **Rotation and audit** — Rotate quarterly minimum. Log all secret access. Verify masking in logs (`***`).
+
+#### Environment Promotion (Dev → Staging → Production)
+
+- **Same artifact** — The exact same build artifact moves through environments. Only configuration (env vars, feature flags) changes.
+- **Progressive rollout** — Production deploys should use: canary (1% traffic) → partial (10%) → full (100%).
+- **Smoke tests** — After each deployment, run a minimal health check. Automatic rollback if smoke tests fail.
+- **Feature flags** — Decouple deployment from release. Deploy code to production with flags off. Enable gradually.
+- **Environment parity** — Staging must mirror production as closely as possible: same infrastructure, same data shape (anonymized), same configuration.
+
+#### Rollback Strategy
+
+- **Keep N previous artifacts** — Retain last 5 production artifacts for instant rollback.
+- **One-click revert** — Single action (button/CLI), not a multi-step process.
+- **Rollback testing** — Test quarterly. Untested rollbacks fail when needed most.
+- **Database compatibility** — Expand/contract pattern: (1) add new column, (2) deploy new code, (3) remove old column after rollback window.
+- **Auto-rollback triggers** — Error rate >5%, latency p99 >2x baseline, or 3 consecutive health check failures.
+
+### After
+
+1. **Measure pipeline duration** — Track total time from commit to production. Target: <15 minutes for simple services, <30 minutes for complex ones.
+2. **Monitor reliability** — Track pipeline success rate. Target: >95%. Flaky pipelines erode developer trust.
+3. **Review cost** — Audit CI compute costs monthly. Identify waste: unnecessary matrix builds, oversized runners, uncached builds.
+4. **Test the rollback** — Perform a planned rollback quarterly to verify the procedure works.
+
+## Self-check before task completion
+
+- [ ] Pipeline stages follow the standard flow: Lint → Build → Test → Scan → Package → Deploy
+- [ ] Quality gates exist between stages with clear pass/fail criteria
+- [ ] Artifacts are immutable, versioned (commit SHA + semver), and signed
+- [ ] Caching is configured for dependencies, builds, and Docker layers with content-based keys
+- [ ] Independent jobs run in parallel (lint, unit tests, security scan)
+- [ ] Secrets are stored in CI secret store with least-privilege access per job
+- [ ] Same artifact promotes through environments (never rebuild for production)
+- [ ] Rollback procedure is documented, automated, and tested
+- [ ] Database migrations are backward-compatible (expand/contract pattern)
+- [ ] Pipeline duration is measured and within acceptable bounds
+- [ ] Pipeline success rate is tracked (target >95%)

package/.mindforge/skills/cli-design/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: cli-design
+version: 1.0.0
+min_mindforge_version: 10.0.8
+status: stable
+triggers: cli design, command structure, flag design, positional argument, help text design, interactive prompt, exit code, cli ux, subcommand, cli argument parsing, cli error message, terminal output
+---
+
+# CLI Design
+
+## When this skill activates
+
+This skill activates when designing command-line interfaces, implementing argument parsing, writing help text, handling terminal output formatting, or improving CLI user experience. It applies to new CLI tools, adding commands to existing CLIs, and refactoring CLI ergonomics.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. Define the primary audience (developers, ops engineers, end users, CI systems).
+2. Identify the core verbs/actions the CLI must support.
+3. Survey existing CLIs in the same domain for convention alignment (users have muscle memory).
+4. Determine if the CLI will be used interactively (TTY), in scripts (pipes), or both.
+5. Choose the argument parsing library (Commander/yargs for Node, Click/Typer for Python, Cobra for Go, clap for Rust).
+
+### During
+
+**Command Structure:**
+- Use verb-noun pattern: `app deploy staging`, `app config set key=value`.
+- Group related actions under subcommands: `app auth login`, `app auth logout`.
+- Keep top-level commands to 5-8 maximum. Use subcommands for depth.
+- Command names: lowercase, no hyphens in primary commands (use hyphens in flags only).
+- Avoid ambiguity: `app delete project` not `app rm proj` (clarity over brevity for destructive ops).
+
+**Flags and Options:**
+- Boolean flags: `--verbose`, `--force`, `--dry-run` (no value needed).
+- Value flags: `--output json`, `--timeout 30s`, `--config ./my-config.yaml`.
+- Short aliases for common flags: `-v` (verbose), `-f` (force), `-o` (output), `-q` (quiet).
+- Required options should be positional arguments, not flags (reduce typing for common case).
+- Provide sensible defaults: `--timeout 30s` rather than requiring explicit timeout every time.
+
+**Positional Arguments:**
+- Required arguments come first, optional arguments last.
+- Maximum 2-3 positional arguments (beyond that, use flags for clarity).
+- Name them descriptively in help text: `app deploy <environment> [version]`.
+- Support reading from stdin when positional is missing: `echo "data" | app process`.
+
+**Help Text Design:**
+```
+Usage: app <command> [options]
+
+Commands:
+  deploy    Deploy application to target environment
+  config    Manage configuration settings
+  status    Show current deployment status
+
+Options:
+  -v, --verbose    Show detailed output
+  -q, --quiet      Suppress non-error output
+  -h, --help       Show this help message
+  --version        Show version number
+
+Examples:
+  app deploy staging              Deploy to staging
+  app deploy prod --dry-run       Preview production deployment
+  app config set region=us-east   Set region config
+```
+- One-line description per command (max 60 chars).
+- Always include 2-3 examples showing real usage.
+- Group options logically (common first, advanced last).
+- `--help` must work on every subcommand.
+
+**Interactive Prompts:**
+- Only prompt when stdin is a TTY (check `process.stdin.isTTY` or equivalent).
+- In CI/pipe mode: fail with clear error if required input is missing.
+- Use confirmation prompts for destructive actions: "Delete 47 files? [y/N]".
+- Default to the safe option (N for destructive, Y for read-only).
+- Support `--yes` / `--no-input` flag to skip all prompts (for automation).
+
+**Exit Codes:**
+- `0` — Success. Command completed as expected.
+- `1` — General error. Something went wrong during execution.
+- `2` — Misuse. Invalid arguments, unknown flags, missing required input.
+- `130` — Interrupted (Ctrl+C / SIGINT).
+- Document non-standard exit codes if used (e.g., `3` = partial success).
+- Always exit with non-zero on failure (scripts depend on this).
+
+**Output Design:**
+- **Human mode** (TTY): Colors, progress bars, tables, spinners.
+- **Machine mode** (pipe/CI): Plain text or structured (JSON/CSV), no ANSI codes.
+- Auto-detect: `if (stdout.isTTY) { prettyOutput() } else { jsonOutput() }`.
+- Support `--output json` flag to force structured output regardless of TTY.
+- Errors go to stderr, data goes to stdout (enables `app list | grep "prod"`).
+
+**Error Messages:**
+- **What went wrong**: "Failed to connect to database at localhost:5432."
+- **Why it failed**: "Connection refused — is the database server running?"
+- **What to do**: "Run `docker compose up db` to start the database."
+- Never show raw stack traces to users (log them with `--verbose`).
+- Include error codes for searchability: `[ERR_DB_CONNECT] Failed to connect...`.
+
+### After
+
+1. Every command has `--help` with description, usage pattern, and examples.
+2. Exit codes are consistent and documented.
+3. Output works correctly in both TTY and pipe modes.
+4. Destructive commands require confirmation (skippable with `--yes`).
+5. Error messages are actionable (user knows what to do next).
+
+## Self-check before task completion
+
+- [ ] Command structure follows verb-noun convention consistently.
+- [ ] All flags have both long form (`--verbose`) and short form (`-v`) for common options.
+- [ ] Help text includes real-world examples (not just abstract usage patterns).
+- [ ] Interactive prompts are suppressed in non-TTY environments.
+- [ ] Exit codes distinguish success (0), general error (1), and misuse (2).
+- [ ] Output format adapts to context (pretty for humans, structured for scripts).
+- [ ] Error messages include what failed, why, and what to do next.
+- [ ] Destructive operations require explicit confirmation or `--force` flag.