bmad-module-skill-forge 0.6.0 → 0.7.1

package/src/workflows/create-stack-skill/steps-c/step-04-parallel-extract.md

@@ -27,7 +27,7 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 ### Step-Specific Rules:
 
-- 🎯 Extract per-library using Pattern 4 (parallel subprocess) when available
+- 🎯 Extract per-library using Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 💬 Each subprocess returns structured extraction, not raw file contents
 - 🚫 FORBIDDEN to analyze cross-library integrations — that is step 05
 - ⚙️ If parallel subprocess unavailable, extract libraries sequentially in main thread
@@ -50,6 +50,30 @@ For each confirmed dependency, extract key exports, usage patterns, and API surf
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
+### 0. Check Compose Mode
+
+**If `compose_mode` is true:**
+
+"**Extraction data already available from individual skills. Skipping extraction phase.**"
+
+For each confirmed skill, load `{skills_output_folder}/{skill_dir}/SKILL.md` (where `skill_dir` is the subdirectory name stored in step-02, which may differ from the `name` field in metadata.json) into context. Build a `per_library_extractions[]` entry for each skill with the following fields:
+- `library`: skill name from metadata.json
+- `exports`: exports list extracted from the SKILL.md exports section
+- `usage_patterns`: usage patterns from the SKILL.md usage section
+- `confidence`: the skill's existing confidence tier (T1, T1-low, T2) — inherited directly
+
+Display an extraction summary:
+
+"**Loaded {N} skill extractions from existing skills.**
+
+| Skill | Exports | Confidence | Status |
+|-------|---------|------------|--------|
+| {name} | {count} | {tier} | Loaded |"
+
+Auto-proceed to next step.
+
+**If not compose_mode:** Continue with section 1 (existing flow).
+
 ### 1. Prepare Extraction Plan
 
 **AST Tool Availability Check (Forge/Deep only):**
@@ -81,14 +105,25 @@ For each library in `confirmed_dependencies`, determine extraction strategy base
 - Confidence: T1 (AST-verified structural extraction)
 
 **Deep Tier (adds to Forge):**
-- Use qmd_bridge for temporal usage evolution
-- Identify deprecated patterns and migration paths
-- Track API changes across project history
-- Confidence: T2 (QMD-enriched temporal context)
+- Perform all Forge tier extractions (T1)
+- Additionally: query existing QMD temporal collections for each library
+- Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`
+- For each library in `confirmed_dependencies`, search for a registry entry where `skill_name` matches the library name AND `type` is `"temporal"`
+- **If a matching temporal collection exists:**
+  - Query `qmd_bridge.search("{library_name} deprecated OR removed OR breaking change")` for deprecation context
+  - Query `qmd_bridge.search("{library_name} migration OR upgrade")` for migration patterns
+  - Query `qmd_bridge.search("{library_name} version issue OR bug OR workaround")` for version-specific warnings
+  - **Tool resolution for qmd_bridge:** Use QMD MCP tools — `mcp__plugin_qmd-plugin_qmd__search` (Claude Code), qmd MCP server (Cursor), `qmd search "{query}"` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
+  - Classify each result as T2-past (historical) or T2-future (planned changes) per confidence-tiers.md
+  - Append temporal findings to the library's extraction as T2 annotations with `[QMD:{collection}:{doc}]` citations
+- **If no matching temporal collection found:**
+  - Log: "No temporal collection for {library_name}. T2 enrichment skipped."
+  - Continue with T1/T1-low extraction only
+- Confidence: T1 for structural (AST), T2 for temporal annotations (QMD-enriched)
 
 ### 2. Launch Parallel Extraction
 
-**Launch subprocesses in parallel** (max_parallel_generation) — one per confirmed library:
+**Launch subprocesses in parallel** (max_parallel_generation: 3–5 concurrent Agent tool calls in Claude Code, IDE-dependent in Cursor, CPU core count in CLI) — one per confirmed library:
 
 Each subprocess:
 1. Reads all files importing the library (from step 03 file lists)
@@ -105,7 +140,13 @@ Each subprocess:
   usage_patterns: ["pattern description with file:line"],
   confidence: "T1|T1-low|T2",
   files_analyzed: count,
-  warnings: []
+  warnings: [],
+  temporal: {
+    deprecated_exports: ["export_name — reason [QMD:collection:doc]"],
+    migration_notes: ["note [QMD:collection:doc]"],
+    version_warnings: ["warning [QMD:collection:doc]"],
+    t2_annotation_count: count
+  }
 }
 ```
 
