bmad-module-skill-forge 0.8.3 → 0.9.0

package/src/workflows/update-skill/data/remote-source-resolution.md

@@ -6,21 +6,35 @@ If `source_root` (from metadata.json) is a remote URL (GitHub URL or owner/repo
 
 1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
 
-2. **Ephemeral sparse clone:** Clone only the changed files from the change manifest to a system temp path. Note: at this point in the flow, `{source_root}` is known to be a remote URL (the local-path case was already handled above).
+2. **Resolve source ref:** Read `source_ref` from the existing `metadata.json`. If the user provided a new `target_version`, resolve its tag first (using the Tag Resolution algorithm in `create-skill/data/source-resolution-protocols.md`).
+
+3. **Ephemeral sparse clone:** Clone only the changed files from the change manifest to a system temp path. Note: at this point in the flow, `{source_root}` is known to be a remote URL (the local-path case was already handled above).
 
    ```
    temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
+   ```
+
+   If `source_ref` exists and is not `HEAD`/null/`"local"`:
+   ```
+   git clone --depth 1 --branch {source_ref} --single-branch --filter=blob:none --sparse {source_root} {temp_path}
+   ```
+
+   If `source_ref` is `HEAD`/null/`"local"` (or absent):
+   ```
    git clone --depth 1 --single-branch --filter=blob:none --sparse {source_root} {temp_path}
+   ```
+
+   ```
    git -C {temp_path} sparse-checkout set --skip-checks {changed_files_from_manifest}
    ```
 
    **Note:** `--skip-checks` is required because `changed_files_from_manifest` contains individual file paths (e.g., `src/core/parser.py`), not directories. Without this flag, `git sparse-checkout set` rejects non-directory entries.
 
-   No `--branch` flag is used — the clone targets the remote's default branch, which must match the branch used during the original [CS] Create Skill run. This scopes the clone to only the files identified in step-02's change manifest, avoiding a full repository download.
+   When `source_ref` is a tag (e.g., `v0.5.0`), the clone targets that specific tag to ensure update-skill extracts from the same source version as the original create-skill run. When `source_ref` is `HEAD`, null, or `"local"`, no `--branch` flag is used — the clone targets the remote's default branch. This scopes the clone to only the files identified in step-02's change manifest, avoiding a full repository download.
 
-3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
+4. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
 
-4. **If clone fails (network error, auth failure, timeout):**
+5. **If clone fails (network error, auth failure, timeout):**
 
    Warning message: "Ephemeral clone of `{source_root}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and re-run [CS] Create Skill with the local path, then re-run this update."
 

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

@@ -60,25 +60,32 @@ Load the existing skill and all its provenance data, detect whether this is an i
 "**Which skill would you like to update?**
 
 Provide either:
-- A skill name (resolves to `{skills_output_folder}/{name}/`)
+- A skill name (resolves via version-aware path resolution — see [knowledge/version-paths.md](../../../knowledge/version-paths.md))
 - A full path to the skill folder
 - A skill name with `--from-test-report` to use the test report's gap findings instead of source drift detection
 
 **Skill:** {user provides path or name}"
 
+**Version-Aware Path Resolution:**
+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}` for all subsequent artifact loading
+
 Resolve the path to an absolute skill folder location.
 
 **If `--from-test-report` was provided (or user references a test report):**
-Search for the test report at `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`. If found, set `test_report_path` in context and `update_mode: gap-driven`. If not found, warn and continue with normal source drift mode.
+Search for the test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`. If found, set `test_report_path` in context and `update_mode: gap-driven`. If not found at either path, warn and continue with normal source drift mode.
 
 ### 2. Validate Required Artifacts
 
 **Check SKILL.md exists:**
-- Load `{resolved_skill_path}/SKILL.md`
-- If missing: **ABORT** — "No SKILL.md found at `{resolved_skill_path}`. Run create-skill first."
+- Load `{resolved_skill_package}/SKILL.md`
+- If missing: **ABORT** — "No SKILL.md found at `{resolved_skill_package}`. Run create-skill first."
 
 **Check metadata.json exists:**
-- Load `{resolved_skill_path}/metadata.json`
+- Load `{resolved_skill_package}/metadata.json`
 - Extract: `name`, `skill_type` (single or stack), `version`, `generation_date`, `confidence_tier`, `source_root`
 - If missing: **ABORT** — "No metadata.json found. This skill may have been created manually. Run create-skill to generate provenance data."
 
