bmad-module-skill-forge 0.8.4 → 0.9.0

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

@@ -1,5 +1,37 @@
 # Source Resolution Protocols
 
+## Tag Resolution (when target_version is set)
+
+When `brief.target_version` is present AND `source_repo` is a remote URL, resolve the target version to a git tag before cloning:
+
+1. **List available tags:**
+   - `gh api repos/{owner}/{repo}/tags --paginate --jq '.[].name'`
+   - Fallback: `git ls-remote --tags {source_repo} | sed 's|.*refs/tags/||'`
+
+2. **Match `target_version` against tags** in priority order:
+   - **Exact match:** `{target_version}` (e.g., `0.5.0`)
+   - **With `v` prefix:** `v{target_version}` (e.g., `v0.5.0`)
+   - **With package scope (monorepos):** `{brief.name}@{target_version}` or `@{scope}/{brief.name}@{target_version}`
+
+3. **Resolution outcomes:**
+   - **Single match:** Store the matched tag as `source_ref`. Use it as `{branch}` in all subsequent clone/API commands.
+   - **Multiple matches:** Present the matching tags to the user — "Multiple tags match version {target_version}: {list}. Which one should I use?" Wait for selection.
+   - **Zero matches:** ⚠️ Warn: "No git tag found matching version {target_version}. Closest available tags: {list 5 nearest by semver sort}. Falling back to default branch — **extracted code may not match target version.**" Set `source_ref` to `HEAD` and proceed with default branch.
+
+4. **Store `source_ref`** in context. This value is written to metadata.json and provenance-map.json for downstream workflows (update-skill, audit-skill) to re-clone from the same ref.
+
+When `brief.target_version` is NOT set: skip tag resolution. Set `source_ref` to `HEAD` (default branch behavior, unchanged from before).
+
+### Local Source Warning
+
+When `brief.target_version` is set AND `source_repo` is a local path:
+
+⚠️ "**Local source may not match target version {target_version}.** Ensure you've checked out the correct version locally, or use a remote GitHub URL so SKF can clone from the git tag automatically."
+
+Proceed with local files as-is. Set `source_ref` to `"local"`.
+
+---
+
 ## Remote Source Resolution (Forge/Deep only)
 
 If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
@@ -8,17 +40,17 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
 1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
 
-2. **Ephemeral shallow clone:** Clone the repository to a system temp path for AST access:
+2. **Ephemeral shallow clone:** Clone the repository to a system temp path for AST access. Use `source_ref` from tag resolution (or `{branch}` for the default branch if no tag was resolved):
 
    ```
    temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
-   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none {source_repo} {temp_path}
+   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none {source_repo} {temp_path}
    ```
 
    **If `include_patterns` are NOT specified:**
 
    ```
-   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none {source_repo} {temp_path}
+   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none {source_repo} {temp_path}
    ```
 
    **If `include_patterns` ARE specified**, use sparse-checkout to limit the clone scope:
@@ -132,14 +164,18 @@ After the source path is accessible, capture the current commit hash for provena
 
 - **Local path:** `git -C {source_root} rev-parse HEAD` — if the path is a git repo
 - **Ephemeral clone (Forge/Deep):** already captured during clone (step 3 above)
-- **Quick tier (remote, no clone):** `gh api repos/{owner}/{repo}/commits/{branch} --jq '.sha'`
+- **Quick tier (remote, no clone):** `gh api repos/{owner}/{repo}/commits/{source_ref} --jq '.sha'`
 
 Store the result as `source_commit` in context. If capture fails (not a git repo, API unavailable), set `source_commit: null` — this is not an error.
 
+Also store `source_ref` in context (from tag resolution above, or `HEAD` if no tag was resolved, or `"local"` for local sources). This value is persisted to metadata.json and provenance-map.json so downstream workflows (update-skill, audit-skill) can re-access the same source ref.
+
 ---
 
 ## Version Reconciliation (all tiers, source mode only)
 
