bmad-module-skill-forge 0.5.0 → 0.7.0

package/src/workflows/audit-skill/steps-c/step-04-semantic-diff.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-04-semantic-diff'
-description: 'Compare QMD knowledge context for meaning-level changes (Deep tier only, skip at Quick/Forge)'
+description: 'Compare QMD knowledge context for meaning-level changes (Deep tier only, skip at Quick/Forge/Forge+)'
 
 nextStepFile: './step-05-severity-classify.md'
 outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
@@ -10,7 +10,7 @@ outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
 
 ## STEP GOAL:
 
-Compare QMD knowledge context between the original skill creation and current state to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier — at Quick and Forge tiers, it appends a skip notice and auto-proceeds.
+Compare QMD knowledge context between the original skill creation and current state to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier — at Quick, Forge, and Forge+ tiers, it appends a skip notice and auto-proceeds.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -35,7 +35,7 @@ Compare QMD knowledge context between the original skill creation and current st
 - 🚫 FORBIDDEN to repeat structural findings from Step 03
 - 💬 Use subprocess Pattern 3 (data operations) when available for QMD queries
 - ⚙️ If subprocess unavailable, query QMD in main thread
-- 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge tier — append skip notice only
+- 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append skip notice only
 
 ## EXECUTION PROTOCOLS:
 
@@ -57,7 +57,7 @@ Compare QMD knowledge context between the original skill creation and current st
 
 ### 1. Check Forge Tier
 
-**IF forge tier is Quick or Forge:**
+**IF forge tier is Quick, Forge, or Forge+:**
 
 Append to {outputFile}:
 
@@ -82,7 +82,7 @@ Continue to section 2.
 ### 2. Query Original Knowledge Context
 
 Launch a subprocess (Pattern 3 — data operations) that:
-1. Loads the QMD collection for the project
+1. Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`. Find the entry where `skill_name` matches `{skill_name}` AND `type` is `"extraction"`. Use the `name` field from that entry as the collection to query. If no matching entry exists, log: "No QMD extraction collection found for {skill_name}. Semantic diff skipped." → Auto-proceed to {nextStepFile}.
 2. Queries for knowledge context around each export documented in the skill
 3. Retrieves: usage patterns, conventions, architectural context, dependency relationships
 4. Returns structured findings to parent
@@ -179,7 +179,7 @@ ONLY WHEN the ## Semantic Drift section (or skip notice) has been appended to {o
 
 ### ✅ SUCCESS:
 
-- Forge tier checked FIRST — skip gracefully at Quick/Forge
+- Forge tier checked FIRST — skip gracefully at Quick/Forge/Forge+
 - Deep tier: QMD knowledge context queried and compared
 - All semantic findings have T2 confidence labels
 - Findings clearly distinguished from structural drift (T1)

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

@@ -2,7 +2,7 @@
 name: audit-skill
 description: "Drift detection. Forge tier: structural. Deep tier: full."
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/audit-skill'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/audit-skill'
 ---
 
 # Audit Skill
@@ -24,7 +24,7 @@ This uses **step-file architecture** for disciplined execution:
 - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
 - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
 - **Append-Only Building**: Build the drift report by appending sections as directed to the output file
-- **Tier-Aware Execution**: Adapt analysis depth based on detected forge tier (Quick/Forge/Deep) with graceful degradation
+- **Tier-Aware Execution**: Adapt analysis depth based on detected forge tier (Quick/Forge/Forge+/Deep) with graceful degradation
 
 ### Step Processing Rules
 
@@ -57,6 +57,7 @@ Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
 - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
 - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+- Generate and store `timestamp` as the current date-time in `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run and must not be regenerated in subsequent steps.
 
 ### 2. First Step Execution
 

package/src/workflows/brief-skill/data/scope-templates.md

@@ -59,6 +59,16 @@ Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
 Exclusions will include all internal implementation files, tests, and utilities.
 Prompt: "Any additional items you'd like to include or exclude?"
 
+### Docs-Only Boundaries
+
+**No source code access.** Scope is defined by the `doc_urls` collected during intent gathering.
+
+- All content derived from external documentation
+- No include/exclude patterns — coverage determined by fetched documentation
+- All extractions labeled T3 (`[EXT:{url}]` citations)
+
+Prompt: "Any additional documentation URLs to include? Or URLs to exclude from the ones collected?"
+
 ## Scripts & Assets Detection (Optional Refinement)
 
 When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -2,26 +2,27 @@
 
 ## Required Fields
 
