bmad-module-skill-forge 0.6.0 → 0.7.0

package/src/workflows/refine-architecture/steps-c/step-05-compile.md

@@ -0,0 +1,200 @@
+---
+name: 'step-05-compile'
+description: 'Produce the refined architecture document by annotating the original with gaps, issues, and improvements'
+
+nextStepFile: './step-06-report.md'
+outputFile: '{output_folder}/refined-architecture-{project_name}.md'
+---
+
+# Step 5: Compile Refined Architecture
+
+## STEP GOAL:
+
+Produce the refined architecture document by starting with the original as a base, adding gap-fill subsections, issue callout blocks, and improvement suggestions. Append a Refinement Summary. Present for user review before finalizing.
+
+## 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 an architecture refinement analyst compiling the final refined document
+- ✅ Additive, not destructive — preserve every word of the original, only add refinements
+- ✅ The document must be in `{document_output_language}`
+
+### Step-Specific Rules:
+
+- 🚫 FORBIDDEN to discover new gaps, issues, or improvements — use only what Steps 02-04 produced
+- 🚫 FORBIDDEN to delete, reword, or rearrange original architecture content
+- 💬 Present compiled document for user review (Gate checkpoint)
+
+## EXECUTION PROTOCOLS:
+
+- Compile refined architecture from original + findings from Steps 02-04
+- Write output to {outputFile}, wait for user approval before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- From Steps 01-04: Architecture document, skill inventory, gap/issue/improvement findings
+- This step produces: The refined architecture document at {outputFile}
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Prepare the Original as Base
+
+Load the complete original architecture document.
+
+This is the base. Every line of the original MUST appear in the refined document, unmodified.
+
+**Context recovery check:** If gap, issue, or improvement findings from Steps 02-04 are not available in context (e.g., due to context degradation in long runs), attempt to read the durability state from `{forge_data_folder}/ra-state-{project_name}.md`. Parse the `<!-- [RA-GAPS] -->`, `<!-- [RA-ISSUES] -->`, and `<!-- [RA-IMPROVEMENTS] -->` comment blocks to recover the complete formatted findings (each block contains full citation text with evidence, not just counts). If a section is still missing or contains only summary counts after recovery, HALT: "⚠️ Context for the [Gaps|Issues|Improvements] analysis was lost and the durability state is insufficient to reconstruct findings. Re-run [RA] from the beginning — step 01 will reset the state file, then steps 02-04 will rebuild all findings."
+
+### 2. Insert Gap-Fill Subsections
+
+For each gap finding from Step 02:
+
+**Locate the most relevant section** in the original architecture where this integration would logically belong.
+
+**Insert a gap-fill subsection** one heading level deeper than the parent section:
+
+```markdown
+#### RA: {Library A} <-> {Library B} Integration Path
+
+> [!NOTE] **Gap Identified by Refine Architecture**
+> This integration path was not documented in the original architecture but is supported by skill API evidence.
+
+{Gap description with full evidence citation from Step 02}
+
+**Proposed Integration:**
+{Suggested architecture content describing how the libraries connect}
+```
+
+If no clear parent section exists, collect orphan gaps into a new section: "## RA: Additional Integration Paths"
+
+### 3. Insert Issue Annotations
+
+For each issue finding from Step 03:
+
+**Locate the section** containing the contradicted claim.
+
+**Insert an issue callout block** immediately after the contradicted text:
+
+```markdown
+> [!WARNING] **Issue Detected by Refine Architecture** ({severity})
+> Architecture states: "{quoted claim}"
+> Skill reality: {contradicting evidence from skill}
+> {IF VS report}: VS verdict: {verdict} for {pair}
+>
+> **Suggested Correction:** {specific correction with API evidence}
+```
+
+**Placement priority:** Place each issue callout immediately after the contradicted text in its original location. If the contradicted claim is inside a Markdown list item, code block, or table row where inserting a callout block would break syntax, place the callout immediately after the enclosing block instead. If the contradicted claim cannot be precisely located, collect into "## RA: Additional Issues Detected" at the end of the document, ordered by severity (Critical first, then Major, then Minor).
+
+### 4. Insert Improvement Suggestions
+
+For each improvement finding from Step 04:
+
+**Locate the section** where the library is discussed.
+
+**Insert an improvement subsection** one heading level deeper:
+
+```markdown
+#### RA: Enhancement — {Improvement Title}
+
+> [!TIP] **Improvement Suggested by Refine Architecture** ({value} value)
+> {skill_name} provides `{api}` which is not currently leveraged.
+
+{Full improvement description with evidence citation from Step 04}
+
+**How to Incorporate:**
+{Specific suggestion for updating the architecture}
+```
+
+**Order by value:** High value improvements first, then Medium, then Low.
+
+**Placement fallback:** If the library's only architecture mention is inside a table, code block, or Mermaid diagram where inserting a subsection would break syntax, collect into `## RA: Additional Improvements Suggested` at the end of the document.
+
+### 5. Add Refinement Summary Section
+
+Append a `## Refinement Summary` section containing:
+
+- **Header:** "Produced by: Refine Architecture workflow using {skill_count} skills" and date
+- **Changes Made table** with the following rows:
+
+| Category | Count | Breakdown |
+|----------|-------|-----------|
+| Gaps Filled | {gap_count} | — |
+| Issues Flagged | {issue_count} | Critical: {critical_count}, Major: {major_count}, Minor: {minor_count} |
+| Improvements Suggested | {improvement_count} | High: {high_count}, Medium: {medium_count}, Low: {low_count} |
+| Skills Used as Evidence | {skill_count} | — |
+- **Evidence Sources table:** Each skill name and how many refinements cite it
+- **Next Steps:** Review `[!WARNING]` issues, `[!NOTE]` gaps, `[!TIP]` improvements; then run **[SS] Stack Skill** to compose your individual skills into a unified stack skill, providing this refined architecture doc when prompted
+
+### 6. Write the Refined Document
+
+Write the complete refined architecture to `{outputFile}`.
+
+### 7. Present Compiled Document for Review
+
+"**Refined architecture compiled. Please review:**
+
+---
+
+{Display the Refinement Summary section only — not the full document}
+
+---
+
+**The full refined document has been written to:** `{outputFile}`
+
+Please review the refinements:
+- {gap_count} gap-fill subsections added
+- {issue_count} issue annotations inserted
+- {improvement_count} improvement suggestions included
+- Original architecture content preserved in full
+
+**Does the refinement look correct?**"
+
+### 8. Present MENU OPTIONS
+
+Display: **Select:** [C] Continue to Final Report
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting compilation
+- ONLY proceed to next step when user approves and selects 'C'
+
+#### Menu Handling Logic:
+
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF Any other: Process as feedback, adjust specific refinements in the document, rewrite {outputFile}, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Original architecture document preserved in full without modifications
+- Gap-fill subsections inserted at logical locations with evidence citations
+- Issue callout blocks inserted adjacent to contradicted claims with severity
+- Improvement suggestions inserted with value ratings and evidence
+- Refinement Summary section appended with accurate counts
+- Refined document written to {outputFile}
+- User reviewed and approved compilation
+- Proceeded to step 06 only after user selected C
+
+### ❌ SYSTEM FAILURE:
+
+- Deleting, rewording, or rearranging original architecture content
+- Discovering new findings not from Steps 02-04
+- Inserting refinements without evidence citations
+- Proceeding without user review (Gate checkpoint)
+- Not writing the document to {outputFile} before presenting for review
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Additive only. Preserve the original. Get user approval before proceeding.

