mindforge-cc 8.2.0 → 10.0.0

package/.agent/workflows/mindforge:learn.md

@@ -1,146 +0,0 @@
----
-description: Convert any knowledge source into a reusable, validated, committed MindForge SKILL.md.
----
-# 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/.agent/workflows/mindforge:map-codebase.md

@@ -1,301 +0,0 @@
----
-description: - Joining an existing project that has no MindForge context files
----
-# MindForge — Map Codebase Command
-# Usage: /mindforge:map-codebase [area]
-# Onboards MindForge to an existing (brownfield) codebase.
-# Run this INSTEAD of /mindforge:init-project when joining an existing project.
-
-## When to use this command
-- Joining an existing project that has no MindForge context files
-- Adding MindForge to a team that already has a codebase
-- Onboarding to a new-to-you repository
-- Re-mapping after major architectural changes
-
-## What it produces
-- `.planning/ARCHITECTURE.md` — system architecture discovered from code
-- `.planning/PROJECT.md` — project identity inferred from codebase + user confirmation
-- `.mindforge/org/CONVENTIONS.md` — actual conventions found in the code
-- `.planning/STATE.md` — current position (MindForge onboarded, ready to plan)
-- `.planning/decisions/ADR-NNN-[title].md` — key architectural decisions found
-
-## Pre-execution security check
-
-Before reading ANY files, build an exclusion list.
-NEVER read these file patterns during codebase mapping:
-
-```bash
-# Build the exclusion list
-EXCLUDED_PATTERNS=(
-  "*.env"         ".env.*"       "*.env.local"
-  "*.key"         "*.pem"        "*.p12"         "*.pfx"
-  "secrets/*"     "**/secrets/*" "**/.secrets/*"
-  "*.secret"      "*credentials*"
-  ".npmrc"        # may contain npm tokens
-  ".pypirc"       # may contain PyPI tokens
-  "~/.aws/*"      "~/.ssh/*"
-)
-```
-
-For any file the agent is about to read, check:
-1. Does the file name match any excluded pattern?
-2. Is the file in a directory named `secrets/`, `.secrets/`, or `credentials/`?
-3. Is the file listed in `.gitignore`? (`.gitignore` files are intentionally excluded from git for a reason)
-
-If yes to any: SKIP the file. Log that it was skipped.
-Do not include any content from excluded files in ARCHITECTURE.md or CONVENTIONS.md.
-
-## Step 0 — Clean up any previous mapping artifacts
-
-```bash
-# Remove any stale temp files from a previous mapping attempt
-if [ -d ".planning/map-temp" ]; then
-  echo "Cleaning up previous mapping session..."
-  rm -rf .planning/map-temp
-fi
-mkdir -p .planning/map-temp
-```
-
-## Step 1 — Codebase inventory
-
-Spawn FOUR parallel subagents. Each focuses on one analysis area.
-Each subagent writes its findings to a temporary file.
-
-### Subagent A — Technology Stack Analyst
-Context: minimal (CONVENTIONS.md template + task description)
-Persona: architect.md
-Task:
-```
-Analyse this repository's technology stack. Read:
-- package.json / requirements.txt / Cargo.toml / go.mod (root and workspaces)
-- Dockerfile, docker-compose.yml (if present)
-- CI/CD configuration: .github/workflows/, .gitlab-ci.yml, .circleci/
-- Infrastructure files: terraform/, pulumi/, k8s/, helm/
-
-Write to: .planning/map-temp/STACK.md
-Include:
-- Runtime/language and version
-- Framework(s) and versions
-- Database(s) used
-- Cache and queue systems
-- Testing framework(s)
-- Build and bundling tools
-- Deployment target (AWS/GCP/Azure/bare metal/etc.)
-- External services integrated (payment, email, auth, etc.)
-```
-
-### Subagent B — Architecture Analyst
-Context: minimal
-Persona: architect.md
-Task:
-```
-Analyse this repository's architecture. Read:
-- All files in src/ (or equivalent) — structure, not content
-- README.md and any docs/ directory
-- Any architecture diagrams (look for .png, .svg, .drawio in docs/)
-- Entry points: index.ts, main.py, app.go, server.ts (root-level)
-
-Write to: .planning/map-temp/ARCHITECTURE-RAW.md
-Include:
-- Architectural pattern: MVC / Clean Architecture / Hexagonal / Modular Monolith / Microservices
-- Domain model: what are the core entities? (infer from models/, entities/, types/)
-- API surface: public endpoints found in routes/, controllers/, handlers/
-- Module structure: how is the code organised? Feature-based / Layer-based?
-- Key design patterns in use: Repository, Service, Factory, Observer, etc.
-```
-
-### Scale handling for large codebases
-
-Before reading source files, count them:
-```bash
-find src/ -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) | wc -l
-```
-
-If count > 200 files: use sampling strategy instead of full read:
-- Read 3 files from each top-level subdirectory
-- Prioritise: largest files (by size), entry points (index.*, main.*, app.*)
-- Read the full Prisma schema / SQLAlchemy models / Django models file (always)
-- Read all route/controller index files (always)
-- Sample 2-3 files per feature directory
-- Do NOT read test files during mapping (they follow source patterns, not add to them)
-
-If count > 1000 files: read only entry points, schema files, and top-level indices.
-Report to the user: "Large codebase detected ([N] source files).
-Using sampling strategy — some conventions may require manual confirmation."
-
-### Subagent C — Conventions Analyst
-Context: minimal
-Persona: developer.md
-Task:
-```
-Analyse the actual coding conventions used in this repository.
-Read 5-10 representative source files from different areas of the codebase.
-
-Write to: .planning/map-temp/CONVENTIONS-RAW.md
-Infer and document:
-- Naming conventions: variables, functions, classes, files, database columns
-- Import order and grouping style
-- Error handling patterns: how are errors thrown and caught?
-- TypeScript patterns: preferred type patterns, generic usage
-- Comment style: JSDoc, inline, etc.
-- Test file naming and location pattern
-- Async patterns: callbacks / promises / async-await
-- State management (frontend): if applicable
-- Any recurring patterns that appear across multiple files
-
-Important: document what IS there, not what should be there.
-This is a description of reality, not a prescription.
-```
-
-### Subagent D — Quality Baseline Analyst
-Context: minimal
-Persona: qa-engineer.md
-Task:
-```
-Assess the current quality baseline of this repository.
-
-Write to: .planning/map-temp/QUALITY-BASELINE.md
-Check:
-- Test coverage: does a test suite exist? What framework? Run: [test command] --coverage
-- Linting: is a linter configured? (.eslintrc, .pylintrc, ruff.toml, etc.)
-- Type checking: TypeScript config? Strict mode enabled?
-- CI/CD: does it run tests on PRs?
-- Security: any security scanning in CI?
-- Known issues: open GitHub/GitLab issues, TODO count in source
-
-Note: do not fix anything. Only document what exists.
-```
-
-## Step 2 — Synthesise findings
-
-Read all four temp files. Synthesise into the permanent context files.
-
-### Write `.planning/ARCHITECTURE.md`
-
-Use ARCHITECTURE-RAW.md as input. Write a clean, structured architecture document:
-
-```markdown
-# [Project Name] — Architecture
-
-## System overview
-[2-3 sentences from the subagent's findings]
-
-## Technology stack
-[From STACK.md — organised by layer]
-
-## Architectural pattern
-[From ARCHITECTURE-RAW.md]
-
-## Domain model
-[Core entities and their relationships]
-
-## API surface
-[Key endpoints / GraphQL operations / gRPC services found]
-
-## Module structure
-[How the codebase is organised]
-
-## External integrations
-[Third-party services found]
-
-## Known architectural decisions
-[Any ADRs, architecture docs, or README decisions found]
-
-## Quality baseline
-[From QUALITY-BASELINE.md — honest assessment]
-
-## MindForge onboarding notes
-[What was inferred vs. confirmed, what needs human review]
-```
-
-### Write `.mindforge/org/CONVENTIONS.md`
-
-Use CONVENTIONS-RAW.md as input. Write the conventions file in the standard format,
-but clearly mark inferred conventions:
-
-```markdown
-# Coding Conventions — [Project Name]
-# Source: Inferred from codebase analysis by MindForge
-# Status: DRAFT — confirm with team before treating as authoritative
-
-## IMPORTANT
-These conventions were inferred from code analysis. Review each section
-and mark as [CONFIRMED] or [NEEDS REVIEW] before running /mindforge:plan-phase.
-
-## Naming conventions [NEEDS REVIEW]
-[What was found]
-```
-
-## Step 3 — Present findings for confirmation
-
-Present a summary to the user. Ask for confirmation and corrections:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-MindForge Codebase Analysis Complete
-
-  Stack:
-    Runtime   : Node.js 20 (inferred from .nvmrc)
-    Framework : Next.js 14 (inferred from package.json)
-    Database  : PostgreSQL via Prisma (inferred from prisma/schema.prisma)
-    Auth      : NextAuth.js (inferred from package.json)
-
-  Architecture:
-    Pattern   : Feature-based modular (inferred from src/ structure)
-    Entities  : User, Organization, Project, Task (inferred from Prisma schema)
-    API       : REST API in src/app/api/ (24 route files found)
-
-  Quality baseline:
-    Tests     : Vitest, ~340 test files, ~67% coverage (inferred from coverage report)
-    Linting   : ESLint configured, strict TypeScript
-    CI/CD     : GitHub Actions (4 workflows)
-
-  Conventions: see .mindforge/org/CONVENTIONS.md (DRAFT — needs review)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Does this look correct? (yes / correct [field]: [value] / no)
-```
-
-Wait for user confirmation. Apply any corrections the user provides.
-
-## Step 4 — Write PROJECT.md and STATE.md
-
-After confirmation, write:
-
-`.planning/PROJECT.md` — populated with confirmed findings
-`.planning/STATE.md` — status: "Codebase mapped. Ready to plan first phase."
-Add a warning in STATE.md if CONVENTIONS.md is still DRAFT and requires review.
-`.planning/HANDOFF.json` — updated with onboarding completion
-
-## Step 5 — Clean up and report
-
-After analysis completes, delete `.planning/map-temp/` to avoid stale data.
-
-```bash
-rm -rf .planning/map-temp/
-```
-
-Report to user:
-"✅ Codebase mapped.
-
-  Files created:
-    .planning/ARCHITECTURE.md
-    .planning/PROJECT.md
-    .mindforge/org/CONVENTIONS.md (DRAFT — please review)
-    .planning/STATE.md
-
-  Review .mindforge/org/CONVENTIONS.md and mark each section as [CONFIRMED].
-  Then run /mindforge:plan-phase 1 to begin your first phase."
-
-Write AUDIT entry:
-```json
-{
-  "event": "codebase_mapped",
-  "files_analysed": [N],
-  "entities_found": [N],
-  "api_routes_found": [N],
-  "conventions_confidence": "medium",
-  "requires_human_review": [".mindforge/org/CONVENTIONS.md"]
-}
-```

package/.agent/workflows/mindforge:marketplace.md

@@ -1,123 +0,0 @@
----
-description: Discover, evaluate, and install community-published MindForge skills from the
----
-# MindForge v2 — Marketplace Command
-# Usage: /mindforge:marketplace [search|featured|trending|install|publish]
-# Version: v2.0.0-alpha.6
-
-## Purpose
-Discover, evaluate, and install community-published MindForge skills from the
-marketplace — a curated layer on top of the npm registry.
-
-The marketplace is the shortcut: instead of learning from documentation yourself,
-install skills that the community has already created, validated, and battle-tested.
-
-## Sub-commands
-
-### search [query]
-Find skills relevant to your tech stack or domain.
-```
-/mindforge:marketplace search "prisma"
-/mindforge:marketplace search "stripe payment processing"
-/mindforge:marketplace search "HIPAA compliance"
-/mindforge:marketplace search "graphql api"
-```
-
-Output:
-```
-🔍 Marketplace search: "prisma" (6 results)
-
-  1. prisma-advanced (v1.2.3)
-     Advanced Prisma patterns: relations, migrations, performance, cursor pagination
-     847 installs this week
-
-  2. prisma-schema (v1.0.1)
-     Prisma schema design: models, relations, enums, cascade rules
-     234 installs this week
-
-  3. prisma-testing (v1.0.0)
-     Testing Prisma with Jest: database seeding, teardown, transaction rollback
-     156 installs this week
-
-Install: /mindforge:marketplace install prisma-advanced
-```
-
-### featured
-Show curated featured skills by category.
-```
-/mindforge:marketplace featured
-```
-
-Output:
-```
-🏪 MindForge Community Skills — Featured
-
-  Database:
-    db-postgres-advanced v2.1.0  — Advanced PostgreSQL patterns, indexes, partitioning
-    db-prisma-advanced   v1.2.0  — Prisma relations, migrations, query optimisation
-    db-drizzle           v1.0.0  — Drizzle ORM type-safe patterns
-
-  API:
-    api-graphql v1.4.0  — GraphQL schema, resolvers, N+1 prevention
-    api-rest    v2.0.0  — REST API design, versioning, error schemas
-
-  Compliance:
-    fintech-pci-compliance  v1.1.0 — PCI DSS Level 1 safeguards
-    healthtech-hipaa        v1.0.1 — HIPAA Security Rule for PHI
-    [more...]
-```
-
-### trending
-Show most-installed skills this month.
-```
-/mindforge:marketplace trending
-```
-
-### install [name] [--tier project|org]
-Install a marketplace skill.
-```
-/mindforge:marketplace install prisma-advanced
-/mindforge:marketplace install mindforge-skill-api-graphql --tier org
-/mindforge:marketplace install fintech-pci-compliance --tier project
-```
-
-Short names work (without `mindforge-skill-` prefix).
-Delegates to `/mindforge:install-skill` for actual installation.
-Shows quality score and session_quality_lift before installing.
-
-### publish [skill-dir]
-Publish a skill to the community marketplace.
-```
-/mindforge:marketplace publish .mindforge/skills/my-skill/
-```
-
-Requirements:
-- Quality score ≥ 80/100
-- No injection patterns
-- Has complete version history
-- Has author contact (GitHub issues URL)
-
-## Skill quality display format
-
-```
-📊 Skill: prisma-advanced v1.2.3
-   Quality score: 94/100 (Excellent)
-   ★★★★★ Session quality lift: +8.2 points (over 1,247 sessions)
-   847 installs/week | Published by: @prisma-community
-
-   Top trigger keywords: "prisma schema", "@relation", "prisma migrate",
-                          "prisma generate", "onDelete", "cursor pagination"
-
-   [Install] [Preview SKILL.md] [View on npm]
-```
-
-## AUDIT entry
-```json
-{
-  "event": "marketplace_action",
-  "action": "search|install|publish",
-  "query": "[search query if search]",
-  "skill_name": "[name if install/publish]",
-  "quality_score": 94
-}
-```

package/.agent/workflows/mindforge:memory.md

@@ -1,18 +0,0 @@
----
-description: Invoke the Semantic Clerk persona (mf-memory)
----
-# 📓 /mindforge:memory
-
-## Objective
-Adopt the **Semantic Clerk** persona to manage long-term project memory and knowledge graph maintenance.
-
----
-
-## Execution
-// turbo
-1. Execute the MindForge CLI to spawn the memory essence:
-   ```bash
-   node bin/mindforge-cli.js spawn mf-memory
-   ```
-
-2. The AI will adopt the **Memory Indexing & Pattern Recall** pattern and await your persistence tasks.

package/.agent/workflows/mindforge:metrics.md

@@ -1,25 +0,0 @@
----
-description: Display session and phase quality trends with early warning signals.
----
-# MindForge — Metrics Command
-# Usage: /mindforge:metrics [--phase N] [--window short|medium|long] [--export path]
-
-Display session and phase quality trends with early warning signals.
-
-## Data sources
-- `.mindforge/metrics/session-quality.jsonl`
-- `.mindforge/metrics/phase-metrics.jsonl`
-- `.mindforge/metrics/skill-usage.jsonl`
-- `.mindforge/metrics/compaction-quality.jsonl`
-- `.planning/AUDIT.jsonl` for correlation
-
-## Dashboard sections
-- session quality trend
-- verify pass/security/failure/compaction summary
-- skill usage distribution
-- early warnings + recommendations
-
-## AUDIT
-```json
-{ "event": "metrics_viewed", "window": "short", "early_warnings": 0 }
-```

package/.agent/workflows/mindforge:migrate.md

@@ -1,43 +0,0 @@
----
-description: Run explicit schema migrations for .planning/ files.
----
-# MindForge — Migrate Command
-# Usage: /mindforge:migrate [--from X.Y.Z] [--to X.Y.Z] [--dry-run] [--force]
-
-## Purpose
-Run explicit schema migrations for .planning/ files.
-Normally triggered automatically by /mindforge:update.
-Use this command manually when: auto-migration failed, manual version jump, recovery.
-
-## Flow
-
-### Auto-detect migration need
-Read `schema_version` from HANDOFF.json.
-Compare against current `package.json` version.
-Determine migration path.
-
-### Dry-run mode (--dry-run)
-Show: which migrations would run, what each changes.
-Show: breaking changes for the migration path.
-Make NO changes to any file.
-
-### Backup first
-Before any changes: create `.planning/migration-backup-[timestamp]/`
-Verify backup integrity (file count, non-empty).
-If backup fails: ABORT. Explain disk space issue.
-
-### Execute migrations
-Run `node bin/migrations/migrate.js`.
-Show progress for each migration.
-If any migration fails: auto-restore from backup.
-
-### Verify
-Run /mindforge:health after migration.
-If health errors: report with specific fix instructions.
-Preserve backup until user is satisfied — they must delete it manually.
-
-## Manual version override
-`/mindforge:migrate --from 0.1.0 --to 1.0.0` — forces migration between specified versions.
-Use with care: intended for recovery scenarios where HANDOFF.json schema_version is wrong.
-
-## AUDIT entry

package/.agent/workflows/mindforge:milestone.md

@@ -1,15 +0,0 @@
----
-description: Create or update a milestone definition in .planning/milestones/ and track the
----
-Create or update a milestone definition in `.planning/milestones/` and track the
- health of grouped phases. Usage: `/mindforge:milestone <name> [phase list]`
-
-## Outputs
-- milestone document with included phases
-- health summary (on track, at risk, blocked)
-- linked approvals, blockers, and verification status
-
-## Health rules
-- any blocked phase makes the milestone at risk
-- missing verification keeps milestone status yellow
-- completed verified phases count toward release readiness

package/.agent/workflows/mindforge:new-runtime.md

@@ -1,22 +0,0 @@
----
-description: Scaffold support for a new AI coding runtime.
----
-# /mindforge:new-runtime
-
-Scaffold support for a new AI coding runtime.
-
-## Usage
-
-/mindforge:new-runtime [name]
-
-## Action
-
-1.  Identify target runtime's entry file format (e.g. .myrules, instructions.md)
-2.  Scaffold the required directories in both global and local scopes
-3.  Add a new entry to the RUNTIMES configuration in `bin/installer-core.js`
-4.  Generate first-run instructions for the new runtime
-
-## Examples
-
-/mindforge:new-runtime void-editor
-/mindforge:new-runtime zed-ai