bmad-module-skill-forge 0.5.0 → 0.7.0

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

@@ -46,7 +46,7 @@ To extract all public exports, function signatures, type definitions, and co-imp
 
 ## CONTEXT BOUNDARIES:
 
-- Available: brief_data, tier, source_location, file_tree from step-01; ecosystem_status from step-02
+- Available: brief_data, tier, source_location, 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)
@@ -75,7 +75,7 @@ Build the filtered file list from the source tree resolved in step-01. Record th
 
 "**Docs-only mode:** No source code to extract. Documentation content will be fetched from `doc_urls` in step-03c."
 
-Build an empty extraction inventory with zero exports. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 5) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
+Build an empty extraction inventory with zero exports. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 6) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
 
 **If `source_type: "source"` (default):** Continue with extraction below.
 
@@ -92,7 +92,16 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 5. Infer types from JSDoc, docstrings, type annotations
 6. Confidence: All results T1-low — `[SRC:{file}:L{line}]`
 
-**Forge/Deep Tier (AST available):**
+**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.
 
@@ -117,24 +126,21 @@ Degrade to Quick tier extraction. Note the degradation reason in context for the
 - If a file cannot be read: log warning, skip file, continue with remaining files
 - If AST parsing fails on a file: fall back to source reading for that file, continue
 
-**Re-export tracing (Forge/Deep only):**
-
-After the initial AST scan, check for public exports from the entry point (`__init__.py`, `index.ts`, `lib.rs`) that were NOT found by AST extraction. These are likely module-level re-exports. Follow the **Re-Export Tracing** protocol in `{extractionPatternsTracingData}` to resolve them to their actual definition files. This ensures module re-export patterns (common in Python libraries with clean public APIs) do not create gaps in the extraction inventory.
+**Re-export tracing (Forge/Deep only):** After the initial AST scan, check for unresolved public exports from entry points (`__init__.py`, `index.ts`, `lib.rs`). Follow the **Re-Export Tracing** protocol in `{extractionPatternsTracingData}` to resolve them to their definition files.
 
 ### 4b. Validate Exports Against Package Entry Point
 
 After extraction, validate the collected exports against the package's actual public API surface:
 
-- **Python:** Read `{source_root}/__init__.py` — extract all import statements to build the actual public export list. Compare against AST-extracted exports:
-  - In AST results but not in `__init__.py` → mark as internal (exclude from `metadata.json` exports, keep in provenance-map with a note)
-  - In `__init__.py` but not in AST results → flag as extraction gap (add to inventory, trace via re-export protocol)
-- **TypeScript/JavaScript:** Read `index.ts`/`index.js` — extract named exports. Same comparison logic.
-- **Rust:** Read `lib.rs` — extract `pub use` items. Same comparison logic.
-- **Go:** Scan package-level files for exported (capitalized) identifiers.
+- **Python:** Read `{source_root}/__init__.py` — extract imports to build the public export list. Compare against AST results:
+  - In AST but not entry point → mark as internal (exclude from `metadata.json` exports)
+  - In entry point but not AST → flag as extraction gap (trace via re-export protocol)
+- **TypeScript/JS:** Read `index.ts`/`index.js` — same comparison logic.
+- **Rust:** Read `lib.rs` — extract `pub use` items. Same logic. **Go:** Scan for exported (capitalized) identifiers.
 
-Use the entry point as the authoritative source for `metadata.json`'s `exports[]` array. This prevents internal symbols from inflating the exports list and ensures all public API items are captured.
+Use the entry point as the authoritative source for `metadata.json`'s `exports[]` array.
 
-**If entry point is missing or unreadable:** Skip validation with a warning. Use the AST-extracted list as-is.
+**If entry point is missing or unreadable:** Skip validation with a warning.
 
 ### 4c. Detect and Inventory Scripts/Assets
 
@@ -143,10 +149,8 @@ Use the entry point as the authoritative source for `metadata.json`'s `exports[]
 After export extraction, scan the source for scripts and assets using the detection patterns in `{extractionPatternsTracingData}`:
 
 1. Scan source tree for directories/files matching detection heuristics (scripts/, bin/, tools/, cli/ for scripts; assets/, templates/, schemas/, configs/, examples/ for assets)