package/src/workflows/refine-architecture/steps-c/step-06-report.md

@@ -0,0 +1,147 @@
+---
+name: 'step-06-report'
+description: 'Present refinement summary to user with counts, next steps, and review options'
+
+outputFile: '{output_folder}/refined-architecture-{project_name}.md'
+---
+
+# Step 6: Present Report
+
+## STEP GOAL:
+
+Present the complete refinement summary to the user. Display counts of gaps filled, issues flagged, and improvements suggested. Provide the output file path and recommend next steps. Offer the user options to review changes in detail or exit. This is the FINAL step — no nextStepFile.
+
+## 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 an architecture refinement analyst delivering the final summary
+- ✅ Present findings clearly and concisely — the user needs to decide which refinements to keep
+- ✅ Next step recommendations must be specific and actionable
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on presenting the completed refinement — no new analysis
+- 🚫 FORBIDDEN to discover new gaps, issues, or improvements
+- 🚫 FORBIDDEN to modify the refined document — only read and present
+- 📋 This is the FINAL step — no nextStepFile
+
+## EXECUTION PROTOCOLS:
+
+- Load and present the refinement summary from the compiled document
+- No new content written — document was finalized in Step 05
+- Present summary, next steps, and review options clearly
+- Read-only presentation — do not alter document data
+
+## CONTEXT BOUNDARIES:
+
+- Available: Complete {outputFile} with all refinements from Steps 02-05
+- Focus: Clear, actionable presentation of refinement results
+- Limits: Do not add new analysis or change any refinements
+- Dependencies: All previous steps must be complete (Steps 01-05)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Refined Document
+
+Read the `{outputFile}` to have all data available for presentation.
+
+Verify the `## Refinement Summary` section is present. If it is absent, HALT: "⚠️ Refinement Summary not found in `{outputFile}`. Step 05 may not have completed successfully. Re-run [RA] from the beginning."
+
+**Extract metrics from the Refinement Summary section:** Parse `gap_count`, `issue_count`, `improvement_count`, `critical_count`, `major_count`, `minor_count`, `high_count`, `medium_count`, `low_count`, and `skill_count` from the Changes Made table and Evidence Sources table. Use these extracted values in the summary table and next-steps sections below.
+
+### 2. Display Summary
+
+"**Refine Architecture — Refinement Complete**
+
+---
+
+| Metric | Count |
+|--------|-------|
+| **Gaps Filled** | {gap_count} |
+| **Issues Flagged** | {issue_count} (Critical: {critical_count}, Major: {major_count}, Minor: {minor_count}) |
+| **Improvements Suggested** | {improvement_count} (High: {high_count}, Medium: {medium_count}, Low: {low_count}) |
+| **Skills Used as Evidence** | {skill_count} |
+
+**Evidence Sources:** (which skills contributed evidence)
+
+{Display the Evidence Sources table from the Refinement Summary section of the document}
+
+---
+
+**Your refined architecture is at:** `{outputFile}`
+
+The original architecture content is fully preserved. All refinements are clearly marked with `[!NOTE]`, `[!WARNING]`, and `[!TIP]` callout blocks that you can accept, modify, or remove."
+
+### 3. Present Next Steps
+
+"**Recommended next steps:**
+
+1. **Review the refined document** — accept, modify, or remove individual refinements
+2. **[SS] Stack Skill** — compose-mode activates automatically when SS detects existing individual skills without a codebase; provide this refined architecture doc as the architecture document when prompted
+3. **Re-run [VS] Verify Stack** if you made changes based on issue corrections — to confirm resolution
+
+{IF issues with Critical severity were found:}
+**⚠️ Attention:** {critical_count} critical issue(s) were flagged. These indicate fundamental contradictions between your architecture and the verified API surfaces. Address these before proceeding to stack skill composition."
+
+### 4. Present Menu
+
+Display: "**[R] Review changes in detail** | **[X] Exit refinement**"
+
+#### Menu Handling Logic:
+
+- **IF R:** Walk through each refinement with its full evidence citation:
+  1. First, all gaps with their evidence and proposed integration paths
+  2. Then, all issues ordered by severity with architecture claim vs. skill reality
+  3. Finally, all improvements ordered by value with untapped capability details
+  After completing the walkthrough, redisplay the menu.
+
+- **IF X:** "**Refined architecture saved to:** `{outputFile}`
+
+Re-run **[RA] Refine Architecture** anytime after updating your skills or architecture document.
+
+**Architecture refinement complete.**"
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting the menu
+- R may be selected multiple times — always walk through all refinements
+- X ends the workflow
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final step of the refine-architecture workflow. When the user selects X, the workflow is complete. The refined architecture at `{outputFile}` contains the full original content plus all gap-fills, issue annotations, and improvement suggestions backed by skill API evidence.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refined document loaded and verified for Refinement Summary section
+- Summary displayed with accurate counts for gaps, issues, and improvements
+- Output file path displayed prominently
+- Next steps presented with specific workflow recommendations
+- Critical issues highlighted if present
+- Menu presented with R and X options
+- Detailed review walkthrough available on R selection with full evidence citations
+- Workflow exits cleanly on X with saved file path
+
+### ❌ SYSTEM FAILURE:
+
+- Discovering new findings or changing refinements in this step
+- Modifying the refined document content
+- Not presenting the menu
+- Not displaying the document save path on exit
+- Inaccurate counts in the summary
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/workflow.md