@@ -137,6 +178,8 @@ For each library extraction:
 
 **Results:** {success_count}/{total_count} libraries extracted
 **Confidence distribution:** T1: {count}, T1-low: {count}, T2: {count}
+{If Deep tier:} **T2 enrichment:** {enriched_count}/{total_count} libraries had temporal collections available
+{If libraries without temporal > 0:} **Tip:** Run [CS] Create Skill at Deep tier for individual libraries to generate temporal collections, then re-run [SS] for full T2 enrichment.
 {If warnings:} **Warnings:** {warning_count} issues noted
 
 **Proceeding to integration detection...**"

package/src/workflows/create-stack-skill/steps-c/step-05-detect-integrations.md

@@ -4,6 +4,7 @@ description: 'Detect co-import patterns and integration points between confirmed
 
 nextStepFile: './step-06-compile-stack.md'
 integrationPatterns: '../data/integration-patterns.md'
+composeModeRules: '../data/compose-mode-rules.md'
 ---
 
 # Step 5: Detect Integrations
@@ -28,7 +29,7 @@ Analyze co-import patterns between confirmed libraries to identify integration p
 
 ### Step-Specific Rules:
 
-- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep) subprocess
+- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep/search): In Claude Code, use the Grep tool or Bash with `rg`. In Cursor, use built-in search. In CLI, use `grep`/`rg` directly. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
 - 🚫 FORBIDDEN to compile SKILL.md — that is step 06
 - 💬 Integration detection is the core differentiator of stack skills vs individual skills
 - ⚙️ If subprocess unavailable, perform grep operations in main thread
@@ -42,7 +43,7 @@ Analyze co-import patterns between confirmed libraries to identify integration p
 
 ## CONTEXT BOUNDARIES:
 
-- From step 03: confirmed_dependencies[] with file lists per library
+- From step 03: confirmed_dependencies[] — in code-mode, includes file lists per library; in compose-mode, file lists are not present (use per_library_extractions[] from step 04 for skill content)
 - From step 04: per_library_extractions[] with exports and patterns
 - This step produces: integration_graph {pairs[], types[], files[]}
 - This is the VALUE-ADD step — what makes stack skills different from individual skills
@@ -61,10 +62,39 @@ Report: "**Analyzing {pair_count} library pairs for integration patterns...**"
 
 ### 2. Detect Co-Import Files
 
+**If `compose_mode` is true:**
+
+Instead of co-import grep, detect integrations from architecture document:
+
+1. Load `{composeModeRules}` for integration evidence format rules
+2. **If `{architecture_doc_path}` is null or not available:** Skip directly to the "If no architecture document available" fallback below
+3. Load the architecture document from `{architecture_doc_path}`
+4. Use prose-based co-mention analysis: find paragraphs mentioning 2+ confirmed skill names
+5. For each detected integration pair:
+   - Load both skills' export lists and API signatures
+   - Compose an integration section following the format from `{composeModeRules}`
+   - Include VS feasibility verdict if a feasibility report (`feasibility-report-{project_name}.md`) exists in `{forge_data_folder}/`
+   - Cite evidence from both skills: `[from skill: {skill_name}]`
+
+All integration evidence inherits confidence tiers from the source skills. Load and apply the full **Confidence Tier Inheritance** matrix from `{composeModeRules}` to compute the correct tier for each pair (covers T1+T1, T1+T1-low, T1-low+T1-low, T1+T2, T1-low+T2, T2+T2 cases). Apply the `[composed]` suffix to all confidence labels — e.g., `T1 [composed]`, `T1-low [composed, +T2 annotations]`.
+
+**VS verdict parsing (if feasibility report exists):** Read the `overall_verdict` from the report's YAML frontmatter. Parse the `## Integration Verdicts` markdown table for per-pair verdicts. For each architecture-detected pair, include `VS overall: {verdict}` and `VS pair: {verdict}` in the integration evidence per the format in `{composeModeRules}`. VS verdicts do not apply to inferred integrations since the VS report operates on architecture-described interactions only. Additionally, flag any pairs where VS reported `Risky` or `Blocked` by appending a `[VS: Risky]` or `[VS: Blocked]` warning annotation to the integration entry.
+
+If no architecture document available:
+- Infer potential integrations from skills sharing the same `language` field or sharing domain keywords in their SKILL.md descriptions (use the `usage_patterns` and `exports` fields from `per_library_extractions[]` built in step-04, or reload `{skills_output_folder}/{skill_dir}/SKILL.md` if full prose text is needed for keyword extraction)
+- Mark inferred integrations: `[inferred from shared domain]` — use this suffix instead of `[composed]` for inferred integrations
+- Inferred integrations qualify automatically — no file-count threshold applies
+
+Skip to section 3 (Classify Integration Types) with the compose-mode pairs.
+
+**If not compose_mode:**
+
 For each library pair (A, B):
 
 **Launch a subprocess** that greps across all source files to find files importing BOTH library A and library B. Return only file paths and import line numbers.
 
