bmad-module-skill-forge 0.4.0 → 0.6.0

package/README.md

@@ -89,7 +89,7 @@ See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/
 
 - **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Installation, prerequisites, and your first skill
 - **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Plain-English definitions of all key terms
-- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/architecture/)** — Architecture, capability tiers, output format, and design decisions
+- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Architecture, capability tiers, output format, and design decisions
 - **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 10 workflows with commands and connection diagrams
 - **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the AI agent that runs all SKF workflows
 - **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios, tips, and troubleshooting
@@ -102,8 +102,9 @@ SKF builds on these excellent open-source tools:
 |--------------------------------------------------------------|--------------------------------------------------------------------|
 | [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard                         |
 | [GitHub CLI](https://cli.github.com/)                        | Source code access and repository intelligence (all tiers)         |
-| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Deep tiers)            |
+| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Forge+/Deep tiers)     |
 | [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)     | MCP server for memory-efficient AST queries (recommended)          |
+| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file discovery pre-ranking (Forge+ tier)  |
 | [QMD](https://github.com/tobi/qmd)                           | Local hybrid search engine for knowledge indexing (Deep tier)      |
 | [skill-check](https://github.com/thedaviddias/skill-check)   | Skill validation, auto-fix, quality scoring, and security scanning |
 | [Snyk Agent Scan](https://github.com/snyk/agent-scan)   | Security scanning for prompt injection and data exposure (optional) |

package/docs/agents.md

@@ -22,10 +22,13 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 **Key Capabilities:**
 - AST analysis via ast-grep for structural truth
+- Semantic code discovery via cocoindex-code for intelligent file pre-ranking
 - QMD knowledge search for temporal context and evidence
 - agentskills.io specification compliance and validation
 - GitHub source navigation and package-to-repo resolution
 - Cross-knowledge synthesis for stack skills and integration patterns
+- Skill authoring best practices enforcement (third-person voice, consistent terminology, discovery optimization)
+- Source-derived scripts and assets extraction with provenance tracking
 
 **Workflow-Driven Modes:**
 

package/docs/concepts.md

@@ -31,27 +31,29 @@ Provenance means every instruction in a skill traces back to where it came from.
 
 ---
 
-## Confidence Tiers (T1/T2/T3)
+## Confidence Tiers (T1/T1-low/T2/T3)
 
 Each piece of information in a skill carries a confidence level based on where it came from:
 
 - **T1 — AST extraction:** Pulled directly from source code via AST parsing. This is structural truth — the function signature actually exists in the code right now.
+- **T1-low — Source reading:** Found by reading source files directly without AST parsing. The location is correct but the type signature may be inferred. Produced by Quick tier and by Forge/Deep when ast-grep cannot parse a specific file.
 - **T2 — Evidence:** Found in issues, PRs, changelogs, or documentation within the repository. Reliable context, but not as definitive as code.
 - **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked.
 
-**Example:** A function signature is T1. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
+**Example:** A function signature is T1. A source-read export without AST verification is T1-low. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
 
 ---
 
-## Capability Tiers (Quick/Forge/Deep)
+## Capability Tiers (Quick/Forge/Forge+/Deep)
 
 Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
 
-- **Quick** — GitHub CLI only. SKF reads source files and builds best-effort skills. Works in under a minute.
+- **Quick** — No tools required. SKF reads source files and builds best-effort skills. Works in under a minute. GitHub CLI used when available.
 - **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing for structural truth. Instructions are verified against the actual code structure.
-- **Deep** — Adds [QMD](https://github.com/tobi/qmd). SKF indexes knowledge for semantic search. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
+- **Forge+** — Adds [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code). SKF uses semantic code search to discover relevant source regions before AST extraction, improving coverage on large codebases.
+- **Deep** — Adds [GitHub CLI](https://cli.github.com) + [QMD](https://github.com/tobi/qmd). Requires ast-grep, gh, and QMD. SKF indexes knowledge for semantic search and performs GitHub repository exploration. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
 
-You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../architecture.md) for the full technical treatment.
+You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../how-it-works.md) for the full technical treatment.
 
 ---
 
@@ -94,3 +96,19 @@ Ferris switches between four modes depending on which workflow is active: Archit
 SKF's core principle: if an instruction can't be traced back to actual source code, it doesn't get included in the skill. This is the opposite of how most AI tools work — they generate plausible-sounding content from training data. SKF only includes what it can verify.
 
 This doesn't mean skills are perfect. Quick-tier skills read source files without AST verification, so they rely on best-effort extraction. But even Quick skills cite their sources, and no tier includes invented information.
+
+---
+
+## Scripts & Assets
+
+Skills can include executable scripts and static assets alongside the main SKILL.md instructions. Scripts handle deterministic operations (validation, setup, data processing) while assets provide templates, schemas, and configuration examples. Both are extracted from the source repository with provenance tracking — SKF copies them, it doesn't fabricate them.
+
+**Example:** A database library skill might include `scripts/migrate.sh` (copied from the library's `bin/` directory) and `assets/config-schema.json` (copied from the library's `schemas/` directory). Each file carries a `[SRC:file:L1]` citation and SHA-256 hash for drift detection.
+
+---
+
+## Best Practices
+
+SKF integrates skill authoring best practices from the Claude platform and community guidelines. Generated skills use third-person descriptions for reliable agent discovery, consistent terminology throughout, and appropriate degrees of freedom (prescriptive for fragile operations like database migrations, flexible for creative tasks like code reviews). These practices are enforced during compilation and verified during testing.
+
+**Example:** A skill description reads "Processes payments via REST API with token-based auth. NOT for: billing dashboards" — third-person voice, specific keywords, and negative triggers help agents select the right skill.

package/docs/examples.md

@@ -44,7 +44,25 @@ Provenance tags trace each instruction to its source:
 - `[EXT:url]` — sourced from external documentation
 - `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
 
-See [How It Works](../architecture.md) for the full output structure.
+See [How It Works](../how-it-works.md) for the full output structure.
+
+**Full skill directory structure:**
+
+```
+skills/cognee/
+├── SKILL.md              # What your agent reads
+├── context-snippet.md    # Compressed index for CLAUDE.md
+├── metadata.json         # Machine-readable provenance
+├── references/           # Progressive disclosure detail
+│   ├── api-core.md
+│   └── graph-types.md
+├── scripts/              # Executable utilities (when detected)
+│   └── setup-graphdb.sh
+└── assets/               # Templates and schemas (when detected)
+    └── config-schema.json
+```
+
+The `scripts/` and `assets/` directories appear only when the source repository contains them. Each file traces back to its source with provenance citations and SHA-256 hashes.
 
 ---
 
@@ -150,7 +168,7 @@ The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whateve
 
 ### Progressive Capability
 
-Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
+Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Forge+ (install cocoindex-code for semantic discovery), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
 
 ### Batch Operations
 
@@ -164,6 +182,14 @@ Stack skills focus on integration patterns. Individual skills focus on API surfa
 
 After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
 
+### Best Practices Built In
+
+Generated skills automatically follow authoring best practices: third-person descriptions for reliable agent discovery, consistent terminology, degrees-of-freedom matching (prescriptive for fragile operations, flexible for creative tasks), and table-of-contents headers in large reference files. Discovery testing recommendations are included in test reports.
+
+### Scripts & Assets
+
+If your source repo includes executable scripts (`scripts/`, `bin/`) or static assets (`templates/`, `schemas/`), SKF detects and packages them automatically with provenance tracking. Custom scripts you add to `scripts/[MANUAL]/` are preserved during updates — just like `<!-- [MANUAL] -->` markers in SKILL.md.
+
 ---
 
 ## Troubleshooting
@@ -182,6 +208,9 @@ An official skill already exists for this package. Consider installing it with `
 **Quick mode skills have lower confidence**
 Quick mode reads source without AST analysis. Install ast-grep to upgrade to Forge mode for structural truth (T1 confidence).
 
+**Want semantic discovery for large codebases?**
+Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) to unlock Forge+ mode. CCC indexes your codebase and pre-ranks files by semantic relevance before AST extraction, improving coverage on projects with 500+ files.
+
 ---
 
 ## Getting More Help

package/docs/getting-started.md

@@ -194,6 +194,17 @@ Your existing skill is now out of date. Audit detects the drift, Update regenera
 @Ferris TS    # Verify the update
 ```
 
+### I want scripts and assets included in my skills
+
+Your source repo has CLI tools, setup scripts, or config templates that agents should use. SKF detects and packages them automatically.
+
+```
+@Ferris BS    # Brief — set scripts_intent: detect
+@Ferris CS    # Create — scripts/ and assets/ auto-detected
+```
+
+Scripts from `scripts/`, `bin/`, and `tools/` directories are copied with provenance. Config templates and schemas from `assets/`, `templates/`, and `schemas/` are included. Custom files you add to `scripts/[MANUAL]/` survive updates.
+
 ---
 
 ## What's Next?

package/docs/{architecture.md → how-it-works.md}

@@ -35,7 +35,7 @@ Each workflow directory contains these files, and each has a specific job:
 | `data/*.md`               | Workflow-specific reference data — schemas, heuristics, rules, patterns                                             | Read by steps on demand                           |
 | `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
 | `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
-| `knowledge/*.md`          | 10 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
+| `knowledge/*.md`          | 12 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`, `ccc-bridge.md`) | Selectively read into context when a step directs |
 
 ```mermaid
 flowchart LR
@@ -96,7 +96,8 @@ SKF uses an additive tier model. Each tier is the previous tier plus one tool. Y
 |------|-------|-------------|
 | **Quick** | `gh_bridge` + `skill-check` + `tessl` | Source reading + spec validation + content quality review. Best-effort skills in under a minute. |
 | **Forge** | + `ast_bridge` | Structural truth. AST-verified signatures. Co-import detection. T1 confidence. |
-| **Deep** | + `qmd_bridge` | Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
+| **Forge+** | + `ccc_bridge` | Semantic discovery. CCC pre-ranks files by meaning before AST extraction. Better coverage on large codebases. |
+| **Deep** | + `gh_bridge` + `qmd_bridge` | Requires ast-grep + gh + QMD. Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
 
 Setup detects your installed tools and sets your tier automatically:
 
@@ -105,10 +106,10 @@ Setup detects your installed tools and sets your tier automatically:
 ```
 
 ```
-Forge initialized. Tools: gh, ast-grep, QMD. Tier: Deep. Ready.
+Forge initialized. Tools: gh, ast-grep, ccc, QMD. Tier: Deep. Ready.
 ```
 
-Don't have ast-grep or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
+Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
 
 ### Tier Override — Comparing Output Across Tiers
 
@@ -128,10 +129,13 @@ This is useful for comparing skill quality across tiers for the same target:
 # 2. Change to tier_override: Forge
 @Ferris CS                # recompile at Forge tier — compare output
 
-# 3. Reset to tier_override: ~ (auto-detect)
+# 3. Change to tier_override: Forge+
+@Ferris CS                # recompile with semantic discovery — compare coverage
+
+# 4. Reset to tier_override: ~ (auto-detect)
 ```
 
-Set `tier_override` to `Quick`, `Forge`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
+Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
 
 ---
 
@@ -142,7 +146,8 @@ Every claim in a generated skill carries a confidence tier that traces to its so
 | Tier | Source | Tool | What It Means |
 |------|--------|------|---------------|
 | **T1** | AST extraction | `ast_bridge` | Current code, structurally verified. Immutable for that version. |
-| **T2** | QMD evidence / source reading | `qmd_bridge` / `gh_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
+| **T1-low** | Source reading | `gh_bridge` | Source-read without AST verification. Location correct, signature may be inferred. |
+| **T2** | QMD evidence | `qmd_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
 | **T3** | External documentation | `doc_fetcher` | External, untrusted. Quarantined. |
 
 ### Temporal Provenance
@@ -165,11 +170,12 @@ Progressive disclosure controls how much context surfaces at each level:
 
 Your forge tier limits what authority claims a skill can make:
 
-| Forge Tier | AST? | QMD? | Max Authority | Accuracy Guarantee |
-|-----------|------|------|---------------|-------------------|
-| Quick | No | No | `community` | Best-effort |
-| Forge | Yes | No | `official` | Structural (AST-verified) |
-| Deep | Yes | Yes | `official` | Full (structural + contextual + temporal) |
+| Forge Tier | AST? | CCC? | QMD? | Max Authority | Accuracy Guarantee |
+|-----------|------|------|------|---------------|-------------------|
+| Quick | No | No | No | `community` | Best-effort |
+| Forge | Yes | No | No | `official` | Structural (AST-verified) |
+| Forge+ | Yes | Yes | No | `official` | Structural + semantic discovery |
+| Deep | Yes | opt. (enhances when installed) | Yes | `official` | Full (structural + contextual + temporal) |
 
 ---
 
@@ -184,14 +190,17 @@ skills/{name}/
 ├── SKILL.md              # Active skill (loaded on trigger)
 ├── context-snippet.md    # Passive context (compressed, always-on)
 ├── metadata.json         # Machine-readable provenance
-└── references/           # Progressive disclosure
-    ├── {function-a}.md
-    ├── {function-b}.md
-    └── integrations/     # Stack skills only
-        ├── auth-db.md
-        └── pwa-auth.md
+├── references/           # Progressive disclosure
+│   ├── {function-a}.md
+│   └── {function-b}.md
+├── scripts/              # Executable automation (when detected in source)
+│   └── {script-name}.sh
+└── assets/               # Templates, schemas, configs (when detected in source)
+    └── {asset-name}.json
 ```
 
+The `scripts/` and `assets/` directories are optional — only created when the source repository contains executable scripts or static assets matching detection heuristics. Each file traces to its source via `[SRC:file:L1]` provenance citations with SHA-256 content hashes for drift detection. User-authored files go in `scripts/[MANUAL]/` or `assets/[MANUAL]/` subdirectories and are preserved during updates.
+
 ### SKILL.md Format
 
 Skills follow the [agentskills.io specification](https://agentskills.io/specification) with frontmatter:
@@ -199,9 +208,10 @@ Skills follow the [agentskills.io specification](https://agentskills.io/specific
 ```yaml
 ---
 name: payment-service
-version: 2.1.0
-description: Payment processing API skill — 23 verified functions
-author: org/payment-team
+description: >
+  Processes payments via REST API with token-based auth. Use when writing
+  payment integration code. NOT for: billing dashboards or reporting.
+  23 verified functions from github.com/org/payment-service.
 ---
 ```
 
@@ -233,11 +243,21 @@ Machine-readable provenance for every skill:
     "coverage": 1.0,
     "confidence_t1": 20,
     "confidence_t2": 3,
-    "confidence_t3": 0
-  }
+    "confidence_t3": 0,
+    "scripts_count": 1,
+    "assets_count": 1
+  },
+  "scripts": [
+    { "file": "scripts/validate.sh", "purpose": "Validates config schema", "confidence": "T1-low" }
+  ],
+  "assets": [
+    { "file": "assets/config-schema.json", "purpose": "Configuration JSON schema", "confidence": "T1-low" }
+  ]
 }
 ```
 
+`scripts` and `assets` arrays are optional — omitted entirely (not empty) when the source has no scripts or assets.
+
 ### Stack Skill Output
 
 Stack skills map how your dependencies interact — shared types, co-import patterns, integration points:
@@ -301,7 +321,7 @@ Export injects a managed section between markers:
 
 ## Tool Ecosystem
 
-### 6 Tools
+### 7 Tools
 
 | Tool | Wraps | Purpose |
 |------|-------|---------|
@@ -309,6 +329,7 @@ Export injects a managed section between markers:
 | **`skill-check`** | [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) | Validation + auto-fix (`check --fix`), quality scoring (0-100), security scan, split-body, diff comparison |
 | **`tessl`** | [tessl](https://tessl.io) | Content quality review, actionability scoring, progressive disclosure evaluation, AI judge with suggestions |
 | **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
+| **`ccc_bridge`** | cocoindex-code | Semantic code search, project indexing, file discovery pre-ranking |
 | **`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. |
 
@@ -319,6 +340,7 @@ When tools disagree, higher priority wins for instructions. Lower priority is pr
 | Priority | Source | Tool |
 |----------|--------|------|
 | 1 (highest) | AST extraction | `ast_bridge` |
+| 1b | CCC discovery (pre-ranking) | `ccc_bridge` |
 | 2 | QMD evidence | `qmd_bridge` |
 | 3 | Source reading (non-AST) | `gh_bridge` |
 | 4 | External documentation | `doc_fetcher` |
@@ -344,6 +366,8 @@ forge-data/{skill-name}/
 └── extraction-rules.yaml   # Language-specific ast-grep schema
 ```
 
+The `provenance-map.json` includes a `file_entries` array for script/asset file-level provenance (SHA-256 hashes, source paths) alongside the export-level `entries` array.
+
 `skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
 
 ---
@@ -396,7 +420,7 @@ src/
 │   └── README.md
 ├── knowledge/
 │   ├── skf-knowledge-index.csv
-│   └── *.md (10 fragments)
+│   └── *.md (12 fragments)
 └── workflows/
     ├── setup-forge/
     ├── analyze-source/

package/docs/index.md

@@ -17,7 +17,7 @@ hero:
 
 ## What does Skill Forge do?
 
-AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from.
+AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from. Generated skills can also include executable scripts and static assets extracted from the source repository, each with full provenance tracking.
 
 ## Quick Install
 
@@ -40,7 +40,7 @@ See the [Getting Started](./getting-started/) guide for full installation and us
 
 - **[Getting Started](./getting-started/)** — Installation, prerequisites, and your first skill
 - **[Concepts](./concepts/)** — Plain-English definitions of key terms (provenance, tiers, drift, and more)
-- **[How It Works](./architecture/)** — Architecture, capability model, output format, and design decisions
+- **[How It Works](./how-it-works/)** — Architecture, capability model, output format, and design decisions
 - **[Workflows](./workflows/)** — All 10 workflows with commands and connection diagrams
 - **[Agents](./agents/)** — Ferris: the AI agent that runs all SKF workflows
 - **[Examples](./examples/)** — Real-world scenarios, tips, and troubleshooting

package/docs/workflows.md

@@ -15,11 +15,11 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **Command:** `@Ferris SF`
 
-**Purpose:** Initialize forge environment, detect tools, set capability tier, verify QMD collection health.
+**Purpose:** Initialize forge environment, detect tools (ast-grep, ccc, gh, qmd), set capability tier, index project in CCC (Forge+), verify QMD collection health (Deep).
 
 **When to Use:** First time using SKF in a project. Run once per project.
 
-**Key Steps:** Detect tools → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
+**Key Steps:** Detect tools → CCC index check (Forge+) → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
 
 **Agent:** Ferris (Architect mode)
 
@@ -33,7 +33,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** Before `Create Skill` when you want maximum control over what gets compiled.
 
-**Key Steps:** Gather intent → Analyze target → Define scope → Write skill-brief.yaml
+**Key Steps:** Gather intent → Analyze target → Define scope → Scripts/assets intent → Write skill-brief.yaml
 
 **Agent:** Ferris (Architect mode)
 
@@ -47,7 +47,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After Brief Skill, or with an existing skill-brief.yaml.
 
-**Key Steps:** Load brief → Ecosystem check → AST extract → QMD enrich → Compile → Validate → Generate
+**Key Steps:** Load brief → Ecosystem check → AST extract → Scripts/assets detect → QMD enrich → Compile → Validate → Generate
 
 **Agent:** Ferris (Architect mode)
 
@@ -61,7 +61,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After source code changes when an existing skill needs updating.
 
-**Key Steps:** Load existing → Detect changes → Re-extract → Merge (preserve MANUAL) → Validate → Write
+**Key Steps:** Load existing → Detect changes (incl. scripts/assets) → Re-extract → Merge (preserve MANUAL) → Validate → Write
 
 **Agent:** Ferris (Surgeon mode)
 
@@ -119,7 +119,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** To check if a skill has fallen out of date with its source code.
 
-**Key Steps:** Load skill → Re-index source → Structural diff → Semantic diff (Deep) → Classify severity → Report
+**Key Steps:** Load skill → Re-index source → Structural diff → Script/asset drift → Semantic diff (Deep) → Classify severity → Report
 
 **Agent:** Ferris (Audit mode)
 

package/package.json

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

package/src/agents/forger.agent.yaml

@@ -15,7 +15,7 @@ agent:
       Skill compilation specialist who transforms code repositories, documentation, and developer discourse into verified agent skills.
       Manages the full lifecycle: source analysis, skill briefing, AST-backed compilation,
       integrity testing, and ecosystem-ready export across progressive capability tiers
-      (Quick/Forge/Deep).
+      (Quick/Forge/Forge+/Deep).
 
     identity: |
       The forge master — a precision-focused craftsman who works through four modes:

package/src/forger/forge-tier.yaml

@@ -6,8 +6,24 @@ tools:
   ast_grep: ~
   gh_cli: ~
   qmd: ~
+  ccc: ~
+  security_scan: ~
 
 # Capability tier (derived from tool availability)
-# Quick = no tools required | Forge = + ast-grep | Deep = + ast-grep + gh + QMD
+# Quick = no tools | Forge = + ast-grep | Forge+ = + ast-grep + ccc | Deep = + ast-grep + gh + QMD
 tier: ~
 tier_detected_at: ~
+
+# CCC semantic index state (managed by setup-forge and extraction workflows)
+ccc_index:
+  indexed_path: ~
+  last_indexed: ~
+  status: "none"
+  staleness_threshold_hours: 24
+
+# CCC index registry (tracks which source paths have been indexed for skill workflows)
+ccc_index_registry: []
+
+# QMD collection registry (populated by create-skill, consumed by audit/update-skill)
+# Each entry tracks a QMD collection created during skill workflows
+qmd_collections: []

package/src/forger/preferences.yaml

@@ -2,7 +2,7 @@
 # Created by setup-forge workflow on first run
 # Edit this file to customize Ferris behavior
 
-# Override detected tier (set to Quick, Forge, or Deep to force a tier)
+# Override detected tier (set to Quick, Forge, Forge+, or Deep to force a tier)
 tier_override: ~
 
 # Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)

package/src/knowledge/agentskills-spec.md

@@ -36,7 +36,9 @@ description: >
 
 **Frontmatter constraints:**
 - `name`: 1-64 characters, lowercase alphanumeric + hyphens, must match parent directory name
+  - **Naming convention:** Prefer gerund form (verb + -ing) for clarity: `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`. Noun phrases (`pdf-processing`) and action-oriented forms (`process-pdfs`) are acceptable alternatives. Avoid vague names (`helper`, `utils`, `tools`).
 - `description`: 1-1024 characters, trigger-optimized for agent matching
+  - **MUST use third-person voice.** The description is injected into the system prompt; inconsistent point-of-view causes discovery problems. Write "Processes Excel files and generates reports" — never "I can help you process Excel files" or "You can use this to process Excel files."
 
 **Body:** Free-form markdown — no structural restrictions, but Skill Forge follows a consistent section order (see skill-sections.md in create-skill/data/).
 
@@ -52,6 +54,8 @@ skill-name/
 
 All subdirectories are exactly one level deep. Files are loaded on demand when SKILL.md directs — never automatically.
 
+Scripts and assets extracted by Skill Forge inherit provenance from their source repository. Each file receives a `[SRC:{source_path}:L1]` citation (T1-low confidence) and a SHA-256 content hash for drift detection. Scripts must follow the quality principles in the Script Quality section below. Assets are static files loaded on demand — agents use them as directed by SKILL.md instructions.
+
 ## Progressive Disclosure Model
 
 The format implements a three-phase loading model:
@@ -141,6 +145,24 @@ the user's configuration against the expected structure.
 - Line count is a guideline — exceeding 500 lines produces a warning
 - Path validation prevents broken references in the published skill
 
+## MCP Tool References
+
+If a skill references MCP (Model Context Protocol) tools, always use fully qualified names to avoid "tool not found" errors: `ServerName:tool_name` (e.g., `BigQuery:bigquery_schema`, `GitHub:create_issue`). Without the server prefix, agents may fail to locate the tool when multiple MCP servers are available.
+
+## Script Quality
+
+Skills that include executable scripts in `scripts/` must follow these principles:
+
+- **Solve, don't punt.** Scripts handle errors explicitly rather than failing and leaving the agent to figure it out. Provide fallback behavior, descriptive error messages, and recovery paths.
+- **No voodoo constants.** Every magic number or configuration value must be justified with a comment explaining why that value was chosen. If you don't know the right value, the agent won't either.
+- **Descriptive error output.** Write error messages to stdout/stderr that enable agents to self-correct without user intervention (e.g., "Field 'signature_date' not found. Available fields: customer_name, order_total").
+
+## Development Methodology
+
+- **Evaluation-driven development.** Define 2-3 concrete use cases and realistic test prompts before building the skill. Build evaluations before writing extensive documentation — this ensures the skill solves real problems rather than documenting imagined ones.
+- **Realistic test prompts.** Test with prompts the way real users actually talk — with typos, casual abbreviations, and incomplete context. A skill tested only with clean prompts will break in unexpected ways in production.
+- **Iterative refinement.** Observe how agents navigate and use the skill. Watch for unexpected exploration paths, missed references, overreliance on certain sections, and ignored content. Iterate based on observed behavior, not assumptions.
+
 ## Anti-Patterns
 
 - Writing skills as documentation (README-style) instead of procedural agent instructions
@@ -148,6 +170,9 @@ the user's configuration against the expected structure.
 - Vague descriptions ("helps with databases") — descriptions must be specific and trigger-optimized
 - Including redundant content that duplicates what the agent already knows (standard language features, basic CLI commands)
 - Bundling large library code inside skills — skills reference existing tools, not replace them
+- Time-sensitive instructions ("If before August 2025, use the old API") — use versioned sections instead
+- Offering too many tool/library options without a clear default — provide one recommended approach with escape hatches for edge cases
+- Inconsistent terminology — mixing synonyms ("API endpoint", "URL", "route") confuses agent execution
 
 ## Related Fragments