bmad-module-skill-forge 0.2.0 → 0.3.0

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

@@ -64,10 +64,17 @@ Write the merged SKILL.md content to `{skills_output_folder}/{skill_name}/SKILL.
 ### 2. Write Updated metadata.json
 
 Update `{skills_output_folder}/{skill_name}/metadata.json`:
-- Update `version` (increment patch version)
-- Update `last_updated` timestamp to current date
-- Update `export_count` to reflect current total
-- Update `confidence_distribution` with new T1/T1-low/T2 counts
+- Update `version`: if a source version was detected during re-extraction and differs from the current metadata version, use the source version; otherwise increment patch version
+- Update `generation_date` timestamp to current ISO-8601 date
+- Update `exports` array to reflect current export list
+- Update `stats` from re-extraction results:
+  - `exports_documented`: count of exports with documentation in the merged skill
+  - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent)
+  - `exports_internal`: count of all other non-underscore-prefixed exports
+  - `exports_total`: `exports_public_api` + `exports_internal`
+  - `public_api_coverage`: `exports_documented / exports_public_api` (`null` if `exports_public_api` is 0)
+  - `total_coverage`: `exports_documented / exports_total` (`null` if `exports_total` is 0)
+  - `confidence_t1`, `confidence_t2`, `confidence_t3`: update counts from re-extraction results
 - For stack skills: update `library_count`, `integration_count` if changed
 
 ### 3. Write Updated provenance-map.json
@@ -75,26 +82,28 @@ Update `{skills_output_folder}/{skill_name}/metadata.json`:
 Write to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
 **For each export in the updated skill:**
-- Update `file_path` if moved
-- Update `start_line`, `end_line` from fresh extraction
-- Update `extraction_timestamp` to current date for re-extracted exports
-- Update `confidence_tier` from extraction results
-- Update `content_hash` for modified exports
+- Update `export_name` if renamed
+- Update `params[]` array if parameters changed (add, remove, or modify individual entries)
+- Update `return_type` if changed
+- Update `source_file` if moved
+- Update `source_line` from fresh extraction
+- Update `confidence` from extraction results
+- Update `extraction_method` and `ast_node_type` if re-extracted with different tools
 
 **For deleted exports:**
 - Remove entry from provenance map
 
 **For new exports:**
-- Add new entry with full extraction metadata
+- Add new entry with full structured fields: `export_name`, `export_type`, `params[]`, `return_type`, `source_file`, `source_line`, `confidence`, `extraction_method`, `ast_node_type`
 
 **Add update operation metadata:**
 ```json
 {
   "last_update": "{current_date}",
-  "update_type": "incremental",
+  "update_type": "{incremental if normal mode | full if degraded_mode}",
   "files_changed": {count},
   "exports_affected": {count},
-  "forge_tier": "{tier}",
+  "confidence_tier": "{tier}",
   "manual_sections_preserved": {count}
 }
 ```
@@ -162,13 +171,27 @@ For each file written:
 
 **All files written and verified.**"
 
-### 7. Present MENU OPTIONS
+### 7. Run Post-Write Validation (Deferred from Step 05)
+
+External tool checks deferred from step-05 now run against the written files:
+
+**If skill-check available:**
+- Run: `npx skill-check check {skills_output_folder}/{skill_name} --fix --format json --no-security-scan`
+- If `body.max_lines` reported, run: `npx skill-check split-body {skills_output_folder}/{skill_name} --write`
+- Run: `npx skill-check diff` if original version was preserved
+- Run: `npx skill-check check {skills_output_folder}/{skill_name} --format json` for security scan
+
+Record findings in the evidence report (section 4). These are advisory — do not block on warnings.
+
+**If skill-check unavailable:** Skip with note — structural checks from step-05 are sufficient.
+
+### 8. Present MENU OPTIONS
 
 Display: "**Proceeding to report...**"
 
 #### Menu Handling Logic:
 
-- After all writes verified, immediately load, read entire file, then execute {nextStepFile}
+- After all writes verified and post-write validation complete, immediately load, read entire file, then execute {nextStepFile}
 
 #### EXECUTION RULES:
 

package/src/workflows/update-skill/steps-c/step-07-report.md

@@ -76,7 +76,7 @@ Source code matches provenance map exactly. The skill `{skill_name}` is current
 
 | Metric | Value |
 |--------|-------|
-| **Skill** | {skill_name} ({individual/stack}) |
+| **Skill** | {skill_name} ({single/stack}) |
 | **Forge Tier** | {tier} |
 | **Mode** | {normal/degraded} |
 | **Duration** | {step count} steps |

package/src/workflows/update-skill/validation-report.md

@@ -192,7 +192,7 @@ Workflow is SKF module — correctly references `{project-root}/_bmad/skf/config
 
 ### Detailed Analysis
 