+**Subprocess resolution:** Use the Grep tool (Claude Code), built-in search (Cursor), or `grep`/`rg` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 **Subprocess returns:** `{pair: [A, B], co_import_files: [{path, line_A, line_B}], count: N}`
 
 **If subprocess unavailable:** Intersect the file lists from step 03 import counts for each pair.
@@ -77,6 +107,8 @@ If `tools.ccc` is true AND `ccc_index.status` is `"fresh"` or `"stale"` in forge
 
 For each library pair that has exactly 1 co-import file (below the 2-file threshold), run `ccc_bridge.search("{libA} {libB}", source_root, top_k=10)` to find files where the two libraries interact semantically — even without explicit import co-location. If CCC returns additional files where both libraries appear, add them to the pair's co-import candidate list and re-evaluate against the 2-file threshold.
 
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{libA} {libB}" --path {source_root} --top 10` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
 For pairs that already qualify (2+ files), CCC is not needed for detection — but the CCC results may surface additional integration files for richer classification in section 3.
 
 CCC failures: skip augmentation silently, proceed with grep-only results.
@@ -85,7 +117,7 @@ CCC failures: skip augmentation silently, proceed with grep-only results.
 
 Load `{integrationPatterns}` for classification rules.
 
-For each qualifying pair (2+ co-import files), analyze the co-import files to classify the integration type:
+For each qualifying pair, analyze to classify the integration type (**in compose-mode**: all architecture-document-detected pairs qualify automatically — the 2+ co-import file threshold applies only in code-mode; **in code-mode**: pair must have 2+ co-import files):
 
 - **Type 1: Middleware Chain** — Sequential function calls piping output between libraries
 - **Type 2: Shared Types** — Type definitions exchanged between libraries

package/src/workflows/create-stack-skill/steps-c/step-06-compile-stack.md

@@ -80,6 +80,8 @@ description: >
 
 **This is the core value of the stack skill.** Compile in order:
 
+**Zero-integration guard:** If the integration graph from step 05 has zero edges (no detected integration pairs), skip the integration layer compilation and note: "No integration patterns detected — stack skill will contain library summaries without an integration layer." Proceed directly to section 4 (Per-Library Sections).
+
 **Cross-cutting patterns** (if any):
 - Patterns spanning 3+ libraries
 - Middleware chains, shared configuration, common architectural patterns
@@ -98,7 +100,7 @@ description: >
 
 ### 4. Compile Per-Library Sections
 
-For each confirmed library (ordered by integration connectivity, then import count):
+For each confirmed library (ordered by integration connectivity, then import count — **in compose-mode**, order by integration connectivity, then skill confidence tier since import counts are not available):
 
 - Role in stack (one-line description)
 - Key exports used in this project
@@ -122,6 +124,8 @@ Create the reference index table:
 |---------|---------|-------------|------------|-----------|
 | ... | ... | ... | ... | ... |
 
+(**in compose-mode**: replace the Imports column with Export Count from source skill metadata, since import counts are not available)
+
 ### 7. Present Compiled SKILL.md Preview
 
 "**Stack skill compilation complete. Please review:**

package/src/workflows/create-stack-skill/steps-c/step-07-generate-output.md

@@ -77,10 +77,10 @@ Write `{skills_output_folder}/{project_name}-stack/SKILL.md` with the approved s
 For each confirmed library, write `{skills_output_folder}/{project_name}-stack/references/{library_name}.md`:
 
 Load structure from `{stackSkillTemplate}` references section:
