bmad-module-skill-forge 0.7.0 → 0.7.1

package/docs/how-it-works.md

@@ -332,6 +332,8 @@ Export injects a managed section between markers:
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
 | **`doc_fetcher`** | Environment web tools | Remote documentation fetching for T3-confidence content. Tool-agnostic — uses whatever web fetching is available (Firecrawl, WebFetch, curl, etc.). Output quarantined as T3. |
 
+Bridge names are **conceptual interfaces** used throughout workflow steps. Each bridge resolves to concrete MCP tools, CLI commands, or fallback behavior depending on the IDE environment. See [`src/knowledge/tool-resolution.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/knowledge/tool-resolution.md) for the complete resolution table.
+
 ### Conflict Resolution
 
 When tools disagree, higher priority wins for instructions. Lower priority is preserved as annotations:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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

@@ -2,7 +2,7 @@
 
 ## Principle
 
-`ccc_bridge.*` references in workflow steps are **conceptual interfaces**, not callable functions. They describe a semantic code discovery operation to perform. Use the `ccc` MCP server tools (when available) or `ccc` CLI commands to execute these operations. See the TOOL/SUBPROCESS FALLBACK rule — if ccc is unavailable, the calling step falls back to direct ast-grep or source reading without ccc pre-discovery.
+`ccc_bridge.*` references in workflow steps are **conceptual interfaces**, not callable functions. They describe a semantic code discovery operation to perform. Use the `ccc` MCP server tools (when available) or `ccc` CLI commands to execute these operations. See the TOOL/SUBPROCESS FALLBACK rule — if ccc is unavailable, the calling step falls back to direct ast-grep or source reading without ccc pre-discovery. For the complete bridge-to-tool resolution table covering all IDE environments, see [tool-resolution.md](tool-resolution.md).
 
 ## Rationale
 
@@ -103,6 +103,7 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 
 ## Related Fragments
 
+- [tool-resolution.md](tool-resolution.md) — canonical bridge-to-tool and subprocess-to-tool mapping per IDE
 - [progressive-capability.md](progressive-capability.md) — Forge+ tier definition and positive framing
 - [confidence-tiers.md](confidence-tiers.md) — why ccc does not create a new confidence tier
 - [qmd-registry.md](qmd-registry.md) — the parallel but separate registry for QMD collections

package/src/knowledge/overview.md

@@ -31,6 +31,7 @@ With knowledge files:
 | [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
 | [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
 | [ccc-bridge.md](ccc-bridge.md)                             | ccc_bridge interface, indexing lifecycle, Forge+ discovery-before-extraction | SF, AN, CS, SS, US, AS             |
+| [tool-resolution.md](tool-resolution.md)                   | Bridge-to-tool and subprocess-to-tool mapping per IDE environment | CS, QS, SS, US, AS, AN, BS, RA     |
 | [architecture-verification.md](architecture-verification.md) | Pre-code verification pipeline, integration verdicts, iteration loop | VS, RA, SS                        |
 | [doc-fetcher.md](doc-fetcher.md)                           | T3 external documentation fetching, quarantine rules, tool-agnostic | CS, QS                             |
 | [split-body-strategy.md](split-body-strategy.md)           | Selective vs full split-body, detection pattern, agent accuracy   | CS, QS, US, TS, EX                |

package/src/knowledge/progressive-capability.md

@@ -84,6 +84,8 @@ Deep:   "Full intelligence pipeline — AST verification plus GitHub exploration
 - **Forge+:** Identical extraction to Forge, plus ccc semantic pre-discovery narrows the file set before ast-grep runs. For large codebases, `ccc_bridge.search()` produces a ranked candidate list. ast-grep operates on that list rather than the full tree. All results remain T1 (AST-verified) — ccc is upstream, not in the extraction chain.
 - **Deep:** Identical extraction to Forge, plus QMD enrichment in a separate step. T2 annotations layer on top of the T1 base without replacing it.
 
+*Bridge names (`gh_bridge`, `ast_bridge`, `ccc_bridge`, `qmd_bridge`) are conceptual interfaces. See [tool-resolution.md](tool-resolution.md) for concrete tool resolution per IDE.*
+
 **Key Points:**
 - Extraction quality increases with tier, but every tier produces complete output
 - Forge and Deep share the same extraction core — Deep adds enrichment, not better parsing

package/src/knowledge/qmd-registry.md

@@ -21,7 +21,7 @@ The progressive registry solves all three by indexing **curated workflow artifac
 | Role | Workflow | Responsibility |
 | --- | --- | --- |
 | **Producer** | brief-skill, create-skill | Creates QMD collections from workflow artifacts and registers them in forge-tier.yaml |
-| **Consumer** | audit-skill, update-skill | Reads the registry, discovers collections by skill name and type, queries via qmd_bridge |
+| **Consumer** | audit-skill, update-skill, create-stack-skill | Reads the registry, discovers collections by skill name and type, queries via qmd_bridge (see [tool-resolution.md](tool-resolution.md) for concrete resolution) |
 | **Janitor** | setup-forge | Cross-references live QMD collections against the registry, cleans orphans and stale entries |
 
 ### Registry Schema

package/src/knowledge/skf-knowledge-index.csv

@@ -12,3 +12,4 @@ qmd-registry,QMD Collection Registry,"Progressive registry architecture — prod
 doc-fetcher,Doc Fetcher,"T3 external documentation — tool-agnostic URL fetching, quarantine rules, conflict resolution","doc-fetcher,t3,external,documentation,quarantine",extended,knowledge/doc-fetcher.md
 architecture-verification,Architecture Verification,"Pre-code verification pipeline — VS/RA/SS-compose lifecycle, integration verdicts, coverage analysis, iteration loop","architecture,verification,stack,feasibility,integration,vs,ra,ss,compose",core,knowledge/architecture-verification.md
 split-body-strategy,Split-Body Strategy,"Selective split guidance — detection pattern, recommended approach, impact on tessl scores and snippet anchors","split-body,selective-split,references,body-size",core,knowledge/split-body-strategy.md
+tool-resolution,Tool Resolution,"Bridge-to-tool and subprocess-to-tool mapping — ast_bridge, ccc_bridge, qmd_bridge, gh_bridge resolution per IDE, subprocess Pattern 1-4 definitions","bridge,tools,resolution,subprocess,mcp,cli,ide",core,knowledge/tool-resolution.md

package/src/knowledge/tool-resolution.md

@@ -0,0 +1,55 @@
+# Tool Resolution
+
+Bridge names (`ast_bridge`, `ccc_bridge`, `qmd_bridge`, `gh_bridge`) and subprocess patterns (Pattern 1–4) used throughout SKF workflows are **conceptual interfaces**, not callable functions. This document provides the canonical mapping from abstract names to concrete tools per IDE environment.
+
+## Bridge Resolution Table
+
+| Bridge       | Operation                        | Claude Code                                                      | Cursor         | CLI                                                | Fallback                         |
+|--------------|----------------------------------|------------------------------------------------------------------|----------------|----------------------------------------------------|----------------------------------|
+| `ast_bridge` | `scan_definitions()`             | `mcp__ast-grep__find_code` or `mcp__ast-grep__find_code_by_rule` | ast-grep MCP   | `sg run` / `ast-grep -p`                           | Source reading (T1-low)          |
+| `ast_bridge` | `detect_co_imports()`            | `mcp__ast-grep__find_code_by_rule` with co-import YAML rule      | ast-grep MCP   | `ast-grep -p 'import $$$' --json=stream`           | grep-based co-import count       |
+| `ccc_bridge` | `search(query, root, top_k)`     | `/ccc` skill search                                              | ccc MCP server | `ccc search "{query}" --path {root} --top {top_k}` | Skip silently                    |
+| `ccc_bridge` | `ensure_index(root)`             | `/ccc` skill indexing                                            | ccc MCP server | `ccc init` + `ccc index {root}`                    | Skip silently                    |
+| `ccc_bridge` | `status()`                       | `/ccc` skill status                                              | ccc MCP server | `ccc --help` + `ccc doctor`                        | Unavailable = `tools.ccc: false` |
+| `qmd_bridge` | `search(query)`                  | `mcp__plugin_qmd-plugin_qmd__search`                             | qmd MCP server | `qmd search "{query}"`                             | Skip enrichment                  |
+| `qmd_bridge` | `vector_search(query)`           | `mcp__plugin_qmd-plugin_qmd__vector_search`                      | qmd MCP server | `qmd vector_search "{query}"`                      | Use BM25 search only             |
+| `gh_bridge`  | `list_tree(owner, repo, branch)` | `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1`     | gh CLI         | `gh api ...`                                       | Direct file listing if local     |
+| `gh_bridge`  | `read_file(owner, repo, path)`   | `gh api repos/{owner}/{repo}/contents/{path}`                    | gh CLI         | `gh api ...`                                       | Direct file read if local        |
+
+## Subprocess Pattern Definitions
+
+Workflow steps reference "subprocess" execution with numbered patterns. These map to concrete mechanisms per IDE:
+
+| Pattern                                | Purpose                                               | Claude Code                                                          | Cursor                            | CLI                                |
+|----------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------|-----------------------------------|------------------------------------|
+| **Pattern 1** (grep/search)            | Search across files for imports, co-imports           | Grep tool or Bash with `rg`                                          | Built-in search                   | `grep` / `rg`                      |
+| **Pattern 2** (per-file deep analysis) | Deep analysis of individual files or units            | Agent tool (sequential per unit)                                     | Sequential analysis               | Per-unit script                    |
+| **Pattern 3** (data operations)        | QMD queries, severity classification, data transforms | Main thread (Read + process)                                         | Main thread                       | Script                             |
+| **Pattern 4** (parallel execution)     | Parallel per-library extraction, parallel diffing     | Agent tool with multiple parallel calls or `run_in_background: true` | Parallel requests (IDE-dependent) | `xargs -P` or background processes |
+
+### max_parallel_generation
+
+Referenced by Pattern 4 steps. Defines the maximum concurrent subprocess spawns:
+
+| Environment | Recommended Value                | Notes                                                                 |
+|-------------|----------------------------------|-----------------------------------------------------------------------|
+| Claude Code | 3–5                              | Concurrent Agent tool calls; higher values may cause context pressure |
+| Cursor      | IDE-dependent                    | Follow Cursor's agent concurrency limits                              |
+| CLI         | CPU core count or user-specified | Use `xargs -P {n}` or equivalent                                      |
+
+## Resolution Protocol
+
+When a workflow step references a bridge name or subprocess pattern:
+
+1. **Identify** the bridge name (`ast_bridge`, `ccc_bridge`, etc.) or pattern number (Pattern 1–4)
+2. **Check tool availability** in `{sidecar_path}/forge-tier.yaml` → `tools.*` section
+3. **Resolve** using the tables above — use the first available option in priority order: MCP tool → CLI command → Fallback
+4. **Apply fallback** if no resolution is available — fallbacks are always defined and never block the workflow
+5. **Log degradation** when falling back — note the reason in context for the evidence report
+
+## Related Fragments
+
+- [ccc-bridge.md](ccc-bridge.md) — CCC semantic discovery interface and lifecycle
+- [progressive-capability.md](progressive-capability.md) — Quick/Forge/Forge+/Deep tier philosophy
+- [confidence-tiers.md](confidence-tiers.md) — T1/T1-low/T2/T3 trust model and citation formats
+- [qmd-registry.md](qmd-registry.md) — QMD collection producer/consumer/janitor architecture

package/src/workflows/analyze-source/steps-c/step-04-map-and-detect.md

@@ -33,7 +33,7 @@ To analyze each qualifying unit's export surface and import graph, detect cross-
 
 ### Step-Specific Rules:
 
-- 🎯 Use subprocess optimization (Pattern 2) — per-unit analysis for export mapping
+- 🎯 Use subprocess optimization (Pattern 2 — per-unit deep analysis): In Claude Code, use Agent tool for each unit sequentially. In CLI, use a per-unit script. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 💬 DO NOT BE LAZY — For EACH qualifying unit, perform thorough export surface analysis
 - 🚫 FORBIDDEN to make recommendations in this step (that's step 05)
 - 📋 Tier-aware depth: Quick (file-level exports), Forge (AST export analysis), Deep (AST + semantic relationships)
@@ -82,7 +82,7 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
    - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
    - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
    - **Forge+ tier:** All Forge analysis plus:
-     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` to discover semantically relevant files beyond directory scan
+     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) — to discover semantically relevant files beyond directory scan
      - Merge CCC-discovered files with scoped file list — files from CCC that are within the unit's directory are added to the analysis queue
      - Record CCC signals in per-unit findings: top 3 CCC-ranked file names (or "—" if no ccc results)
    - **Deep tier:** All Forge analysis plus:

