mindforge-cc 2.0.0-alpha.8 → 2.0.0

package/.claude/commands/mindforge/marketplace.md

@@ -0,0 +1,120 @@
+# 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/.claude/commands/mindforge/new-runtime.md

@@ -0,0 +1,19 @@
+# /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

package/.mindforge/distribution/marketplace.md

@@ -0,0 +1,53 @@
+# MindForge v2 — Community Skills Marketplace
+
+## Purpose
+The MindForge Marketplace is a distribution network for reusable AI skills.
+It leverages the `mindforge-skill-` npm package prefix for discovery.
+
+## Naming conventions
+Skills published to the marketplace MUST follow this naming convention:
+`mindforge-skill-[technology-or-pattern]`
+
+Example:
+- `mindforge-skill-prisma-schema`
+- `mindforge-skill-zod-api-contracts`
+- `mindforge-skill-stripe-webhooks`
+
+## Marketplace categories
+Skills are grouped into these canonical categories:
+1. **Engines & Runtimes** (Node.js, Python, Go, Rust)
+2. **Databases & ORMs** (Prisma, Drizzle, Kysely, Sequelize)
+3. **API & Integration** (Stripe, Twilio, OpenAI, Anthropic)
+4. **UI & Frontend** (React, Next.js, Tailwind, Radix)
+5. **Patterns & Security** (Auth, RBAC, Validation, Error Handling)
+
+## Quality requirements
+To be listed in the marketplace, a skill MUST:
+- Achieve a quality score of ≥ 80/100
+- Pass all level 1 + level 2 validation checks
+- Include at least 5 complete, working code examples
+- Be free of any placeholder text
+- Be licensed under MIT or Apache-2.0
+
+## Publishing process
+1. Run `/mindforge:learn` to generate/update the skill.
+2. Achieve score ≥ 80 using `skill-scorer.js`.
+3. Fill in the optional `author`, `license`, and `category` fields in frontmatter.
+4. Run `/mindforge:marketplace publish [skill-name]`.
+   - This prepares the `package.json`.
+   - Runs final verification.
+   - Prompts for `npm publish`.
+
+## Interaction interface
+```
+/mindforge:marketplace search [query]       # Search the marketplace
+/mindforge:marketplace featured             # Show featured skills
+/mindforge:marketplace trending             # Show trending skills
+/mindforge:marketplace info [name]           # Show skill details and quality score
+/mindforge:marketplace install [name]        # Install a community skill
+/mindforge:marketplace publish [name]        # Publish your skill
+```
+
+## Marketplace Registry
+By default, the marketplace uses the global npm registry with the `mindforge-skill-` prefix.
+Private registries can be configured via `MARKETPLACE_REGISTRY` in MINDFORGE.md.

package/.mindforge/org/skills/MANIFEST.md

@@ -22,6 +22,7 @@
 
 | Name | Version | Status | Min MindForge | Path |
 |---|---|---|---|---|
+| security-owasp | 1.2.0 | stable | 0.1.0 | .mindforge/org/skills/security-owasp/SKILL.md |
 | (none yet — see docs/skills-authoring-guide.md to add org skills) | | | | |
 
 ## Project Skills — Tier 3 (add project-specific skills here)

package/.mindforge/production/production-checklist.md

@@ -1,6 +1,6 @@
-# MindForge v1.0.0 — Production Readiness Checklist
+# MindForge v2.0.0 — Production Readiness Checklist
 
-## Policy: ALL 55 items must be ✅ before tagging v1.0.0
+## Policy: ALL 65 items must be ✅ before tagging v2.0.0
 
 This is not a "should" list — it is a hard gate.
 No item can be marked ✅ without:
@@ -13,145 +13,56 @@ Document completed checks in `.planning/RELEASE-CHECKLIST.md`.
 ---
 
 ## SECTION A — Installation & Upgrade (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| A01 | `npx mindforge-cc@latest` launches interactive wizard on macOS | Run on macOS terminal with TTY | | | |
