bmad-module-skill-forge 0.4.0 → 0.6.0

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

@@ -134,9 +134,26 @@ Append temporal metadata to each export in the snapshot.
 Log: "No QMD extraction collection found for {skill_name}. Temporal enrichment skipped. Re-run [CS] Create Skill to generate the collection."
 Continue without T2 enrichment — this is not an error.
 
-**IF forge tier is Quick or Forge:**
+**IF forge tier is Quick, Forge, or Forge+:**
 Skip this section. Temporal context requires Deep tier.
 
+### 4b. CCC Rename Detection (Forge+ and Deep with ccc)
+
+**IF `tools.ccc` is true in forge-tier.yaml:**
+
+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
+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
+   - This reduces false-positive structural drift findings where exports were relocated, not removed
+3. If CCC returns no results or verification fails: keep the "deleted" classification
+
+CCC failures: skip rename detection silently, proceed with standard structural diff.
+
+**IF `tools.ccc` is false:** Skip this section silently.
+
 ### 5. Validate Extraction Completeness
 
 "**Extraction complete.**

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

@@ -108,6 +108,20 @@ For each changed export, record:
 - What changed (signature / type / location)
 - Confidence tier
 
+### 4b. Detect Script/Asset Drift
+
+**Only execute if provenance-map.json contains `file_entries`.**
+
+For each entry in `file_entries`:
+1. Locate the source file at the original `source_file` path
+2. Compute current SHA-256 content hash
+3. Compare against stored `content_hash`
+- CHANGED: hash mismatch → record as script/asset content drift
+- MISSING: source file no longer exists → record as removed
+- NEW: source contains files matching script/asset patterns not in `file_entries` → record as added
+
+Append results to the Structural Drift section as "### Script/Asset Drift ({count})".
+
 ### 5. Compile Structural Drift Section
 
 Append to {outputFile}:

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

@@ -1,6 +1,6 @@
 ---
 name: 'step-04-semantic-diff'
-description: 'Compare QMD knowledge context for meaning-level changes (Deep tier only, skip at Quick/Forge)'
+description: 'Compare QMD knowledge context for meaning-level changes (Deep tier only, skip at Quick/Forge/Forge+)'
 
 nextStepFile: './step-05-severity-classify.md'
 outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
@@ -10,7 +10,7 @@ outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
 
 ## STEP GOAL:
 
-Compare QMD knowledge context between the original skill creation and current state to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier — at Quick and Forge tiers, it appends a skip notice and auto-proceeds.
+Compare QMD knowledge context between the original skill creation and current state to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier — at Quick, Forge, and Forge+ tiers, it appends a skip notice and auto-proceeds.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -35,7 +35,7 @@ Compare QMD knowledge context between the original skill creation and current st
 - 🚫 FORBIDDEN to repeat structural findings from Step 03
 - 💬 Use subprocess Pattern 3 (data operations) when available for QMD queries
 - ⚙️ If subprocess unavailable, query QMD in main thread
-- 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge tier — append skip notice only
+- 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append skip notice only
 
 ## EXECUTION PROTOCOLS:
 
@@ -57,7 +57,7 @@ Compare QMD knowledge context between the original skill creation and current st
 
 ### 1. Check Forge Tier
 
-**IF forge tier is Quick or Forge:**
+**IF forge tier is Quick, Forge, or Forge+:**
 
 Append to {outputFile}:
 
@@ -179,7 +179,7 @@ ONLY WHEN the ## Semantic Drift section (or skip notice) has been appended to {o
 
 ### ✅ SUCCESS:
 
-- Forge tier checked FIRST — skip gracefully at Quick/Forge
+- Forge tier checked FIRST — skip gracefully at Quick/Forge/Forge+
 - Deep tier: QMD knowledge context queried and compared
 - All semantic findings have T2 confidence labels
 - Findings clearly distinguished from structural drift (T1)

package/src/workflows/audit-skill/validation-report.md

@@ -413,7 +413,7 @@ The audit-skill workflow is a well-designed, cohesive 6-step pipeline that achie
 ### Strengths
 
 1. **Zero-hallucination principle** enforced consistently — every finding traces to actual code
