bmad-module-skill-forge 0.2.0

package/src/workflows/export-skill/steps-c/step-01-load-skill.md

@@ -0,0 +1,184 @@
+---
+name: 'step-01-load-skill'
+description: 'Load skill artifacts and validate spec compliance before export'
+
+nextStepFile: './step-02-package.md'
+---
+
+# Step 1: Load Skill
+
+## STEP GOAL:
+
+To load the target skill's artifacts, validate they meet agentskills.io spec compliance, parse export flags, and confirm with the user before proceeding to packaging.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER proceed without user confirmation of the loaded skill
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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 delivery and packaging specialist in Ferris Delivery mode
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Precise and efficient — validate thoroughly, report clearly
+- ✅ User brings the skill path and export preferences
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on loading, validating, and confirming the skill
+- 🚫 FORBIDDEN to modify any skill files — this is read-only
+- 🚫 FORBIDDEN to write any output files yet — packaging starts in step-02
+- 💬 Present a clear summary of what was found for user confirmation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Hold all loaded data in context for subsequent steps
+- 📖 Validate against agentskills.io spec requirements
+- 🚫 Hard halt if required files are missing — do not proceed with incomplete skill
+
+## CONTEXT BOUNDARIES:
+
+- Available: SKF module config (skills_output_folder, forge_data_folder)
+- Focus: Skill discovery, loading, and validation
+- Limits: Read-only — no file writes in this step
+- Dependencies: Skill must have been created by create-skill or update-skill
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Parse Export Arguments
+
+"**Starting skill export...**"
+
+Determine the skill to export and any flags:
+
+**Skill Path Discovery:**
+- If user provided a skill name or path as argument, use that
+- If not provided, search `{skills_output_folder}/*/SKILL.md` for available skills
+- If multiple skills found, present list and ask user to select
+- If no skills found, halt: "No skills found in {skills_output_folder}/. Run create-skill first."
+
+**Flag Parsing:**
+- `--platform` flag: Check if provided (claude/cursor/copilot). Default: `claude`
+- `--dry-run` flag: Check if provided. Default: `false`
+
+"**Skill:** {skill-name}
+**Platform:** {platform} ({target-file})
+**Dry Run:** {yes/no}"
+
+### 2. Load and Validate Skill Artifacts
+
+Load all files from the skill directory `{skills_output_folder}/{skill-name}/`:
+
+**Required Files (hard halt if missing):**
+- `SKILL.md` — The main skill document
+- `metadata.json` — Machine-readable skill metadata
+
+**Optional Files (note presence):**
+- `references/` — Progressive disclosure directory
+- `context-snippet.md` — Existing snippet (will be regenerated)
+
+**Validation Checks:**
+1. `SKILL.md` exists and is non-empty
+2. `metadata.json` exists and is valid JSON
+3. `metadata.json` contains required fields: `name`, `version`, `skill_type`, `source_authority`, `exports`, `generation_date`, `confidence_tier`
+4. `metadata.json.exports` is a non-empty array (warn if empty — graceful handling)
+
+**If any required validation fails:**
+"**Export cannot proceed.** Missing or invalid: {list failures}
+Run create-skill to generate a complete skill first."
+
+### 3. Read Skill Metadata
+
+Extract from `metadata.json`:
+- `name` — Skill display name
+- `skill_type` — `single` or `stack`
+- `source_authority` — `official`, `internal`, or `community`
+- `exports` — Array of exported functions/types
+- `generation_date` — When the skill was last generated
+- `confidence_tier` — Quick/Forge/Deep
+
+**For stack skills, also extract:**
+- `components` — Array of dependencies with versions
+- `integrations` — Array of co-import patterns
+
+### 4. Check Forge Configuration
+
+Load `{forge_data_folder}/forge-config.yaml` (if exists):
+- Check `passive_context` setting
+- If `passive_context: false` — note that steps 03-04 (snippet + context update) will be skipped
+
+### 5. Present Skill Summary
+
+"**Skill loaded and validated.**
+
+| Field | Value |
+|-------|-------|
+| **Name** | {name} |
+| **Type** | {skill_type} |
+| **Authority** | {source_authority} |
+| **Confidence** | {confidence_tier} |
+| **Exports** | {count} functions/types |
+| **Generated** | {generation_date} |
+| **References** | {count files or 'none'} |
+
+**Export Configuration:**
+| Setting | Value |
+|---------|-------|
+| **Platform** | {platform} → {target-file} |
+| **Dry Run** | {yes/no} |
+| **Passive Context** | {enabled/disabled} |
+
+**Top Exports:**
+{list top 5 exports from metadata}
+
+**Is this the correct skill to export?**"
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select:** [C] Continue to packaging"
+
+#### Menu Handling Logic:
+
+- IF C: Proceed with loaded skill data, then load, read entire file, then execute {nextStepFile}
+- IF Any other: help user respond, then [Redisplay Menu Options](#6-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 the user confirms the correct skill is loaded by selecting 'C' will you load and read fully `{nextStepFile}` to execute packaging.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Skill path resolved (from argument or discovery)
+- All required files loaded and validated
+- metadata.json parsed with required fields
+- Export flags parsed (platform, dry-run)
+- Forge config checked for passive_context
+- Clear summary presented to user
+- User confirms correct skill
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without finding SKILL.md or metadata.json
+- Not validating metadata.json fields
+- Not checking forge-config for passive_context opt-out
+- Proceeding without user confirmation
+- Modifying any skill files (read-only step)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/export-skill/steps-c/step-02-package.md

@@ -0,0 +1,153 @@
+---
+name: 'step-02-package'
+description: 'Build agentskills.io-compliant package structure from skill artifacts'
+
+nextStepFile: './step-03-generate-snippet.md'
+---
+
+# Step 2: Package
+
+## STEP GOAL:
+
+To assemble and validate an agentskills.io-compliant package structure from the loaded skill artifacts, ensuring all required components are present and properly formatted for distribution.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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 delivery and packaging specialist in Ferris Delivery mode
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Precise validation — ensure package meets ecosystem standards
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on package structure assembly and validation
+- 🚫 FORBIDDEN to modify SKILL.md content — package what exists
+- 💬 This is a deterministic packaging step — auto-proceed when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Hold validated package structure in context for subsequent steps
+- 📖 Validate all required agentskills.io fields
+- 🚫 Warn on non-critical issues but do not halt
+
+## CONTEXT BOUNDARIES:
+
+- Available: Skill metadata, SKILL.md, metadata.json from step-01
+- Focus: Package structure validation and assembly
+- Limits: Do not modify source files — validate and assemble only
+- Dependencies: Step-01 must have loaded and validated the skill
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Validate Package Structure
+
+Verify the skill directory contains the expected agentskills.io package layout:
+
+```
+{skills_output_folder}/{skill-name}/
+├── SKILL.md              ← Required: Active skill document
+├── metadata.json         ← Required: Machine-readable metadata
+├── context-snippet.md    ← Will be generated/updated in step-03
+└── references/           ← Optional: Progressive disclosure
+    ├── {function-a}.md
+    └── {function-b}.md
+```
+
+**Check each component:**
+1. `SKILL.md` — Verify has frontmatter with `name` field
+2. `metadata.json` — Verify required agentskills.io fields:
+   - `name` (string, non-empty)
+   - `version` (string, semver format preferred)
+   - `skill_type` ("single" or "stack")
+   - `source_authority` ("official", "internal", or "community")
+   - `exports` (array)
+   - `generation_date` (ISO date string)
+   - `confidence_tier` ("Quick", "Forge", or "Deep")
+3. `references/` — If exists, check at least one .md file present
+
+### 2. Validate Metadata Completeness
+
+Check metadata.json for recommended (non-required) fields:
+
+- `description` — Brief skill description
+- `source_repo` — Source repository URL
+- `language` — Primary language of source code
+- `ast_node_count` — Number of AST nodes analyzed
+- `tool_versions` — Tools used during generation
+
+**For each missing recommended field:** Note as warning, do not halt.
+
+### 3. Assess Package Readiness
+
+Determine package status:
+
+**READY:** All required files present, all required metadata fields valid
+**WARNINGS:** Ready but with missing recommended fields or empty references/
+**NOT READY:** Missing required files or required metadata fields (should not reach here — step-01 would have halted)
+
+### 4. Report Package Status
+
+"**Package structure validated.**
+
+**Status:** {READY / WARNINGS}
+
+**Required Components:**
+- SKILL.md: ✅
+- metadata.json: ✅ ({count} required fields valid)
+- references/: {✅ present ({count} files) / ⚠️ not present}
+
+{If warnings:}
+**Warnings:**
+- {list missing recommended fields}
+
+**Package is ready for snippet generation.**"
+
+### 5. Proceed to Snippet Generation
+
+Display: "**Proceeding to snippet generation...**"
+
+#### Menu Handling Logic:
+
+- After package validation completes, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to next step after validation
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN package validation is complete will you load and read fully `{nextStepFile}` to execute snippet generation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All required package components validated
+- All required metadata.json fields checked
+- Warnings noted for missing recommended fields
+- Package status clearly reported
+- Auto-proceed to step-03
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking all required files
+- Not validating metadata.json fields
+- Halting on non-critical warnings (should warn and continue)
+- Modifying any source files
+- Not auto-proceeding after validation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/export-skill/steps-c/step-03-generate-snippet.md

@@ -0,0 +1,166 @@
+---
+name: 'step-03-generate-snippet'
+description: 'Generate context-snippet.md in compressed two-line format per ADR-L'
+
+nextStepFile: './step-04-update-context.md'
+snippetFormatData: '../data/snippet-format.md'
+---
+
+# Step 3: Generate Snippet
+
+## STEP GOAL:
+
+To generate or update context-snippet.md for the skill in the compressed two-line format defined by ADR-L, targeting ~30 tokens per skill with T1-now content only.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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 delivery and packaging specialist in Ferris Delivery mode
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Compress precisely — every token in a snippet must earn its place
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on generating the context-snippet.md content
+- 🚫 FORBIDDEN to include T2 annotations or temporal context — T1-now only
+- 💬 This is a deterministic generation step — auto-proceed when complete
+- 📋 If `passive_context: false` was detected in step-01, SKIP this step entirely and auto-proceed to step-04
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Write context-snippet.md to skill directory (or hold in context if dry-run)
+- 📖 Load {snippetFormatData} for format template
+- 🚫 Strict adherence to ADR-L format — no deviations
+
+## CONTEXT BOUNDARIES:
+
+- Available: Skill metadata (name, exports, skill_type, components, integrations) from step-01
+- Focus: Snippet generation in exact ADR-L format
+- Limits: T1-now content only, ~30 tokens target
+- Dependencies: Step-01 metadata, step-02 package validation
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Check Passive Context Setting
+
+**If `passive_context: false` was detected in step-01:**
+
+"**Passive context disabled in forge-config.yaml. Skipping snippet generation.**"
+
+Auto-proceed immediately to {nextStepFile}.
+
+**If `passive_context: true` (default):** Continue to step 2.
+
+### 2. Load Snippet Format
+
+Load {snippetFormatData} and read the format template for the skill type.
+
+### 3. Generate Snippet Content
+
+**For single skills (`skill_type: "single"`):**
+
+Select top 5 exports from metadata.json `exports` array (by order as listed — assumed most important first).
+
+Generate:
+```
+{skill-name} → skills/{skill-name}/
+  exports: {export-1}, {export-2}, {export-3}, {export-4}, {export-5}
+```
+
+**If fewer than 5 exports:** List all available.
+**If no exports:** Omit the exports line entirely:
+```
+{skill-name} → skills/{skill-name}/
+```
+
+**For stack skills (`skill_type: "stack"`):**
+
+Generate:
+```
+{project}-stack → skills/{project}-stack/
+  stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
+  integrations: {pattern-1}, {pattern-2}, {pattern-3}
+```
+
+### 4. Verify Token Count
+
+Estimate token count of generated snippet (approximate: words * 1.3).
+
+- Target: ~30 tokens per skill
+- Warning threshold: >50 tokens
+- If exceeding warning threshold, trim exports list or integration patterns to fit
+
+### 5. Write or Preview Snippet
+
+**If dry-run mode:**
+
+"**[DRY RUN] context-snippet.md would be written to:**
+`{skills_output_folder}/{skill-name}/context-snippet.md`
+
+**Content:**
+```
+{generated snippet content}
+```
+
+**Estimated tokens:** {count}"
+
+Hold content in context for step-04.
+
+**If NOT dry-run:**
+
+Write the generated content to `{skills_output_folder}/{skill-name}/context-snippet.md`.
+
+"**context-snippet.md written.**
+**Path:** `{skills_output_folder}/{skill-name}/context-snippet.md`
+**Estimated tokens:** {count}"
+
+### 6. Proceed to Context Update
+
+Display: "**Proceeding to context update...**"
+
+#### Menu Handling Logic:
+
+- After snippet generation completes, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to next step after generation
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-out) will you load and read fully `{nextStepFile}` to execute context update.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Snippet format loaded from {snippetFormatData}
+- Content generated matching exact ADR-L format
+- Token count estimated and within target
+- File written (or previewed in dry-run)
+- Passive context opt-out correctly handled (skip when disabled)
+- Auto-proceed to step-04
+
+### ❌ SYSTEM FAILURE:
+
+- Deviating from ADR-L two-line format
+- Including T2 annotations or temporal context
+- Not checking passive_context setting
+- Not estimating token count
+- Halting for user input (auto-proceed step)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.