-| A02 | `npx mindforge-cc@latest` launches wizard on Linux | Run on Ubuntu 22.04 LTS terminal | | | |
-| A03 | `npx mindforge-cc --claude --local` installs correctly | Verify files, run /mindforge:health | | | |
-| A04 | `npx mindforge-cc --all --global` installs both runtimes | Check ~/.claude and ~/.gemini/antigravity | | | |
-| A05 | `--update` updates and preserves install scope | Install locally, run --update, verify scope preserved | | | |
-| A06 | `--uninstall` removes only MindForge files (not .planning/) | Run uninstall, verify .planning/ intact | | | |
-| A07 | `--version` and `--help` exit 0 with correct output | Run both flags, check exit code | | | |
-| A08 | Install over existing CLAUDE.md backs it up | Create custom CLAUDE.md, install, verify backup | | | |
-| A09 | Install over existing .planning/ preserves it | Create test .planning/, install, verify preserved | | | |
-| A10 | Node.js < 18 prints helpful error and exits 1 | Run with node 16, verify error message | | | |
+... (existing items A01-A10)
 
 ## SECTION B — Command Coverage (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| B01 | `/mindforge:help` shows all 36 commands | Count commands in output, verify ≥ 36 | | | |
-| B02 | `/mindforge:init-project` creates all 5 required .planning/ files | Run in empty dir, check file list | | | |
-| B03 | `/mindforge:health` reports ✅ on a fresh install | Fresh install, run health, zero errors | | | |
-| B04 | `/mindforge:health --repair` fixes CLAUDE.md drift | Corrupt .agent/CLAUDE.md, run repair, verify fix | | | |
-| B05 | `/mindforge:skills list` shows all 10 core skills | Count in output, verify all 10 names | | | |
-| B06 | `/mindforge:skills validate` shows all valid | Run, verify zero errors | | | |
-| B07 | `/mindforge:security-scan --secrets` detects fake key | Add test key pattern, scan, verify detection | | | |
-| B08 | `/mindforge:audit --summary` shows metrics dashboard | Run in project with some audit entries | | | |
-| B09 | `/mindforge:update` checks version without changing files | Run without --apply, verify no file changes | | | |
-| B10 | `/mindforge:migrate --dry-run` shows plan without changes | Run dry-run on v0.6.0 schema, verify dry-run | | | |
+... (existing items B01-B10)
 
 ## SECTION C — Governance Gates (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| C01 | Gate 3 (secret detection) blocks commit with fake API key | Stage file with `FAKE_ghp_abcdef1234567890abcd`, run gate | | | |
-| C02 | Gate 2 (tests passing) blocks on test failure | Break a test, run gate, verify block | | | |
-| C03 | Gate 1 (CRITICAL findings) blocks PR creation | Add CRITICAL finding to SECURITY-REVIEW, attempt ship | | | |
-| C04 | AUDIT.jsonl gains entry for every task start and complete | Execute one quick task, count new AUDIT lines | | | |
-| C05 | Tier 3 change classifier detects jwt.sign in non-auth path | Create file with jwt.sign, run classifier | | | |
-| C06 | Tier 3 CI block produces clear error message | Simulate CI run with Tier 3 pending, check output | | | |
-| C07 | MINDFORGE.md non-overridable keys are silently enforced | Set SECRET_DETECTION=false, verify it has no effect | | | |
-| C08 | Approval workflow creates APPROVAL-[uuid].json | Request a Tier 2 approval, verify file created | | | |
-| C09 | Plugin injection guard blocks malicious SKILL.md | Create SKILL.md with IGNORE ALL PREVIOUS, run guard | | | |
-| C10 | All 5 compliance gates produce GATE-RESULTS-N.md | Complete a full phase, verify GATE-RESULTS file | | | |
+... (existing items C01-C10)
 
 ## SECTION D — Documentation (10 points)