@@ -102,13 +109,13 @@ Search for the test report at `{forge_data_folder}/{skill_name}/test-report-{ski
 
 ### 4. Load Provenance Map
 
-**Load `{forge_data_folder}/{skill_name}/provenance-map.json`:**
+**Load `{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`:
 - Extract: export list, file mappings, extraction timestamps, confidence tiers
 - Calculate provenance age (days since last extraction)
 
-**If provenance map missing:**
+**If provenance map missing at both paths:**
 
-"**WARNING:** No provenance map found at `{forge_data_folder}/{skill_name}/provenance-map.json`.
+"**WARNING:** No provenance map found at `{forge_version}/provenance-map.json` or flat fallback.
 
 Without a provenance map, update-skill cannot perform targeted change detection. Options:
 

package/src/workflows/update-skill/steps-c/step-06-write.md

@@ -49,6 +49,7 @@ Write all updated skill artifacts to disk: the merged SKILL.md, updated provenan
 - Focus: file I/O operations — write and verify
 - Limits: write only to skill output and forge data directories
 - Dependencies: steps 02-05 must all be complete
+- Path resolution: See `knowledge/version-paths.md` for canonical path templates (`{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`)
 
 ## MANDATORY SEQUENCE
 
@@ -56,14 +57,16 @@ Write all updated skill artifacts to disk: the merged SKILL.md, updated provenan
 
 ### 1. Write Updated SKILL.md
 
-Write the merged SKILL.md content to `{skills_output_folder}/{skill_name}/SKILL.md`:
+Write the merged SKILL.md content to `{skill_package}/SKILL.md`:
 - Overwrite the existing file with merged content
 - Preserve file encoding (UTF-8)
 - Verify write by reading back and confirming [MANUAL] section count matches expected
 
+If the version changed (source version differs from the previous metadata version), write to the new `{skill_package}` (creating the version directory if needed). The previous version's directory is preserved on disk.
+
 ### 2. Write Updated metadata.json
 
-Update `{skills_output_folder}/{skill_name}/metadata.json`:
+Update `{skill_package}/metadata.json`:
 - Update `version`: if a source version was detected during re-extraction and differs from the current metadata version, use the source version; otherwise increment patch version
 - Update `generation_date` timestamp to current ISO-8601 date
 - Update `exports` array to reflect current export list
@@ -81,7 +84,7 @@ Update `{skills_output_folder}/{skill_name}/metadata.json`:
 
 ### 3. Write Updated provenance-map.json
 
-Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
+Write to `{forge_version}/provenance-map.json`:
 
 **For each export in the updated skill:**
 - Update `export_name` if renamed
@@ -117,7 +120,7 @@ Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
 ### 4. Write Updated evidence-report.md
 
-Append update operation section to `{forge_data_folder}/{skill_name}/evidence-report.md` (create the file with a standard header if it does not yet exist):
+Append update operation section to `{forge_version}/evidence-report.md` (create the file with a standard header if it does not yet exist):
 
 ```markdown
 ## Update Operation — {current_date}
@@ -146,17 +149,43 @@ Append update operation section to `{forge_data_folder}/{skill_name}/evidence-re
 - Provenance: {PASS/WARN/FAIL}
 ```
 
-### 5. Write Stack Skill Reference Files (Conditional)
+### 5. Write Stack Skill Reference Files (Conditional) and Regenerate context-snippet.md
 
 **ONLY if skill_type == "stack":**
 
 For each affected reference file from the merge:
 - Write updated `references/{library}.md` files
 - Write updated `references/integrations/{pair}.md` files
-- Regenerate `context-snippet.md` with updated export summaries
 - Verify [MANUAL] sections preserved in each reference file
 
-**If skill_type != "stack":** Skip reference file updates. However, if exports changed (added, removed, or renamed), warn: "⚠️ `context-snippet.md` was NOT updated — exports have changed. Run **[EX] Export Skill** to regenerate the context snippet and update CLAUDE.md/AGENTS.md."
+**For all skills (both single and stack) — regenerate `context-snippet.md`:**
+
+Per `knowledge/version-paths.md` "Writing Workflows (CS, QS, SS, US)", update-skill is a writing workflow that MUST write all deliverables to `{skill_package}`. `context-snippet.md` is one of those deliverables and goes stale whenever exports, version, or gotchas change.
+
+Regenerate the snippet using the format from the matching template file:
+
+- For single skills: `create-skill/data/skill-sections.md` (pipe-delimited indexed format)
+- For stack skills: `create-stack-skill/data/stack-skill-template.md`
+
+Use the **flat legacy form** for the `root:` path in the draft snippet: `root: skills/{skill-name}/`. The platform-specific prefix (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`) is applied later by `export-skill` step-03 when the skill is exported. Do not choose a platform prefix in update-skill — that is an export-time decision that depends on config.yaml.
+
+Pull values for the regenerated snippet from the updated metadata.json (version, top exports), the merged SKILL.md (section anchors, inline summaries), and the evidence report (new gotchas). If gotchas cannot be derived from the updated evidence but the prior snippet has a `|gotchas:` line, carry forward the prior line with the `[CARRIED]` marker — see `export-skill/steps-c/step-03-generate-snippet.md` for the carry-forward protocol (one-cycle limit).
+
+Write the regenerated snippet to `{skill_package}/context-snippet.md`, preserving file permissions.
+
+**If skill_type == "stack"**, also verify that the reference file updates from the first half of this section have been applied before writing the snippet so the stack snippet reflects the newest integration list.
+
+### 5b. Update Active Symlink (If Version Changed)
+
+If the version was incremented or changed in section 2 (metadata.json update):
+- Create or update the `active` symlink at `{skill_group}/active` pointing to the new `{version}`
+- If the symlink already exists, remove it first and recreate
+
+```
+{skill_group}/active -> {version}
+```
+
+If the version did not change, the existing symlink already points to the correct version -- no action needed.
 
 ### 6. Verify All Writes
 
@@ -183,11 +212,11 @@ For each file written:
 External tool checks deferred from step-05 now run against the written files:
 
 **If skill-check available:**
-- Run: `npx skill-check check {skills_output_folder}/{skill_name} --fix --format json --no-security-scan`
+- Run: `npx skill-check check {skill_package} --fix --format json --no-security-scan`
 - **Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07-report will reference.
-- If `body.max_lines` reported, prefer selective split — extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). Fall back to `npx skill-check split-body {skills_output_folder}/{skill_name} --write` if not feasible. Verify anchors resolve after split.
+- If `body.max_lines` reported, prefer selective split — extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). Fall back to `npx skill-check split-body {skill_package} --write` if not feasible. Verify anchors resolve after split.
 - Run: `npx skill-check diff` if original version was preserved
-- Run: `npx skill-check check {skills_output_folder}/{skill_name} --format json` for security scan
+- Run: `npx skill-check check {skill_package} --format json` for security scan
 
 Record findings in the evidence report (section 4). These are advisory — do not block on warnings.
 
@@ -216,11 +245,12 @@ ONLY WHEN all files have been written and verified will you load {nextStepFile}
 
 ### ✅ SUCCESS:
 
-- SKILL.md written with all merged content and [MANUAL] sections intact
+- SKILL.md written to {skill_package} with all merged content and [MANUAL] sections intact
 - metadata.json updated with new version, timestamp, export counts
-- provenance-map.json updated with current file:line references and timestamps
-- evidence-report.md appended with update operation record
+- provenance-map.json updated at {forge_version} with current file:line references and timestamps
+- evidence-report.md appended at {forge_version} with update operation record
 - Stack reference files updated if applicable
+- Active symlink updated at {skill_group}/active -> {version} if version changed
 - All writes verified by read-back confirmation
 
 ### ❌ SYSTEM FAILURE:

package/src/workflows/update-skill/steps-c/step-07-report.md

@@ -142,11 +142,13 @@ Source code matches provenance map exactly. The skill `{skill_name}` is current
 
 | File | Status |
 |------|--------|
-| `{skills_output_folder}/{skill_name}/SKILL.md` | Updated |
-| `{skills_output_folder}/{skill_name}/metadata.json` | Updated |
-| `{forge_data_folder}/{skill_name}/provenance-map.json` | Updated |
-| `{forge_data_folder}/{skill_name}/evidence-report.md` | Appended |
-| {stack reference files if applicable} | Updated |"
+| `{resolved_skill_package}/SKILL.md` | Updated |
+| `{resolved_skill_package}/metadata.json` | Updated |
+| `{forge_version}/provenance-map.json` | Updated |
+| `{forge_version}/evidence-report.md` | Appended |
+| {stack reference files if applicable} | Updated |
+
+Where `{resolved_skill_package}` = `{skills_output_folder}/{skill_name}/{version}/{skill_name}/` and `{forge_version}` = `{forge_data_folder}/{skill_name}/{version}/` — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)."
 
 ### 5. Workflow Chaining Recommendations
 

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

@@ -81,9 +81,14 @@ Wait for user input.
 
 ### 2. Scan Skills Folder
 
-Read the `{skills_output_folder}` directory.
+Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)).
 
-For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+**Version-aware skill discovery:**
+1. Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports`, use `active_version` to resolve `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+2. For any subdirectory not covered by the manifest, check for an `active` symlink at `{skills_output_folder}/{dir_name}/active` — resolve to `{skill_group}/active/{dir_name}/`
+3. Fall back to flat path `{skills_output_folder}/{dir_name}/` for unmigrated skills
+
+For each resolved skill package, check for the presence of `SKILL.md` and `metadata.json`.
 
 **For each valid skill directory, extract from metadata.json:**
 - `name` — skill name
@@ -94,7 +99,7 @@ For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
 
 **Build a skill inventory** as an internal list of all loaded skills with the fields above.
 
-**If a subdirectory lacks SKILL.md or metadata.json:**
+**If a resolved skill package lacks SKILL.md or metadata.json:**
 - Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
 - Do not include in inventory
 

package/tools/cli/lib/installer.js

@@ -238,6 +238,7 @@ class Installer {
       document_output_language: 'en',
       skills_output_folder: config.skills_output_folder || 'skills',
       forge_data_folder: config.forge_data_folder || 'forge-data',
+      sidecar_path: '_bmad/_memory/forger-sidecar',
       skf_folder: config.skfFolder,
       ides: config.ides || [],
     };

package/tools/cli/lib/ui.js

@@ -15,6 +15,8 @@ const figlet = require('figlet');
 const path = require('node:path');
 const fs = require('fs-extra');
 const yaml = require('js-yaml');
+const { readManifest } = require('./manifest');
+const { compareVersions } = require('./version-check');
 
 const SKF_FOLDER = '_bmad/skf';
 
@@ -94,12 +96,32 @@ class UI {
     let action = 'fresh';
 
     if (detection.type === 'existing') {
-      log.warn(`Found existing installation at ${chalk.white(SKF_FOLDER + '/')}`);
+      const existingManifest = await readManifest(projectDir);
+      const installedVersion = existingManifest?.version || null;
+      const incomingVersion = require('../../../package.json').version;
+
+      let versionLabel;
+      let updateOptionLabel;
+      if (!installedVersion) {
+        versionLabel = `version unknown → v${incomingVersion}`;
+        updateOptionLabel = `Update — Install v${incomingVersion}, keep config.yaml`;
+      } else if (installedVersion === incomingVersion) {
+        versionLabel = `v${installedVersion} — already at this version`;
+        updateOptionLabel = `Update — Reinstall v${incomingVersion}, keep config.yaml`;
+      } else if (compareVersions(installedVersion, incomingVersion)) {
+        versionLabel = `v${installedVersion} → v${incomingVersion} available`;
+        updateOptionLabel = `Update — Upgrade from v${installedVersion} to v${incomingVersion}, keep config.yaml`;
+      } else {
+        versionLabel = `v${installedVersion} → v${incomingVersion}, DOWNGRADE`;
+        updateOptionLabel = `Update — Downgrade to v${incomingVersion}, keep config.yaml`;
+      }
+
+      log.warn(`Found existing installation at ${chalk.white(SKF_FOLDER + '/')} (${versionLabel})`);
 
       const choice = await select({
         message: 'What would you like to do?',
         options: [
-          { label: 'Update — Replace SKF files, keep config.yaml', value: 'update' },
+          { label: updateOptionLabel, value: 'update' },
           { label: 'Fresh install — Remove everything and start over', value: 'fresh' },
           { label: 'Cancel', value: 'cancel' },
         ],