-2. **Graceful degradation** at every level — tier-aware (Quick/Forge/Deep), missing provenance (degraded mode)
+2. **Graceful degradation** at every level — tier-aware (Quick/Forge/Forge+/Deep), missing provenance (degraded mode)
 3. **Structured output** with file:line citations and confidence tier labels on all findings
 4. **Actionable remediation** — specific suggestions per finding (what to change, where, why)
 5. **Workflow chaining** — update-skill recommendation when CRITICAL/HIGH drift found
@@ -441,7 +441,7 @@ The audit-skill workflow is a well-designed, cohesive 6-step pipeline that achie
 |-------------|-------------|---------|--------|
 | Drift detection between skill and source | workflow.md + all 6 steps | High | ✅ |
 | Ferris Audit mode | workflow.md + all step role reinforcements | High | ✅ |
-| Tier-aware depth (Quick/Forge/Deep) | Steps 01-04 adapt per tier | High | ✅ |
+| Tier-aware depth (Quick/Forge/Forge+/Deep) | Steps 01-04 adapt per tier | High | ✅ |
 | Drift report with severity levels | Steps 03-06 build categorized report | High | ✅ |
 
 ### Classification Validation
@@ -534,7 +534,7 @@ None identified. All requirements from the plan are fully implemented.
 ### Key Strengths
 
 - Zero-hallucination principle enforced consistently throughout
-- Graceful tier-aware degradation (Quick/Forge/Deep)
+- Graceful tier-aware degradation (Quick/Forge/Forge+/Deep)
 - Well-chosen subprocess patterns with graceful fallbacks
 - Clean data flow: provenance → extraction → diff → classification → report
 - Actionable remediation suggestions with workflow chaining

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