-
-| # | Check | Verification step | ✅/❌ | Verified by | Date |
-|---|---|---|---|---|---|
-| D01 | README.md quick start works end-to-end in < 5 minutes | New developer follows README, measures time | | | |
-| D02 | `docs/reference/commands.md` documents all 36 commands | Count documented commands, verify ≥ 36 | | | |
-| D03 | `docs/enterprise-setup.md` covers all integration steps | Walk through integration setup docs | | | |
-| D04 | `docs/governance-guide.md` explains all 3 tiers clearly | Review with someone unfamiliar with governance | | | |
-| D05 | `docs/security/threat-model.md` covers all 7 threat actors | Count actors, verify controls for each | | | |
-| D06 | `docs/security/SECURITY.md` has disclosure process | Verify email + 90-day policy present | | | |
-| D07 | `docs/contributing/CONTRIBUTING.md` has PR guidelines | Check for: fork, branch, test, PR process | | | |
-| D08 | `docs/contributing/skill-authoring.md` is actionable | Follow guide to create a test skill | | | |
-| D09 | All 20 ADRs listed in decision-records-index.md | Count ADRs, cross-check index | | | |
-| D10 | CHANGELOG.md v1.0.0 entry is complete with date | Verify entry has date, all components listed | | | |
+... (existing items D01-D10)
 
 ## SECTION E — Test Coverage (10 points)
+... (existing items E01-E10)
+
+## SECTION F — v2.0.0 Features (10 points)
 
 | # | Check | Verification step | ✅/❌ | Verified by | Date |
 |---|---|---|---|---|---|
-| E01 | All 15 test suites pass with 0 failures (Run 1) | Execute full test battery | | | |
-| E02 | All 15 test suites pass with 0 failures (Run 2) | Execute full test battery again | | | |
-| E03 | All 15 test suites pass with 0 failures (Run 3) | Execute full test battery third time | | | |
-| E04 | No test uses `process.exit(0)` inside a test function | `grep -rn 'process.exit(0)' tests/` | | | |
-| E05 | E2E tests simulate complete brownfield onboarding | Run tests/e2e.test.js, verify brownfield path | | | |
-| E06 | Migration tests cover v0.1.0 → v1.0.0 full chain | Run tests/migration.test.js full suite | | | |
-| E07 | No test has `// TODO` or `// skip` in test body | `grep -rn 'TODO\|skip' tests/` | | | |
-| E08 | Security penetration test pass (all 7 threat actors) | Run through threat-model.md controls manually | | | |
-| E09 | CI pipeline runs all tests on PR against main | Create test PR, verify CI passes | | | |
-| E10 | Version in package.json matches git tag matches npm dist | `node -e "console.log(require('./package.json').version)"` | | | |
-
-## SECTION F — Release Artifacts (5 points)
+| F01 | `/mindforge:new-runtime` scaffolds commands in both .claude and .agent | Run command, check both dirs | | | |
+| F02 | `--gemini` installs GEMINI.md with correct context substitution | Run install --gemini, verify filename and content | | | |
+| F03 | `--cursor` and `--copilot` entry files contain usage preambles | Run install, verify preambles in rule files | | | |
+| F04 | Migration 1.0.0 → 2.0.0 backfills `runtime` in AUDIT.jsonl | Run migration on v1 audit, verify backfill | | | |
+| F05 | Migration 1.0.0 → 2.0.0 backfills `model_group` in tokens | Run migration, verify token-usage.jsonl | | | |
+| F06 | Migration creates automatic backup before modification | Verify `.planning/.backups/` exists with files | | | |
+| F07 | Installer correctly handles the `--runtime <name>` explicit flag | Run with --runtime opencode, verify install | | | |
+| F08 | Install `--all` targets 6 distinct runtimes correctly | Run --all, verify 6 locations | | | |
+| F09 | ADRs 039-041 are present and indexed | Verify ADR files and index entry | | | |
+| F10 | Self-building skills (Day 13) features pass regression tests | Run self-building-skills.test.js | | | |
+
+## SECTION G — final packaging (5 points)
 
 | # | Check | Verification step | ✅/❌ | Verified by | Date |
 |---|---|---|---|---|---|