@@ -0,0 +1,61 @@
+---
+name: refine-architecture
+description: Improve architecture doc using verified skill data and VS feasibility findings
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/refine-architecture'
+---
+
+# Refine Architecture
+
+**Goal:** Take an original architecture document + generated skills + optional VS feasibility report, and produce a refined architecture with gaps filled, issues flagged, and improvements suggested — all backed by specific API evidence from the generated skills.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an architecture refinement analyst operating in Ferris Architect mode. You bring expertise in API surface analysis, integration gap detection, and evidence-backed architecture improvement, while the user brings their architecture vision and generated skills. Execute with analytical precision — every suggestion must cite specific APIs from the generated skills. Evidence-backed suggestions, not speculation.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory — never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **Additive, Not Destructive**: This workflow enhances the original architecture — it never deletes original content, only adds annotations, subsections, and suggestions
+- **Evidence-Backed Refinement**: Every gap, issue, or improvement must cite specific APIs, types, or function signatures from the generated skills
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- ⚙️ **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}`
+- 📝 **DOCUMENT-PRODUCING**: This workflow outputs a refined architecture markdown file
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/_bmad/skf/config.yaml and resolve:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`
+- `skills_output_folder`, `forge_data_folder`, `output_folder`
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/workflows/setup-forge/steps-c/step-01-detect-and-tier.md