-2. For each candidate: verify file exists, check size (flag if >500 lines for user confirmation), exclude binary files
-3. Compute SHA-256 content hash for each included file
-4. Extract purpose from file header comments, shebang, README references, or schema `title`/`description` fields. If no purpose found, use filename.
-5. Record: file_path, purpose, source_path, language (for scripts), type (for assets), content_hash, confidence (T1-low)
+2. For each candidate: verify existence, check size (flag >500 lines), exclude binaries, compute SHA-256 hash
+3. Extract purpose from header comments, shebang, README references, or schema fields. Record: file_path, purpose, source_path, language/type, content_hash, confidence (T1-low)
 
 Add results to `scripts_inventory[]` and `assets_inventory[]` alongside the existing export inventory.
 
@@ -205,8 +209,9 @@ Display: "**Extraction Summary — Select an Option:** [C] Continue to compilati
 
 #### EXECUTION RULES:
 
-- ALWAYS halt and wait for user input after presenting the extraction summary
-- This is Gate 2 — user must confirm before compilation proceeds
+- IF docs-only mode (`extraction_mode: "docs-only"`): Auto-proceed immediately to `{nextStepFile}` — no user interaction required
+- OTHERWISE: ALWAYS halt and wait for user input after presenting the extraction summary
+- This is Gate 2 — user must confirm before compilation proceeds (except docs-only mode)
 - User may ask questions about the extraction results before continuing
 
 #### Menu Handling Logic:

package/src/workflows/create-skill/steps-c/step-03b-fetch-temporal.md

@@ -27,7 +27,7 @@ To fetch temporal context (issues, PRs, changelogs, release notes) from the sour
 
 ### Step-Specific Rules:
 
-- 🎯 Deep tier only — Quick and Forge tiers skip this step entirely and silently
+- 🎯 Deep tier only — Quick, Forge, and Forge+ tiers skip this step entirely and silently
 - 🎯 GitHub repositories only — other source types degrade gracefully
 - 🚫 FORBIDDEN to halt the workflow if fetching or indexing fails
 - 🚫 FORBIDDEN to modify extraction data from step-03 — this step only creates QMD collections
@@ -43,7 +43,7 @@ To fetch temporal context (issues, PRs, changelogs, release notes) from the sour
 ## CONTEXT BOUNDARIES:
 
 - Available: brief_data, tier, source_location from step-01; extraction_inventory from step-03
-- **Used from extraction_inventory:** `top_exports[]` — the list of top-level public API function names (typically 10-20). Used for targeted GitHub searches (section 3b).
+- **Used from extraction_inventory:** `top_exports[]` — the list of top-level public API function names (typically 10-20). Used for targeted GitHub searches (section 3b). If `extraction_mode: "docs-only"` or `top_exports` is absent/empty, skip targeted searches silently.
 - Focus: Creating a QMD temporal collection for the source repository
 - Limits: Do NOT modify extraction data, begin enrichment, or compile content
 - Dependencies: Extraction must be complete from step-03
@@ -56,7 +56,7 @@ To fetch temporal context (issues, PRs, changelogs, release notes) from the sour
 
 Evaluate the following conditions sequentially. **If ANY condition fails, skip silently to section 5 (auto-proceed) with no output:**
 
-1. **Tier is Deep:** If tier is Quick or Forge, skip silently.
+1. **Tier is Deep:** If tier is Quick, Forge, or Forge+, skip silently.
 2. **Source is GitHub:** Verify `source_repo` is a GitHub URL (`https://github.com/...`) or `owner/repo` format. If the source is a local path, a non-GitHub URL, or any other format, skip silently.
 3. **`gh` CLI is available:** Run `gh auth status` to verify the CLI is installed and authenticated. If it fails, skip silently.
 
@@ -200,7 +200,7 @@ After temporal context is fetched and indexed (or skipped for any reason), immed
 #### EXECUTION RULES:
 
 - This is an auto-proceed step with no user choices
-- Quick/Forge tiers skip directly to next step with no output
+- Quick/Forge/Forge+ tiers skip directly to next step with no output
 - Non-GitHub sources skip directly to next step with no output
 - Cached collections (< 7 days old) skip with brief cache-hit message
 - Deep tier with fresh fetch displays brief confirmation then auto-proceeds
