bmad-module-skill-forge 0.2.0

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

@@ -0,0 +1,222 @@
+---
+name: 'step-04-update-context'
+description: 'Update managed section in CLAUDE.md/AGENTS.md with three-case logic per ADR-J'
+
+nextStepFile: './step-05-token-report.md'
+managedSectionData: '../data/managed-section-format.md'
+---
+
+# Step 4: Update Context
+
+## 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.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER modify content outside `<!-- SKF:BEGIN/END -->` markers
+- 📖 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
+- ✅ Surgical precision required — existing file content MUST be preserved
+- ✅ User confirms changes before any writes to shared context files
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on the managed section update in the target context file
+- 🚫 FORBIDDEN to modify ANY content outside `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` markers
+- 🚫 FORBIDDEN to write without user confirmation — this modifies shared project files
+- 💬 Show a clear diff preview before writing
+- 📋 If `passive_context: false` was detected in step-01, SKIP this step entirely and auto-proceed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Load {managedSectionData} for format template and three-case logic
+- 📖 Rebuild the COMPLETE skill index — not just the current skill
+- 🚫 ZERO data loss — verify preserved content before and after write
+
+## CONTEXT BOUNDARIES:
+
+- Available: Skill metadata from step-01, context-snippet.md from step-03, platform flag
+- Focus: Three-case detection and managed section update
+- Limits: Only modify content between markers — preserve everything else
+- Dependencies: Step-03 must have generated the snippet (or step skipped if passive_context off)
+
+## 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 context update.**"
+
+Auto-proceed immediately to {nextStepFile}.
+
+**If `passive_context: true` (default):** Continue to step 2.
+
+### 2. Load Managed Section Format
+
+Load {managedSectionData} and read the complete format template and three-case logic.
+
+### 3. Determine Target File
+
+Based on the `--platform` flag parsed in step-01:
+
+| Platform | Target File |
+|----------|-------------|
+| `claude` (default) | CLAUDE.md |
+| `cursor` | .cursorrules |
+| `copilot` | AGENTS.md |
+
+Resolve target file path at project root: `{project-root}/{target-file}`
+
+### 4. Rebuild Complete Skill Index
+
+Scan `{skills_output_folder}/*/context-snippet.md` to find ALL exported skills (not just the current one).
+
+**If no context-snippet.md files are found:** Generate managed section with zero skills — header only, no skill entries.
+
+For each found context-snippet.md:
+1. Read snippet content
+2. Add to skill index
+
+**Sort skills alphabetically by name.**
+
+Count totals:
+- Total skills (single type)
+- Total stack skills
+
+### 5. Generate Managed Section
+
+Assemble the complete managed section:
+
+```markdown
+<!-- SKF:BEGIN updated:{current-date} -->
+[SKF Skills]|{n} skills|{m} stack
+|IMPORTANT: Prefer documented APIs over training data.
+|
+|{skill-snippet-1}
+|
+|{skill-snippet-2}
+|
+|{skill-snippet-N}
+<!-- SKF:END -->
+```
+
+### 6. Detect Case and Prepare Changes
+
+**Check target file at `{project-root}/{target-file}`:**
+
+**Case 1: Create (file does not exist)**
+- Action: Create new file with managed section only
+- Diff: Show entire managed section as new content
+
+**Case 2: Append (file exists, no `<!-- SKF:BEGIN` marker found)**
+- Action: Read existing content, append managed section at end
+- Diff: Show managed section being appended after existing content
+- Preserved: ALL existing content untouched
+
+**Case 3: Regenerate (file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->`)**
+- Action: Replace everything between markers (inclusive) with new managed section
+- Diff: Show old managed section vs new managed section
+- Preserved: ALL content before `<!-- SKF:BEGIN` and after `<!-- SKF:END -->`
+
+### 7. Present Change Preview
+
+"**Context update prepared.**
+
+**Target:** `{project-root}/{target-file}`
+**Case:** {1: Create / 2: Append / 3: Regenerate}
+**Skills in index:** {n} skills, {m} stack
+
+**Changes:**
+
+{Show diff preview:}
+- For Case 1: Show full file content to be created
+- For Case 2: Show `...existing content preserved...\n\n{managed section}`
+- For Case 3: Show old section vs new section with surrounding context preserved
+
+**Content outside markers:** {preserved / n/a (new file)}
+
+**Ready to write changes?**"
+
+### 8. Present MENU OPTIONS
+
+**If dry-run mode:**
+
+"**[DRY RUN] No files will be written. Preview above shows what would change.**
+
+**Proceeding to token report...**"
+
+Auto-proceed to {nextStepFile}.
+
+**If NOT dry-run:**
+
+Display: "**Select:** [C] Continue — write changes to {target-file}"
+
+#### Menu Handling Logic:
+
+- IF C: Write the changes to target file, verify write succeeded, then 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'
+- In dry-run mode, auto-proceed without writing
+
+### 9. Write and Verify (Non-Dry-Run Only)
+
+After user confirms with 'C':
+
+1. Write the file using the appropriate case logic
+2. Re-read the written file
+3. Verify `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers are present
+4. Verify content outside markers is unchanged (for Cases 2 and 3)
+5. Report: "**{target-file} updated successfully.** Verified: markers present, external content preserved."
+
+**If verification fails:**
+"**WARNING: Write verification failed.** {describe issue}. File may need manual review."
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run) and the write is verified will you load and read fully `{nextStepFile}` to execute the token report.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Managed section format loaded from {managedSectionData}
+- Target file correctly determined from platform flag
+- Complete skill index rebuilt from all exported skills
+- Correct case detected (create/append/regenerate)
+- Clear diff preview shown to user
+- User confirmation received before writing
+- Write verified — markers present, external content preserved
+- Passive context opt-out correctly handled (skip when disabled)
+- Dry-run correctly handled (preview only, no writes)
+
+### ❌ SYSTEM FAILURE:
+
+- Modifying content outside `<!-- SKF:BEGIN/END -->` markers
+- Not rebuilding the COMPLETE skill index (only adding current skill)
+- Writing without user confirmation
+- Not verifying write after completion
+- Not detecting the correct case (create/append/regenerate)
+- Losing existing file content during write
+- Not skipping when passive_context is disabled
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. ZERO data loss in target files is NON-NEGOTIABLE.

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

