bmad-module-skill-forge 0.2.0

package/src/workflows/test-skill/workflow.md

@@ -0,0 +1,57 @@
+---
+name: test-skill
+description: Cognitive completeness verification. Naive and contextual modes.
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/test-skill'
+---
+
+# Test Skill
+
+**Goal:** Verify that a skill is complete enough to be useful to an AI agent by checking coverage of the public API surface (naive mode) or validating SKILL.md + references coherence (contextual mode), producing a completeness score and gap report as a quality gate before export.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a skill auditor and completeness analyst operating in Ferris's Audit mode. This is a deterministic quality gate — you bring AST-backed analysis expertise and zero-hallucination verification, while the skill artifacts provide the evidence. Every finding must trace to actual code with file:line citations.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
+- **Append-Only Building**: Build the test report by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- ⚙️ **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
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
+
+- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+- `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/workflows/update-skill/data/manual-section-rules.md

@@ -0,0 +1,44 @@
+# [MANUAL] Section Rules
+
+## Detection Pattern
+
+[MANUAL] sections are developer-authored content blocks within generated SKILL.md files that must survive regeneration.
+
+### Identification
+
+A [MANUAL] section is delimited by markers in the SKILL.md:
+
+```markdown
+<!-- [MANUAL:section-name] -->
+Developer-authored content here.
+This content was added by the developer after skill generation.
+It must be preserved during any update operation.
+<!-- [/MANUAL:section-name] -->
+```
+
+### Rules
+
+1. **Never modify content between [MANUAL] markers** — treat as immutable
+2. **Preserve marker positions** — if the surrounding generated content moves, the [MANUAL] block moves with its logical parent section
+3. **Orphan detection** — if the parent section is deleted (export removed), flag as WARNING and present to user
+4. **Multiple [MANUAL] blocks** — a single SKILL.md may have multiple [MANUAL] sections; preserve all
+5. **Stack skill [MANUAL] blocks** — [MANUAL] markers can appear in any output file (SKILL.md, references/*.md, integrations/*.md); preserve across all files
+6. **Nested [MANUAL] forbidden** — [MANUAL] blocks cannot be nested; if detected, flag as ERROR
+
+### Conflict Types
+
+| Conflict | Severity | Resolution |
+|----------|----------|------------|
+| Regenerated content overlaps [MANUAL] position | HIGH | Present both versions, user chooses |
+| Parent section deleted | WARNING | Flag orphaned [MANUAL], user decides keep/remove |
+| [MANUAL] references deleted export | MEDIUM | Flag stale reference, suggest update |
+| New export inserted adjacent to [MANUAL] | LOW | Auto-resolve: place new content before [MANUAL] block |
+
+### Preservation Algorithm
+
+1. Extract all [MANUAL] blocks with their section-name identifiers
+2. Map each block to its parent section (by heading hierarchy)
+3. Perform merge on generated content only
+4. Re-insert [MANUAL] blocks at their mapped positions
+5. If position conflict: halt and present to user
+6. If clean insert: auto-place and continue

package/src/workflows/update-skill/data/merge-conflict-rules.md

@@ -0,0 +1,62 @@
+# Merge Conflict Rules
+
+## Change Categories
+
+### Category 1: Modified Exports (signature/type change)
+
+- **Action:** Re-extract affected export with fresh AST analysis
+- **Merge:** Replace generated content for that export; preserve adjacent [MANUAL] blocks
+- **Confidence:** Same tier as original (T1/T1-low/T2)
+
+### Category 2: New Exports (added since last generation)
+
+- **Action:** Extract new export with full AST analysis
+- **Merge:** Append to appropriate section based on export type (function, type, class, constant)
+- **Confidence:** Label with extraction tier confidence
+- **[MANUAL] impact:** None — new content, no existing [MANUAL] blocks
+
+### Category 3: Deleted Exports (removed from source)
+
+- **Action:** Remove generated content for that export
+- **Merge:** Check for attached [MANUAL] blocks before deletion
+- **If [MANUAL] attached:** Flag as orphan, present to user for decision
+- **If no [MANUAL]:** Auto-remove generated content
+
+### Category 4: Moved Exports (file relocated)
+
+- **Action:** Update provenance map file references
+- **Merge:** Update file:line citations in generated content
+- **Confidence:** Retain original tier if AST structure unchanged; downgrade to T1-low if structure changed
+- **[MANUAL] impact:** Preserve — content unchanged, only provenance metadata updates
+
+### Category 5: Renamed Exports (identifier changed)
+
+- **Action:** Re-extract with new identifier
+- **Merge:** Replace old identifier references in generated content
+- **[MANUAL] impact:** Flag if [MANUAL] blocks reference old identifier name
+
+## Merge Priority Order
+
+1. Process deleted exports first (remove generated content, flag [MANUAL] orphans)
+2. Process moved exports second (update references only)
+3. Process renamed exports third (update identifiers)
+4. Process modified exports fourth (re-extract and replace)
+5. Process new exports last (append to sections)
+
+## Stack Skill Merge Rules
+
+For stack skills with multi-file outputs:
+
+1. **SKILL.md:** Apply standard merge rules above
+2. **references/{library}.md:** Merge per-library, preserving [MANUAL] blocks within each
+3. **references/integrations/{pair}.md:** Merge per-integration-pair
+4. **metadata.json:** Regenerate completely (no [MANUAL] support in JSON)
+5. **context-snippet.md:** Regenerate completely (no [MANUAL] support — too concise)
+
+## Conflict Resolution Strategies
+
+| Strategy | When | Action |
+|----------|------|--------|
+| Auto-resolve | No [MANUAL] conflicts, clean merge | Proceed without user input |
+| User-resolve | [MANUAL] conflicts detected | Halt, present conflicts, require decision |
+| Abort | Critical structural incompatibility | Stop workflow, recommend full re-creation |

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

@@ -0,0 +1,208 @@
+---
+name: 'step-01-init'
+description: 'Load existing skill artifacts, provenance map, and forge tier; detect skill type; present baseline and change scope'
+
+nextStepFile: './step-02-detect-changes.md'
+manualSectionRulesFile: '../data/manual-section-rules.md'
+---
+
+# Step 1: Initialize Update
+
+## STEP GOAL:
+
+Load the existing skill and all its provenance data, detect whether this is an individual or stack skill, load the forge tier configuration, and present a baseline summary so the user can confirm the update scope before proceeding.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 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 a precision code analyst operating in Surgeon mode
+- ✅ Zero-hallucination principle: every statement must trace to actual artifacts
+- ✅ Clinical, terse communication — confidence-labeled, AST-backed
+- ✅ You bring provenance-driven analysis expertise; the source code provides ground truth
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading existing artifacts and establishing the baseline
+- 🚫 FORBIDDEN to modify any files in this step — read-only operations
+- 🚫 FORBIDDEN to begin change detection — that is step 02
+- 💬 Present findings with confidence tier labels on all loaded data
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Load all required artifacts into working context
+- 📖 Validate artifact existence before proceeding
+- 🚫 FORBIDDEN to proceed without user confirmation at gate
+
+## CONTEXT BOUNDARIES:
+
+- Available: SKF module config (skills_output_folder, forge_data_folder), user-provided skill path
+- Focus: artifact loading and baseline establishment
+- Limits: read-only — do not modify any files
+- Dependencies: setup-forge must have been run (forge-tier.yaml), create-skill or create-stack-skill must have been run (SKILL.md + provenance-map.json)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Request Skill Path
+
+"**Which skill would you like to update?**
+
+Provide either:
+- A skill name (resolves to `{skills_output_folder}/{name}/`)
+- A full path to the skill folder
+
+**Skill:** {user provides path or name}"
+
+Resolve the path to an absolute skill folder location.
+
+### 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."
+
+**Check metadata.json exists:**
+- Load `{resolved_skill_path}/metadata.json`
+- Extract: `skill_name`, `skill_type` (individual or stack), `version`, `created`, `forge_tier`, `source_root`
+- If missing: **ABORT** — "No metadata.json found. This skill may have been created manually. Run create-skill to generate provenance data."
+
+**Detect skill type from metadata:**
+- If `skill_type == "stack"`: flag as stack skill (multi-file update mode)
+- If `skill_type == "individual"` or absent: flag as individual skill
+
+### 3. Load Forge Tier Configuration
+
+**Load `sidecar/forge-tier.yaml`:**
+- Extract: `forge_tier` (Quick, Forge, or Deep), available tools
+- If missing: **ABORT** — "No forge-tier.yaml found. Run setup-forge first to detect available tools."
+
+**Determine analysis capabilities:**
+- **Quick:** text pattern matching only → T1-low confidence
+- **Forge:** AST structural extraction → T1 confidence
+- **Deep:** AST + QMD semantic enrichment → T1 + T2 confidence
+
+### 4. Load Provenance Map
+
+**Load `{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:**
+
+"**WARNING:** No provenance map found at `{forge_data_folder}/{skill_name}/provenance-map.json`.
+
+Without a provenance map, update-skill cannot perform targeted change detection. Options:
+
+**[D]egraded mode** — Perform full re-extraction with T1-low confidence (equivalent to re-running create-skill but preserving [MANUAL] sections)
+**[X]** — Abort and run create-skill first to generate provenance data
+
+Select: [D] Degraded / [X] Abort"
+
+- If D: set `degraded_mode = true`, proceed with full extraction scope
+- If X: **ABORT**
+
+### 5. Load [MANUAL] Section Inventory
+
+Load {manualSectionRulesFile} to understand [MANUAL] detection patterns.
+
+**Scan SKILL.md for [MANUAL] sections:**
+- Count all `<!-- [MANUAL:*] -->` markers
+- Map each [MANUAL] block to its parent section (by heading hierarchy)
+- Record section names and approximate line positions
+
+**For stack skills, also scan:**
+- All `references/*.md` files for [MANUAL] markers
+- All `references/integrations/*.md` files for [MANUAL] markers
+
+### 6. Resolve Source Code Path
+
+**From provenance map (if available):**
+- Extract `source_root` path
+- Validate source path exists and is accessible
+
+**If source path invalid or missing:**
+
+"**Source path from provenance map is invalid:** `{source_root}`
+
+Please provide the current source code path:
+**Path:** {user provides path}"
+
+### 7. Present Baseline Summary
+
+"**Update Skill Baseline:**
+
+| Property | Value |
+|----------|-------|
+| **Skill** | {skill_name} |
+| **Type** | {individual/stack} |
+| **Version** | {version} |
+| **Created** | {created date} |
+| **Source** | {source_root} |
+| **Forge Tier** | {forge_tier} (current) vs {original_tier} (at creation) |
+| **Provenance Age** | {days} days since last extraction |
+| **Exports** | {export_count} tracked exports |
+| **[MANUAL] Sections** | {manual_count} preserved sections |
+| **Mode** | {normal/degraded} |
+
+**Analysis plan:** {tier_description}
+- {Quick: text pattern diff → T1-low findings}
+- {Forge: AST structural diff → T1 findings}
+- {Deep: AST structural + QMD semantic diff → T1 + T2 findings}
+
+**Ready to detect changes and update this skill?**"
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select:** [C] Continue to Change Detection"
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C] is selected and baseline has been established with all required artifacts loaded, will you then load and read fully `{nextStepFile}` to execute change detection.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- SKILL.md loaded and validated
+- metadata.json loaded with skill_name, skill_type, version, source_root
+- Forge tier loaded from sidecar/forge-tier.yaml
+- Provenance map loaded (or degraded mode confirmed)
+- [MANUAL] sections inventoried across all output files
+- Source code path validated
+- Baseline summary presented to user
+- User confirms scope via [C] Continue
+
+### ❌ SYSTEM FAILURE:
+
+- Not validating artifact existence before proceeding
+- Not detecting skill type (individual vs stack)
+- Modifying any files during this read-only step
+- Proceeding without user confirmation
+- Not inventorying [MANUAL] sections before update begins
+- Not loading forge tier configuration
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/update-skill/steps-c/step-02-detect-changes.md