@@ -208,7 +208,7 @@ After temporal context is fetched and indexed (or skipped for any reason), immed
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to eligibility, cache, or failure) will you proceed to load `{nextStepFile}` for QMD enrichment.
+ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to eligibility, cache, or failure) will you proceed to load `{nextStepFile}` for documentation fetch.
 
 ---
 
@@ -216,7 +216,7 @@ ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to el
 
 ### ✅ SUCCESS:
 
-- Non-eligible scenarios (Quick/Forge tier, non-GitHub source, no `gh` CLI) skipped silently
+- Non-eligible scenarios (Quick/Forge/Forge+ tier, non-GitHub source, no `gh` CLI) skipped silently
 - Cached collections (< 7 days old) detected and re-fetch skipped
 - Temporal data fetched via `gh` CLI into staging directory (generic + targeted)
 - Targeted searches performed for up to 10 top_exports function names
@@ -224,14 +224,14 @@ ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to el
 - Collection `{skill-name}-temporal` indexed into QMD
 - Registry entry added/updated in forge-tier.yaml with type `"temporal"`
 - Staging directory cleaned up after indexing
-- Auto-proceeded to step-04
+- Auto-proceeded to step-03c
 
 ### ❌ SYSTEM FAILURE:
 
 - Halting the workflow due to a `gh` CLI, QMD, or network failure
 - Leaving staging files on disk after indexing (must clean up)
 - Overwriting or modifying extraction data from step-03
-- Displaying skip messages for Quick/Forge tiers (should be silent)
+- Displaying skip messages for Quick/Forge/Forge+ tiers (should be silent)
 - Attempting to fetch temporal data from non-GitHub sources
 - Not registering the collection in forge-tier.yaml after successful indexing
 

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

@@ -85,7 +85,9 @@ Content fetched from external URLs is classified as **T3** (external, untrusted)
 
 After fetching a URL, apply the following heuristic to detect documentation root pages that contain no useful API content. This is common with modern documentation sites (Mintlify, Docusaurus, ReadTheDocs, GitBook) that render API content on subpages.
 