+**Target version override:** If `brief.target_version` is present, use it as the authoritative version for the skill. Do NOT warn about a brief-vs-source version mismatch — the user intentionally specified this version. Set the working version to `brief.target_version` and skip the rest of this reconciliation section. The `target_version` field indicates deliberate user intent (e.g., targeting an older version, or providing the version for a docs-only skill).
+
 **If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
 
 After the source path is accessible (local path from step-01, or ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:

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

@@ -47,7 +47,7 @@ To extract all public exports, function signatures, type definitions, and co-imp
 
 ## CONTEXT BOUNDARIES:
 
-- Available: brief_data, tier, source_root, file_tree from step-01; ecosystem check outcome from step-02 (proceed/halt decision — no named variable stored)
+- Available: brief_data, tier, source_root, file_tree from step-01; ecosystem check outcome from step-02; source_ref and source_commit from source resolution (see source-resolution-protocols.md)
 - Focus: Source code extraction and inventory building
 - Limits: Do NOT compile, assemble, or write any output
 - Dependencies: Source code must be accessible (local repos resolved in step-01; remote repos cloned in section 2a)

package/src/workflows/create-skill/steps-c/step-05-compile.md

@@ -101,6 +101,7 @@ Following the structure from the skill-sections data file:
 - Populate all fields from brief_data, extraction inventory, and tier
 - Set `generation_date` to current ISO-8601 timestamp
 - Set `source_commit` from resolved source (if available)
+- Set `source_ref` from resolved source ref (tag name, branch, or `HEAD`; null if unavailable)
 - Set `stats` from extraction aggregate counts:
   - `exports_documented`: count of exports with documentation in the assembled SKILL.md
   - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent) — derive this from step-03's entry-point validation (section 4b), NOT from the provenance-map entry count (which may be incomplete if extraction patterns missed some export types)

package/src/workflows/create-skill/steps-c/step-07-generate-artifacts.md

@@ -9,7 +9,7 @@ forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 
 ## STEP GOAL:
 