-| F01 | package.json version === target release version | `node -e "console.log(require('./package.json').version)"` | | | |
-| F02 | SDK package.json version matches root version | `node -e "console.log(require('./sdk/package.json').version)"` | | | |
-| F03 | Git tag v1.0.0 exists and points to correct commit | `git show v1.0.0 --no-patch` | | | |
-| F04 | CHANGELOG.md has v1.0.0 entry with today’s date | `grep -n \"1.0.0\" CHANGELOG.md` | | | |
-| F05 | `npm publish --dry-run` shows no unexpected files | Run dry-run, review output | | | |
+| G01 | package.json version === 2.0.0 | `node -e "console.log(require('./package.json').version)"` | | | |
+| G02 | SDK package.json version === 2.0.0 | `node -e "console.log(require('./sdk/package.json').version)"` | | | |
+| G03 | Git tag v2.0.0 exists and points to HEAD | `git show v2.0.0 --no-patch` | | | |
+| G04 | CHANGELOG.md has v2.0.0 entry with release highlights | `grep -n "2.0.0" CHANGELOG.md` | | | |
+| G05 | `npm publish --dry-run` is clean | Run dry-run, verify file list | | | |
 
 ---
 
 ## Checkbox summary (for quick audits)
-Use this list when you want a fast “all items present” view.
-
-- [ ] A01
-- [ ] A02
-- [ ] A03
-- [ ] A04
-- [ ] A05
-- [ ] A06
-- [ ] A07
-- [ ] A08
-- [ ] A09
-- [ ] A10
-- [ ] B01
-- [ ] B02
-- [ ] B03
-- [ ] B04
-- [ ] B05
-- [ ] B06
-- [ ] B07
-- [ ] B08
-- [ ] B09
-- [ ] B10
-- [ ] C01
-- [ ] C02
-- [ ] C03
-- [ ] C04
-- [ ] C05
-- [ ] C06
-- [ ] C07
-- [ ] C08
-- [ ] C09
-- [ ] C10
-- [ ] D01
-- [ ] D02
-- [ ] D03
-- [ ] D04
-- [ ] D05
-- [ ] D06
-- [ ] D07
-- [ ] D08
-- [ ] D09
-- [ ] D10
-- [ ] E01
-- [ ] E02
-- [ ] E03
-- [ ] E04
-- [ ] E05
-- [ ] E06
-- [ ] E07
-- [ ] E08
-- [ ] E09
-- [ ] E10
+- [ ] A01-A10
+- [ ] B01-B10
+- [ ] C01-C10
+- [ ] D01-D10
+- [ ] E01-E10
+- [ ] F01-F10
+- [ ] G01-G05
+ [ ] E10
 - [ ] F01
 - [ ] F02
 - [ ] F03

package/.mindforge/skills-builder/auto-capture-protocol.md

