bmad-module-skill-forge 0.8.4 → 0.10.0

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

@@ -3,6 +3,7 @@ name: 'step-05-write-brief'
 description: 'Generate and write skill-brief.yaml to the forge data folder'
 
 briefSchemaFile: '../data/skill-brief-schema.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 5: Write Brief
@@ -67,12 +68,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 +100,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
@@ -203,13 +217,13 @@ After compilation, you can:
 
 **Brief-skill workflow complete.**"
 
-### 7. End Workflow
+### 7. Workflow Health Check
 
-This is the final step. No next step file to load. The workflow is complete.
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the FINAL step of the brief-skill workflow. After writing the file and displaying the success summary, the workflow ends.
+This step chains to the shared health check. After the health check completes, the brief-skill workflow is fully done.
 
 ---
 

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": [
     {

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

@@ -1,6 +1,7 @@
 ---
 name: 'step-08-report'
 description: 'Display compilation summary with confidence tiers, suggest next steps'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 8: Report
@@ -77,13 +78,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)
 
@@ -136,17 +138,19 @@ Set `batch_active: false` in `{sidecar_path}/batch-state.yaml` to prevent stale
 
 End workflow. No further steps.
 
-### 6. Workflow Complete
+### 6. Workflow Health Check
 
-This is the final step. No `{nextStepFile}` to load.
+**If not batch mode (or all batch briefs complete):**
 
-Display: "Forge session complete. Return to Ferris menu for further actions."
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
+**If batch mode with remaining briefs:** Skip health check — loop back to step-01 for the next brief. Health check runs after the final brief in the batch.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the FINAL STEP of the create-skill workflow. After displaying the compilation report and next steps, the workflow is complete. No further steps are loaded.
+This step chains to the shared health check (unless batch mode loops back to step-01). After the health check completes, the create-skill workflow is fully done.
 
-For batch mode: loop back to step-01 for remaining briefs via sidecar checkpoint.
+For batch mode: loop back to step-01 for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
 
 ---
 

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