package/src/workflows/audit-skill/steps-c/step-01-init.md

@@ -83,7 +83,7 @@ Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
 
 **If found:**
 - Extract tier level: Quick / Forge / Forge+ / Deep
-- Extract available tools: gh_bridge, ast_bridge, qmd_bridge
+- Extract available tools: gh_bridge, ast_bridge, qmd_bridge — see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for concrete tool resolution per IDE
 
 **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.
 

package/src/workflows/audit-skill/steps-c/step-02-re-index.md

@@ -78,6 +78,8 @@ Based on forge tier detected in Step 01:
 - Query qmd_bridge for temporal context: when exports were added, modification history, usage frequency
 - Confidence labels: T1 for structural, T2 for temporal context
 
+**Tool resolution:** `gh_bridge` → `gh api` commands or direct file I/O if local. `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`search`, `vector_search`) or `qmd` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 ### 2. Scan Source Files
 
 Identify all source files in the source directory that contain public exports.
@@ -148,7 +150,7 @@ Skip this section. Temporal context requires Deep tier.
 
 For each export in the skill baseline that was NOT found at its recorded file path during re-extraction (potential "deleted" export):
 
-1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` to find candidate current locations
+1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` — **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{export_name}" --path {source_root} --top 5` (CLI) — to find candidate current locations
 2. If CCC returns files containing the export name:
    - Run ast-grep verification on each candidate file
    - If verified at a new location: reclassify from "deleted" to "moved" with the new file:line reference

