mindforge-cc 11.3.0 → 11.4.0

package/.agent/mindforge/proofread.md

@@ -0,0 +1,87 @@
+---
+description: "Run copy editing pass for grammar, tone, clarity, and readability. Usage: /mindforge:proofread [file] [--tone formal|casual|technical] [--fix]"
+---
+
+<objective>
+Perform a thorough copy editing pass on a document or code comments, checking grammar, tone consistency, clarity, terminology, and readability — then either report findings or apply fixes directly.
+</objective>
+
+<execution_context>
+@.mindforge/skills/proofreader/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (file path to proofread, optional --tone target, optional --fix to auto-apply corrections)
+Knowledge: Project terminology from CONVENTIONS.md, brand voice guidelines, target audience.
+</context>
+
+<process>
+1. **Read for flow**: Read the entire document once without marking issues. Assess:
+   - Does the document have a clear logical structure?
+   - Does each section follow naturally from the previous?
+   - Are there abrupt transitions or missing connective tissue?
+   - Is the overall length appropriate for the content?
+   - Does it achieve its stated purpose?
+
+2. **Check grammar**: Scan for grammatical issues:
+   - Subject-verb agreement
+   - Tense consistency (past/present/future mixed incorrectly)
+   - Dangling modifiers and misplaced clauses
+   - Pronoun-antecedent agreement and clarity
+   - Run-on sentences and comma splices
+   - Incorrect word usage (affect/effect, its/it's, their/there)
+
+3. **Check clarity**: Evaluate sentence-level clarity:
+   - Sentence length (flag any over 30 words — suggest splitting)
+   - Active vs passive voice ratio (prefer active, flag unnecessary passive)
+   - Nominalization (verbs turned to nouns: "implementation of" → "implement")
+   - Hedge words that weaken claims (somewhat, rather, quite, basically)
+   - Ambiguous pronouns ("this", "it" without clear referent)
+
+4. **Check tone consistency**: Against --tone flag or inferred tone:
+   - `formal`: No contractions, no colloquialisms, third person
+   - `casual`: Contractions OK, direct address (you/we), conversational
+   - `technical`: Precise terminology, no anthropomorphism, specification-style
+   - Flag any sections that deviate from the target tone
+   - Note if tone shifts are intentional (e.g., callout boxes)
+
+5. **Check terminology**: Verify consistent term usage:
+   - Build a glossary of domain terms used in the document
+   - Flag synonyms used interchangeably (user/customer/client — pick one)
+   - Verify capitalization consistency for product names and features
+   - Check abbreviation introduction (first use should be spelled out)
+   - Cross-reference with CONVENTIONS.md terminology if available
+
+6. **Score readability**: Compute metrics:
+   - Average sentence length (target: 15-20 words)
+   - Average paragraph length (target: 3-5 sentences)
+   - Flesch-Kincaid grade level (target depends on audience)
+   - Percentage of passive voice (target: <15%)
+   - Jargon density (specialized terms per 100 words)
+
+7. **Check formatting**: Verify structural consistency:
+   - Heading hierarchy (no skipped levels)
+   - List formatting (parallel structure within lists)
+   - Code block syntax highlighting language tags
+   - Link text is descriptive (not "click here")
+   - Consistent use of bold/italic/code formatting
+
+8. **Report findings**: If --fix is NOT set, output a structured report:
+   - Summary statistics (word count, readability score, issue count by severity)
+   - Issues grouped by type (grammar, clarity, tone, terminology)
+   - Each issue: line number, original text, suggested fix, severity (error/warning/style)
+   - Top 3 most impactful improvements to make
+
+9. **Apply fixes**: If --fix IS set:
+   - Apply all error-severity fixes automatically
+   - Apply warning-severity fixes automatically
+   - Present style-level suggestions for user approval
+   - Show a diff summary of all changes made
+   - Preserve the author's voice — improve, don't rewrite
+
+10. **Final assessment**: Provide an overall quality rating:
+    - Grade: A (publish-ready) / B (minor polish needed) / C (significant editing needed) / D (rewrite recommended)
+    - Strengths of the writing (what works well)
+    - Top 3 areas for improvement
+    - Estimated time to address remaining issues
+</process>

package/.agent/mindforge/publish-skill.md

@@ -0,0 +1,23 @@
+---
+description: Publish a skill to the npm registry (or private registry).
+---
+
+# MindForge — Publish Skill Command
+# Usage: /mindforge:publish-skill [skill-dir] [--registry URL] [--dry-run]
+
+Publish a skill to the npm registry (or private registry).
+
+Pre-publication checklist:
+1. Run full skill validation (Level 1 + 2 + 3 from skill-validator.md)
+   Fail if Level 1 or 2 fails. Warn if Level 3 fails.
+2. Verify package.json has `mindforge` field with all required sub-fields
+3. Verify CHANGELOG.md has an entry for the current version
+4. Check if version already published: `npm info [package-name]@[version]`
+   If already published: error "Version already exists. Bump the version."
+5. Run `npm pack --dry-run` to preview what will be published
+6. Confirm with user: "These files will be published: [list]. Proceed? (yes/no)"
+7. If --dry-run: stop here, show preview only
+8. Publish: `npm publish --access public`
+9. Verify: `npm info [package-name]@[version]` — confirm publication succeeded
+10. Write AUDIT: `{ "event": "skill_published", "package": "...", "version": "..." }`
+11. Report: "✅ [package-name]@[version] published to npm registry"

package/.agent/mindforge/push-notify.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:push-notify
+description: "Design push notification architecture. Usage: /mindforge:push-notify [channel] [--platform ios|android|web] [--priority high|normal|low]"
+argument-hint: "[channel] [--platform ios|android|web] [--priority high|normal|low]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design push notification systems with platform-specific optimizations, delivery guarantees, user preference management, and A/B testing capabilities.
+</objective>
+
+<execution_context>
+@.mindforge/skills/push-notification-architecture/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/push-notification-architecture/`
+State: Designs notification delivery pipeline, platform integration (APNS/FCM), segmentation rules, opt-in flows, and analytics tracking.
+</context>
+
+<process>
+1. **Platform Integration**: iOS (APNs, certificates or token-based auth, silent/regular notifications). Android (FCM, priority handling, notification channels). Web (Push API, VAPID keys, service worker required). Use vendor SDKs (OneSignal, Pusher, Firebase) or direct APIs.
+
+2. **Delivery Architecture**: Queue-based system (SQS, RabbitMQ). Worker processes consume queue. Batch sends (1000/request). Exponential backoff on failure. Dead-letter queue for permanent failures. Monitor send rate and latency.
+
+3. **User Preferences**: Opt-in prompt timing (after first value delivered, not immediately). Granular channels (promotions, updates, transactional). Quiet hours (no notifications 10pm-8am). Frequency caps (max 3/day). Persistent preferences in user profile.
+
+4. **Personalization**: User segmentation (behavior, demographics, device). Dynamic content (name, location, recent activity). A/B testing (message variants, send times). Predictive send time optimization. Track conversion per variant.
+
+5. **Rich Notifications**: Images/videos in notification. Action buttons (reply, snooze, deep link). Grouped notifications (conversation threads). Badge count management. Sound/vibration customization. Lock screen vs notification center.
+
+6. **Analytics**: Delivery rate (sent vs delivered). Open rate (by platform, time, segment). Conversion rate (notification → action). Opt-out tracking (which channels). Notification fatigue metrics (declining engagement over time).
+
+7. **Compliance**: GDPR (explicit consent, right to withdraw). CAN-SPAM (transactional vs promotional). Time-sensitive (medical, financial) vs marketing. Unsubscribe mechanism. Audit log of sends. Rate limiting to prevent spam.
+</process>

package/.agent/mindforge/pwa.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:pwa
+description: "Progressive Web App design. Usage: /mindforge:pwa [app] [--cache networkfirst|cachefirst|stale] [--scope full|partial]"
+argument-hint: "[app] [--cache networkfirst|cachefirst|stale] [--scope full|partial]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design Progressive Web Apps with service worker caching strategies, offline capabilities, install prompts, and native-like experiences on web.
+</objective>
+
+<execution_context>
+@.mindforge/skills/progressive-web-app/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/progressive-web-app/`
+State: Designs service worker architecture, caching strategies, manifest configuration, and progressive enhancement patterns for installable web apps.
+</context>
+
+<process>
+1. **Service Worker Strategy**: Network-first (fresh data, fallback to cache) → news apps. Cache-first (performance, stale data OK) → static assets, docs. Stale-while-revalidate (instant + fresh) → social feeds. Network-only → auth endpoints. Cache-only → app shell.
+
+2. **Caching Layers**: App shell (HTML/CSS/JS core, precache on install). Static assets (images/fonts, long cache TTL). API responses (runtime cache, short TTL). User content (IndexedDB for structured data). Max 50MB quota (mobile browsers).
+
+3. **Offline UX**: Detect offline with navigator.onLine. Show offline indicator. Queue mutations (background sync API). Cached content with freshness timestamp. Graceful feature degradation. Custom offline page.
+
+4. **Install Experience**: Manifest.json (name, icons, theme_color, display:standalone). Defer install prompt (show after user engagement). A2HS (Add to Home Screen) button. Track install analytics. Update prompt when new version available.
+
+5. **Performance**: Lighthouse score >90. First Contentful Paint <1.8s. Time to Interactive <3.5s. Cumulative Layout Shift <0.1. Code splitting. Lazy load images. Preload critical resources.
+
+6. **Platform Features**: Push notifications (with user permission). Background sync (retry failed requests). Share target (receive shared content). Shortcuts (quick actions in app icon menu). Badging API (unread count).
+
+7. **Update Strategy**: Skip waiting for critical updates. Prompt user for non-critical updates. Version in cache names. Migration logic for schema changes. Test update flow in CI. Monitor update adoption rate.
+</process>

package/.agent/mindforge/qa.md

@@ -0,0 +1,20 @@
+---
+description: @mindforge qa [--phase N] [--auto]
+---
+
+# /mindforge:qa
+
+## Usage
+`@mindforge qa [--phase N] [--auto]`
+
+## Description
+Runs systematic visual QA on UI surfaces changed in the current phase.
+Analyzes git diff to find pages, navigates to them, and looks for errors.
+
+## Options
+- `--phase N`: Target specific phase for reporting (defaults to current).
+- `--auto`: Automatically run after successful wave execution if configured.
+
+## Output
+- `QA-REPORT-[N].md`: Found bugs with screenshots.
+- `tests/regression/*.test.ts`: Playwright tests to prevent bug recurrence.

package/.agent/mindforge/quality-audit.md

@@ -0,0 +1,34 @@
+---
+description: Run weighted 4-dimension quality scoring on current output. Usage - /mindforge:quality-audit [target] [--mode quick|full|comparative] [--compare path]
+---
+
+<objective>
+Score output quality across four weighted dimensions (Clarity, Completeness,
+Accuracy, Usefulness) with a blocking accuracy gate.
+</objective>
+
+<execution_context>
+@.mindforge/skills/quality-audit/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse target (file/diff/output to evaluate) and mode (default: full).
+2. If --mode quick: evaluate Accuracy dimension only (fast gate check).
+3. If --mode full: evaluate all 4 dimensions.
+4. If --mode comparative: load --compare target, score BOTH, produce delta.
+5. For each dimension, score 1-5 with specific evidence citations:
+   - Clarity (25%): Is it understandable? Unambiguous? Well-structured?
+   - Completeness (25%): Does it cover all requirements? Any gaps?
+   - Accuracy (30%): Is it factually correct? Do code refs exist? Do examples work?
+   - Usefulness (20%): Does it solve the actual problem? Is it actionable?
+6. Compute weighted average: (clarity*0.25 + completeness*0.25 + accuracy*0.30 + usefulness*0.20).
+7. Check blocking gate: if accuracy < 3.0 → FAIL regardless of other scores.
+8. Determine verdict: weighted avg >= 3.0 AND accuracy >= 3.0 → PASS.
+9. Report per-dimension scores, weighted average, verdict, and evidence.
+10. If comparative: show side-by-side scores with improvement/regression indicators.
+11. Log quality audit in AUDIT.
+</process>

package/.agent/mindforge/queue.md

@@ -0,0 +1,31 @@
+---
+description: Design message queue topology and broker selection. Usage - /mindforge:queue [domain] [--broker kafka|rabbitmq|sqs] [--pattern fanout|topic|p2p]
+---
+
+<objective>
+Design a message queue topology that selects the right broker for the workload,
+configures routing patterns for decoupled communication, implements dead-letter
+handling for poison messages, and provides observability into queue depth,
+consumer throughput, and delivery guarantees.
+</objective>
+
+<execution_context>
+@.mindforge/skills/queue-design/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Identify messaging needs by analyzing the domain: message volume (msgs/sec), payload size, ordering requirements, delivery guarantee (at-most-once, at-least-once, exactly-once), and retention period. Classify as command (point-to-point) or event (broadcast).
+2. Select broker based on --broker flag or requirements: Kafka for high-throughput ordered event streams with replay, RabbitMQ for complex routing with flexible patterns and low-latency RPC, SQS for serverless with minimal ops overhead. Document selection rationale.
+3. Design topic/queue topology based on --pattern: fanout (all consumers receive all messages), topic (content-based routing with wildcards), point-to-point (single consumer per message). Map domain events to topics/exchanges with clear naming conventions.
+4. Configure consumers: competing consumers for horizontal scaling (consumer groups), broadcast consumers for event notification, and exclusive consumers for ordered processing. Set prefetch count and acknowledgment mode.
+5. Set TTL and dead-letter queue (DLQ) policies: define message expiration per queue, max delivery attempts before DLQ routing, DLQ retention period, and DLQ monitoring with alerting on depth > 0. Implement DLQ replay tooling.
+6. Plan partition strategy (Kafka) or queue sharding (RabbitMQ): partition by entity key for ordering, configure replication factor for durability, set min-ISR for write safety. For SQS, configure visibility timeout and batch size.
+7. Configure monitoring and alerting: track queue depth, consumer lag, publish/consume rates, unacknowledged messages, and DLQ depth. Set alerts on queue depth exceeding 10x normal and consumer lag exceeding processing SLA.
+8. Document message schemas: define payload contracts (JSON Schema or Avro), versioning strategy (envelope with schema_version field), backward/forward compatibility rules, and schema registry integration.
+9. Design retry and error handling: exponential backoff with jitter for transient failures, circuit breaker for downstream unavailability, poison message detection (fail count > threshold), and manual intervention workflow for unprocessable messages.
+10. Log queue design decision in AUDIT with: domain, broker, pattern, throughput target, delivery guarantee, DLQ policy, and partition count.
+</process>

package/.agent/mindforge/quick.md

@@ -0,0 +1,139 @@
+---
+description: Use QUICK for:
+---
+
+# MindForge — Quick Command
+# Usage: /mindforge:quick [--research] [--review] [--full]
+# For ad-hoc tasks that don't need full lifecycle management.
+
+## When to use quick vs plan-phase
+Use QUICK for:
+- Bug fixes not tied to a current phase
+- Small improvements (< 3 files, < 2 hours)
+- Dependency updates
+- Documentation corrections
+- One-off scripts or utilities
+
+Use PLAN-PHASE for:
+- Feature development
+- Anything touching more than 6 files
+- Anything requiring research before implementation
+- Anything with external dependencies or stakeholder requirements
+
+## Step 1 — Task intake
+
+Ask the user:
+"What do you want to do?"
+
+Listen to the description. If the task sounds larger than "quick" scope
+(more than 6 files, architectural change, new feature), say:
+"This sounds like more than a quick task. I recommend using /mindforge:plan-phase
+ instead to ensure it's properly planned and verified. Want to proceed with quick anyway?"
+
+## Step 2 — Optional research (--research flag or user requests it)
+
+If `--research` is provided or the task involves unfamiliar libraries:
+Spawn a focused research subagent. Give it:
+- The task description
+- The current tech stack from PROJECT.md
+Ask it to: investigate the best approach, identify gotchas, recommend specific
+libraries (with versions), and write a brief research note.
+
+Report research findings to the user before proceeding.
+
+## Step 3 — Create a quick plan
+
+### Sequential quick task numbering
+Determine the next quick task number by scanning `.planning/quick/`:
+1. List directories matching `[0-9][0-9][0-9]-*`
+2. Take the max numeric prefix and add 1 (start at 001 if none exist)
+3. If a directory already exists for the chosen number, require `--force` to proceed
+
+Create `.planning/quick/[NNN]-[slug]/PLAN.md` where NNN is a sequential number
+and slug is a 2-4 word kebab-case description.
+
+Example: `.planning/quick/001-fix-login-null-check/PLAN.md`
+
+Use the standard XML plan format:
+```xml
+<task type="quick">
+  <n>[task name]</n>
+  <persona>[appropriate persona]</persona>
+  <files>[files to touch]</files>
+  <context>[relevant context]</context>
+  <action>[implementation instructions]</action>
+  <verify>[verification command]</verify>
+  <done>[definition of done]</done>
+</task>
+```
+
+Show the plan to the user. Wait for approval before executing.
+
+## Step 4 — Execute the quick plan
+
+### Security auto-trigger (mandatory)
+Before execution, scan the task description and files for security keywords:
+auth, authentication, login, password, token, JWT, session, payment, PII, upload,
+credential, secret, key.
+
+If any keyword matches: load `security-review/SKILL.md` and activate
+`security-reviewer.md` persona for the implementation. This is required even
+without the `--full` flag.
+
+1. Load persona from `.mindforge/personas/`
+2. Load any relevant skills based on task keywords
+3. Execute the plan
+4. Run `<verify>` — must pass before committing
+5. Commit: `[type](quick/[NNN]): [task name]`
+6. Write `.planning/quick/[NNN]-[slug]/SUMMARY.md`
+
+### STATE.md update policy
+Quick tasks do not change phase status. If there is no active phase, note the
+quick task completion in STATE.md under "Last completed task".
+
+## Step 5 — Optional review (--review flag)
+
+If `--review` is provided:
+Activate `code-quality.md` skill on the diff.
+Report any issues before committing.
+If BLOCKING issues found: fix before commit.
+
+## Step 6 — Optional full mode (--full flag)
+
+If `--full` is provided, additionally:
+- Run the project's full test suite (not just task-specific verify)
+- Run the type checker and linter
+- Activate `security-reviewer.md` if the task touches any security-sensitive code
+- Write an AUDIT entry for the quick task
+
+## Linting always runs
+Regardless of flags, after every quick task execution:
+1. Run the project's linter (from CONVENTIONS.md — check which linter applies)
+2. If lint errors found: fix them before committing.
+3. Linting is not part of `--full` — it is always part of quick.
+
+## Flags are composable
+```
+/mindforge:quick                     # minimal — task, plan, execute
+/mindforge:quick --research          # adds domain research step
+/mindforge:quick --review            # adds code quality review of diff
+/mindforge:quick --full              # adds full test suite + linting + security
+/mindforge:quick --research --full   # all of the above
+```
+
+## AUDIT entry for quick tasks
+```json
+{
+  "id": "uuid",
+  "timestamp": "ISO-8601",
+  "event": "quick_task_completed",
+  "agent": "mindforge-orchestrator",
+  "phase": null,
+  "session_id": "sess_abc",
+  "quick_id": "001",
+  "task_name": "Fix login null check",
+  "commit_sha": "abc1234",
+  "files_changed": ["src/auth/login.ts"],
+  "flags_used": ["--review"]
+}
+```

package/.agent/mindforge/rag.md

@@ -0,0 +1,30 @@
+---
+description: Design RAG pipeline architecture with chunking and retrieval. Usage - /mindforge:rag [corpus] [--chunking semantic|fixed] [--retrieval hybrid] [--rerank]
+---
+
+<objective>
+Design a production RAG (Retrieval-Augmented Generation) pipeline with optimized
+chunking, hybrid retrieval, and re-ranking. Covers corpus ingestion, embedding
+strategy, retrieval quality evaluation, and context window packing.
+</objective>
+
+<execution_context>
+@.mindforge/skills/rag-architecture/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Analyze the corpus: document types (PDF, markdown, code, HTML), average document length, structure (headings, tables, code blocks), and total size. Identify natural semantic boundaries.
+2. Choose chunking strategy based on --chunking flag: semantic (split at paragraph/section boundaries, variable size 200-1000 tokens) or fixed (512 tokens with 50-token overlap). For code: chunk at function/class boundaries.
+3. Select embedding model based on corpus domain and latency requirements: OpenAI text-embedding-3-large (general, high quality), Cohere embed-v3 (multilingual), or local (BAAI/bge-large for privacy). Benchmark on domain-specific queries.
+4. Configure retrieval strategy based on --retrieval flag: dense-only (vector similarity), sparse-only (BM25/TF-IDF), or hybrid (dense + sparse with Reciprocal Rank Fusion, alpha=0.7 dense weight). Hybrid recommended for most cases.
+5. Add re-ranking if --rerank flag is set: retrieve top-50 candidates with fast retrieval, then re-rank with cross-encoder (ms-marco-MiniLM or Cohere rerank-v3) to get top-k (k=5-10). Dramatically improves precision.
+6. Design context packing strategy: order chunks by relevance, fit within context window budget (reserve 30% for generation), deduplicate overlapping chunks, and include metadata (source, page, section title).
+7. Set up evaluation pipeline: measure recall@k (are relevant chunks in top-k?), MRR (Mean Reciprocal Rank), and end-to-end answer quality. Build a golden test set of 50+ query-answer pairs with source attribution.
+8. Iterate on retrieval quality: tune chunk size, overlap, embedding model, retrieval weights, and re-ranker threshold. Use evaluation metrics to drive decisions. Target recall@10 > 0.9 on golden set.
+9. Design the ingestion pipeline: document parsing, chunking, embedding generation, vector store upsert. Handle incremental updates (add/modify/delete documents) without full re-index.
+10. Log rag invocation in AUDIT with: corpus size, chunking strategy, embedding model, retrieval method, evaluation metrics (recall@k, MRR).
+</process>

package/.agent/mindforge/rate-limit.md

@@ -0,0 +1,31 @@
+---
+description: Design rate limiting strategy with per-tenant quotas. Usage - /mindforge:rate-limit [api] [--algorithm token-bucket|sliding-window] [--per-tenant]
+---
+
+<objective>
+Design a rate limiting strategy that protects the API from abuse, implements
+fair per-tenant quotas across pricing tiers, uses distributed counters for
+horizontal scaling, and provides clear feedback to clients via standard
+rate limit headers with burst allowance for legitimate traffic spikes.
+</objective>
+
+<execution_context>
+@.mindforge/skills/rate-limiting-design/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Choose algorithm based on --algorithm flag: token bucket (allows bursts up to bucket size, refills at steady rate — best for APIs with bursty traffic), sliding window log (precise per-window counting — best for strict compliance), or sliding window counter (approximation with lower memory — best for high-volume APIs). Document trade-offs.
+2. Define limits per pricing tier: free tier (100 req/min, 1000 req/day), pro tier (1000 req/min, 50000 req/day), enterprise tier (10000 req/min, unlimited daily with fair-use policy). Set per-endpoint overrides for expensive operations (e.g., search: 10 req/min free).
+3. Implement distributed counter using Redis: MULTI/EXEC for atomic increment + TTL, use sorted sets for sliding window, or Lua scripts for token bucket. Ensure counter survives Redis restart (persistence) and handle Redis unavailability (fail-open with local fallback).
+4. Configure standard rate limit headers on every response: X-RateLimit-Limit (max requests), X-RateLimit-Remaining (requests left), X-RateLimit-Reset (UTC epoch when window resets), and Retry-After (seconds to wait on 429). Return 429 Too Many Requests with JSON error body.
+5. Handle burst allowance: configure token bucket capacity at 2x the per-second rate (e.g., 100 req/min = 1.67/sec steady, allow burst of 3/sec). Document burst behavior in API docs so clients can optimize request timing.
+6. Set up bypass for internal services: whitelist internal service accounts by API key prefix, implement separate limits for service-to-service calls (10x user limits), and add request header (X-Internal-Service) for observability without bypassing auth.
+7. Add adaptive rate limiting for incidents: automatically reduce limits by 50% when error rate exceeds 5% or latency exceeds 2x baseline. Implement gradual restoration over 5 minutes after recovery. Log all adaptive changes.
+8. Monitor and alert on quota exhaustion: track 429 response rate per tenant, alert when any tenant consistently hits limits (potential abuse or under-provisioned tier), dashboard showing top consumers, and weekly report of tenants approaching upgrade thresholds.
+9. Design rate limit key composition: combine tenant_id + endpoint + time_window for per-tenant per-endpoint limiting. Support IP-based limiting for unauthenticated endpoints and geographic limiting for compliance (e.g., different limits per region).
+10. Log rate limiting design in AUDIT with: API, algorithm, tier definitions, burst policy, bypass rules, adaptive thresholds, and monitoring configuration.
+</process>

package/.agent/mindforge/react-native.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:react-native
+description: "React Native specific architecture guidance. Usage: /mindforge:react-native [feature] [--arch new|legacy] [--state redux|zustand|jotai]"
+argument-hint: "[feature] [--arch new|legacy] [--state redux|zustand|jotai]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design React Native apps using New Architecture (Fabric + TurboModules) with optimal bundle size, native module patterns, and JS-to-native bridge optimization.
+</objective>
+
+<execution_context>
+@.mindforge/skills/react-native-patterns/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/react-native-patterns/`
+State: Evaluates RN version, recommends migration to New Architecture, designs state management, native module integration, and performance optimization strategies.
+</context>
+
+<process>
+1. **New Architecture Migration**: Fabric (concurrent renderer) enables priority-based rendering. TurboModules (lazy-loaded native modules) reduce startup time. JSI (direct JS-to-native binding) eliminates bridge bottleneck. Migrate incrementally (interop mode), test thoroughly (some libraries not yet compatible).
+
+2. **State Management**: Redux → full-featured but verbose, good for complex apps. Zustand → minimal API, better DevEx, sufficient for most apps. Jotai → atomic state, excellent for derived state. React Context → avoid for frequently changing global state (causes re-renders). Choose based on team familiarity and app complexity.
+
+3. **Bundle Optimization**: Enable Hermes engine (faster startup, smaller bundle). Use inline requires (lazy load screens). RAM bundles for faster initial load. Tree shake unused dependencies. Monitor bundle with react-native-bundle-visualizer.
+
+4. **Native Module Patterns**: Write TurboModules for performance-critical code (image processing, encryption). Use codegen for type-safe JS-Native interface. Handle threading correctly (UI thread vs background). Implement proper error boundaries.
+
+5. **Navigation**: Use React Navigation v6+ (native-stack for performance). Pre-load screens with useFocusEffect. Handle deep linking. Implement proper back button behavior. Optimize tab bar (defer rendering of inactive tabs).
+
+6. **Performance**: Use FlashList over FlatList (better performance). Memoize components with React.memo. Avoid anonymous functions in render. Use Reanimated for 60fps animations. Profile with Systrace/Instruments.
+
+7. **Testing**: Jest for unit/integration tests. Detox for E2E. Snapshot testing for UI consistency. Mock native modules properly. CI runs tests on real devices (not just simulators).
+</process>

package/.agent/mindforge/realtime-analytics.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:realtime-analytics
+description: "Design real-time analytics backend. Usage: /mindforge:realtime-analytics [domain] [--engine clickhouse|druid|pinot] [--latency sub-second|seconds]"
+argument-hint: "[domain] [--engine clickhouse|druid|pinot] [--latency sub-second|seconds]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive realtime-analytics system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/real-time-analytics/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/real-time-analytics/`
+State: Analyzes requirements, constraints, and scale to generate optimized realtime-analytics architecture.
+</context>
+
+<process>
+1. **Requirement Analysis**: Analyze domain-specific requirements, performance constraints, and scalability needs.
+2. **Architecture Design**: Design system architecture with component interaction patterns and data flow.
+3. **Technology Selection**: Evaluate and select appropriate technologies, tools, and frameworks.
+4. **Integration Strategy**: Define integration patterns with existing systems and external dependencies.
+5. **Optimization Approach**: Implement performance, cost, and resource optimization strategies.
+6. **Monitoring Framework**: Design observability, alerting, and debugging mechanisms.
+7. **Deployment Planning**: Create deployment strategy with rollback procedures and disaster recovery.
+</process>

package/.agent/mindforge/record-learning.md

@@ -0,0 +1,22 @@
+---
+description: Append a new Learning Entry to the Evolution Log in AGENTS_LEARNING.md
+---
+
+# /mindforge:record-learning
+
+Append a new Learning Entry to the `Evolution Log`. Recording learnings regularly is a MANDATORY practice to build project intelligence.
+
+## Usage
+
+`/mindforge:record-learning`
+
+This command initiates a session-end recording. You should provide details on:
+- **Context**: What task was being performed.
+- **Mistake**: What went wrong.
+- **Root Cause**: Why it happened.
+- **Fix**: What was done.
+- **Prevention Rule**: Rule to avoid this in the future.
+- **Category**: (Best Practice, Anti-Pattern, Bug Fix, Architecture).
+
+## Example
+Run after a complex debugging session to capture the root cause and the specific engineering oversight to prevent it from happening again.

package/.agent/mindforge/release.md

@@ -0,0 +1,14 @@
+---
+description: Execute the complete MindForge v1.0.0 (or any version) release pipeline.
+---
+
+# MindForge — Release Command
+# Usage: /mindforge:release [--version X.Y.Z] [--dry-run] [--checklist-only]
+# ⚠️  This command is for releasing the MindForge framework itself.
+#     For releasing your project phases, use /mindforge:ship instead.
+
+## Purpose
+Execute the complete MindForge v1.0.0 (or any version) release pipeline.
+Intended for the MindForge core team.
+
+## Gate: Production Readiness Checklist

package/.agent/mindforge/remember.md

@@ -0,0 +1,30 @@
+---
+description: Manage the MindForge long-term memory (knowledge graph).
+---
+
+# /mindforge:remember
+
+Manage the MindForge long-term memory (knowledge graph).
+
+## Usage
+
+- Add an entry:
+  ```bash
+  node bin/mindforge-cli.js remember --add "Your knowledge" --topic "Title"
+  ```
+- Search memories:
+  ```bash
+  node bin/mindforge-cli.js remember --search "query" --global
+  ```
+- View statistics:
+  ```bash
+  node bin/mindforge-cli.js remember --stats
+  ```
+- Promote to global:
+  ```bash
+  node bin/mindforge-cli.js remember --promote "id"
+  ```
+
+## Description
+
+MindForge capture, stores, and retrieves knowledge (architectural decisions, code patterns, team preferences) across all sessions and projects. This command allows for manual management and querying of this data.

package/.agent/mindforge/research.md

@@ -0,0 +1,16 @@
+---
+description: Deep research using Gemini 1.5 Pro's 1-million-token context window.
+---
+
+# MindForge v2 — Research Command
+# Usage: /mindforge:research [topic] [--type general|library|codebase|compliance] [--url URL]
+
+## Purpose
+Deep research using Gemini 1.5 Pro's 1-million-token context window.
+Uses **Context7 MCP** as the primary engine for real-time documentation and code example retrieval.
+
+## Capabilities
+- Ingest full library documentation via Context7.
+- Codebase-wide architectural analysis.
+- Regulatory compliance audits.
+- Real-time resolution of version-specific API contracts.