bmad-module-skill-forge 0.6.0 → 0.7.0

package/src/workflows/export-skill/data/managed-section-format.md

@@ -22,7 +22,7 @@
 | Cursor | `cursor` | .cursorrules |
 | Copilot | `copilot` | AGENTS.md |
 
-## Three-Case Logic
+## Four-Case Logic
 
 ### Case 1: Create (No File Exists)
 
@@ -53,6 +53,13 @@ Target file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers. Replace co
 4. Replace everything between markers (inclusive) with new managed section
 5. Write file
 
+### Case 4: Malformed Markers (Halt)
+
+Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker. This indicates a corrupted managed section.
+
+1. Halt workflow with error: "Malformed managed section — `<!-- SKF:BEGIN` found but no `<!-- SKF:END -->`. Fix the markers manually before re-running export."
+2. Do not modify the file
+
 ## Regeneration: Full Index Rebuild
 
 When regenerating (Case 3), rebuild the COMPLETE skill index:

package/src/workflows/export-skill/data/snippet-format.md

@@ -40,7 +40,7 @@
 
 ## Rules
 
-- **api line**: Top exports from metadata.json `exports` array. Append `()` to function names. Comma-separated.
+- **api line**: Top exports from metadata.json `exports` array (up to 10 for Deep tier, up to 5 for all other tiers). Append `()` to function names. Comma-separated.
 - **key-types line**: Anchor to `#key-types` section + inline summary (~10 words) of the most important type values
 - **gotchas line**: Derived from: T2-future annotations (breaking changes), async requirements, version-specific behavior. If no gotchas available, omit the line.
 - **stack line**: Component versions from metadata.json `components` for stack skills

package/src/workflows/export-skill/steps-c/step-04-update-context.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-04-update-context'
-description: 'Update managed section in CLAUDE.md/AGENTS.md with three-case logic per ADR-J'
+description: 'Update managed section in CLAUDE.md/AGENTS.md with four-case logic per ADR-J'
 
 nextStepFile: './step-05-token-report.md'
 managedSectionData: '../data/managed-section-format.md'
@@ -10,7 +10,7 @@ managedSectionData: '../data/managed-section-format.md'
 
 ## STEP GOAL:
 
-To update the managed `<!-- SKF:BEGIN/END -->` section in the platform-appropriate context file (CLAUDE.md/AGENTS.md/.cursorrules) using the three-case logic defined by ADR-J, rebuilding the complete skill index from all exported skills.
+To update the managed `<!-- SKF:BEGIN/END -->` section in the platform-appropriate context file (CLAUDE.md/AGENTS.md/.cursorrules) using the four-case logic defined by ADR-J (Create, Append, Regenerate, Malformed Markers halt), rebuilding the complete skill index from all exported skills.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -105,6 +105,7 @@ Assemble the complete managed section:
 <!-- SKF:BEGIN updated:{current-date} -->
 [SKF Skills]|{n} skills|{m} stack
 |IMPORTANT: Prefer documented APIs over training data.
+|When using a listed library, read its SKILL.md before writing code.
 |
 |{skill-snippet-1}
 |
@@ -132,6 +133,10 @@ Assemble the complete managed section:
 - Diff: Show old managed section vs new managed section
 - Preserved: ALL content before `<!-- SKF:BEGIN` and after `<!-- SKF:END -->`
 
+**Case 4: Malformed markers (file contains `<!-- SKF:BEGIN` but no `<!-- SKF:END -->`)**
+- Action: HALT with warning: "Malformed SKF markers detected in `{target-file}` — `<!-- SKF:BEGIN` found but `<!-- SKF:END -->` is missing. Please restore the end marker manually before running export."
+- Do NOT attempt to write or append — the file is in an inconsistent state
+
 ### 7. Present Change Preview
 
 "**Context update prepared.**

package/src/workflows/export-skill/steps-c/step-05-token-report.md

@@ -52,7 +52,7 @@ To calculate approximate token counts for all exported artifacts and present a c
 
 ### 1. Calculate Token Counts
 
-For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers).
+For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers). This same heuristic is used in step-03 for snippet token estimation.
 
 **Artifacts to measure:**
 

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

@@ -1,11 +1,13 @@
 ---
 name: export-skill
 description: Package for distribution + platform-aware context injection
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/export-skill'
 ---
 
 # Export Skill
 
