bmad-module-skill-forge 0.7.3 → 0.8.0

package/src/workflows/create-skill/data/skill-sections.md

@@ -59,6 +59,82 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 - **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge/Forge+ tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
 - **Section 7b (Scripts & Assets)** is conditional: only emitted when `scripts_inventory` or `assets_inventory` is non-empty. Omitted entirely when no scripts or assets are detected. Parsers and validators must treat this section as optional.
 
+### Component Library Section Overrides
+
+When `scope.type: "component-library"`, these section formats replace their standard counterparts. All other sections (Overview, Common Workflows, Architecture, CLI, Manual Sections, etc.) use the standard format.
+
+#### Section 4 — Component Catalog (replaces Key API Summary)
+
+```markdown
+## Component Catalog
+
+| Category | Count | Key Components |
+|----------|-------|---------------|
+| {category} | {count} | {ComponentA}, {ComponentB}, {ComponentC}, ... |
+
+**Design system variants:** {primary} (primary), {variant2}, {variant3}
+**Total components:** {unique_count} | **With {variant1}:** {count1} | **With {variant2}:** {count2}
+```
+
+- Source: `component_catalog[]` from step-03d extraction
+- Group by `category` field from registry
+- Show top 3-5 component names per category
+- Cite registry file: `[SRC:{registry_file}:L1]`
+- Budget: ~20 lines (same as standard Section 4)
+
+#### Section 5 — Key Props (replaces Key Types)
+
+```markdown
+## Key Types
+
+### {ComponentName}Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| {propName} | {type} | {default or —} | {yes/no} |
+
+{Repeat for top 5 Props interfaces}
+```
+
+- Show only the 5 most-used Props interfaces (by component count or documentation prominence)
+- Full Props details for all components go in Tier 2 reference
+- Budget: ~20 lines (same as standard Section 5)
+
+#### Tier 2 — Props Reference (replaces Full API Reference)
+
+```markdown
+## Full API Reference
+
+### {ComponentName}
+
+**Install:** `npx {cli} add {component-id}`
+**Available in:** {variant list}
+**Props:** `{ComponentName}Props`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| {prop} | {type} | {default} | {description from JSDoc or —} |
+
+**Provenance:** `[AST:{file}:L{line}]`
+```
+
+- Organize by component, not by function
+- Each component shows: install command, variant availability, full props table
+- Include JSDoc descriptions for props when available
+- Standard provenance citations apply
+
+#### context-snippet.md — Component Library Format
+
+```markdown
+[{name} v{version}]|root: skills/{name}/
+|IMPORTANT: {name} v{version} — read SKILL.md before writing {name} code. Do NOT rely on training data.
+|install: npx {cli} add <component-id>
+|catalog:{SKILL.md#component-catalog} — {N} components: {category(count), ...}
+|variants: {variant list} — {provider wrapping note if applicable}
+|key-props:{SKILL.md#key-types} — {top props interfaces with key fields}
+|gotchas: {detected gotchas}
+```
+
 ### Provenance Citation Format
 
 | Tier | Format | Example |

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -68,8 +68,8 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    When `exclude_patterns` exist, use `--no-cone` mode to pass both include and exclude patterns directly as gitignore-style rules:
 