package/src/workflows/audit-skill/steps-c/step-03-structural-diff.md

@@ -33,7 +33,7 @@ Compare the original provenance map extractions from create-skill against the cu
 - 🎯 Focus only on structural comparison — added/removed/changed exports
 - 🚫 FORBIDDEN to classify severity — that happens in Step 05
 - 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
-- 💬 Use subprocess Pattern 4 (parallel execution) when available to compare export categories simultaneously
+- 💬 Use subprocess Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, compare categories sequentially in main thread
 
 ## EXECUTION PROTOCOLS:
@@ -70,7 +70,7 @@ Normalize both sets for comparison:
 
 ### 2. Detect Added Exports
 
-**Launch subprocess (Pattern 4 — parallel execution):**
+**Launch subprocess (Pattern 4 — parallel execution):** In Claude Code, use multiple parallel Agent tool calls. In CLI, use `xargs -P` or equivalent.
 
 Find exports that exist in current scan but NOT in provenance map.
 

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

@@ -33,7 +33,7 @@ Compare QMD knowledge context between the original skill creation and current st
 - 🎯 Focus only on semantic/meaning-level changes via QMD context
 - 🚫 FORBIDDEN to classify severity — that happens in Step 05
 - 🚫 FORBIDDEN to repeat structural findings from Step 03
