bmad-module-skill-forge 0.8.4 → 0.9.0

package/src/knowledge/version-paths.md

@@ -0,0 +1,243 @@
+# Version-Aware Paths
+
+## Principle
+
+Skills are stored in a version-nested directory structure that allows multiple versions to coexist. Each version directory contains a self-contained agentskills.io-compliant skill package. All workflows resolve skill paths through canonical templates defined here, ensuring consistency across the pipeline and compatibility with `skill.sh` / `npx skills` distribution tooling.
+
+## Rationale
+
+Without version-aware paths:
+- Updating a skill for cognee v0.6.0 overwrites the v0.5.0 skill — users pinned to v0.5.0 lose their instructions
+- Audit and provenance comparisons cannot span version boundaries
+- Skills cannot be distributed to registries that serve multiple versions
+
+With version-aware paths:
+- Multiple versions coexist under `{skill-name}/` — no data loss on update
+- Provenance, evidence, and test reports are preserved per-version
+- The inner `{skill-name}/` directory is a standalone agentskills.io package, directly installable via `npx skills add`
+
+## Path Templates
+
+All workflows MUST use these templates when constructing paths. Never hardcode paths to skill artifacts.
+
+### skills_output_folder (Deliverables)
+
+| Template | Resolves To | Usage |
+|----------|------------|-------|
+| `{skill_package}` | `{skills_output_folder}/{skill-name}/{version}/{skill-name}/` | Skill package root — where SKILL.md, metadata.json, context-snippet.md, references/, scripts/, assets/ live |
+| `{skill_group}` | `{skills_output_folder}/{skill-name}/` | Parent directory for all versions of a skill |
+| `{active_skill}` | `{skills_output_folder}/{skill-name}/active/{skill-name}/` | Resolved via `active` symlink — stable path to the current version |
+
+### forge_data_folder (Workspace Artifacts)
+
+| Template | Resolves To | Usage |
+|----------|------------|-------|
+| `{forge_version}` | `{forge_data_folder}/{skill-name}/{version}/` | Version-specific workspace artifacts — provenance-map.json, evidence-report.md, extraction-rules.yaml, test-report |
+| `{forge_group}` | `{forge_data_folder}/{skill-name}/` | Parent directory — contains skill-brief.yaml (version-independent) and version subdirectories |
+
+### Platform Paths (Unchanged — Flat)
+
+| Platform | Root Path |
+|----------|-----------|
+| `claude` | `.claude/skills/{skill-name}/` |
+| `cursor` | `.cursor/skills/{skill-name}/` |
+| `copilot` | `.agents/skills/{skill-name}/` |
+| _(legacy)_ | `skills/{skill-name}/` |
+
+Platform paths are **not versioned**. The export workflow resolves the active version from the manifest and references its `{skill_package}` when building the managed section. The snippet `root:` always uses the flat platform path.
+
+## Directory Structure
+
+### skills_output_folder
+
+```
+{skills_output_folder}/
+  .export-manifest.json
+  {skill-name}/
+    active -> {version}
+    {version}/
+      {skill-name}/
+        SKILL.md
+        metadata.json
+        context-snippet.md
+        references/
+        scripts/
+        assets/
+    {older-version}/
+      {skill-name}/
+        ...
+  {project}-stack/
+    active -> {version}
+    {version}/
+      {project}-stack/
+        SKILL.md
+        metadata.json
+        context-snippet.md
+        references/
+          integrations/
+```
+
+The inner `{skill-name}/` directory IS the agentskills.io-compliant skill package. The version directory is an organizational wrapper. The `name` field in SKILL.md frontmatter matches the inner directory name — spec compliance is preserved.
+
+### forge_data_folder
+
+```
+{forge_data_folder}/
+  {skill-name}/
+    skill-brief.yaml
+    {version}/
+      provenance-map.json
+      evidence-report.md
+      extraction-rules.yaml
+      test-report-{skill-name}.md
+```
+
+`skill-brief.yaml` stays at `{forge_group}` level — the brief is a workflow input that defines extraction scope, not a versioned output.
+
+## Version Resolution
+
+### Writing Workflows (CS, QS, SS, US)
+
+When writing artifacts, resolve `{version}` from the skill brief's `version` field (CS, SS), the extraction inventory (QS), or the updated metadata (US). Then:
+
+1. Create `{skill_group}` if it does not exist
+2. Create `{skill_package}` (including all parent directories)
+3. Write all deliverables to `{skill_package}`
+4. Create `{forge_version}` if it does not exist
+5. Write all workspace artifacts to `{forge_version}`
+6. Create or update the `active` symlink at `{skill_group}/active` pointing to `{version}`
+
+### Reading Workflows (EX, AS, TS, VS, RA)
+
+When reading artifacts, resolve the skill path using the export manifest:
+
+1. Read `{skills_output_folder}/.export-manifest.json`
+2. Look up the skill name in `exports`
+3. Read `active_version` to get the target version
+4. Resolve to `{skill_package}` using the active version
+5. If manifest does not contain the skill: check for `active` symlink at `{skill_group}/active`
+6. If neither manifest nor symlink: fall back to flat-path resolution (migration — see below)
+
+### Manifest-Driven Snippet Scanning (EX Step-04)
+
+Replace the glob-based snippet scan (`{skills_output_folder}/*/context-snippet.md`) with manifest-driven resolution:
+
+1. Read export manifest
+2. For each skill in the exported skill set: resolve `active_version` to get `{skill_package}`
+3. Read `{skill_package}/context-snippet.md`
+4. Filter and assemble as before
+
+## Export Manifest v2
+
+The export manifest gains version awareness:
+
+```json
+{
+  "schema_version": "2",
+  "exports": {
+    "skill-name": {
+      "active_version": "0.6.0",
+      "versions": {
+        "0.5.0": {
+          "platforms": ["claude"],
+          "last_exported": "2026-03-15",
+          "status": "archived"
+        },
+        "0.6.0": {
+          "platforms": ["claude", "copilot"],
+          "last_exported": "2026-04-04",
+          "status": "active"
+        }
+      }
+    }
+  }
+}
+```
+
+**Fields:**
+- `schema_version`: `"2"` — enables v1-to-v2 migration detection
+- `active_version`: The version whose `{skill_package}` supplies the context snippet for the managed section. Must match exactly one version with `status: "active"`
+- `versions.{v}.status`: `"active"` (currently exported), `"archived"` (previously exported, retained on disk), `"deprecated"` (dropped via drop-skill workflow, excluded from all exports), `"draft"` (created but never exported)
+- `versions.{v}.platforms`: Array of platforms this version was last exported to
+- `versions.{v}.last_exported`: ISO date of the last export
+
+**Only one version per skill can have `status: "active"` at any time.**
+
+## Skill Management Operations
+
+Two workflows operate on the version-aware structure for skill lifecycle management:
+
+### Rename (RS - Rename Skill)
+
+Renames a skill across all versions. Because the agentskills.io spec requires `name` to match parent directory name, a rename is a coordinated move across:
+1. Outer `{skill_group}` directory: `{skills_output_folder}/{old-name}/` → `{skills_output_folder}/{new-name}/`
+2. Inner `{skill-name}/` directories inside each version: `{version}/{old-name}/` → `{version}/{new-name}/`
+3. `SKILL.md` frontmatter `name:` field (in every version)
+4. `metadata.json` `name` field (in every version)
+5. `context-snippet.md` root paths and display name (in every version)
+6. `provenance-map.json` `skill_name` field (in every version under `{forge_group}`)
+7. `{forge_group}` directory: `{forge_data_folder}/{old-name}/` → `{forge_data_folder}/{new-name}/`
+8. Export manifest: remove old key, add new key with same version data
+9. Platform context files (CLAUDE.md, AGENTS.md, .cursorrules): rebuild managed sections
+
+Rename is transactional — copy-verify-delete pattern. If any step fails, old skill remains intact. See `workflows/rename-skill/`.
+
+### Drop (DS - Drop Skill)
+
+Drops a specific version or the entire skill with two modes:
+
+**Soft drop (default):** Sets version status to `"deprecated"` in the export manifest. Files remain on disk. Export-skill excludes deprecated versions from all platform context files. Reversible by manually editing manifest back to `"active"`/`"archived"`.
+
+**Hard drop (`--purge`):** Same as soft drop, plus deletes the version directory (`{skill_package}`) and forge data directory (`{forge_version}`). Irreversible.
+
+**Active version guard:** Cannot drop the active version when other versions exist. The user must either switch active to another version first, or drop all versions at once.
+
+**Skill-level drop:** Removes the entire `{skill_group}` from the manifest. If purge, also deletes `{skill_group}` and `{forge_group}` directories.
+
+See `workflows/drop-skill/`.
+
+## Version Sanitization
+
+Directory names use the semver version with `+{build}` metadata stripped:
+
+| Source Version | Directory Name | Rule |
+|---------------|---------------|------|
+| `1.0.0` | `1.0.0` | Clean — no transformation |
+| `0.5.0-beta.1` | `0.5.0-beta.1` | Pre-release preserved |
+| `1.0.0-rc.2+build.456` | `1.0.0-rc.2` | Build metadata stripped per semver spec |
+| `2.0.0+20260404` | `2.0.0` | Build metadata stripped |
+
+Build metadata does not affect version precedence per the semver specification and is stripped to avoid filesystem issues with the `+` character.
+
+## Migration: Flat to Versioned
+
+When a reading workflow encounters a skill at the flat path (`{skills_output_folder}/{skill-name}/SKILL.md` exists directly — no version subdirectory), it auto-migrates:
+
+1. Read `metadata.json` from the flat path to get the `version` field
+2. Create the versioned directory: `{skill_group}/{version}/{skill-name}/`
+3. Move all package files (SKILL.md, metadata.json, context-snippet.md, references/, scripts/, assets/) into the versioned location
+4. Create the `active` symlink: `{skill_group}/active -> {version}`
+5. If `{forge_data_folder}/{skill-name}/` contains provenance artifacts at the flat level (not in a version subdirectory):
+   - Create `{forge_version}`
+   - Move provenance-map.json, evidence-report.md, extraction-rules.yaml, test-report into `{forge_version}`
+   - Leave skill-brief.yaml at `{forge_group}` (it is already version-independent)
+6. If `.export-manifest.json` exists and lacks `schema_version`:
+   - Migrate to v2 schema: wrap existing entries with `active_version` and `versions` structure
+   - Set `schema_version: "2"`
+7. Report migration to user: "Migrated {skill-name} from flat to versioned layout ({version})"
+
+**Migration preserves all content** — [MANUAL] sections, provenance, evidence reports, and scripts/assets are moved, not re-generated.
+
+## Anti-Patterns
+
+- Hardcoding `{skills_output_folder}/{skill-name}/SKILL.md` without version resolution — always use `{skill_package}` template
+- Storing `skill-brief.yaml` inside a version directory — the brief is version-independent
+- Versioning platform root paths — platform paths stay flat, version lives in the forge workspace
+- Using glob patterns to discover snippets across all versions — use the export manifest to resolve the active version
+- Creating version directories with `+` in the name — strip build metadata
+
+## Related Fragments
+
+- [agentskills-spec.md](agentskills-spec.md) — the format that `{skill_package}` contents must comply with
+- [skill-lifecycle.md](skill-lifecycle.md) — how versioned artifacts flow through the pipeline
+- [provenance-tracking.md](provenance-tracking.md) — provenance is version-bound and stored per-version in `{forge_version}`