@@ -0,0 +1,126 @@
+---
+name: 'step-05-token-report'
+description: 'Calculate and report token counts for all export artifacts'
+
+nextStepFile: './step-06-summary.md'
+---
+
+# Step 5: Token Report
+
+## STEP GOAL:
+
+To calculate approximate token counts for all exported artifacts and present a clear report showing the token cost of each component, helping users understand the context budget impact of their skills.
+
+## 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
+- ✅ Report clearly — token counts inform developers' context budget decisions
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on token counting and reporting
+- 🚫 FORBIDDEN to modify any files — read-only measurement
+- 💬 This is a deterministic reporting step — auto-proceed when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Hold token counts in context for the summary step
+- 📖 Use consistent estimation method across all files
+- 🚫 No file writes — measurement only
+
+## CONTEXT BOUNDARIES:
+
+- Available: All artifacts from steps 01-04 (SKILL.md, metadata.json, context-snippet.md, managed section content)
+- Focus: Token estimation and reporting
+- Limits: Estimates only — exact counts vary by tokenizer
+- Dependencies: Steps 01-04 must have completed (or been skipped where appropriate)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Calculate Token Counts
+
+For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers).
+
+**Artifacts to measure:**
+
+1. **context-snippet.md** — The compressed snippet (if generated)
+2. **Managed section** — The complete `<!-- SKF:BEGIN/END -->` block (all skills, not just this one)
+3. **SKILL.md** — The full active skill document
+4. **metadata.json** — The machine-readable metadata
+5. **references/** — Total across all reference files (if present)
+6. **Full package total** — Sum of all above
+
+**If passive_context was disabled:** Skip context-snippet.md and managed section measurements, note as "N/A (disabled)".
+
+### 2. Present Token Report
+
+"**Token Report**
+
+| Artifact | Words | Est. Tokens | Notes |
+|----------|-------|-------------|-------|
+| context-snippet.md | {n} | ~{t} | Passive context (always-on) |
+| Managed section (all skills) | {n} | ~{t} | In {target-file}, all {count} skills |
+| SKILL.md | {n} | ~{t} | Active skill (on-trigger) |
+| metadata.json | {n} | ~{t} | Machine-readable |
+| references/ | {n} | ~{t} | {count} files |
+| **Package total** | **{n}** | **~{t}** | **All artifacts combined** |
+
+**Context Budget Impact:**
+- **Always-on cost:** ~{managed-section-tokens} tokens (managed section in {target-file})
+- **On-trigger cost:** ~{skill-tokens} tokens (when SKILL.md is loaded)
+- **Full disclosure cost:** ~{total-tokens} tokens (if references/ also loaded)
+
+**Benchmark:** Target is ~30 tokens per skill in managed section. Current: ~{snippet-tokens} tokens."
+
+### 3. Proceed to Summary
+
+Display: "**Proceeding to export summary...**"
+
+#### Menu Handling Logic:
+
+- After token report is displayed, 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 reporting
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the token report is displayed will you load and read fully `{nextStepFile}` to execute the export summary.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All artifacts measured with consistent heuristic
+- Clear table format with words and estimated tokens
+- Context budget impact explained (always-on vs on-trigger vs full)
+- Benchmark comparison for managed section target
+- Passive context opt-out correctly handled (skip snippet/section measurements)
+- Auto-proceed to step-06
+
+### ❌ SYSTEM FAILURE:
+
+- Not measuring all artifacts
+- Inconsistent estimation method
+- Not explaining context budget impact
+- Modifying any files (read-only step)
+- Not auto-proceeding after report
+
+**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-06-summary.md

@@ -0,0 +1,167 @@
+---
+name: 'step-06-summary'
+description: 'Display export summary with distribution instructions'
+---
+
+# Step 6: Summary
+
+## STEP GOAL:
+
+To present a complete export summary showing all files written, token counts, and provide distribution instructions based on the skill's source authority. This is the final step — workflow ends here.
+
+## 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 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
+- ✅ Clear and complete — the user should know exactly what happened and what to do next
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on summarizing what was done and providing next steps
+- 🚫 FORBIDDEN to write any additional files — summary is console-only
+- 💬 This is the final step — end with clear completion signal
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 📖 Compile results from all previous steps
+- 🚫 No file writes — console output only
+- ✅ End workflow gracefully
+
+## CONTEXT BOUNDARIES:
+
+- Available: All data from steps 01-05 (metadata, package status, snippet, context update, token counts)
+- Focus: Summary compilation and distribution instructions
+- Limits: No new operations — reporting only
+- Dependencies: All previous steps
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Compile Export Summary
+
+"**Export Complete{if dry-run: ' (Dry Run)'}**
+
+---
+
+**Skill:** {skill-name}
+**Type:** {skill_type} | **Authority:** {source_authority} | **Tier:** {confidence_tier}
+**Platform:** {platform} → {target-file}
+
+---
+
+### Files {if dry-run: 'Previewed' else: 'Written'}
+
+| File | Status | Tokens |
+|------|--------|--------|
+| context-snippet.md | {✅ written / ⚠️ skipped (passive off) / 👁️ previewed} | ~{t} |
+| {target-file} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
+| Package structure | ✅ validated | ~{t} total |
+
+**Total context cost:** ~{always-on-tokens} tokens always-on, ~{on-trigger-tokens} tokens on-trigger"
+
+### 2. Distribution Instructions
+
+**Based on `source_authority` from metadata:**
+
+**If `official`:**
+
+"### Distribution: Official Ecosystem
+
+Your skill is ready for the agentskills.io ecosystem.
+
+**Publish:**
+```
+npx skills publish {skill-name}
+```
+
+**Others can install with:**
+```
+npx skills add {skill-name}
+```
+
+**Before publishing, ensure:**
+- Source repo URL is correct in metadata.json
+- You have publish access to the agentskills.io registry
+- SKILL.md has been reviewed for accuracy"
+
+**If `internal`:**
+
+"### Distribution: Internal
+
+Your skill is committed to the project's `skills/` directory and ships with your code.
+
+**Team members** will automatically have access when they pull the latest changes.
+
+**To update team context:** Ensure {target-file} is committed with the managed section update."
+
+**If `community`:**
+
+"### Distribution: Community (Local)
+
+Your skill is generated from an external dependency for local use.
+
+**Location:** `{skills_output_folder}/{skill-name}/`
+**Scope:** This project only — not for publishing to agentskills.io
+
+**Note:** Community skills are generated from third-party source code. Only `official` skills (generated by the library maintainer) should be published to the ecosystem."
+
+### 3. Dry Run Reminder (If Applicable)
+
+**If dry-run mode was active:**
+
+"### Dry Run Complete
+
+No files were written. To run the export for real:
+
+**Re-run without `--dry-run`** to write all files."
+
+### 4. Recommended Next Steps
+
+"### Next Steps
+
+- **audit-skill** — Run periodic integrity checks to detect drift between skill and source
+- **update-skill** — After refactoring source code, regenerate the skill
+- **test-skill** — Verify skill completeness and accuracy"
+
+### 5. Workflow Complete
+
+"---
+
+**Skill forged and delivered.** ⚒️"
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final step. The workflow is complete. No further steps to load.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete summary with all files and their status
+- Token counts included from step-05
+- Distribution instructions appropriate for source_authority
+- Dry-run correctly indicated (if applicable)
+- Recommended next workflows listed
+- Clear workflow completion signal
+
+### ❌ SYSTEM FAILURE:
+
+- Missing files from summary
+- Wrong distribution instructions for source_authority
+- Not indicating dry-run status
+- Writing additional files (console-only step)
+- Not ending the workflow cleanly
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.