@@ -54,7 +54,7 @@ Drift report with severity levels (added/removed/changed exports, breaking chang
 ### Key Instructions to LLM
 
 - Primary agent: Ferris (Audit mode)
-- Tiered operation: Forge tier (structural only) vs Deep tier (full semantic + QMD)
+- Tiered operation: Forge/Forge+ tier (structural, with optional CCC augmentation) vs Deep tier (full semantic + QMD)
 - The spec references AST diff for structural comparison and QMD for semantic context
 - CI integration is noted as optional export (ADR-A decision)
 
@@ -70,7 +70,7 @@ Drift report with severity levels (added/removed/changed exports, breaking chang
 - Document-producing output aligns with drift report use case
 
 **What needs improvement (fix during build):**
-- **Missing Quick tier path** — All SKF workflows support Quick/Forge/Deep with graceful degradation; Quick tier needs text-diff fallback
+- **Missing Quick tier path** — All SKF workflows support Quick/Forge/Forge+/Deep with graceful degradation; Quick tier needs text-diff fallback
 - **No provenance map format specification** — Step 01 loads it, but must reference known `provenance-map.json` from create-skill's `forge-data/{name}/` output
 - **No confidence tier labels (T1/T2/T3)** — Every SKF workflow uses these for traceability; drift findings need confidence scoring
 - **Step 04 conditional skip** — semantic-diff is Deep-only but spec has no skip logic or degradation behavior for Forge/Quick tiers

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

@@ -24,7 +24,7 @@ This uses **step-file architecture** for disciplined execution:
 - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
 - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
 - **Append-Only Building**: Build the drift report by appending sections as directed to the output file
-- **Tier-Aware Execution**: Adapt analysis depth based on detected forge tier (Quick/Forge/Deep) with graceful degradation
+- **Tier-Aware Execution**: Adapt analysis depth based on detected forge tier (Quick/Forge/Forge+/Deep) with graceful degradation
 
 ### Step Processing Rules
 

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

@@ -58,3 +58,7 @@ Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
 
 Exclusions will include all internal implementation files, tests, and utilities.
 Prompt: "Any additional items you'd like to include or exclude?"
+
+## Scripts & Assets Detection (Optional Refinement)
+
+When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.

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

@@ -10,7 +10,7 @@
 | language | string | Primary programming language | Must be detected or user-specified |
 | scope | object | Inclusion/exclusion boundaries | Must have type + at least one pattern |
 | description | string | What this skill covers | 1-3 sentences |
-| forge_tier | string | Compilation tier | One of: quick, forge, deep |
+| forge_tier | string | Compilation tier | One of: quick, forge, forge+, deep |
 | created | string | Creation date | ISO date format |
 | created_by | string | User who created the brief | From config user_name |
 
@@ -20,6 +20,8 @@
 |-------|------|-------------|------------|
 | source_type | string | Source mode: `source` or `docs-only` | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required |
 | doc_urls | array | Documentation URLs for T3 content | Each entry: `{url, label}`. Required when `source_type: "docs-only"` |
+| `scripts_intent` | string | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent` | string | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -65,7 +67,7 @@ source_type: "source"                    # "source" (default) or "docs-only"
 source_repo: "{github-url-or-local-path}"
 language: "{detected-language}"
 description: "{brief-description}"
-forge_tier: "{quick|forge|deep}"
+forge_tier: "{quick|forge|forge+|deep}"
 created: "{date}"
 created_by: "{user_name}"
 scope:
@@ -79,6 +81,8 @@ scope:
 # doc_urls:
 #   - url: "https://docs.example.com/api"
 #     label: "API Reference"
+# scripts_intent: detect         # Optional: detect | none | description
+# assets_intent: detect          # Optional: detect | none | description
 ---
 ```
 
@@ -112,6 +116,6 @@ Created by: {created_by}
 3. `language` must be a recognized programming language
 4. `scope.type` must be one of the three defined types
 5. `scope.include` must have at least one pattern
-6. `forge_tier` must match the tier from forge-tier.yaml (or default to quick)
+6. `forge_tier` must be one of: quick, forge, forge+, deep (must match the tier from forge-tier.yaml, or default to quick)
 7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional
 8. Each `doc_urls` entry must have a valid `url` field

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

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

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

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

package/src/workflows/brief-skill/steps-c/step-03-scope-definition.md

@@ -135,6 +135,18 @@ Does this look right? You can adjust before we continue."
 
 Wait for confirmation. Make adjustments if requested.
 
+### 5b. Scripts & Assets Intent (Optional)
+
+**Only ask when `scope.type` is `full-library` or `specific-modules` (skip for `public-api` and `docs-only`).**
+
+"Does this library include executable scripts (CLI tools, validation scripts, setup helpers) or static assets (config templates, JSON schemas, example configs) that should be packaged with the skill?"
+
+- **[D] Auto-detect** from source (default) — SKF will scan for `scripts/`, `bin/`, `assets/`, `templates/`, `schemas/` directories
+- **[N] None expected** — skip script/asset detection
+- Or describe what you expect (free text)
+
+Record the response as `scripts_intent` and `assets_intent` in the brief. Default to `detect` if user does not respond or skips.
+
 ### 6. Present MENU OPTIONS
 
 Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Confirmation

package/src/workflows/create-skill/data/compile-assembly-rules.md

@@ -14,8 +14,8 @@ description: >
 
 **Frontmatter rules:**
 
-- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name
-- `description`: non-empty, max 1024 chars, optimized for agent discovery
+- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity.
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. **MUST use third-person voice** ("Processes Excel files..." not "I can help you..." or "You can use this to..."). Inconsistent point-of-view causes discovery problems since the description is injected into the system prompt.
 - Only `name` and `description` in frontmatter — `version` and `author` go in metadata.json
 - No other frontmatter fields for standard skills (only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec)
 
@@ -77,6 +77,14 @@ These sections form the essential standalone body. Target: **under 300 lines tot
 - Basic CLI commands if the library has a CLI interface
 - Skip if no CLI exists
 
+**Section 7b — Scripts & Assets (~10 lines, if applicable):**
+- Manifest table of included scripts with filename, one-line purpose, and provenance citation
+- Manifest table of included assets with filename, one-line purpose, and provenance citation
+- Each entry: `scripts/{filename}` or `assets/{filename}`, purpose, `[SRC:{source_path}:L1]`
+- Include a note: "Load scripts from `scripts/` and assets from `assets/` when directed by the instructions above."
+- **Skip entirely** when no scripts or assets detected in extraction inventory — do not emit an empty section
+- Like Sections 4b and 7, parsers must treat this section as optional
+
 **Section 8 — Manual Sections:**
 - Seed empty `<!-- [MANUAL] -->` markers:
 ```markdown
@@ -108,3 +116,36 @@ Do NOT repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is
 4. If Tier 1 alone exceeds 300 lines, reduce Key API Summary and Architecture at a Glance
 5. Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full ...` headings) instead
 6. After split-body, SKILL.md must still contain all Tier 1 sections with actionable content
+
+### Reference File Rules
+
+- **Table of contents required** for any reference file exceeding 100 lines — include a `## Contents` section at the top listing all sub-sections. This ensures agents can see the full scope even when previewing with partial reads.
+- One file per major function group or type — group by module, file, or functional area
+- Name files descriptively: `form_validation_rules.md`, not `doc2.md`
+
+### Content Quality Rules
+
+These rules apply to all content assembled in SKILL.md and reference files.
+
+**Degrees of freedom:** Match instruction specificity to the task's fragility and variability:
+- **High freedom** (text guidance): When multiple approaches are valid and context determines the best one. Example: code review patterns, architecture suggestions.
+- **Medium freedom** (pseudocode/parameterized scripts): When a preferred pattern exists but variation is acceptable. Example: configuration templates, report generation.
+- **Low freedom** (exact scripts, no parameters): When operations are fragile and consistency is critical. Example: database migrations, deployment sequences. Use "Run exactly this" language.
+
+**Consistent terminology:** Choose one term per concept and use it throughout the skill. Do not mix synonyms (e.g., "API endpoint" vs "URL" vs "route", or "field" vs "box" vs "element"). Consistency helps agents understand and follow instructions deterministically.
+
+**Avoid time-sensitive information:** Do not include date-conditional instructions ("If before August 2025, use the old API"). Instead, document the current method and place deprecated patterns in a collapsible "Old patterns" section with the deprecation date.
+
+**Template and examples patterns:**
+- **For strict requirements** (API responses, data formats): Provide an exact template with "ALWAYS use this exact structure" language.
+- **For flexible guidance** (reports, analysis): Provide a sensible default template with "Adjust sections as needed" language.
+- **Input/output examples:** When output quality depends on seeing examples and concrete pairs exist in source tests or official docs, include 2-3 input/output pairs sourced from those tests or docs. Examples help agents understand desired style and detail more clearly than descriptions alone. If no examples exist in source, note the gap rather than fabricating pairs — zero hallucination applies.
+
+**Workflow checklist pattern:** When a skill includes multi-step workflows, provide a copy-paste checklist that agents can track progress against:
+```markdown
+Copy this checklist and track your progress:
+- [ ] Step 1: {action}
+- [ ] Step 2: {action}
+```
+
+**Verifiable intermediate outputs:** For skills involving batch operations, destructive changes, or complex validation, recommend the plan-validate-execute pattern: create a structured plan file (e.g., `changes.json`), validate it with a script, then execute. This catches errors before changes are applied.

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

@@ -0,0 +1,110 @@
+# Extraction Patterns: Tracing and File-Level Extraction
+
+This file covers re-export tracing protocols and script/asset file-level extraction patterns. For core tier strategies and AST extraction protocol, see `extraction-patterns.md`.
+
+---
+
+## Re-Export Tracing
+
+After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.
+
+**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.
+
+**Tracing protocol:**
+
+1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
+2. For each import where Y was NOT found by the initial AST scan:
+   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
+   - If directory: read its `__init__.py` to find the actual re-exported symbol
+   - **Handle aliases:** Check for `from .module import A as B` patterns in the intermediate `__init__.py`. If the parent imports `B`, trace through to `A` in `.module`. If the parent imports `A` but the `__init__.py` only exports it as `B` (via `from .module import A as B`), match by original name `A` and note the alias
+   - Trace the symbol to its definition file and run AST extraction on that file
+3. Cite the actual definition location: `[AST:{definition_file}:L{line}]`
+
+**Examples:**
+
+```python
+# Module re-export — follow required
+from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py
+
+# Direct function import — no follow needed
+from .api.v1.add.add import add      # add.py exists with def add()
+
+# Aliased re-export — follow through alias
+# In cognee/api/v1/visualize/__init__.py:
+#   from .start_visualization_server import visualization_server
+# In cognee/__init__.py:
+#   from .api.v1.visualize import start_visualization_server
+# → Match start_visualization_server against both definition names AND alias names
+#   in the intermediate __init__.py to resolve the chain
+```
+
+**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."
+
+**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.
+
+**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
+
+---
+
+## Script/Asset Extraction Patterns
+
+Scripts and assets are file-level artifacts, not code exports. They follow the **file-copy extraction method** — detected in source, copied with provenance citations.
+
+### Detection Heuristics
+
+**Script directories:** `scripts/`, `bin/`, `tools/`, `cli/`
+**Asset directories:** `assets/`, `templates/`, `schemas/`, `configs/`, `examples/`
+
+**Script file signals:**
+
+| Signal | Strength | Pattern |
+|--------|----------|---------|
+| Entry point declaration | Strong | `package.json` `bin` field, Cargo.toml `[[bin]]`, pyproject.toml `[project.scripts]` |
+| Shebang + executable | Strong | `#!/bin/bash`, `#!/usr/bin/env python`, `#!/usr/bin/env node` |
+| CLI argument parser | Moderate | `argparse`, `yargs`, `commander`, `cobra`, `clap` imports in file |
+| Directory convention | Moderate | File in `scripts/`, `bin/`, `tools/` directory |
+| CI/CD reference | Moderate | Script referenced in `.github/workflows/*.yml` |
+
+**Asset file signals:**
+
+| Signal | Strength | Pattern |
+|--------|----------|---------|
+| JSON Schema | Strong | `*.schema.json`, file contains `"$schema"` key |
+| Config template | Strong | `*.example`, `*.template.*`, `*.sample` extension |
+| Official example | Moderate | File in `examples/` directory, referenced in README |
+| OpenAPI/GraphQL | Moderate | `openapi.json`, `*.graphql`, `swagger.yaml` |
+| Design tokens | Weak | `tokens.json`, `theme.json` in `assets/` |
+
+### Inclusion Rules
+
+- Only include files within brief's `scope.include` patterns (or auto-detected directories)
+- Exclude binary files (check extension: `.so`, `.dll`, `.jar`, `.wasm`, `.exe`)
+- Exclude generated files (`dist/`, `build/`, `.webpack/` output)
+- Exclude vendored/third-party files
+- Flag files >500 lines for user confirmation (may be too large for skill package)
+- If `scripts_intent: "none"` or `assets_intent: "none"` in brief, skip that category
+
+### Provenance and Hashing
+
+Each extracted file receives:
+- Citation: `[SRC:{source_path}:L1]` (T1-low — file verified to exist but content not AST-analyzed)
+- Content hash: SHA-256 of file content (for drift detection in audit-skill)
+- Extraction method: `"file-copy"` (distinct from `"ast_bridge"` for code exports)
+
+### Inventory Structure
+
+**Script inventory entry:**
+- `name`: filename (e.g., `validate-config.sh`)
+- `source_file`: path relative to source root
+- `purpose`: extracted from file header comments or README reference (if none found, use filename)
+- `language`: detected from extension or shebang
+- `content_hash`: SHA-256
+- `confidence`: T1-low
+
+**Asset inventory entry:**
+- `name`: filename (e.g., `config-schema.json`)
+- `source_file`: path relative to source root
+- `purpose`: extracted from file header or schema `title`/`description` field
+- `type`: `template`, `schema`, `config`, `example`
+- `content_hash`: SHA-256
+- `confidence`: T1-low

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

@@ -28,7 +28,7 @@ Source reading via gh_bridge — infer exports from file structure and content.
 
 Structural extraction via ast-grep — verified exports with line-level citations.
 
-> **Note:** `ast_bridge.*` and `qmd_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations and QMD (MCP tool or CLI) for `qmd_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
+> **Note:** `ast_bridge.*`, `qmd_bridge.*`, and `ccc_bridge.*` references below are **conceptual interfaces**, not callable functions. They describe the operation to perform. Use ast-grep (MCP tool or CLI) for `ast_bridge.*` operations, QMD (MCP tool or CLI) for `qmd_bridge.*` operations, and ccc CLI or MCP for `ccc_bridge.*` operations. See the AST Extraction Protocol section below and the TOOL/SUBPROCESS FALLBACK rule for dispatch details.
 
 ### Strategy
 
@@ -52,6 +52,42 @@ Structural extraction via ast-grep — verified exports with line-level citation
 
 ---
 
+## Forge+ Tier (AST + CCC)
+
+Identical extraction to Forge tier. CCC adds an upstream semantic discovery step that pre-ranks the file extraction queue.
+
+### When CCC Pre-Discovery Applies
+
+CCC pre-discovery runs in step-02b-ccc-discover (before this extraction step) when ALL of the following are true:
+- Tier is Forge+ or Deep
+- `tools.ccc: true` in forge-tier.yaml
+- `ccc_index.status` is `"fresh"`, `"stale"`, `"created"`, or `"none"`/`"failed"` (step-02b attempts lazy indexing for the latter two)
+
+The discovery step stores `{ccc_discovery: [{file, score, snippet}]}` in context. This extraction step consumes those results to pre-rank the file list.
+
+### CCC Pre-Ranking Strategy
+
+When `{ccc_discovery}` is present and non-empty:
+
+1. Files appearing in `{ccc_discovery}` results move to the front of the extraction queue, sorted by relevance score descending
+2. Files NOT in CCC results remain in the queue — they are not excluded, only deprioritized
+3. If the CCC intersection with scoped files produces <10 files: include all scoped files (CCC results too narrow)
+4. Proceed with the AST Extraction Protocol on the pre-ranked list
+
+### ast-grep Patterns
+
+Same patterns as Forge tier — see Forge tier section above. CCC pre-ranking does not change which AST patterns are used, only which files are processed first.
+
+### Confidence
+
+All results: T1 (AST-verified) — identical to Forge tier. CCC is upstream discovery only and is invisible in the output artifact.
+
+### Important
+
+CCC pre-discovery failures (ccc unavailable, command error, empty results) always result in standard Forge extraction behavior. This is not reported to the user as a problem — it is normal behavior when ccc has no relevant results for the skill's scope.
+
+---
+
 ## Deep Tier (AST + QMD)
 
 Same extraction as Forge tier. Deep tier adds enrichment in step-04, not extraction.
@@ -234,43 +270,9 @@ constraints:
     regex: '^[A-Z]'
 ```
 
-### Re-Export Tracing
-
-After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.
-
-**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.
-
-**Tracing protocol:**
-
-1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
-2. For each import where Y was NOT found by the initial AST scan:
-   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
-   - If directory: read its `__init__.py` to find the actual re-exported symbol
-   - **Handle aliases:** Check for `from .module import A as B` patterns in the intermediate `__init__.py`. If the parent imports `B`, trace through to `A` in `.module`. If the parent imports `A` but the `__init__.py` only exports it as `B` (via `from .module import A as B`), match by original name `A` and note the alias
-   - Trace the symbol to its definition file and run AST extraction on that file
-3. Cite the actual definition location: `[AST:{definition_file}:L{line}]`
-
-**Examples:**
-
-```python
-# Module re-export — follow required
-from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py
-
-# Direct function import — no follow needed
-from .api.v1.add.add import add      # add.py exists with def add()
-
-# Aliased re-export — follow through alias
-# In cognee/api/v1/visualize/__init__.py:
-#   from .start_visualization_server import visualization_server
-# In cognee/__init__.py:
-#   from .api.v1.visualize import start_visualization_server
-# → Match start_visualization_server against both definition names AND alias names
-#   in the intermediate __init__.py to resolve the chain
-```
-
-**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."
-
-**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.
+### Re-Export Tracing and Script/Asset Extraction
 
-**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
+See `extraction-patterns-tracing.md` for:
+- **Re-export tracing protocol** — resolving module imports through `__init__.py`, barrel files, `pub use`
+- **Script/asset extraction patterns** — detection heuristics, inclusion rules, provenance, inventory structure
 

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

@@ -17,8 +17,8 @@ description: >
 
 **Frontmatter rules (agentskills.io specification):**
 
-- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name
-- `description`: 1-1024 characters, trigger-optimized for agent matching
+- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity; noun phrases and action-oriented forms are acceptable alternatives.
+- `description`: 1-1024 characters, trigger-optimized for agent matching. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
 - Only 6 fields permitted: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
 - `version` and `author` belong in metadata.json, NOT in frontmatter
 
@@ -38,6 +38,7 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 | 5 | **Key Types** | ~20 lines | Most important enum/type values inline |
 | 6 | **Architecture at a Glance** | ~10 lines | Bullet list of subsystem categories |
 | 7 | **CLI** | ~10 lines | Basic CLI commands (skip if no CLI) |
+| 7b | **Scripts & Assets** | ~10 lines | Manifest of included scripts and assets (skip if none detected) |
 | 8 | **Manual Sections** | ~5 lines | `<!-- [MANUAL] -->` markers for update-skill |
 
 #### Tier 2 — Reference-Eligible (extracted by split-body into references/)
@@ -55,7 +56,8 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 - Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full` headings) into `references/`
 - After split-body, SKILL.md retains all Tier 1 content — actionable without loading references
 - An agent loading only SKILL.md (no references) must get enough to act