@@ -45,6 +45,7 @@ Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any e
 - This is the first step — no prior context exists
 - Available: forge-tier.yaml and preferences.yaml may exist from prior runs
 - Focus: tool verification and tier calculation only
+- Produces: `{detected_tools}`, `{calculated_tier}`, `{previous_tier}`, `{tier_override}` for downstream steps
 - Dependencies: none — this step bootstraps everything
 
 ## MANDATORY SEQUENCE
@@ -104,7 +105,7 @@ This is informational only — security scan availability does NOT affect the ti
 
 **Step B — Daemon health:** Run `ccc doctor`
 
-- If daemon is running and model check OK: record `{ccc: true}` and store version string from output
+- If daemon is running and model check OK: record `{ccc: true, ccc_daemon: "healthy"}` and store version string from output
 - If daemon is not running: record `{ccc: true, ccc_daemon: "stopped"}` — binary available, daemon needs starting. Step-01b will handle this.
 - If error or timeout: record `{ccc: true, ccc_daemon: "error"}` — binary works but daemon has issues.
 

package/src/workflows/setup-forge/steps-c/step-01b-ccc-index.md

@@ -71,7 +71,7 @@ Check the `ccc_index` section:
   - Proceed to section 4
 
 - If `ccc_index.indexed_path` matches `{project-root}` but timestamp is older than threshold:
-  - Store `{ccc_index_result: "stale", ccc_indexed_path: {existing path}, ccc_last_indexed: {existing timestamp}}` — proceed to section 3 for re-index
+  - Note index is stale — proceed to section 3 for re-index (section 3 will overwrite `ccc_index_result` to `"created"` or `"failed"`)
 
 - If `ccc_index` is missing, has null values, or path doesn't match:
   - Proceed to section 3 for initial index

package/src/workflows/setup-forge/steps-c/step-02-write-config.md

@@ -41,10 +41,10 @@ Write the detected tool availability and calculated tier to forge-tier.yaml, cre
 
 ## CONTEXT BOUNDARIES:
 
-- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01
+- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01; {ccc_index_result}, {ccc_indexed_path}, {ccc_last_indexed} from step-01b
 - Focus: file I/O operations only
 - Limits: do not modify preferences.yaml if it exists
-- Dependencies: step-01 must have completed with tool detection results
+- Dependencies: step-01 and step-01b must have completed with tool detection and CCC index results
 
 ## MANDATORY SEQUENCE
 
@@ -76,18 +76,19 @@ tier_detected_at: {current ISO timestamp}
 ccc_index:
   indexed_path: {ccc_indexed_path from step-01b, or ~}
   last_indexed: {ccc_last_indexed from step-01b, or ~}
-  status: {ccc_index_status from step-01b: "fresh"|"created"|"none"|"failed"}
+  status: {ccc_index_result from step-01b: "fresh"|"created"|"none"|"failed"}
   staleness_threshold_hours: 24
 
 # CCC index registry (tracks which source paths have been indexed for skill workflows)
-ccc_index_registry: []
+# PRESERVE existing entries on re-runs — see Note below
+ccc_index_registry: {preserved from existing forge-tier.yaml, or [] if first run}
 
 # QMD collection registry (populated by create-skill, consumed by audit/update-skill)