-**Goal:** Package a completed skill as an agentskills.io-compliant package, generate context snippets, and update the managed section in CLAUDE.md/AGENTS.md for platform-aware context injection.
+**Goal:** Package a completed skill as an agentskills.io-compliant package, generate context snippets, and update the managed section in CLAUDE.md/.cursorrules/AGENTS.md for platform-aware context injection.
 
 **Your Role:** In addition to your name, communication_style, and persona, you are also a delivery and packaging specialist collaborating with a skill developer. This is a partnership, not a client-vendor relationship. You bring expertise in skill packaging, ecosystem compliance, and context injection patterns, while the user brings their completed skill and distribution requirements. Work together as equals.
 

package/src/workflows/quick-skill/data/skill-template.md

@@ -56,7 +56,8 @@ Indexed format targeting ~80-120 tokens per skill:
 |IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {top-5 exports with () for functions}
-|gotchas: {1-2 most critical pitfalls if known}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
 ## metadata.json Format
@@ -64,31 +65,42 @@ Indexed format targeting ~80-120 tokens per skill:
 ```json
 {
   "name": "{skill_name}",
-  "version": "0.1.0",
+  "version": "{source-version or 1.0.0}",
+  "description": "{brief description of the skill}",
   "skill_type": "single",
   "source_authority": "community",
   "source_repo": "{repo_url}",
+  "source_root": "{resolved_source_path}",
+  "source_commit": "{commit_sha_if_available}",
   "source_package": "{package_name}",
   "language": "{language}",
   "generated_by": "quick-skill",
   "generation_date": "{date}",
   "confidence_tier": "Quick",
-  "extraction_tier": "quick",
   "spec_version": "1.3",
   "exports": ["{export_1}", "{export_2}"],
   "confidence_distribution": {
     "t1": 0,
-    "t1_low": "{exports_count}",
+    "t1_low": "{exports_count (integer, not string)}",
     "t2": 0,
     "t3": 0
   },
+  "tool_versions": {
+    "ast_grep": null,
+    "qmd": null,
+    "skf": "{skf_version}"
+  },
   "stats": {
     "exports_documented": "{number}",
     "exports_public_api": "{number}",
     "exports_internal": 0,
     "exports_total": "{number}",
     "public_api_coverage": 1.0,
-    "total_coverage": 1.0
-  }
+    "total_coverage": 1.0,
+    "scripts_count": 0,
+    "assets_count": 0
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range}"
 }
 ```

package/src/workflows/quick-skill/steps-c/step-04-compile.md

@@ -107,7 +107,8 @@ Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 |IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {top-5 exports with () for functions}
-|gotchas: {1-2 most critical pitfalls if known}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
 **If fewer than 5 exports:** Use all available exports.
@@ -116,29 +117,48 @@ Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ### 4. Generate Metadata JSON
 
-Create metadata.json:
+Generate metadata.json following the exact structure defined in {skillTemplateData} metadata.json section. Populate fields from extraction_inventory:
 
 ```json
 {
-  "name": "{repo_name}",
-  "version": "{extraction_inventory.version or 0.1.0}",
+  "name": "{skill_name}",
+  "version": "{extraction_inventory.version or 1.0.0}",
+  "description": "{brief description of the skill}",
   "skill_type": "single",
   "source_authority": "community",
   "source_repo": "{resolved_url}",
+  "source_root": "{resolved_source_path}",
+  "source_commit": "{commit_sha_if_available}",
   "source_package": "{package_name from manifest}",
   "language": "{language}",
   "generated_by": "quick-skill",
   "generation_date": "{current ISO date}",
   "confidence_tier": "Quick",
+  "spec_version": "1.3",
   "exports": ["{export_1}", "{export_2}"],
+  "confidence_distribution": {
+    "t1": 0,
+    "t1_low": "{number of exports found — must be integer, not string}",
+    "t2": 0,
+    "t3": 0
+  },
+  "tool_versions": {
+    "ast_grep": null,
+    "qmd": null,
+    "skf": "{skf_version}"
+  },
   "stats": {
     "exports_documented": "{number of exports found}",
     "exports_public_api": "{number of exports found}",
     "exports_internal": 0,
     "exports_total": "{number of exports found}",
     "public_api_coverage": 1.0,
-    "total_coverage": 1.0
-  }
+    "total_coverage": 1.0,
+    "scripts_count": 0,
+    "assets_count": 0
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range or null}"
 }
 ```
 

