bmad-module-skill-forge 0.8.4 → 0.10.0

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

@@ -1,6 +1,7 @@
 ---
 name: 'step-09-report'
 description: 'Display final stack skill summary with confidence distribution and next workflow recommendations'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 9: Stack Skill Report
@@ -25,7 +26,7 @@ Display the final summary of the forged stack skill with confidence distribution
 
 ### Step-Specific Rules:
 
-- 🎯 This is the FINAL step — no nextStepFile
+- 🎯 Chains to shared health check via `{nextStepFile}` — no further steps after that
 - 🚫 FORBIDDEN to write or modify any files — report is console output only
 - 💬 Lead with the positive summary, then details, then warnings if any
 - 🎯 Recommend next workflows based on what was produced
@@ -74,16 +75,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
 
@@ -117,6 +120,10 @@ Forge tier: **{tier}**"
 
 **Workflow complete.**"
 
+### 7. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
 ---
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS

package/src/workflows/drop-skill/steps-c/step-01-select.md

@@ -0,0 +1,298 @@
+---
+name: 'step-01-select'
+description: 'Select skill, version(s), and drop mode (deprecate/purge)'
+nextStepFile: './step-02-execute.md'
+versionPathsKnowledge: '../../../knowledge/version-paths.md'
+---
+
+# Step 1: Select Drop Target
+
+## STEP GOAL:
+
+Identify exactly what the user wants to drop — which skill, which version(s), and whether the drop is a soft deprecation (manifest-only) or a hard purge (files deleted). Enforce the active version guard, gather the list of affected directories, and obtain explicit user confirmation before any write or delete operation is scheduled.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER schedule a destructive operation without explicit user confirmation
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are Ferris in Management mode — a destructive operation specialist
+- ✅ Safety first, confirmation required
+- ✅ You protect the active version and enforce the active version guard
+- ✅ You treat every drop as potentially irreversible — soft drops are recoverable, hard drops are not
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on selection, validation, and confirmation
+- 🚫 FORBIDDEN to proceed without explicit user confirmation at the final gate
+- 🚫 FORBIDDEN to modify the manifest or delete any files in this step — execution happens in step-02
+- 🚫 FORBIDDEN to drop an active version when other non-deprecated versions exist
+- 💬 Present selections clearly so the user can verify scope, mode, and blast radius before committing
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load version-paths knowledge and the export manifest (if present) alongside an on-disk skill scan
+- 💾 Gather all selection decisions into context for step-02
+- 📖 Show version lists, statuses, and directory paths clearly so the user understands what will be affected
+- 🚫 Halt only if neither the manifest nor an on-disk scan yields any skill — a missing manifest is not fatal for purge mode because draft skills (created but never exported) can still be legitimately hard-dropped from disk
+
+## CONTEXT BOUNDARIES:
+
+- Available: Export manifest v2, SKF module config variables, on-disk skill directory listing
+- Focus: Selection, validation, and user confirmation
+- Limits: Do not write to the manifest, do not delete any files — execution is deferred to step-02
+- Dependencies: At least one skill must exist in either the export manifest or on disk under `{skills_output_folder}/`; otherwise the workflow halts. Draft skills (on disk but not in the manifest) are eligible for purge mode only
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Knowledge
+
+Read `{versionPathsKnowledge}` completely and extract:
+
+- Path templates: `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`
+- Export manifest v2 schema (`schema_version`, `exports`, `active_version`, `versions` map, `status` field values)
+- Skill management operations (Drop section — soft vs hard, active version guard, skill-level drop)
+
+You will use these templates and rules to build directory paths and enforce safety guards in the following sections.
+
+### 2. Read Export Manifest
+
+Load `{skills_output_folder}/.export-manifest.json` if it exists.
+
+**If the file is missing, empty, or contains no `exports` entries:** Treat as an empty manifest — proceed to section 3 and rely on the on-disk directory scan. Draft skills (created by `[CS]`/`[QS]`/`[SS]` but never exported) can still be hard-dropped in purge mode. Store `manifest_exists = false` so section 8 (Ask Mode) can restrict the options to purge only. Soft-deprecate is meaningless without a manifest to record the deprecation against.
+
+**If the file exists with entries:** Parse JSON and verify `schema_version` is `"2"`. If the manifest is v1 (no `schema_version` field), note this but continue — treat every entry as having a single active version derived from its current state. Store `manifest_exists = true`.
+
+**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before dropping."
+
+### 3. List Available Skills
+
+Build and display a summary of every skill available to drop. Start with the manifest (if any), then augment with an on-disk scan.
+
+For each skill in the manifest's `exports` (only if `manifest_exists = true` and entries exist):
+
+1. Read `active_version` from the manifest entry
+2. List every entry in the skill's `versions` map with its `status` field
+3. Mark the active version with a trailing `*`
+4. Sort versions in descending order (newest first) where possible
+
+Also scan `{skills_output_folder}/` for any top-level directories that are NOT present in the manifest's `exports` object. Record these as "(not in manifest)" — they represent draft or orphaned skills eligible for purge mode only. When the manifest is missing or empty, every on-disk skill appears in this category.
+
+**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Drop Skill — nothing to drop.** No skills found in `{skills_output_folder}/` and no entries in `.export-manifest.json`. Run `[CS] Create Skill` first."
+
+Display the combined list:
+
+```
+**Drop Skill — select target**
+
+Available skills:
+1. cognee
+   - 0.1.0 (deprecated)
+   - 0.5.0 (archived)
+   - 0.6.0 (active) *
+2. express
+   - 4.18.0 (active) *
+3. legacy-helper (not in manifest — purge only)
+```
+
+### 4. Ask Which Skill
+
+"**Which skill would you like to drop?**
+Enter the skill name or its number from the list above."
+
+Wait for user input. Accept either the numeric index or the skill name (exact match).
+
+**If the user's input does not match any listed skill:** Re-display the list and ask again.
+
+Store the selection as `target_skill`. Also store `target_in_manifest = true` if the selected skill has an entry in the manifest, `false` otherwise — subsequent sections use this flag to restrict the available drop options.
+
+### 5. Display Version Details
+
+**If `target_in_manifest = true`**, display every version with its full metadata from the manifest:
+
+```
+**{target_skill} — versions:**
+
+| Version | Status     | Last Exported | Platforms              |
+|---------|------------|---------------|------------------------|
+| 0.1.0   | deprecated | 2026-01-15    | claude                 |
+| 0.5.0   | archived   | 2026-03-15    | claude                 |
+| 0.6.0   | active *   | 2026-04-04    | claude, copilot        |
+```
+
+**If `target_in_manifest = false`** (draft skill discovered only by on-disk scan), display the on-disk version directories instead and note the constraint:
+
+```
+**{target_skill} — on-disk versions (not in manifest):**
+
+  {list version subdirectories found under {skills_output_folder}/{target_skill}/, or "(flat layout)" if no version nesting is present}
+
+**Note:** This skill has no manifest entry, so soft-deprecate is not available. Only a skill-level hard purge can be performed — the drop will delete the entire on-disk skill group and forge group.
+```
+
+### 6. Ask Scope
+
+**If `target_in_manifest = false`:** Skip this prompt — draft skills can only be dropped as a whole. Set `target_versions = "all"` and `is_skill_level = true`, then proceed to section 7.
+
+**If `target_in_manifest = true`:**
+
+"**Drop which version(s)?**
+
+- **[N]** Specific version — soft deprecate or hard purge a single version
+- **[A]** All versions — drops the entire skill (skill-level operation)"
+
+Wait for user selection.
+
+**If [N] Specific version:**
+
+"**Which version?** Enter the version string (e.g. `0.5.0`)."
+
+Wait for user input. Validate that the version exists in the manifest's `versions` map for `target_skill`. If not, repeat the prompt.
+
+Set `target_versions = [<selected version>]` and `is_skill_level = false`.
+
+**If [A] All versions:**
+
+Set `target_versions = "all"` and `is_skill_level = true`.
+
+### 7. Active Version Guard
+
+**Does not apply when `target_in_manifest = false`:** A draft skill has no manifest-recorded active version, so the guard is a no-op. Proceed to section 8.
+
+**Applies only when `target_in_manifest = true` AND `is_skill_level = false` (specific version selected):**
+
+1. Read the selected version's `status` field from the manifest
+2. If `status != "active"` → skip this guard, the version is safe to drop
+3. If `status == "active"`:
+   a. Count the number of OTHER versions in the `versions` map with `status != "deprecated"` (i.e., `active`, `archived`, or `draft`)
+   b. If that count is `> 0` → REFUSE the drop:
+
+      "**Cannot drop the active version `{version}`.**
+      Other non-deprecated versions of `{target_skill}` still exist. To proceed, either:
+
+      **(a)** Switch the active version to another version first by re-running `[EX] Export Skill` with a different version selected, then return here to drop `{version}`, OR
+
+      **(b)** Use the `[A] All versions` option to drop every version of `{target_skill}` at once."
+
+      HALT the workflow. Do not proceed.
+
+   c. If the count is `0` → the active version is the ONLY version; allow the drop to continue (it is functionally equivalent to a skill-level drop on a single-version skill)
+
+### 8. Ask Mode
+
+**If `target_in_manifest = false`:** Skip this prompt — soft-deprecate is meaningless without a manifest entry to mark. Force `drop_mode = "purge"` and inform the user: "**Mode forced to purge** — `{target_skill}` has no manifest entry, so there is nothing to deprecate. The skill's on-disk directories will be deleted."
+
+**If `target_in_manifest = true`:**
+
+"**How should this be dropped?**
+
+- **[D]** Deprecate (soft) — Mark the version as `deprecated` in the manifest. Files remain on disk. Export-skill will exclude it from all platform context files. Reversible by editing the manifest.
+- **[P]** Purge (hard) — Deprecate AND delete files from disk (`{skill_package}` and `{forge_version}`, or full `{skill_group}` and `{forge_group}` for a skill-level drop). **Irreversible.**"
+
+Wait for user selection.
+
+Set `drop_mode` to `"deprecate"` (on D) or `"purge"` (on P).
+
+### 9. Compute Affected Directories
+
+Using the templates from `{versionPathsKnowledge}`, resolve the list of directories that would be affected:
+
+**If `is_skill_level = false` (version-level drop):**
+
+- `{skill_package}` = `{skills_output_folder}/{target_skill}/{version}/{target_skill}/`
+- The enclosing version directory = `{skills_output_folder}/{target_skill}/{version}/`
+- `{forge_version}` = `{forge_data_folder}/{target_skill}/{version}/`
+
+**If `is_skill_level = true` (skill-level drop):**
+
+- `{skill_group}` = `{skills_output_folder}/{target_skill}/`
+- `{forge_group}` = `{forge_data_folder}/{target_skill}/`
+
+Store the list as `affected_directories`.
+
+If `drop_mode == "deprecate"`, record the list but present it as "retained" in the confirmation output — no deletion will occur.
+
+### 10. Confirmation Gate
+
+Display the full operation summary:
+
+```
+**About to drop:**
+
+  Skill:   {target_skill}
+  Version: {version or "ALL versions"}
+  Mode:    {Deprecate (soft) | Purge (hard)}
+  Files:
+    {for each path in affected_directories, list one per line}
+    {or "(retained on disk — soft drop)" if drop_mode == "deprecate"}
+
+{if drop_mode == "purge":}
+  ⚠️  This operation cannot be undone. Files will be permanently deleted.
+{else:}
+  Files remain on disk. Reversible by manually editing the manifest.
+
+Proceed? [Y/N]
+```
+
+Wait for explicit user response.
+
+- **If `Y`** → proceed to section 11
+- **If `N`** → "**Cancelled.** No changes were made." HALT the workflow
+- **Any other input** → re-display the confirmation and ask again
+
+### 11. Store Decisions in Context
+
+Store the following decisions in workflow context for step-02:
+
+- `target_skill` — the skill name
+- `target_in_manifest` — boolean (true if the skill has a manifest entry, false if it was discovered only by on-disk scan)
+- `target_versions` — list of version strings (`[<version>]`) or the literal string `"all"`
+- `drop_mode` — `"deprecate"` or `"purge"` (always `"purge"` when `target_in_manifest = false`)
+- `is_skill_level` — boolean (true if all versions; always true when `target_in_manifest = false`)
+- `affected_directories` — list of absolute directory paths that step-02 will delete in purge mode (or retain in deprecate mode)
+
+### 12. Load Next Step
+
+Load, read the full file, and then execute `{nextStepFile}`.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user has confirmed with `Y` at the confirmation gate AND all selection decisions have been stored in context, will you then load and read fully `{nextStepFile}` to execute the drop.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Version-paths knowledge loaded and applied via templates (no hardcoded paths)
+- Export manifest read if present; on-disk scan augments the list; halt only if both are empty
+- Complete skill and version list displayed with statuses, active marker, and on-disk-only entries flagged "(not in manifest — purge only)"
+- Skill, version(s), and mode selected by explicit user input; mode forced to purge for not-in-manifest skills
+- Active version guard enforced for manifest-tracked skills — refused to drop an active version with surviving non-deprecated peers
+- Affected directories computed from templates
+- Explicit user confirmation (`Y`) received at the confirmation gate
+- All selection decisions stored in context for step-02 (including `target_in_manifest`)
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without reading version-paths knowledge
+- Halting when the manifest is missing but on-disk skills exist — the fallback scan MUST be attempted before any "nothing to drop" halt
+- Offering soft-deprecate for a skill that has no manifest entry
+- Hardcoding directory paths instead of using `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}` templates
+- Allowing a drop of the active version when other non-deprecated versions exist
+- Modifying the manifest or deleting files in this step (execution belongs to step-02)
+- Skipping the confirmation gate or proceeding on any response other than `Y`
+- Not storing decisions in context for step-02
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. No destructive action proceeds without explicit user confirmation.