-- 💬 Use subprocess Pattern 3 (data operations) when available for QMD queries
+- 💬 Use subprocess Pattern 3 (data operations — main thread Read + process in Claude Code, script in CLI) when available for QMD queries. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, query QMD in main thread
 - 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append skip notice only
 

package/src/workflows/audit-skill/steps-c/step-05-severity-classify.md

@@ -34,7 +34,7 @@ Grade every drift finding from Steps 03 and 04 by severity level (CRITICAL/HIGH/
 - 🎯 Focus only on classifying severity of existing findings
 - 🚫 FORBIDDEN to discover new drift items — only classify what Steps 03-04 found
 - 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
-- 💬 Use subprocess Pattern 3 (data operations) to load severity rules and classify
+- 💬 Use subprocess Pattern 3 (data operations — main thread Read + process in Claude Code, script in CLI) to load severity rules and classify. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, load rules and classify in main thread
 
 ## EXECUTION PROTOCOLS:

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

@@ -135,7 +135,7 @@ Based on detected language, identify public API surface:
 
 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)`.
+Run `ccc_bridge.search("{repo_name} public API exports modules", source_path, top_k=10)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
 
 If results are returned, display:
 

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

@@ -28,7 +28,13 @@ 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.*`, `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.
+> **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. Resolve them as follows:
+> - `ast_bridge.*` → ast-grep MCP tools (`mcp__ast-grep__find_code`, `mcp__ast-grep__find_code_by_rule`) or `ast-grep` CLI
+> - `qmd_bridge.*` → QMD MCP tools (`mcp__plugin_qmd-plugin_qmd__search`, `vector_search`) or `qmd` CLI
+> - `ccc_bridge.*` → `/ccc` skill (Claude Code), ccc MCP server (Cursor), or `ccc` CLI
+> - `gh_bridge.*` → `gh api` commands or direct file I/O for local sources
+>
+> See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for the complete resolution table. Also see the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
 

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