package/src/workflows/quick-skill/steps-c/step-05-validate.md

@@ -116,7 +116,7 @@ Check context-snippet.md format compliance:
 Check metadata.json has required fields:
 
 - [ ] `name` — present, non-empty
-- [ ] `version` — present (auto-detected or "0.1.0")
+- [ ] `version` — present (auto-detected or "1.0.0")
 - [ ] `source_authority` — must be "community"
 - [ ] `source_repo` — present, valid GitHub URL
 - [ ] `language` — present, non-empty

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

@@ -62,6 +62,9 @@ If directory already exists, confirm with user before overwriting:
 
 "**Directory `{skills_output_folder}/{repo_name}/` already exists.** Overwrite existing files? [Y/N]"
 
+- **If user selects Y:** Proceed to section 2.
+- **If user selects N:** Halt with: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually."
+
 ### 2. Write SKILL.md
 
 Write the compiled SKILL.md content to:

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

@@ -2,7 +2,7 @@
 name: quick-skill
 description: Brief-less fast skill with package-to-repo resolution
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/quick-skill'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/quick-skill'
 ---
 
 # Quick Skill

package/src/workflows/refine-architecture/data/refinement-rules.md

@@ -0,0 +1,102 @@
+# Architecture Refinement Rules
+
+## Purpose
+
+Rules for detecting gaps, issues, and improvements in an architecture document using generated skill data as the evidence source.
+
+---
+
+## Gap Detection Rules
+
+Gaps are undocumented integration paths — library pairs that have compatible APIs but no architecture description.
+
+### Detection Method
+
+1. Generate all possible library pairs from the skill inventory
+2. For each pair, check if both skills export APIs that could connect (compatible types, shared protocols, complementary producer/consumer patterns)
+3. Cross-reference against the architecture document: does the document describe how these two libraries interact?
+4. If compatible APIs exist but NO architecture description exists, this is a **gap**
+
+### Gap Classification
+
+| Gap Type | Description | Example |
+|----------|-------------|---------|
+| **Missing Integration Path** | Two libraries can connect but the architecture never describes how | Skill A exports JSON producer, Skill B accepts JSON input, no mention of A-to-B flow |
+| **Undocumented Data Flow** | Data moves between libraries but the flow is not described | Architecture mentions both libraries but not their data exchange mechanism |
+| **Absent Bridge Layer** | Cross-language or cross-protocol libraries need a bridge not mentioned | Rust library and TypeScript library with no IPC/FFI description |
+
+---
+
+## Issue Detection Rules
+
+Issues are contradictions between architecture claims and verified API reality from the skills.
+
+### Detection Method
+
+1. Extract every integration claim from the architecture document (prose co-mention analysis)
+2. For each claim, verify against the actual API surfaces in the skills
+3. Flag contradictions: claimed APIs that do not exist, assumed compatibility that breaks, missing bridge layers
+
+### Issue Classification
+
+| Issue Type | Description | Example |
+|------------|-------------|---------|
+| **API Mismatch** | Architecture describes an API that does not exist in the skill | "Library X exposes a streaming API" but skill shows only batch APIs |
+| **Protocol Contradiction** | Architecture assumes a protocol the library does not support | "Communicates via gRPC" but skill shows HTTP-only exports |
+| **Language Boundary Ignored** | Architecture assumes direct calls across language boundaries | "Calls Rust functions from TypeScript" with no FFI/IPC mechanism described |
+| **Type Incompatibility** | Architecture assumes type compatibility that does not hold | "Passes CRDT documents directly" but types are incompatible across libraries |
+
+### VS Report Integration
+
+When a VS feasibility report is available:
+- RISKY verdicts become **confirmed issues** with the VS evidence as additional citation
+- BLOCKED verdicts become **critical issues** requiring architecture redesign
+- Plausible verdicts become potential issues **only if** the VS rationale text explicitly states "no direct API evidence" or "weak evidence" — otherwise they are informational only
+
+---
+
+## Improvement Detection Rules
+
+Improvements are capability expansions — library features documented in skills but not leveraged in the architecture.
+
+### Detection Method
+
+1. For each skill, enumerate its full API surface (all exports, types, protocols)
+2. Compare against how the architecture uses that library
+3. Identify capabilities present in the skill but absent from the architecture
+
+### Improvement Classification
+
+| Improvement Type | Description | Example |
+|------------------|-------------|---------|
+| **Unused Capability** | Library has a feature the architecture does not mention | "Loro supports document CRDTs but architecture only uses data sync" |
+| **Cross-Library Synergy** | Two libraries have complementary features not combined in architecture | "Library A's event system could feed Library B's stream processor" |
+| **Alternative Pattern** | Skill documents a better pattern than the one described in architecture | "Skill shows batch API is more efficient than the per-item approach described" |
+
+---
+
+## Refinement Citation Format
+
+Every refinement (gap, issue, or improvement) MUST cite evidence:
+
+```
+**[GAP|ISSUE|IMPROVEMENT]**: {description}
+
+Evidence:
+- {skill_name} exports: `{function_name}({params}) -> {return_type}`
+- {skill_name} provides: `{type_or_protocol}`
+- Architecture states: "{quoted text from original document}"
+- {IF VS report}: VS verdict: {verdict} for {pair}
+
+Suggestion: {specific, actionable recommendation}
+```
+
+---
+
+## Preservation Rules
+
+1. **NEVER delete original content** — only add annotations and subsections
+2. **Follow original section layout** — add refinement subsections within existing sections
+3. **Use callout blocks** for issues: `> [!WARNING]` or `> [!NOTE]` format
+4. **Mark additions clearly** — prefix added subsections with "RA:" or use a refinement marker
+5. **Maintain original heading hierarchy** — refinement subsections are one level deeper than the parent