-To write all compiled content to disk — 4 deliverable files to `{skills_output_folder}/{name}/` and 3 workspace artifacts to `{forge_data_folder}/{name}/`, creating directories as needed.
+To write all compiled content to disk — 4 deliverable files to `{skill_package}` and 3 workspace artifacts to `{forge_version}`, creating directories as needed. Then create or update the `active` symlink.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -47,6 +47,7 @@ To write all compiled content to disk — 4 deliverable files to `{skills_output
 - Focus: File system operations — create directories, write files
 - Limits: Do NOT modify content during writing
 - Dependencies: All content must be compiled and validated in context
+- Path resolution: See `knowledge/version-paths.md` for canonical path templates (`{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`)
 
 ## MANDATORY SEQUENCE
 
@@ -54,65 +55,77 @@ To write all compiled content to disk — 4 deliverable files to `{skills_output
 
 ### 1. Create Directory Structure
 
-Create the following directories:
+Resolve `{version}` from the skill brief's `version` field. Create the following directories:
 
 ```
-{skills_output_folder}/{name}/
-{skills_output_folder}/{name}/references/
-{forge_data_folder}/{name}/
+{skill_group}                          # {skills_output_folder}/{name}/
+{skill_package}                        # {skills_output_folder}/{name}/{version}/{name}/
+{skill_package}/references/
+{forge_version}                        # {forge_data_folder}/{name}/{version}/
 ```
 
-If `scripts_inventory` is non-empty, also create: `{skills_output_folder}/{name}/scripts/`
-If `assets_inventory` is non-empty, also create: `{skills_output_folder}/{name}/assets/`
+If `scripts_inventory` is non-empty, also create: `{skill_package}/scripts/`
+If `assets_inventory` is non-empty, also create: `{skill_package}/assets/`
 
-Where `{name}` is the skill name from the brief (kebab-case).
+Where `{name}` is the skill name from the brief (kebab-case) and `{version}` is the semver version from the brief (with build metadata stripped per `knowledge/version-paths.md`).
 
 If directories already exist, do not error — proceed with file writing (overwrites existing files).
 
-### 2. Write Deliverables to {skills_output_folder}/{name}/
+### 2. Write Deliverables to {skill_package}
 
 Write these 4 files from the compiled content:
 
-**File 1:** `{skills_output_folder}/{name}/SKILL.md`
+**File 1:** `{skill_package}/SKILL.md`
 - The complete compiled skill document
 - agentskills.io-compliant format with all sections
 - [MANUAL] markers seeded
 
-**File 2:** `{skills_output_folder}/{name}/context-snippet.md`
+**File 2:** `{skill_package}/context-snippet.md`
 - Compressed 2-line format for CLAUDE.md integration
 
-**File 3:** `{skills_output_folder}/{name}/metadata.json`
+**File 3:** `{skill_package}/metadata.json`
 - Machine-readable birth certificate with stats and provenance
 
-**File 4:** `{skills_output_folder}/{name}/references/*.md`
+**File 4:** `{skill_package}/references/*.md`
 - One file per function group or type
 - Progressive disclosure detail files
 
-**Files 4b (conditional):** `{skills_output_folder}/{name}/scripts/*`
+**Files 4b (conditional):** `{skill_package}/scripts/*`
 - One file per detected script, copied from source with content preserved
 - Only created when `scripts_inventory` is non-empty
 
-**Files 4c (conditional):** `{skills_output_folder}/{name}/assets/*`
+**Files 4c (conditional):** `{skill_package}/assets/*`
 - One file per detected asset, copied from source with content preserved
 - Only created when `assets_inventory` is non-empty
 
-### 3. Write Workspace Artifacts to {forge_data_folder}/{name}/
+### 3. Write Workspace Artifacts to {forge_version}
 
 Write these 3 files from the compiled content:
 
-**File 5:** `{forge_data_folder}/{name}/provenance-map.json`
+**File 5:** `{forge_version}/provenance-map.json`
 - Per-claim source map with AST bindings and confidence tiers
 
-**File 6:** `{forge_data_folder}/{name}/evidence-report.md`
+**File 6:** `{forge_version}/evidence-report.md`
 - Build artifact with extraction summary, validation results, warnings
 
-**File 7:** `{forge_data_folder}/{name}/extraction-rules.yaml`
+**File 7:** `{forge_version}/extraction-rules.yaml`
 - Language and ast-grep schema used for this extraction (for reproducibility)
 
-### 4. Verify Write Completion
+### 4. Create Active Symlink
+
+Create or update the `active` symlink at `{skill_group}/active` pointing to `{version}`:
+
+```
+{skill_group}/active -> {version}
+```
+
+If the symlink already exists, remove it first and recreate. This ensures `{skill_group}/active/{name}/` resolves to the just-written skill package.
+
+### 5. Verify Write Completion
 
 After all files are written, verify:
 - All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, at least one file in references/), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
+- The `active` symlink at `{skill_group}/active` resolves to `{version}`
 - Store `ref_count` = count of files written to `references/` for use in step-08 report
 - List each file with its path and size
 
@@ -124,7 +137,7 @@ Display brief confirmation:
 
 "**Artifacts generated.**
 
-**Deliverables ({skills_output_folder}/{name}/):**
+**Deliverables ({skill_package}):**
 - SKILL.md
 - context-snippet.md
 - metadata.json
@@ -132,14 +145,16 @@ Display brief confirmation:
 {if assets: - assets/ ({assets_count} files)}
 - references/ ({reference_count} files)
 
-**Workspace ({forge_data_folder}/{name}/):**
+**Workspace ({forge_version}):**
 - provenance-map.json
 - evidence-report.md
 - extraction-rules.yaml
 
+**Symlink:** {skill_group}/active -> {version}
+
 Proceeding to compilation report..."
 
-### 5. QMD Collection Registration (Deep Tier Only)
+### 6. QMD Collection Registration (Deep Tier Only)
 
 **IF forge tier is Deep AND QMD tool is available:**
 
@@ -148,7 +163,7 @@ Index the generated skill artifacts into a QMD collection so that audit-skill an
 **Collection creation:** Create (or replace) a QMD collection from the skill artifacts:
 ```bash
 qmd collection remove {name}-extraction 2>/dev/null  # no-op if new
-qmd collection add {skills_output_folder}/{name} --name {name}-extraction --mask "**/*"
+qmd collection add {skill_package} --name {name}-extraction --mask "**/*"
 qmd embed  # generates vector embeddings for vector_search/deep_search
 ```
 
@@ -174,7 +189,7 @@ Write the updated forge-tier.yaml.
 
 **IF forge tier is NOT Deep:** Skip this section silently. No messaging.
 
-### 5b. CCC Index Registry Registration (Forge+ and Deep with ccc)
+### 6b. CCC Index Registry Registration (Forge+ and Deep with ccc)
 
 **IF `tools.ccc` is true in forge-tier.yaml (Forge+ or Deep with ccc available):**
 
@@ -204,7 +219,7 @@ Write the updated forge-tier.yaml.
 
 **IF `tools.ccc` is false:** Skip this section silently.
 
-### 6. Menu Handling Logic
+### 7. Menu Handling Logic
 
 **Auto-proceed step — no user interaction.**
 
@@ -220,7 +235,7 @@ After all artifacts are written, verified, and optionally indexed into QMD, imme
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN all 7 artifact files are written and verified will you proceed to load `{nextStepFile}` for the compilation report.
+ONLY WHEN all 7 artifact files are written, the active symlink is created, and verification is complete will you proceed to load `{nextStepFile}` for the compilation report.
 
 ---
 
@@ -228,10 +243,11 @@ ONLY WHEN all 7 artifact files are written and verified will you proceed to load
 
 ### ✅ SUCCESS:
 
-- Directory structure created ({skills_output_folder}/{name}/, {forge_data_folder}/{name}/)
-- All 4 deliverable files written to {skills_output_folder}/{name}/
-- All 3 workspace artifact files written to {forge_data_folder}/{name}/
-- Write completion verified — all 7 files exist
+- Directory structure created ({skill_group}, {skill_package}, {forge_version})
+- All 4 deliverable files written to {skill_package}
+- All 3 workspace artifact files written to {forge_version}
+- Active symlink created at {skill_group}/active -> {version}
+- Write completion verified — all 7 files exist and symlink resolves
 - Deep tier: QMD collection `{name}-extraction` created/updated and registered in forge-tier.yaml
 - Non-Deep tier: QMD indexing skipped silently
 - Brief confirmation displayed with file list
@@ -246,4 +262,4 @@ ONLY WHEN all 7 artifact files are written and verified will you proceed to load
 - Not verifying all files were written
 - Failing the workflow due to QMD indexing errors (should degrade gracefully)
 
-**Master Rule:** This step writes artifacts and registers QMD collections. All content was compiled and validated in previous steps. Write faithfully, verify completely. QMD indexing failures never block the workflow.
+**Master Rule:** This step writes artifacts, creates the active symlink, and registers QMD collections. All content was compiled and validated in previous steps. Write faithfully, verify completely. QMD indexing failures never block the workflow.

package/src/workflows/create-skill/steps-c/step-08-report.md

@@ -77,13 +77,14 @@ Where `{primary_confidence}` is the predominant confidence tier (T1 if Forge/Dee
 | T3 (External) | {t3_count} | Sourced from external documentation URLs |
 
 **Output Files:**
-- `{skills_output_folder}/{name}/SKILL.md` — Active skill with trigger-based usage
-- `{skills_output_folder}/{name}/context-snippet.md` — Passive context for CLAUDE.md
-- `{skills_output_folder}/{name}/metadata.json` — Machine-readable birth certificate
-- `{skills_output_folder}/{name}/references/` — Progressive disclosure ({ref_count} files)
-- `{forge_data_folder}/{name}/provenance-map.json` — Source map with AST bindings
-- `{forge_data_folder}/{name}/evidence-report.md` — Build audit trail
-- `{forge_data_folder}/{name}/extraction-rules.yaml` — Reproducible extraction schema"
+- `{skill_package}/SKILL.md` — Active skill with trigger-based usage
+- `{skill_package}/context-snippet.md` — Passive context snippet (used by export-skill)
+- `{skill_package}/metadata.json` — Machine-readable birth certificate
+- `{skill_package}/references/` — Progressive disclosure ({ref_count} files)
+- `{forge_version}/provenance-map.json` — Source map with AST bindings
+- `{forge_version}/evidence-report.md` — Build audit trail
+- `{forge_version}/extraction-rules.yaml` — Reproducible extraction schema
+- `{skill_group}/active` -> `{version}` — Symlink to current version"
 
 ### 3. Display Warnings (If Any)
 

package/src/workflows/create-stack-skill/data/compose-mode-rules.md

@@ -4,12 +4,18 @@ Rules for synthesizing a stack skill from pre-generated individual skills and an
 
 ## Skill Loading
 
-1. Scan `{skills_output_folder}` for subdirectories containing both `SKILL.md` and `metadata.json`
-2. **Filter:** Skip any subdirectory named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops
-3. Skip any subdirectory missing either `SKILL.md` or `metadata.json` — log a warning and skip
-4. Load each `metadata.json` and extract: `name`, `language`, `confidence_tier`, `source_repo`, `exports` (count), `version`
-5. Store the subdirectory name as `skill_dir` (distinct from `name` — the directory may differ from the metadata name)
-6. Store loaded skills as `raw_dependencies` with `source: "existing_skill"`
+Skills use version-nested directories — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for the full path templates and resolution rules.
+
+**Version-aware skill enumeration:**
+
+1. **Primary: Export manifest** — Read `{skills_output_folder}/.export-manifest.json`. For each entry in `exports`, resolve the active version path: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` — this directory must contain both `SKILL.md` and `metadata.json`.
+2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, or a manifest entry lacks an `active_version`, scan for `{skills_output_folder}/*/active/*/SKILL.md`. Each match resolves to a skill package at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
+3. **Filter:** Skip any skill named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops
+4. Skip any resolved skill package missing either `SKILL.md` or `metadata.json` — log a warning and skip
+5. Load each `metadata.json` from the resolved version-aware path and extract: `name`, `language`, `confidence_tier`, `source_repo`, `exports` (count), `version`
+6. Store the skill group directory name as `skill_dir` (the top-level name under `{skills_output_folder}`, distinct from `name` — the directory may differ from the metadata name)
+7. Store the resolved package path as `skill_package_path` for use in later steps (extraction, integration detection)
+8. Store loaded skills as `raw_dependencies` with `source: "existing_skill"`
 
 ## Architecture Integration Mapping
 

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

@@ -106,8 +106,11 @@ Check if the user provided:
 
 Set `compose_mode: false` as the default.
 
+Skills use version-nested directories — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for the full path templates and resolution rules.
+
 - If user provides an architecture document path for composition or explicitly requests compose mode → set `compose_mode: true` and store `architecture_doc_path`
-- If no manifest files exist in project root AND at least one subdirectory in `{skills_output_folder}` contains both `SKILL.md` and `metadata.json` → suggest compose mode to the user and ask for optional architecture document path
+- If no manifest files exist in project root AND at least one skill is discoverable in `{skills_output_folder}` → suggest compose mode to the user and ask for optional architecture document path
+  - **Skill discovery (version-aware):** First, read `{skills_output_folder}/.export-manifest.json` — each entry in `exports` names a skill with an `active_version`, which resolves to `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` containing `SKILL.md` and `metadata.json`. If the export manifest does not exist or is empty, fall back to scanning for `active` symlinks: check `{skills_output_folder}/*/active/*/SKILL.md` — each match indicates a skill whose package lives at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
   - If user accepts → set `compose_mode: true` and store `architecture_doc_path` (may be `null` if user chose not to provide one)
   - If user declines → `compose_mode` remains `false`, continue with code-mode
 

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

@@ -58,17 +58,23 @@ Use the explicit dependency list directly. Store the explicit list as `raw_depen
 
 **If `compose_mode` is true AND `explicit_deps` was NOT provided:**
 
-Scan `{skills_output_folder}` for subdirectories containing SKILL.md and metadata.json.
+Discover skills in `{skills_output_folder}` using version-aware resolution — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for path templates.
 
-**Filter:** Skip any subdirectory named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops.
+**Version-aware skill enumeration:**
+
+1. **Primary: Export manifest** — Read `{skills_output_folder}/.export-manifest.json`. For each entry in `exports`, resolve the active version path: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` — this directory must contain both `SKILL.md` and `metadata.json`.
+2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, or a manifest entry lacks an `active_version`, scan for `{skills_output_folder}/*/active/*/SKILL.md`. Each match resolves to a skill package at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
+
+**Filter:** Skip any skill named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops.
 
 **If zero skills remain after filtering:** HALT with: "**Cannot proceed in compose-mode.** No individual skills found in `{skills_output_folder}` (after filtering stack skills). Run [CS] Create Skill or [QS] Quick Skill to generate individual skills first, then re-run [SS]."
 
 For each skill found:
-1. Read metadata.json
+1. Read `metadata.json` from the resolved version-aware path (`{skill_package}` or `{active_skill}`)
 2. Extract: name, language, confidence_tier, source_repo, exports count, version
-3. Store the subdirectory name as `skill_dir` (distinct from `name` — the directory may differ from the metadata name)
-4. Store as `raw_dependencies` with source: "existing_skill"
+3. Store the skill group directory name as `skill_dir` (the top-level name under `{skills_output_folder}`, distinct from `name` — the directory may differ from the metadata name)
+4. Store the resolved package path as `skill_package_path` for use in later steps
+5. Store as `raw_dependencies` with source: "existing_skill"
 
 Display:
 "**Loaded {N} existing skills as dependencies.**

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

@@ -56,7 +56,7 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 "**Extraction data already available from individual skills. Skipping extraction phase.**"
 
-For each confirmed skill, load `{skills_output_folder}/{skill_dir}/SKILL.md` (where `skill_dir` is the subdirectory name stored in step-02, which may differ from the `name` field in metadata.json) into context. Build a `per_library_extractions[]` entry for each skill with the following fields:
+For each confirmed skill, load SKILL.md from the version-aware path resolved in step-02. Use `skill_package_path` (stored in step-02) directly — this already points to the resolved `{skill_package}` or `{active_skill}` directory containing the skill's artifacts. If `skill_package_path` is not available, resolve via the `{active_skill}` template: `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)). Build a `per_library_extractions[]` entry for each skill with the following fields:
 - `library`: skill name from metadata.json
 - `exports`: exports list extracted from the SKILL.md exports section
 - `usage_patterns`: usage patterns from the SKILL.md usage section

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