-- Library name, version from manifest
-- Import count and file count
+- Library name, version from manifest (**in compose-mode**: version from source skill `metadata.json`)
+- Import count and file count (**in compose-mode**: export count from source skill metadata)
 - Key exports with signatures
-- Usage patterns with file:line citations
+- Usage patterns with file:line citations (**in compose-mode**: usage patterns from source skill SKILL.md)
 - Confidence tier label
 
 ### 4. Write Integration Pair Reference Files
@@ -102,7 +102,7 @@ Write `{skills_output_folder}/{project_name}-stack/context-snippet.md`:
 
 Use the Vercel-aligned indexed format targeting ~80-120 tokens:
 ```
-[{project_name}-stack v{version}]|root: skills/{project_name}-stack/
+[{project_name}-stack v{version — in code-mode: primary_library_version or 1.0.0; in compose-mode: highest version across constituent skill metadata.json files, or 1.0.0 if none}]|root: skills/{project_name}-stack/
 |IMPORTANT: {project_name}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
@@ -113,6 +113,8 @@ Use the Vercel-aligned indexed format targeting ~80-120 tokens:
 
 Write `{skills_output_folder}/{project_name}-stack/metadata.json`:
 
+Populate all fields from the metadata.json schema defined in `{stackSkillTemplate}`:
+
 ```json
 {
   "skill_type": "stack",
@@ -120,11 +122,34 @@ Write `{skills_output_folder}/{project_name}-stack/metadata.json`:
   "version": "{primary_library_version or 1.0.0}",
   "generation_date": "{current_date}",
   "confidence_tier": "{tier}",
+  "spec_version": "1.3",
+  "source_authority": "{official|community|internal — use the lowest authority among constituent skills}",
+  "generated_by": "create-stack-skill",
+  "exports": [],
   "library_count": N,
   "integration_count": N,
   "libraries": ["lib1", "lib2"],
   "integration_pairs": [["lib1", "lib2"]],
-  "confidence_distribution": {"T1": N, "T1-low": N, "T2": N}
+  "language": "{primary language or list of languages from constituent skills}",
+  "ast_node_count": "{number or omit if no AST extraction performed}",
+  "confidence_distribution": {"t1": N, "t1_low": N, "t2": N, "t3": N},
+  "tool_versions": {
+    "ast_grep": "{version or null}",
+    "qmd": "{version or null}",
+    "skf": "{skf_version}"
+  },
+  "stats": {
+    "exports_documented": N,
+    "exports_public_api": N,
+    "exports_internal": N,
+    "exports_total": N,
+    "public_api_coverage": 0.0,
+    "total_coverage": 0.0,
+    "scripts_count": N,
+    "assets_count": N
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range}"
 }
 ```
 
@@ -133,6 +158,8 @@ Write `{skills_output_folder}/{project_name}-stack/metadata.json`:
 Write workspace artifacts to `{forge_data_folder}/{project_name}-stack/`:
 
 **provenance-map.json:**
+
+**In code-mode:**
 ```json
 {
   "libraries": {
@@ -154,6 +181,27 @@ Write workspace artifacts to `{forge_data_folder}/{project_name}-stack/`:
 }
 ```
 
+**In compose-mode:**
+```json
+{
+  "libraries": {
+    "lib_name": {
+      "source_skill_path": "skills/{skill_dir}/",
+      "compose_source": "architecture_co_mention|inferred_from_shared_domain",
+      "confidence": "T1|T1-low|T2",
+      "source_skill_tier": "{original skill confidence tier}",
+      "exports_found": N
+    }
+  },
+  "integrations": {
+    "libA+libB": {
+      "detection_method": "architecture_co_mention|inferred_from_shared_domain",
+      "type": "pattern_type"
+    }
+  }
+}
+```
+
 **evidence-report.md:**
 - Extraction summary per library
 - Integration detection results per pair

package/src/workflows/create-stack-skill/steps-c/step-08-validate.md

@@ -112,16 +112,16 @@ Parse metadata.json and verify required fields:
 - [ ] `skill_type` equals "stack"
 - [ ] `name` matches `{project_name}-stack`
 - [ ] `version` and `generation_date` present
-- [ ] `confidence_tier` matches tier from step 01
+- [ ] `confidence_tier` matches forge tier from step 01 (Quick/Forge/Forge+/Deep) — in both code-mode and compose-mode, this is the forge tier; per-library inherited confidence is tracked separately in `confidence_distribution`
 - [ ] `library_count` matches actual reference files; `integration_count` matches pair files
 - [ ] `libraries` array present and non-empty
-- [ ] `confidence_distribution` object present with T1/T1-low/T2 keys
+- [ ] `confidence_distribution` object present with `t1`, `t1_low`, `t2`, `t3` keys (lowercase, matching template definition)
 
 Record mismatches as **WARNING** findings.
 
 ### 6. Validate Reference File Completeness
 
-For each confirmed library, verify `references/{library}.md` contains: library name header, version from manifest, Key Exports section, Usage Patterns section.
+For each confirmed library, verify `references/{library}.md` contains: library name header, version from manifest (**in compose-mode**: version from source skill metadata), Key Exports section, Usage Patterns section.
 
 For each integration pair, verify `references/integrations/{libraryA}-{libraryB}.md` contains: integration pair header, type classification, Integration Pattern section, Key Files section.
 

package/src/workflows/create-stack-skill/steps-c/step-09-report.md

@@ -64,7 +64,11 @@ Forge tier: **{tier}**"
 |------|-------|-------------|
 | T1 | {count} | AST-verified structural extraction |
 | T1-low | {count} | Source reading inference |
-| T2 | {count} | QMD-enriched temporal context |"
+| T2 | {count} | QMD-enriched temporal context |
+
+{IF compose_mode:}
+*Note: Confidence tiers above are inherited from source skills — they reflect the extraction method used when those skills were originally generated, not the current compose run.*
+{END IF}"
 
 ### 3. Display Output File Summary
 
@@ -107,7 +111,9 @@ Forge tier: **{tier}**"
 
 "**Next steps:**
 - **[TS] test-skill** — Validate the stack skill against its own assertions
-- **[ES] export-skill** — Package for distribution or agent loading
+- **[EX] export-skill** — Package for distribution or agent loading
+
+- **[VS] verify-stack** — Validate the stack's integration feasibility against your architecture document{IF compose_mode:} (re-run to confirm feasibility after any architecture changes from **[RA] refine-architecture**){END IF}
 
 **Workflow complete.**"
 

package/src/workflows/create-stack-skill/workflow.md

@@ -7,7 +7,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/skillforge/create-stack-skil
 
 # Create Stack Skill
 
-**Goal:** Analyze a project's dependency manifests, detect significant libraries, discover co-import integration points, and produce a consolidated stack skill documenting how libraries connect in THIS specific codebase.
+**Goal:** Produce a consolidated stack skill documenting how libraries connect. **Code-mode:** analyzes dependency manifests and co-import patterns from actual source code. **Compose-mode:** synthesizes from pre-generated individual skills and architecture documents when no codebase exists yet.
 
 **Your Role:** In addition to your name, communication_style, and persona, you are also a dependency analyst and integration architect operating in Ferris Architect mode. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences. Execute with prescriptive precision — every finding must trace to actual code with file:line citations.
 
@@ -23,7 +23,7 @@ This uses **step-file architecture** for disciplined execution:
 - **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
 - **Append-Only Building**: Build outputs by accumulating state across steps
-- **Zero Hallucination**: All extracted content must trace to actual source code — no inferred or assumed patterns
+- **Zero Hallucination**: All extracted content must trace to actual source code — no inferred or assumed patterns. In compose-mode, inferred integrations are permitted but must be labeled `[inferred from shared domain]` per compose-mode-rules.md
 
 ### Step Processing Rules
 

package/src/workflows/export-skill/data/managed-section-format.md

@@ -22,7 +22,7 @@
 | Cursor | `cursor` | .cursorrules |
 | Copilot | `copilot` | AGENTS.md |
 
-## Three-Case Logic
+## Four-Case Logic
 
 ### Case 1: Create (No File Exists)
 
@@ -53,6 +53,13 @@ Target file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers. Replace co
 4. Replace everything between markers (inclusive) with new managed section
 5. Write file
 
+### Case 4: Malformed Markers (Halt)
+
+Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker. This indicates a corrupted managed section.
+
+1. Halt workflow with error: "Malformed managed section — `<!-- SKF:BEGIN` found but no `<!-- SKF:END -->`. Fix the markers manually before re-running export."
+2. Do not modify the file
+
 ## Regeneration: Full Index Rebuild
 
 When regenerating (Case 3), rebuild the COMPLETE skill index:

package/src/workflows/export-skill/data/snippet-format.md

@@ -40,7 +40,7 @@
 
 ## Rules
 
-- **api line**: Top exports from metadata.json `exports` array. Append `()` to function names. Comma-separated.
+- **api line**: Top exports from metadata.json `exports` array (up to 10 for Deep tier, up to 5 for all other tiers). Append `()` to function names. Comma-separated.
 - **key-types line**: Anchor to `#key-types` section + inline summary (~10 words) of the most important type values
 - **gotchas line**: Derived from: T2-future annotations (breaking changes), async requirements, version-specific behavior. If no gotchas available, omit the line.
 - **stack line**: Component versions from metadata.json `components` for stack skills

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

@@ -1,6 +1,6 @@
 ---
 name: 'step-04-update-context'
-description: 'Update managed section in CLAUDE.md/AGENTS.md with three-case logic per ADR-J'
+description: 'Update managed section in CLAUDE.md/AGENTS.md with four-case logic per ADR-J'
 
 nextStepFile: './step-05-token-report.md'
 managedSectionData: '../data/managed-section-format.md'
@@ -10,7 +10,7 @@ managedSectionData: '../data/managed-section-format.md'
 
 ## 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.
+To update the managed `<!-- SKF:BEGIN/END -->` section in the platform-appropriate context file (CLAUDE.md/AGENTS.md/.cursorrules) using the four-case logic defined by ADR-J (Create, Append, Regenerate, Malformed Markers halt), rebuilding the complete skill index from all exported skills.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -105,6 +105,7 @@ Assemble the complete managed section:
 <!-- SKF:BEGIN updated:{current-date} -->
 [SKF Skills]|{n} skills|{m} stack
 |IMPORTANT: Prefer documented APIs over training data.
+|When using a listed library, read its SKILL.md before writing code.
 |
 |{skill-snippet-1}
 |
@@ -132,6 +133,10 @@ Assemble the complete managed section:
 - Diff: Show old managed section vs new managed section
 - Preserved: ALL content before `<!-- SKF:BEGIN` and after `<!-- SKF:END -->`
 
+**Case 4: Malformed markers (file contains `<!-- SKF:BEGIN` but no `<!-- SKF:END -->`)**
+- Action: HALT with warning: "Malformed SKF markers detected in `{target-file}` — `<!-- SKF:BEGIN` found but `<!-- SKF:END -->` is missing. Please restore the end marker manually before running export."
+- Do NOT attempt to write or append — the file is in an inconsistent state
+
 ### 7. Present Change Preview
 
 "**Context update prepared.**

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

@@ -52,7 +52,7 @@ To calculate approximate token counts for all exported artifacts and present a c
 
 ### 1. Calculate Token Counts
 
-For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers).
+For each artifact, estimate tokens using the heuristic: **words * 1.3** (approximate for GPT/Claude tokenizers). This same heuristic is used in step-03 for snippet token estimation.
 
 **Artifacts to measure:**
 

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

