bmad-module-skill-forge 0.2.0

package/src/workflows/create-stack-skill/steps-c/step-07-generate-output.md

@@ -0,0 +1,202 @@
+---
+name: 'step-07-generate-output'
+description: 'Write all output files — SKILL.md, references, metadata, context-snippet, and forge-data'
+
+nextStepFile: './step-08-validate.md'
+stackSkillTemplate: '../data/stack-skill-template.md'
+---
+
+# Step 7: Generate Output Files
+
+## STEP GOAL:
+
+Write all deliverable and workspace artifact files to their target directories.
+
+## 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 a skill packager operating in Ferris Architect mode
+- ✅ Precise file writing — every file matches its template structure
+- ✅ Hard halt on any write failure — partial output is worse than no output
+
+### Step-Specific Rules:
+
+- 🎯 Write ALL output files in correct directory structure
+- 🚫 FORBIDDEN to modify compiled content — step 06 produced the approved version
+- 💬 Report each file written with path and size
+- 🎯 Create directory structure before writing files
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Create output directories, write all files
+- 💾 Store written_files list as workflow state
+- 📖 Auto-proceed to validation after all files written
+- 🚫 HARD HALT on any individual file write failure
+
+## CONTEXT BOUNDARIES:
+
+- From step 06: skill_content (approved compiled SKILL.md)
+- From step 04: per_library_extractions[] for reference files
+- 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)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Create Output Directories
+
+Create the directory structure:
+
+```
+{skills_output_folder}/{project_name}-stack/
+├── references/
+│   └── integrations/
+```
+
+```
+{forge_data_folder}/{project_name}-stack/
+```
+
+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.
+
+### 3. Write Per-Library Reference Files
+
+For each confirmed library, write `{skills_output_folder}/{project_name}-stack/references/{library_name}.md`:
+
+Load structure from `{stackSkillTemplate}` references section:
+- Library name, version from manifest
+- Import count and file count
+- Key exports with signatures
+- Usage patterns with file:line citations
+- Confidence tier label
+
+### 4. Write Integration Pair Reference Files
+
+For each detected integration pair, write `{skills_output_folder}/{project_name}-stack/references/integrations/{libraryA}-{libraryB}.md`:
+
+Load structure from `{stackSkillTemplate}` integrations section:
+- Library pair and integration type
+- Co-import file count
+- Integration pattern description with file:line citations
+- Usage convention
+- Confidence tier label
+
+**If no integrations detected:** Skip this section (no files to write).
+
+### 5. Write context-snippet.md
+
+Write `{skills_output_folder}/{project_name}-stack/context-snippet.md`:
+
+Use ADR-L two-line format targeting ~30 tokens per library entry:
+```
+**{library}** ({import_count} imports): {top_3_exports}
+  → integrates with: {comma-separated integration partners}
+```
+
+### 6. Write metadata.json
+
+Write `{skills_output_folder}/{project_name}-stack/metadata.json`:
+
+```json
+{
+  "skill_type": "stack",
+  "skill_name": "{project_name}-stack",
+  "version": "1.0.0",
+  "created": "{current_date}",
+  "forge_tier": "{tier}",
+  "library_count": N,
+  "integration_count": N,
+  "libraries": ["lib1", "lib2"],
+  "integration_pairs": [["lib1", "lib2"]],
+  "confidence_distribution": {"T1": N, "T1-low": N, "T2": N}
+}
+```
+
+### 7. Write Forge Data Artifacts
+
+Write workspace artifacts to `{forge_data_folder}/{project_name}-stack/`:
+
+**provenance-map.json:**
+```json
+{
+  "libraries": {
+    "lib_name": {
+      "manifest_source": "package.json",
+      "extraction_method": "ast_bridge|source_reading|qmd_bridge",
+      "confidence": "T1|T1-low|T2",
+      "files_analyzed": N,
+      "exports_found": N
+    }
+  },
+  "integrations": {
+    "libA+libB": {
+      "detection_method": "co-import grep",
+      "co_import_files": N,
+      "type": "pattern_type"
+    }
+  }
+}
+```
+
+**evidence-report.md:**
+- Extraction summary per library
+- Integration detection results per pair
+- Warnings and failures encountered
+- Confidence tier distribution
+
+### 8. 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
+
+**Workspace** ({forge_data_folder}/{project_name}-stack/):
+- ✓ provenance-map.json
+- ✓ evidence-report.md
+
+**Total files written:** {total_count}
+
+**Proceeding to validation...**"
+
+### 9. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All deliverable files written to skills_output_folder
+- All workspace artifacts written to forge_data_folder
+- Directory structure created correctly
+- Each file matches its template structure
+- Write summary displayed with accurate counts
+
+### ❌ SYSTEM FAILURE:
+
+- Any file write failure not caught (hard halt required)
+- Modifying approved skill_content during writing
+- Missing files from the expected output set
+- Wrong directory paths for output
+
+**Master Rule:** Write everything, modify nothing. Hard halt on any write failure.

