bmad-module-skill-forge 0.7.3 → 0.7.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/knowledge/ccc-bridge.md

@@ -77,6 +77,36 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 - A stale index still produces useful results — the workflow proceeds with the stale index and notes the staleness
 - setup-forge is the designated refresh authority
 
+### Exclusion Patterns
+
+CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. This file contains `exclude_patterns` and `include_patterns` arrays in glob format. `ccc init` creates the file with sensible defaults (excludes `node_modules`, `__pycache__`, hidden dirs, etc.).
+
+**SKF infrastructure exclusions:** setup-forge step-01b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
+
+| Pattern | Purpose |
+|---------|---------|
+| `**/_bmad` | SKF framework module (workflow instructions, agents, knowledge) |
+| `**/_bmad-output` | Build output artifacts (TODO files, reports) |
+| `**/.claude` | Claude Code configuration |
+| `**/_skf-learn` | SKF learning materials |
+| `**/{skills_output_folder}` | Generated skill files (from manifest, default: `skills`) |
+| `**/{forge_data_folder}` | Compilation workspace (from manifest, default: `forge-data`) |
+
+The `skills_output_folder` and `forge_data_folder` values are read from `_bmad/_config/skf-manifest.yaml` when available, falling back to the defaults `skills` and `forge-data`. Patterns are appended only if not already present — user customizations to `settings.yml` are preserved.
+
+The configured exclusion patterns are stored in `ccc_index.exclude_patterns` in forge-tier.yaml for reference.
+
+### Deferred Discovery (Remote Sources)
+
+For remote repository sources (GitHub URLs), CCC cannot operate during step-02b because no local code exists yet. The ephemeral clone happens in step-03. To provide CCC pre-ranking for remote sources:
+
+1. **step-02b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
+2. **step-03:** After ephemeral clone succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND ephemeral_clone_active == true AND tier is Forge+/Deep`)
+3. **step-03:** Runs `ccc init {temp_path}` + `ccc index` on the ephemeral clone (extended timeout or background mode, verified via `ccc status`)
+4. **step-03:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
+
+The ephemeral clone index is not registered in `ccc_index_registry` — the clone is deleted after extraction and the CCC daemon's own GC handles orphaned indexes.
+
 ### Relationship to QMD Registry
 
 ccc_index and qmd_collections are **orthogonal**:
@@ -100,6 +130,8 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 - Running ccc_bridge.ensure_index() without checking ccc_index.status first — unnecessary re-indexing
 - Passing ccc results directly to the extraction inventory — they are candidates, not extractions
 - Listing ccc as "unavailable" in reports for Quick/Forge tiers — ccc is a Forge+ capability, not something Quick/Forge tiers are missing
+- Indexing without configuring SKF exclusions — framework and output directories pollute search results
+- Skipping CCC discovery for remote sources without deferring to step-03 — remote repos deserve the same pre-ranking as local sources
 
 ## Related Fragments
 

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

@@ -139,7 +139,7 @@ Based on detected language, identify public API surface:
 
 **Semantic Signals (Forge+ and Deep with ccc only):**
 
-**Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC will be available during create-skill if the source is cloned locally."
+**Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC discovery will run automatically during create-skill after the source is cloned."
 
 If `tools.ccc` is true in forge-tier.yaml, supplement the module listing with a semantic discovery pass:
 

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
 

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

@@ -96,9 +96,30 @@ Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution*
 
 **Forge/Forge+/Deep Tier (AST available):**
 
+**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 `ccc init {temp_path}` then `ccc index` with an extended timeout or in background mode — 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 `ccc search "{query}" --path {temp_path} --top 20` (CLI). 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):
+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."

package/src/workflows/setup-forge/steps-c/step-01b-ccc-index.md

@@ -9,7 +9,7 @@ nextStepFile: './step-02-write-config.md'
 
 ## STEP GOAL:
 
-If ccc is available (`{ccc: true}` from step-01), verify that the ccc index exists for the project root. If no index exists, create it. Store index state in context for step-02 to write into forge-tier.yaml.
+If ccc is available (`{ccc: true}` from step-01), configure CCC exclusion patterns for SKF infrastructure directories, verify that the ccc index exists for the project root, and create or refresh it if needed. Store index state and exclusion patterns in context for step-02 to write into forge-tier.yaml.
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
@@ -32,7 +32,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 - 🎯 Focus only on ccc index verification and creation
 - 🚫 FORBIDDEN to display skip messages for Quick/Forge tiers
 - 🚫 FORBIDDEN to fail the workflow if ccc indexing fails
-- 🚫 FORBIDDEN to re-index if ccc index already exists and is fresh (< staleness threshold)
+- 🚫 FORBIDDEN to re-index if ccc index already exists and is fresh (< staleness threshold) UNLESS new exclusion patterns were applied to settings.yml
 
 ## EXECUTION PROTOCOLS:
 
@@ -56,7 +56,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 Read `{ccc}` from step-01 context.
 
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
+**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: []}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
 
 **If `{ccc}` is true:** Continue to section 2.
 
@@ -64,17 +64,58 @@ Read `{ccc}` from step-01 context.
 
 Read existing forge-tier.yaml at `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml` (if it exists from a previous run).
 
+Read `staleness_threshold_hours` from `ccc_index.staleness_threshold_hours` in the existing forge-tier.yaml (default: 24 if not present or not a number). Use this value for the freshness check below.
+
 Check the `ccc_index` section:
-- If `ccc_index.indexed_path` matches `{project-root}` AND `ccc_index.status` is `"fresh"`:
-  - Check freshness: if `ccc_index.last_indexed` is within `staleness_threshold_hours` (default 24h) of now → index is fresh
+- If `ccc_index.indexed_path` matches `{project-root}` AND `ccc_index.status` is `"fresh"` or `"created"`:
+  - Check freshness: if `ccc_index.last_indexed` is within `staleness_threshold_hours` of now → index is fresh
   - Store `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {existing timestamp}}`
-  - Proceed to section 4
+  - Set `{needs_reindex: false}` — proceed to section 2b (exclusions must still be configured)
 
 - If `ccc_index.indexed_path` matches `{project-root}` but timestamp is older than threshold:
-  - Note index is stale — proceed to section 3 for re-index (section 3 will overwrite `ccc_index_result` to `"created"` or `"failed"`)
+  - Set `{needs_reindex: true}` — proceed to section 2b then section 3
 
 - If `ccc_index` is missing, has null values, or path doesn't match:
-  - Proceed to section 3 for initial index
+  - Set `{needs_reindex: true}` — proceed to section 2b then section 3
+
+### 2b. Configure CCC Exclusions
+
+SKF infrastructure and output directories must be excluded from the CCC index — they contain workflow instructions, build artifacts, and generated skills that pollute semantic search results with zero extraction value.
+
+**Build the SKF exclusion list:**
+
+1. Read `{project-root}/_bmad/_config/skf-manifest.yaml` to resolve configurable paths:
+   - `skills_output_folder` (default: `skills` if manifest is missing or field is absent)
+   - `forge_data_folder` (default: `forge-data` if manifest is missing or field is absent)
+
+2. Assemble the exclusion patterns using `**/` prefix format (matching `.cocoindex_code/settings.yml` convention — e.g., `**/node_modules`):
+   - `**/_bmad` — SKF framework module (workflows, agents, knowledge files)
+   - `**/_bmad-output` — Build output artifacts
+   - `**/.claude` — Claude Code configuration
+   - `**/_skf-learn` — SKF learning materials
+   - `**/{skills_output_folder}` — Generated skill files (resolved from manifest)
+   - `**/{forge_data_folder}` — Compilation workspace (resolved from manifest)
+
+3. Store `{ccc_exclude_patterns}` in context for step-02 to write into forge-tier.yaml.
+
+**Apply exclusions to settings.yml:**
+
+Check if `{project-root}/.cocoindex_code/settings.yml` exists. Set `{settings_yml_existed: true}` if it does, `{settings_yml_existed: false}` if not.
+
+If `{settings_yml_existed}` is true (from a previous `ccc init` run):
+
+1. Read `settings.yml`
+2. For each pattern in `{ccc_exclude_patterns}`: if the pattern is NOT already present in `exclude_patterns`, append it and set `{exclusions_changed: true}`
+3. If `{exclusions_changed}`: write the updated `settings.yml` back, set `{needs_reindex: true}` (new exclusions require re-indexing), display: "**CCC exclusions configured:** {count} SKF patterns applied to .cocoindex_code/settings.yml"
+4. If no new patterns needed: display nothing (exclusions already configured)
+
+This preserves any existing user customizations and default exclusions while ensuring SKF directories are filtered out.
+
+If `{settings_yml_existed}` is false: the exclusions will be applied after `ccc init` in section 3.
+
+**Flow decision:**
+- If `{needs_reindex}` is true: proceed to section 3
+- If `{needs_reindex}` is false: proceed to section 4 (Auto-Proceed)
 
 ### 3. Create or Refresh CCC Index
 
@@ -93,6 +134,15 @@ ccc init
 
 **If init fails** (project may already be initialized): continue — this is not an error.
 
+**Apply SKF exclusion patterns (if not already applied in section 2b):**
+
+If `{settings_yml_existed}` is false (first-time setup — `ccc init` just created it), apply exclusions now:
+
+1. Read `{project-root}/.cocoindex_code/settings.yml` (created by `ccc init`)
+2. For each pattern in `{ccc_exclude_patterns}`: if the pattern is NOT already present in `exclude_patterns`, append it
+3. Write the updated `settings.yml` back
+4. Display: "**CCC exclusions configured:** {count} SKF patterns applied to .cocoindex_code/settings.yml"
+
 Then run:
 ```bash
 ccc index