@@ -81,7 +81,7 @@ All integration evidence inherits confidence tiers from the source skills. Load
 **VS verdict parsing (if feasibility report exists):** Read the `overall_verdict` from the report's YAML frontmatter. Parse the `## Integration Verdicts` markdown table for per-pair verdicts. For each architecture-detected pair, include `VS overall: {verdict}` and `VS pair: {verdict}` in the integration evidence per the format in `{composeModeRules}`. VS verdicts do not apply to inferred integrations since the VS report operates on architecture-described interactions only. Additionally, flag any pairs where VS reported `Risky` or `Blocked` by appending a `[VS: Risky]` or `[VS: Blocked]` warning annotation to the integration entry.
 
 If no architecture document available:
-- Infer potential integrations from skills sharing the same `language` field or sharing domain keywords in their SKILL.md descriptions (use the `usage_patterns` and `exports` fields from `per_library_extractions[]` built in step-04, or reload `{skills_output_folder}/{skill_dir}/SKILL.md` if full prose text is needed for keyword extraction)
+- Infer potential integrations from skills sharing the same `language` field or sharing domain keywords in their SKILL.md descriptions (use the `usage_patterns` and `exports` fields from `per_library_extractions[]` built in step-04, or reload SKILL.md from the version-aware path: use `skill_package_path` from step-02, or resolve via `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` — see [knowledge/version-paths.md](../../../knowledge/version-paths.md))
 - Mark inferred integrations: `[inferred from shared domain]` — use this suffix instead of `[composed]` for inferred integrations
 - Inferred integrations qualify automatically — no file-count threshold applies
 

