mindforge-cc 11.2.1 → 11.3.1

package/.claude/commands/mindforge/benchmark.md

@@ -0,0 +1,37 @@
+---
+description: Measure skill effectiveness over time.
+---
+
+# MindForge — Benchmark Command
+# Usage: /mindforge:benchmark [--skill skill-name] [--compare skill-a skill-b]
+
+Measure skill effectiveness over time.
+
+## Single skill benchmark
+For a named skill, analyse AUDIT.jsonl and skill-usage.jsonl:
+- How many times was the skill loaded this month?
+- What is the verify pass rate for tasks where this skill was loaded?
+- Are there anti-patterns less common after this skill is loaded?
+- What is the average session quality score when this skill is active?
+
+Report:
+```
+Skill Benchmark: security-review v1.0.0
+────────────────────────────────────────
+Usage (last 30 days): 47 task loads
+Trigger distribution: text match 68%, file-path 22%, file-name 10%
+Verify pass rate:     91% (vs. 84% baseline without this skill)
+Security findings:    8 HIGH caught (0 CRITICAL missed in tasks using this skill)
+Session quality lift: +6.2 points average when loaded
+
+Assessment: HIGH VALUE — clear quality improvement signal
+```
+
+## Skill comparison
+Compare two skills head-to-head:
+- Load frequency
+- Verify pass rate improvement
+- Anti-pattern detection rate
+- Context budget cost (token estimate)
+
+Helps decide: should you keep both skills, or deprecate the lower-performer?

package/.claude/commands/mindforge/brd.md

