mindforge-cc 11.3.0 → 11.3.1

package/.agent/mindforge/hire.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:hire
+description: "Design technical interview process. Usage: /mindforge:hire [role] [--level junior|mid|senior|staff] [--type system-design|coding|behavioral]"
+argument-hint: "[role] [--level junior|mid|senior|staff] [--type system-design|coding|behavioral]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive technical interview processes tailored to role, seniority level, and organization culture. Generates interview rubrics, question banks, and calibration frameworks to ensure consistent, fair, and predictive hiring.
+</objective>
+
+<execution_context>
+@.mindforge/skills/hiring-engineering/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/hiring-engineering/`
+State: Analyzes role requirements, maps to competencies, designs multi-stage interview funnel with scorecards, questions, and calibration mechanisms.
+</context>
+
+<process>
+1. **Role Decomposition**: Extract core competencies from job description. For Backend → API design, data modeling, concurrency, observability. For Frontend → component architecture, state management, accessibility, performance. For Infra → distributed systems, networking, cost optimization, incident response. Map to 4-6 key evaluation areas.
+
+2. **Seniority Calibration**: Junior → executes tasks, learns patterns, needs guidance. Mid → owns features, solves ambiguous problems, mentors juniors. Senior → designs systems, defines standards, unblocks team. Staff → sets technical direction, influences org-wide decisions, scales team effectiveness. Adjust complexity and autonomy expectations per level.
+
+3. **Interview Stage Design**: Stage 1 (Screening) → 30min technical phone screen with 2 focused questions. Stage 2 (Coding) → 60-90min live coding (algorithm + system implementation). Stage 3 (System Design) → 60min architecture session (scale/reliability/trade-offs). Stage 4 (Behavioral) → 45min STAR method competency questions. Stage 5 (Team Fit) → 30min cultural values alignment.
+
+4. **Question Bank Generation**: For system-design → design URL shortener (junior), design rate limiter (mid), design distributed cache (senior), design multi-region data platform (staff). For coding → two-sum (junior), LRU cache (mid), concurrent task scheduler (senior), distributed transaction coordinator (staff). Include rubric with 1-4 scoring for each question dimension.
+
+5. **Rubric Framework**: Define 4 levels per competency. Level 1 (Below bar) → cannot complete basic task with hints. Level 2 (Mixed signals) → completes with significant guidance. Level 3 (Hire bar) → completes independently with good trade-off reasoning. Level 4 (Strong hire) → exceptional depth, proactive edge case handling, teaches interviewer something new.
+
+6. **Calibration Protocol**: Run shadow interviews for first 3 sessions. Compare scores across interviewers weekly. Flag score variance > 1 point for debrief. Maintain question difficulty metrics (pass rate, average score). Rotate questions quarterly to prevent memorization. Document common failure modes and how to probe deeper.
+
+7. **Bias Mitigation**: Use structured rubrics (not gut feel). Ask same core questions to all candidates. Train interviewers on inclusive language. Anonymize resumes during screening. Track demographic offer rates and adjust process if disparities emerge. Provide clear feedback to rejected candidates.
+</process>

package/.agent/mindforge/hitl.md

@@ -0,0 +1,27 @@
+---
+description: "Design human-in-the-loop escalation gates and thresholds. Usage: /mindforge:hitl [system] [--autonomy progressive] [--explain always]"
+---
+
+<objective>
+Design a human-in-the-loop system with calibrated escalation gates that balances agent autonomy with human oversight, using reversibility and impact as the primary classification axes, and progressively expanding autonomy as trust is established.
+</objective>
+
+<execution_context>
+@.mindforge/skills/human-in-the-loop-design/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (system or agent name, optional --autonomy mode, optional --explain frequency)
+Knowledge: Agent action catalog, business criticality classification, regulatory requirements, historical escalation data.
+</context>
+
+<process>
+1. **Classify All Agent Actions By Reversibility x Impact**: Create a 2x2 matrix: (reversible + low impact = autonomous), (reversible + high impact = confirm), (irreversible + low impact = approve), (irreversible + high impact = block until human review). Catalog every action the agent can take.
+2. **Set Autonomy Level Per Action Type**: Assign each action one of four levels: autonomous (agent acts freely, logs for audit), confirm (agent proposes, human clicks approve/reject), approve (agent drafts, human reviews thoroughly before execution), block (agent cannot perform, must hand off to human).
+3. **Design Escalation UX**: Create low-friction, informative escalation interfaces. Show: what the agent wants to do, why (evidence/reasoning), what the alternatives are, and what happens if rejected. Minimize context-switching cost for the human reviewer.
+4. **Set Confidence Thresholds For Escalation**: Define confidence scores that trigger escalation: agent confidence < 0.7 = escalate even for normally-autonomous actions. Confidence < 0.4 = block. Calibrate thresholds using historical accuracy data.
+5. **Implement Explanation Generation**: For every escalation, generate a structured explanation: action proposed, reasoning chain, evidence consulted, confidence score, risk assessment, and recommended human action. Explanations must be concise (< 200 words).
+6. **Track Escalation Rate**: Monitor: total escalations per day, escalation rate by action type, human approval rate (high approval = threshold too tight), human rejection rate (high rejection = agent quality issue), and time-to-resolution.
+7. **Calibrate Boundaries**: Too many escalations = threshold too tight (human fatigue, defeats purpose). Too few = threshold too loose (risk of unreviewed harmful actions). Target: 5-15% escalation rate for mature systems. Review weekly and adjust.
+8. **Plan Progressive Autonomy Expansion**: As the agent demonstrates reliability (>95% approval rate for a category over 30 days), propose promoting that action category to a less restrictive level. Require explicit human approval to expand autonomy. Never auto-promote.
+</process>

package/.agent/mindforge/i18n.md

@@ -0,0 +1,31 @@
+---
+description: Set up internationalization architecture. Usage - /mindforge:i18n [app] [--format icu] [--locales en,fr,ja] [--lazy-load]
+---
+
+<objective>
+Set up a comprehensive internationalization architecture that externalizes
+all user-facing strings, implements ICU message format for complex plurals
+and selections, configures locale detection with fallback chains, and
+establishes a scalable translation workflow with lazy-loading per route.
+</objective>
+
+<execution_context>
+@.mindforge/skills/i18n-architecture/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Audit all user-facing strings in the application: UI labels, error messages, email templates, push notifications, PDF reports, and dynamic content. Flag hardcoded strings, string concatenation (breaks in inflected languages), and embedded formatting (dates, numbers, currencies).
+2. Set up message catalog structure organized by feature namespace: one file per locale per namespace (e.g., messages/en/auth.json, messages/fr/auth.json). Keep namespaces small (<200 keys) for efficient lazy-loading. Define key naming convention (dot-separated, descriptive).
+3. Implement ICU message format based on --format flag (default ICU): configure plural rules ({count, plural, one {# item} other {# items}}), select for gender/context ({gender, select, male {He} female {She} other {They}}), and nested formatting. Validate messages at build time.
+4. Configure locale detection with fallback chain: (1) URL parameter/path prefix, (2) user preference from profile/cookie, (3) Accept-Language header, (4) geo-IP lookup, (5) default locale. Implement locale negotiation (fr-CA falls back to fr, then to en).
+5. Add lazy-loading per route based on --lazy-load flag: split message bundles by route/feature, load locale data on navigation (prefetch next likely locale), cache loaded bundles in memory, and handle loading states (show skeleton or previous locale until loaded).
+6. Handle RTL layout for Arabic/Hebrew based on --locales: use CSS logical properties (margin-inline-start instead of margin-left), configure dir="rtl" attribute, mirror icons and layouts, and test bidirectional text mixing within a single paragraph.
+7. Set up number, date, and currency formatting using Intl API: configure Intl.NumberFormat per locale (decimal separators, grouping), Intl.DateTimeFormat (12h/24h, month names), and Intl.RelativeTimeFormat. Never hardcode format patterns.
+8. Configure translation workflow: source strings extracted to translation management system (Crowdin/Phrase/Lokalise), context and screenshots attached per key, translator review and QA process, automated PR with new translations, and CI validation of completeness.
+9. Implement locale-aware sorting and searching: configure Intl.Collator for proper alphabetical ordering per locale, handle diacritics in search (normalize to NFD), and support locale-specific search tokenization for CJK languages.
+10. Log i18n architecture in AUDIT with: app, locales supported, format standard, lazy-loading strategy, RTL support, translation workflow, and completeness percentage per locale.
+</process>

package/.agent/mindforge/idempotent.md

@@ -0,0 +1,31 @@
+---
+description: Design idempotency patterns for a service or API. Usage - /mindforge:idempotent [endpoint] [--key-strategy client|server] [--store redis|db]
+---
+
+<objective>
+Design idempotency patterns that ensure repeated requests produce the same
+result without side effects, selecting the appropriate key strategy and storage
+backend, handling concurrent duplicate submissions safely, and providing
+clear retry semantics to API consumers.
+</objective>
+
+<execution_context>
+@.mindforge/skills/idempotency-patterns/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Identify non-idempotent operations in the service: POST endpoints that create resources, payment processing, email/notification sending, external API calls with side effects, and state machine transitions. Classify by impact of duplicate execution (financial, data integrity, user experience).
+2. Choose key strategy based on --key-strategy flag: client-generated UUID (client sends Idempotency-Key header, best for payment APIs), or server-derived key (hash of request body + user + endpoint, best for implicit deduplication). Document key format and uniqueness guarantees.
+3. Select storage backend based on --store flag: Redis for ephemeral keys with auto-expiration (ideal for APIs with short retry windows), database for permanent records (required for financial operations with audit trail). Consider hybrid: Redis for fast lookup + DB for permanent record.
+4. Implement the check-execute-store pattern: (1) receive request with idempotency key, (2) check if key exists in store, (3) if exists return stored response, (4) if not acquire lock, (5) execute operation, (6) store response with key, (7) release lock, (8) return response.
+5. Set TTL for idempotency keys based on retry window: 24 hours for payment APIs, 1 hour for general mutations, 5 minutes for high-volume low-risk operations. Document TTL in API documentation so clients know the safe retry window.
+6. Handle concurrent requests with the same key: implement distributed locking (Redis SETNX or database advisory lock), return 409 Conflict if lock is held, or implement optimistic locking with compare-and-swap. Ensure lock has a timeout to prevent deadlocks.
+7. Design response storage: store full HTTP response (status code, headers, body) for exact replay, include metadata (created_at, expires_at, request_hash), and handle response size limits (compress if > 1MB, reject if > 10MB).
+8. Test with duplicate submissions: verify same response returned for duplicate key, verify no duplicate side effects (double charge, double email), verify concurrent duplicates resolve safely, and verify expired keys allow re-execution.
+9. Document retry safety in API contract: specify which endpoints are idempotent, required headers (Idempotency-Key format), safe retry window (TTL), and error responses for key conflicts (409) and expired keys (410 Gone).
+10. Log idempotency design in AUDIT with: endpoint, key strategy, storage backend, TTL, concurrent handling approach, and retry semantics.
+</process>

package/.agent/mindforge/init-org.md

@@ -0,0 +1,135 @@
+---
+description: Set up MindForge at the organisation level — create standardised org-level
+---
+
+# MindForge — Init Org Command
+# Usage: /mindforge:init-org [--org-name "Name"] [--update]
+
+## Purpose
+Set up MindForge at the organisation level — create standardised org-level
+context files that are shared across ALL projects in the organisation.
+
+Intended to be run ONCE by a platform engineer or engineering lead.
+Output is committed to a shared `mindforge-org-config` repository
+and distributed to projects as a git submodule or npm package.
+
+## Step 1 — Gather org information
+
+Ask (one question at a time):
+1. "What is your organisation name?"
+2. "Describe what your organisation builds in 1-2 sentences."
+3. "What is your primary tech stack? (describe in plain English)"
+4. "What is your default deployment target? (AWS / GCP / Azure / self-hosted / hybrid)"
+5. "What regulatory frameworks apply to your organisation?"
+   Options: GDPR / HIPAA / SOC 2 / PCI-DSS / ISO 27001 / None / Multiple
+6. "What is your source control platform?" (GitHub / GitLab / Bitbucket / Azure DevOps)
+7. "What is your issue tracker?" (Jira / GitHub Issues / Linear / Azure DevOps / None)
+8. "Who are your Tier 3 compliance approvers? (email addresses, comma-separated)"
+
+## Step 2 — Generate org-level context files
+
+Create (or update with `--update`) these files:
+
+### `.mindforge/org/ORG.md`
+Populated from answers with:
+- Organisation identity and mission
+- Default tech stack with version recommendations
+- Architecture defaults
+- Team conventions
+- Compliance requirements
+
+### `.mindforge/org/CONVENTIONS.md`
+Generate sensible defaults based on the tech stack detected.
+For TypeScript/Node.js stacks: strict TypeScript, ESLint, Conventional Commits
+For Python stacks: ruff, mypy, black formatting
+For Go: standard Go toolchain conventions
+Mark each section clearly: [DEFAULT] or [CUSTOMISE THIS]
+
+### `.mindforge/org/SECURITY.md`
+Generate based on declared compliance frameworks:
+- GDPR → include GDPR-specific policies
+- HIPAA → include PHI handling requirements
+- PCI-DSS → include card data handling policies
+- SOC 2 → include access control requirements
+Mark critical sections: [REVIEW WITH SECURITY TEAM]
+
+### `.mindforge/org/TOOLS.md`
+Generate approved library list based on tech stack.
+Include common forbidden libraries (moment.js, request, etc.)
+Mark: [ADD YOUR APPROVED LIBRARIES]
+
+### `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`
+Pre-populate based on declared platforms:
+- GitHub → fill GitHub config section
+- Jira → fill Jira config section
+Mark credential fields clearly: [SET VIA ENVIRONMENT VARIABLE]
+
+### `.mindforge/governance/GOVERNANCE-CONFIG.md`
+Pre-populate based on declared approvers and compliance frameworks.
+Higher compliance burden → lower Tier 2/3 thresholds.
+Stricter approval SLAs for HIPAA/PCI-DSS organisations.
+
+## Step 3 — Generate skills recommendation
+
+Based on the tech stack and compliance requirements, recommend skills to install:
+
+```
+Recommended skills for your tech stack:
+
+Core skills (already included — v0.6.0):
+  ✅ security-review, code-quality, api-design, testing-standards, documentation,
+     performance, accessibility, data-privacy, incident-response, database-patterns
+
+Additional skills recommended for your stack:
+  [tech-stack-specific recommendations from registry]
+
+For your compliance requirements:
+  [compliance-specific skill recommendations]
+
+Install all recommendations?
+  yes → npx mindforge-skills install [list]
+  no  → I'll show you the install commands for each
+```
+
+## Step 4 — Create distribution package
+
+Offer to create an org-skills npm package for distributing org-level config:
+
+```
+Create `@your-org/mindforge-config` npm package?
+This package will distribute your org-level MindForge configuration
+to all projects in your organisation via: npx @your-org/mindforge-config
+
+Files included:
+  .mindforge/org/ORG.md
+  .mindforge/org/CONVENTIONS.md
+  .mindforge/org/SECURITY.md
+  .mindforge/org/TOOLS.md
+  .mindforge/org/skills/MANIFEST.md
+  .mindforge/org/integrations/INTEGRATIONS-CONFIG.md (without credentials)
+  .mindforge/governance/GOVERNANCE-CONFIG.md (without credentials)
+```
+
+## Step 5 — Write AUDIT entry and report
+
+```json
+{ "event": "org_initialised", "org_name": "[name]", "compliance_frameworks": [...], "skills_recommended": [...] }
+```
+
+Report:
+```
+✅ MindForge organisation configuration complete.
+
+Files created:
+  .mindforge/org/ORG.md
+  .mindforge/org/CONVENTIONS.md
+  .mindforge/org/SECURITY.md
+  .mindforge/org/TOOLS.md
+  .mindforge/governance/GOVERNANCE-CONFIG.md
+
+Next steps:
+  1. Review each file — look for [CUSTOMISE THIS] markers
+  2. Fill in SECURITY.md with your security team
+  3. Commit to your org's mindforge-config repository
+  4. Share with all projects: npx @your-org/mindforge-config (if you created the package)
+```

package/.agent/mindforge/init-project.md

@@ -0,0 +1,170 @@
+---
+description: Initialise a new project under the MindForge framework.
+---
+
+Initialise a new project under the MindForge framework.
+
+## Pre-check
+Read `.planning/PROJECT.md`. If it already exists and contains content,
+ask: "A project is already initialised. Do you want to reinitialise? (yes/no)"
+Stop if the user says no.
+
+## Pre-flight Environment Check
+Verify that `CLAUDE.md` exists at the root of the project and `.claude/commands/mindforge/` is populated. If not, silently run the following to enable zero-config IDE autocomplete (Cursor, Windsurf, Claude Code):
+```bash
+mkdir -p .claude/commands/mindforge
+cp -r .agent/mindforge/* .claude/commands/mindforge/ 2>/dev/null || true
+cp -r .agents/workflows/* .claude/commands/mindforge/ 2>/dev/null || true
+cp .agent/CLAUDE.md ./CLAUDE.md 2>/dev/null || true
+cp .agent/CLAUDE.md ./.cursorrules 2>/dev/null || true
+cp .agent/CLAUDE.md ./.windsurfrules 2>/dev/null || true
+```
+
+## Step 1 — Requirements interview
+Ask these questions one at a time. Wait for the full answer before asking the next.
+Do not batch them. Do not rush.
+
+1. "What is this project? Give me a 1-2 sentence description."
+2. "Who is the primary user? Describe them specifically."
+3. "What problem does this solve for them? What is the pain today?"
+4. "What tech stack do you want to use? (Say 'recommend one' if unsure.)"
+   — If they say recommend: ask 3 clarifying questions about team size,
+     deployment environment, and performance requirements. Then recommend
+     a specific stack with brief rationale for each choice.
+5. "What is explicitly NOT in scope for v1? Name at least 3 things."
+6. "What does a successful v1 look like? How will you know it worked?"
+7. "Are there any compliance requirements? (GDPR, HIPAA, SOC2, PCI-DSS, none)"
+
+## Step 2 — Create context files
+
+Write `.planning/PROJECT.md`:
+```markdown
+# [Project Name]
+[One-line description]
+
+## Problem statement
+[From answer 3]
+
+## Target user
+[From answer 2]
+
+## Tech stack
+| Layer      | Choice          | Rationale                      |
+|------------|-----------------|--------------------------------|
+| [layer]    | [technology]    | [why]                          |
+
+## v1 scope — IN
+[Bullet list of what is included]
+
+## v1 scope — OUT (explicitly excluded)
+[Bullet list from answer 5]
+
+## Success criteria
+[From answer 6]
+
+## Compliance
+[From answer 7]
+
+## Initialised
+[ISO 8601 timestamp]
+```
+
+Write `.planning/REQUIREMENTS.md`:
+```markdown
+# Requirements — [Project Name]
+
+## Functional requirements
+| ID    | Requirement              | Acceptance criterion           | Scope |
+|-------|--------------------------|--------------------------------|-------|
+| FR-01 |                          |                                | v1    |
+
+## Non-functional requirements
+| ID     | Category      | Requirement                    | Measure        |
+|--------|---------------|--------------------------------|----------------|
+| NFR-01 | Performance   |                                |                |
+| NFR-02 | Security      |                                |                |
+| NFR-03 | Availability  |                                |                |
+
+## Out of scope
+[Items explicitly excluded from v1]
+```
+
+Write `.planning/STATE.md`:
+```markdown
+# MindForge — Project State
+
+## Status
+Project initialised. No phases started.
+
+## Current phase
+None
+
+## Last completed task
+Project initialisation
+
+## Next action
+Run /mindforge:plan-phase 1 to begin planning Phase 1.
+
+## Decisions made
+- Project scope defined (see PROJECT.md)
+- Tech stack chosen (see PROJECT.md)
+
+## Active blockers
+None
+
+## Last updated
+[ISO 8601 timestamp]
+```
+
+Write `.planning/HANDOFF.json`:
+```json
+{
+  "schema_version": "1.0.0",
+  "project": "[project name]",
+  "phase": null,
+  "plan": null,
+  "plan_step": null,
+  "last_completed_task": {
+    "description": "Project initialisation",
+    "commit_sha": null,
+    "verified": true
+  },
+  "next_task": "Run /mindforge:plan-phase 1",
+  "in_progress": {
+    "file": null,
+    "intent": null,
+    "completed_steps": [],
+    "remaining_steps": []
+  },
+  "blockers": [],
+  "decisions_needed": [],
+  "context_refs": [
+    ".planning/PROJECT.md",
+    ".planning/STATE.md",
+    ".planning/REQUIREMENTS.md"
+  ],
+  "agent_notes": "Fresh project. Read PROJECT.md and REQUIREMENTS.md before planning.",
+  "session_summary": "Project initialised.",
+  "recent_files": [
+    ".planning/PROJECT.md",
+    ".planning/REQUIREMENTS.md",
+    ".planning/STATE.md",
+    ".planning/HANDOFF.json"
+  ],
+  "recent_commits": [],
+  "updated_at": "[ISO 8601 timestamp]",
+  "_warning": "Never store secrets, tokens, or passwords in this file. It is tracked in git."
+}
+```
+
+## Step 3 — Confirm and guide
+Tell the user:
+"✅ MindForge project initialised.
+
+Files created:
+  .planning/PROJECT.md
+  .planning/REQUIREMENTS.md
+  .planning/STATE.md
+  .planning/HANDOFF.json
+
+Next step: Run /mindforge:plan-phase 1 to plan your first phase."

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

@@ -0,0 +1,28 @@
+---
+description: Follow the full installation protocol from .mindforge/distribution/registry-client.md.
+---
+
+Follow the full installation protocol from `.mindforge/distribution/registry-client.md`.
+
+Steps:
+1. Resolve package name from skill name.
+2. Check if already installed (skip if same version, offer upgrade if newer).
+3. Fetch from registry (npm or private if --registry specified).
+4. Validate the skill:
+   ```bash
+   node bin/mindforge-cli.js validate-skill ./SKILL.md
+   ```
+5. Run injection guard check (handled by validator).
+6. Install to tier directory:
+   ```bash
+   node bin/mindforge-cli.js install-skill [skill-name] --tier [1|2|3]
+   ```
+7. Register in MANIFEST.md:
+   ```bash
+   node bin/mindforge-cli.js register-skill [skill-name] [version] [tier]
+   ```
+8. Write AUDIT entry:
+   ```bash
+   node bin/mindforge-cli.js audit-skill [skill-name] [version] [tier]
+   ```
+9. Confirm: "Run /mindforge:skills validate to verify installation"

package/.agent/mindforge/introspect.md

@@ -0,0 +1,46 @@
+---
+description: Debug agent behavior or failures using 4-phase self-diagnosis. Usage - /mindforge:introspect [--last-failure] [--session] [--stuck]
+---
+
+<objective>
+When the agent is stuck, producing incorrect outputs, or wasting tokens,
+run structured self-diagnosis to identify and recover from the failure.
+</objective>
+
+<execution_context>
+@.mindforge/skills/agent-introspection-debugging/SKILL.md
+@.mindforge/engine/autonomous/stuck-detector.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse flags: --last-failure (analyze most recent failure), --session (review current session), --stuck (analyze stuck signals).
+2. **Phase 1 — Failure Capture:**
+   - If --last-failure: read recent AUDIT entries for the failed task
+   - If --session: scan current session for quality degradation signals
+   - If --stuck: read stuck-detector.md signals and iteration count
+   - Document: what was attempted, what happened, what was expected
+3. **Phase 2 — Diagnosis:**
+   - Match symptoms to failure mode table:
+     - Context overflow? (repeating mistakes, forgetting constraints)
+     - Hallucination? (confident claims about non-existent things)
+     - Loop spinning? (same action 3+ times without progress)
+     - Scope creep? (task expanding beyond spec)
+     - Stale context? (acting on outdated info)
+   - Identify the root cause (not just symptoms)
+4. **Phase 3 — Contained Recovery:**
+   - Identify MINIMUM change needed to recover
+   - Do NOT restart from scratch unless necessary
+   - Do NOT make speculative changes
+   - Attempt recovery (max 2 attempts)
+   - If recovery fails: escalate to user
+5. **Phase 4 — Introspection Report:**
+   - Write to `.planning/INTROSPECTION-[timestamp].md`
+   - Include: failure type, root cause, recovery action, prevention recommendation
+   - Consider: should this become an instinct? (via learn-instinct)
+6. Log introspection event in AUDIT.
+7. If recovery succeeded: resume work. If not: present report and await user direction.
+</process>

package/.agent/mindforge/iot.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:iot
+description: "Design IoT platform architecture. Usage: /mindforge:iot [component] [--protocol mqtt|coap|http] [--scale devices]"
+argument-hint: "[component] [--protocol mqtt|coap|http] [--scale devices]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Designs IoT platform architectures for device connectivity, telemetry ingestion, command/control, and edge computing. Produces designs for MQTT/CoAP brokers, device management, time-series data storage, real-time analytics, and firmware update systems with support for millions of concurrent devices.
+</objective>
+
+<execution_context>
+@.mindforge/skills/iot-platform/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/iot-platform/`
+State: Evaluates IoT use case, device scale, protocol requirements, and produces architecture with device provisioning, telemetry pipelines, edge processing, and device twin patterns for industrial, consumer, and smart city applications.
+</context>
+
+<process>
+1. **Use Case Analysis**: Identify IoT domain (industrial monitoring, smart home, connected vehicles, agriculture) and classify device types (sensors, actuators, gateways), communication patterns (telemetry streaming, command/response, firmware updates), and scale (thousands to millions of devices).
+2. **Protocol Architecture**: Select communication protocols based on device constraints (MQTT for reliable messaging, CoAP for constrained devices, HTTP/REST for simple integrations), design pub/sub topic hierarchies, and implement protocol gateways for multi-protocol support with TLS encryption.
+3. **Device Management**: Design device lifecycle management with secure provisioning (X.509 certificates, token-based auth), device registry with metadata/tags, health monitoring with heartbeat tracking, and bulk operations for fleet management (configuration updates, diagnostics).
+4. **Telemetry Ingestion**: Architect high-throughput data ingestion pipeline with MQTT broker clustering (EMQX, HiveMQ), message queuing (Kafka, Pulsar) for decoupling, and time-series database (InfluxDB, TimescaleDB) for sensor data storage with downsampling and retention policies.
+5. **Edge Computing**: Implement edge processing with local data filtering/aggregation to reduce bandwidth, edge analytics for real-time anomaly detection, offline operation with store-and-forward capabilities, and edge AI model deployment for predictive maintenance.
+6. **Command and Control**: Design bidirectional communication for remote device control with command queuing, acknowledgment patterns, timeout handling, and desired state management using device twin/shadow patterns for eventually consistent configuration.
+7. **Analytics and Visualization**: Build real-time dashboards for device status monitoring, streaming analytics for alerting on threshold violations, historical trend analysis, and integration with ML pipelines for predictive analytics using telemetry data.
+</process>

package/.agent/mindforge/knowledge-graph.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:knowledge-graph
+description: "Design knowledge graph architecture. Usage: /mindforge:knowledge-graph [domain] [--db neo4j|neptune|dgraph] [--scale nodes]"
+argument-hint: "[domain] [--db neo4j|neptune|dgraph] [--scale nodes]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design a scalable knowledge graph system for relationship-rich data modeling, entity resolution, and semantic querying. This command creates graph database architecture with schema design, query optimization strategies, entity linking pipelines, and reasoning capabilities for complex relationship traversals and inference.
+</objective>
+
+<execution_context>
+@.mindforge/skills/knowledge-graphs/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/knowledge-graphs/`
+State: Analyzes domain entity relationships, query patterns, scale requirements, and reasoning needs to design graph schema, database selection, ingestion pipelines, and query optimization strategies.
+</context>
+
+<process>
+1. **Domain and Schema Modeling**: Identify core entities and relationship types, design ontology with classes, properties, and constraints, model multi-hop relationships and temporal dimensions, and define cardinality rules and validation logic.
+
+2. **Graph Database Selection**: Compare options (Neo4j for ACID/Cypher, Neptune for AWS integration, Dgraph for distributed scale), evaluate trade-offs (consistency vs availability, query expressiveness vs performance), and specify deployment topology (single-node, cluster, multi-region).
+
+3. **Data Ingestion and ETL**: Design entity extraction pipelines from structured/unstructured sources, implement entity resolution and deduplication with fuzzy matching, create relationship inference rules from co-occurrence patterns, and build incremental update mechanisms for real-time graphs.
+
+4. **Query Optimization**: Implement indexing strategies for high-cardinality properties, design query patterns for common traversals (shortest path, neighborhood expansion, pattern matching), optimize for specific workloads (OLTP vs OLAP graph queries), and create materialized views for frequent aggregations.
+
+5. **Entity Linking and Enrichment**: Design entity disambiguation with contextual embeddings, implement cross-source entity alignment, create knowledge base augmentation from external graphs (Wikidata, DBpedia), and build confidence scoring for inferred relationships.
+
+6. **Graph Reasoning and Inference**: Implement rule-based inference (transitive closure, property inheritance), design probabilistic reasoning with uncertainty quantification, create graph neural network embeddings for link prediction, and specify reasoning depth limits for query performance.
+
+7. **Monitoring and Maintenance**: Define graph quality metrics (completeness, consistency, freshness), implement anomaly detection for suspicious relationships, design archival and pruning strategies for temporal graphs, and create versioning mechanisms for schema evolution.
+</process>

package/.agent/mindforge/lakehouse.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:lakehouse
+description: "Design data lakehouse architecture. Usage: /mindforge:lakehouse [domain] [--format delta|iceberg|hudi] [--layer bronze|silver|gold]"
+argument-hint: "[domain] [--format delta|iceberg|hudi] [--layer bronze|silver|gold]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive lakehouse system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/data-lakehouse/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/data-lakehouse/`
+State: Analyzes requirements, constraints, and scale to generate optimized lakehouse 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/lead.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:lead
+description: "Technical leadership guidance and decision framework. Usage: /mindforge:lead [situation] [--context team|org|technical]"
+argument-hint: "[situation] [--context team|org|technical]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Provides technical leadership guidance for decision-making, team management, and organizational influence. Produces frameworks for handling complex situations including technical direction, conflict resolution, career development, and strategic planning for engineering leaders at all levels.
+</objective>
+
+<execution_context>
+@.mindforge/skills/technical-leadership/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/technical-leadership/`
+State: Evaluates leadership challenges, organizational context, and produces actionable frameworks with decision matrices, communication strategies, and stakeholder management approaches for technical leaders.
+</context>
+
+<process>
+1. **Situation Analysis**: Identify leadership challenge category (technical decision-making, people management, cross-functional collaboration, organizational change) and assess scope of impact (team, department, organization), urgency (immediate, short-term, strategic), and stakeholder complexity.
+2. **Context Mapping**: Map organizational context including reporting structure, decision-making authority, team dynamics, cultural norms, and political landscape to understand constraints and leverage points for effective leadership.
+3. **Decision Framework**: Apply appropriate decision-making framework (RACI for ownership clarity, trade-off analysis for technical choices, stakeholder mapping for buy-in, forcing functions for priority decisions) based on situational characteristics.
+4. **Communication Strategy**: Design multi-level communication plan with tailored messaging for different audiences (executives, peers, direct reports, cross-functional partners) considering timing, medium (written, verbal, visual), and feedback mechanisms.
+5. **People Development**: Address team growth needs with career development frameworks, delegation strategies matching skill levels, mentorship approaches, performance feedback models, and creating psychological safety for innovation and healthy conflict.
+6. **Influence Patterns**: Implement influence strategies including building coalitions, leveraging data and prototypes for technical persuasion, managing up with executive-friendly communication, and navigating organizational politics with integrity.
+7. **Action Plan**: Generate specific action plan with timelines, success metrics, contingency options, and reflection checkpoints to adapt approach based on outcomes and new information emerging from implementation.
+</process>