mindforge-cc 11.3.0 → 11.3.1

package/.claude/commands/mindforge/graphql.md

@@ -0,0 +1,31 @@
+---
+description: Design GraphQL schema and resolver architecture. Usage - /mindforge:graphql [domain] [--style code-first|schema-first] [--federation]
+---
+
+<objective>
+Design a GraphQL schema and resolver architecture that models the domain
+accurately, prevents N+1 queries via DataLoader, implements cursor-based
+pagination for all lists, and provides production-ready configuration with
+persisted queries, depth limiting, and cost analysis.
+</objective>
+
+<execution_context>
+@.mindforge/skills/graphql-patterns/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Identify domain entities and their relationships: map core types (User, Order, Product), their fields, and connections between them (User has many Orders, Order has many LineItems). Determine which relationships are required vs optional, and identify aggregate roots.
+2. Design the type schema based on --style flag: code-first (TypeGraphQL/Nexus — types generated from code, better for rapid iteration) or schema-first (SDL files — explicit contract, better for API-first design). Follow naming conventions: PascalCase for types, camelCase for fields.
+3. Implement connections for all list fields using cursor-based pagination: define Connection/Edge/PageInfo types per Relay spec, use opaque cursors (base64-encoded id or timestamp), support first/after and last/before arguments, and include totalCount as optional expensive field.
+4. Add DataLoader for ALL nested resolvers to prevent N+1 queries: create one DataLoader per entity type per request (request-scoped), batch all IDs collected in a single event loop tick, implement caching within request lifecycle, and verify with query logging that batch queries fire.
+5. Design mutations with input types and meaningful returns: use Input suffix for mutation arguments (CreateUserInput), return the modified entity (not just ID), include userErrors field for domain validation errors (separate from GraphQL errors), and make mutations as specific as possible (updateUserEmail vs generic updateUser).
+6. Configure subscriptions if real-time is needed: use WebSocket transport (graphql-ws protocol), implement subscription resolvers with pub/sub backend (Redis), filter events per subscriber (only receive own tenant's events), and handle connection lifecycle (keepalive, reconnection).
+7. Set up persisted queries for production: extract all queries at build time into a query map (hash -> query text), reject arbitrary queries in production (allowlist mode), reduce bandwidth (client sends hash instead of full query), and prevent malicious query injection.
+8. Implement security and performance guards: query depth limiting (max 7 levels), query cost analysis (assign cost to each field/connection), rate limiting per operation complexity, disable introspection in production, and field-level authorization directives.
+9. Configure federation if --federation flag set: identify subgraph boundaries (one per domain team), define entity types with @key directives, implement reference resolvers for cross-subgraph lookups, and configure the gateway (Apollo Router or similar).
+10. Log GraphQL design in AUDIT with: domain entities, schema style, pagination approach, DataLoader coverage, subscription needs, persisted query strategy, and federation topology.
+</process>

package/.claude/commands/mindforge/health.md

@@ -0,0 +1,31 @@
+---
+description: Run all seven health-engine categories from .mindforge/intelligence/health-engine.md.
+---
+
+# MindForge — Health Command
+# Usage: /mindforge:health [--repair] [--category C] [--verbose]
+
+Run all seven health-engine categories from `.mindforge/intelligence/health-engine.md`.
+
+## Output
+- category status summary
+- errors (must fix)
+- warnings (should fix)
+- informational signals
+
+## Sovereign Intelligence Checks (v6.2.0-alpha)
+- **PQAS Verification**: Check `bin/governance/quantum-crypto.js` presence
+- **Homing Verification**: Check `bin/autonomous/intent-harvester.js` presence
+- **Self-Healer Verification**: Check `bin/autonomous/mesh-self-healer.js` presence
+- **Policy Check**: Verify `bin/governance/policy-engine.js` is Sovereign-configured
+
+## Flags
+- `--repair`: apply safe auto-repair only
+- `--category`: one of `installation|context|skills|personas|state|integrations|security`
+- `--verbose`: include passing checks and exact inspected values
+
+## AUDIT
+Append:
+```json
+{ "event": "health_check_completed", "errors": 0, "warnings": 0, "repaired": 0 }
+```

package/.claude/commands/mindforge/healthcare.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:healthcare
+description: "Design HIPAA-compliant healthcare system architecture. Usage: /mindforge:healthcare [service] [--standard hipaa|hl7|fhir] [--scope full|audit]"
+argument-hint: "[service] [--standard hipaa|hl7|fhir] [--scope full|audit]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Designs HIPAA-compliant healthcare system architectures with proper PHI handling, audit trails, and regulatory compliance. Produces architecture diagrams, data flow models, and compliance checklists for healthcare applications including EHR, telemedicine, patient portals, and health data exchanges.
+</objective>
+
+<execution_context>
+@.mindforge/skills/healthcare-systems/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/healthcare-systems/`
+State: Evaluates healthcare service requirements, compliance standards (HIPAA, HL7, FHIR), and produces compliant architecture with security controls, encryption strategies, and audit mechanisms.
+</context>
+
+<process>
+1. **Service Analysis**: Parse the healthcare service type (EHR, telemedicine, patient portal, HIE) and identify PHI touchpoints, user roles, and data sensitivity classification.
+2. **Compliance Mapping**: Map required compliance standards (HIPAA Security/Privacy Rules, HL7 messaging, FHIR resources) to architectural components and identify technical safeguards (encryption at rest/in transit, access controls, audit logs).
+3. **Architecture Design**: Design system architecture with secure zones (DMZ, application tier, data tier), authentication/authorization flows (RBAC, ABAC), and PHI access patterns with minimum necessary principle.
+4. **Data Flow Modeling**: Model PHI data flows across system boundaries, external integrations (labs, pharmacies, insurance), and patient data exchange patterns with encryption and consent management.
+5. **Audit Trail Design**: Design comprehensive audit logging for all PHI access (who, what, when, where, why), tamper-proof log storage, and automated compliance reporting mechanisms.
+6. **Security Controls**: Define encryption standards (AES-256, TLS 1.3), key management (HSM, KMS), session management, and incident response procedures for breach notification.
+7. **Documentation Generation**: Generate compliance documentation including Security Risk Assessment, BAA requirements, technical safeguards matrix, and architecture decision records for regulatory audits.
+</process>

package/.claude/commands/mindforge/help.md

@@ -0,0 +1,33 @@
+---
+description: Show all available MindForge commands.
+---
+
+Show all available MindForge commands.
+
+## Pre-check
+If `.planning/STATE.md` exists, read it.
+If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
+
+1. Scan every .md file in `.claude/commands/mindforge/`
+2. For each file, extract the first non-empty line as the command description
+3. Display as a clean table:
+
+| Command                      | Description                                  |
+|------------------------------|----------------------------------------------|
+| /mindforge:help              | Show all available commands                  |
+| /mindforge:init-project      | ...                                          |
+| ...                          | ...                                          |
+
+## Sovereign Intelligence (v6.2.0-alpha)
+MindForge now operates with **Sovereign Intelligence** enabled by default:
+- **PQAS**: Post-Quantum Agentic Security is active. High-risk operations require biometric/executive bypass.
+- **Proactive Homing**: The swarm now proactively harvests intent and self-heals reasoning drifts.
+- **Integrity**: Every `security-scan` now verifies framework signatures using lattice-based cryptography.
+
+4. After the table, print:
+   "Current project: [read PROJECT.md first line, or 'Not initialised']"
+   "Current phase:   [read STATE.md current phase, or 'None']"
+   "Next step:       [read STATE.md next action]"
+
+5. If CLAUDE.md has not been read this session, remind the user to ensure
+   it is loaded as MindForge's system context.

package/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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/.claude/commands/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>