mindforge-cc 2.0.0 → 2.1.1

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

@@ -1,23 +1,29 @@
-Show all available MindForge commands.
+---
+name: mindforge:help
+description: Show all available MindForge commands and current project summary
+argument-hint: none
+allowed-tools:
+  - list_dir
+  - view_file
+---
 
-## Pre-check
-If `.planning/STATE.md` exists, read it.
-If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
+<objective>
+Provide a searchable, categorized directory of all accessible MindForge commands, along with a quick snapshot of the project's current state.
+</objective>
 
-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:
+<execution_context>
+.claude/commands/mindforge/help.md
+</execution_context>
 
-| Command                      | Description                                  |
-|------------------------------|----------------------------------------------|
-| /mindforge:help              | Show all available commands                  |
-| /mindforge:init-project      | ...                                          |
-| ...                          | ...                                          |
+<context>
+Discovery: Scans `.claude/commands/mindforge/*.md`
+State: PROJECT.md and STATE.md
+</context>
 
-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 the agent's system context.
+<process>
+1. **Command Scan**: List all markdown definitions in the command directory and extract their first-line descriptions or YAML metadata.
+2. **Read Project Info**: Summarize the current project name, active phase, and recommended next step.
+3. **Format Dashboard**: Render a clean table of commands and descriptions.
+4. **Verify Context**: If `CLAUDE.md` hasn't been read in the current session, remind the user to load it as the agent's context.
+5. **Display**: Present the help table and project summary.
+</process>

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

@@ -1,131 +1,37 @@
-# 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)
-```
+---
+name: mindforge:init-org
+description: Set up MindForge at the organization level with standardized context
+argument-hint: [--org-name "Name"] [--update]
+allowed-tools:
+  - run_command
+  - list_dir
+  - write_to_file
+  - view_file
+---
+
+<objective>
+Establish a consistent engineering culture and governance framework by generating organization-wide context files, security policies, and tech stack defaults for all projects.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/init-org.md
+</execution_context>
+
+<context>
+Scope: Organization-wide (Tier 1/2).
+Output: Shared `.mindforge/org/` repository or npm package.
+Governance: Defines Tier 2/3 approver lists and compliance burdens.
+</context>
+
+<process>
+1. **Interview**: Conduct a structured interview about org identity, tech stack, deployment defaults, and compliance (GDPR, HIPAA, etc.).
+2. **Generate Defaults**:
+    - `ORG.md`: Mission and global architecture defaults.
+    - `CONVENTIONS.md`: Tech-stack-specific coding standards.
+    - `SECURITY.md`: Compliance-mapped security policies.
+    - `TOOLS.md`: Approved library and dependency list.
+3. **Configuration**: Pre-populate `INTEGRATIONS-CONFIG.md` and `GOVERNANCE-CONFIG.md`.
+4. **Skill Recommendation**: Suggest core and compliance skills to install org-wide.
+5. **Distribution**: Offer to package the configuration into an npm package for project-wide inheritance.
+6. **Audit**: Log `org_initialised` with frameworks and recommended skills.
+</process>

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

@@ -1,155 +1,40 @@
-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.
-
-## 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."
+---
+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
+---
+
+<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>

package/.claude/commands/mindforge/install-skill.md

@@ -1,15 +1,32 @@
-# MindForge — Install Skill Command
-# Usage: /mindforge:install-skill [skill-name|package-name] [--tier 1|2|3] [--registry URL]
-
-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 (Level 1 + Level 2 from skill-validator.md)
-5. Run injection guard check
-6. Install to tier directory (default: Tier 2 org skill)
-7. Register in MANIFEST.md
-8. Write AUDIT entry
-9. Confirm: "Run /mindforge:skills validate to verify installation"
+---
+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
+---
+
+<objective>
+Enable the rapid extension of agent capabilities by resolving, downloading, validating, and registering pre-built skills from official or private registries.
+</objective>
+
+<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>

package/.claude/commands/mindforge/learn.md

@@ -1,142 +1,36 @@
-# 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 npm:drizzle-orm
-/mindforge:learn npm:@tanstack/react-query
-```
-→ Fetches README from npm registry
-→ 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
-}
-```
+---
+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
+---
+
+<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>