-# Each entry tracks a QMD collection created during skill workflows
-qmd_collections: []
+# PRESERVE existing entries on re-runs — see Note below
+qmd_collections: {preserved from existing forge-tier.yaml, or [] if first run}
 ```
 
-**Note on re-runs:** The `qmd_collections` and `ccc_index_registry` arrays must be preserved across re-runs. Before overwriting forge-tier.yaml, read the existing `qmd_collections` and `ccc_index_registry` arrays and re-inject them into the new write. These arrays are populated by create-skill workflows and must not be reset.
+**Note on re-runs:** The `qmd_collections`, `ccc_index_registry` arrays, and `staleness_threshold_hours` value must be preserved across re-runs. Before overwriting forge-tier.yaml, read these existing values and re-inject them into the new write. These values are populated by create-skill workflows or customized by users and must not be reset.
 
 **This file is ALWAYS overwritten** on every run — it reflects current tool state.
 
@@ -110,27 +111,25 @@ tier_override: ~
 # Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
 passive_context: true
 
-# Language defaults
-output_language: ~
-skill_format_version: ~
-
-# Output preferences
-citation_style: ~
-confidence_display: ~
+# Reserved for future use — these fields are not yet consumed by any workflow step
+# output_language: ~
+# skill_format_version: ~
+# citation_style: ~
+# confidence_display: ~
 ```
 
 **If it DOES exist:** Do not modify. Preserve entirely.
 
 ### 3. Ensure forge-data/ Directory
 
-Check if `{project-root}/forge-data/` directory exists:
+Check if `{forge_data_folder}` directory exists:
 
 - If missing: create it
 - If exists: skip silently
 
 ### 4. Auto-Proceed
 
-"**Proceeding to auto-index check...**"
+"**Proceeding to QMD collection hygiene...**"
 
 #### Menu Handling Logic:
 

package/src/workflows/setup-forge/steps-c/step-03-auto-index.md

@@ -59,7 +59,7 @@ For Quick and Forge tiers (without ccc), skip silently and proceed. For Forge+ t
 
 Read `{calculated_tier}` from context.
 
-**If tier is Quick or Forge:** Proceed directly to section 6 (Auto-Proceed) — no output, no messaging.
+**If tier is Quick or Forge:** Set `{ccc_registry_stale_cleaned: 0}`. Proceed directly to section 6 (Auto-Proceed) — no output, no messaging.
 
 **If tier is Forge+:** Skip QMD hygiene (qmd is not available at Forge+). Proceed directly to section 5b (CCC Index Registry Hygiene) — no QMD output, no messaging.
 

package/src/workflows/setup-forge/steps-c/step-04-report.md

@@ -115,10 +115,10 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 
 ### 3. Handle --update-spec Flag (Optional)
 
-**If `--update-spec` was passed:**
+**If the user included `--update-spec` in their workflow invocation (e.g., `@Ferris SF --update-spec`):**
 - Attempt to fetch the latest agentskills.io specification schema
 - Use `gh` or `curl` to retrieve the spec
-- Store in `{project-root}/forge-data/agentskills-spec.json` (or appropriate format)
+- Store in `{forge_data_folder}/agentskills-spec.json` (or appropriate format)
 - If fetch succeeds: display "agentskills.io spec updated."
 - If fetch fails: display "Could not fetch agentskills.io spec. Existing spec (if any) unchanged."
 - Do NOT fail the workflow over this — it is purely optional

package/src/workflows/setup-forge/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: setup-forge
-description: Initialize forge environment, detect tools, set tier, auto-index project
+description: Initialize forge environment, detect tools, set tier, verify QMD collection hygiene
 web_bundle: true
 installed_path: '{project-root}/_bmad/skf/workflows/skillforge/setup-forge'
 ---
@@ -15,7 +15,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/skillforge/setup-forge'
 
 ### Core Principles
 
-- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere to 1 file as directed at a time
 - **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
 - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
 - **Fully Autonomous**: All steps auto-proceed with no user interaction until the final report