package/src/module-help.csv

@@ -9,6 +9,8 @@ skf,anytime,Update Skill,US,,_bmad/skf/workflows/skillforge/update-skill/workflo
 skf,anytime,Audit Skill,AS,,_bmad/skf/workflows/skillforge/audit-skill/workflow.md,skf_audit_skill,false,ferris,Audit Mode,"Drift detection between skill and current source code",,"drift report",
 skf,anytime,Test Skill,TS,,_bmad/skf/workflows/skillforge/test-skill/workflow.md,skf_test_skill,false,ferris,Audit Mode,"Cognitive completeness verification — quality gate before export",,"completeness score",
 skf,anytime,Export Skill,EX,,_bmad/skf/workflows/skillforge/export-skill/workflow.md,skf_export_skill,false,ferris,Delivery Mode,"Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules",skills_output_folder,"agentskills.io package",
+skf,anytime,Rename Skill,RS,,_bmad/skf/workflows/skillforge/rename-skill/workflow.md,skf_rename_skill,false,ferris,Management Mode,"Rename a skill across all its versions — transactional copy-verify-delete with platform context rebuild",skills_output_folder,"renamed skill group",
+skf,anytime,Drop Skill,DS,,_bmad/skf/workflows/skillforge/drop-skill/workflow.md,skf_drop_skill,false,ferris,Management Mode,"Drop a specific skill version or an entire skill — soft (deprecate) or hard (purge) with platform context rebuild",skills_output_folder,"updated manifest",
 skf,anytime,Verify Stack,VS,,_bmad/skf/workflows/skillforge/verify-stack/workflow.md,skf_verify_stack,false,ferris,Audit Mode,"Pre-code stack feasibility verification against architecture and PRD documents",forge_data_folder,"feasibility-report-{project_name}.md",
 skf,anytime,Refine Architecture,RA,,_bmad/skf/workflows/skillforge/refine-architecture/workflow.md,skf_refine_architecture,false,ferris,Architect Mode,"Improve architecture doc using verified skill data and VS feasibility findings",output_folder,"refined-architecture-{project_name}.md",
 skf,anytime,Workflow Status,WS,,,skf_workflow_status,false,ferris,Reference,"Show current lifecycle position, active skill briefs, and forge tier status",,lifecycle status,