@@ -102,8 +152,8 @@ ccc index
 
 **If succeeds:**
 - Run `ccc status` to get file count
-- Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from status}}`
-- Display: "**CCC index created.** {file_count} files indexed for semantic discovery."
+- Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from ccc status}}`
+- Display: "**CCC index created.** {ccc_file_count} files indexed for semantic discovery."
 
 **If fails:**
 - Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null}`
@@ -134,8 +184,8 @@ ONLY WHEN ccc index verification is complete (or step is skipped for ccc unavail
 ### ✅ SUCCESS:
 
 - ccc unavailable: skipped silently with no output, context variables set to null/none
-- ccc available with fresh index: verified freshness, skipped re-index, context variables set
-- ccc available with stale/missing index: index created, context variables set with fresh timestamp
+- ccc available with fresh index: verified freshness, exclusions configured, skipped re-index, context variables set
+- ccc available with stale/missing index: exclusions configured, index created, context variables set with fresh timestamp
 - ccc indexing fails: logged gracefully, workflow continues, context variables set to failed/null
 - Auto-proceeded to step-02
 
@@ -143,8 +193,10 @@ ONLY WHEN ccc index verification is complete (or step is skipped for ccc unavail
 
 - Displaying skip messages when ccc is unavailable
 - Halting the workflow on ccc index failure
-- Re-indexing when index is already fresh and path matches
+- Re-indexing when index is already fresh and path matches (unless exclusion patterns changed)
 - Writing forge-tier.yaml (that is step-02's responsibility)
 - Not storing ccc index context variables for step-02
+- Indexing without configuring SKF exclusion patterns in `.cocoindex_code/settings.yml`
+- Overwriting user customizations in `.cocoindex_code/settings.yml` instead of appending
 
 **Master Rule:** CCC indexing is always best-effort. Failures degrade gracefully. The workflow never halts over ccc issues.

package/src/workflows/setup-forge/steps-c/step-02-write-config.md

@@ -41,7 +41,7 @@ Write the detected tool availability and calculated tier to forge-tier.yaml, cre
 
 ## CONTEXT BOUNDARIES:
 
-- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01; {ccc_index_result}, {ccc_indexed_path}, {ccc_last_indexed} from step-01b
+- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01; {ccc_index_result}, {ccc_indexed_path}, {ccc_last_indexed}, {ccc_file_count}, {ccc_exclude_patterns} from step-01b
 - Focus: file I/O operations only
 - Limits: do not modify preferences.yaml if it exists
 - Dependencies: step-01 and step-01b must have completed with tool detection and CCC index results
@@ -78,6 +78,8 @@ ccc_index:
   last_indexed: {ccc_last_indexed from step-01b, or ~}
   status: {ccc_index_result from step-01b: "fresh"|"created"|"none"|"failed"}
   staleness_threshold_hours: 24
+  file_count: {ccc_file_count from step-01b, or ~}
+  exclude_patterns: {ccc_exclude_patterns from step-01b, or []}
 
 # CCC index registry (tracks which source paths have been indexed for skill workflows)
 # PRESERVE existing entries on re-runs — see Note below
@@ -88,7 +90,7 @@ ccc_index_registry: {preserved from existing forge-tier.yaml, or [] if first run
 qmd_collections: {preserved from existing forge-tier.yaml, or [] if first run}
 ```
 