package/src/workflows/create-stack-skill/steps-c/step-08-validate.md

@@ -0,0 +1,193 @@
+---
+name: 'step-08-validate'
+description: 'Validate all output files against structure requirements and confidence tier completeness'
+
+nextStepFile: './step-09-report.md'
+stackSkillTemplate: '../data/stack-skill-template.md'
+---
+
+# Step 8: Validate Output
+
+## STEP GOAL:
+
+Validate all written output files against their expected structure and verify confidence tier label completeness.
+
+## 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 a quality gate operator in Ferris Architect mode
+- ✅ Validation is advisory — findings are warnings, not blockers
+- ✅ Report findings accurately — do not downplay or exaggerate
+
+### Step-Specific Rules:
+
+- 🎯 Validate structure and completeness, not content quality
+- 🚫 FORBIDDEN to modify any output files — validation is read-only
+- 💬 Report findings with specific file paths and issue descriptions
+- 🎯 Advisory mode: always proceed to report regardless of findings
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check each deliverable file against its expected structure
+- 💾 Store validation_result as workflow state
+- 📖 Auto-proceed to report after validation complete
+- 🚫 FORBIDDEN to halt on validation warnings (advisory only)
+
+## CONTEXT BOUNDARIES:
+
+- From step 07: written_files[] (all output artifacts with paths)
+- From step 01: forge_tier, project_name, skills_output_folder, forge_data_folder
+- This step produces: validation_result {status, findings[], warnings[]}
+- This is a quality gate — findings inform the report but do not block it
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Verify File Existence
+
+Check that all expected files exist from written_files[]:
+
+**Deliverables** (`{skills_output_folder}/{project_name}-stack/`):
+- [ ] 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/`):
+- [ ] provenance-map.json
+- [ ] evidence-report.md
+
+Record any missing files as **ERROR** findings.
+
+### 2. Validate SKILL.md Structure
+
+Load `{stackSkillTemplate}` and verify SKILL.md contains expected sections:
+
+- [ ] Header with project name, library count, integration count, forge tier
+- [ ] Integration Patterns section (should appear BEFORE per-library summaries)
+- [ ] Library Reference Index table
+- [ ] Per-Library Summaries section
+- [ ] Conventions section
+
+Record missing sections as **WARNING** findings.
+
+### 3. Validate metadata.json Fields
+
+Parse metadata.json and verify required fields:
+
+- [ ] `skill_type` equals "stack"
+- [ ] `skill_name` matches `{project_name}-stack`
+- [ ] `version` is present
+- [ ] `created` is present
+- [ ] `forge_tier` matches the tier from step 01
+- [ ] `library_count` matches actual number of reference files
+- [ ] `integration_count` matches actual integration pair files
+- [ ] `libraries` array is present and non-empty
+- [ ] `confidence_distribution` object is present with T1/T1-low/T2 keys
+
+Record mismatches as **WARNING** findings.
+
+### 4. Validate Reference File Completeness
+
+For each confirmed library, verify `references/{library}.md` exists and contains:
+- [ ] Library name header
+- [ ] Version from manifest
+- [ ] Key Exports section
+- [ ] Usage Patterns section
+
+For each integration pair (if any), verify `references/integrations/{libraryA}-{libraryB}.md` exists and contains:
+- [ ] Integration pair header
+- [ ] Type classification
+- [ ] Integration Pattern section
+- [ ] Key Files section
+
+Record missing or incomplete files as **WARNING** findings.
+
+### 5. Validate Confidence Tier Labels
+
+Scan across all output files for confidence tier coverage:
+
+- [ ] SKILL.md: Each per-library summary has a confidence label
+- [ ] SKILL.md: Each integration pair entry has a confidence label
+- [ ] Reference files: Each has a confidence label in its header
+- [ ] metadata.json: confidence_distribution sums match library_count
+
+Record missing tier labels as **WARNING** findings.
+
+### 6. Validate context-snippet.md
+
+Verify context-snippet.md follows ADR-L two-line format:
+- [ ] Each library has an entry with import count and top exports
+- [ ] Integration partners listed on second line
+- [ ] No library from confirmed list is missing
+
+Record format violations as **WARNING** findings.
+
+### 7. Display Validation Results
+
+**If all checks pass:**
+
+"**Validation complete — all checks passed.**
+
+- **Files:** {file_count}/{file_count} present
+- **SKILL.md:** Structure valid
+- **metadata.json:** All required fields present
+- **References:** {lib_count} library + {pair_count} integration files verified
+- **Confidence tiers:** Complete coverage
+
+**Proceeding to summary report...**"
+
+**If warnings found:**
+
+"**Validation complete with {warning_count} finding(s).**
+
+**Findings:**
+{For each finding:}
+- ⚠ {severity}: {description} — {file_path}
+
+**Summary:**
+- **Files:** {present_count}/{expected_count} present
+- **Warnings:** {warning_count}
+- **Errors:** {error_count}
+
+{If errors (missing files):}
+**Note:** Missing files may indicate a write failure in step 07. Review evidence-report.md for details.
+
+**Proceeding to summary report...**"
+
+### 8. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All expected files checked for existence
+- SKILL.md validated against template structure
+- metadata.json fields verified
+- Reference files checked for completeness
+- Confidence tier coverage verified
+- Validation results displayed with specific findings
+- Advisory mode: always proceeded to report
+
+### ❌ SYSTEM FAILURE:
+
+- Modifying any output files during validation
+- Halting the workflow on validation warnings
+- Not checking all expected files
+- Reporting vague findings without file paths
+- Skipping the confidence tier check
+
+**Master Rule:** Validate everything, modify nothing. Advisory findings — always proceed to report.

package/src/workflows/create-stack-skill/steps-c/step-09-report.md

@@ -0,0 +1,137 @@
+---
+name: 'step-09-report'
+description: 'Display final stack skill summary with confidence distribution and next workflow recommendations'
+---
+
+# Step 9: Stack Skill Report
+
+## STEP GOAL:
+
+Display the final summary of the forged stack skill with confidence distribution, output file listing, and next workflow recommendations.
+
+## 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 Ferris delivering the final forge report
+- ✅ Positive capability framing — lead with what was accomplished
+- ✅ Warnings are secondary — present them only if they exist
+
+### Step-Specific Rules:
+
+- 🎯 This is the FINAL step — no nextStepFile
+- 🚫 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
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Compile summary from all previous step results
+- 📖 Display report to user — workflow is complete after this
+- 🚫 No file writes, no state updates — this is terminal output
+
+## CONTEXT BOUNDARIES:
+
+- From step 01: project_name, forge_tier
+- From step 03: confirmed_dependencies[] count
+- From step 04: per_library_extractions[] with confidence tiers
+- From step 05: integration_graph with pair count
+- From step 07: written_files[] with paths
+- From step 08: validation_result with findings
+- This step produces: console report (no stored artifacts)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Display Stack Forged Banner
+
+"**Stack forged: {project_name}-stack — {lib_count} libraries, {integration_count} integration patterns**
+
+Forge tier: **{tier}**"
+
+### 2. Display Confidence Distribution
+
+"**Confidence distribution:**
+
+| Tier | Count | Description |
+|------|-------|-------------|
+| T1 | {count} | AST-verified structural extraction |
+| T1-low | {count} | Source reading inference |
+| T2 | {count} | QMD-enriched temporal context |"
+
+### 3. Display Output File Summary
+
+"**Output files:**
+
+**Deliverables** (`{skills_output_folder}/{project_name}-stack/`):
+- 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/`):
+- provenance-map.json — Extraction source tracking
+- evidence-report.md — Evidence and confidence breakdown"
+
+### 4. Display Validation Summary
+
+**If validation passed with no findings:**
+
+"**Validation:** All checks passed"
+
+**If validation had findings:**
+
+"**Validation:** {warning_count} warning(s) found
+{For each finding:}
+- ⚠ {description}"
+
+### 5. Display Warnings (Conditional)
+
+**Only display if warnings exist from any step:**
+
+"**Warnings:**
+{For each warning from steps 04, 05, 07, 08:}
+- {warning_description}"
+
+**If no warnings:** Skip this section entirely.
+
+### 6. Recommend Next Workflows
+
+"**Next steps:**
+- **[TS] test-skill** — Validate the stack skill against its own assertions
+- **[ES] export-skill** — Package for distribution or agent loading
+
+**Workflow complete.**"
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Banner displayed with accurate library and integration counts
+- Confidence distribution table with correct tier counts
+- All output files listed with descriptions
+- Validation summary reflects actual step 08 findings
+- Warnings displayed only when they exist
+- Next workflow recommendations included
+- Positive capability framing throughout
+
+### ❌ SYSTEM FAILURE:
+
+- Inaccurate counts in banner or distribution table
+- Missing output files from the listing
+- Displaying warnings section when no warnings exist
+- Writing or modifying files in this step
+- Not recommending next workflows
+- Negative framing or apologetic tone
+
+**Master Rule:** Celebrate what was built. Report accurately. Recommend next steps. Workflow complete.