-- **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
+- **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge/Forge+ tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
+- **Section 7b (Scripts & Assets)** is conditional: only emitted when `scripts_inventory` or `assets_inventory` is non-empty. Omitted entirely when no scripts or assets are detected. Parsers and validators must treat this section as optional.
 
 ### Provenance Citation Format
 
@@ -118,9 +120,12 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   "source_repo": "{github-url}",
   "source_root": "{resolved-source-path}",
   "source_commit": "{commit-hash}",
-  "confidence_tier": "{Quick|Forge|Deep}",
+  "confidence_tier": "{Quick|Forge|Forge+|Deep}",
   "spec_version": "1.3",
   "generation_date": "{ISO-8601}",
+  "description": "{SKILL.md frontmatter description}",
+  "language": "{primary-source-language}",
+  "ast_node_count": "{number-or-omitted-if-no-ast}",
   "exports": [],
   "tool_versions": {
     "ast_grep": "{version-or-null}",
@@ -136,8 +141,16 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "total_coverage": 0.0,
     "confidence_t1": 0,
     "confidence_t2": 0,
-    "confidence_t3": 0
+    "confidence_t3": 0,
+    "scripts_count": 0,
+    "assets_count": 0
   },
+  "scripts": [
+    { "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
+  ],
+  "assets": [
+    { "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }
+  ],
   "dependencies": [],
   "compatibility": "{semver-range}"
 }
@@ -163,6 +176,7 @@ Each reference file includes:
 - Complete usage examples
 - Related functions cross-references
 - Temporal annotations (Deep tier: T2-past, T2-future)
+- **Table of contents** (required for files exceeding 100 lines) — a `## Contents` section at the top listing all sub-sections for agent discoverability
 
 ---
 
@@ -186,10 +200,22 @@ Each reference file includes:
       "extraction_method": "ast_bridge.scan_definitions",
       "ast_node_type": "export_function_declaration"
     }
+  ],
+  "file_entries": [
+    {
+      "file_name": "scripts/{name}",
+      "file_type": "script",
+      "source_file": "{source-path}",
+      "confidence": "T1-low",
+      "extraction_method": "file-copy",
+      "content_hash": "sha256:{hash}"
+    }
   ]
 }
 ```
 
+`scripts` and `assets` arrays in metadata.json are optional — omit entirely (not empty arrays) when no scripts/assets exist. `file_entries` in provenance-map.json is optional — omit when no scripts/assets exist.
+
 ---
 
 ## evidence-report.md Structure