bmad-module-skill-forge 0.2.0

package/src/workflows/create-stack-skill/steps-c/step-03-rank-and-confirm.md

@@ -0,0 +1,161 @@
+---
+name: 'step-03-rank-and-confirm'
+description: 'Rank dependencies by import frequency and confirm scope with user'
+
+nextStepFile: './step-04-parallel-extract.md'
+---
+
+# Step 3: Rank and Confirm Scope
+
+## STEP GOAL:
+
+Count import frequency for each dependency across the codebase, rank by usage, and present for user confirmation of which libraries to include in the stack skill.
+
+## 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 dependency analyst operating in Ferris Architect mode
+- ✅ Prescriptive precision — import counts must reflect actual code
+- ✅ User has final authority on scope — present data, let them decide
+
+### Step-Specific Rules:
+
+- 🎯 Focus on counting imports, ranking, and getting user confirmation
+- 🚫 FORBIDDEN to extract library documentation — that is step 04
+- 💬 Present data clearly so user can make informed scope decisions
+- 🎯 Use subprocess (Pattern 1 grep) for import counting when available
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Count imports per library across the codebase
+- 💾 Store confirmed_dependencies as workflow state
+- 📖 Wait for user confirmation before proceeding
+- 🚫 FORBIDDEN to proceed without explicit user scope confirmation
+
+## CONTEXT BOUNDARIES:
+
+- From step 02: raw_dependencies[] with ecosystem info
+- This step produces: confirmed_dependencies[] (user-approved scope)
+- User interaction: Gate 1 — scope confirmation required
+- Apply scope_overrides from step 01 if provided
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Count Import Frequency
+
+For each dependency in `raw_dependencies`:
+
+**Launch a subprocess** that runs grep across all source files in the project to count import statements for each library. Return only the counts, not file contents.
+
+Use ecosystem-appropriate import patterns:
+- JavaScript/TypeScript: `import .* from ['"]library`, `require\(['"]library`
+- Python: `import library`, `from library import`
+- Rust: `use library::`, `extern crate library`
+- Go: `"library"` in import blocks
+- (Match patterns from manifest-patterns.md)
+
+**Subprocess returns:** `{library_name: import_count, files: [file_paths]}` for each dependency.
+
+**If subprocess unavailable:** Perform grep operations in main thread sequentially.
+
+Exclude from counting:
+- Test files (*/test/*, *_test.*, *.spec.*, *.test.*)
+- Config files (*.config.*, .eslintrc, etc.)
+- Build artifacts (dist/, build/, node_modules/, target/, __pycache__/)
+
+### 2. Rank and Filter
+
+Sort dependencies by import count (descending).
+
+Apply filtering:
+- **Include by default:** Libraries with 2+ import files
+- **Flag as trivial:** Libraries with 0-1 import files
+- **Apply scope_overrides** from step 01 if provided (force include/exclude)
+
+### 3. Present Ranked List
+
+"**Dependency ranking complete.** Here are your project's libraries ranked by usage:
+
+| # | Library | Imports | Files | Category |
+|---|---------|---------|-------|----------|
+| 1 | {name} | {count} | {file_count} | runtime |
+| 2 | {name} | {count} | {file_count} | runtime |
+| ... | ... | ... | ... | ... |
+
+**Below threshold** (0-1 imports — excluded by default):
+| Library | Imports | Category |
+|---------|---------|----------|
+| {name} | {count} | {category} |
+
+**Total:** {total} dependencies detected, {above_threshold} recommended for inclusion
+
+---
+
+**Please confirm your scope:**
+- Type **C** to accept the recommended scope (all above-threshold libraries)
+- Type library names to **add** from the below-threshold list
+- Type **-library_name** to **exclude** a recommended library
+- Type a custom list to override entirely"
+
+### 4. Process User Response
+
+**If C (accept recommended):**
+Store all above-threshold libraries as `confirmed_dependencies`.
+
+**If modifications requested:**
+Apply additions/exclusions, display updated list, and ask for final confirmation.
+
+**If custom list provided:**
+Use the custom list as `confirmed_dependencies`.
+
+Display final confirmation:
+
+"**Scope confirmed:** {count} libraries selected for stack skill extraction.
+
+{List confirmed libraries}
+
+**Proceeding to parallel extraction...**"
+
+### 5. Present MENU OPTIONS
+
+Display: **Select:** [C] Continue to Extraction
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting scope
+- ONLY proceed to next step when user confirms scope and selects 'C'
+
+#### Menu Handling Logic:
+
+- IF C: Store confirmed_dependencies, then load, read entire file, then execute {nextStepFile}
+- IF Any other: Process as scope modification, redisplay updated list, then [Redisplay Menu Options](#5-present-menu-options)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Import counts reflect actual codebase usage (not guesses)
+- Dependencies ranked by import frequency
+- Trivial dependencies filtered below threshold
+- User explicitly confirmed scope
+- confirmed_dependencies stored for step 04
+
+### ❌ SYSTEM FAILURE:
+
+- Fabricating import counts without grepping
+- Proceeding without user scope confirmation
+- Including test/config files in import counts
+- Starting library extraction (step 04's job)
+
+**Master Rule:** Present data, let user decide. No extraction until scope is confirmed.

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

@@ -0,0 +1,155 @@
+---
+name: 'step-04-parallel-extract'
+description: 'Extract per-library documentation in parallel using tier-dependent tools'
+
+nextStepFile: './step-05-detect-integrations.md'
+---
+
+# Step 4: Parallel Library Extraction
+
+## STEP GOAL:
+
+For each confirmed dependency, extract key exports, usage patterns, and API surface documentation using tier-dependent tools in parallel.
+
+## 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 dependency analyst operating in Ferris Architect mode
+- ✅ Zero hallucination — only extract what exists in actual source code
+- ✅ Every export and pattern must cite actual file:line references
+
+### Step-Specific Rules:
+
+- 🎯 Extract per-library using Pattern 4 (parallel subprocess) when available
+- 💬 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
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Launch parallel extraction per confirmed library
+- 💾 Store per_library_extractions with confidence tier labels
+- 📖 Report extraction summary before auto-proceeding
+- 🚫 FORBIDDEN to proceed if zero libraries successfully extracted
+
+## CONTEXT BOUNDARIES:
+
+- From step 03: confirmed_dependencies[] (user-approved scope)
+- From step 01: forge_tier, available_tools
+- This step produces: per_library_extractions[] per library
+- Each extraction includes: exports, patterns, confidence tier
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Prepare Extraction Plan
+
+For each library in `confirmed_dependencies`, determine extraction strategy based on forge tier:
+
+**Quick Tier:**
+- Read source files that import the library
+- Extract usage patterns from import statements and function calls
+- Identify key exports used in this project
+- Confidence: T1-low (source reading inference)
+
+**Forge Tier (adds to Quick):**
+- Use ast_bridge to analyze structural exports from library source
+- Extract function signatures, type definitions, class hierarchies
+- Map parameter types and return types
+- 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)
+
+### 2. Launch Parallel Extraction
+
+**Launch subprocesses in parallel** (max_parallel_generation) — one per confirmed library:
+
+Each subprocess:
+1. Reads all files importing the library (from step 03 file lists)
+2. Extracts key exports used in this project (functions, classes, types, constants)
+3. Identifies usage patterns (initialization, configuration, common call patterns)
+4. Labels confidence tier based on extraction method
+5. Returns structured extraction to parent:
+
+```
+{
+  library: "name",
+  version: "from_manifest",
+  exports_found: ["fn1", "fn2", "Type1"],
+  usage_patterns: ["pattern description with file:line"],
+  confidence: "T1|T1-low|T2",
+  files_analyzed: count,
+  warnings: []
+}
+```
+
+**If parallel subprocess unavailable:** Process libraries sequentially in main thread. Report progress after each library.
+
+### 3. Handle Extraction Failures
+
+For each library extraction:
+
+**Success:** Store extraction result.
+
+**Partial failure:** Store partial result with warnings, continue with other libraries.
+
+**Complete failure:** Log failure reason, exclude from stack skill, note in report.
+
+"**Warning:** Extraction failed for {library}: {reason}. Excluding from stack skill."
+
+**If ALL extractions fail:** HALT — cannot produce meaningful stack skill.
+
+### 4. Display Extraction Summary
+
+"**Library extraction complete.**
+
+| Library | Exports | Patterns | Confidence | Status |
+|---------|---------|----------|------------|--------|
+| {name} | {count} | {count} | {tier} | ✓ |
+| {name} | {count} | {count} | {tier} | ✓ |
+| {name} | — | — | — | ⚠ partial |
+
+**Results:** {success_count}/{total_count} libraries extracted
+**Confidence distribution:** T1: {count}, T1-low: {count}, T2: {count}
+{If warnings:} **Warnings:** {warning_count} issues noted
+
+**Proceeding to integration detection...**"
+
+### 5. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All confirmed libraries have extraction attempted
+- Extractions cite actual file:line references
+- Confidence tiers correctly assigned per extraction method
+- Partial failures handled gracefully (skip library, continue)
+- Extraction summary displayed with accurate counts
+- Auto-proceeded to step 05
+
+### ❌ SYSTEM FAILURE:
+
+- Fabricating exports not found in source code
+- Not assigning confidence tiers to extractions
+- Halting on single library failure (should degrade gracefully)
+- Analyzing cross-library integrations (step 05's job)
+- Returning raw file contents instead of structured extractions
+
+**Master Rule:** Extract per-library only. Every export must trace to actual code. Degrade gracefully on individual failures.

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

@@ -0,0 +1,154 @@
+---
+name: 'step-05-detect-integrations'
+description: 'Detect co-import patterns and integration points between confirmed libraries'
+
+nextStepFile: './step-06-compile-stack.md'
+integrationPatterns: '../data/integration-patterns.md'
+---
+
+# Step 5: Detect Integrations
+
+## STEP GOAL:
+
+Analyze co-import patterns between confirmed libraries to identify integration points — where and how libraries connect in this specific codebase.
+
+## 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 integration architect operating in Ferris Architect mode
+- ✅ Zero hallucination — only document integrations evidenced in actual code
+- ✅ Every integration pattern must cite co-import files with file:line references
+
+### Step-Specific Rules:
+
+- 🎯 Focus on detecting cross-library patterns using Pattern 1 (grep) subprocess
+- 🚫 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
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load integration-patterns.md for detection rules
+- 💾 Store integration_graph as workflow state
+- 📖 Auto-proceed to step 06 after detection complete
+- 🚫 Graceful handling if no integrations detected
+
+## CONTEXT BOUNDARIES:
+
+- From step 03: confirmed_dependencies[] with file lists per library
+- 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
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Generate Library Pairs
+
+From `confirmed_dependencies`, generate all unique pairs:
+- N libraries → N*(N-1)/2 pairs
+- Skip pairs where either library had extraction failure in step 04
+
+Report: "**Analyzing {pair_count} library pairs for integration patterns...**"
+
+### 2. Detect Co-Import Files
+
+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 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.
+
+**Threshold:** A pair must have 2+ co-import files to qualify as an integration pattern (single file co-imports may be incidental).
+
+### 3. Classify Integration Types
+
+Load `{integrationPatterns}` for classification rules.
+
+For each qualifying pair (2+ co-import files), analyze the co-import files to classify the integration type:
+
+- **Type 1: Middleware Chain** — Sequential function calls piping output between libraries
+- **Type 2: Shared Types** — Type definitions exchanged between libraries
+- **Type 3: Configuration Bridge** — One library configuring or initializing another
+- **Type 4: Event Handler** — Event patterns crossing library boundaries
+- **Type 5: Adapter/Wrapper** — Thin wrapper connecting library interfaces
+- **Type 6: State Sharing** — Shared state stores or context providers
+
+For each detected integration:
+- Identify the top 3 files demonstrating the pattern
+- Extract a brief description of how the libraries connect
+- Assign confidence: T1 if AST-verified, T1-low if source reading
+
+### 4. Build Integration Graph
+
+Assemble the integration graph:
+- **Nodes:** Confirmed libraries (with extraction data from step 04)
+- **Edges:** Detected integration pairs with type, file count, and description
+- Identify **hub libraries** (connected to 3+ other libraries)
+- Identify **cross-cutting patterns** (patterns spanning 3+ libraries)
+
+### 5. Display Integration Summary
+
+**If integrations detected:**
+
+"**Integration detection complete.**
+
+**Integration graph:** {lib_count} libraries, {pair_count} integration pairs
+
+**Hub libraries** (connected to 3+ others):
+{For each hub:} - **{library}** — integrates with {partner_list}
+
+**Detected integrations:**
+| Library A | Library B | Type | Co-import Files | Confidence |
+|-----------|-----------|------|-----------------|------------|
+| {name} | {name} | {type} | {count} | {tier} |
+
+{If cross-cutting patterns:}
+**Cross-cutting patterns:**
+- {description spanning 3+ libraries}
+
+**Proceeding to stack compilation...**"
+
+**If no integrations detected:**
+
+"**No co-import integration patterns detected** between confirmed libraries.
+
+The libraries in this project appear to operate independently. The stack skill will contain library summaries without an integration layer.
+
+**Proceeding to stack compilation...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All library pairs analyzed for co-imports
+- Integration types classified using pattern rules
+- Hub libraries and cross-cutting patterns identified
+- Integration graph built with confidence labels
+- Graceful handling of zero integrations (not a failure)
+- Auto-proceeded to step 06
+
+### ❌ SYSTEM FAILURE:
+
+- Fabricating integrations not evidenced in code
+- Not applying the 2+ file threshold for pairs
+- Starting to compile SKILL.md (step 06's job)
+- Treating zero integrations as a workflow failure (it's valid)
+
+**Master Rule:** Only document integrations that exist in actual code. Zero integrations is a valid result.

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

@@ -0,0 +1,160 @@
+---
+name: 'step-06-compile-stack'
+description: 'Compile SKILL.md with integration layer and present for user review'
+
+nextStepFile: './step-07-generate-output.md'
+stackSkillTemplate: '../data/stack-skill-template.md'
+---
+
+# Step 6: Compile Stack Skill
+
+## STEP GOAL:
+
+Assemble the main SKILL.md by combining per-library extractions with the integration layer, and present for user review before writing output files.
+
+## 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 integration architect operating in Ferris Architect mode
+- ✅ The integration layer is the VALUE — not just concatenated library docs
+- ✅ Zero hallucination — only include content backed by extraction evidence
+
+### Step-Specific Rules:
+
+- 🎯 Compile SKILL.md following the stack-skill-template structure
+- 🚫 FORBIDDEN to write output files — that is step 07
+- 💬 Present compiled content for user review (Gate 2)
+- 🎯 Integration patterns go FIRST — they are the primary value
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load stack-skill-template.md for section structure
+- 💾 Store compiled skill_content as workflow state
+- 📖 Wait for user review and approval before proceeding
+- 🚫 FORBIDDEN to proceed without user confirming the compilation
+
+## CONTEXT BOUNDARIES:
+
+- From step 04: per_library_extractions[] with exports, patterns, confidence
+- From step 05: integration_graph with pairs, types, hub libraries, cross-cutting patterns
+- This step produces: skill_content (compiled SKILL.md ready for writing)
+- User interaction: Gate 2 — compile checkpoint required
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Template Structure
+
+Load `{stackSkillTemplate}` and prepare SKILL.md section structure.
+
+### 2. Compile Integration Layer
+
+**This is the core value of the stack skill.** Compile in order:
+
+**Cross-cutting patterns** (if any):
+- Patterns spanning 3+ libraries
+- Middleware chains, shared configuration, common architectural patterns
+
+**Library pair integrations:**
+- For each detected integration pair from step 05:
+  - Type classification
+  - Pattern description with file:line citations
+  - Key files demonstrating the integration
+  - Confidence tier label
+
+**Hub library connections:**
+- For each hub library (3+ connections):
+  - Role in the stack architecture
+  - How it connects to partner libraries
+
+### 3. Compile Per-Library Sections
+
+For each confirmed library (ordered by integration connectivity, then import count):
+
+- Role in stack (one-line description)
+- Key exports used in this project
+- Usage patterns from extraction
+- Confidence tier label
+- Link to reference file: `./references/{library}.md`
+
+### 4. Compile Project Conventions
+
+Extract project-specific conventions from the extractions:
+- Common initialization patterns
+- Error handling approaches across libraries
+- Configuration conventions
+- Import organization patterns
+
+### 5. Compile Library Reference Index
+
+Create the reference index table:
+
+| Library | Imports | Key Exports | Confidence | Reference |
+|---------|---------|-------------|------------|-----------|
+| ... | ... | ... | ... | ... |
+
+### 6. Present Compiled SKILL.md Preview
+
+"**Stack skill compilation complete. Please review:**
+
+---
+
+{Display full compiled SKILL.md content}
+
+---
+
+**Compilation stats:**
+- **Libraries:** {count}
+- **Integration pairs:** {count}
+- **Cross-cutting patterns:** {count}
+- **Confidence:** T1: {count}, T1-low: {count}, T2: {count}
+
+**Please review the integration layer and per-library sections.**
+- Does the integration layer capture how your libraries connect?
+- Are the per-library summaries accurate?
+- Any sections to adjust before writing output?"
+
+### 7. Present MENU OPTIONS
+
+Display: **Select:** [C] Continue to Output Generation
+
+#### 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: Store skill_content, then load, read entire file, then execute {nextStepFile}
+- IF Any other: Process as feedback, adjust compilation, redisplay preview, then [Redisplay Menu Options](#7-present-menu-options)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- SKILL.md follows stack-skill-template structure
+- Integration layer presented FIRST (primary value)
+- All content includes confidence tier labels
+- Per-library sections ordered by connectivity
+- User reviewed and approved compilation
+- skill_content stored for step 07
+
+### ❌ SYSTEM FAILURE:
+
+- Integration layer missing or buried below library listings
+- Content without confidence tier labels
+- Proceeding without user review (Gate 2)
+- Writing files in this step (step 07's job)
+- Fabricating integration patterns not from step 05
+
+**Master Rule:** Integration layer is the value. Present it first, get user approval before writing.