@@ -135,4 +135,4 @@ Update the working version in context to the source version. Record the mismatch
 
 **If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
 
-**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` for the primary version file of the detected language. If the read fails, keep `brief.version`.
+**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` — resolved as `gh api repos/{owner}/{repo}/contents/{version_file}` or direct file read if local (see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)) — for the primary version file of the detected language. If the read fails, keep `brief.version`.

package/src/workflows/create-skill/data/tier-degradation-rules.md

@@ -20,7 +20,7 @@ When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tie
 - The extraction step MUST warn the user explicitly before degrading
 - **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
 - **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
-- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge — resolved as `gh api` commands or direct file I/O; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md))
 - All results labeled T1-low with `[SRC:...]` citations
 - The degradation reason is recorded in the evidence report
 

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

@@ -114,7 +114,7 @@ Halt with specific error: "Brief validation failed: missing required field `{fie
 **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)`
+- Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - If branch not specified, detect default branch
 - Store resolved: owner, repo, branch, file tree
 

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

@@ -75,6 +75,8 @@ Read `ccc_index` from forge-tier.yaml:
 - If `ccc_index.status` is `"stale"`: display brief note — "CCC index is stale — discovery results may miss recent changes." Continue to section 3.
 - If `ccc_index.status` is `"none"` or `"failed"`: attempt lazy indexing via `ccc_bridge.ensure_index(source_root)`. If indexing succeeds, continue to section 3. If indexing fails, set `{ccc_discovery: []}` and auto-proceed to section 5.
 
+**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `ccc init` + `ccc index {source_root}` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 ### 3. Construct Semantic Query
 
 Build the discovery query from the brief data:
@@ -91,6 +93,8 @@ Where:
 
 Run `ccc_bridge.search(query, source_root, top_k=20)`:
 
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{query}" --path {source_root} --top 20` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **If search succeeds:**
 
 Store results as `{ccc_discovery: [{file, score, snippet}]}` in context.

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

@@ -92,6 +92,8 @@ 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}]`
 
+**Tool resolution for gh_bridge:** Use `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` for list_tree, `gh api repos/{owner}/{repo}/contents/{path}` for read_file. If source is local, use direct file listing/reading instead. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **Forge/Forge+/Deep Tier (AST available):**
 
 **CCC Discovery Integration (Forge+ and Deep with ccc only):**
@@ -115,6 +117,8 @@ If `{ccc_discovery}` is empty or not in context: proceed with existing file orde
 5. Build extraction rules YAML data for reproducibility
 6. Confidence: All results T1 — `[AST:{file}:L{line}]`
 
+**Tool resolution for ast_bridge:** Use ast-grep MCP tools (`mcp__ast-grep__find_code`, `mcp__ast-grep__find_code_by_rule`) as specified in the AST Extraction Protocol above, or `ast-grep` CLI. For `detect_co_imports`, use `find_code_by_rule` with a co-import YAML rule scoped to the libraries list. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **If AST tool is unavailable at Forge/Deep tier** (see `{tierDegradationRulesData}` for full rules):
 
 ⚠️ **Warn the user explicitly:** "AST tools are unavailable — extraction will use source reading (T1-low). Run [SF] Setup Forge to detect and configure AST tools for T1 confidence."

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

@@ -96,6 +96,8 @@ For each function, derive the **module context** from the extraction inventory's
 
 4. **Semantic migration context:** `qmd_bridge.vector_search("{module_context} {function_name} migration deprecated")` — adds semantic matches (synonyms, paraphrases) that BM25 keyword search may miss. Merge results with search #3, deduplicating by document ID. If `vector_search` fails (VRAM, GPU driver, model loading), discard silently — the BM25 results from search #3 provide baseline coverage.
 
+**Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` for BM25 search, `mcp__plugin_qmd-plugin_qmd__vector_search` for semantic search (Claude Code). Cursor: qmd MCP server. CLI: `qmd search "{query}"` / `qmd vector_search "{query}"`. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **For each QMD result:**
 
 - Create a T2 annotation: `[QMD:{collection}:{doc}]`

