bmad-module-skill-forge 0.2.0

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

@@ -0,0 +1,180 @@
+---
+name: 'step-04-compile'
+description: 'Assemble best-effort SKILL.md, context-snippet.md, and metadata.json from extraction inventory'
+
+nextStepFile: './step-05-validate.md'
+skillTemplateData: '../data/skill-template.md'
+---
+
+# Step 4: Compile
+
+## STEP GOAL:
+
+To assemble the best-effort SKILL.md document, context-snippet.md in ADR-L two-line format, and metadata.json with `source_authority: community` from the extraction inventory. Present compiled output for review before validation.
+
+## 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a rapid skill compiler assembling output documents
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Best-effort quality — populate what's available, mark gaps honestly
+- ✅ Follow template structure exactly from {skillTemplateData}
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on assembling the three output documents
+- 🚫 FORBIDDEN to write files to disk — that's step-06
+- 💬 Approach: Load template, populate from inventory, present for review
+- 📋 Mark any sections with insufficient data as best-effort
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Set state: skill_content, context_snippet, metadata_json
+- 📖 Load {skillTemplateData} for section structure and format specs
+- 🚫 Do not write files — only assemble content in memory
+
+## CONTEXT BOUNDARIES:
+
+- Previous step provided: extraction_inventory (exports, description, manifest_data, confidence)
+- Also available: resolved_url, repo_name, language, scope_hint
+- Focus: compilation and assembly only
+- This step presents output for review — user gets a checkpoint before validation
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Skill Template
+
+Load {skillTemplateData} to understand:
+- SKILL.md required and optional sections
+- context-snippet.md two-line format (ADR-L)
+- metadata.json field requirements
+
+### 2. Assemble SKILL.md
+
+Using the template structure, populate each section from extraction_inventory:
+
+**Required sections:**
+- **Overview:** Package name, repository, language, source authority, generation date
+- **Description:** From extraction_inventory.description (README-derived)
+- **Key Exports:** From extraction_inventory.exports — list each with name, type, brief description
+- **Usage Patterns:** From extraction_inventory.usage_patterns (README examples)
+
+**Optional sections (include when data available):**
+- **Configuration:** If configuration options were found in source
+- **Dependencies:** Key dependencies from manifest
+- **Notes:** Caveats, limitations, extraction confidence level
+
+**If confidence is low:**
+- Include a note: "This skill was generated with limited source data. Consider running create-skill for a more thorough compilation."
+
+### 3. Generate Context Snippet
+
+Create context-snippet.md in ADR-L two-line format (~30 tokens):
+
+```
+{skill_name}: {top-5 exports as comma-separated list}
+  → {skills_output_folder}/{skill_name}/SKILL.md
+```
+
+**If fewer than 5 exports:** Use all available exports.
+**If no exports:** Use key features from description instead.
+
+### 4. Generate Metadata JSON
+
+Create metadata.json:
+
+```json
+{
+  "name": "{repo_name}",
+  "version": "0.1.0",
+  "source_authority": "community",
+  "source_repo": "{resolved_url}",
+  "source_package": "{package_name from manifest}",
+  "language": "{language}",
+  "generated_by": "quick-skill",
+  "generated_date": "{current date}",
+  "exports_count": {number of exports found},
+  "confidence": "{extraction confidence}"
+}
+```
+
+### 5. Present Compiled Output for Review
+
+"**Compilation complete. Review before validation:**
+
+---
+
+**SKILL.md Preview:**
+
+{Display the full assembled SKILL.md content}
+
+---
+
+**context-snippet.md:**
+
+{Display the two-line snippet}
+
+---
+
+**metadata.json:**
+
+{Display the JSON}
+
+---
+
+**Extraction confidence:** {confidence}
+**Exports documented:** {count}
+
+Review the output above. When ready, continue to validation."
+
+### 6. Present MENU OPTIONS
+
+Display: **Select:** [C] Continue to Validation
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other: Help user adjust compiled output, then redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting compiled output
+- ONLY proceed to validation when user selects 'C'
+- User can request changes to the compiled output before proceeding
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user reviews the compiled output and selects 'C' will you load and read fully `{nextStepFile}` to execute validation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- SKILL.md assembled with all available sections populated
+- context-snippet.md generated in correct two-line ADR-L format
+- metadata.json generated with source_authority: community
+- Compiled output presented for user review
+- User confirms readiness before proceeding to validation
+
+### ❌ SYSTEM FAILURE:
+
+- Writing files to disk (that's step-06)
+- Skipping the review checkpoint
+- Not following template structure from {skillTemplateData}
+- Hallucinating exports or data not in extraction_inventory
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

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

@@ -0,0 +1,150 @@
+---
+name: 'step-05-validate'
+description: 'Validate compiled SKILL.md, context-snippet, and metadata against agentskills.io spec'
+
+nextStepFile: './step-06-write.md'
+---
+
+# Step 5: Validate
+
+## STEP GOAL:
+
+To validate the compiled SKILL.md, context-snippet.md, and metadata.json against the agentskills.io specification at community tier. Report any gaps or issues. This is advisory validation — issues are reported but do not block output.
+
+## 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a rapid skill compiler performing quality checks
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Community-tier validation — lighter than official requirements
+- ✅ Report issues honestly but don't block output
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on validating the compiled output
+- 🚫 FORBIDDEN to modify the compiled content — report issues only
+- 💬 Approach: Check each requirement, report findings, proceed
+- 📋 Validation failures are advisory — user can proceed regardless
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Set state: validation_result (pass/fail, issues_list)
+- 📖 Check against community-tier requirements
+- 🚫 Do not block output on validation issues
+
+## CONTEXT BOUNDARIES:
+
+- Previous step provided: skill_content (SKILL.md), context_snippet, metadata_json
+- Focus: validation only, not modification
+- Community tier has lighter requirements than official
+- Dependencies: compiled output from step-04
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Validate SKILL.md Structure
+
+Check that SKILL.md has these required sections populated:
+
+- [ ] **Overview section** present with package name, repo, language, authority
+- [ ] **Description section** present with non-empty content
+- [ ] **Key Exports section** present (may be empty if confidence is low)
+- [ ] **Usage Patterns section** present (may have README fallback)
+
+**For each missing or empty required section, log an issue.**
+
+### 2. Validate Context Snippet Format
+
+Check context-snippet.md format compliance:
+
+- [ ] **Two-line format** — first line has skill name and exports, second line has path pointer
+- [ ] **First line** matches pattern: `{name}: {exports list}`
+- [ ] **Second line** matches pattern: `  → {path}/SKILL.md`
+- [ ] **Approximate token count** is ~30 tokens or less
+
+**If format is wrong, log an issue.**
+
+### 3. Validate Metadata JSON
+
+Check metadata.json has required fields:
+
+- [ ] `name` — present, non-empty
+- [ ] `version` — present (should be "0.1.0")
+- [ ] `source_authority` — must be "community"
+- [ ] `source_repo` — present, valid GitHub URL
+- [ ] `language` — present, non-empty
+- [ ] `generated_by` — must be "quick-skill"
+- [ ] `generated_date` — present
+- [ ] `exports_count` — present, number
+- [ ] `confidence` — present
+
+**For each missing or invalid field, log an issue.**
+
+### 4. Report Validation Results
+
+"**Validation complete:**
+
+**SKILL.md:** {pass/issues found}
+{list any issues}
+
+**context-snippet.md:** {pass/issues found}
+{list any issues}
+
+**metadata.json:** {pass/issues found}
+{list any issues}
+
+**Overall:** {pass / N issues found}
+
+{If issues found:}
+These issues are advisory for community-tier skills. You can proceed to write output or go back to adjust.
+
+**Proceeding to write output...**"
+
+Set `validation_result` with pass/fail status and issues list.
+
+### 5. Auto-Proceed to Write
+
+#### Menu Handling Logic:
+
+- After validation report, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step — validation is advisory
+- Proceed directly to write step after reporting results
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN validation checks are complete and results reported will you load and read fully `{nextStepFile}` to execute file writing.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All three outputs validated against requirements
+- Issues reported clearly with specific details
+- Community-tier validation applied (not official-tier strictness)
+- validation_result set with pass/fail and issues list
+- Auto-proceeding to write step
+
+### ❌ SYSTEM FAILURE:
+
+- Modifying compiled content instead of just reporting
+- Blocking output on validation issues (advisory only)
+- Skipping validation checks
+- Not reporting found issues
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

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

@@ -0,0 +1,160 @@
+---
+name: 'step-06-write'
+description: 'Write output files to skills folder and display completion summary'
+---
+
+# Step 6: Write Output
+
+## STEP GOAL:
+
+To write the compiled SKILL.md, context-snippet.md, and metadata.json to the skills output folder and display a completion summary with next step recommendations.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a rapid skill compiler delivering the final output
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Precision file writing — correct paths, correct content
+- ✅ This is the final step — deliver cleanly and recommend next actions
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on writing files and displaying summary
+- 🚫 FORBIDDEN to modify content — write exactly what was compiled
+- 💬 Approach: Create directory, write files, confirm, summarize
+- 📋 If write fails, hard halt with error details
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Write three files to {skills_output_folder}/{repo_name}/
+- 📖 File I/O required for directory creation and file writing
+- 🚫 This is the final step — no next step to load
+
+## CONTEXT BOUNDARIES:
+
+- Previous steps provided: skill_content, context_snippet, metadata_json, validation_result
+- Also available: resolved_url, repo_name, language, skills_output_folder
+- Focus: file writing and completion only
+- This is the FINAL step — workflow ends here
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Create Output Directory
+
+Create the skill output directory:
+
+```
+{skills_output_folder}/{repo_name}/
+```
+
+If directory already exists, confirm with user before overwriting:
+
+"**Directory `{skills_output_folder}/{repo_name}/` already exists.** Overwrite existing files? [Y/N]"
+
+### 2. Write SKILL.md
+
+Write the compiled SKILL.md content to:
+
+```
+{skills_output_folder}/{repo_name}/SKILL.md
+```
+
+Confirm: "Written: SKILL.md"
+
+### 3. Write context-snippet.md
+
+Write the context snippet to:
+
+```
+{skills_output_folder}/{repo_name}/context-snippet.md
+```
+
+Confirm: "Written: context-snippet.md"
+
+### 4. Write metadata.json
+
+Write the metadata JSON to:
+
+```
+{skills_output_folder}/{repo_name}/metadata.json
+```
+
+Confirm: "Written: metadata.json"
+
+### 5. Handle Write Failures
+
+**If any file write fails — HARD HALT:**
+
+"**Write failed:** Could not write to `{file_path}`.
+
+Error: {error details}
+
+Please check:
+- Does the output directory exist and is it writable?
+- Is there sufficient disk space?
+- Are there permission issues?"
+
+### 6. Display Completion Summary
+
+"**Quick Skill complete.**
+
+**Skill:** {repo_name}
+**Language:** {language}
+**Source:** {resolved_url}
+**Authority:** community
+**Confidence:** {extraction confidence}
+
+**Files written:**
+- `{skills_output_folder}/{repo_name}/SKILL.md`
+- `{skills_output_folder}/{repo_name}/context-snippet.md`
+- `{skills_output_folder}/{repo_name}/metadata.json`
+
+**Exports documented:** {count}
+**Validation:** {pass / N issues (advisory)}
+
+---
+
+**Recommended next steps:**
+
+1. **test-skill** (advisory) — Run cognitive completeness verification on the generated skill
+2. **export-skill** — Package and distribute the skill with platform-aware context injection
+
+**Note:** This is a best-effort community skill. For deeper analysis with AST-verified exports and provenance tracking, use the full **create-skill** workflow with a skill brief."
+
+### 7. End Workflow
+
+This is the final step. The workflow is complete.
+
+No next step to load. Session ends here.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Output directory created (or overwrite confirmed)
+- All three files written successfully
+- Completion summary displayed with file paths
+- Next step recommendations provided
+- Workflow ends cleanly
+
+### ❌ SYSTEM FAILURE:
+
+- Modifying content during write (write exactly what was compiled)
+- Not handling write failures with hard halt
+- Not displaying completion summary
+- Attempting to load a next step (this is final)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.