package/src/workflows/README.md

@@ -1,6 +1,6 @@
 # SKF Workflows
 
-Twelve workflows covering the full skill lifecycle — from source discovery through verified export, with pre-code architecture verification.
+Fourteen workflows covering the full skill lifecycle — from source discovery through verified export, with pre-code architecture verification and post-distribution management.
 
 All workflows are triggered via Ferris (`@Ferris <code>`) and execute as step-by-step sequences with just-in-time step loading.
 
@@ -20,6 +20,8 @@ All workflows are triggered via Ferris (`@Ferris <code>`) and execute as step-by
 | AS | [audit-skill](audit-skill/workflow.md) | 6 | Audit | Drift detection between skill and current source code |
 | TS | [test-skill](test-skill/workflow.md) | 7 | Audit | Cognitive completeness verification — quality gate before export |
 | EX | [export-skill](export-skill/workflow.md) | 6 | Delivery | Package for distribution, inject into CLAUDE.md/AGENTS.md |
+| RS | [rename-skill](rename-skill/workflow.md) | 3 | Management | Rename a skill across all versions (transactional copy-verify-delete) |
+| DS | [drop-skill](drop-skill/workflow.md) | 3 | Management | Drop specific versions or whole skill (soft deprecate or hard purge) |
 
 ## Typical Flows
 