-**Root page detection heuristic — a page is a root if BOTH conditions are true:**
+**Root page detection heuristic — apply only when the URL path ends in `/`, `/index`, `/index.html`, has no path component (bare domain), or has 1 path segment (e.g., `/docs`). For deeper URL paths (2+ segments like `/api/reference`), skip this heuristic and keep the content as-is.**
+
+**A page is classified as a root if BOTH conditions are true:**
 
 1. **Zero API content indicators:** The fetched markdown contains none of: fenced code blocks (`` ``` ``), parameter tables (`|---|`), or function signature patterns (`def `, `function `, `fn `, `func `, `export `).
 2. **High link density:** More than 70% of non-empty lines are markdown links (matching `[text](url)` with no other substantive content on the line).

package/src/workflows/create-skill/steps-c/step-04-enrich.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-04-enrich'
-description: 'QMD knowledge enrichment for extracted functions — Deep tier only, skip for Quick/Forge'
+description: 'QMD knowledge enrichment for extracted functions — Deep tier only, skip for Quick/Forge/Forge+'
 nextStepFile: './step-05-compile.md'
 ---
 
@@ -8,7 +8,7 @@ nextStepFile: './step-05-compile.md'
 
 ## STEP GOAL:
 
-To enrich the extraction inventory with temporal context from QMD knowledge searches — issues, PRs, changelogs, and migration notes that add T2-confidence annotations to extracted functions. Deep tier only; Quick and Forge tiers skip this step entirely.
+To enrich the extraction inventory with temporal context from QMD knowledge searches — issues, PRs, changelogs, and migration notes that add T2-confidence annotations to extracted functions. Deep tier only; Quick, Forge, and Forge+ tiers skip this step entirely.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -31,7 +31,7 @@ To enrich the extraction inventory with temporal context from QMD knowledge sear
 - 🚫 FORBIDDEN to modify extraction results — enrichment is additive only
 - 🚫 FORBIDDEN to begin compilation — that's step-05
 - 💬 QMD failures degrade gracefully — continue without enrichment
-- ⏱️ Quick and Forge tiers: skip this step entirely, auto-proceed
+- ⏱️ Quick, Forge, and Forge+ tiers: skip this step entirely, auto-proceed
 
 ## EXECUTION PROTOCOLS:
 
@@ -53,7 +53,7 @@ To enrich the extraction inventory with temporal context from QMD knowledge sear
 
 ### 1. Check Tier Eligibility
 
-**If tier is Quick or Forge:**
+**If tier is Quick, Forge, or Forge+:**
 
 Auto-proceed silently. Display no message. Immediately load, read entire file, then execute `{nextStepFile}`.
 
@@ -70,7 +70,7 @@ Before searching, check which QMD collections are available:
 3. **If no enrichment collections exist** (no `"temporal"` or `"docs"` type collections): report this and auto-proceed. Display:
 
 "**Enrichment: no enrichment collections available.**
-Only brief-type or extraction-type QMD collections found — no temporal context (issues, PRs, changelogs) or docs collections indexed. Enrichment skipped (expected for first-run skill creation). Enrichment becomes available when temporal or docs context is indexed into QMD collections.
+Only brief-type or extraction-type QMD collections found — no temporal context (issues, PRs, changelogs) or docs collections indexed. {IF extraction_mode is 'docs-only' AND T3 items exist in extraction_inventory: 'T3 documentation content is available in extraction inventory — enrichment via QMD is skipped but T3 content will be compiled.'} {ELSE: 'Enrichment skipped (expected for first-run skill creation). Enrichment becomes available when temporal or docs context is indexed into QMD collections.'}
 
 Proceeding to compilation..."
 
@@ -145,13 +145,13 @@ After enrichment is complete (or skipped for non-Deep tiers), immediately load,
 #### EXECUTION RULES:
 
 - This is an auto-proceed step with no user choices
-- Quick/Forge tiers skip directly to next step with no output
+- Quick/Forge/Forge+ tiers skip directly to next step with no output
 - Deep tier displays brief enrichment summary then auto-proceeds
 - QMD failures do not halt — degrade and proceed
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge) will you proceed to load `{nextStepFile}` for SKILL.md compilation.
+ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge/Forge+) will you proceed to load `{nextStepFile}` for SKILL.md compilation.
 
 ---
 
@@ -159,7 +159,7 @@ ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge
 
 ### ✅ SUCCESS:
 
-- Quick/Forge tiers: skipped silently with no output, auto-proceeded
+- Quick/Forge/Forge+ tiers: skipped silently with no output, auto-proceeded
 - Deep tier: collection inventory checked before searching
 - Deep tier: no temporal collections → reported and auto-proceeded (not silently skipped)
 - Deep tier: temporal collections exist → QMD searches performed per public API function (10-20, not all exports) with module context derived from extraction inventory source paths
@@ -172,7 +172,7 @@ ONLY WHEN enrichment is complete (Deep tier) or the step is skipped (Quick/Forge
 
 - Halting on QMD unavailability or search failures
 - Modifying T1 extraction results with QMD data
-- Displaying skip messages for Quick/Forge tiers (should be silent)
+- Displaying skip messages for Quick/Forge/Forge+ tiers (should be silent)
 - Pre-emptively skipping all searches without checking the collection inventory
 - Searching all 800+ exports instead of scoping to public API surface (10-20)
 - Using bare function names without module context when source path is available in extraction inventory

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

@@ -39,7 +39,7 @@ To assemble the complete skill content from the extraction inventory and enrichm
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 Build all content in context or write to a staging directory (`_bmad-output/{name}/`)
+- 💾 Build all content in context AND write to the staging directory (`_bmad-output/{name}/`) — staging write is mandatory for step-06 validation
 - 📖 Follow agentskills.io section structure from data file
 - 🚫 Do not promote any output files to final `skills/` or `forge-data/` directories — that's step-07
 
@@ -100,7 +100,8 @@ Following the structure from the skill-sections data file:
 - Set `description` from the SKILL.md frontmatter `description` field (already assembled in section 2)
 - Set `language` from source analysis (e.g., `"typescript"`, `"python"`) — use the primary language of the entry point file
 - Set `ast_node_count` from extraction stats if ast-grep was used (Forge/Deep tier), otherwise omit
-- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` from the SKF module's `package.json` `version` field (run `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"` or read the installed module's `package.json`). If unresolvable, fall back to `git describe --tags --abbrev=0` in the SKF module root. Never hardcode the version.
+- Set `tool_versions` based on tier and available tools. Resolve `{skf_version}` from the installed module's `package.json` at `{project-root}/_bmad/skf/package.json`. If unresolvable there, fall back to `node -p "require('./node_modules/bmad-module-skill-forge/package.json').version"`. If still unresolvable, use `"unknown"` and add a warning to the evidence report. Never hardcode the version.
+- 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.
 
 ### 5. Build references/ Content