package/src/workflows/create-stack-skill/data/manifest-patterns.md

@@ -20,6 +20,28 @@
 3. Normalize names across ecosystems (e.g., `@scope/package` → `package`)
 4. Deduplicate across multiple manifests
 
+## Scan Exclusion Patterns
+
+When scanning for manifest files, ALWAYS exclude these directories from glob results:
+
+**Dependency/Vendor Directories:**
+- `node_modules/`
+- `.venv/` / `venv/` / `.env/`
+- `vendor/` (PHP Composer, Go modules)
+- `Pods/` (iOS CocoaPods)
+
+**Build Output Directories:**
+- `dist/` / `build/` / `out/`
+- `target/` (Rust, Java/Maven)
+- `__pycache__/`
+- `.next/` / `.nuxt/` / `.output/`
+
+**Hidden and VCS Directories:**
+- `.git/`
+- Any directory starting with `.` (except project root hidden config files like `.csproj`)
+
+**Monorepo Note:** For monorepo structures (e.g., `packages/*/package.json`), the depth 0-1 scan rule already limits scope. If monorepo manifest detection is needed at deeper levels, these exclusions become critical to prevent scanning dependency trees within each package.
+
 ## Filtering Rules
 
 - Exclude dev-only dependencies unless they appear in production imports
@@ -32,4 +54,4 @@
 For each dependency, count distinct files that import it:
 - Use grep patterns from Import Pattern column
 - Count unique file paths, not total import statements
-- Exclude test files, config files, and build artifacts from count
+- Exclude test files (`*/test/*`, `*_test.*`, `*.spec.*`, `*.test.*`), config files (`*.config.*`, `.eslintrc`, etc.), and build artifacts (`dist/`, `build/`, `node_modules/`, `target/`, `__pycache__/`) from count

package/src/workflows/create-stack-skill/steps-c/step-01-init.md

@@ -84,6 +84,8 @@ Extract:
 - **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step-05
 - **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
 
+See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for how each bridge name resolves to concrete tools per IDE environment.
+
 Report tool availability. If a tier-required tool is missing, downgrade tier and note:
 
 "**Tier adjusted:** {original_tier} → {adjusted_tier} — {missing_tool} unavailable."

package/src/workflows/create-stack-skill/steps-c/step-02-detect-manifests.md

