bmad-module-skill-forge 0.8.4 → 0.10.0

package/docs/how-it-works.md

@@ -11,7 +11,7 @@ This page is for people who want to understand how SKF works under the hood. It
 
 ## How BMad Works
 
-BMad works because it turns big, fuzzy work into **repeatable workflows**. Each workflow is broken into small steps with clear instructions, so the AI follows the same path every time. It also uses a **shared knowledge base** (standards and patterns) so outputs are consistent, not random. In short: **structured steps + shared standards = reliable results**.
+[BMad](https://docs.bmad-method.org/) works because it turns big, fuzzy work into **repeatable workflows**. Each workflow is broken into small steps with clear instructions, so the AI follows the same path every time. It also uses a **shared knowledge base** (standards and patterns) so outputs are consistent, not random. In short: **structured steps + shared standards = reliable results**.
 
 ## How SKF Fits In
 
@@ -185,26 +185,135 @@ Your forge tier limits what authority claims a skill can make:
 
 ---
 
+## Completeness Scoring
+
+The Test Skill workflow (`@Ferris TS`) calculates a **completeness score** — a weighted measure of how thoroughly and accurately a skill documents its target. This score is the quality gate: pass and the skill is ready for export; fail and it routes to update-skill for remediation.
+
+### Categories & Weights
+
+The score is the weighted sum of five categories:
+
+| Category | Weight | What It Measures |
+|----------|--------|------------------|
+| **Export Coverage** | 36% | Percentage of source exports documented in SKILL.md |
+| **Signature Accuracy** | 22% | Documented function signatures match actual source signatures (parameter names, types, order, return types) |
+| **Type Coverage** | 14% | Types and interfaces referenced in exports are fully documented |
+| **Coherence** | 18% | Cross-references resolve, integration patterns are complete (contextual mode only) |
+| **External Validation** | 10% | Average of skill-check quality score (0-100) and tessl content score (0-100%) |
+
+### Formula
+
+```
+total_score = sum(category_weight × category_score)
+```
+
+Each category score is a percentage: `(items_passing / items_total) × 100`.
+
+**Coherence** (contextual mode) combines two sub-scores:
+
+```
+coherence = (reference_validity × 0.6) + (integration_completeness × 0.4)
+```
+
+If no integration patterns exist, coherence equals reference validity alone.
+
+**External validation** averages the two tools when both are available. When only one tool is available, that tool's score is used. When neither is available, the 10% weight is redistributed proportionally to the other active categories.
+
+### Naive vs Contextual Mode
+
+Test Skill runs in one of two modes, detected automatically:
+
+- **Contextual mode** (stack skills) — All five categories scored with the default weights above.
+- **Naive mode** (individual skills) — Coherence is not scored. Its 18% weight is redistributed:
+
+| Category | Naive Weight |
+|----------|-------------|
+| Export Coverage | 45% |
+| Signature Accuracy | 25% |
+| Type Coverage | 20% |
+| External Validation | 10% |
+
+### Tier Adjustments
+
+Your forge tier determines which categories can be scored:
+
+| Tier | Skipped Categories | Reason |
+|------|-------------------|--------|
+| **Quick** | Signature Accuracy, Type Coverage | No AST parsing available |
+| **Docs-only** | Signature Accuracy, Type Coverage | No source code to compare against |
+| **Provenance-map** (State 2) | Signature Accuracy, Type Coverage | String comparison only, no semantic AST verification |
+| **Forge / Forge+ / Deep** | None | Full AST-backed scoring |
+
+When categories are skipped, their combined weight (36%) is redistributed proportionally to the remaining active categories. A Quick-tier skill and a Deep-tier skill both pass at the same 80% threshold — the score reflects what your tier can actually measure.
+
+### Pass/Fail
+
+```
+threshold = custom_threshold OR 80% (default)
+
+score >= threshold  →  PASS  →  Recommend export-skill
+score <  threshold  →  FAIL  →  Recommend update-skill
+```
+
+The default is 80%. You can override it by specifying a custom threshold when invoking the workflow (e.g., "test this skill with a 70% threshold").
+
+### Gap Severities
+
+When the score is calculated, each finding is classified by severity to guide remediation:
+
+| Severity | Examples |
+|----------|----------|
+| **Critical** | Missing exported function/class documentation |
+| **High** | Signature mismatch between source and SKILL.md |
+| **Medium** | Missing type/interface documentation; scripts/assets directory inconsistencies |
+| **Low** | Missing optional metadata or examples; description optimization opportunities |
+| **Info** | Style suggestions; discovery testing recommendations |
+
+### Score Report Output
+
+The test report includes a score breakdown table showing each category's raw score, weight, and weighted contribution:
+
+| Category | Score | Weight | Weighted |
+|----------|-------|--------|----------|
+| Export Coverage | 92% | 36% | 33.1% |
+| Signature Accuracy | 85% | 22% | 18.7% |
+| Type Coverage | 100% | 14% | 14.0% |
+| Coherence | 80% | 18% | 14.4% |
+| External Validation | 78% | 10% | 7.8% |
+| **Total** | | **100%** | **88.0%** |
+
+The report also records `analysisConfidence` (full, provenance-map, metadata-only, remote-only, or docs-only) and includes a degradation notice when source access was limited.
+
+---
+
 ## Output Architecture
 
 ### Per-Skill Output
 
-Every generated skill produces a self-contained directory:
+Every generated skill produces a self-contained, version-aware directory:
 
 ```
 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
-├── scripts/              # Executable automation (when detected in source)
-│   └── {script-name}.sh
-└── assets/               # Templates, schemas, configs (when detected in source)
-    └── {asset-name}.json
+├── active -> {version}           # Symlink to current version
+├── {version}/
+│   └── {name}/                   # agentskills.io-compliant package
+│       ├── 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
+│       ├── scripts/              # Executable automation (when detected in source)
+│       │   └── {script-name}.sh
+│       └── assets/               # Templates, schemas, configs (when detected in source)
+│           └── {asset-name}.json
+└── {older-version}/
+    └── {name}/                   # Previous version preserved
+        └── ...
 ```
 
+Multiple versions coexist under the same skill name. The `active` symlink points to the current version. Updating a skill for a new library release creates a new version directory — users pinned to older versions keep their skill intact. The inner `{name}/` directory is a standalone [agentskills.io](https://agentskills.io) package, directly installable via `npx skills add`.
+
 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
@@ -247,6 +356,7 @@ Machine-readable provenance for every skill:
   "source_repo": "https://github.com/topoteretes/cognee",
   "source_root": "cognee/",
   "source_commit": null,
+  "source_ref": "v0.5.5",
   "confidence_tier": "Deep",
   "spec_version": "1.3",
   "generation_date": "2026-03-20T16:55:00+04:00",
@@ -272,15 +382,18 @@ Stack skills map how your dependencies interact — shared types, co-import patt
 
 ```
 skills/{project}-stack/
-├── SKILL.md              # Integration patterns + project conventions
-├── context-snippet.md    # Compressed stack index
-├── metadata.json         # Component versions, integration graph
-└── references/
-    ├── nextjs.md         # Project-specific subset
-    ├── better-auth.md    # Project-specific subset
-    └── integrations/
-        ├── auth-db.md    # Cross-library pattern
-        └── pwa-auth.md   # Cross-library pattern
+├── active -> {version}
+└── {version}/
+    └── {project}-stack/
+        ├── SKILL.md              # Integration patterns + project conventions
+        ├── context-snippet.md    # Compressed stack index
+        ├── metadata.json         # Component versions, integration graph
+        └── references/
+            ├── nextjs.md         # Project-specific subset
+            ├── better-auth.md    # Project-specific subset
+            └── integrations/
+                ├── auth-db.md    # Cross-library pattern
+                └── pwa-auth.md   # Cross-library pattern
 ```
 
 The primary source is your project repo. Component references trace to library repos. `skill_type: "stack"` in metadata.
@@ -294,9 +407,9 @@ Based on [Vercel research](https://vercel.com/blog/agents-md-outperforms-skills-
 Every skill generates both:
 
 1. **SKILL.md** — Active skill loaded on trigger with full instructions
-2. **context-snippet.md** — Passive context, compressed index; injected into CLAUDE.md/AGENTS.md only when `export-skill` is run
+2. **context-snippet.md** — Passive context, compressed index; injected into platform context files (CLAUDE.md/AGENTS.md/.cursorrules) only when `export-skill` is run. Export reads configured IDEs from `config.yaml` and writes to all target platforms in one pass.
 
-### Managed CLAUDE.md Section
+### Managed Context Section
 
 Export injects a managed section between markers:
 
@@ -305,7 +418,7 @@ Export injects a managed section between markers:
 [SKF Skills]|1 skill
 |IMPORTANT: Prefer documented APIs over training data.
 |
-[cognee v0.5.5]|root: skills/cognee/
+[cognee v0.5.5]|root: .agents/skills/cognee/
 |IMPORTANT: cognee v0.5.5 — read SKILL.md before writing cognee code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start} — add → cognify → search async workflow
 |api: add(), cognify(), search(), memify(), config, datasets, prune, update(), session, SearchType, run_custom_pipeline(), visualize_graph()
@@ -314,7 +427,7 @@ Export injects a managed section between markers:
 <!-- SKF:END -->
 ```
 
-~80-120 tokens per skill (version-pinned, retrieval instruction, section anchors, inline gotchas). Aligned with [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) finding that indexed format with explicit retrieval instructions dramatically improves agent performance. Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations.
+~80-120 tokens per skill (version-pinned, retrieval instruction, section anchors, inline gotchas). Root paths are platform-aware (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`). Aligned with [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) finding that indexed format with explicit retrieval instructions dramatically improves agent performance. Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations. An `.export-manifest.json` tracks which skills have been explicitly exported, preventing draft skills from leaking into the managed section.
 
 ---
 
@@ -361,10 +474,11 @@ Build artifacts are committable — another developer can reproduce the same ski
 
 ```
 forge-data/{skill-name}/
-├── skill-brief.yaml        # Compilation config
-├── provenance-map.json     # Source map with AST bindings
-├── evidence-report.md      # Build audit trail
-└── extraction-rules.yaml   # Language-specific ast-grep schema
+├── skill-brief.yaml        # Compilation config (version-independent)
+└── {version}/
+    ├── provenance-map.json     # Source map with AST bindings
+    ├── evidence-report.md      # Build audit trail
+    └── 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.

package/docs/index.md

@@ -41,7 +41,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](./how-it-works/)** — Architecture, capability model, output format, and design decisions
-- **[Workflows](./workflows/)** — All 12 workflows with commands and connection diagrams
+- **[Workflows](./workflows/)** — All 14 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

@@ -1,11 +1,13 @@
 ---
 title: Workflows
-description: All 12 SKF workflows with commands, steps, and connection diagram
+description: All 14 SKF workflows with commands, steps, and connection diagram
 ---
 
 # Workflows Reference
 
-SKF has 12 workflows. You trigger them by typing commands to [Ferris](../agents/), the AI agent that runs everything. Each workflow handles a specific part of the skill lifecycle — from analyzing source code to packaging for distribution. If any terms are unfamiliar, see the [Concepts](../concepts/) page for definitions.
+SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/), the AI agent that runs everything. Each workflow handles a specific part of the skill lifecycle — from analyzing source code to packaging for distribution, plus management operations for renaming and dropping skills. If any terms are unfamiliar, see the [Concepts](../concepts/) page for definitions.
+
+> Already using BMAD? See [BMAD Synergy](../bmad-synergy/) for when to invoke each SKF workflow during BMM phases and alongside TEA, BMB, and GDS.
 
 ---
 
@@ -71,11 +73,11 @@ SKF has 12 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 ### Quick Skill (QS)
 
-**Command:** `@Ferris QS <package-or-url>`
+**Command:** `@Ferris QS <package-or-url>` or `@Ferris QS <package-or-url>@<version>`
 
 **Purpose:** Brief-less fast skill with package-to-repo resolution.
 
-**When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs.
+**When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs. Append `@version` to target a specific version (e.g., `@Ferris QS cognee@0.5.0`).
 
 **Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
 
@@ -139,6 +141,8 @@ SKF has 12 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → External validation (skill-check, tessl) → Score → Gap report
 
+**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%**. Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](../how-it-works/#completeness-scoring) for the full formula and tier adjustments.
+
 **Agent:** Ferris (Audit mode)
 
 ---
@@ -181,7 +185,7 @@ SKF has 12 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Purpose:** Validate package structure, generate context snippets, and inject managed sections into CLAUDE.md/AGENTS.md/.cursorrules.
 
-**When to Use:** When a skill is ready for CLAUDE.md/AGENTS.md integration. Also provides distribution instructions for `npx skills publish`.
+**When to Use:** When a skill is ready for CLAUDE.md/AGENTS.md integration. Also provides a local install command (`npx skills add <path>`) and distribution instructions for `npx skills publish`. See [Installation → Source Formats](https://www.npmjs.com/package/skills#installation) for other install methods.
 
 **Key Steps:** Load skill → Validate package → Generate snippet → Update context file (CLAUDE.md/AGENTS.md/.cursorrules) → Token report → Summary
 
@@ -189,6 +193,40 @@ SKF has 12 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 ---
 
+## Management Workflows
+
+### Rename Skill (RS)
+
+**Command:** `@Ferris RS`
+
+**Purpose:** Rename a skill across all its versions. Because the agentskills.io spec requires `name` to match parent directory name, this is a coordinated move across outer/inner directories, SKILL.md frontmatter, metadata.json, context snippets, provenance maps, the export manifest, and platform context files.
+
+**When to Use:** You need to change a skill's name — for example, graduating a `QS`-generated skill (named from the repo) to a formal name, or adding a suffix like `-community` to distinguish from an official skill.
+
+**Key Steps:** Select skill + new name → Transactional copy → Update all references → Rebuild context files → Delete old name (point of no return)
+
+**Safety:** Transactional — if any step fails before the final delete, the old skill remains intact. Warns if `source_authority: "official"` (rename is local-only; published registry skill won't change).
+
+**Agent:** Ferris (Management mode)
+
+---
+
+### Drop Skill (DS)
+
+**Command:** `@Ferris DS`
+
+**Purpose:** Drop a specific skill version or an entire skill. Soft drop (default) marks the version as deprecated in the manifest and keeps files on disk. Hard drop (`--purge`) also deletes the files.
+
+**When to Use:** Retire a deprecated version (e.g., drop `cognee 0.1.0` because it's obsolete), free disk space, or remove a skill you no longer need.
+
+**Key Steps:** Select skill → Select version(s) + mode → Update manifest → Rebuild context files → Delete files (if purge)
+
+**Safety:** Active version guard — cannot drop the currently active version when other non-deprecated versions exist (switch active first, or drop all). Soft drop is reversible by editing the manifest.
+
+**Agent:** Ferris (Management mode)
+
+---
+
 ## Workflow Connections
 
 **Standard path (code-mode):**

package/package.json

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

@@ -0,0 +1,47 @@
+# SKF Module Source
+
+This directory contains the **Skill Forge (SKF)** BMAD module — the files that get installed into a BMAD project under `_bmad/skf/` when a user runs the installer.
+
+For user-facing documentation (what SKF does, how to install it, how to use it), see the [repository README](../README.md) and the published docs at [armelhbobdad.github.io/bmad-module-skill-forge](https://armelhbobdad.github.io/bmad-module-skill-forge/).
+
+## Layout
+
+```
+src/
+├── module.yaml           # Module config: code, name, install prompts
+├── module-help.csv       # Help registry — one row per agent command
+├── agents/
+│   └── forger.agent.yaml # Ferris — the single agent persona
+├── workflows/            # 14 workflows (see workflows/README.md)
+│   ├── setup-forge/
+│   ├── analyze-source/
+│   ├── brief-skill/
+│   ├── create-skill/
+│   ├── quick-skill/
+│   ├── create-stack-skill/
+│   ├── verify-stack/
+│   ├── refine-architecture/
+│   ├── update-skill/
+│   ├── audit-skill/
+│   ├── test-skill/
+│   ├── export-skill/
+│   ├── rename-skill/
+│   └── drop-skill/
+├── knowledge/            # Cross-cutting knowledge fragments (JiT loaded)
+│   └── skf-knowledge-index.csv
+└── forger/               # Sidecar seed files (preferences, forge tier)
+```
+
+## Components
+
+- **Agent:** [Ferris](agents/forger.agent.yaml) — single-persona module operating in four modes (Architect / Surgeon / Audit / Delivery)
+- **Workflows:** see [workflows/README.md](workflows/README.md) for the full index, typical flows, and the knowledge-vs-data distinction
+- **Knowledge fragments:** cross-cutting principles Ferris consults via `knowledge/skf-knowledge-index.csv`
+
+## Editing this module
+
+- Agent edits — `agents/forger.agent.yaml`; validate with `bmad:bmb:agents:agent-validate`
+- Workflow edits — each workflow in `workflows/{name}/`; validate with `bmad:bmb:workflows:workflow-validate`
+- Module-level edits — `module.yaml` and `module-help.csv`; validate with `bmad:bmb:modules:validate-module`
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the contribution workflow.

package/src/agents/forger.agent.yaml

@@ -97,6 +97,14 @@ agent:
       workflow: "{project-root}/_bmad/skf/workflows/skillforge/export-skill/workflow.md"
       description: "[EX] Export Skill — package for distribution"
 
+    - trigger: RS or fuzzy match on rename-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/rename-skill/workflow.md"
+      description: "[RS] Rename Skill — rename a skill across all its versions (transactional)"
+
+    - trigger: DS or fuzzy match on drop-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/drop-skill/workflow.md"
+      description: "[DS] Drop Skill — deprecate (soft) or purge (hard) skill versions"
+
     - trigger: KI or fuzzy match on knowledge-index
       action: "Load and display {project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv — cross-cutting knowledge fragments available for JiT loading"
       description: "[KI] Knowledge Index — list available knowledge fragments"

package/src/knowledge/agentskills-spec.md

@@ -54,6 +54,8 @@ skill-name/
 
 All subdirectories are exactly one level deep. Files are loaded on demand when SKILL.md directs — never automatically.
 
+**Version-aware storage:** Skill Forge stores skills in a version-nested layout: `{skill-name}/{version}/{skill-name}/`. The inner `{skill-name}/` directory is the agentskills.io-compliant package shown above. The outer `{skill-name}/` and `{version}/` directories are organizational wrappers managed by the forge — they are not part of the skill package structure. The "one level deep" subdirectory rule applies to the skill package root (the inner directory), not the forge's storage hierarchy. See [version-paths.md](version-paths.md) for full path resolution rules.
+
 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
@@ -179,5 +181,6 @@ Skills that include executable scripts in `scripts/` must follow these principle
 - [skill-lifecycle.md](skill-lifecycle.md) — where agentskills.io compliance fits in the pipeline
 - [confidence-tiers.md](confidence-tiers.md) — how citations appear within the formatted output
 - [zero-hallucination.md](zero-hallucination.md) — the integrity principle that shapes skill content
+- [version-paths.md](version-paths.md) — version-aware storage layout and path resolution templates
 
 _Source: synthesized from agentskills.io specification, what-are-skills.mdx, integrate-skills.mdx, and Best Practices for Creating Agent Skills_

package/src/knowledge/overview.md

@@ -35,6 +35,7 @@ With knowledge files:
 | [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                |
+| [version-paths.md](version-paths.md)                       | Version-aware storage layout, path templates, export manifest v2, migration | CS, QS, SS, US, AS, TS, EX, VS, RA |
 | [overview.md](overview.md)                                 | Knowledge map and JiT loading protocol (this file)               | All (entry point)                  |
 
 ## JiT Loading Protocol

package/src/knowledge/provenance-tracking.md

@@ -39,6 +39,7 @@ With provenance tracking:
   "skill_name": "express-skill",
   "source_repo": "https://github.com/expressjs/express",
   "source_commit": "abc1234",
+  "source_ref": "v0.5.0",
   "generated_at": "2025-01-15T10:30:00Z",
   "entries": [
     {
@@ -174,11 +175,13 @@ Citations appear directly in SKILL.md content:
 - Copying provenance from a previous extraction without re-verifying — timestamps must reflect actual verification time
 - Omitting the evidence report — it is required for every compilation, not optional
 - Using provenance from one source file version against a different version — provenance is version-bound
+- Storing provenance at a flat path (`{forge_data_folder}/{skill-name}/provenance-map.json`) instead of the versioned path (`{forge_version}/provenance-map.json`) — each version has its own provenance chain (see [version-paths.md](version-paths.md))
 
 ## Related Fragments
 
 - [confidence-tiers.md](confidence-tiers.md) — defines the citation formats used in provenance
 - [zero-hallucination.md](zero-hallucination.md) — the principle that provenance enforces
 - [manual-section-integrity.md](manual-section-integrity.md) — how \[MANUAL\] sections interact with provenance
+- [version-paths.md](version-paths.md) — version-aware storage layout where provenance artifacts are stored per-version
 
 _Source: consolidated from create-skill steps 03/05/07, audit-skill steps 02/03, and skill-sections.md_

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

@@ -13,3 +13,4 @@ doc-fetcher,Doc Fetcher,"T3 external documentation — tool-agnostic URL fetchin
 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
+version-paths,Version-Aware Paths,"Version-nested directory structure — path templates, version resolution, export manifest v2, migration from flat layout, version sanitization","version,paths,directory,structure,migration,manifest,symlink",core,knowledge/version-paths.md

package/src/knowledge/skill-lifecycle.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-The 12 SKF workflows form an end-to-end pipeline from source discovery through verified export, with a pre-code architecture verification path. Each workflow produces artifacts consumed by downstream workflows. Understanding the lifecycle enables Ferris to recommend the right workflow for a user's situation and to maintain artifact continuity across the pipeline.
+The 14 SKF workflows form an end-to-end pipeline from source discovery through verified export, with a pre-code architecture verification path and post-distribution management operations. Each workflow produces artifacts consumed by downstream workflows. Understanding the lifecycle enables Ferris to recommend the right workflow for a user's situation and to maintain artifact continuity across the pipeline.
 
 ## Rationale
 
@@ -25,11 +25,12 @@ With lifecycle awareness:
 | Setup | SF (Setup Forge) | Detect environment and set capability tier | `forge-tier.yaml` |
 | Discovery | AN (Analyze Source) | Scan project, identify skillable units | Analysis report, skill briefs |
 | Design | BS (Brief Skill) | Interactive scope definition for one skill | `skill-brief.yaml` |
-| Compilation | CS, QS, SS (Create/Quick/Stack) | Extract source and compile skill | `SKILL.md`, metadata, provenance, `scripts/`, `assets/` (when source contains them) |
+| Compilation | CS, QS, SS (Create/Quick/Stack) | Extract source and compile skill | `SKILL.md`, metadata, provenance, `scripts/`, `assets/` (when source contains them) — written to `{skill_package}` and `{forge_version}` (see [version-paths.md](version-paths.md)) |
 | Architecture Verification | VS, RA (Verify Stack, Refine Architecture) | Pre-code feasibility check and architecture refinement | Feasibility report, refined architecture doc |
 | Maintenance | US, AS (Update/Audit) | Detect drift and refresh skills | Updated `SKILL.md`, drift report |
 | Verification | TS (Test Skill) | Quality gate — completeness scoring | Test report, pass/fail decision |
 | Distribution | EX (Export Skill) | Package and inject into agent context | agentskills.io bundle, snippets |
+| Management | RS, DS (Rename/Drop) | Rename or retire skills and versions | Renamed skill group, deprecated/purged versions |
 
 ## Typical Flows
 
@@ -92,6 +93,16 @@ AS → US → TS → EX
 3. **TS** re-verifies the updated skill
 4. **EX** re-exports the updated package
 
+### Management
+
+```
+RS or DS → EX
+```
+
+1. **RS** renames a skill across all versions (transactional copy-verify-delete), OR
+2. **DS** drops a specific version (soft — deprecate, or hard — purge) or the entire skill
+3. **EX** rebuilds platform context files (CLAUDE.md/AGENTS.md/.cursorrules) to reflect the management operation — deprecated versions are excluded, renamed skills appear under their new name
+
 ## Pattern Examples
 
 ### Example 1: Workflow Selection Decision
@@ -124,11 +135,11 @@ SF → forge-tier.yaml
        ↓ (read by all subsequent workflows)
 AN → analysis-report.md + skill-brief.yaml[]
        ↓ (briefs consumed by CS)
-CS → SKILL.md + metadata.json + provenance-map.json + scripts/ + assets/ (when present) + evidence-report.md
-       ↓ (skill consumed by TS)
-TS → test-report.md (pass/fail gate)
-       ↓ (passing skill consumed by EX)
-EX → agentskills.io bundle + context snippets
+CS → {skill_package}/SKILL.md + metadata.json + {forge_version}/provenance-map.json + scripts/ + assets/ (when present) + evidence-report.md
+       ↓ (skill consumed by TS — resolved via active version)
+TS → {forge_version}/test-report.md (pass/fail gate)
+       ↓ (passing skill consumed by EX — resolved via export manifest v2)
+EX → agentskills.io bundle + context snippets (flat platform paths)
 
 VS → feasibility-report-{project_name}.md (verdict + integration verdicts)
        ↓ (report consumed by RA)
@@ -170,5 +181,6 @@ SS (compose) → SKILL.md (stack skill synthesized from individual skills + arch
 - [progressive-capability.md](progressive-capability.md) — how the forge tier affects each pipeline phase
 - [agentskills-spec.md](agentskills-spec.md) — the output format that export-skill packages
 - [provenance-tracking.md](provenance-tracking.md) — how provenance flows through the pipeline
+- [version-paths.md](version-paths.md) — version-aware storage layout, path templates, and migration rules
 
 _Source: synthesized from all 12 workflow.md files (including VS, RA) and module-help.csv_