mindforge-cc 6.2.0-alpha → 6.2.0

package/.claude/commands/mindforge/init-project.md

@@ -1,40 +1,170 @@
 ---
-name: mindforge:init-project
-description: Initialise a new project under the MindForge framework
-argument-hint: none
-allowed-tools:
-  - view_file
-  - write_to_file
-  - list_dir
+description: Initialise a new project under the MindForge framework.
 ---
 
-<objective>
-Initialise a new project by conducting a structured requirements interview, setting up the `.planning/` directory, and creating the foundational context files (PROJECT.md, REQUIREMENTS.md, STATE.md, HANDOFF.json).
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/init-project.md
-</execution_context>
-
-<context>
-Target Directory: .planning/
-State: Checks if .planning/PROJECT.md already exists before re-initialising.
-</context>
-
-<process>
-1. **Pre-check**: Read `.planning/PROJECT.md`. If it exists, ask the user if they want to re-initialise.
-2. **Requirements Interview**: Ask the following 7 questions one by one:
-    - Description of the project.
-    - Primary user description.
-    - Problem statement.
-    - Tech stack (recommend one if requested).
-    - Scope exclusions (v1).
-    - Success criteria.
-    - Compliance requirements.
-3. **Generate Context Files**:
-    - Write `.planning/PROJECT.md` with the interview results.
-    - Write `.planning/REQUIREMENTS.md` with functional and non-functional tables.
-    - Write `.planning/STATE.md` set to "Project initialised".
-    - Write `.planning/HANDOFF.json` with initial state and context references.
-4. **Finalize**: Confirm the creation of files and guide the user to the next step (`/mindforge:plan-phase 1`).
-</process>
+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

@@ -1,32 +1,28 @@
 ---
-name: mindforge:install-skill
-description: Install a skill from a remote registry or package
-argument-hint: [skill-name|package-name] [--tier 1|2|3] [--registry URL]
-allowed-tools:
-  - run_command
-  - list_dir
-  - write_to_file
+description: Follow the full installation protocol from .mindforge/distribution/registry-client.md.
 ---
 
-<objective>
-Enable the rapid extension of agent capabilities by resolving, downloading, validating, and registering pre-built skills from official or private registries.
-</objective>
+Follow the full installation protocol from `.mindforge/distribution/registry-client.md`.
 
-<execution_context>
-.claude/commands/mindforge/install-skill.md
-</execution_context>
-
-<context>
-Registry Client: registry-client.md
-Validation: Level 1 + Level 2 via skill-validator.md.
-Security: Enforces injection guards before installation.
-</context>
-
-<process>
-1. **Resolve**: Map the skill name to its registry package name.
-2. **Fetch**: Download the package to a secure temporary directory.
-3. **Validate**: Run strict structural and security checks (Injection guards, frontmatter validation).
-4. **Deploy**: Move the skill to the target tier directory (Default: Tier 2).
-5. **Register**: Append the skill to `MANIFEST.md`.
-6. **Audit**: Log `skill_installed` event.
-</process>
+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/learn.md

@@ -1,36 +1,147 @@
 ---
-name: mindforge:learn
-description: Convert any knowledge source into a reusable, validated MindForge skill
-argument-hint: [url|path|--session|npm:package] [--name name] [--tier T]
-allowed-tools:
-  - read_url_content
-  - run_command
-  - view_file
-  - write_to_file
+description: Convert any knowledge source into a reusable, validated, committed MindForge SKILL.md.
 ---
 
-<objective>
-Capture institutional or technical knowledge from external documentation, local files, npm packages, or the current session and transform it into a structured, validated, and automatically-loading `SKILL.md` file.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/learn.md
-</execution_context>
-
-<context>
-Sources: URLs (with SSRF protection), local markdown/directories, npm READMEs, or session summaries.
-Models: Gemini 2.0 Pro (for large docs), Claude 3.5 Sonnet (for analysis).
-Tiers: project (T3), org (T2), core (T1).
-</context>
-
-<process>
-1. **Ingest Content**: Fetch the URL, read the local path, or pull the npm README.
-2. **Analyze Patterns**:
-    - Use high-context models to extract key architectural patterns.
-    - Generate 15-25 trigger keywords for automatic activation.
-3. **Draft Skill**: Write the initial `SKILL.md` following the standard template.
-4. **Score Quality**: Audit the draft against the quality rubric (triggers, actions, examples, safety).
-5. **Review**: Present the skill and its score (0-100) to the user for approval, editing, or registration.
-6. **Register**: Add the skill to the appropriate manifest tier and commit the change.
-7. **Audit**: Log `skill_learned` with source, name, quality score, and cost.
-</process>
+# MindForge v2 — Learn Command
+# Usage: /mindforge:learn [url|path|--session|npm:package] [--name skill-name] [--tier project|org|core]
+# Version: v2.0.0-alpha.6
+
+## Purpose
+Convert any knowledge source into a reusable, validated, committed MindForge SKILL.md.
+Feed Claude your documentation and it writes down what it learned — for every future session.
+
+## The insight
+Every developer on your team already knows how Prisma works, how your internal API
+conventions are structured, how your CI pipeline behaves. That knowledge lives in their
+heads and in documentation. `/mindforge:learn` captures it permanently as skills that
+load automatically whenever relevant work begins.
+
+## Usage examples
+
+### Learn from external documentation
+```
+/mindforge:learn https://docs.prisma.io/concepts/components/prisma-schema
+/mindforge:learn https://stripe.com/docs/webhooks
+/mindforge:learn https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html
+```
+→ Fetches the page (with SSRF protection)
+→ Uses Gemini 2.5 Pro (1M context) for large docs, claude-sonnet-4-6 for smaller ones
+→ Extracts 10 patterns + 15-25 trigger keywords
+→ Writes SKILL.md + scores it + presents for approval
+
+### Learn from local documentation
+```
+/mindforge:learn ./docs/api-conventions.md
+/mindforge:learn ./docs/internal/
+/mindforge:learn ./CONTRIBUTING.md
+```
+→ Reads local files directly (no model call for reading, only for analysis)
+→ Perfect for: internal API docs, team conventions, onboarding guides
+
+### Learn from npm package docs
+```
+/mindforge:learn npm:zod
+/mindforge:learn context7:zod
+/mindforge:learn npm:drizzle-orm
+/mindforge:learn context7:drizzle-orm
+```
+→ Fetches README from npm registry or real-time docs from Context7
+→ Extracts patterns from the package documentation
+
+### Learn from current session
+```
+/mindforge:learn --session
+```
+→ Analyses SUMMARY files from the most recent phase
+→ Finds patterns that appeared across 2+ tasks
+→ Generates up to 3 skills from what was learned (focused: quality over quantity)
+→ Does NOT repeat patterns already in the knowledge base
+
+## Flags
+
+### --name [skill-name]
+Override the auto-generated skill name (kebab-case).
+Default: inferred from the URL domain/path or file name.
+Example: `/mindforge:learn ./docs/prisma-patterns.md --name prisma-advanced`
+
+### --tier [project|org|core]
+Where to install the skill (default: project).
+- project: only loads in this project (T3)
+- org: loads in all projects using this org config (T2)
+- core: loads everywhere (T1 — use sparingly)
+
+### --model [model-id]
+Override the model used for analysis.
+Default: RESEARCH_MODEL for large content (>50K chars), EXECUTOR_MODEL for small.
+
+## Output format
+
+```
+📚 Learning from: https://docs.prisma.io/...
+
+  🔍 Fetching content...            done (148K chars)
+  🧠 Extracting patterns (gemini-2.5-pro)...
+  Step 1/3 — Extracting patterns... done (10 patterns)
+  Step 2/3 — Generating triggers... done (22 triggers)
+  Step 3/3 — Writing SKILL.md...    done
+
+📊 Skill Quality Score: 84/100 (Good — can register + publish)
+  trigger_coverage   : 26/30   ✅
+  mandatory_actions  : 21/25   ✅
+  code_examples      : 17/20   ✅
+  self_check         : 12/15   ✅
+  injection_safe     : 10/10   ✅
+  no_placeholders    : 9/10    ✅
+  version_history    : 8/10    ⚠️
+
+Preview (top 3 patterns):
+  1. [CRITICAL] Always define explicit cascade behaviour
+     "Set onDelete on every @relation — never rely on database defaults"
+  2. [HIGH] Use compound indexes for cursor pagination
+     "Always index (createdAt, id) together for reliable cursor pagination"
+  3. [HIGH] Never use String for UUID fields in Prisma schema
+     "Use @id @default(uuid()) with the String type — Prisma handles this"
+
+Triggers (22): prisma schema, schema.prisma, @relation, prisma migrate,
+               @id @default, prisma.findMany, prisma generate, model definition...
+
+Skill file: .mindforge/skills/prisma-schema/SKILL.md
+
+[ y ] Register in project tier and commit
+[ n ] Discard
+[ e ] Edit SKILL.md before registering
+[ p ] Register AND publish to community marketplace (score ≥ 80 ✅)
+```
+
+## After registration
+
+```
+✅ Skill registered: prisma-schema (T3 Project)
+
+  Will auto-load when tasks contain:
+    "prisma schema", "schema.prisma", "@relation", "prisma migrate"...
+
+  Committed: feat(skills): learn prisma-schema from docs.prisma.io
+
+  Next: /mindforge:skills info prisma-schema
+```
+
+## Integration with auto-capture
+When `AUTO_CAPTURE_SKILLS=true` in MINDFORGE.md:
+`/mindforge:learn --session` is called automatically after each phase completion.
+The prompt is shown; if no patterns found, it exits silently (no noise).
+
+## AUDIT entry
+```json
+{
+  "event": "skill_learned",
+  "source_type": "url|local|session|npm",
+  "source": "[url or path]",
+  "skill_name": "prisma-schema",
+  "quality_score": 84,
+  "pattern_count": 10,
+  "trigger_count": 22,
+  "tier": "project",
+  "cost_usd": 0.31
+}
+```

package/.claude/commands/mindforge/learning.md

@@ -0,0 +1,20 @@
+---
+description: Consult or initialize the project agentic learning memory - AGENTS_LEARNING.md
+---
+
+# /mindforge:learning [init]
+
+Consult the project's persistent engineering memory to avoid past mistakes and follow established best practices.
+
+## Usage
+
+- `/mindforge:learning`: Displays the current learning status and path to the learning file.
+- `/mindforge:learning init`: Initializes a new `AGENTS_LEARNING.md` in the project root if it doesn't already exist.
+
+## Why use this?
+Before starting any significant implementation or refactor, you MUST consult the learning memory. It contains project-specific "Anti-Patterns" to avoid and "Best Practices" that have been proven in this specific system.
+
+## Example
+1. Run `/mindforge:learning` to find where the learning file is.
+2. Read the file to understand recent architectural shifts or discovered failure scenarios.
+3. If the project is new, run `/mindforge:learning init` to scaffold the memory.