@@ -99,10 +99,11 @@ Store the explicit list as `raw_dependencies` and skip to [Display Detection Sum
 
 Load `{manifestPatterns}` for supported ecosystem detection patterns.
 
-Scan the project root (depth 0-1) for manifest files:
+Scan the project root (depth 0-1) for manifest files, **excluding directories listed in the Scan Exclusion Patterns section of `{manifestPatterns}`**:
 
 - Search for each supported manifest filename
 - Record: file path, ecosystem type, file size
+- **Apply exclusion patterns** from `{manifestPatterns}` — skip `node_modules/`, `.venv/`, `vendor/`, `dist/`, `build/`, `target/`, `.git/`, and all hidden directories when globbing
 - Note any unusual structures (monorepo with multiple manifests, workspace configurations)
 
 **If no manifest files found:**

package/src/workflows/create-stack-skill/steps-c/step-03-rank-and-confirm.md

@@ -30,7 +30,7 @@ Count import frequency for each dependency across the codebase, rank by usage, a
 - 🎯 Focus on counting imports, ranking, and getting user confirmation
 - 🚫 FORBIDDEN to extract library documentation — that is step 04
 - 💬 Present data clearly so user can make informed scope decisions
-- 🎯 Use subprocess (Pattern 1 grep) for import counting when available
+- 🎯 Use subprocess (Pattern 1 — grep/search): In Claude Code, use the Grep tool or Bash with `rg`. In Cursor, use built-in search. In CLI, use `grep`/`rg` directly. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 
 ## EXECUTION PROTOCOLS:
 
@@ -80,6 +80,8 @@ For each dependency in `raw_dependencies`:
 
 **Launch a subprocess** that runs grep across all source files in the project to count import statements for each library. Return only the counts, not file contents.
 
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 Use ecosystem-appropriate import patterns:
 - JavaScript/TypeScript: `import .* from ['"]library`, `require\(['"]library`
 - Python: `import library`, `from library import`

package/src/workflows/create-stack-skill/steps-c/step-04-parallel-extract.md

@@ -27,7 +27,7 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 ### Step-Specific Rules:
 
-- 🎯 Extract per-library using Pattern 4 (parallel subprocess) when available
+- 🎯 Extract per-library using Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 💬 Each subprocess returns structured extraction, not raw file contents
 - 🚫 FORBIDDEN to analyze cross-library integrations — that is step 05
 - ⚙️ If parallel subprocess unavailable, extract libraries sequentially in main thread
@@ -105,14 +105,25 @@ For each library in `confirmed_dependencies`, determine extraction strategy base
 - Confidence: T1 (AST-verified structural extraction)
 
 **Deep Tier (adds to Forge):**
-- Use qmd_bridge for temporal usage evolution
-- Identify deprecated patterns and migration paths
-- Track API changes across project history
-- Confidence: T2 (QMD-enriched temporal context)
+- Perform all Forge tier extractions (T1)
+- Additionally: query existing QMD temporal collections for each library
+- Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`
+- For each library in `confirmed_dependencies`, search for a registry entry where `skill_name` matches the library name AND `type` is `"temporal"`
+- **If a matching temporal collection exists:**
+  - Query `qmd_bridge.search("{library_name} deprecated OR removed OR breaking change")` for deprecation context
+  - Query `qmd_bridge.search("{library_name} migration OR upgrade")` for migration patterns
+  - Query `qmd_bridge.search("{library_name} version issue OR bug OR workaround")` for version-specific warnings
+  - **Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` (Claude Code), qmd MCP server (Cursor), `qmd search "{query}"` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
+  - Classify each result as T2-past (historical) or T2-future (planned changes) per confidence-tiers.md
+  - Append temporal findings to the library's extraction as T2 annotations with `[QMD:{collection}:{doc}]` citations
+- **If no matching temporal collection found:**
+  - Log: "No temporal collection for {library_name}. T2 enrichment skipped."
+  - Continue with T1/T1-low extraction only
+- Confidence: T1 for structural (AST), T2 for temporal annotations (QMD-enriched)
 
 ### 2. Launch Parallel Extraction
 
-**Launch subprocesses in parallel** (max_parallel_generation) — one per confirmed library:
+**Launch subprocesses in parallel** (max_parallel_generation: 3–5 concurrent Agent tool calls in Claude Code, IDE-dependent in Cursor, CPU core count in CLI) — one per confirmed library:
 
 Each subprocess:
 1. Reads all files importing the library (from step 03 file lists)
@@ -129,7 +140,13 @@ Each subprocess:
   usage_patterns: ["pattern description with file:line"],
   confidence: "T1|T1-low|T2",
   files_analyzed: count,
-  warnings: []
+  warnings: [],
+  temporal: {
+    deprecated_exports: ["export_name — reason [QMD:collection:doc]"],
+    migration_notes: ["note [QMD:collection:doc]"],
+    version_warnings: ["warning [QMD:collection:doc]"],
+    t2_annotation_count: count
+  }
 }
 ```
 
@@ -161,6 +178,8 @@ For each library extraction:
 
 **Results:** {success_count}/{total_count} libraries extracted
 **Confidence distribution:** T1: {count}, T1-low: {count}, T2: {count}
+{If Deep tier:} **T2 enrichment:** {enriched_count}/{total_count} libraries had temporal collections available
+{If libraries without temporal > 0:} **Tip:** Run [CS] Create Skill at Deep tier for individual libraries to generate temporal collections, then re-run [SS] for full T2 enrichment.
 {If warnings:} **Warnings:** {warning_count} issues noted
 
 **Proceeding to integration detection...**"

package/src/workflows/create-stack-skill/steps-c/step-05-detect-integrations.md

@@ -29,7 +29,7 @@ Analyze co-import patterns between confirmed libraries to identify integration p
 
 ### Step-Specific Rules:
 
-- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep) subprocess
+- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep/search): In Claude Code, use the Grep tool or Bash with `rg`. In Cursor, use built-in search. In CLI, use `grep`/`rg` directly. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 🚫 FORBIDDEN to compile SKILL.md — that is step 06
 - 💬 Integration detection is the core differentiator of stack skills vs individual skills
 - ⚙️ If subprocess unavailable, perform grep operations in main thread
@@ -93,6 +93,8 @@ For each library pair (A, B):
 
 **Launch a subprocess** that greps across all source files to find files importing BOTH library A and library B. Return only file paths and import line numbers.
 
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **Subprocess returns:** `{pair: [A, B], co_import_files: [{path, line_A, line_B}], count: N}`
 
 **If subprocess unavailable:** Intersect the file lists from step 03 import counts for each pair.
@@ -105,6 +107,8 @@ If `tools.ccc` is true AND `ccc_index.status` is `"fresh"` or `"stale"` in forge
 
 For each library pair that has exactly 1 co-import file (below the 2-file threshold), run `ccc_bridge.search("{libA} {libB}", source_root, top_k=10)` to find files where the two libraries interact semantically — even without explicit import co-location. If CCC returns additional files where both libraries appear, add them to the pair's co-import candidate list and re-evaluate against the 2-file threshold.
 
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{libA} {libB}" --path {source_root} --top 10` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 For pairs that already qualify (2+ files), CCC is not needed for detection — but the CCC results may surface additional integration files for richer classification in section 3.
 
 CCC failures: skip augmentation silently, proceed with grep-only results.

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