@@ -0,0 +1,184 @@
+---
+name: 'step-02-detect-changes'
+description: 'Diff source file timestamps and hashes against provenance map to identify all changes since last extraction'
+
+nextStepFile: './step-03-re-extract.md'
+noChangeReportFile: './step-07-report.md'
+---
+
+# Step 2: Detect Changes
+
+## STEP GOAL:
+
+Compare current source code state against the provenance map to produce a complete change manifest identifying every changed, added, deleted, moved, and renamed file and export since last extraction.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 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 a precision code analyst operating in Surgeon mode
+- ✅ Zero-hallucination principle: every change must be verified against actual source state
+- ✅ Clinical, terse communication — report changes factually with file:line references
+- ✅ You bring provenance-driven analysis; the source code provides ground truth
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on detecting and classifying changes — do not extract or merge
+- 🚫 FORBIDDEN to modify any files — read-only change detection
+- 🚫 FORBIDDEN to re-extract content — that is step 03
+- 💬 Use subprocess optimization Pattern 4 for parallel comparison when available
+- ⚙️ If subprocess unavailable, perform comparison sequentially in main thread
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 Build change manifest with categorized findings
+- 📖 Track change counts by category for summary
+- 🚫 FORBIDDEN to proceed if source path is inaccessible
+
+## CONTEXT BOUNDARIES:
+
+- Available: loaded baseline from step 01 (SKILL.md, metadata.json, provenance-map.json, forge-tier, source_root)
+- Focus: change detection only — no extraction, no merge
+- Limits: read-only operations on source code
+- Dependencies: step 01 must have loaded all artifacts successfully
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Scan Current Source State
+
+Read the source directory at `{source_root}` and build a current file inventory:
+- For each source file: record path, file size, last modified timestamp
+- Focus on file types relevant to the skill (from provenance map file patterns)
+- Exclude non-source files (node_modules, build artifacts, etc.)
+
+### 2. Compare Against Provenance Map
+
+**If normal mode (provenance map available):**
+
+Launch subprocesses in parallel that compare source state against provenance map across these categories, returning change findings per category:
+
+**Category A — File-level changes:**
+- Files in provenance map but missing from source → DELETED
+- Files in source but not in provenance map → ADDED
+- Files in both but with different timestamps/sizes → MODIFIED
+- Files with same content at different paths → MOVED
+
+**Category B — Export-level changes (for MODIFIED files only):**
+- For each modified file, compare export list against provenance map exports
+- Exports in provenance but not in source → DELETED_EXPORT
+- Exports in source but not in provenance → NEW_EXPORT
+- Exports with changed signatures/types → MODIFIED_EXPORT
+- Exports at different line numbers but same content → MOVED_EXPORT
+
+**Category C — Rename detection:**
+- Cross-reference deleted files/exports with added files/exports
+- If content similarity > 80%: classify as RENAMED instead of deleted+added
+
+Aggregate all subprocess results into a unified change manifest.
+
+**If degraded mode (no provenance map):**
+- All source files are treated as MODIFIED
+- All exports will be fully re-extracted in step 03
+- Skip export-level comparison
+
+### 3. Build Change Manifest
+
+Compile the change manifest with structured entries:
+
+```
+Change Manifest:
+  files_changed: [count]
+  files_added: [count]
+  files_deleted: [count]
+  files_moved: [count]
+
+  exports_modified: [count]
+  exports_new: [count]
+  exports_deleted: [count]
+  exports_renamed: [count]
+  exports_moved: [count]
+
+  Per-file detail:
+    {file_path}:
+      status: MODIFIED|ADDED|DELETED|MOVED
+      exports_affected: [{export_name, change_type, old_line, new_line}]
+```
+
+### 4. Check for No-Change Shortcut
+
+**If zero changes detected across all categories:**
+
+"**No changes detected.** Source code matches provenance map exactly.
+
+The skill `{skill_name}` is current — no update needed.
+
+**Skipping to report step...**"
+
+→ Skip steps 03-06, immediately load {noChangeReportFile} with "no changes" status.
+
+### 5. Display Change Summary and Auto-Proceed
+
+"**Change Detection Complete:**
+
+| Category | Count |
+|----------|-------|
+| Files modified | {count} |
+| Files added | {count} |
+| Files deleted | {count} |
+| Files moved/renamed | {count} |
+| Exports affected | {total_export_changes} |
+
+**Proceeding to re-extraction of {affected_file_count} changed files...**"
+
+### 6. Present MENU OPTIONS
+
+Display: "**Proceeding to re-extraction...**"
+
+#### Menu Handling Logic:
+
+- After change manifest is built, immediately load, read entire file, then execute {nextStepFile}
+- **EXCEPTION:** If no changes detected (section 4), load {noChangeReportFile} instead
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to next step after change detection completes
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the change manifest is fully built will you load {nextStepFile} to begin re-extraction. If no changes detected, skip to {noChangeReportFile}.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Every file in provenance map compared against current source state
+- Changes categorized correctly (modified, added, deleted, moved, renamed)
+- Export-level changes detected for modified files
+- Change manifest built with per-file detail
+- No-change shortcut correctly routes to report step
+- Summary displayed before auto-proceeding
+
+### ❌ SYSTEM FAILURE:
+
+- Not comparing all files in provenance map
+- Missing category of changes (e.g., not detecting deletions)
+- Modifying any files during detection
+- Not detecting rename patterns (treating as delete+add)
+- Proceeding with empty change manifest when changes exist
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.