@@ -53,6 +55,12 @@ SF → CS×N (per library) → VS → RA → SS (compose) → TS → EX
 AS → US → TS → EX
 ```
 
+**Management:**
+
+```
+RS or DS → EX
+```
+
 ## Knowledge vs. Data
 
 The module uses two kinds of reference material, loaded just-in-time during workflow execution:

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

@@ -26,7 +26,9 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
 | `scripts_intent` | string | `detect` / `none` / free-text | 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 | `detect` / `none` / free-text | 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/"). |
+| `target_version` | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable. |
 | `source_authority` | string | `official` / `community` / `internal` | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`. |
+| `source_ref` | string | Git ref (tag/branch/HEAD) | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -49,6 +51,8 @@ If detection succeeds, use the detected version. If it fails or returns a non-se
 
 The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
+**Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
+
 **Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
 
 ## Scope Object

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

@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Load existing skill, provenance map, and detect forge tier for drift analysis'
 
 nextStepFile: './step-02-re-index.md'
-outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
 templateFile: '../data/drift-report-template.md'
 ---
 
@@ -63,14 +63,18 @@ Load the existing skill artifacts, provenance map, and forge tier configuration
 
 Which skill would you like to audit? Please provide the skill name or path."
 
-**If user provides skill name (not full path):**
-- Resolve to `{skills_output_folder}/{skill_name}/`
+**If user provides skill name (not full path) — version-aware path resolution (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)):**
+1. Read `{skills_output_folder}/.export-manifest.json` and look up the skill name in `exports` to get `active_version`
+2. If found: resolve to `{skill_package}` = `{skills_output_folder}/{skill_name}/{active_version}/{skill_name}/`
+3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill_name}/active` — resolve to `{skill_group}/active/{skill_name}/`
+4. If neither: fall back to flat path `{skills_output_folder}/{skill_name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
+5. Store the resolved path as `{resolved_skill_package}`
 
 **If user provides full path:**
 - Use as provided
 
 **Validate:** Check that `SKILL.md` exists at the resolved path.
-- If missing → "Skill not found at `{resolved_path}`. Check the path and try again."
+- If missing → "Skill not found at `{resolved_skill_package}`. Check the path and try again."
 - If found → Continue
 
 ### 2. Load Forge Tier
@@ -103,13 +107,13 @@ Load the following from the skill directory:
 
 ### 4. Load Provenance Map
 
-Search for provenance map at `{forge_data_folder}/{skill_name}/provenance-map.json`
+Search for provenance map at `{forge_data_folder}/{skill_name}/{active_version}/provenance-map.json` (i.e., `{forge_version}/provenance-map.json`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
 **If found:**
 - Load and extract: export list, file mappings, extraction timestamps, confidence tiers
 - Record provenance map age (days since last extraction)
 
-**If missing:**
+**If missing at both paths:**
 - "No provenance map found for `{skill_name}`. This skill may not have been created by create-skill."
 - "**Degraded mode available:** I can perform text-based comparison without provenance data. Findings will have T1-low confidence."
 - "**[D]egraded mode** — proceed with text-diff only"

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

@@ -3,7 +3,7 @@ name: 'step-02-re-index'
 description: 'Re-scan source code with current tier tools to build fresh extraction snapshot'
 
 nextStepFile: './step-03-structural-diff.md'
-outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
 
 # Step 2: Re-Index Source

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

@@ -3,7 +3,7 @@ name: 'step-03-structural-diff'
 description: 'Compare original provenance map extractions against current scan to detect structural drift'
 
 nextStepFile: './step-04-semantic-diff.md'
-outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
 
 # Step 3: Structural Diff

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

@@ -3,7 +3,7 @@ name: 'step-04-semantic-diff'
 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'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
 
 # Step 4: Semantic Diff

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

@@ -3,7 +3,7 @@ name: 'step-05-severity-classify'
 description: 'Grade every drift finding by severity using classification rules'
 
 nextStepFile: './step-06-report.md'
-outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
 severityRulesFile: '../data/severity-rules.md'
 ---
 

package/src/workflows/audit-skill/steps-c/step-06-report.md

@@ -2,7 +2,7 @@
 name: 'step-06-report'
 description: 'Finalize drift report with audit summary, remediation suggestions, and provenance metadata'
 
-outputFile: '{forge_data_folder}/{skill_name}/drift-report-{timestamp}.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
 
 # Step 6: Generate Report

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

@@ -22,7 +22,9 @@
 | doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
 | `scripts_intent` | string | `detect` / `none` / free-text | 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 | `detect` / `none` / free-text | 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/"). |
+| `target_version` | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable. |
 | `source_authority` | string | `official` / `community` / `internal` | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`. |
+| `source_ref` | string | Git ref (tag/branch/HEAD) | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -45,6 +47,8 @@ If detection succeeds, use the detected version. If it fails or returns a non-se
 
 The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
+**Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
+
 **Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
 
 ## Scope Object Structure
@@ -88,6 +92,8 @@ scope:
   exclude:
     - "{pattern}"
   notes: "{optional-scope-notes}"
+# target_version: "X.Y.Z"       # Optional: overrides auto-detection when specified
+# source_ref: "v0.5.0"          # Auto-resolved — do not set manually
 # Optional: documentation URLs for T3 content (required when source_type: "docs-only")
 # doc_urls:
 #   - url: "https://docs.example.com/api"
@@ -131,7 +137,12 @@ Assets:     {assets_intent}
 
 Source Authority: {source_authority}
 
+{If target_version is set:}
+Target Version:   {target_version} (user-specified)
+Detected Version: {detected_version or "N/A"}
+{Else:}
 Version:    {version}
+{End if}
 Created:    {created}
 Created by: {created_by}
 ```

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

@@ -96,7 +96,7 @@ Let's get started."
 Provide one of:
 - A **GitHub URL** (e.g., `https://github.com/org/repo`)
 - A **local path** (e.g., `/path/to/project`)
-- **Documentation URLs** for a docs-only skill (e.g., `https://docs.cognee.ai/`) — use this when no source code is available (SaaS, closed-source)
+- **Documentation URLs** for a docs-only skill (e.g., `https://docs.stripe.com/api`) — use this when no source code is available (SaaS, closed-source)
 
 **Target:**"
 
@@ -123,6 +123,26 @@ Default to `"community"` if user does not specify or skips. For `docs-only` skil
 
 Confirm the target.
 
+### 3b. Gather Target Version
+
+"**Are you targeting a specific version of this library?**
+(Leave blank to auto-detect from source)"
+
+{If source_type is "docs-only":}
+"Since this is a docs-only skill with no source code, specifying the version is recommended — otherwise it defaults to 1.0.0."
+
+Wait for user response.
+
+**If user provides a version:** Store as `target_version`. Set `version` to this value.
+**If blank:** Proceed without `target_version` — version will be auto-detected in step 02.
+
+{If target_version was set AND doc_urls are being collected (either docs-only primary or supplemental):}
+
+"**You're targeting version {target_version}. Do these documentation URLs correspond to that version?** [Y/N]"
+
+- **If Y:** Proceed.
+- **If N:** "Please provide the correct documentation URLs for version {target_version}." Re-collect doc_urls.
+
 ### 4. Gather User Intent
 
 "**What's your intent for this skill?**
@@ -167,6 +187,8 @@ Wait for confirmation or alternative.
 - **Skill name:** {confirmed name}
 - **Source type:** {source or docs-only}
 - **Source authority:** {official/community/internal}
+{If target_version set:}
+- **Target version:** {target_version} (user-specified)
 {If doc_urls collected:}
 - **Doc URLs:** {count} supplemental documentation URLs
 - **Forge tier:** {tier}
@@ -203,6 +225,7 @@ ONLY WHEN C is selected and target repository is confirmed will you load and rea
 - Skill name derived and confirmed
 - Scope hints noted (if provided)
 - Source type and source authority captured
+- Target version captured (if provided)
 - User ready to proceed to analysis
 
 ### ❌ SYSTEM FAILURE:

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

@@ -161,6 +161,10 @@ If CCC is unavailable or returns no results: skip this subsection silently.
 
 ### 4b. Detect Source Version
 
+**If `target_version` was provided in step 01:**
+- Display: "**Target version:** {target_version} (user-specified)"
+- Still run auto-detection below for informational purposes.
+
 Attempt to auto-detect the source version using the rules from the skill-brief-schema.md Version Detection section:
 
 **For Python:** Check `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
@@ -173,6 +177,12 @@ Attempt to auto-detect the source version using the rules from the skill-brief-s
 
 Display: "**Detected version:** {version or 'Not detected — will default to 1.0.0'}"
 
+{If target_version was provided AND auto-detected version differs:}
+"**Note:** Detected version ({detected_version}) differs from your target version ({target_version}). Using target version."
+
+{If target_version was provided:}
+Store `target_version` as the brief's `version` field (overrides auto-detection).
+
 If detection fails or returns a non-semver value: note that version will default to `"1.0.0"` and the user can override in step 04.
 
 ### 5. Report Analysis Summary

package/src/workflows/brief-skill/steps-c/step-04-confirm-brief.md

@@ -68,6 +68,7 @@ Compile all gathered data from steps 01-03 into the complete brief:
 
 - **name:** {skill name from step 01}
 - **version:** {auto-detected from source, or "1.0.0" if not found — see schema for detection rules}
+- **target_version:** {target_version from step 01, if set}
 - **source_repo:** {target repo from step 01}
 - **language:** {detected/confirmed language from steps 02-03}
 - **description:** {derived from user intent in step 01}
@@ -121,7 +122,12 @@ Assets:     {assets_intent}
 
 Source Authority: {source_authority}
 
+{If target_version is set:}
+Target Version: {target_version} (user-specified)
+Detected Version: {detected_version or "N/A"}
+{Else:}
 Version:    {version}
+
 Created:    {created}
 Created by: {created_by}
 ```
@@ -144,6 +150,9 @@ Flag any fields that may need review:
 {If any scope patterns seem broad or narrow:}
 "**Note:** {specific observation about scope breadth}."
 
+{If target_version is set AND detected_version exists AND they differ:}
+"**Note:** Target version ({target_version}) differs from detected source version ({detected_version}). The target version will be used for compilation."
+
 "**This is your last chance to make changes before writing the file.**
 
 You can:

package/src/workflows/brief-skill/steps-c/step-05-write-brief.md

@@ -67,12 +67,19 @@ If `{forge_data_folder}` is not set or doesn't exist:
 
 ### 3. Generate skill-brief.yaml
 
+**Resolve the `version` field before generating the YAML:**
+
+- If `target_version` was set in step 01 (the user explicitly asked for a specific version), use `target_version` as the value of the `version` field. This is the authoritative version for create-skill.
+- Otherwise, use the auto-detected source version from step 02, or `1.0.0` if none was detected.
+
+`target_version` and `version` must never carry different values in the written brief. When the user provided a `target_version`, also include it as a separate `target_version` field so downstream tooling can distinguish "user-requested" from "auto-detected" without re-deriving the provenance — but its value must be identical to `version`.
+
 Generate the YAML file using the approved field values and the schema template:
 
 ```yaml
 ---
 name: "{approved skill name}"
-version: "{detected source version or 1.0.0}"
+version: "{resolved version — target_version if set, else detected source version, else 1.0.0}"
 source_type: "{source or docs-only}"
 source_repo: "{approved source repo or doc site URL}"
 language: "{approved language}"
@@ -92,6 +99,12 @@ scope:
 
 **Conditional optional field inclusion:**
 
+**If `target_version` was set in step 01:**
+Include the `target_version` field in the generated YAML — its value MUST be identical to the `version` field above:
+```yaml
+target_version: "{target_version — same value as version}"
+```
+
 **If `source_type: "docs-only"` OR supplemental `doc_urls` were collected:**
 Include the `doc_urls` array (uncommented) in the generated YAML:
 ```yaml

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

@@ -196,6 +196,7 @@ 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}",
+  "source_ref": "{source_ref or null}",
   "confidence_tier": "{Quick|Forge|Forge+|Deep}",
   "spec_version": "1.3",
   "generation_date": "{ISO-8601}",
@@ -264,6 +265,7 @@ Each reference file includes:
   "skill_name": "{name}",
   "source_repo": "{url}",
   "source_commit": "{hash}",
+  "source_ref": "v0.5.0",
   "generated_at": "{ISO-8601}",
   "entries": [
     {