-| Field | Type | Description | Validation |
-|-------|------|-------------|------------|
-| name | string | Kebab-case skill name | Must match `[a-z0-9-]+` |
-| version | string | Semantic version | Must match `X.Y.Z` pattern. Auto-detect from source (see Version Detection below), fall back to "1.0.0" |
-| source_repo | string | GitHub URL or local path | Must be accessible |
-| language | string | Primary programming language | Must be detected or user-specified |
-| scope | object | Inclusion/exclusion boundaries | Must have type + at least one pattern |
-| description | string | What this skill covers | 1-3 sentences |
-| forge_tier | string | Compilation tier | One of: quick, forge, deep |
-| created | string | Creation date | ISO date format |
-| created_by | string | User who created the brief | From config user_name |
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| name | string | kebab-case `[a-z0-9-]+` | Unique skill identifier |
+| version | string | Semantic `X.Y.Z` | Auto-detect from source (see Version Detection below), fall back to `1.0.0` |
+| source_repo | string | GitHub URL or local path | Repository or project root (optional when `source_type: "docs-only"`) |
+| language | string | Recognized language | Primary programming language |
+| scope | object | See Scope Object below | Boundary definition |
+| description | string | 1-3 sentences | What the skill covers |
+| forge_tier | string | `Quick` / `Forge` / `Forge+` / `Deep` | Inherited from forge-tier.yaml (Title Case) |
+| created | string | ISO date `YYYY-MM-DD` | Generation date |
+| created_by | string | user_name from config | Who generated the brief |
 
 ## Optional Fields
 
-| Field | Type | Description | Validation |
-|-------|------|-------------|------------|
-| source_type | string | Source mode: `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
-| doc_urls | array | Documentation URLs for T3 content | Each entry: `{url, label}`. Required when `source_type: "docs-only"` |
-| `scripts_intent` | string | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
-| `assets_intent` | string | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
+| Field | Type | Constraint | Description |
+|-------|------|------------|-------------|
+| source_type | string | `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
+| doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
+| `scripts_intent` | string | `detect` / `none` / free-text | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent` | string | `detect` / `none` / free-text | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
+| `source_authority` | string | `official` / `community` / `internal` | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -48,7 +49,7 @@ The create-skill workflow (step-03-extract) also performs version reconciliation
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api
+  type: full-library | specific-modules | public-api | docs-only
   include:
     - "src/**/*.ts"           # Glob patterns for included files/directories
   exclude:
@@ -67,7 +68,7 @@ source_type: "source"                    # "source" (default) or "docs-only"
 source_repo: "{github-url-or-local-path}"
 language: "{detected-language}"
 description: "{brief-description}"
-forge_tier: "{quick|forge|deep}"
+forge_tier: "{Quick|Forge|Forge+|Deep}"
 created: "{date}"
 created_by: "{user_name}"
 scope:
@@ -83,12 +84,13 @@ scope:
 #     label: "API Reference"
 # scripts_intent: detect         # Optional: detect | none | description
 # assets_intent: detect          # Optional: detect | none | description
+# source_authority: community    # Optional: official | community | internal
 ---
 ```
 
 ## Human-Readable Presentation Format
 