@@ -119,7 +120,7 @@ One entry per extracted export: export_name, export_type, params[] (typed string
 
 ### 7. Build evidence-report.md Content
 
-Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), validation results (populated in step-06), warnings. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
+Compilation audit trail: generation date, forge tier, source info, tool versions, extraction summary (files/exports/confidence), warnings. For validation-specific fields (Schema, Body, Security, Content Quality, tessl, Metadata), insert the placeholder text `[PENDING — populated by step-06]`. Step-06 will replace these placeholders with actual results. See `{skillSectionsData}` for full template. Use the same `{skf_version}` value resolved in section 4 when populating the Tool Versions block.
 
 ### 8. Menu Handling Logic
 

package/src/workflows/create-skill/steps-c/step-06-validate.md

@@ -101,7 +101,7 @@ If fails: auto-fix (deterministic), re-validate once, record result. If passes:
 
 **If step 2 reported `body.max_lines` failure:**
 
-**Preferred approach — selective split:** Rather than a full `split-body`, identify which Tier 2 section(s) are largest (usually `## Full API Reference`) and manually extract only those to `references/`. Keep all Tier 1 content and smaller Tier 2 sections inline. This preserves agent accuracy — inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research). See `knowledge/split-body-strategy.md` for the full rationale.
+**Preferred approach — selective split:** Rather than a full `split-body`, identify which Tier 2 section(s) are largest (usually `## Full API Reference`) and manually extract only those to `references/`. Keep all Tier 1 content and smaller Tier 2 sections inline. This preserves agent accuracy — inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research). The rationale: inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research).
 
 **If manual selective split is not feasible**, fall back to the automated full split:
 