@@ -0,0 +1,88 @@
+# MindForge v2 — Auto-Capture Protocol
+
+## Purpose
+When `AUTO_CAPTURE_SKILLS=true` in MINDFORGE.md, MindForge automatically
+analyses each completed phase for reusable patterns worth capturing as skills.
+
+## When auto-capture runs
+After `/mindforge:verify-phase [N]` completes (all gates passed):
+The auto-capture hook analyses the phase's output for patterns.
+
+## What auto-capture analyses
+
+### Source 1: SUMMARY files
+All SUMMARY-[N]-[M].md files in `.planning/phases/[N]/`.
+Looks for: repeated approaches across 3+ tasks, common code patterns,
+repeated library usage, consistent error handling approaches.
+
+### Source 2: HANDOFF.json implicit_knowledge
+The Level 2/3 compaction extracts implicit knowledge.
+Any item with confidence > 0.7 in the implicit_knowledge array is a
+candidate for skill capture.
+
+### Source 3: ADR files created this phase
+New ADR files represent significant decisions.
+ADRs about technology choices → potential technology skill.
+ADRs about patterns → potential code-pattern skill.
+
+### Source 4: Debug reports
+DEBUG-*.md files contain root cause + fix.
+Root causes that are technology-specific → bug_pattern skill contribution.
+
+## Pattern detection algorithm
+
+For each source file, run:
+```
+Ask EXECUTOR_MODEL:
+"Read these [N] files from a completed software development phase.
+Identify patterns that appeared 2+ times (strong signal) or once but
+are highly important (architectural decisions, security patterns).
+
+Focus on:
+1. Code patterns that appear in multiple files
+2. Library-specific patterns (how a specific API/library was used)
+3. Configuration patterns (how something was set up)
+4. Error handling patterns (what edge cases were handled)
+
+For each pattern found, rate:
+- Frequency: how many files/tasks used it?
+- Generality: would this apply to future phases? (high/medium/low)
+- Difficulty: is this hard to get right without knowing it? (high/medium/low)
+
+Return: JSON array of { pattern_name, frequency, generality, difficulty, evidence_files }
+Capture candidates: (frequency >= 2 OR difficulty == 'high') AND generality != 'low'
+```
+
+## Presentation to user
+
+After analysis, if patterns are found:
+```
+🎯 Auto-capture: 2 reusable patterns found in Phase [N]
+
+  1. Prisma relation cascade patterns (★★★ high generality)
+     Appeared in: Plan 02, Plan 04, Plan 07
+     "Cascade delete must be explicitly configured..."
+
+  2. Zod schema composition pattern (★★ medium generality)
+     Appeared in: Plan 01, Plan 03
+     "Using z.discriminatedUnion() for API response types..."
+
+Save as skills? [y=both] [1=first only] [2=second only] [n=skip]
+```
+
+If user selects yes (or a subset):
+- Run full learn protocol (Steps 2-7) for each selected pattern
+- Sources: the identified SUMMARY files as documentation
+- Quality score minimum: 60
+
+If user selects skip:
+- Discard pattern drafts
+- Note in AUDIT: "auto_capture_skipped, phase: N"
+- Do NOT add to knowledge-base.jsonl (they must explicitly remember)
+
+## Minimum thresholds (configurable in MINDFORGE.md)
+
+```
+AUTO_CAPTURE_MIN_PATTERN_COUNT=2    # minimum times a pattern appears
+AUTO_CAPTURE_MIN_CONFIDENCE=0.75    # HANDOFF.json implicit_knowledge confidence
+```

package/.mindforge/skills-builder/learn-protocol.md