@@ -1,11 +1,13 @@
 ---
 name: export-skill
 description: Package for distribution + platform-aware context injection
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/export-skill'
 ---
 
 # Export Skill
 
-**Goal:** Package a completed skill as an agentskills.io-compliant package, generate context snippets, and update the managed section in CLAUDE.md/AGENTS.md for platform-aware context injection.
+**Goal:** Package a completed skill as an agentskills.io-compliant package, generate context snippets, and update the managed section in CLAUDE.md/.cursorrules/AGENTS.md for platform-aware context injection.
 
 **Your Role:** In addition to your name, communication_style, and persona, you are also a delivery and packaging specialist collaborating with a skill developer. This is a partnership, not a client-vendor relationship. You bring expertise in skill packaging, ecosystem compliance, and context injection patterns, while the user brings their completed skill and distribution requirements. Work together as equals.
 

package/src/workflows/quick-skill/data/skill-template.md

@@ -56,7 +56,8 @@ Indexed format targeting ~80-120 tokens per skill:
 |IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {top-5 exports with () for functions}
-|gotchas: {1-2 most critical pitfalls if known}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
 ## metadata.json Format
@@ -64,31 +65,42 @@ Indexed format targeting ~80-120 tokens per skill:
 ```json
 {
   "name": "{skill_name}",
-  "version": "0.1.0",
+  "version": "{source-version or 1.0.0}",
+  "description": "{brief description of the skill}",
   "skill_type": "single",
   "source_authority": "community",
   "source_repo": "{repo_url}",
+  "source_root": "{resolved_source_path}",
+  "source_commit": "{commit_sha_if_available}",
   "source_package": "{package_name}",
   "language": "{language}",
   "generated_by": "quick-skill",
   "generation_date": "{date}",
   "confidence_tier": "Quick",
-  "extraction_tier": "quick",
   "spec_version": "1.3",
   "exports": ["{export_1}", "{export_2}"],
   "confidence_distribution": {
     "t1": 0,
-    "t1_low": "{exports_count}",
+    "t1_low": "{exports_count (integer, not string)}",
     "t2": 0,
     "t3": 0
   },
+  "tool_versions": {
+    "ast_grep": null,
+    "qmd": null,
+    "skf": "{skf_version}"
+  },
   "stats": {
     "exports_documented": "{number}",
     "exports_public_api": "{number}",
     "exports_internal": 0,
     "exports_total": "{number}",
     "public_api_coverage": 1.0,
-    "total_coverage": 1.0
-  }
+    "total_coverage": 1.0,
+    "scripts_count": 0,
+    "assets_count": 0
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range}"
 }
 ```

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