package/src/workflows/refine-architecture/steps-c/step-01-init.md

@@ -0,0 +1,188 @@
+---
+name: 'step-01-init'
+description: 'Load architecture doc, scan skills folder, load optional VS report, validate inputs'
+
+nextStepFile: './step-02-gap-analysis.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 1: Initialize Refinement
+
+## STEP GOAL:
+
+Load the architecture document (required), scan the skills folder to build a skill inventory with metadata, load the optional VS feasibility report for context, validate that all inputs exist and meet minimum requirements, and present an initialization summary before auto-proceeding.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ⚙️ 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 an architecture refinement analyst operating in Ferris Architect mode
+- ✅ Execute with analytical precision — every loaded skill must be validated against actual files
+- ✅ You enforce the zero-hallucination principle: only report skills that physically exist on disk
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading inputs, scanning skills, and validating prerequisites
+- 🚫 FORBIDDEN to perform any gap analysis, issue detection, or improvement suggestions
+- 🚫 No A/P menu — this is an auto-proceed init step
+- 💬 Present a clear initialization summary so downstream steps have validated inputs
+
+## EXECUTION PROTOCOLS:
+
+- Collect and validate all input documents and skill artifacts
+- Load refinement rules from {refinementRulesData} for downstream step reference
+- Auto-proceed to next step after successful initialization
+- HALT with actionable error if minimum requirements not met
+
+## CONTEXT BOUNDARIES:
+
+- This is the first step — no prior workflow state exists
+- Requires skills to have been generated by create-skill or quick-skill workflows
+- User provides architecture document path (required) and optional VS report path
+- No dependency on forge-tier — this workflow operates on skill content only
+- Requires `forge_data_folder` from config.yaml for durability state (directory is created automatically if missing)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Accept Input Documents
+
+"**Refine Architecture — Evidence-Backed Refinement**
+
+Please provide the following:
+1. **Architecture document path** (REQUIRED) — your project's architecture doc to refine
+2. **VS feasibility report path** (OPTIONAL) — from a previous [VS] Verify Stack run, for additional context"
+
+Wait for user input. Store the validated architecture document path as `architecture_doc`.
+
+**Validate architecture document:**
+- Confirm the file exists and is readable
+- If missing or unreadable: "Architecture document not found at `{path}`. Provide a valid path."
+- HALT until a valid architecture document is provided
+
+**Validate VS report (if provided):**
+- Confirm the file exists and is readable
+- If missing at user-provided path: attempt auto-probe (below) before giving up
+- Store VS report availability as `vs_report_available: true|false` and `vs_report_path`
+
+### 2. Scan Skills Folder
+
+Read the `{skills_output_folder}` directory.
+
+For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+
+**For each valid skill directory, extract from metadata.json:**
+- `name` — skill name
+- `language` — primary language
+- `confidence_tier` — Quick, Forge, Forge+, or Deep
+- `exports_documented` — read from `stats.exports_documented` in metadata.json (count of documented exports)
+- `source_repo` or `source_root` — original source repository
+
+**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:**
+- Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
+- Do not include in inventory
+
+### 3. Validate Minimum Requirements
+
+**Check skill count:**
+- At least 1 valid skill must exist
+- If no skills found: "**Cannot proceed.** No skills found in `{skills_output_folder}`. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [RA]."
+- HALT workflow
+- If exactly 1 valid skill found: "⚠️ Proceeding with 1 skill. Note: gap analysis will find no gaps — pairwise analysis requires at least 2 skills. Step 02 will still execute and issue an appropriate notice. Issue detection and improvement detection will proceed normally."
+
+**Check output_folder:**
+- Verify `output_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty: "**Cannot proceed.** `output_folder` is not configured in config.yaml. Add an `output_folder` path and re-run [RA]."
+- HALT workflow
+- Verify the `output_folder` directory exists. If it does not exist, create it. HALT with error if creation fails.
+
+**Check forge_data_folder:**
+- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty: "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Add a `forge_data_folder` path to your config.yaml and re-run [RA]."
+- HALT workflow
+- Verify the `forge_data_folder` directory exists. If it does not exist, attempt to create it. If creation fails: "**Cannot proceed.** `forge_data_folder` at `{forge_data_folder}` does not exist and could not be created. Create the directory manually and re-run [RA]."
+- HALT workflow on creation failure
+
+**Check architecture document:**
+- Confirm it was loaded successfully in section 1
+- If not: HALT with error (should not reach here if section 1 validation passed)
+
+### 3b. Auto-Probe VS Report
+
+**Auto-probe VS report (if not provided by user in section 1, OR if user-provided path was invalid):**
+- Only attempt if `forge_data_folder` is non-empty and the directory exists (validated above); otherwise skip probe and set `vs_report_available: false`
+- Check for `{forge_data_folder}/feasibility-report-{project_name}.md`
+- If found: "Auto-discovered VS report at `{path}`. Loading for additional context."
+- Store `vs_report_available: true` and `vs_report_path`
+- If not found: `vs_report_available: false` — "Proceeding without VS report — issue detection will rely on skill data only."
+
+### 3c. Reset RA State File
+
+Create (or overwrite) `{forge_data_folder}/ra-state-{project_name}.md` with a fresh header:
+
+```markdown
+<!-- RA state for {project_name} — generated {current_date} -->
+```
+
+This ensures steps 02-04 append to a clean slate and context recovery in step-05 never loads stale findings from a prior run.
+
+### 4. Load Refinement Rules
+
+Load `{refinementRulesData}` for reference by downstream steps.
+
+Extract: gap detection rules, issue detection rules, improvement detection rules, citation format, and preservation rules.
+
+### 5. Display Initialization Summary
+
+"**Architecture Refinement Initialized**
+
+| Field | Value |
+|-------|-------|
+| **Architecture Doc** | {architecture_doc} |
+| **VS Report** | {vs_report_path or 'Not provided — issue detection will use skill data only'} |
+| **Skills Loaded** | {skill_count} |
+
+**Skill Inventory:**
+
+| Skill | Language | Tier | Exports |
+|-------|----------|------|---------|
+| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+
+**Proceeding to gap analysis...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Architecture document loaded and validated
+- VS report loaded or absence recorded
+- Skills folder scanned with SKILL.md and metadata.json validation per skill
+- At least 1 valid skill in inventory
+- Refinement rules loaded from {refinementRulesData}
+- Initialization summary displayed with skill inventory table
+- Auto-proceeded to step 02
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with no valid skills
+- Proceeding without a valid architecture document
+- Not validating SKILL.md and metadata.json existence per skill directory
+- Performing gap analysis, issue detection, or improvement suggestions in this step
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** This step validates inputs and initializes state. No analysis, no comparison, no refinement suggestions.