mindforge-cc 11.3.0 → 11.3.1

package/.claude/commands/mindforge/microservices.md

@@ -0,0 +1,64 @@
+---
+description: "Design microservice boundaries, API contracts, and communication patterns. Usage: /mindforge:microservices [component] [--style event-driven|request-reply]"
+---
+
+<objective>
+Decompose a system into well-bounded microservices with clearly defined API contracts, communication patterns, and saga orchestration. Ensures no circular dependencies and validates domain alignment.
+</objective>
+
+<execution_context>
+@.mindforge/skills/microservices-patterns/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (target component or domain area, optional --style flag)
+Knowledge: Domain model from ARCHITECTURE.md, bounded contexts, existing service inventory.
+</context>
+
+<process>
+1. **Identify domain boundaries**: Analyze the target component against the domain model. Map nouns to aggregates, verbs to commands/events. List candidate service boundaries.
+
+2. **Define bounded contexts**: For each candidate service, define its bounded context — what data it owns, what language it uses, what invariants it enforces. Write context map showing relationships (Shared Kernel, Customer-Supplier, Conformist, ACL).
+
+3. **Design API contracts**: For each service boundary, define the public API contract:
+   - REST endpoints (OpenAPI 3.1 schema) or gRPC proto definitions
+   - Request/response types with validation rules (Zod schemas)
+   - Versioning strategy (URL path vs header)
+   - Error contract (RFC 7807 Problem Details)
+
+4. **Choose communication style**: Based on `--style` flag or inferred from requirements:
+   - `event-driven`: Define event schemas, topic naming, ordering guarantees, idempotency keys
+   - `request-reply`: Define sync call chains, circuit breaker placement, timeout budgets
+   - Hybrid: identify which interactions need sync vs async
+
+5. **Document saga flows**: For operations spanning multiple services, design compensation-based sagas:
+   - Sequence diagram for happy path
+   - Compensation steps for each failure point
+   - Saga orchestrator vs choreography decision with rationale
+
+6. **Define data ownership**: Each service owns its data store. Document:
+   - Which entities belong to which service
+   - How cross-service queries are resolved (API composition, CQRS read models, event sourcing)
+   - Data consistency model (eventual vs strong, per boundary)
+
+7. **Validate no circular dependencies**: Build a directed dependency graph of all services. Run topological sort — if it fails, circular dependency exists. Propose resolution (extract shared service, merge services, or introduce event-based decoupling).
+
+8. **Design resilience patterns**: For each inter-service call:
+   - Circuit breaker configuration (thresholds, half-open behavior)
+   - Retry policy (exponential backoff, max attempts, jitter)
+   - Bulkhead isolation (thread pool or semaphore)
+   - Timeout budget allocation across the call chain
+
+9. **Output service catalog**: Write a structured service catalog document containing:
+   - Service name, owner, bounded context
+   - Public API summary
+   - Dependencies (upstream/downstream)
+   - Communication style per dependency
+   - Data store type and ownership
+
+10. **Verify alignment**: Cross-reference the decomposition against:
+    - Team structure (Conway's Law alignment)
+    - Deployment independence (can each service deploy without coordinating?)
+    - Failure isolation (does one service failure cascade?)
+    Report any violations with recommended fixes.
+</process>

package/.claude/commands/mindforge/migrate.md

@@ -0,0 +1,44 @@
+---
+description: Run explicit schema migrations for .planning/ files.
+---
+
+# MindForge — Migrate Command
+# Usage: /mindforge:migrate [--from X.Y.Z] [--to X.Y.Z] [--dry-run] [--force]
+
+## Purpose
+Run explicit schema migrations for .planning/ files.
+Normally triggered automatically by /mindforge:update.
+Use this command manually when: auto-migration failed, manual version jump, recovery.
+
+## Flow
+
+### Auto-detect migration need
+Read `schema_version` from HANDOFF.json.
+Compare against current `package.json` version.
+Determine migration path.
+
+### Dry-run mode (--dry-run)
+Show: which migrations would run, what each changes.
+Show: breaking changes for the migration path.
+Make NO changes to any file.
+
+### Backup first
+Before any changes: create `.planning/migration-backup-[timestamp]/`
+Verify backup integrity (file count, non-empty).
+If backup fails: ABORT. Explain disk space issue.
+
+### Execute migrations
+Run `node bin/migrations/migrate.js`.
+Show progress for each migration.
+If any migration fails: auto-restore from backup.
+
+### Verify
+Run /mindforge:health after migration.
+If health errors: report with specific fix instructions.
+Preserve backup until user is satisfied — they must delete it manually.
+
+## Manual version override
+`/mindforge:migrate --from 0.1.0 --to 1.0.0` — forces migration between specified versions.
+Use with care: intended for recovery scenarios where HANDOFF.json schema_version is wrong.
+
+## AUDIT entry

package/.claude/commands/mindforge/migration-mgmt.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:migration-mgmt
+description: "Design migration orchestration platform. Usage: /mindforge:migration-mgmt [scope] [--type schema|data|infrastructure] [--downtime zero|planned]"
+argument-hint: "[scope] [--type schema|data|infrastructure] [--downtime zero|planned]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive migration-mgmt system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/migration-platform/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/migration-platform/`
+State: Analyzes requirements, constraints, and scale to generate optimized migration-mgmt 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/.claude/commands/mindforge/milestone.md

@@ -0,0 +1,16 @@
+---
+description: Create or update a milestone definition in .planning/milestones/ and track the
+---
+
+Create or update a milestone definition in `.planning/milestones/` and track the
+ health of grouped phases. Usage: `/mindforge:milestone <name> [phase list]`
+
+## Outputs
+- milestone document with included phases
+- health summary (on track, at risk, blocked)
+- linked approvals, blockers, and verification status
+
+## Health rules
+- any blocked phase makes the milestone at risk
+- missing verification keeps milestone status yellow
+- completed verified phases count toward release readiness

package/.claude/commands/mindforge/mobile.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:mobile
+description: "Design mobile app architecture. Usage: /mindforge:mobile [app] [--platform ios|android|cross] [--framework rn|flutter|native]"
+argument-hint: "[app] [--platform ios|android|cross] [--framework rn|flutter|native]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design mobile-first architectures that balance native performance with cross-platform developer velocity. Addresses offline-first, app size, battery optimization, and platform-specific patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/mobile-performance/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/mobile-performance/`
+State: Analyzes target platforms, performance requirements, team expertise to recommend architecture (native/hybrid/cross-platform) with specific implementation patterns.
+</context>
+
+<process>
+1. **Platform Strategy**: Single platform (iOS or Android native, best performance) vs Cross-platform (React Native/Flutter, 70% code sharing). Consider team skills (Swift/Kotlin vs JS/Dart), time-to-market, performance needs (gaming/AR → native, content apps → cross-platform).
+
+2. **Architecture Pattern**: MV* pattern selection (MVVM for iOS, MVP for Android, BLoC for Flutter, Redux for React Native). Layer separation (UI/Business Logic/Data). Navigation architecture (stack-based, tab-based, drawer). State management (local vs global, persistence strategy).
+
+3. **Performance Optimization**: App size budget (<50MB for emerging markets). Launch time target (<2s cold start). Frame rate (maintain 60fps scrolling). Battery impact (background tasks, network polling, location tracking). Memory management (image caching, list virtualization).
+
+4. **Offline-First Design**: Local database (SQLite, Realm, WatermelonDB). Sync strategy (optimistic UI, conflict resolution). Queue outgoing requests. Cache images/assets. Handle network transitions gracefully.
+
+5. **Native Integration**: Bridge patterns for platform-specific features (camera, biometrics, push notifications). Third-party SDK integration (analytics, crash reporting). App extensions (widgets, share extensions, Siri shortcuts).
+
+6. **Testing Strategy**: Unit tests (business logic, data layer). UI tests (critical user flows). Screenshot tests (visual regression). Device matrix testing (5-10 representative devices). Performance benchmarking (startup time, frame drops).
+
+7. **Release Pipeline**: CI/CD setup (Fastlane, Bitrise, GitHub Actions). Code signing automation. Beta distribution (TestFlight, Firebase App Distribution). Staged rollout (5% → 25% → 100%). Crash monitoring with auto-rollback triggers.
+</process>

package/.claude/commands/mindforge/monorepo.md

@@ -0,0 +1,30 @@
+---
+description: Set up monorepo with task pipelines. Usage - /mindforge:monorepo [--tool nx|turborepo] [--packages N]
+---
+
+<objective>
+Design and configure a monorepo architecture with efficient task pipelines,
+dependency-aware build ordering, and intelligent caching. Optimizes for
+developer velocity while maintaining clear package boundaries.
+</objective>
+
+<execution_context>
+@.mindforge/skills/monorepo-management/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Choose the monorepo tool based on --tool flag or project needs. Nx for larger projects needing computation caching and module federation; Turborepo for simpler pipeline orchestration with minimal config.
+2. Define workspace structure: separate `apps/` (deployable applications) from `packages/` (shared libraries). Establish naming conventions and package scoping (@org/package-name).
+3. Configure the task pipeline with dependency relationships — build depends on ^build (dependencies first), test depends on ^build, lint runs in parallel with no dependencies.
+4. Set up affected analysis so only packages impacted by a change are built/tested. Configure the base branch for comparison and ignore patterns (docs, README).
+5. Configure caching at two levels: local cache (filesystem, immediate hits on repeated runs) and remote cache (shared across team/CI for cross-machine cache hits).
+6. Define package boundaries and enforce them: no circular dependencies, explicit public API exports, lint rules preventing deep imports across package boundaries.
+7. Set up publishing workflow for shared packages: conventional commits, automated versioning (independent or fixed), changelog generation, and npm/registry publishing.
+8. Configure CI to leverage affected analysis and remote cache — skip unchanged packages, parallelize independent tasks, fail fast on first error.
+9. Document the monorepo conventions: how to add a new package, how to add cross-package dependencies, how to run tasks for specific packages, and troubleshooting cache misses.
+10. Log monorepo invocation in AUDIT with: tool selected, package count, cache strategy, pipeline definition.
+</process>

package/.claude/commands/mindforge/multi-tenant.md

@@ -0,0 +1,31 @@
+---
+description: Design multi-tenancy isolation strategy. Usage - /mindforge:multi-tenant [app] [--isolation rls|schema|database] [--routing subdomain|header]
+---
+
+<objective>
+Design a multi-tenancy architecture that provides appropriate data isolation
+based on regulatory and security requirements, implements tenant context
+propagation through all layers, prevents data leakage between tenants,
+and supports efficient tenant provisioning and onboarding.
+</objective>
+
+<execution_context>
+@.mindforge/skills/multi-tenancy-patterns/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Assess isolation requirements based on the application domain: regulatory constraints (HIPAA/SOC2 may require physical separation), data sensitivity (financial data needs stronger isolation), performance requirements (noisy neighbor concerns), and compliance certifications per tenant.
+2. Choose isolation level based on --isolation flag: RLS (Row-Level Security — shared schema, best for most SaaS with cost efficiency), schema-per-tenant (logical separation, good for regulated industries), or database-per-tenant (physical separation, required for enterprise with data residency requirements). Document trade-offs.
+3. Implement tenant context middleware: extract tenant identifier from request (subdomain, header, JWT claim, or API key), validate tenant exists and is active, inject tenant context into request lifecycle (AsyncLocalStorage/cls-hooked), and propagate to all downstream service calls.
+4. Add query guards for data isolation: for RLS implement PostgreSQL policies (CREATE POLICY tenant_isolation ON table USING (tenant_id = current_setting('app.tenant_id'))), for schema isolation set search_path per request, for DB isolation route connection per tenant. Never rely solely on application-level WHERE clauses.
+5. Configure tenant routing based on --routing flag: subdomain routing (tenant1.app.com — DNS wildcard + middleware extraction), header routing (X-Tenant-ID — simpler but less user-friendly), path-prefix routing (/tenant1/api — SEO-friendly). Implement routing at load balancer level for efficiency.
+6. Test isolation rigorously: verify no data leakage between tenants (create data as tenant A, query as tenant B must return empty), test with concurrent requests from different tenants, verify tenant context survives async operations, and run automated isolation tests in CI.
+7. Plan tenant provisioning workflow: automated tenant creation (database/schema/RLS setup), initial data seeding (defaults, templates), DNS configuration (if subdomain routing), welcome email with onboarding steps, and billing activation. Target <30 seconds for new tenant provisioning.
+8. Document onboarding flow: admin creates tenant via API/dashboard, system provisions resources, tenant admin receives invite, configures settings (branding, users, integrations), and begins using the platform. Include self-service tier for instant provisioning.
+9. Design tenant-aware observability: tag all logs/metrics/traces with tenant_id, per-tenant dashboards for resource consumption, tenant-level SLO tracking, and usage-based billing data collection. Alert on tenants exceeding resource quotas.
+10. Log multi-tenancy design in AUDIT with: app, isolation level, routing strategy, provisioning time target, isolation test coverage, and compliance requirements met.
+</process>

package/.claude/commands/mindforge/multimodal.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:multimodal
+description: "Design multimodal AI system architecture. Usage: /mindforge:multimodal [system] [--modality vision|audio|text|multi] [--task generation|understanding|retrieval]"
+argument-hint: "[system] [--modality vision|audio|text|multi] [--task generation|understanding|retrieval]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design a comprehensive multimodal AI system that integrates multiple data modalities (vision, audio, text) for generation, understanding, or retrieval tasks. This command creates architecture blueprints for systems that process and synthesize information across different sensory inputs, ensuring efficient model selection, data alignment, and cross-modal reasoning capabilities.
+</objective>
+
+<execution_context>
+@.mindforge/skills/multimodal-ai/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/multimodal-ai/`
+State: Evaluates the target system's modality requirements, task characteristics, and performance constraints to generate a multimodal architecture with model recommendations, data pipeline design, and alignment strategies.
+</context>
+
+<process>
+1. **Modality Analysis**: Identify required input/output modalities (vision, audio, text, video) and their interaction patterns, analyzing data characteristics, resolution requirements, and temporal dependencies for each modality.
+
+2. **Model Selection Strategy**: Recommend foundation models (CLIP, Flamingo, GPT-4V, Gemini, LLaVA) based on task requirements, evaluate trade-offs between unified models vs specialized model ensembles, and specify fine-tuning approaches for domain adaptation.
+
+3. **Cross-Modal Alignment Architecture**: Design alignment mechanisms (contrastive learning, cross-attention, adapter layers) to map different modalities into shared representation spaces, ensuring semantic consistency and efficient cross-modal retrieval.
+
+4. **Data Pipeline Design**: Architect preprocessing pipelines for each modality including normalization, augmentation, and synchronization strategies, define batch composition strategies for mixed-modality training, and implement quality validation checkpoints.
+
+5. **Inference Optimization**: Design inference architecture with model serving patterns (sequential, parallel, cascade), implement caching strategies for embeddings and intermediate representations, and specify hardware allocation (GPU/CPU split) per modality.
+
+6. **Evaluation Framework**: Define modality-specific metrics (CLIP score for vision-text, audio quality metrics, generation fidelity), design cross-modal evaluation protocols, and establish baseline benchmarks for the target task.
+
+7. **Integration and Scaling**: Specify API contracts for modality inputs/outputs, design horizontal scaling strategies for high-throughput scenarios, implement monitoring for per-modality performance degradation, and document failure modes and fallback strategies.
+</process>

package/.claude/commands/mindforge/new-runtime.md

@@ -0,0 +1,23 @@
+---
+description: Scaffold support for a new AI coding runtime.
+---
+
+# /mindforge:new-runtime
+
+Scaffold support for a new AI coding runtime.
+
+## Usage
+
+/mindforge:new-runtime [name]
+
+## Action
+
+1.  Identify target runtime's entry file format (e.g. .myrules, instructions.md)
+2.  Scaffold the required directories in both global and local scopes
+3.  Add a new entry to the RUNTIMES configuration in `bin/installer-core.js`
+4.  Generate first-run instructions for the new runtime
+
+## Examples
+
+/mindforge:new-runtime void-editor
+/mindforge:new-runtime zed-ai

package/.claude/commands/mindforge/next.md

@@ -0,0 +1,109 @@
+---
+description: Auto-detect the current project state and execute the appropriate next step.
+---
+
+# MindForge — Next Command
+# Usage: /mindforge:next
+
+Auto-detect the current project state and execute the appropriate next step.
+The user does not need to know the workflow. MindForge figures it out.
+
+## HANDOFF.json priority rule
+Check HANDOFF.json BEFORE running the decision tree.
+
+If HANDOFF.json exists AND `updated_at` is within 48 hours AND `next_task` is not null:
+present the HANDOFF state first. Only run the decision tree if the user declines
+or the HANDOFF.json is stale.
+
+## State detection logic
+
+Read STATE.md and HANDOFF.json. Then follow this decision tree:
+
+### Decision tree
+
+```
+Does .planning/PROJECT.md exist AND have content?
+  NO  → Run /mindforge:init-project
+  YES → Continue
+
+Does .planning/ROADMAP.md exist AND have phases defined?
+  NO  → Tell user: "Project is initialised but no phases are defined yet.
+         Describe what Phase 1 should accomplish and I'll plan it."
+         Then run /mindforge:plan-phase 1
+  YES → Continue
+
+Read the phase status from STATE.md.
+
+Does the current phase have plans? (check .planning/phases/[N]/PLAN-[N]-*.md)
+  NO  → Run /mindforge:plan-phase [N]
+  YES → Continue
+
+Do SUMMARY files exist for all plans in the current phase?
+  NO  → Run /mindforge:execute-phase [N]
+  YES → Continue
+
+Does VERIFICATION.md exist for the current phase?
+  NO  → Run /mindforge:verify-phase [N] (automated part)
+  YES → Continue
+
+Does UAT.md exist and show all tests passing?
+  NO  → Run /mindforge:verify-phase [N] (UAT part)
+  YES → Continue
+
+Is this phase marked as shipped in STATE.md?
+  NO  → Run /mindforge:ship [N]
+  YES → Continue
+
+Are there more phases in ROADMAP.md?
+  YES → Increment phase number. Run /mindforge:plan-phase [N+1]
+  NO  → Tell user: "All phases complete! Run /mindforge:ship [N] for the final release."
+```
+
+## Partial phase execution handling
+In the decision tree step "Do SUMMARY files exist for all plans?":
+
+Do not treat this as binary. Check individually:
+
+```
+PLAN-[N]-01.md exists?          SUMMARY-[N]-01.md exists?
+PLAN-[N]-02.md exists?          SUMMARY-[N]-02.md exists?
+PLAN-[N]-03.md exists?          SUMMARY-[N]-03.md exists?
+```
+
+If some SUMMARY files exist and some don't: this is a partially-executed phase.
+Report: "Phase [N] is partially executed: plans [X, Y] are done, [Z] is not."
+Ask: "Resume execution from Plan [Z]? (yes/no)"
+Do not restart the entire phase — resume from the first missing SUMMARY.
+
+## Before auto-executing: always confirm
+Before running any command automatically, tell the user:
+
+```
+MindForge next step detected:
+  Current state : [description of current state]
+  Next action   : [what will be run]
+  Command       : /mindforge:[command] [args]
+
+Run this now? (yes/no/different)
+```
+
+If user says "different": ask what they want to do instead.
+If user says "yes": proceed with the detected command.
+
+## Handling HANDOFF.json (session restart)
+If HANDOFF.json has a `next_task` field from a previous session:
+Present it prominently:
+
+```
+Previous session found:
+  Saved at  : [updated_at from HANDOFF.json]
+  Left off  : [last_completed_task]
+  Next task : [next_task]
+
+Options:
+  1. Continue from where we left off
+  2. Check current state and determine next step fresh
+  3. Tell me what you want to do
+
+Choose 1, 2, or 3:
+```

package/.claude/commands/mindforge/note.md

@@ -0,0 +1,35 @@
+---
+name: mindforge:note
+description: Capture an idea, task, or issue that surfaces during a session as a quick note for later
+argument-hint: <text> [list|promote N]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - multi_replace_file_content
+---
+
+<objective>
+Provide a zero-friction way to capture ephemeral thoughts, bugs, or todos during an active session without interrupting the current flow, with the ability to later promote them to official tasks.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/note.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The note text or subcommand like `list` or `promote`)
+Storage: .planning/notes/
+Target for Promotion: ROADMAP.md or STATE.md
+</context>
+
+<process>
+1. **Route Subcommand**:
+    - If `list`: Read all files in `.planning/notes/` and present them.
+    - If `promote <N>`: Read note N, add it to current phase/milestone in STATE.md or ROADMAP.md, then move the note to `.planning/notes/archived/`.
+    - Else (default): Capture the text.
+2. **Capture Flow**:
+    - Ensure `.planning/notes/` directory.
+    - Create a file `note_[timestamp].md` with the content.
+3. **Confirm**: Quick confirmation of capture or promotion result.
+</process>

package/.claude/commands/mindforge/observability-platform.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:observability-platform
+description: "Design unified observability platform. Usage: /mindforge:observability-platform [scope] [--stack otel|datadog|grafana] [--scale services]"
+argument-hint: "[scope] [--stack otel|datadog|grafana] [--scale services]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive observability-platform system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/platform-observability/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/platform-observability/`
+State: Analyzes requirements, constraints, and scale to generate optimized observability-platform 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/.claude/commands/mindforge/observability.md

@@ -0,0 +1,75 @@
+---
+description: "Set up logging, tracing, and metrics stack. Usage: /mindforge:observability [service] [--stack otel|custom] [--alerts]"
+---
+
+<objective>
+Design and implement a comprehensive observability stack covering structured logging, distributed tracing, and metrics collection with alert definitions for a service or system.
+</objective>
+
+<execution_context>
+@.mindforge/skills/observability-stack/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (service name, optional --stack otel|custom, optional --alerts flag)
+Knowledge: Current infrastructure, existing monitoring, SLO definitions, incident history.
+</context>
+
+<process>
+1. **Identify golden signals**: For the target service, define:
+   - Latency: request duration distribution (p50, p95, p99)
+   - Traffic: requests per second, broken down by endpoint and method
+   - Errors: error rate by type (4xx client, 5xx server, timeout, circuit-open)
+   - Saturation: resource utilization (CPU, memory, connections, queue depth)
+   - Map each signal to concrete measurement points in the code
+   - Identify which signals are leading indicators vs lagging
+
+2. **Implement structured logging**: Design the logging layer:
+   - Format: JSON with consistent field names across all services
+   - Required fields: timestamp, level, service, trace_id, span_id, message
+   - Context fields: user_id, request_id, correlation_id, environment
+   - Log levels: ERROR (actionable), WARN (degraded), INFO (state changes), DEBUG (development)
+   - Correlation: inject trace_id and span_id into every log line
+   - Sampling: log 100% of errors, sample INFO/DEBUG in production
+   - Redaction: automatically mask PII fields (email, IP, tokens)
+
+3. **Add tracing (OpenTelemetry spans)**: Instrument the request lifecycle:
+   - Root span at service entry (HTTP handler or message consumer)
+   - Child spans for: database queries, external API calls, cache operations, queue publish
+   - Span attributes: operation name, status code, error message, duration
+   - Propagation: W3C TraceContext headers for cross-service correlation
+   - Sampling strategy: always-on for errors, probabilistic (10%) for success
+   - Exporter configuration: OTLP to collector, batch with 5s flush interval
+
+4. **Define metrics (RED for services, USE for resources)**:
+   - RED (Request-focused): Rate, Errors, Duration per endpoint
+   - USE (Resource-focused): Utilization, Saturation, Errors per resource
+   - Histogram buckets for latency: [5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 5s]
+   - Counter for requests by: method, path, status_code
+   - Gauge for: active connections, queue depth, cache size
+   - Summary for: batch job duration, background task completion time
+
+5. **Design alerts (symptom-based)**: When --alerts flag is set:
+   - SLO-based: alert on error budget burn rate (fast burn = 14.4x in 1h, slow burn = 6x in 6h)
+   - Latency: p99 > 2x target for 5 minutes
+   - Error rate: > 1% for 5 minutes (page), > 0.1% for 30 minutes (ticket)
+   - Saturation: resource > 80% for 10 minutes (warn), > 95% for 5 minutes (page)
+   - Absence: no data for 5 minutes (service may be down)
+   - Alert routing: PagerDuty for page-severity, Slack for warn-severity
+   - Runbook link in every alert annotation
+
+6. **Build dashboard**: Design the observability dashboard hierarchy:
+   - L0 (Overview): Service health grid, error budget remaining, top-level SLIs
+   - L1 (Service): Golden signals for the specific service, recent deployments overlay
+   - L2 (Request): Individual request trace waterfall, span breakdown
+   - L3 (Resource): CPU, memory, disk, network for underlying infrastructure
+   - Include: deployment markers, anomaly detection overlay, comparison (now vs last week)
+
+7. **Output observability plan**: Deliver:
+   - Architecture diagram (collector topology, data flow)
+   - Instrumentation code snippets for the target stack
+   - Alert definitions (Prometheus rules or equivalent)
+   - Dashboard JSON (Grafana or equivalent)
+   - Retention policy (hot: 7d full resolution, warm: 30d downsampled, cold: 90d aggregated)
+   - Cost estimate for the observability stack
+</process>

package/.claude/commands/mindforge/offline.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:offline
+description: "Design offline-first data architecture. Usage: /mindforge:offline [feature] [--sync crdt|ot|custom] [--conflict lww|merge|manual]"
+argument-hint: "[feature] [--sync crdt|ot|custom] [--conflict lww|merge|manual]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design offline-first architectures with local-first data storage, optimistic UI updates, sync conflict resolution, and graceful degradation during network outages.
+</objective>
+
+<execution_context>
+@.mindforge/skills/offline-first-design/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/offline-first-design/`
+State: Designs local database schema, sync protocols (CRDT/OT), conflict resolution strategies, and queue management for offline operations.
+</context>
+
+<process>
+1. **Local Storage**: SQLite (structured relational data). IndexedDB (web, large datasets). Realm (mobile, reactive queries). WatermelonDB (React Native, observable). Choose based on platform and query patterns.
+
+2. **Sync Strategy**: CRDT (Conflict-free Replicated Data Types) → automatic merge, no conflicts, eventual consistency (Yjs, Automerge). OT (Operational Transformation) → transforms operations, preserves intent (Google Docs style). Custom → simpler logic but requires explicit conflict handling.
+
+3. **Conflict Resolution**: Last-Write-Wins → simple, risk of data loss, acceptable for low-conflict scenarios. Field-level merge → granular, preserves more data, requires schema design. Manual resolution → show UI for user decision, use for critical data. Version vectors track causality.
+
+4. **Optimistic UI**: Apply changes immediately to local state. Show pending indicator. Queue sync operation. Rollback on server rejection. Show conflicts in UI. Maintain operation log for debugging.
+
+5. **Queue Management**: Persist operations to disk (survive app restart). Retry with exponential backoff. Handle partial failures (some operations succeed, others fail). Order dependencies (create before update). Prune completed operations.
+
+6. **Data Pruning**: Archive old data (>90 days inactive). Delete ephemeral data (cached images). Compress large payloads. Implement storage quotas. Monitor disk usage. User-triggered full sync to recover space.
+
+7. **Testing**: Simulate offline mode. Test conflict scenarios (concurrent edits). Verify data integrity post-sync. Test with poor network (slow 3G). Load test sync with large datasets. Monitor sync latency and queue depth.
+</process>

package/.claude/commands/mindforge/onboard.md

@@ -0,0 +1,37 @@
+---
+description: Generate a knowledge graph, entry point summary, and learning path for the current or specified codebase. Usage - /mindforge:onboard [path] [--depth shallow|deep] [--output ONBOARDING-REPORT.md]
+---
+
+<objective>
+Rapidly understand an unfamiliar codebase by generating structured summaries,
+identifying entry points, and creating an ordered learning path.
+</objective>
+
+<execution_context>
+@.mindforge/skills/codebase-onboarding/SKILL.md
+@.mindforge/engine/knowledge-graph-protocol.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Determine target directory (default: current working directory).
+2. Detect stack: scan for package.json, Cargo.toml, go.mod, pyproject.toml, etc.
+3. Identify languages, frameworks, build tools, and test frameworks.
+4. Find entry points: main files, bin entries, route definitions, CLI commands, event handlers.
+5. If --depth deep: build full module dependency graph (nodes=files, edges=imports).
+6. If --depth shallow: identify top 10 most-imported modules only.
+7. Identify hot paths: files modified most frequently (git log --name-only).
+8. Generate learning path: ordered file reading sequence (config → entry → core → utilities → edge cases).
+9. Write ONBOARDING-REPORT.md (or --output path) to `.planning/` with sections:
+   - Overview (1-paragraph summary)
+   - Tech Stack (detected languages, frameworks, tools)
+   - Entry Points (with file paths)
+   - Architecture (module graph summary)
+   - Hot Paths (most-active areas)
+   - Learning Path (ordered reading list with WHY for each file)
+   - Concerns (potential issues spotted during exploration)
+10. Log onboarding event in AUDIT.
+</process>