package/src/workflows/create-stack-skill/steps-c/step-07-generate-output.md

@@ -47,6 +47,7 @@ Write all deliverable and workspace artifact files to their target directories.
 - From step 05: integration_graph for integration pair references
 - From step 01: forge_tier, project info for metadata
 - This step produces: written_files[] (all output artifacts)
+- Path resolution: See `knowledge/version-paths.md` for canonical path templates. Stack skills use `{project_name}-stack` as the skill name
 
 ## MANDATORY SEQUENCE
 
@@ -54,27 +55,30 @@ Write all deliverable and workspace artifact files to their target directories.
 
 ### 1. Create Output Directories
 
-Create the directory structure:
+Resolve `{version}` from the primary library version or default to `1.0.0`. Create the directory structure:
 
 ```
-{skills_output_folder}/{project_name}-stack/
+{skill_group}                          # {skills_output_folder}/{project_name}-stack/
+{skill_package}                        # {skills_output_folder}/{project_name}-stack/{version}/{project_name}-stack/
 ├── references/
 │   └── integrations/
 ```
 
 ```
-{forge_data_folder}/{project_name}-stack/
+{forge_version}                        # {forge_data_folder}/{project_name}-stack/{version}/
 ```
 
+Where the skill name is `{project_name}-stack` and `{version}` is the semver version (with build metadata stripped per `knowledge/version-paths.md`).
+
 If directories already exist, proceed (overwrite previous output).
 
 ### 2. Write SKILL.md
 
