bmad-module-skill-forge 0.2.0

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

@@ -0,0 +1,52 @@
+---
+name: create-skill
+description: Compile a skill from a brief. Supports --batch for multiple briefs.
+web_bundle: true
+---
+
+# Create Skill
+
+**Goal:** Compile a verified agent skill from a skill-brief.yaml and source code, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references.
+
+**Your Role:** You are a skill compilation engine performing structural extraction and assembly. This workflow is mostly autonomous with two strategic confirmation gates — one after ecosystem check (if a match is found) and one after source extraction (to confirm findings before compilation). All other steps auto-proceed. Apply zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation.
+
+## WORKFLOW ARCHITECTURE
+
+### 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
+- **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
+- **Tier-Aware Execution**: Steps adapt behavior based on forge tier (Quick/Forge/Deep) loaded from sidecar at init
+- **Zero Hallucination**: Every claim requires a provenance citation — uncitable content is excluded, not guessed
+
+### 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**: At confirmation gates (steps 02 and 03), halt and wait for user selection
+4. **AUTO-PROCEED**: All other steps proceed to the next automatically after completion
+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
+- 📋 **NEVER** create mental todo lists from future steps
+- ⚒️ **NEVER** include content in SKILL.md that cannot be cited to source code
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+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`
+
+### 2. First Step Execution
+
+Load, read the full file and then execute ./steps-c/step-01-load-brief.md to begin the workflow.

package/src/workflows/create-stack-skill/data/integration-patterns.md

@@ -0,0 +1,61 @@
+# Integration Pattern Detection Rules
+
+## Co-Import Detection
+
+A co-import is detected when two or more confirmed libraries are imported in the same source file.
+
+### Detection Method
+
+1. For each file in the codebase, extract all import statements
+2. Map imports to confirmed library list
+3. If a file imports 2+ confirmed libraries → co-import detected
+4. Record: file path, library pair, line numbers
+
+### Minimum Threshold
+
+- A library pair must co-appear in **2+ files** to qualify as an integration pattern
+- Single file co-imports may be incidental
+
+## Integration Pattern Types
+
+### Type 1: Middleware Chain
+Libraries connected in a processing pipeline.
+- **Signal:** Sequential function calls passing output of one library to another
+- **Example:** `express` + `cors` — cors middleware registered on express app
+
+### Type 2: Shared Types
+Libraries exchanging type definitions or data structures.
+- **Signal:** Type imports from one library used as parameters/returns in another
+- **Example:** `react` + `react-router` — Router components accepting React elements
+
+### Type 3: Configuration Bridge
+One library configuring or initializing another.
+- **Signal:** Config objects or initialization calls referencing both libraries
+- **Example:** `next` + `tailwindcss` — Tailwind configured via next.config
+
+### Type 4: Event Handler
+Libraries connected through event emission/handling patterns.
+- **Signal:** Event listeners from one library triggering actions in another
+- **Example:** `socket.io` + `redis` — Redis pub/sub driving socket events
+
+### Type 5: Adapter/Wrapper
+One library wrapping another to provide a unified interface.
+- **Signal:** Thin wrapper functions delegating to underlying library
+- **Example:** `prisma` + `zod` — Zod schemas validating Prisma model inputs
+
+### Type 6: State Sharing
+Libraries sharing application state or context.
+- **Signal:** Shared state stores, context providers, or global singletons
+- **Example:** `react` + `zustand` — Zustand stores consumed in React components
+
+## Output Format
+
+For each detected integration:
+```
+Library A + Library B
+  Type: [pattern type]
+  Files: [count] files with co-imports
+  Key files: [top 3 files by integration density]
+  Pattern: [brief description of how they integrate]
+  Confidence: [T1/T1-low based on detection method]
+```

package/src/workflows/create-stack-skill/data/manifest-patterns.md

@@ -0,0 +1,35 @@
+# Manifest Detection Patterns
+
+## Supported Ecosystems
+
+| Ecosystem | Manifest File(s) | Dependency Key | Import Pattern |
+|-----------|-----------------|----------------|----------------|
+| JavaScript/TypeScript | package.json | dependencies, devDependencies | `import ... from '...'`, `require('...')` |
+| Python | requirements.txt, setup.py, pyproject.toml, Pipfile | install_requires, [project.dependencies] | `import ...`, `from ... import` |
+| Rust | Cargo.toml | [dependencies] | `use ...`, `extern crate` |
+| Go | go.mod | require | `import "..."` |
+| Java | pom.xml, build.gradle | dependencies | `import ...` |
+| Ruby | Gemfile | gem | `require '...'`, `require_relative` |
+| PHP | composer.json | require, require-dev | `use ...`, `require_once` |
+| .NET | *.csproj | PackageReference | `using ...` |
+
+## Detection Priority
+
+1. Search project root for manifest files (depth 0-1)
+2. Parse each found manifest to extract dependency names
+3. Normalize names across ecosystems (e.g., `@scope/package` → `package`)
+4. Deduplicate across multiple manifests
+
+## Filtering Rules
+
+- Exclude dev-only dependencies unless they appear in production imports
+- Exclude build tools (webpack, babel, eslint, etc.) unless significantly imported
+- Include all runtime dependencies by default
+- Flag transitive dependencies that appear in direct imports
+
+## Import Counting
+
+For each dependency, count distinct files that import it:
+- Use grep patterns from Import Pattern column
+- Count unique file paths, not total import statements
+- Exclude test files, config files, and build artifacts from count

package/src/workflows/create-stack-skill/data/stack-skill-template.md

@@ -0,0 +1,110 @@
+# Stack Skill Template
+
+## SKILL.md Section Structure
+
+```markdown
+# {project_name} Stack Skill
+
+> {lib_count} libraries | {integration_count} integration patterns | Forge tier: {tier}
+
+## Integration Patterns
+
+### Cross-Cutting Patterns
+[Patterns that span 3+ libraries — middleware chains, shared config, etc.]
+
+### Library Pair Integrations
+[For each detected integration pair:]
+#### {LibraryA} + {LibraryB}
+**Type:** {pattern_type}
+**Pattern:** {description}
+**Key files:** {file_list}
+**Confidence:** {T1/T1-low/T2}
+
+## Library Reference Index
+
+| Library | Imports | Key Exports | Confidence | Reference |
+|---------|---------|-------------|------------|-----------|
+| {name} | {count} | {top_exports} | {tier} | [ref](./references/{name}.md) |
+
+## Per-Library Summaries
+
+### {library_name}
+**Role in stack:** {one-line description of what this library does in this project}
+**Key exports used:** {comma-separated list}
+**Usage pattern:** {brief pattern description}
+**Confidence:** {T1/T1-low/T2}
+
+## Conventions
+
+[Project-specific conventions for library usage:]
+- {convention_1}
+- {convention_2}
+```
+
+## context-snippet.md Format (ADR-L)
+
+Two-line format per library, targeting ~30 tokens per entry:
+
+```markdown
+**{library}** ({import_count} imports): {top_3_exports}
+  → integrates with: {comma-separated integration partners}
+```
+
+## metadata.json Structure
+
+```json
+{
+  "skill_type": "stack",
+  "skill_name": "{project}-stack",
+  "version": "1.0.0",
+  "created": "{date}",
+  "forge_tier": "{Quick|Forge|Deep}",
+  "library_count": 0,
+  "integration_count": 0,
+  "libraries": ["lib1", "lib2"],
+  "integration_pairs": [["lib1", "lib2"]],
+  "confidence_distribution": {
+    "T1": 0,
+    "T1-low": 0,
+    "T2": 0
+  }
+}
+```
+
+## references/{library}.md Structure
+
+```markdown
+# {library_name} Reference
+
+**Version:** {version_from_manifest}
+**Import count:** {count} files
+**Confidence:** {T1/T1-low/T2}
+
+## Key Exports
+[Top exports used in this project with signatures]
+
+## Usage Patterns
+[How this library is typically used in this codebase]
+
+## Common Imports
+[Most frequent import statements]
+```
+
+## references/integrations/{pair}.md Structure
+
+```markdown
+# {LibraryA} + {LibraryB} Integration
+
+**Type:** {pattern_type}
+**Co-import files:** {count}
+**Confidence:** {T1/T1-low}
+
+## Integration Pattern
+[Detailed description of how these libraries connect]
+
+## Key Files
+[Files demonstrating the integration with line references]
+
+## Usage Convention
+[How this integration is typically structured in the project]
+```

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

@@ -0,0 +1,142 @@
+---
+name: 'step-01-init'
+description: 'Initialize stack skill workflow by loading forge tier and validating prerequisites'
+
+nextStepFile: './step-02-detect-manifests.md'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
+---
+
+# Step 1: Initialize
+
+## STEP GOAL:
+
+Load forge tier configuration, validate prerequisites, and prepare the stack skill workflow for execution.
+
+## 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 and integration architect operating in Ferris Architect mode
+- ✅ Execute with prescriptive precision — every finding must trace to actual code
+- ✅ Speed-first approach with zero hallucination
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading configuration and validating prerequisites
+- 🚫 FORBIDDEN to start detecting manifests or analyzing dependencies
+- 🚫 No A/P menu — this is an auto-proceed init step
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load forge tier and validate tools
+- 💾 Store tier, tools, and optional inputs as workflow state
+- 📖 Auto-proceed to next step after successful initialization
+- 🚫 HALT with actionable error if prerequisites missing
+
+## CONTEXT BOUNDARIES:
+
+- This is the first step — no prior workflow state exists
+- Requires setup-forge to have been completed (forge-tier.yaml)
+- User may provide optional explicit dependency list or scope overrides
+- No dependencies on brief-skill or create-skill outputs
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Forge Tier Configuration
+
+Load `{forgeTierFile}` from the Ferris sidecar.
+
+**If forge-tier.yaml does not exist:**
+
+"**Cannot proceed.** The setup-forge workflow has not been run for this project.
+
+**Required:** Run `setup-forge` first to detect available tools and determine your forge tier.
+
+**Halting workflow.**"
+
+STOP — do not proceed.
+
+**If forge-tier.yaml exists:**
+
+Extract:
+- `forge_tier` — Quick, Forge, or Deep
+- `available_tools` — list of detected tools (gh_bridge, ast_bridge, qmd_bridge, skills_ref)
+- `project_root` — project root path
+
+Check for `tier_override` in preferences.yaml if it exists.
+
+### 2. Validate Available Tools
+
+**Required for all tiers:**
+- File I/O capability (read project files)
+
+**Tier-dependent tools:**
+- **Quick:** gh_bridge (source reading) — graceful degradation to local file reading if unavailable
+- **Forge:** ast_bridge (ast-grep structural analysis) — required for Forge tier
+- **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
+
+Report tool availability. If a tier-required tool is missing, downgrade tier and note:
+
+"**Tier adjusted:** {original_tier} → {adjusted_tier} — {missing_tool} unavailable."
+
+### 3. Accept Optional Inputs
+
+Check if the user provided:
+
+**Explicit dependency list:**
+- If provided, store as `explicit_deps` and skip auto-detection in step 02
+- Format: comma-separated library names or a file path
+
+**Scope overrides:**
+- If provided, store as `scope_overrides` for use in step 03
+- Format: `library_name: include|exclude`
+
+If no optional inputs provided, auto-detection will be used.
+
+### 4. Display Initialization Summary
+
+"**Stack Skill Forge initialized.**
+
+**Project:** {project_name}
+**Forge Tier:** {tier_description}
+- Quick: Source reading and import counting
+- Forge: + AST-backed structural analysis
+- Deep: + Temporal integration evolution
+
+**Available Tools:** {tool_list}
+**Input Mode:** {auto-detect | explicit dependency list}
+
+**Proceeding to manifest detection...**"
+
+### 5. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Forge tier loaded and validated
+- Tool availability confirmed with tier adjustment if needed
+- Optional inputs accepted and stored
+- Initialization summary displayed with positive capability framing
+- Auto-proceeded to step 02
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without forge-tier.yaml
+- Not reporting tier adjustments when tools missing
+- Starting manifest detection in this step
+- Displaying A/P menu (this is auto-proceed)
+
+**Master Rule:** This step validates prerequisites and initializes state. No analysis, no detection, no extraction.

package/src/workflows/create-stack-skill/steps-c/step-02-detect-manifests.md

@@ -0,0 +1,145 @@
+---
+name: 'step-02-detect-manifests'
+description: 'Scan project for dependency manifests and extract raw dependency list'
+
+nextStepFile: './step-03-rank-and-confirm.md'
+manifestPatterns: '../data/manifest-patterns.md'
+---
+
+# Step 2: Detect Manifests
+
+## STEP GOAL:
+
+Scan the project root for dependency manifest files, parse each to extract dependency names and versions, and produce a raw dependency list for ranking.
+
+## 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 — report exactly what was found, nothing assumed
+- ✅ Zero hallucination — only list dependencies actually present in manifest files
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on finding and parsing manifest files
+- 🚫 FORBIDDEN to count imports or rank dependencies — that is step 03
+- 🚫 FORBIDDEN to extract library documentation — that is step 04
+- 💬 If explicit dependency list was provided in step 01, use it and skip detection
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load manifest-patterns.md for detection rules
+- 💾 Store manifests found and raw dependency list as workflow state
+- 📖 Auto-proceed to step 03 after successful detection
+- 🚫 HALT if no manifests found and no explicit list provided
+
+## CONTEXT BOUNDARIES:
+
+- From step 01: forge tier, available tools, optional explicit_deps, project_root
+- This step produces: manifests[], raw_dependencies[]
+- Does NOT rank, filter, or analyze — just detect and parse
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check for Explicit Dependency List
+
+**If `explicit_deps` was provided in step 01:**
+
+"**Using provided dependency list.** Skipping manifest auto-detection.
+
+**Dependencies:** {explicit_deps_count} libraries provided"
+
+Store the explicit list as `raw_dependencies` and skip to section 4.
+
+**If no explicit list:** Continue to section 2.
+
+### 2. Scan for Manifest Files
+
+Load `{manifestPatterns}` for supported ecosystem detection patterns.
+
+Scan the project root (depth 0-1) for manifest files:
+
+- Search for each supported manifest filename
+- Record: file path, ecosystem type, file size
+- Note any unusual structures (monorepo with multiple manifests, workspace configurations)
+
+**If no manifest files found:**
+
+"**No dependency manifests detected** in the project root.
+
+Searched for: package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile, composer.json, *.csproj
+
+**Options:**
+1. Provide an explicit dependency list
+2. Specify a different project root path
+3. Cancel workflow
+
+**Halting — please provide input.**"
+
+STOP — wait for user response.
+
+### 3. Parse Each Manifest
+
+For each discovered manifest file:
+
+1. Read the file contents
+2. Extract dependency names and version constraints using ecosystem-specific parsing:
+   - JSON manifests: parse dependencies/devDependencies keys
+   - TOML manifests: parse [dependencies] sections
+   - Text manifests: parse line-by-line (name==version or name>=version)
+   - XML manifests: parse dependency elements
+   - Gradle: parse implementation/api/compile declarations
+3. Categorize: runtime vs dev-only
+4. Normalize dependency names across ecosystems
+
+Deduplicate dependencies found across multiple manifests.
+
+### 4. Display Detection Summary
+
+"**Manifest detection complete.**
+
+**Manifests found:** {count}
+{For each manifest:}
+- `{file_path}` ({ecosystem}) — {dep_count} dependencies
+
+**Total unique dependencies:** {total_count}
+- Runtime: {runtime_count}
+- Dev-only: {dev_count}
+
+**Proceeding to dependency ranking...**"
+
+### 5. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All manifest files in project root detected
+- Each manifest parsed with dependency names extracted
+- Runtime vs dev-only categorization applied
+- Deduplication across multiple manifests completed
+- Detection summary displayed with accurate counts
+- Auto-proceeded to step 03
+
+### ❌ SYSTEM FAILURE:
+
+- Missing manifest files that exist in the project
+- Inventing dependencies not in manifest files
+- Starting to rank or analyze dependencies (step 03's job)
+- Not halting when no manifests found
+- Displaying A/P menu (this is auto-proceed)
+
+**Master Rule:** Detect and parse only. No ranking, no filtering, no analysis.