@@ -107,7 +107,8 @@ Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 |IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {top-5 exports with () for functions}
-|gotchas: {1-2 most critical pitfalls if known}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
 **If fewer than 5 exports:** Use all available exports.
@@ -116,29 +117,48 @@ Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ### 4. Generate Metadata JSON
 
-Create metadata.json:
+Generate metadata.json following the exact structure defined in {skillTemplateData} metadata.json section. Populate fields from extraction_inventory:
 
 ```json
 {
-  "name": "{repo_name}",
-  "version": "{extraction_inventory.version or 0.1.0}",
+  "name": "{skill_name}",
+  "version": "{extraction_inventory.version or 1.0.0}",
+  "description": "{brief description of the skill}",
   "skill_type": "single",
   "source_authority": "community",
   "source_repo": "{resolved_url}",
+  "source_root": "{resolved_source_path}",
+  "source_commit": "{commit_sha_if_available}",
   "source_package": "{package_name from manifest}",
   "language": "{language}",
   "generated_by": "quick-skill",
   "generation_date": "{current ISO date}",
   "confidence_tier": "Quick",
+  "spec_version": "1.3",
   "exports": ["{export_1}", "{export_2}"],
+  "confidence_distribution": {
+    "t1": 0,
+    "t1_low": "{number of exports found — must be integer, not string}",
+    "t2": 0,
+    "t3": 0
+  },
+  "tool_versions": {
+    "ast_grep": null,
+    "qmd": null,
+    "skf": "{skf_version}"
+  },
   "stats": {
     "exports_documented": "{number of exports found}",
     "exports_public_api": "{number of exports found}",
     "exports_internal": 0,
     "exports_total": "{number of exports found}",
     "public_api_coverage": 1.0,
-    "total_coverage": 1.0
-  }
+    "total_coverage": 1.0,
+    "scripts_count": 0,
+    "assets_count": 0
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range or null}"
 }
 ```
 

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

@@ -116,7 +116,7 @@ Check context-snippet.md format compliance:
 Check metadata.json has required fields:
 
 - [ ] `name` — present, non-empty
-- [ ] `version` — present (auto-detected or "0.1.0")
+- [ ] `version` — present (auto-detected or "1.0.0")
 - [ ] `source_authority` — must be "community"
 - [ ] `source_repo` — present, valid GitHub URL
 - [ ] `language` — present, non-empty

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

@@ -62,6 +62,9 @@ If directory already exists, confirm with user before overwriting:
 
 "**Directory `{skills_output_folder}/{repo_name}/` already exists.** Overwrite existing files? [Y/N]"
 
+- **If user selects Y:** Proceed to section 2.
+- **If user selects N:** Halt with: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually."
+
 ### 2. Write SKILL.md
 
 Write the compiled SKILL.md content to:

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

@@ -2,7 +2,7 @@
 name: quick-skill
 description: Brief-less fast skill with package-to-repo resolution
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/quick-skill'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/quick-skill'
 ---
 
 # Quick Skill