-When presenting the brief for confirmation (step 04), display as:
+When presenting the brief for confirmation (brief-skill step 04 only — not applicable to analyze-source batch generation), display as:
 
 ```
 Skill Brief: {name}
@@ -114,8 +116,8 @@ Created by: {created_by}
 1. `name` must be unique within {forge_data_folder}
 2. `source_repo` must be accessible (gh api for GitHub, path exists for local)
 3. `language` must be a recognized programming language
-4. `scope.type` must be one of the three defined types
-5. `scope.include` must have at least one pattern
-6. `forge_tier` must match the tier from forge-tier.yaml (or default to quick)
+4. `scope.type` must be one of the four defined types
+5. `scope.include` must have at least one pattern (exception: `docs-only` scope, where include patterns are optional since no source code is available)
+6. `forge_tier` must be one of: Quick, Forge, Forge+, Deep (Title Case, must match the tier from forge-tier.yaml, or default to Quick)
 7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional
 8. Each `doc_urls` entry must have a valid `url` field

package/src/workflows/brief-skill/steps-c/step-01-gather-intent.md

@@ -3,7 +3,7 @@ name: 'step-01-gather-intent'
 description: 'Initialize brief-skill workflow, discover forge tier, and gather user intent for skill creation'
 
 nextStepFile: './step-02-analyze-target.md'
-forgeTierFile: '{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
 # Step 1: Gather Intent
@@ -61,14 +61,14 @@ To initialize the brief-skill workflow by discovering the forge tier configurati
 Attempt to load `{forgeTierFile}`:
 
 **If found:**
-- Read the tier level (quick, forge, or deep)
+- Read the tier level (quick, forge, forge+, or deep)
 - Note available tools for scoping guidance later
 
-**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
 **If not found:**
 - Display: "**Note:** No forge tier configuration found. Defaulting to Quick tier. Run **setup-forge** first for full capabilities."
-- Default to: `forge_tier: quick`
+- Default to: `forge_tier: Quick`
 
 ### 2. Welcome and Explain
 

package/src/workflows/brief-skill/steps-c/step-02-analyze-target.md

@@ -131,6 +131,21 @@ Based on detected language, identify public API surface:
 **Detected Exports/Entry Points:**
 {numbered list of public-facing items found}"
 
+**Semantic Signals (Forge+ and Deep with ccc only):**
+
+If `tools.ccc` is true in forge-tier.yaml, supplement the module listing with a semantic discovery pass:
+
+Run `ccc_bridge.search("{repo_name} public API exports modules", source_path, top_k=10)`.
+
+If results are returned, display:
+
+"**Semantic Signals (ccc):**
+{numbered list of file:snippet pairs from CCC results — top 5 most relevant}"
+
+This supplements — never replaces — the explicit module list above. CCC may surface non-obvious entry points (dynamically constructed exports, re-export chains) that static directory analysis misses.
+
+If CCC is unavailable or returns no results: skip this subsection silently.
+
 ### 5. Report Analysis Summary
 
 Present the complete analysis:

package/src/workflows/brief-skill/steps-c/step-05-write-brief.md

@@ -91,6 +91,9 @@ scope:
 # doc_urls:
 #   - url: "{documentation URL}"
 #     label: "{page label}"
+# scripts_intent: detect         # Optional: detect | none | description of expected scripts
+# assets_intent: detect          # Optional: detect | none | description of expected assets
+# source_authority: community    # Optional: official | community | internal
 ---
 ```
 

package/src/workflows/create-skill/data/extraction-patterns.md

@@ -28,7 +28,7 @@ Source reading via gh_bridge — infer exports from file structure and content.
 
 Structural extraction via ast-grep — verified exports with line-level citations.
 
-> **Note:** `ast_bridge.*` and `qmd_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations and QMD (MCP tool or CLI) for `qmd_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
+> **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations, QMD (MCP tool or CLI) for `qmd_bridge.*` operations, and ccc CLI or MCP for `ccc_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
 
@@ -52,6 +52,42 @@ Structural extraction via ast-grep — verified exports with line-level citation
 
 ---
 
+## Forge+ Tier (AST + CCC)
+
+Identical extraction to Forge tier. CCC adds an upstream semantic discovery step that pre-ranks the file extraction queue.
+
+### When CCC Pre-Discovery Applies
+
+CCC pre-discovery runs in step-02b-ccc-discover (before this extraction step) when ALL of the following are true:
+- Tier is Forge+ or Deep
+- `tools.ccc: true` in forge-tier.yaml
+- `ccc_index.status` is `"fresh"`, `"stale"`, `"created"`, or `"none"`/`"failed"` (step-02b attempts lazy indexing for the latter two)
+
+The discovery step stores `{ccc_discovery: [{file, score, snippet}]}` in context. This extraction step consumes those results to pre-rank the file list.
+
+### CCC Pre-Ranking Strategy
+
+When `{ccc_discovery}` is present and non-empty:
+
+1. Files appearing in `{ccc_discovery}` results move to the front of the extraction queue, sorted by relevance score descending
+2. Files NOT in CCC results remain in the queue — they are not excluded, only deprioritized
+3. If the CCC intersection with scoped files produces <10 files: include all scoped files (CCC results too narrow)
+4. Proceed with the AST Extraction Protocol on the pre-ranked list
+
+### ast-grep Patterns
+
+Same patterns as Forge tier — see Forge tier section above. CCC pre-ranking does not change which AST patterns are used, only which files are processed first.
+
+### Confidence
+
+All results: T1 (AST-verified) — identical to Forge tier. CCC is upstream discovery only and is invisible in the output artifact.
+
+### Important
+
+CCC pre-discovery failures (ccc unavailable, command error, empty results) always result in standard Forge extraction behavior. This is not reported to the user as a problem — it is normal behavior when ccc has no relevant results for the skill's scope.
+
+---
+
 ## Deep Tier (AST + QMD)
 
 Same extraction as Forge tier. Deep tier adds enrichment in step-04, not extraction.

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

@@ -56,7 +56,7 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 - Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full` headings) into `references/`
 - After split-body, SKILL.md retains all Tier 1 content — actionable without loading references
 - An agent loading only SKILL.md (no references) must get enough to act