-**Note on re-runs:** The `qmd_collections`, `ccc_index_registry` arrays, and `staleness_threshold_hours` value must be preserved across re-runs. Before overwriting forge-tier.yaml, read these existing values and re-inject them into the new write. These values are populated by create-skill workflows or customized by users and must not be reset.
+**Note on re-runs:** The `qmd_collections`, `ccc_index_registry` arrays, and `staleness_threshold_hours` value must be preserved across re-runs. Before overwriting forge-tier.yaml, read these existing values and re-inject them into the new write. These values are populated by create-skill workflows or customized by users and must not be reset. Note: `exclude_patterns` is NOT preserved — it is always written fresh from `{ccc_exclude_patterns}` computed by step-01b.
 
 **This file is ALWAYS overwritten** on every run — it reflects current tool state.
 
@@ -150,7 +152,7 @@ ONLY WHEN forge-tier.yaml has been written successfully and preferences.yaml exi
 
 ### ✅ SUCCESS:
 
-- forge-tier.yaml written with accurate tool booleans (including ccc), tier, timestamp, ccc_index state, and preserved qmd_collections/ccc_index_registry arrays
+- forge-tier.yaml written with accurate tool booleans (including ccc), tier, timestamp, ccc_index state (including exclude_patterns), and preserved qmd_collections/ccc_index_registry arrays
 - preferences.yaml exists (created with defaults on first run, preserved on re-run)
 - forge-data/ directory exists (created or pre-existing)
 - Auto-proceeded to step-03

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

@@ -139,6 +139,8 @@ This helps the merge step (section 4) prioritize which changes are most likely t
 
 CCC failures: skip ranking silently, all changes treated equally.
 
+**Note on remote sources:** If `source_root` is an ephemeral clone (remote source), the clone path is not indexed by CCC. The search will return empty results and semantic ranking will be skipped. This is expected — deferred CCC indexing is implemented in create-skill step-03 but not in update-skill. All changes are treated equally for remote sources.
+
 **IF `tools.ccc` is false:** Skip this section silently.
 
 ### 3. Deep Tier QMD Enrichment (Conditional)