-**step-01-init:** Init with Input Discovery pattern. Requests skill path from user, validates required artifacts (SKILL.md, metadata.json, forge-tier.yaml), offers degraded mode for missing provenance, inventories [MANUAL] sections. C-only gate (no A/P — correct for init). Non-continuable (correct for single-session).
+**step-01-init:** Init with Input Discovery pattern. Requests skill path from user, validates required artifacts (SKILL.md, metadata.json, forge-tier.yaml), checks `preferences.yaml` for `tier_override`, offers degraded mode for missing provenance, inventories [MANUAL] sections. C-only gate (no A/P — correct for init). Non-continuable (correct for single-session).
 
 **step-02-detect-changes:** Auto-proceed middle step with Pattern 4 parallel subprocess. No-change shortcut correctly routes to final step. No user interaction.
 
@@ -237,7 +237,7 @@ YES — This workflow modifies code-derived artifacts with provenance tracking.
 
 | Criterion | Status |
 |-----------|--------|
-| Loads validation data/standards (skills_ref) | ✅ |
+| Loads validation data/standards (skill-check) | ✅ |
 | Systematic check sequence (4 parallel checks) | ✅ |
 | Auto-proceeds through checks | ✅ |
 | Clear pass/fail criteria (PASS/WARN/FAIL per check) | ✅ |
@@ -246,7 +246,7 @@ YES — This workflow modifies code-derived artifacts with provenance tracking.
 
 ### 4 Validation Checks Assessed
 
-1. **Spec Compliance** — validates against agentskills.io via skills_ref ✅
+1. **Spec Compliance** — validates against agentskills.io via skill-check ✅
 2. **[MANUAL] Section Integrity** — byte-level comparison against step-01 inventory ✅
 3. **Confidence Tier Consistency** — verifies tier labels match forge capabilities ✅
 4. **Provenance Completeness** — verifies export-to-source mapping integrity ✅
@@ -495,7 +495,7 @@ None. The workflow is well-designed and should function correctly in its current
 | ast_bridge | External | Referenced in step-03 | ✅ |
 | gh_bridge | External | Implied in source file access | ✅ |
 | qmd_bridge | External | Referenced in step-03 (Deep tier) | ✅ |
-| skills_ref | External | Referenced in step-05 | ✅ |
+| skill-check | External | Referenced in step-05 | ✅ |
 | manual-section-rules.md | Data file | Created | ✅ |
 | merge-conflict-rules.md | Data file | Created | ✅ |
 

package/src/workflows/update-skill/workflow-plan-update-skill.md

@@ -213,7 +213,7 @@ Document-producing workflow that outputs:
 - **ast_bridge:** required for Forge/Deep tier AST extraction (pre-detected by setup-forge)
 - **gh_bridge:** required for all tiers to read source files
 - **qmd_bridge:** required for Deep tier semantic enrichment only
-- **skills_ref:** required for validation against agentskills.io spec (Step 05)
+- **skill-check:** required for validation against agentskills.io spec (Step 05) — `npx skill-check check --fix --format json` for validation + auto-fix + quality scoring, `diff` for before/after comparison, security scan for prompt injection detection, `split-body` for oversized body remediation
 
 **Installation Requirements:**
 - None — all tools pre-detected by setup-forge workflow