-- **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/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 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.
 
 ### Provenance Citation Format
@@ -120,7 +120,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   "source_repo": "{github-url}",
   "source_root": "{resolved-source-path}",
   "source_commit": "{commit-hash}",
-  "confidence_tier": "{Quick|Forge|Deep}",
+  "confidence_tier": "{Quick|Forge|Forge+|Deep}",
   "spec_version": "1.3",
   "generation_date": "{ISO-8601}",
   "description": "{SKILL.md frontmatter description}",
@@ -132,6 +132,12 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "qmd": "{version-or-null}",
     "skf": "{skf_version}"
   },
+  "confidence_distribution": {
+    "t1": 0,
+    "t1_low": 0,
+    "t2": 0,
+    "t3": 0
+  },
   "stats": {
     "exports_documented": 0,
     "exports_public_api": 0,
@@ -139,18 +145,13 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "exports_total": 0,
     "public_api_coverage": 0.0,
     "total_coverage": 0.0,
-    "confidence_t1": 0,
-    "confidence_t2": 0,
-    "confidence_t3": 0,
     "scripts_count": 0,
     "assets_count": 0
   },
-  "scripts": [
-    { "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
-  ],
-  "assets": [
-    { "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
-  ],
+  // scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
+  // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
+  // "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
+  "generated_by": "{quick-skill|create-skill}",
   "dependencies": [],
   "compatibility": "{semver-range}"
 }
@@ -197,7 +198,7 @@ Each reference file includes:
       "source_file": "src/auth/index.ts",
       "source_line": 42,
       "confidence": "T1",
-      "extraction_method": "ast_bridge.scan_definitions",
+      "extraction_method": "ast-grep",
       "ast_node_type": "export_function_declaration"
     }
   ],
@@ -235,7 +236,7 @@ Each reference file includes:
 ## Extraction Summary
 - Files scanned: {count}
 - Exports found: {count}
-- Confidence: T1={n}, T2={n}, T3={n}
+- Confidence: T1={n}, T1-low={n}, T2={n}, T3={n}
 
 ## Validation Results
 - Schema: {pass/fail}

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

@@ -112,7 +112,7 @@ 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.
+**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.
 
 ---
 

package/src/workflows/create-skill/steps-c/step-01-load-brief.md

@@ -2,8 +2,8 @@
 name: 'step-01-load-brief'
 description: 'Load skill-brief.yaml, validate structure, resolve source code location, load forge tier'
 nextStepFile: './step-02-ecosystem-check.md'
-forgeTierFile: '{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml'
-preferencesFile: '{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
+preferencesFile: '{sidecar_path}/preferences.yaml'
 ---
 
 # Step 1: Load Brief
@@ -61,22 +61,23 @@ Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge fir
 
 **If file exists:**
 Extract and report:
-- `tier`: Quick, Forge, or Deep
-- `tools`: which tools are available (gh, ast-grep, qmd)
+- `tier`: Quick, Forge, Forge+, or Deep
+- `tools`: which tools are available (gh, ast-grep, ccc, qmd)
+- `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step-02b
 
-**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
 ### 2. Discover Skill Brief
 
 **If user provided a specific brief path or skill name:**
-- Search `{project-root}/forge-data/{skill-name}/skill-brief.yaml`
+- If the value looks like a file path (starts with `/`, `./`, `~`, or contains path separators): treat it as a direct file path and load it
+- Otherwise, treat it as a skill name and search `{forge_data_folder}/{skill-name}/skill-brief.yaml`
 - If found, load it completely
 
 **If user invoked with --batch flag:**
-- Search specified directory for all `skill-brief.yaml` files
-- List discovered briefs with skill names
-- Store list for batch loop processing
-- For this run, load the FIRST brief (batch loops back for remaining)
+- Check `{sidecar_path}/batch-state.yaml` for an active batch checkpoint:
+  - If `batch_active: true` and `current_index` is valid: load the brief at `brief_list[current_index]` (resuming a batch loop from step-08)
+  - If no checkpoint exists or `batch_active` is false: search specified directory for all `skill-brief.yaml` files, list discovered briefs with skill names, store list for batch loop processing, and load the FIRST brief
 
 **If no brief found:**
 Halt with: "No skill brief found. Run [BS] Brief Skill to create one, or use [QS] Quick Skill for brief-less generation."
@@ -100,6 +101,8 @@ Check that the loaded skill-brief.yaml contains required fields:
 - `include_patterns` — file glob patterns to include
 - `exclude_patterns` — file glob patterns to exclude
 - `description` — human description of the skill
+- `scripts_intent` — `"none"` to skip scripts detection, omit for default auto-detection
+- `assets_intent` — `"none"` to skip assets detection, omit for default auto-detection
 
 **Docs-only validation:** When `source_type: "docs-only"`, `source_repo` is not required but `doc_urls` must have at least one entry. `source_authority` is forced to `community`.
 
@@ -108,6 +111,8 @@ Halt with specific error: "Brief validation failed: missing required field `{fie
 
 ### 4. Resolve Source Code Location
 
+**If `source_type: "docs-only"`:** Skip source resolution. Set `source_location: null` in context. Proceed directly to section 5 (Report Initialization) — docs-only skills have no source to resolve.
+
 **If source_repo is a GitHub URL or owner/repo format:**
 - Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)`
 - If branch not specified, detect default branch
@@ -138,7 +143,8 @@ Proceeding to ecosystem check..."
 Where tier_description follows positive capability framing:
 - Quick: "Source reading and spec validation"
 - Forge: "AST-backed structural extraction"
-- Deep: "Full intelligence — structural + contextual + temporal"
+- Forge+: "Semantic-guided precision — ccc pre-ranks files before AST extraction"
+- Deep: "Full intelligence — structural + contextual + QMD knowledge synthesis"
 
 ### 6. Menu Handling Logic
 
@@ -164,7 +170,7 @@ ONLY WHEN forge-tier.yaml is loaded, skill-brief.yaml is validated, and source c
 
 - Forge tier loaded from sidecar with tool availability
 - Skill brief loaded and all required fields validated
-- Source code location resolved and accessible
+- Source code location resolved and accessible (or `source_location: null` confirmed for docs-only skills)
 - Initialization summary displayed with tier and capabilities
 - Auto-proceeded to step-02
 

package/src/workflows/create-skill/steps-c/step-02-ecosystem-check.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-02-ecosystem-check'
 description: 'Check agentskills.io ecosystem for existing official skill before compilation'
-nextStepFile: './step-03-extract.md'
+nextStepFile: './step-02b-ccc-discover.md'
 ---
 
 # Step 2: Ecosystem Check
@@ -131,7 +131,7 @@ If no match is found, this step auto-proceeds with no user interaction.
 - Match presented factually with clear options if found
 - No-match case auto-proceeds silently
 - User decision respected (Proceed/Install/Abort)
-- Auto-proceeded to step-03 (when no match or user chose Proceed)
+- Auto-proceeded to step-02b (when no match or user chose Proceed)
 
 ### ❌ SYSTEM FAILURE:
 

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

@@ -0,0 +1,157 @@
+---
+name: 'step-02b-ccc-discover'
+description: 'CCC semantic discovery pass — Forge+ and Deep tiers when ccc is available, skip for Quick/Forge'
+nextStepFile: './step-03-extract.md'
+---
+
+# Step 2b: CCC Semantic Discovery
+
+## STEP GOAL:
+
+If tier is Forge+ or Deep AND ccc is available, perform a semantic discovery pass over the source code to identify the most relevant files for the skill being created. Store ranked discovery results in context to pre-rank the file extraction queue in step-03.
+
+For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
+
+## 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
+- 🔄 CRITICAL: When loading next step, ensure entire file is read
+- ⚙️ 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 semantic pre-discovery
+- ✅ CCC discovery is a hint layer — it guides extraction, it does not replace it
+- ✅ Discovery failure is graceful degradation, not an error
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on running ccc semantic search and storing results
+- 🚫 FORBIDDEN to extract exports — that is step-03
+- 🚫 FORBIDDEN to modify brief data or source resolution
+- 🚫 FORBIDDEN to block the workflow if ccc fails
+- ⏱️ Quick and Forge tiers: skip this step entirely and silently
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Discovery results stored in context as `{ccc_discovery}`
+- 📖 Results are consumed by step-03 to pre-rank the file extraction queue
+- 🚫 Never treat ccc results as verified extractions
+
+## CONTEXT BOUNDARIES:
+
+- Available: tier, tools.ccc, ccc_index from forge-tier.yaml (loaded in step-01)
+- Available: brief_data (name, scope, description) from step-01
+- Available: source_root (resolved source path) from step-01
+- Focus: Semantic discovery only — no extraction, no compilation
+- Dependencies: step-02 must have completed
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check Tier Eligibility
+
+**If tier is Quick or Forge:**
+
+Set `{ccc_discovery: []}` in context. Auto-proceed silently. Display no message. Immediately load, read entire file, then execute `{nextStepFile}`.
+
+**If tier is Forge+ or Deep:**
+
+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.
+
+### 2. Check CCC Index State
+
+Read `ccc_index` from forge-tier.yaml:
+
+- If `ccc_index.status` is `"fresh"`: continue to section 3.
+- 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.
+
+### 3. Construct Semantic Query
+
+Build the discovery query from the brief data:
+
+**Primary query:** `"{brief.name} {brief.scope}"`
+
+Where:
+- `brief.name` is the skill name from the brief
+- `brief.scope` is the scope field (e.g., "Full library", "Public API", or specific module names)
+
+**Query length cap:** Truncate to 80 characters if longer — ccc semantic search is sensitive to overly long queries. When truncating, 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.
+
+### 4. Execute CCC Semantic Search
+
+Run `ccc_bridge.search(query, source_root, top_k=20)`:
+
+**If search succeeds:**
+
+Store results as `{ccc_discovery: [{file, score, snippet}]}` in context.
+
+Display brief discovery summary:
+
+"**CCC semantic discovery: {N} relevant regions identified across {M} unique files.**"
+
+Where:
+- `{N}` is the total result count
+- `{M}` is the count of unique file paths in results
+
+**If search fails (any error):**
+
+Set `{ccc_discovery: []}` in context.
+
+Display: "CCC discovery unavailable — proceeding with standard extraction."
+
+Do NOT halt. This is not an error.
+
+**If search returns empty results:**
+
+Set `{ccc_discovery: []}` in context.
+
+No message needed — empty results are normal for small or highly focused libraries.
+
+### 5. Auto-Proceed
+
+Immediately load, read entire file, then execute `{nextStepFile}`.
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Quick/Forge tiers skip directly with no output
+- Forge+/Deep with ccc displays brief discovery summary then auto-proceeds
+- CCC failures do not halt — degrade and proceed
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN discovery is complete (Forge+/Deep with ccc) or the step is skipped (Quick/Forge or ccc unavailable) will you proceed to load `{nextStepFile}` for AST extraction.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Quick/Forge tiers: skipped silently with no output, auto-proceeded
+- Forge+/Deep with ccc: semantic query constructed from brief data
+- Forge+/Deep with ccc: ccc_bridge.search executed, results stored as `{ccc_discovery}` in context
+- Discovery summary displayed (count of regions and unique files)
+- CCC failures handled gracefully (empty discovery, continue)
+- Auto-proceeded to step-03
+
+### ❌ SYSTEM FAILURE:
+
+- Halting on CCC unavailability or search failures
+- Extracting exports or signatures (that is step-03)
+- Displaying skip messages for Quick/Forge tiers
+- Treating CCC discovery results as verified extractions
+- Not storing `{ccc_discovery}` in context (even if empty)
+- Beginning compilation or SKILL.md assembly in this step
+
+**Master Rule:** CCC discovery is a hint layer. It improves extraction coverage but never replaces structural verification. Failures degrade gracefully.