@@ -0,0 +1,90 @@
+---
+description: "Generate Business Requirements Document with stakeholder analysis. Usage: /mindforge:brd [project] [--stakeholders list]"
+---
+
+<objective>
+Produce a comprehensive Business Requirements Document (BRD) that captures stakeholder needs, maps current-state vs future-state, performs gap analysis, and delivers actionable requirements traceable to business outcomes.
+</objective>
+
+<execution_context>
+@.mindforge/skills/business-analyst/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (project name or description, optional --stakeholders comma-separated list)
+Knowledge: PROJECT.md context, existing PRDs, domain research, organizational goals.
+</context>
+
+<process>
+1. **Identify stakeholders**: Enumerate all stakeholders for the project. For each, capture:
+   - Name/role
+   - Department or domain
+   - Level of authority (decision-maker, influencer, contributor, informed)
+   - Primary concerns and success metrics
+   - Communication preference and frequency
+
+2. **Build power-interest grid**: Plot stakeholders on a 2x2 matrix:
+   - High Power / High Interest → Manage closely (key players)
+   - High Power / Low Interest → Keep satisfied
+   - Low Power / High Interest → Keep informed
+   - Low Power / Low Interest → Monitor
+   Derive engagement strategy per quadrant.
+
+3. **Elicit requirements**: For each key stakeholder group, extract:
+   - Business objectives (what outcome do they need?)
+   - Functional requirements (what must the system do?)
+   - Non-functional requirements (performance, security, compliance, accessibility)
+   - Constraints (budget, timeline, technology, regulatory)
+   - Assumptions and dependencies
+
+4. **Draft BRD (10 sections)**:
+   - 1. Executive Summary
+   - 2. Business Objectives and Success Criteria
+   - 3. Stakeholder Analysis (power-interest grid)
+   - 4. Scope (in-scope, out-of-scope, future phases)
+   - 5. Functional Requirements (numbered, prioritized)
+   - 6. Non-Functional Requirements (measurable targets)
+   - 7. Business Rules and Constraints
+   - 8. AS-IS Process Model
+   - 9. TO-BE Process Model
+   - 10. Risk Register and Mitigation Plan
+
+5. **Map AS-IS state**: Document the current process:
+   - Process flow (steps, actors, systems involved)
+   - Pain points and inefficiencies
+   - Current metrics and baselines
+   - Technology landscape in use today
+   - Compliance obligations already met
+
+6. **Map TO-BE state**: Document the desired future process:
+   - Improved process flow
+   - Eliminated pain points
+   - Target metrics (with specific improvement percentages)
+   - New technology components
+   - New compliance requirements addressed
+
+7. **Gap analysis**: For each AS-IS vs TO-BE delta:
+   - Gap description
+   - Impact if not addressed (quantified where possible)
+   - Effort estimate (T-shirt size: S/M/L/XL)
+   - Priority (Must/Should/Could/Won't — MoSCoW)
+   - Dependencies on other gaps
+
+8. **Define acceptance criteria**: For each functional requirement, write testable acceptance criteria using Given-When-Then format. Ensure each criterion is:
+   - Specific (no ambiguity)
+   - Measurable (pass/fail deterministic)
+   - Traceable to a business objective
+
+9. **Validate with stakeholders**: Present the BRD summary to stakeholders:
+   - Highlight key trade-offs and decisions needed
+   - Flag any conflicting requirements between stakeholder groups
+   - Propose resolution options for conflicts
+   - Request sign-off on scope and priorities
+
+10. **Output BRD**: Write the final document to `.planning/BRD-[project-slug].md` with:
+    - Version number and date
+    - Approval signatures section
+    - Change log
+    - Traceability matrix (requirement → objective → stakeholder)
+    - Appendices (glossary, acronyms, reference documents)
+</process>

package/.claude/commands/mindforge/browse.md

@@ -0,0 +1,30 @@
+---
+description: @mindforge browse <url | action>
+---
+
+# /mindforge:browse
+
+## Usage
+`@mindforge browse <url | action>`
+
+## Description
+Controls the persistent MindForge browser daemon. 
+Maintains session state (cookies/localStorage) for the AI.
+
+## Actions
+| Action | Description |
+|---|---|
+| `--start` | Initialize browser daemon |
+| `--stop` | Kill browser daemon |
+| `--status` | Show daemon health and active sessions |
+| `--session <name>` | Switch browser context |
+| `--import-session <name> --from <browser>` | Import cookies from host browser (chrome, arc, etc) |
+| `<url>` | Navigate the current page to URL |
+| `click <selector>` | Trigger click event |
+| `type <sel> <text>` | Fill input field |
+| `screenshot` | Capture current viewport |
+
+## Security
+- Daemon binds to `127.0.0.1` only.
+- Session files are gitignored.
+- Use only for debugging and visual verification.

package/.claude/commands/mindforge/build-opt.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:build-opt
+description: "Optimize build system performance. Usage: /mindforge:build-opt [project] [--tool bazel|nx|turbo] [--target time-minutes]"
+argument-hint: "[project] [--tool bazel|nx|turbo] [--target time-minutes]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive build-opt system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/build-system-optimization/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/build-system-optimization/`
+State: Analyzes requirements, constraints, and scale to generate optimized build-opt 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/build-vs-buy.md

@@ -0,0 +1,29 @@
+---
+description: "Evaluate build vs buy decision with TCO analysis. Usage: /mindforge:build-vs-buy [capability] [--timeline N months] [--strategic high|low]"
+---
+
+<objective>
+Evaluate whether to build a capability in-house or purchase/adopt an external solution, using total cost of ownership analysis, strategic alignment scoring, and vendor lock-in risk assessment.
+</objective>
+
+<execution_context>
+@.mindforge/skills/build-vs-buy/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (capability name, optional --timeline, optional --strategic)
+Knowledge: Architecture docs, team capacity, existing vendor contracts, strategic roadmap.
+</context>
+
+<process>
+1. **Define Capability Needed**: Clarify the exact capability, its boundaries, and who the internal consumers are. Document functional and non-functional requirements.
+2. **Identify Buy Options**: Research vendor solutions (SaaS, managed services) and open-source alternatives. List at least 3 candidates with pricing models.
+3. **Estimate Build Effort**: Calculate engineering effort (person-months), required expertise, timeline to MVP, and timeline to production-grade.
+4. **Calculate Ongoing Maintenance**: For the build path, estimate annual maintenance cost (bug fixes, upgrades, on-call, infrastructure). Apply 20-40% of initial build cost as baseline.
+5. **Calculate TCO For Each Option**: Project total cost over the specified timeline (default 36 months). Include: licensing, integration effort, training, migration cost, and opportunity cost of engineering time.
+6. **Assess Vendor Lock-in Risk**: Score each buy option on data portability, API standardization, contract flexibility, and exit cost. Flag any single-vendor dependency.
+7. **Evaluate Strategic Importance**: Score how core this capability is to the business (commodity vs differentiator). Core differentiators favor build; commodities favor buy.
+8. **Score Decision Matrix**: Weight factors (cost 30%, strategic fit 25%, time-to-value 20%, risk 15%, team growth 10%) and produce a quantified recommendation.
+9. **Recommend With Confidence Level**: State the recommendation (build/buy/hybrid) with a confidence percentage and the top 2 factors driving the decision.
+10. **Document As ADR**: Write an Architecture Decision Record capturing the decision, context, options considered, and consequences.
+</process>

package/.claude/commands/mindforge/cache.md

@@ -0,0 +1,30 @@
+---
+description: Design caching strategy with invalidation patterns. Usage - /mindforge:cache [service] [--pattern aside|through|behind] [--layers N]
+---
+
+<objective>
+Design a multi-layer caching architecture with explicit invalidation strategies
+that eliminates cache stampedes, prevents stale data serving, and provides
+observable hit rates. Covers L1 (in-process), L2 (shared), and L3 (CDN) layers.
+</objective>
+
+<execution_context>
+@.mindforge/skills/caching-strategies/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Identify hot data paths by analyzing access patterns — read-heavy endpoints, expensive computations, frequently-joined data. Quantify read/write ratios for each candidate.
+2. Select the caching pattern based on --pattern flag: cache-aside (application manages cache explicitly), read-through/write-through (cache handles persistence transparently), or write-behind (async write batching for high throughput).
+3. Design the invalidation strategy: event-driven invalidation (publish on write), TTL-based expiration (with jitter to prevent thundering herd), or version-based (cache key includes data version).
+4. Prevent cache stampedes using established patterns: request coalescing (single-flight), probabilistic early expiration (XFetch), or mutex/lock-based recomputation with stale-while-revalidate.
+5. Set TTLs appropriate to data freshness requirements: seconds for session data, minutes for API responses, hours for reference data. Add random jitter (10-20%) to all TTLs.
+6. Design cache layers based on --layers flag: L1 in-process (Map/LRU, ~1ms, small), L2 shared (Redis/Memcached, ~5ms, medium), L3 CDN (CloudFront/Fastly, ~50ms, large). Define promotion/demotion rules.
+7. Implement cache monitoring: track hit rate, miss rate, eviction rate, and latency per cache layer. Set alerts on hit rate dropping below threshold (e.g., 80%).
+8. Plan cache warming strategy for cold starts: pre-populate on deploy using background job, implement graceful degradation when cache is cold (slightly slower, never broken).
+9. Document cache key naming conventions, serialization format, and max entry sizes. Define cache bypass mechanisms for debugging (e.g., Cache-Control: no-cache header).
+10. Log cache invocation in AUDIT with: service, pattern, layers, estimated hit rate improvement, invalidation strategy.
+</process>

package/.claude/commands/mindforge/causal.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:causal
+description: "Design causal inference analysis. Usage: /mindforge:causal [experiment] [--method ab|did|iv|rdd] [--outcome metric]"
+argument-hint: "[experiment] [--method ab|did|iv|rdd] [--outcome metric]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive causal system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/causal-inference/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/causal-inference/`
+State: Analyzes requirements, constraints, and scale to generate optimized causal 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/cdn.md

@@ -0,0 +1,34 @@
+---
+name: mindforge:cdn
+description: "Optimize CDN caching and invalidation strategy. Usage: /mindforge:cdn [service] [--target-hit-ratio 95%] [--multi-cdn] [--shield]"
+argument-hint: "[service] [--target-hit-ratio 95%] [--multi-cdn] [--shield]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Optimize CDN caching strategy to maximize hit ratios, minimize origin load, and implement efficient invalidation patterns that maintain content freshness without sacrificing performance.
+</objective>
+
+<execution_context>
+@.mindforge/skills/cdn-optimization/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/cdn-optimization/`
+State: Audits current cache performance and designs optimized caching hierarchy with intelligent invalidation.
+</context>
+
+<process>
+1. **Audit Current Cache Performance**: Analyze existing CDN metrics — hit ratio, miss ratio, bandwidth savings, origin offload percentage, and per-path cache effectiveness. Identify the top cache-miss contributors.
+2. **Design Cache Key Strategy**: Optimize cache key composition to avoid over-keying (too many unique keys from unnecessary query params or headers) while maintaining correctness for content variants (language, device, auth state).
+3. **Configure Cache Hierarchy**: Design the multi-tier cache topology — edge PoP → regional shield → origin. Determine which content tiers benefit from shield protection to reduce origin requests from geographically distributed edges.
+4. **Implement Purge Strategy**: Design tag-based (surrogate key) invalidation as the primary purge mechanism. Define purge propagation time targets and fallback to URL-pattern purge for emergency invalidation.
+5. **Enable Stale-While-Revalidate**: Configure SWR directives to serve stale content while fetching fresh versions in the background. Set appropriate stale-if-error windows for origin failure resilience.
+6. **Configure Origin Shielding**: Set up a shield layer that consolidates cache fills from multiple edge locations into a single origin request. Reduces origin load during cache warming and traffic spikes.
+7. **Set Up Hit Ratio Monitoring**: Implement real-time dashboards tracking cache hit ratio by path pattern, content type, and geographic region. Define alerting thresholds for hit ratio degradation.
+8. **Optimize Per-Path Caching Rules**: Create differentiated TTL and caching policies per URL pattern — static assets (long TTL, immutable), API responses (short TTL, vary headers), HTML pages (medium TTL, SWR). Document each rule.
+9. **Plan Multi-CDN Strategy**: If using multiple CDN providers, design DNS-based traffic splitting, failover logic, and consistent cache key normalization across providers.
+10. **Load Test Cache Behavior**: Simulate traffic patterns including cache stampede scenarios, purge storms, and geographic shifts to validate the caching architecture performs under stress.
+</process>

package/.claude/commands/mindforge/change.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:change
+description: "Plan change management for technical migration. Usage: /mindforge:change [migration] [--scope team|org|platform] [--urgency low|medium|high]"
+argument-hint: "[migration] [--scope team|org|platform] [--urgency low|medium|high]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design change management strategies for technical migrations (framework upgrades, platform migrations, architecture rewrites). Balances migration velocity with team stability and system reliability.
+</objective>
+
+<execution_context>
+@.mindforge/skills/change-management/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/change-management/`
+State: Evaluates migration scope, user impact, team capacity, designs phased rollout with rollback triggers, training plans, and success metrics.
+</context>
+
+<process>
+1. **Migration Impact Assessment**: Classify change magnitude (cosmetic UI refresh vs database migration vs rewrite). Map affected systems (frontend/backend/data/infra). Identify user-facing changes (API contracts, UI patterns, performance characteristics). Estimate blast radius (10 users vs 1000 users vs entire platform).
+
+2. **Rollout Strategy Selection**: Big bang (cut over in one release, acceptable for low-risk cosmetic changes). Phased (rollout in waves by user cohort, standard for moderate risk). Parallel run (old + new coexist with feature flag, required for high-risk data migrations). Strangler fig (gradually replace old system piece by piece, for rewrites).
+
+3. **Phase Decomposition**: Phase 0 (foundation) → infra + logging + kill switches. Phase 1 (alpha) → 1% internal users, validate happy path. Phase 2 (beta) → 10% friendly external users, surface edge cases. Phase 3 (GA) → 100% rollout with automated rollback if error rate >threshold. Each phase requires explicit go/no-go decision.
+
+4. **Rollback Design**: Define rollback triggers (error rate >2%, latency >500ms, complaint rate >5%). Implement kill switch (feature flag to instantly revert to old code). Test rollback procedure before each phase. Document runbook with exact rollback steps. Assign rollback decision maker (on-call engineer or release manager).
+
+5. **Communication Plan**: T-30d → announce migration to eng team, share technical RFC. T-14d → email affected users with "what's changing, when, what to expect". T-1d → final reminder + support channel link. T+0 → rollout begins, status page live. T+7d → retrospective on what worked/failed. Tailor message density to urgency (high urgency = daily updates).
+
+6. **Training & Enablement**: For eng team → brown bag session on new patterns + runbook. For support team → FAQ doc + escalation paths. For users → migration guide with before/after examples. For stakeholders → one-pager on timeline + risk mitigation. Schedule training 2 weeks before rollout, not 2 months (recency matters).
+
+7. **Success Metrics & Monitoring**: Define success criteria before migration starts (zero data loss, latency within 10% of baseline, <5 support tickets). Set up real-time monitoring dashboard. Alert on anomaly detection (sudden spike in errors). Run comparison reports (old vs new performance). Plan for post-migration optimization sprint (address performance regressions found in production).
+</process>

package/.claude/commands/mindforge/cli.md

@@ -0,0 +1,30 @@
+---
+description: Design CLI command structure and UX. Usage - /mindforge:cli [app-name] [--style verb-noun|git-style]
+---
+
+<objective>
+Design a complete CLI application with intuitive command hierarchy, consistent
+flag conventions, rich help text, and proper error handling. Prioritizes
+discoverability, composability, and non-interactive CI compatibility.
+</objective>
+
+<execution_context>
+@.mindforge/skills/cli-design/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Define the command hierarchy based on --style flag. Verb-noun (e.g., `create project`, `list users`) for CRUD-heavy CLIs; git-style (e.g., `init`, `commit`, `push`) for workflow-oriented CLIs. Map all commands in a tree structure.
+2. Design flag conventions: short flags (-v) for common options, long flags (--verbose) for all options, boolean flags without values, repeated flags for lists. Use GNU-style -- for positional separator.
+3. Write comprehensive help text for every command: one-line description, usage pattern, flag descriptions with defaults, and 2-3 examples showing real usage. Ensure `--help` works at every level.
+4. Implement argument parsing with a battle-tested library (commander, yargs, cobra, clap). Define required vs optional args, validate types, and provide suggestions for typos.
+5. Define exit codes following conventions: 0 success, 1 general error, 2 usage error, 126 permission denied, 130 interrupted (SIGINT). Document all exit codes.
+6. Add interactive prompts for missing required information when running in a TTY. Detect non-TTY (CI) and fail with clear error messages instead of hanging on stdin.
+7. Design error messages that are actionable: what went wrong, why, and how to fix it. Include the failed command, relevant context, and a suggested next step.
+8. Test in CI (non-interactive mode): verify all commands work with flags only (no prompts), exit codes are correct, stdout/stderr separation is clean, and output is parseable (--json flag).
+9. Add shell completion generation (bash, zsh, fish) and man page generation. Configure auto-update checking with opt-out.
+10. Log cli invocation in AUDIT with: app name, style, command count, flag conventions defined.
+</process>

package/.claude/commands/mindforge/cluster-instincts.md

@@ -0,0 +1,35 @@
+---
+description: Group related instincts by tag overlap and batch-promote qualifying clusters to skills. Usage - /mindforge:cluster-instincts [--dry-run] [--min-cluster 3] [--min-confidence 0.7]
+---
+
+<objective>
+Automatically identify groups of related instincts that together form a
+coherent skill, and promote them as a single combined skill.
+</objective>
+
+<execution_context>
+@.mindforge/skills/instinct-clustering/SKILL.md
+@.mindforge/skills/continuous-learning/SKILL.md
+@.mindforge/engine/instincts/promotion-engine.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Read `.mindforge/engine/instincts/instinct-store.jsonl`, filter to active instincts.
+2. Deduplication pass: merge instincts with >80% observation word overlap (keep higher confidence).
+3. Compute pairwise tag overlap using Jaccard similarity: |A∩B| / |A∪B|.
+4. Form clusters: group instincts with jaccard > 0.5 AND same project scope.
+5. Filter clusters: minimum --min-cluster instincts (default 3), avg confidence > --min-confidence (default 0.7).
+6. For each qualifying cluster: generate proposed skill name from most common tags.
+7. If --dry-run: report clusters with proposed names, member instincts, and avg confidence. Stop.
+8. Present clusters to user for approval (show: name, member count, avg confidence, combined behavior).
+9. For each approved cluster:
+   a. Generate combined SKILL.md (merge behaviors in logical order, deduplicate triggers).
+   b. Create skill directory and register in MANIFEST.md.
+   c. Mark all member instincts as promoted (status: "promoted", promoted_to_skill: "[name]").
+10. Write CLUSTER-REPORT.md to `.planning/` with all clusters (approved + rejected).
+11. Log clustering event in AUDIT with: clusters found, clusters promoted, instincts affected.
+</process>

package/.claude/commands/mindforge/code-tour.md

@@ -0,0 +1,85 @@
+---
+description: "Generate guided codebase walkthrough with annotated reading path. Usage: /mindforge:code-tour [path] [--depth shallow|deep] [--output TOUR.md]"
+---
+
+<objective>
+Create a progressive, annotated codebase walkthrough that guides a new developer through the system in the optimal reading order — from entry points through hot paths to edge cases.
+</objective>
+
+<execution_context>
+@.mindforge/skills/code-tour/SKILL.md
+@.mindforge/skills/codebase-onboarding/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (target path or area, optional --depth shallow|deep, optional --output filename)
+Knowledge: ARCHITECTURE.md, CONVENTIONS.md, module structure, dependency graph.
+</context>
+
+<process>
+1. **Identify entry points**: Locate the system's primary entry points:
+   - Application bootstrap (main.ts, index.ts, app.py, server.go)
+   - Route/controller registration
+   - Configuration loading sequence
+   - Dependency injection container setup
+   - For libraries: public API surface (exports from index)
+
+2. **Trace hot paths**: Starting from entry points, trace the most important execution paths:
+   - The "happy path" for the core use case
+   - Request lifecycle (middleware → handler → service → repository → response)
+   - Data flow from input to persistence
+   - Event/message processing pipeline (if event-driven)
+   - Mark each file touched with its role in the path
+
+3. **Build progressive reading order**: Organize files into a numbered tour sequence:
+   - Level 1: Entry points and configuration (understand how it starts)
+   - Level 2: Core domain models and types (understand what it models)
+   - Level 3: Service layer and business logic (understand what it does)
+   - Level 4: Infrastructure and adapters (understand how it connects)
+   - Level 5: Tests and edge cases (understand how it's verified)
+   - Each level builds on knowledge from the previous level
+
+4. **Annotate each stop**: For every file in the tour, provide:
+   - **Stop number and title** (e.g., "Stop 3: User Authentication Service")
+   - **Why this file matters** (1-2 sentences on its role in the system)
+   - **Key sections to focus on** (specific line ranges or function names)
+   - **Patterns to notice** (design patterns, conventions, architectural decisions)
+   - **Connections** (what calls this, what this calls — upstream/downstream)
+
+5. **Add understanding checkpoints**: After every 3-5 stops, insert a checkpoint:
+   - Summary of what the reader should now understand
+   - Questions to test comprehension ("Can you explain why X uses Y?")
+   - Mental model diagram (ASCII box-and-arrow showing relationships learned so far)
+   - Common misconceptions to avoid at this stage
+
+6. **Document architecture decisions in context**: At relevant tour stops, explain:
+   - Why this approach was chosen over alternatives
+   - Historical context if visible from git blame or comments
+   - Trade-offs accepted and their implications
+   - When this decision should be revisited
+
+7. **Handle depth modes**:
+   - `--depth shallow`: Entry points + core domain + one hot path (10-15 stops)
+   - `--depth deep`: Full system trace including infrastructure, error handling, and edge cases (25-40 stops)
+   - Default: moderate depth covering all layers with representative examples (15-25 stops)
+
+8. **Cross-reference with tests**: For each major component in the tour:
+   - Point to the relevant test file
+   - Highlight which behaviors are tested vs untested
+   - Note any test patterns that reveal intended usage
+
+9. **Write TOUR.md**: Output the complete tour document:
+   - Table of contents with all stops
+   - Prerequisites (tools, environment, background knowledge)
+   - Estimated reading time per section
+   - Numbered stops with full annotations
+   - Checkpoints between sections
+   - "Where to go next" section for deeper exploration
+   - Glossary of project-specific terms
+
+10. **Generate companion commands**: Produce helper commands:
+    - Script to open all tour files in editor in order
+    - Grep patterns to find related code not in the tour
+    - Links to relevant external documentation
+    - Suggested follow-up tours for specific subsystems
+</process>

package/.claude/commands/mindforge/communicate.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:communicate
+description: "Stakeholder communication planning. Usage: /mindforge:communicate [audience] [--type update|risk|proposal|decision]"
+argument-hint: "[audience] [--type update|risk|proposal|decision]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design targeted communication plans for technical stakeholders. Analyzes audience context, selects optimal communication channels, and structures messages for maximum clarity and actionability.
+</objective>
+
+<execution_context>
+@.mindforge/skills/stakeholder-communication/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/stakeholder-communication/`
+State: Evaluates audience technical depth, urgency, decision authority, and relationship context to produce communication plan with channel, timing, structure, and follow-up strategy.
+</context>
+
+<process>
+1. **Audience Analysis**: Map stakeholder to persona (exec/product/eng/support/external). Identify technical depth (1-5), decision authority (blocker/influencer/informed), urgency sensitivity (critical/moderate/low), preferred channels (sync/async/written).
+
+2. **Communication Type Selection**: For "update" → status report with progress metrics + blockers. For "risk" → impact assessment + mitigation options + decision request. For "proposal" → problem context + solution options + recommendation + trade-offs. For "decision" → decision record with rationale + alternatives considered + implementation plan.
+
+3. **Channel Optimization**: Execs → brief written summary + optional sync for questions. Product → detailed narrative + visual roadmap. Engineering → technical RFC + architecture diagrams. Support → FAQ + runbook. External → polished deck + demo.
+
+4. **Message Structure**: Open with TL;DR (1-2 sentences). Context section (why this matters now). Core content (structured by type). Action items (who/what/when). Appendix (supporting data/links).
+
+5. **Timing Strategy**: Critical → synchronous escalation with written follow-up. Urgent → async with 24h response SLA. Normal → weekly update cycle. Low priority → monthly digest.
+
+6. **Feedback Loop Design**: Specify response mechanism (reply/comment/meeting/survey). Set explicit decision deadline. Define escalation path if no response. Plan follow-up cadence (1 day/1 week/1 sprint).
+
+7. **Artifact Generation**: Produce templated communication draft. Include pre-meeting agenda if sync. Generate post-communication summary template. Create decision log entry if applicable.
+</process>

package/.claude/commands/mindforge/complete-milestone.md

@@ -0,0 +1,22 @@
+---
+description: Archive a completed milestone, generate a release report, and prepare the next
+---
+
+Archive a completed milestone, generate a release report, and prepare the next
+ milestone. Usage: `/mindforge:complete-milestone <name> <version>`
+
+## Step 1 — Validate milestone completion
+Ensure every included phase is verified and has no pending blocking approvals.
+
+## Step 2 — Generate milestone report
+Summarise shipped phases, notable changes, risks, approvals, and unresolved
+ follow-ups.
+
+## Step 3 — Archive milestone artifacts
+Archive only the phases included in the milestone, not the entire
+ `.planning/phases/` directory. Preserve history in the archive while keeping
+ active planning files available in place.
+
+## Step 4 — Release metadata
+Create the release tag, update `STATE.md` with milestone summary, and mark the
+ project ready for the next version.

package/.claude/commands/mindforge/compliance.md

@@ -0,0 +1,31 @@
+---
+description: Generate compliance-as-code policies with automated evidence. Usage - /mindforge:compliance [--framework soc2|hipaa|pci] [--engine opa|sentinel]
+---
+
+<objective>
+Implement compliance-as-code by translating regulatory framework controls into
+automated policy rules, continuous evidence collection, and audit-ready
+reporting. Replaces manual compliance checklists with enforceable, versioned
+policy gates.
+</objective>
+
+<execution_context>
+@.mindforge/skills/compliance-as-code/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Map framework controls to technical requirements based on --framework flag. SOC2: CC6.1-CC9.9 (access control, change management, availability). HIPAA: 164.312 (access, audit, integrity, transmission). PCI: Requirements 1-12 (network, encryption, access, monitoring).
+2. Write policy rules using the --engine flag: Rego (OPA) for infrastructure and API policies, Sentinel (HashiCorp) for Terraform plans, or both. Each rule maps to a specific control ID with rationale comments.
+3. Integrate policies into CI pipeline: OPA/Conftest for Kubernetes manifests, Sentinel for Terraform plan checks, custom rules for application code (secrets detection, encryption verification, access control patterns).
+4. Configure evidence collection: automated screenshots of control dashboards, git commit logs for change management, access review exports, vulnerability scan results, and uptime reports. Store evidence in tamper-evident format.
+5. Set up compliance dashboard showing: controls total vs passing vs failing, evidence freshness (last collection timestamp), upcoming audit dates, and control owner assignments.
+6. Define violation SLAs by severity: Critical (fix within 24h, blocks deploy), High (fix within 7 days), Medium (fix within 30 days), Low (fix within 90 days). Configure escalation paths for each severity.
+7. Generate audit report in framework-specific format: control ID, description, implementation evidence, test results, and remediation status. Export as PDF for auditor handoff.
+8. Schedule periodic reviews: quarterly access reviews (who has access to what), annual penetration testing, monthly vulnerability scans, and continuous configuration drift detection.
+9. Implement exception/waiver process: document risk acceptance for controls that cannot be fully automated, require approval from security lead, set expiration date on all exceptions (max 90 days).
+10. Log compliance invocation in AUDIT with: framework, engine, controls mapped, passing percentage, evidence freshness, next audit date.
+</process>

package/.claude/commands/mindforge/consult.md

@@ -0,0 +1,37 @@
+---
+description: Get a multi-LLM second opinion from external models (Claude, Gemini, GPT-4o). Usage - /mindforge:consult [question] [--models gemini,gpt-4o,claude] [--sanitize strict]
+---
+
+<objective>
+Send a sanitized prompt to external AI models for a second opinion. Synthesize
+responses to identify consensus, divergence, and novel insights.
+</objective>
+
+<execution_context>
+@.mindforge/skills/multi-llm-consult/SKILL.md
+@.mindforge/engine/cost-tracking/router.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse the question from arguments. Extract --models flag (default: all configured).
+2. **Sanitize the prompt:**
+   - Remove file paths → replace with generic descriptions
+   - Remove internal names → abstract the pattern
+   - Remove secrets, credentials, PII → NEVER send externally
+   - Keep the abstract question and public references
+3. **Estimate cost** — check token-ledger for budget remaining. Warn if tight.
+4. **Dispatch** — Send sanitized prompt to each selected model (parallel if possible).
+5. **Collect responses** — Handle timeouts (30s), errors (log and skip), unavailability.
+6. **Synthesize:**
+   - Identify agreement (2+ models recommend same approach)
+   - Identify divergence (models disagree — flag for user)
+   - Identify novel insights (unique points from one model)
+7. **Present results** with clear attribution (which model said what).
+8. Log consultation in token-ledger.jsonl (model, tokens, cost per call).
+9. Report total cost of this consultation.
+10. Remind: "External opinions are advisory — user sovereignty applies."
+</process>