@@ -264,8 +264,8 @@ Step 04 (merge)
   OUT: merged SKILL.md content with [MANUAL] sections preserved
 
 Step 05 (validate)
-  IN:  merged content, agentskills.io spec (via skills_ref)
-  OUT: validation results (pass/fail with details)
+  IN:  merged content, agentskills.io spec (via `npx skill-check check --fix --format json`)
+  OUT: validation results (pass/fail with quality score, diff comparison, security findings)
 
 Step 06 (write)
   IN:  validated merged content, updated provenance data
@@ -416,7 +416,7 @@ Fallback: All operations executable in main thread if subprocesses unavailable.
 ### Step 05: validate (~190 lines)
 - Type: Validation Sequence, Auto-proceed (advisory, non-blocking)
 - Pattern 4 parallel validation across 4 checks:
-  - Check A: Spec compliance (agentskills.io via skills_ref)
+  - Check A: Spec compliance (agentskills.io via skill-check)
   - Check B: [MANUAL] section integrity (byte-level comparison)
   - Check C: Confidence tier consistency (tier vs forge capabilities)
   - Check D: Provenance completeness (export-to-source mapping)

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

@@ -49,7 +49,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/update-skill'
 Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
 
 - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
-- `skills_output_folder`, `forge_data_folder`
+- `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
 ### 2. First Step Execution
 

package/tools/cli/commands/status.js

@@ -99,13 +99,13 @@ async function getStatus(projectDir) {
 
 function displayStatus(status, version) {
   console.log('');
-  console.log(chalk.cyan.bold('  Skill Forge — Status'));
+  console.log(chalk.hex('#F59E0B').bold('  Skill Forge — Status'));
   console.log(chalk.dim(`  v${version}`));
   console.log('');
 
   if (!status.installed) {
     console.log(chalk.yellow('  Not installed.'));
-    console.log(chalk.dim('  Run: npx skill-forge install'));
+    console.log(chalk.dim('  Run: npx bmad-module-skill-forge install'));
     console.log('');
     return;
   }
@@ -115,7 +115,7 @@ function displayStatus(status, version) {
   // Installation
   const manifest = status.manifest;
   console.log(chalk.white.bold('  Installation'));
-  console.log(`    Project:      ${chalk.cyan(config.project_name || '(unknown)')}`);
+  console.log(`    Project:      ${chalk.hex('#FBBF24')(config.project_name || '(unknown)')}`);
   console.log(`    SKF folder:   ${chalk.dim(SKF_FOLDER + '/')}`);
   console.log(`    Agent:        ${status.agentCompiled ? chalk.green('compiled') : chalk.yellow('not compiled')}`);
   console.log(`    Workflows:    ${chalk.white(status.workflowCount)}`);
@@ -146,7 +146,7 @@ function displayStatus(status, version) {
   const tools = ft.tools || {};
   console.log(chalk.white.bold('  Forge Tier'));
   if (status.tierDetected) {
-    const tierColors = { Quick: chalk.yellow, Forge: chalk.cyan, Deep: chalk.magenta };
+    const tierColors = { Quick: chalk.yellow, Forge: chalk.hex('#F59E0B'), Deep: chalk.hex('#FCD34D') };
     const tierColor = tierColors[ft.tier] || chalk.white;
     console.log(`    Tier:         ${tierColor(ft.tier)}`);
     console.log(`    Detected:     ${chalk.dim(ft.tier_detected_at || '(unknown)')}`);

package/tools/cli/commands/uninstall.js

@@ -113,7 +113,7 @@ module.exports = {
         const skfExists = await fs.pathExists(path.join(projectDir, '_bmad/skf'));
         if (skfExists) {
           log.warn(
-            'No manifest found. Reinstall first to generate one,\nthen run uninstall again for clean removal.\nRun: npx skill-forge install',
+            'No manifest found. Reinstall first to generate one,\nthen run uninstall again for clean removal.\nRun: npx bmad-module-skill-forge install',
           );
         } else {
           log.warn('SKF is not installed in this directory.');

package/tools/cli/commands/update.js

@@ -24,13 +24,13 @@ module.exports = {
 
       if (!(await fs.pathExists(skfDir))) {
         console.log(chalk.yellow('\n  SKF is not installed in this directory.'));
-        console.log(chalk.dim('  Run: npx skill-forge install\n'));
+        console.log(chalk.dim('  Run: npx bmad-module-skill-forge install\n'));
         process.exit(0);
         return;
       }
 
       console.log('');
-      console.log(chalk.cyan.bold('  Skill Forge — Quick Update'));
+      console.log(chalk.hex('#F59E0B').bold('  Skill Forge — Quick Update'));
       console.log(chalk.dim('  Replacing SKF files, preserving config and sidecar.\n'));
 
       const installer = new Installer();

package/tools/cli/lib/ui.js

@@ -1,6 +1,12 @@
 /**
  * SKF Installer UI - Banner, prompts, and success message.
  * Uses @clack/prompts for terminal UI.
+ *
+ * Brand palette (from skf-logo.svg):
+ *   amber  #F59E0B  — primary (anvil top)
+ *   gold   #FBBF24  — accent, highlights (anvil horn)
+ *   dark   #D97706  — frame, deep emphasis (anvil body)
+ *   spark  #FCD34D  — sparks, icons
  */
 
 const { intro, outro, text, select, multiselect, confirm, note, isCancel, cancel, log } = require('@clack/prompts');
@@ -12,18 +18,54 @@ const yaml = require('js-yaml');
 
 const SKF_FOLDER = '_bmad/skf';
 
+// Brand colors derived from skf-logo.svg
+const brand = {
+  amber: chalk.hex('#F59E0B'),
+  gold: chalk.hex('#FBBF24'),
+  dark: chalk.hex('#D97706'),
+  spark: chalk.hex('#FCD34D'),
+};
+
 class UI {
   displayBanner() {
-    let banner;
+    const packageJson = require('../../../package.json');
+    const version = packageJson.version;
+
+    let logoLines;
     try {
-      banner = figlet.textSync('SKF', { font: 'Standard' });
+      logoLines = figlet.textSync('SKF', { font: 'ANSI Shadow' }).trimEnd().split('\n');
+      // Remove trailing empty lines from figlet output
+      while (logoLines.length > 0 && !logoLines.at(-1).trim()) logoLines.pop();
     } catch {
-      banner = '\n  S K F';
+      logoLines = ['  S K F'];
     }
-    const packageJson = require('../../../package.json');
-    intro(
-      `${chalk.cyan(banner)}\n${chalk.white.bold('  Skill Forge')} ${chalk.dim(`v${packageJson.version}`)}\n${chalk.dim('  AST-verified, provenance-backed agent skills from code\n  repositories, documentation, and developer discourse')}`,
-    );
+
+    const w = 54;
+    const frame = brand.dark;
+    const top = frame('  ╔' + '═'.repeat(w) + '╗');
+    const mid = frame('  ╟' + '─'.repeat(w) + '╢');
+    const bottom = frame('  ╚' + '═'.repeat(w) + '╝');
+    const row = (content) => {
+      // eslint-disable-next-line no-control-regex -- stripping ANSI escape codes for visual width calculation
+      const stripped = content.replaceAll(/\u001B\[\d+(?:;\d+)*m/g, '');
+      const pad = Math.max(0, w - stripped.length - 2);
+      return frame('  ║ ') + content + ' '.repeat(pad) + frame(' ║');
+    };
+
+    console.log();
+    console.log(top);
+    for (const line of logoLines) {
+      console.log(row(brand.amber.bold(line.replace(/\s+$/, ''))));
+    }
+    console.log(mid);
+    console.log(row(chalk.white.bold('Skill Forge') + chalk.dim(` v${version}`)));
+    console.log(row(chalk.dim('Agent Skill Compiler') + ' '.repeat(15) + brand.spark('⚒')));
+    console.log(mid);
+    console.log(row(chalk.dim('AST-verified · version-pinned · zero hallucination')));
+    console.log(bottom);
+    console.log();
+
+    intro(brand.amber('Skill Forge Installer'));
   }
 
   async detectInstallation(projectDir) {
@@ -47,7 +89,7 @@ class UI {
     const detection = await this.detectInstallation(projectDir);
     const skfFolder = detection.folder;
 
-    log.info(`Target: ${chalk.cyan(projectDir)}`);
+    log.info(`Target: ${brand.gold(projectDir)}`);
 
     let action = 'fresh';
 
@@ -109,7 +151,7 @@ class UI {
       const detectedIdes = await this.detectIdes(projectDir);
       if (detectedIdes.length > 0) {
         initialIdes = detectedIdes;
-        log.info(`Auto-detected IDEs: ${detectedIdes.join(', ')}`);
+        log.info(`Auto-detected IDEs: ${brand.gold(detectedIdes.join(', '))}`);
       }
     }
 
@@ -244,25 +286,25 @@ class UI {
     let noteTitle;
     let noteBody;
 
+    const activateCmd = brand.gold('/bmad-agent-skf-forger');
+
     if (action === 'update') {
-      noteTitle = 'Update complete!';
+      noteTitle = brand.amber.bold('Update complete!');
       noteBody = [
         `${chalk.white.bold('What Changed')}`,
         'SKF files and agents have been refreshed.',
         'Your config.yaml and sidecar state are preserved.',
         '',
         `${chalk.white.bold('Next Steps')}`,
-        `1. Reload the agent in ${ideDisplay}:`,
-        `   ${chalk.cyan(`"Read and activate ${skfFolder}/agents/forger.md"`)}`,
+        `1. Reload the agent in ${ideDisplay}:  ${activateCmd}`,
         '2. Run @Ferris SF to re-detect tools if needed',
       ].join('\n');
     } else {
-      noteTitle = 'Installation complete!';
+      noteTitle = brand.amber.bold('Installation complete!');
       noteBody = [
         `${chalk.white.bold('Get Started')}`,
         `1. Open this folder in ${ideDisplay}`,
-        '2. Locate the chat window and type:',
-        `   ${chalk.cyan(`"Read and activate ${skfFolder}/agents/forger.md"`)}`,
+        `2. Activate Ferris:  ${activateCmd}`,
         '3. Ferris (your Skill Architect) will guide you through',
         '   setting up and forging your first agent skill',
       ].join('\n');
@@ -270,7 +312,9 @@ class UI {
 
     note(noteBody, noteTitle);
 
-    outro(`Agent: Ferris (Skill Architect & Integrity Guardian)\nDocs: https://github.com/armelhbobdad/bmad-module-skill-forge`);
+    outro(
+      `${brand.spark('⚒')}  Agent: ${chalk.white('Ferris')} ${chalk.dim('(Skill Architect & Integrity Guardian)')}\n${brand.dark('⚡')} Docs: ${brand.amber('https://armelhbobdad.github.io/bmad-module-skill-forge')}`,
+    );
   }
 }
 

package/tools/cli/lib/version-check.js

@@ -64,9 +64,9 @@ function startVersionCheck(currentVersion) {
     }
     return (
       '\n' +
-      chalk.yellow(`  Update available: ${chalk.dim(currentVersion)} → ${chalk.green(latestVersion)}`) +
+      chalk.hex('#F59E0B')(`  Update available: ${chalk.dim(currentVersion)} → ${chalk.hex('#FBBF24').bold(latestVersion)}`) +
       '\n' +
-      chalk.dim(`  Run: npx skill-forge@latest install`) +
+      chalk.dim(`  Run: npx bmad-module-skill-forge@latest install`) +
       '\n'
     );
   });