-Write `{skills_output_folder}/{project_name}-stack/SKILL.md` with the approved skill_content from step 06.
+Write `{skill_package}/SKILL.md` with the approved skill_content from step 06.
 
 ### 3. Write Per-Library Reference Files
 
-For each confirmed library, write `{skills_output_folder}/{project_name}-stack/references/{library_name}.md`:
+For each confirmed library, write `{skill_package}/references/{library_name}.md`:
 
 Load structure from `{stackSkillTemplate}` references section:
 - Library name, version from manifest (**in compose-mode**: version from source skill `metadata.json`)
@@ -85,7 +89,7 @@ Load structure from `{stackSkillTemplate}` references section:
 
 ### 4. Write Integration Pair Reference Files
 
-For each detected integration pair, write `{skills_output_folder}/{project_name}-stack/references/integrations/{libraryA}-{libraryB}.md`:
+For each detected integration pair, write `{skill_package}/references/integrations/{libraryA}-{libraryB}.md`:
 
 Load structure from `{stackSkillTemplate}` integrations section:
 - Library pair and integration type
@@ -98,7 +102,7 @@ Load structure from `{stackSkillTemplate}` integrations section:
 
 ### 5. Write context-snippet.md
 
-Write `{skills_output_folder}/{project_name}-stack/context-snippet.md`:
+Write `{skill_package}/context-snippet.md`:
 
 Use the Vercel-aligned indexed format targeting ~80-120 tokens:
 ```
@@ -111,7 +115,7 @@ Use the Vercel-aligned indexed format targeting ~80-120 tokens:
 
 ### 6. Write metadata.json
 
-Write `{skills_output_folder}/{project_name}-stack/metadata.json`:
+Write `{skill_package}/metadata.json`:
 
 Populate all fields from the metadata.json schema defined in `{stackSkillTemplate}`:
 
@@ -155,7 +159,7 @@ Populate all fields from the metadata.json schema defined in `{stackSkillTemplat
 
 ### 7. Write Forge Data Artifacts
 
-Write workspace artifacts to `{forge_data_folder}/{project_name}-stack/`:
+Write workspace artifacts to `{forge_version}`:
 
 **provenance-map.json:**
 
@@ -208,26 +212,38 @@ Write workspace artifacts to `{forge_data_folder}/{project_name}-stack/`:
 - Warnings and failures encountered
 - Confidence tier distribution
 
-### 8. Display Write Summary
+### 8. Create Active Symlink
+
+Create or update the `active` symlink at `{skill_group}/active` pointing to `{version}`:
+
+```
+{skill_group}/active -> {version}
+```
+
+If the symlink already exists, remove it first and recreate. This ensures `{skill_group}/active/{project_name}-stack/` resolves to the just-written skill package.
+
+### 9. Display Write Summary
 
 "**Output files written.**
 
-**Deliverables** ({skills_output_folder}/{project_name}-stack/):
-- ✓ SKILL.md ({line_count} lines)
-- ✓ context-snippet.md ({token_estimate} tokens)
-- ✓ metadata.json
-- ✓ references/ — {lib_count} library files
-- ✓ references/integrations/ — {pair_count} integration files
+**Deliverables** ({skill_package}):
+- SKILL.md ({line_count} lines)
+- context-snippet.md ({token_estimate} tokens)
+- metadata.json
+- references/ -- {lib_count} library files
+- references/integrations/ -- {pair_count} integration files
+
+**Workspace** ({forge_version}):
+- provenance-map.json
+- evidence-report.md
 
-**Workspace** ({forge_data_folder}/{project_name}-stack/):
-- ✓ provenance-map.json
-- ✓ evidence-report.md
+**Symlink:** {skill_group}/active -> {version}
 
 **Total files written:** {total_count}
 
 **Proceeding to validation...**"
 
-### 9. Auto-Proceed to Next Step
+### 10. Auto-Proceed to Next Step
 
 Load, read the full file and then execute `{nextStepFile}`.
 
@@ -237,9 +253,10 @@ Load, read the full file and then execute `{nextStepFile}`.
 
 ### ✅ SUCCESS:
 
-- All deliverable files written to skills_output_folder
-- All workspace artifacts written to forge_data_folder
-- Directory structure created correctly
+- All deliverable files written to {skill_package}
+- All workspace artifacts written to {forge_version}
+- Directory structure created correctly with version nesting
+- Active symlink created at {skill_group}/active -> {version}
 - Each file matches its template structure
 - Write summary displayed with accurate counts
 

package/src/workflows/create-stack-skill/steps-c/step-08-validate.md

@@ -55,17 +55,20 @@ Validate all written output files against their expected structure and verify co
 
 Check that all expected files exist from written_files[]:
 
-**Deliverables** (`{skills_output_folder}/{project_name}-stack/`):
+**Deliverables** (`{skill_package}`):
 - [ ] SKILL.md
 - [ ] context-snippet.md
 - [ ] metadata.json
 - [ ] references/ directory with per-library files
 - [ ] references/integrations/ directory with pair files (if integrations detected)
 
-**Workspace** (`{forge_data_folder}/{project_name}-stack/`):
+**Workspace** (`{forge_version}`):
 - [ ] provenance-map.json
 - [ ] evidence-report.md
 
+**Symlink:**
+- [ ] `{skill_group}/active` exists and resolves to `{version}`
+
 Record any missing files as **ERROR** findings.
 
 ### 2. Check Tool Availability
@@ -140,7 +143,7 @@ Record missing tier labels as **WARNING** findings.
 ### 8. Validate context-snippet.md
 
 Verify context-snippet.md follows Vercel-aligned indexed format:
-- [ ] First line matches: `[{project}-stack v{version}]|root: skills/{project}-stack/`
+- [ ] First line matches: `[{project}-stack v{version}]|root: {prefix}{project}-stack/` where prefix is `skills/` or a platform root (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`)
 - [ ] Second line starts with `|IMPORTANT:`
 - [ ] Stack and integrations lines present
 - [ ] Approximate token count is ~80-120 tokens

package/src/workflows/create-stack-skill/steps-c/step-09-report.md

@@ -74,16 +74,18 @@ Forge tier: **{tier}**"
 
 "**Output files:**
 
-**Deliverables** (`{skills_output_folder}/{project_name}-stack/`):
+**Deliverables** (`{skill_package}`):
 - SKILL.md — Integration patterns, library summaries, conventions
 - context-snippet.md — Compressed stack index ({token_estimate} tokens)
 - metadata.json — Skill metadata and library registry
 - references/ — {lib_count} per-library reference files
 {If integrations:} - references/integrations/ — {pair_count} integration pair files
 
-**Workspace** (`{forge_data_folder}/{project_name}-stack/`):
+**Workspace** (`{forge_version}`):
 - provenance-map.json — Extraction source tracking
-- evidence-report.md — Evidence and confidence breakdown"
+- evidence-report.md — Evidence and confidence breakdown
+
+**Symlink:** `{skill_group}/active` -> `{version}`"
 
 ### 4. Display Validation Summary