@@ -0,0 +1,161 @@
+# MindForge v2 — Learn Protocol
+
+## Purpose
+Convert any knowledge source (URL, local file/dir, or current session) into a
+reusable, validated, committed MindForge SKILL.md file.
+
+## Activation sources
+
+### Source type: URL
+```
+/mindforge:learn https://docs.prisma.io/concepts/components/prisma-schema
+```
+Use RESEARCH_MODEL (default: gemini-2.5-pro with 1M context) to ingest and
+analyse the documentation. For large documentation sets, Gemini 2.5 Pro can
+read the entire page including all examples at once.
+
+### Source type: local file or directory
+```
+/mindforge:learn ./docs/api-conventions.md
+/mindforge:learn ./docs/internal/
+```
+Read file(s) directly (no model call needed for reading). Use EXECUTOR_MODEL
+to analyse content and extract patterns.
+
+### Source type: session
+```
+/mindforge:learn --session
+```
+Analyse the current session's SUMMARY files, ADR files, debug reports, and
+HANDOFF.json implicit_knowledge to find patterns worth capturing.
+
+### Source type: npm package docs
+```
+/mindforge:learn npm:zod
+/mindforge:learn npm:prisma
+```
+Fetch from npmjs.com/package/[name] and read the README + linked docs.
+
+## Step-by-step learn protocol
+
+### Step 1: Read and understand the source
+For URLs: use `source-loader.js` to fetch content (with SSRF protection).
+For local: use `source-loader.js` to read file(s) with walkDir().
+For session: read all SUMMARY-*.md and HANDOFF.json implicit_knowledge.
+For npm: fetch README from npmjs.com API.
+
+Maximum context: 900K chars for Gemini (1M context); 50K chars for other models.
+
+### Step 2: Identify the top 10 reusable patterns or rules
+Ask the analysis model:
+```
+You are an expert at reading technical documentation and extracting reusable
+engineering rules and patterns.
+
+Read this documentation carefully:
+[source content]
+
+Identify exactly 10 reusable patterns, rules, or best practices that would
+be most valuable to inject into an AI agent before it works with this technology.
+
+For each pattern:
+- Give it a short title (≤ 60 chars)
+- Write a concise rule statement (≤ 150 chars, actionable)
+- Include a code example showing correct usage (TypeScript/JavaScript preferred)
+- Identify if there is a common anti-pattern to warn against
+- Rate importance: CRITICAL | HIGH | MEDIUM | LOW
+
+Format as JSON array: [{ title, rule, example, anti_pattern, importance }]
+```
+
+### Step 3: Identify 15-25 trigger keywords
+Ask the analysis model:
+```
+Based on the patterns above, identify 15-25 keywords that, if found in a
+task description or code file path, should trigger this skill to load.
+
+Rules for good trigger keywords:
+- 2-4 words each (single-word triggers are too broad)
+- Specific to this technology (not generic like "database" or "model")
+- Cover: package names, file extensions, common function names, config file names
+- Include both noun and verb forms where applicable
+
+Return as JSON array of strings: ["keyword1", "keyword2", ...]
+```
+
+### Step 4: Write the SKILL.md following the authoring template
+Use the standard MindForge SKILL.md format from `docs/skills-authoring-guide.md`.
+Populate all sections:
+- Frontmatter (name, version, status, triggers, description)
+- Purpose (why this skill exists)
+- Key patterns (from Step 2 — the 10 patterns)
+- Anti-patterns to avoid
+- Code examples (at least 3 complete, working examples)
+- Self-check checklist (5-10 items)
+- Version history
+
+### Step 5: Run Level 1 + Level 2 validation
+Level 1 (schema): frontmatter complete, triggers present, mandatory sections exist.
+Level 2 (content): no placeholder text, code examples parse, triggers are specific.
+
+Use `skill-scorer.js` to compute the quality score (target: ≥ 60 for register,
+≥ 80 for community publish).
+
+If score < 60: report the specific gaps and ask user whether to fix or discard.
+
+### Step 6: Present to user for review and approval
+
+Display:
+```
+📚 Skill Generated: [skill-name]
+─────────────────────────────────────────────────────
+Source:        [source type and location]
+Quality score: [score]/100 ([breakdown])
+Patterns:      [N] extracted
+Triggers:      [K] keywords
+Tier:          [Core/Org/Project]
+
+Preview (first 3 patterns):
+  1. [title]: [rule]
+  2. [title]: [rule]
+  3. [title]: [rule]
+
+Skill file: .mindforge/skills/[name]/SKILL.md
+
+[ y ] Register and commit
+[ n ] Discard
+[ e ] Edit before registering
+[ p ] Publish to community marketplace (requires quality score ≥ 80)
+```
+
+### Step 7: If approved — register and commit
+```bash
+# Register in MANIFEST.md (tier determined by target: project=T3, org=T2, core=T1)
+# Default for learned skills: Project tier (T3) unless explicitly set
+node bin/skills-builder/skill-registrar.js --tier project --name [skill-name]
+
+# Write AUDIT entry
+{
+  "event": "skill_learned",
+  "source_type": "url|local|session|npm",
+  "source": "[url or path]",
+  "skill_name": "[name]",
+  "quality_score": [score],
+  "pattern_count": [N],
+  "trigger_count": [K]
+}
+
+# Commit
+git add .mindforge/skills/[name]/SKILL.md .mindforge/org/skills/MANIFEST.md
+git commit -m "feat(skills): learn [skill-name] from [source type]"
+```
+
+## Session-based learning (`--session` flag)
+Analyse these sources in order:
+1. All SUMMARY-*.md files in .planning/phases/[current phase]/
+2. HANDOFF.json implicit_knowledge array (Level 2+ compaction entries)
+3. All ADR-*.md files created in the current phase
+4. RETROSPECTIVE-*.md if it exists in the current phase
+
+Ask: "What patterns emerged that would have been useful to know before this phase?"
+Generate up to 3 skills from this analysis (not more — quality over quantity).