@@ -44,6 +44,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/skillforge/setup-forge'
 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`, `sidecar_path`
 
 ### 2. First Step Execution
 

package/src/workflows/test-skill/data/scoring-rules.md

@@ -17,6 +17,8 @@
 
 ## Naive Mode Weight Redistribution
 
+The following weights replace the default table for naive mode. The 18% coherence weight from the default table has been proportionally redistributed into these values. Do not apply a second redistribution.
+
 When running in naive mode (no coherence category):
 - Export Coverage: 45%
 - Signature Accuracy: 25%
@@ -38,6 +40,7 @@ tessl evaluates SKILL.md body content only — it does not read `references/*.md
 - Signature Accuracy: skipped (no AST)
 - Type Coverage: skipped (no AST)
 - Score based on: structural completeness only
+- Weight redistribution: skipped categories' weights (Signature Accuracy 22% + Type Coverage 14%) redistributed proportionally to remaining active categories
 
 ### Forge Tier (ast-grep)
 - Export Coverage: AST-backed export comparison

package/src/workflows/test-skill/data/source-access-protocol.md

@@ -32,7 +32,7 @@ If no provenance-map.json exists (typical for quick-skill output), fall back to
 If neither provenance-map nor metadata exports provide a usable baseline, but remote reading tools (zread, deepwiki, gh API, or similar) are available and `source_repo` is set in metadata.json, read the entry point remotely to build the export inventory from scratch. Name-matching only — no AST. Set `analysis_confidence: remote-only`.
 
 **State 5 — No source access at all:**
-If none of the above succeed, fall through to docs-only mode (section 0 already handles this). Set `analysis_confidence: docs-only`. Warn: "**No source access available.** Coverage check evaluates documentation self-consistency only. Re-run with local clone or remote access for source-backed verification."
+If none of the above succeed, fall through to docs-only mode (as defined in step-01-init.md Section 0: pre-analysis source type detection). Set `analysis_confidence: docs-only`. Warn: "**No source access available.** Coverage check evaluates documentation self-consistency only. Re-run with local clone or remote access for source-backed verification."
 
 Set `analysis_confidence` in context for use in Section 2 analysis depth, step-05 output, and step-05 scoring.
 

package/src/workflows/test-skill/steps-c/step-01-init.md

@@ -150,6 +150,7 @@ testMode: ''
 forgeTier: '{detected_tier}'
 testResult: ''
 score: ''
+threshold: ''
 analysisConfidence: ''
 testDate: '{current_date}'
 stepsCompleted: ['step-01-init']

package/src/workflows/test-skill/steps-c/step-02-detect-mode.md

@@ -86,6 +86,8 @@ Read the skill metadata (loaded in step 01) and check:
 - Default to **naive mode** (conservative — fewer checks, less chance of false negatives from missing context)
 - Note the default in the report
 
+**Quick-tier adjustment (applies to both modes):** If `forge_tier` is `Quick`, Signature Accuracy and Type Coverage are skipped during scoring (no AST available). Their weights are redistributed proportionally to remaining active categories. See `scoring-rules.md` Tier-Dependent Scoring section for details.
+
 ### 3. Update Output Document
 
 Update `{outputFile}` frontmatter:

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

@@ -2,7 +2,7 @@
 name: test-skill
 description: Cognitive completeness verification. Naive and contextual modes.
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/test-skill'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/test-skill'
 ---
 
 # Test Skill
@@ -15,7 +15,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/test-skill'
 
 ### Core Principles
 
-- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere to 1 file as directed at a time
 - **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
 - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
 - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array

package/src/workflows/update-skill/steps-c/step-02-detect-changes.md

@@ -110,7 +110,7 @@ Launch subprocesses in parallel that compare source state against provenance map
 
 **Category C — Rename detection:**
 - Cross-reference deleted files/exports with added files/exports
-- If content similarity > 80%: classify as RENAMED instead of deleted+added
+- If content similarity > 80%: classify as RENAMED instead of deleted+added. **Similarity mechanism by tier:** Quick: compare file size ratio (within 20%) and export name overlap (>70% of exports match by name). Forge and above: use ast-grep to compare export signatures between the deleted and added files. Forge+/Deep: use CCC semantic similarity when available
 
 **Category D — Script/asset file changes:**
 - Compare `file_entries` from provenance-map.json against current source files
@@ -177,7 +177,7 @@ The skill `{skill_name}` is current — no update needed.
 | Files moved/renamed | {count} |
 | Exports affected | {total_export_changes} |
 
-**Proceeding to re-extraction of {affected_file_count} changed files...**"
+**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**"
 
 ### 6. Present MENU OPTIONS