@@ -125,7 +125,7 @@ npx skill-check check <staging-skill-dir> --format json
 
 (Security scan enabled by default when `--no-security-scan` omitted. The scan uses [Snyk Agent Scan](https://github.com/snyk/agent-scan) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions.)
 
-Record any security warnings in evidence-report. Security findings are advisory — they do not block artifact generation.
+Record any security warnings in evidence-report. Security findings are advisory — they do not block artifact generation. If the full validation re-run produces a different quality score than section 2, update the evidence-report with the newer score.
 
 **If security scan fails due to missing SNYK_TOKEN:**
 
@@ -181,7 +181,7 @@ tessl suggestions:
 Cross-check metadata.json against extraction inventory:
 - `stats.exports_documented` / `stats.exports_public_api` / `stats.exports_internal` / `stats.exports_total` are accurate
 - `stats.public_api_coverage` and `stats.total_coverage` are correctly computed (null when denominator is 0)
-- `confidence_t1`, `confidence_t2`, `confidence_t3` match actual counts
+- `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3` match actual counts
 - `spec_version` is "1.3"
 - If `scripts[]` or `assets[]` arrays present: verify `stats.scripts_count`/`stats.assets_count` match array lengths; verify `file_entries` count in provenance-map.json matches
 

package/src/workflows/create-skill/steps-c/step-07-generate-artifacts.md

@@ -9,7 +9,7 @@ forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 
 ## STEP GOAL:
 
-To write all compiled content to disk — 4 deliverable files to `skills/{name}/` and 3 workspace artifacts to `forge-data/{name}/`, creating directories as needed.
+To write all compiled content to disk — 4 deliverable files to `{skills_output_folder}/{name}/` and 3 workspace artifacts to `{forge_data_folder}/{name}/`, creating directories as needed.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -30,7 +30,7 @@ To write all compiled content to disk — 4 deliverable files to `skills/{name}/
 
 - 🎯 Focus ONLY on writing files from the compiled content in context
 - 🚫 FORBIDDEN to modify content during writing — write exactly what was compiled
-- 🚫 FORBIDDEN to skip any artifact — all 7 files must be written
+- 🚫 FORBIDDEN to skip any artifact — all base artifact types must be written (4 deliverables + 3 workspace files + N reference files)
 - 💬 Report each file written with its path
 - 📁 Create directories before writing files
 
@@ -54,65 +54,66 @@ To write all compiled content to disk — 4 deliverable files to `skills/{name}/
 
 ### 1. Create Directory Structure
 
-Create the following directories at `{project-root}/`:
+Create the following directories:
 
 ```
-skills/{name}/
-skills/{name}/references/
-forge-data/{name}/
+{skills_output_folder}/{name}/
+{skills_output_folder}/{name}/references/
+{forge_data_folder}/{name}/
 ```
 
-If `scripts_inventory` is non-empty, also create: `skills/{name}/scripts/`
-If `assets_inventory` is non-empty, also create: `skills/{name}/assets/`
+If `scripts_inventory` is non-empty, also create: `{skills_output_folder}/{name}/scripts/`
+If `assets_inventory` is non-empty, also create: `{skills_output_folder}/{name}/assets/`
 
 Where `{name}` is the skill name from the brief (kebab-case).
 
 If directories already exist, do not error — proceed with file writing (overwrites existing files).
 
-### 2. Write Deliverables to skills/{name}/
+### 2. Write Deliverables to {skills_output_folder}/{name}/
 
 Write these 4 files from the compiled content:
 
-**File 1:** `skills/{name}/SKILL.md`
+**File 1:** `{skills_output_folder}/{name}/SKILL.md`
 - The complete compiled skill document
 - agentskills.io-compliant format with all sections
 - [MANUAL] markers seeded
 
-**File 2:** `skills/{name}/context-snippet.md`
+**File 2:** `{skills_output_folder}/{name}/context-snippet.md`
 - Compressed 2-line format for CLAUDE.md integration
 
-**File 3:** `skills/{name}/metadata.json`
+**File 3:** `{skills_output_folder}/{name}/metadata.json`
 - Machine-readable birth certificate with stats and provenance
 
-**File 4:** `skills/{name}/references/*.md`
+**File 4:** `{skills_output_folder}/{name}/references/*.md`
 - One file per function group or type
 - Progressive disclosure detail files
 
-**Files 4b (conditional):** `skills/{name}/scripts/*`
+**Files 4b (conditional):** `{skills_output_folder}/{name}/scripts/*`
 - One file per detected script, copied from source with content preserved
 - Only created when `scripts_inventory` is non-empty
 
-**Files 4c (conditional):** `skills/{name}/assets/*`
+**Files 4c (conditional):** `{skills_output_folder}/{name}/assets/*`
 - One file per detected asset, copied from source with content preserved
 - Only created when `assets_inventory` is non-empty
 
-### 3. Write Workspace Artifacts to forge-data/{name}/
+### 3. Write Workspace Artifacts to {forge_data_folder}/{name}/
 
 Write these 3 files from the compiled content:
 
-**File 5:** `forge-data/{name}/provenance-map.json`
+**File 5:** `{forge_data_folder}/{name}/provenance-map.json`
 - Per-claim source map with AST bindings and confidence tiers
 
-**File 6:** `forge-data/{name}/evidence-report.md`
+**File 6:** `{forge_data_folder}/{name}/evidence-report.md`
 - Build artifact with extraction summary, validation results, warnings
 
-**File 7:** `forge-data/{name}/extraction-rules.yaml`
+**File 7:** `{forge_data_folder}/{name}/extraction-rules.yaml`
 - Language and ast-grep schema used for this extraction (for reproducibility)
 
 ### 4. Verify Write Completion
 
 After all files are written, verify:
-- All 7 base files exist at their expected paths, plus scripts/ and assets/ files when inventories are non-empty
+- All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, at least one file in references/), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
+- Store `ref_count` = count of files written to `references/` for use in step-08 report
 - List each file with its path and size
 
 **If any write failed:**
@@ -123,7 +124,7 @@ Display brief confirmation:
 
 "**Artifacts generated.**
 
-**Deliverables (skills/{name}/):**
+**Deliverables ({skills_output_folder}/{name}/):**
 - SKILL.md
 - context-snippet.md
 - metadata.json
@@ -131,7 +132,7 @@ Display brief confirmation:
 {if assets: - assets/ ({assets_count} files)}
 - references/ ({reference_count} files)
 
-**Workspace (forge-data/{name}/):**
+**Workspace ({forge_data_folder}/{name}/):**
 - provenance-map.json
 - evidence-report.md
 - extraction-rules.yaml
@@ -144,23 +145,13 @@ Proceeding to compilation report..."
 
 Index the generated skill artifacts into a QMD collection so that audit-skill and update-skill can perform high-signal searches against curated extraction data instead of raw source files.
 
-**Collection creation:**
-
-Create a QMD collection from both artifact directories:
-```bash
-qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
-qmd embed
-```
-
-If collection already exists (re-run): remove and recreate for atomic replace:
+**Collection creation:** Create (or replace) a QMD collection from the skill artifacts:
 ```bash
-qmd collection remove {name}-extraction
-qmd collection add {project-root}/skills/{name} --name {name}-extraction --mask "**/*"
-qmd embed
+qmd collection remove {name}-extraction 2>/dev/null  # no-op if new
+qmd collection add {skills_output_folder}/{name} --name {name}-extraction --mask "**/*"
+qmd embed  # generates vector embeddings for vector_search/deep_search
 ```
 
-**Note:** `qmd embed` generates vector embeddings required for `vector_search` and `deep_search`. Without it, only BM25 keyword `search` works.
-
 **Registry update:**
 
 Read `{forgeTierConfig}` and update the `qmd_collections` array.
@@ -183,6 +174,36 @@ Write the updated forge-tier.yaml.
 
 **IF forge tier is NOT Deep:** Skip this section silently. No messaging.
 
+### 5b. CCC Index Registry Registration (Forge+ and Deep with ccc)
+
+**IF `tools.ccc` is true in forge-tier.yaml (Forge+ or Deep with ccc available):**
+
+Ensure the source path used for extraction is indexed by ccc and registered in the `ccc_index_registry` array.
+
+**Index verification:**
+
+Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup-forge or step-02b.
+
+**Registry update:**
+
+Read `{forgeTierConfig}` and update the `ccc_index_registry` array.
+
+Deduplicate by `source_repo` + `skill_name` (NOT local `path`, which may be ephemeral). Replace existing match or append:
+
+```yaml
+  - source_repo: "{brief.source_repo}"
+    path: "{source_root}"
+    skill_name: "{name}"
+    indexed_at: "{current ISO date}"
+    source_workflow: "create-skill"
+```
+
+Write the updated forge-tier.yaml.
+
+**Error handling:** If ccc indexing or registry update fails, log and continue — do NOT fail the workflow.
+
+**IF `tools.ccc` is false:** Skip this section silently.
+
 ### 6. Menu Handling Logic
 
 **Auto-proceed step — no user interaction.**
@@ -207,9 +228,9 @@ ONLY WHEN all 7 artifact files are written and verified will you proceed to load
 
 ### ✅ SUCCESS:
 
-- Directory structure created (skills/{name}/, forge-data/{name}/)
-- All 4 deliverable files written to skills/{name}/
-- All 3 workspace artifact files written to forge-data/{name}/
+- Directory structure created ({skills_output_folder}/{name}/, {forge_data_folder}/{name}/)
+- All 4 deliverable files written to {skills_output_folder}/{name}/
+- All 3 workspace artifact files written to {forge_data_folder}/{name}/
 - Write completion verified — all 7 files exist
 - Deep tier: QMD collection `{name}-extraction` created/updated and registered in forge-tier.yaml
 - Non-Deep tier: QMD indexing skipped silently

package/src/workflows/create-skill/steps-c/step-08-report.md

@@ -73,16 +73,17 @@ Where `{primary_confidence}` is the predominant confidence tier (T1 if Forge/Dee
 |------|-------|-------------|
 | T1 (AST) | {t1_count} | Structurally verified via ast-grep |
 | T1-low (Source) | {t1_low_count} | Inferred from source reading |
-| T2 (QMD) | {t2_count} | Enriched with temporal context |
+| T2 (QMD) | {t2_count} | QMD-enriched semantic context |
+| T3 (External) | {t3_count} | Sourced from external documentation URLs |
 
 **Output Files:**
-- `skills/{name}/SKILL.md` — Active skill with trigger-based usage
-- `skills/{name}/context-snippet.md` — Passive context for CLAUDE.md
-- `skills/{name}/metadata.json` — Machine-readable birth certificate
-- `skills/{name}/references/` — Progressive disclosure ({ref_count} files)
-- `forge-data/{name}/provenance-map.json` — Source map with AST bindings
-- `forge-data/{name}/evidence-report.md` — Build audit trail
-- `forge-data/{name}/extraction-rules.yaml` — Reproducible extraction schema"
+- `{skills_output_folder}/{name}/SKILL.md` — Active skill with trigger-based usage
+- `{skills_output_folder}/{name}/context-snippet.md` — Passive context for CLAUDE.md
+- `{skills_output_folder}/{name}/metadata.json` — Machine-readable birth certificate
+- `{skills_output_folder}/{name}/references/` — Progressive disclosure ({ref_count} files)
+- `{forge_data_folder}/{name}/provenance-map.json` — Source map with AST bindings
+- `{forge_data_folder}/{name}/evidence-report.md` — Build audit trail
+- `{forge_data_folder}/{name}/extraction-rules.yaml` — Reproducible extraction schema"
 
 ### 3. Display Warnings (If Any)
 
@@ -99,7 +100,7 @@ If no warnings, omit this section entirely.
 
 "**Recommended next steps:**
 - **[TS] Test Skill** — verify completeness and accuracy before export
-- **[ES] Export Skill** — publish to your skill library or agentskills.io
+- **[EX] Export Skill** — publish to your skill library or agentskills.io
 - **[US] Update Skill** — edit specific sections or add manual content
 
 To use this skill immediately, add the context snippet to your CLAUDE.md:
@@ -115,9 +116,23 @@ To use this skill immediately, add the context snippet to your CLAUDE.md:
 
 {If more remaining:} Proceeding to next brief: {next_skill_name}..."
 
-Update sidecar checkpoint with batch progress, then loop back to step-01 for the next brief.
+Update the batch checkpoint in `{sidecar_path}/batch-state.yaml` with:
 
-**If not batch mode or all batch briefs complete:**
+```yaml
+batch_active: true
+brief_list: [{full list of brief paths}]
+current_index: {index of next brief to process, 0-based}
+completed: [{list of completed skill names}]
+last_updated: {ISO timestamp}
+```
+
+Then loop back to step-01 for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index`.
+
+**If all batch briefs complete:**
+
+Set `batch_active: false` in `{sidecar_path}/batch-state.yaml` to prevent stale state. Display: "Batch complete. {completed_count} skills compiled."
+
+**If not batch mode:**
 
 End workflow. No further steps.
 

package/src/workflows/create-skill/workflow.md

@@ -9,16 +9,16 @@ installed_path: '{project-root}/_bmad/skf/workflows/skillforge/create-skill'
 
 **Goal:** Compile a verified agent skill from a skill-brief.yaml and source code, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references.
 
-**Your Role:** You are a skill compilation engine performing structural extraction and assembly. This workflow is mostly autonomous with three interaction points — one after ecosystem check (if a match is found), one after source extraction (to confirm findings before compilation), and one after content quality review (when tessl produces suggestions). All other steps auto-proceed. Apply zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation.
+**Your Role:** You are operating in **Ferris Architect mode** — a skill compilation engine performing structural extraction and assembly. This workflow is mostly autonomous with three interaction points — one after ecosystem check (if a match is found), one after source extraction (to confirm findings before compilation), and one after content quality review (when tessl produces suggestions). All other steps auto-proceed. Apply zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation.
 
 ## WORKFLOW ARCHITECTURE
 
 ### Core Principles
 
-- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere to 1 file as directed at a time
 - **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
 - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
-- **Tier-Aware Execution**: Steps adapt behavior based on forge tier (Quick/Forge/Deep) loaded from sidecar at init
+- **Tier-Aware Execution**: Steps adapt behavior based on forge tier (Quick/Forge/Forge+/Deep) loaded from sidecar at init
 - **Zero Hallucination**: Every claim requires a provenance citation — uncitable content is excluded, not guessed
 
 ### Step Processing Rules