-   1. Convert `include_patterns` to gitignore-style patterns. If a pattern contains no glob characters (`*`, `?`, `[`) and does not end with `/`, append `/**` to match directory contents recursively (e.g., `cognee` → `cognee/**`; `cognee/**` → kept as-is).
-   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same anchoring rule (e.g., `cognee/tests` → `!cognee/tests/**`; `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
+   1. Convert `include_patterns` to gitignore-style patterns. For patterns without glob characters (`*`, `?`, `[`) that do not end with `/`, apply the **file-detection heuristic**: if the last path segment contains a `.` (file extension), it is an **individual file** — prepend `/` and keep as-is (e.g., `packages/registry/registry.json` → `/packages/registry/registry.json`). If the last path segment has no extension, it is a **bare directory name** — append `/**` (e.g., `cognee` → `cognee/**`). Patterns that already contain glob characters are kept as-is (e.g., `cognee/**` → kept as-is).
+   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same file-detection heuristic: individual files (last segment has `.` extension) get `!/` prefix only (e.g., `src/internal/config.json` → `!/src/internal/config.json`); bare directory names get `/**` appended (e.g., `cognee/tests` → `!cognee/tests/**`). Patterns with globs are kept as-is with `!` prefix (e.g., `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
    3. **CRITICAL:** List all include patterns BEFORE negated exclude patterns — git processes patterns in order and a negation can only suppress a prior inclusion.
    4. Pass to sparse-checkout — include patterns first, then negated exclude patterns:
 
@@ -79,15 +79,17 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    Example transformation:
    ```
-   Brief include_patterns:        Brief exclude_patterns:
-   cognee/**                      cognee/tests/**
-                                  cognee/alembic/**
-                                  **/test_*
+   Brief include_patterns:          Brief exclude_patterns:
+   cognee/**                        cognee/tests/**
+   packages/registry/registry.json  cognee/alembic/**
+                                    **/test_*
 
    sparse-checkout args (--no-cone):
-   'cognee/**' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
+   'cognee/**' '/packages/registry/registry.json' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
    ```
 
+   Note: `registry.json` is an individual file (has `.json` extension), so it gets `/` prefix instead of `/**` suffix.
+
    **Note:** `--no-cone` mode is slower than cone mode for very large repositories but eliminates downloading excluded blobs entirely.
 
    **Always-included root files:**
@@ -112,7 +114,13 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
 
-**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing. **If any error halts the extraction step before Gate 2 is reached**, cleanup must still occur: attempt to delete `{temp_path}` before halting. Log the cleanup attempt regardless of success.
+**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`:
+
+1. **Reset working directory first:** Before deleting the clone, ensure the shell working directory is not inside the temp path. Run `cd {project-root}` using the **absolute path** captured at workflow start (not a relative path). This prevents `getcwd` errors when the temp directory is deleted while it is the shell's cwd — which happens if `cd {temp_path}` was used during CCC init or extraction operations.
+2. **Delete the clone:** `rm -rf {temp_path}`
+3. **Log:** "Ephemeral source clone cleaned up."
+
+This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing. **If any error halts the extraction step before Gate 2 is reached**, cleanup must still occur: reset cwd to `{project-root}` and attempt to delete `{temp_path}` before halting. Log the cleanup attempt regardless of success.
 
 ---
 
@@ -137,7 +145,11 @@ Store the result as `source_commit` in context. If capture fails (not a git repo
 After the source path is accessible (local path from step-01, or ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
 
 - Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
-- JavaScript/TypeScript: `package.json` (`"version"`)
+- JavaScript/TypeScript: `package.json` (`"version"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:
+  1. Package whose `name` field matches `brief.name` (e.g., the skill's target library name)
+  2. Package with a `bin` field (CLI entry point — represents the published version)
+  3. Root workspace `package.json` version (if present)
+  4. Fall back to `brief.version` if no version found. For monorepos using workspace protocols (pnpm, yarn, npm workspaces), the root `package.json` often has no `version` field — this is expected, not an error.
 - Rust: `Cargo.toml` (`[package] version`)
 - Go: `go.mod` (module version if tagged)
 

package/src/workflows/create-skill/steps-c/step-02b-ccc-discover.md

@@ -65,9 +65,11 @@ Set `{ccc_discovery: []}` in context. Auto-proceed silently. Display no message.
 
 Check `tools.ccc` from forge-tier.yaml. If `tools.ccc` is false, set `{ccc_discovery: []}` in context and auto-proceed to section 5.
 
-If `tools.ccc` is true, continue to section 2.
+If `tools.ccc` is true, check the remote source guard **before** proceeding to section 2:
 
-**Remote source guard:** If `source_root` is a remote URL (GitHub repository not yet cloned locally — ephemeral clone happens in step-03), CCC cannot operate. Set `{ccc_discovery: []}` and display: "CCC discovery skipped — remote source not yet available locally. CCC requires a local source index." Auto-proceed to the step completion / next step section.
+**Remote source guard:** If `source_root` is a remote URL (GitHub repository not yet cloned locally — ephemeral clone happens in step-03), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after ephemeral clone in step-03." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the ephemeral clone before AST extraction begins.
+
+If `source_root` is a local path, continue to section 2.
 
 ### 2. Check CCC Index State
 
@@ -77,7 +79,7 @@ Read `ccc_index` from forge-tier.yaml:
 - If `ccc_index.status` is `"stale"`: display brief note — "CCC index is stale — discovery results may miss recent changes." Continue to section 3.
 - If `ccc_index.status` is `"none"` or `"failed"`: attempt lazy indexing via `ccc_bridge.ensure_index(source_root)`. If indexing succeeds, continue to section 3. If indexing fails, set `{ccc_discovery: []}` and auto-proceed to section 5.
 
-**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `ccc init` + `ccc index {source_root}` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc init` + `ccc index` (CLI). Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
 
 ### 3. Construct Semantic Query
 
@@ -95,7 +97,7 @@ Where:
 
 Run `ccc_bridge.search(query, source_root, top_k=20)`:
 
-**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{query}" --path {source_root} --top 20` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 20 "{query}"` (CLI). Note: `ccc search` operates on the index in the current working directory — there is no flag to specify a project directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
 
 **If search succeeds:**
 

package/src/workflows/create-skill/steps-c/step-03-extract.md

@@ -2,6 +2,7 @@
 name: 'step-03-extract'
 description: 'Tier-dependent source code extraction — AST or source reading for exports, signatures, and types'
 nextStepFile: './step-03b-fetch-temporal.md'
+componentExtractionStepFile: './step-03d-component-extraction.md'
 extractionPatternsData: '../data/extraction-patterns.md'
 extractionPatternsTracingData: '../data/extraction-patterns-tracing.md'
 tierDegradationRulesData: '../data/tier-degradation-rules.md'
@@ -49,7 +50,7 @@ To extract all public exports, function signatures, type definitions, and co-imp
 - Available: brief_data, tier, source_root, file_tree from step-01; ecosystem check outcome from step-02 (proceed/halt decision — no named variable stored)
 - Focus: Source code extraction and inventory building
 - Limits: Do NOT compile, assemble, or write any output
-- Dependencies: Source code must be accessible (resolved in step-01)
+- Dependencies: Source code must be accessible (local repos resolved in step-01; remote repos cloned in section 2a)
 
 ## MANDATORY SEQUENCE
 
@@ -69,6 +70,50 @@ From the brief, apply scope and pattern filters:
 
 Build the filtered file list from the source tree resolved in step-01. Record the result: "**Filtered file count: {N} files in scope**" — this count is the input to the AST Extraction Protocol decision tree in the extraction patterns data file.
 
+### 2a. Resolve Source Access
+
+Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution** protocol for Forge/Deep tiers (ephemeral clone, sparse-checkout, cleanup), the **Source Commit Capture** protocol for all tiers, and the **Version Reconciliation** protocol for all tiers. This ensures source code is accessible regardless of which extraction path is taken below (standard, component-library, or docs-only).
+
+**Deferred CCC Discovery (Forge+ and Deep — remote sources only):**
+
+If ALL of these conditions are true:
+- `tools.ccc` is true in forge-tier.yaml
+- `{ccc_discovery}` is empty (step-02b deferred because source was remote)
+- `ephemeral_clone_active` is true (clone succeeded in source resolution above)
+- Tier is Forge+ or Deep
+
+Then run CCC indexing and discovery on the ephemeral clone:
+
+1. **Index the clone:** Run `cd {temp_path} && ccc init` then `ccc index` with an extended timeout or in background mode — `ccc init` takes no positional arguments and initializes the index for the current working directory. Indexing can take several minutes on large codebases (1000+ files). Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero. If init fails or indexing fails, set `{ccc_discovery: []}` and continue — this is not an error.
+
+2. **Construct semantic query:** Build from brief data: `"{brief.name} {brief.scope}"`. Truncate to 80 characters — keep the full skill name and trim `brief.scope` from the end. If `brief.scope` is very short (< 10 chars), append terms from `brief.description` to fill the remaining space.
+
+3. **Execute search:** Run `ccc_bridge.search(query, temp_path, top_k=20)`:
+   - **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {temp_path} && ccc search --limit 20 "{query}"` (CLI). Note: `ccc search` operates on the index in the current working directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
+4. **Store results:** If search succeeds, store as `{ccc_discovery: [{file, score, snippet}]}`. Display: "**CCC semantic discovery (post-clone): {N} relevant regions identified across {M} unique files.**"
+
+5. **On failure:** Set `{ccc_discovery: []}`. Display: "CCC post-clone discovery unavailable — proceeding with standard extraction." Do NOT halt.
+
+**CCC Discovery Integration (Forge+ and Deep with ccc only):**
+
+If `{ccc_discovery}` is in context and non-empty (populated by step-02b or deferred discovery above):
+- Sort the filtered file list by CCC relevance score: files appearing in `{ccc_discovery}` results move to the front of the extraction queue, sorted by their relevance score descending
+- Files NOT in CCC results remain in the queue after ranked files — they are not excluded, only deprioritized
+- Display: "**CCC discovery: {N} files pre-ranked by semantic relevance** — extraction will prioritize these first."
+
+If `{ccc_discovery}` is empty or not in context: proceed with existing file ordering (no change to current behavior).
+
+### 2b. Component Library Delegation
+
+**If `scope.type: "component-library"` in the brief:**
+
+"**Component library detected.** Delegating to specialized extraction strategy for registry-first, props-focused extraction."
+
+Load and execute `{componentExtractionStepFile}` completely. When that step completes, it returns control here. Resume at section 5 (Build Extraction Inventory) with the enriched extraction data and `component_catalog[]` from the component extraction step.
+
+**Otherwise:** Continue with standard extraction below.
+
 ### 3. Check for Docs-Only Mode
 
 **If `source_type: "docs-only"` in the brief data:**
@@ -81,7 +126,7 @@ Build an empty extraction inventory with zero exports. Set `extraction_mode: "do
 
 ### 4. Execute Tier-Dependent Extraction
 
-Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution** protocol for Forge/Deep tiers (ephemeral clone, sparse-checkout, cleanup) and the **Version Reconciliation** protocol for all tiers. Apply the protocols before proceeding with the tier-specific extraction strategy below.
+Source resolution, version reconciliation, and CCC discovery were completed in section 2a. Proceed with the tier-specific extraction strategy below.
 
 **Quick Tier (No AST tools):**
 
@@ -96,16 +141,7 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 
 **Forge/Forge+/Deep Tier (AST available):**
 
-**CCC Discovery Integration (Forge+ and Deep with ccc only):**
-
-If `{ccc_discovery}` is in context and non-empty (populated by step-02b):
-- Sort the filtered file list by CCC relevance score: files appearing in `{ccc_discovery}` results move to the front of the extraction queue, sorted by their relevance score descending
-- Files NOT in CCC results remain in the queue after ranked files — they are not excluded, only deprioritized
-- Display: "**CCC discovery: {N} files pre-ranked by semantic relevance** — extraction will prioritize these first."
-
-If `{ccc_discovery}` is empty or not in context: proceed with existing file ordering (no change to current behavior).
-
-⚠️ **CRITICAL:** Before executing AST extraction, load the **AST Extraction Protocol** section from `{extractionPatternsData}`. Follow the decision tree based on the file count from step-01's file tree. This determines whether to use the MCP tool, scoped YAML rules, or CLI streaming. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases.
+⚠️ **CRITICAL:** Before executing AST extraction, load the **AST Extraction Protocol** section from `{extractionPatternsData}`. Follow the decision tree based on the file count from step-01's file tree. This determines whether to use the MCP tool, scoped YAML rules, or CLI streaming. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases. Always use the explicit `run` subcommand with streaming: `ast-grep run -p '{pattern}' --json=stream`.
 
 1. Detect language from brief or file extensions
 2. Follow the AST Extraction Protocol decision tree from `{extractionPatternsData}`:

package/src/workflows/create-skill/steps-c/step-03d-component-extraction.md

@@ -0,0 +1,292 @@
+---
+name: 'step-03d-component-extraction'
+description: 'Component-library extraction strategy — registry detection, props-first extraction, variant consolidation, demo exclusion'
+returnToStep: './step-03-extract.md'
+extractionPatternsData: '../data/extraction-patterns.md'
+---
+
+# Step 3d: Component Library Extraction
+
+## STEP GOAL:
+
+When `scope.type: "component-library"`, perform specialized extraction that treats the component registry as the primary API surface and props interfaces as API contracts. This step replaces the standard AST extraction flow (step-03 sections 4-4c) and returns control to step-03 section 5 (Build Extraction Inventory).
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 ALWAYS follow the exact instructions in the step file
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a skill compilation engine performing component-library-specialized extraction
+- ✅ Zero hallucination tolerance — every extracted item must trace to source code
+- ✅ Component registry is the source of truth for the API surface
+- ✅ Props interfaces are the API contracts, not function signatures
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on extracting component catalog, props interfaces, and shared types
+- 🚫 FORBIDDEN to compile SKILL.md content — that is step-05
+- 🚫 FORBIDDEN to write any output files — extraction stays in context
+- 🚫 FORBIDDEN to include content that cannot be cited to a source location
+- ⚒️ Every extracted item MUST have a provenance citation: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
+
+## CONTEXT BOUNDARIES:
+
+- Available: brief_data (including `scope.registry_path`, `scope.ui_variants`, `scope.demo_patterns` if present), tier, source_root (may be `temp_path` from ephemeral clone for remote repos — use the working source path resolved in step-03 section 2a), filtered file list from step-03 section 2, CCC discovery results (if available from step-03 section 2a)
+- Focus: Component-specific extraction and inventory building
+- Limits: Do NOT compile, assemble, or write output
+- Dependencies: Source code accessible (resolved in step-03 section 2a — ephemeral clone for remote repos), scope filters already applied
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### Phase 1: Demo/Example Exclusion
+
+Before extraction, identify and exclude demo/example files to avoid inflating export counts.
+
+**If `scope.demo_patterns` is specified in the brief:** Use those patterns directly.
+
+**Otherwise, auto-detect:**
+
+1. Scan the filtered file list for directories matching: `demo/`, `demos/`, `stories/`, `examples/`, `__stories__/`, `storybook/`
+2. Scan for file patterns matching: `*.stories.*`, `*.story.*`, `*.example.*`, `*.demo.*`
+3. Count matches per pattern category
+
+**User confirmation required:**
+
+"**Auto-detected {N} demo/example files** in {M} directories matching these patterns:
+{list detected patterns with counts}
+
+Confirm exclusion? [Y/n] Or adjust patterns:"
+
+Wait for user response. Apply confirmed patterns to the exclude list. Record `demo_files_excluded: {count}` in context.
+
+Update the filtered file list by removing excluded demo files before proceeding.
+
+### Phase 2: Registry Detection
+
+The component registry is the primary API surface for component libraries.
+
+**If `scope.registry_path` is specified in the brief:**
+
+Read the specified file directly. Parse it as described below.
+
+**Otherwise, auto-detect:**
+
+1. Search the filtered file list for files matching these patterns (in priority order):
+   - Files named `registry.ts`, `registry.tsx`, `registry.js` in any directory
+   - Files named `components.ts`, `components.tsx` in `registry/`, `catalog/`, or `components/` directories
+   - Files named `index.ts`, `index.tsx` in `registry/` or `catalog/` directories
+
+2. For each candidate, read the file and look for:
+   - Arrays of objects with fields like `id`, `name`, `component`, `category`
+   - Type annotations containing `Component[]` or similar array types
+   - 10+ entries to qualify as a registry (reject small arrays)
+
+3. **Confidence scoring** for each candidate:
+   - +3 points: Contains `id` field per entry
+   - +2 points: Contains `name` or `component` field per entry
+   - +2 points: Contains `category` or `tags` field per entry
+   - +1 point: Located in a `registry/` or `catalog/` directory
+   - +1 point: Has 20+ entries
+   - Minimum threshold: 5 points to qualify
+
+4. **User confirmation required:**
+
+"**Registry candidate detected** at `{path}` (confidence: {score}/9, {count} entries).
+
+Sample entries:
+{show 3-5 sample entries with id, name, category}
+
+Is this the component registry? [Y/n] Or provide the correct path:"
+
+Wait for user response.
+
+**If no registry found and no `registry_path` in brief:**
+
+"**No component registry detected.** Component-library extraction works best with a registry file. Options:
+- **[P]** Provide the registry file path
+- **[S]** Skip registry — proceed with standard props-first extraction only"
+
+Wait for user response.
+
+### Phase 3: Parse Registry
+
+If a registry was confirmed, parse it into `component_catalog[]`:
+
+**Per-component entry:**
+
+- `id` — registry key (used for CLI `add` command)
+- `name` — display name (PascalCase)
+- `description` — from registry or empty
+- `category` — from registry field or directory structure
+- `available_in[]` — which design system variants include this component
+- `code_paths[]` — source file path for each variant
+- `tags[]` — from registry or empty
+- Provenance citation: `[SRC:{registry_file}:L{line}]`
+
+Display: "**Parsed component catalog: {N} components across {M} categories.**"
+
+**If no registry:** Set `component_catalog: []` and proceed to Phase 4.
+
+### Phase 4: Props-First Extraction
+
+Extract props interfaces as the primary API contracts, then link to components.
+
+**Step 1 — Extract Props interfaces:**
+
+Load `{extractionPatternsData}` and use the component-library-specific patterns.
+
+Using AST tools (Forge/Deep) or source reading (Quick):
+
+```yaml
+# React/TypeScript props interfaces
+id: react-props-interfaces
+language: typescript
+rule:
+  pattern: 'export interface $NAME { $$$ }'
+constraints:
+  NAME:
+    regex: '.*Props$'
+```
+
+For each `*Props` interface found:
+- Extract all fields with types, optionality, and default values
+- Extract JSDoc descriptions per field (if present)
+- Record: interface name, fields[], source file, line number
+- Provenance: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
+
+**Step 2 — Extract component exports:**
+
+```yaml
+# React component exports (PascalCase)
+id: react-component-exports
+language: tsx  # Use 'tsx' for .tsx files, 'typescript' for .ts files
+rule:
+  pattern: 'export function $NAME($$$PARAMS)'
+constraints:
+  NAME:
+    regex: '^[A-Z]'
+```
+
+Also run `export const $NAME` patterns for arrow function components.
+
+For each component export: record name, source file, line number. Do NOT document the function signature in detail (it's always `(props: XProps) => JSX.Element`).
+
+**Step 3 — Link Props to Components:**
+
+Use a 3-level fallback chain:
+
+1. **Naming convention (primary):** Match `FooProps` → `Foo` component by stripping the `Props` suffix
+2. **File co-location (fallback):** If naming doesn't match, check if a Props interface and a component are defined in the same file
+3. **Generic parameter (deep fallback):** Look for `ComponentProps<typeof Foo>` or similar generic patterns that reference the component
+
+For each linked pair, record the association. For unlinked Props interfaces, include them as standalone type exports.
+
+**Step 4 — Extract shared types:**
+
+Extract non-Props type exports using standard AST patterns (same as Forge tier):
+- `export type $NAME = $VALUE`
+- `export enum $NAME { $$$ }`
+- `export interface $NAME { $$$ }` (excluding `*Props` already captured)
+
+### Phase 5: Variant Consolidation
+
+**Skip this phase if `scope.ui_variants` is not specified and no variant directories detected.**
+
+When multiple design system variants exist:
+
+1. **Group components by registry `id`** (NOT by filename — registry is source of truth):
+   - For each `id` in `component_catalog[]`, collect all variant paths from `available_in[]` and `code_paths[]`
+
+2. **Select canonical props definition:**
+   - Use the primary variant (first in `scope.ui_variants` list) as canonical
+   - If primary variant's props are unavailable, use the first available variant
+
+3. **Detect props differences between variants:**
+   - For components available in 2+ variants, compare Props interfaces
+   - Record any variant-specific props as notes (e.g., "Base UI variant adds `slots` prop")
+
+4. **Deduplicate export counts:**
+   - Count unique components (by registry `id`), not total files across variants
+   - Record: `components_unique: {N}`, `components_total_with_variants: {M}`
+
+Display: "**Variant consolidation: {unique} unique components across {variant_count} variants** ({total} total including variants). Primary variant: {primary_name}."
+
+### Phase 6: Build Component Extraction Results
+
+Compile all extracted data into the format expected by step-03 section 5:
+
+**Per-export entry (for Props interfaces — primary API):**
+
+- Interface name (e.g., `NativeLiquidButtonProps`)
+- Full interface with all fields and types
+- Parameters: each field as name, type, required/optional, default
+- Linked component name (e.g., `NativeLiquidButton`)
+- Source file and line number
+- Provenance citation
+- Confidence tier (T1 or T1-low)
+
+**Per-export entry (for component functions):**
+
+- Component name
+- Linked Props interface (if found)
+- Source file and line number
+- Provenance citation
+- Confidence tier
+
+**Per-export entry (for shared types):**
+
+- Same as standard extraction format
+
+**Component library aggregate counts:**
+
+- `components_registered`: count from registry (or 0)
+- `components_documented`: count of components with linked Props
+- `props_interfaces_extracted`: count of `*Props` interfaces
+- `components_unique`: deduplicated count (after variant consolidation)
+- `demo_files_excluded`: count from Phase 1
+- `design_variants`: map of variant name → component count (if variants exist)
+
+**Store `component_catalog[]` in context** — this is consumed by step-05 for the Component Catalog section.
+
+Display: "**Component extraction complete.** Returning to main extraction flow."
+
+## RETURN PROTOCOL
+
+After Phase 6 completes, return control to step-03 section 5 (Build Extraction Inventory). The extraction results from this step are merged into the standard extraction inventory format. Step-03 continues with its normal Gate 2 summary and menu.
+
+Do NOT load `{returnToStep}` — the calling step (step-03) will continue from where it delegated.
+
+---
+
+## SYSTEM SUCCESS/FAILURE METRICS
+
+### SUCCESS:
+
+- Demo/example files detected and excluded with user confirmation
+- Registry detected (or user provided path) and parsed into component_catalog
+- Props interfaces extracted as primary API contracts
+- Components linked to Props via 3-level fallback chain
+- Variant consolidation produced deduplicated counts (if applicable)
+- All extracted items have provenance citations
+- Results compatible with step-03 section 5 inventory format
+- component_catalog stored in context for step-05
+
+### FAILURE:
+
+- Excluding demo files without user confirmation
+- Accepting a registry candidate without user confirmation
+- Not extracting Props interfaces as primary API surface
+- Documenting component function signatures instead of Props
+- Including hallucinated component data not in source
+- Variant deduplication based on filenames instead of registry IDs
+- Not returning control to step-03 after completion
+
+**Master Rule:** Zero hallucination — every extraction must trace to source code. The component registry is the source of truth for the API surface.

package/src/workflows/create-skill/steps-c/step-05-compile.md

@@ -117,6 +117,15 @@ Following the structure from the skill-sections data file:
   3. `{project-root}/_bmad/skf/VERSION` → read plain text file (single line containing version string, written by the SKF installer)
   4. `"unknown"` (final fallback — add a warning to the evidence report)
   Never hardcode the version.
+- Resolve `{ast_grep_version}` using this resolution chain (try each in order, use the first that succeeds):
+  1. `ast-grep --version` → parse version string from output (e.g., `ast-grep 0.41.1` → `"0.41.1"`)
+  2. `mcp__ast-grep__find_code` tool metadata (if version is exposed by the MCP server)
+  3. `"unknown"` (final fallback — add a warning to the evidence report)
+- Resolve `{qmd_version}` using this resolution chain (try each in order, use the first that succeeds):
+  1. `mcp__plugin_qmd-plugin_qmd__status` → parse version from status output
+  2. `pip show qmd-plugin` → read `Version:` field from pip metadata
+  3. `"unknown"` (final fallback — add a warning to the evidence report)
+  Note: `qmd --version` and `qmd -V` return usage text instead of a version string — do not use them for version detection.
 - Store `commit_short` = first 8 characters of `source_commit` (or `"unknown"` if unavailable) for use in step-08 report.
 - If `scripts_inventory` is non-empty, populate `scripts[]` array and set `stats.scripts_count`. If `assets_inventory` is non-empty, populate `assets[]` array and set `stats.assets_count`. Omit these fields entirely when inventories are empty.