bmad-module-skill-forge 0.7.3 → 0.8.0

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)