@@ -86,9 +86,9 @@ The `ccc index` command auto-starts the daemon when needed. Proceed with indexin
 
 Attempt indexing anyway — errors will be caught below.
 
-Run:
+Run (CWD must be `{project-root}`):
 ```bash
-ccc init {project-root}
+ccc init
 ```
 
 **If init fails** (project may already be initialized): continue — this is not an error.
@@ -98,6 +98,8 @@ Then run:
 ccc index
 ```
 
+**Note:** `ccc index` can take several minutes on large codebases (1000+ files). Run with an extended timeout or in background mode. Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero.
+
 **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}}`

package/src/workflows/update-skill/steps-c/step-02-detect-changes.md

@@ -35,7 +35,7 @@ Compare current source code state against the provenance map to produce a comple
 - 🎯 Focus ONLY on detecting and classifying changes — do not extract or merge
 - 🚫 FORBIDDEN to modify any files — read-only change detection
 - 🚫 FORBIDDEN to re-extract content — that is step 03
-- 💬 Use subprocess optimization Pattern 4 for parallel comparison when available
+- 💬 Use subprocess Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, perform comparison sequentially in main thread
 
 ## EXECUTION PROTOCOLS:

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

@@ -101,6 +101,8 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 - QMD provides: usage patterns, historical context, related documentation
 - Confidence: T1 for structural, T2 for semantic enrichment
 
+**Tool resolution:** `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`mcp__plugin_qmd-plugin_qmd__search`, `vector_search`) or `qmd` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 ### 2. Extract Changed Files
 
 DO NOT BE LAZY — For EACH file in the change manifest with status MODIFIED, ADDED, or RENAMED, launch a subprocess that:
@@ -128,7 +130,7 @@ DO NOT BE LAZY — For EACH file in the change manifest with status MODIFIED, AD
 
 Before aggregating extraction results, use CCC to assess semantic significance of changes:
 
-1. Run `ccc_bridge.search("{skill_name}", source_root, top_k=15)` to get the skill's most semantically central files
+1. Run `ccc_bridge.search("{skill_name}", source_root, top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP (Cursor), `ccc search` (CLI) — to get the skill's most semantically central files
 2. Cross-reference the change manifest files with CCC results
 3. Files appearing in BOTH the change manifest AND CCC's top results are **semantically significant changes** — flag them for priority in the merge step
 4. Store `{ccc_significant_changes: [{file, score}]}` in context

package/src/workflows/update-skill/steps-c/step-05-validate.md

@@ -33,7 +33,7 @@ Validate the merged skill content against the agentskills.io specification, veri
 
 - 🎯 Focus ONLY on validation — do not fix issues (that's the user's choice)
 - 🚫 FORBIDDEN to modify merged content — validation is read-only
-- 💬 Launch parallel validation checks when subprocess available (Pattern 4)
+- 💬 Launch parallel validation checks when subprocess available (Pattern 4): In Claude Code, use multiple parallel Agent tool calls. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P`. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - ⚙️ If subprocess unavailable, perform checks sequentially in main thread
 
 ## EXECUTION PROTOCOLS: