bmad-module-skill-forge 0.6.0 → 0.7.1

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

@@ -0,0 +1,174 @@
+---
+name: 'step-01-init'
+description: 'Load generated skills from skills folder, accept architecture doc path and optional PRD path, validate all inputs exist'
+
+nextStepFile: './step-02-coverage.md'
+reportTemplate: '../data/feasibility-report-template.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 1: Initialize Verification
+
+## STEP GOAL:
+
+Load all generated skills from the skills output folder, accept the architecture document path (required) and optional PRD/vision document path from the user, validate that all inputs exist and are readable, create the feasibility report document, and present an initialization summary before auto-proceeding.
+
+## 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 stack verification analyst operating in Ferris Audit mode
+- ✅ Execute with prescriptive precision — every loaded skill must be validated against actual files
+- ✅ You enforce the zero-hallucination principle: only report skills that physically exist on disk
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading inputs, scanning skills, and creating the report skeleton
+- 🚫 FORBIDDEN to perform any coverage analysis or integration checking
+- 🚫 Auto-proceed init step — no user confirmation needed. Halts only on validation errors
+- 💬 Present a clear initialization summary so downstream steps have validated inputs
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Collect and validate all input documents and skill artifacts
+- 💾 Create feasibility report from {reportTemplate} with populated frontmatter
+- 📖 Auto-proceed to next step after successful initialization
+- 🚫 HALT with actionable error if minimum requirements not met
+
+## CONTEXT BOUNDARIES:
+
+- This is the first step — no prior workflow state exists
+- Requires skills to have been generated by create-skill or quick-skill workflows
+- User provides architecture document path (required) and optional PRD/vision document path
+- No dependency on setup-forge or forge-tier — this workflow operates on skill content only
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Accept Input Documents
+
+"**Verify Stack — Feasibility Analysis**
+
+Please provide the following:
+1. **Architecture document path** (REQUIRED) — your project's architecture doc
+2. **PRD or vision document path** (OPTIONAL) — for requirements coverage analysis
+3. **Previous feasibility report path** (OPTIONAL) — for delta comparison with a prior run (provide a backup copy)"
+
+Wait for user input.
+
+**Validate architecture document:**
+- Confirm the file exists and is readable
+- If missing or unreadable → "Architecture document not found at `{path}`. Provide a valid path."
+- HALT until a valid architecture document is provided
+
+**Validate PRD document (if provided):**
+- Confirm the file exists and is readable
+- If missing → "PRD document not found at `{path}`. Proceeding without PRD — requirements pass will be skipped."
+- Store PRD availability as `prd_available: true|false`
+
+**Validate previous report (if provided):**
+- Confirm the file exists and is readable
+- **Collision check:** Resolve both the provided path and `{outputFile}` to their absolute form before comparing (do not rely on string equality alone). If they resolve to the same location, warn: "The previous report path points to the same location as the new report. This file will be overwritten during this run. Provide a path to a backup copy, or leave empty to skip delta comparison." HALT until resolved.
+- If missing → "Previous report not found at `{path}`. Proceeding without delta comparison."
+- Store as `previous_report: {path}` (or empty string if not provided)
+
+### 2. Scan Skills Folder
+
+Read the `{skills_output_folder}` directory.
+
+For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+
+**For each valid skill directory, extract from metadata.json:**
+- `name` — skill name
+- `language` — primary language
+- `confidence_tier` — Quick, Forge, Forge+, or Deep
+- `exports_documented` — read from `stats.exports_documented` in metadata.json (count of documented exports)
+- `source_repo` or `source_root` — original source repository
+
+**Build a skill inventory** as an internal list of all loaded skills with the fields above.
+
+**If a subdirectory lacks SKILL.md or metadata.json:**
+- Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
+- Do not include in inventory
+
+### 3. Validate Minimum Requirements
+
+**Check skill count:**
+- At least 2 valid skills must exist (a stack requires multiple libraries)
+- If fewer than 2 → "**Cannot proceed.** Only {count} skill(s) found in `{skills_output_folder}`. A stack requires at least 2 skills. Generate more skills with [CS] Create Skill or [QS] Quick Skill, then re-run [VS]."
+- HALT workflow
+
+**Check forge_data_folder:**
+- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty → "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Re-run [SF] Setup Forge to initialize."
+- HALT workflow
+
+**Check architecture document:**
+- Confirm it was loaded successfully in section 1
+- If not → HALT with error (should not reach here if section 1 validation passed)
+
+### 4. Create Feasibility Report
+
+Load `{reportTemplate}` and create the output file at `{outputFile}`.
+
+**Populate frontmatter:**
+- `project_name`, `date`, `architecture_doc`, `prd_doc` (or "none")
+- `prd_available: true|false` (from section 1 validation)
+- `previous_report: {path}` (or empty string if not provided)
+- `skills_analyzed: {count}`
+- `overall_verdict: "pending"`
+- `stepsCompleted: ['step-01-init']`
+
+### 5. Display Initialization Summary
+
+"**Stack Verification Initialized**
+
+| Field | Value |
+|-------|-------|
+| **Skills Loaded** | {count} |
+| **Architecture Doc** | {architecture_doc} |
+| **PRD Document** | {prd_doc or 'Not provided — requirements pass will be skipped'} |
+| **Previous Report** | {previous_report or 'Not provided — no delta comparison'} |
+
+**Skill Inventory:**
+
+| Skill | Language | Tier | Exports |
+|-------|----------|------|---------|
+| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+
+**Proceeding to coverage analysis...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Architecture document loaded and validated
+- PRD document loaded or absence recorded
+- Skills folder scanned with SKILL.md and metadata.json validation per skill
+- At least 2 valid skills in inventory
+- Feasibility report created from template with populated frontmatter
+- Initialization summary displayed with skill inventory table
+- Auto-proceeded to step 02
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with fewer than 2 skills
+- Proceeding without a valid architecture document
+- Not validating SKILL.md and metadata.json existence per skill directory
+- Performing coverage or integration analysis in this step
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** This step validates inputs and initializes state. No analysis, no comparison, no verdicts.

package/src/workflows/verify-stack/steps-c/step-02-coverage.md

@@ -0,0 +1,181 @@
+---
+name: 'step-02-coverage'
+description: 'Pass 1 — check that a generated skill exists for every technology referenced in the architecture document'
+
+nextStepFile: './step-03-integrations.md'
+coveragePatternsData: '../data/coverage-patterns.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 2: Technology Coverage Analysis
+
+## STEP GOAL:
+
+Verify that a generated skill exists for every technology, library, or framework referenced in the architecture document. Produce a coverage matrix showing which technologies are covered and which are missing. Detect extra skills not referenced in the architecture.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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 stack verification analyst performing coverage analysis
+- ✅ Every technology reference must trace to actual text in the architecture document
+- ✅ Matching must be precise — do not guess or infer technologies not explicitly mentioned
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on technology-to-skill coverage mapping
+- 🚫 FORBIDDEN to analyze API surfaces or integration compatibility — that is Step 03
+- 🚫 FORBIDDEN to evaluate requirements — that is Step 04
+- 💬 Coverage verdicts must be binary: Covered or Missing — no ambiguity
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract technology references from architecture document using {coveragePatternsData}
+- 💾 Build and display coverage matrix with Covered/Missing verdicts
+- 📖 Append Coverage Matrix section to {outputFile}
+- 🚫 Only coverage mapping — no integration analysis, no requirements checking
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory from Step 01, coverage patterns data
+- Focus: Technology-to-skill matching only
+- Limits: Do not read SKILL.md in detail — use metadata.json for name and source_repo matching only
+- Dependencies: Step 01 must have loaded skill inventory and validated architecture document
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Coverage Patterns
+
+Load `{coveragePatternsData}` for detection rules.
+
+Extract: technology name patterns, section heading indicators, common aliases, and framework-to-library mappings.
+
+### 2. Extract Technology References
+
+Parse the architecture document for technology, library, and framework names.
+
+**Detection methods (apply in order):**
+
+**Section-based detection:**
+- Identify section headings that indicate technology listings (e.g., "Tech Stack", "Dependencies", "Technologies", "Libraries", layer-specific headings)
+- Extract technology names listed under these headings
+
+**Direct name matching:**
+- Scan the full document for names that match loaded skill names (case-insensitive)
+- Apply alias resolution from {coveragePatternsData} (e.g., "React" matches "react", "PostgreSQL" matches "postgres")
+
+**Contextual detection:**
+- Identify technology names mentioned in prose alongside architectural descriptions
+- Look for version-pinned references (e.g., "Express v4", "Tailwind CSS 3.x")
+
+**Build a deduplicated list** of all referenced technologies with the document section where each was found.
+
+### 3. Cross-Reference Against Skills
+
+For each referenced technology in the list:
+
+**Check if a matching skill exists** in the skill inventory from Step 01.
+- Match by skill name (case-insensitive)
+- Match by alias from {coveragePatternsData}
+- Match by `source_repo` or `source_root` field in metadata.json if skill name differs from technology name
+
+**Assign verdict:**
+- **Covered** — a matching skill exists in the inventory
+- **Missing** — no matching skill found
+
+Build the coverage matrix as a structured table.
+
+### 4. Detect Extra Skills
+
+Check if any skills in the inventory are NOT referenced in the architecture document.
+
+**For each extra skill:**
+- Mark as **Extra** (informational — not an error)
+- Note: "Skill `{skill_name}` exists but is not referenced in the architecture document"
+
+Extra skills are informational only. They do not affect the coverage verdict.
+
+### 5. Display Coverage Results
+
+"**Pass 1: Technology Coverage**
+
+| Technology | Source Section | Skill Match | Verdict |
+|------------|---------------|-------------|---------|
+| {tech_name} | {section_heading} | {skill_name or '—'} | {Covered / Missing} |
+
+**Coverage: {covered_count}/{total_count} ({percentage}%)**
+
+{IF 100% coverage AND no Extra skills:}
+**All referenced technologies have a matching skill. No extra skills detected.**
+
+{IF any Missing:}
+**Missing Skills — Action Required:**
+{For each missing technology:}
+- `{tech_name}` → Run **[CS] Create Skill** or **[QS] Quick Skill** for `{tech_name}`, then re-run **[VS]**
+
+{IF any Extra:}
+**Extra Skills (informational):**
+{For each extra skill:}
+- `{skill_name}` — not referenced in architecture document"
+
+### 6. Append to Report
+
+Write the **Coverage Matrix** section to `{outputFile}`:
+- Include the full coverage table
+- Include coverage percentage
+- Include missing skill recommendations
+- Include extra skills list
+- Update frontmatter: append `'step-02-coverage'` to `stepsCompleted`, set `coverage_percentage`
+
+### 7. Auto-Proceed to Next Step
+
+{IF coverage_percentage is 0%:}
+"**⚠️ 0% coverage — no matching skills found for any referenced technology.** All subsequent analysis (integration, requirements) will be vacuous and produce empty tables.
+
+**Recommended:** Generate skills with [CS] or [QS] for your architecture technologies, then re-run [VS].
+
+**Select:** [X] Halt workflow (recommended) | [C] Continue anyway"
+
+- IF X: "**Workflow halted.** Generate skills and re-run [VS] when ready." — END workflow
+- IF C: "**Continuing with 0% coverage — results will be limited.**"
+
+  Load, read the full file and then execute `{nextStepFile}`.
+
+{IF coverage_percentage is NOT 0%:}
+"**Proceeding to integration analysis...**"
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Coverage patterns loaded from {coveragePatternsData}
+- All technology references extracted from architecture document with section citations
+- Every referenced technology cross-referenced against skill inventory
+- Coverage matrix displayed with binary Covered/Missing verdicts
+- Extra skills detected and reported as informational
+- Missing skills have actionable recommendations (run [CS] or [QS])
+- Coverage Matrix section appended to {outputFile}
+- Auto-proceeded to step 03
+
+### ❌ SYSTEM FAILURE:
+
+- Inventing technologies not mentioned in the architecture document
+- Ambiguous verdicts (anything other than Covered or Missing)
+- Analyzing API surfaces or skill content in detail (that is Step 03)
+- Not providing actionable recommendations for missing skills
+- 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/verify-stack/steps-c/step-03-integrations.md

@@ -0,0 +1,195 @@
+---
+name: 'step-03-integrations'
+description: 'Pass 2 — cross-reference API surfaces between library pairs based on integration claims in the architecture document'
+
+nextStepFile: './step-04-requirements.md'
+integrationRulesData: '../data/integration-verification-rules.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 3: Integration Verification
+
+## STEP GOAL:
+
+Cross-reference API surfaces between library pairs that the architecture document claims work together. For each integration pair, verify language compatibility, protocol alignment, type compatibility, and documentation cross-references. Produce an evidence-backed verdict for each integration.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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 stack verification analyst performing integration feasibility analysis
+- ✅ Every verdict must cite evidence from the actual skill content — no speculation
+- ✅ Apply the verification protocol strictly — do not skip compatibility checks
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on integration pair verification using skill API surfaces
+- 🚫 FORBIDDEN to evaluate requirements coverage — that is Step 04
+- 🚫 FORBIDDEN to parse Mermaid diagrams — use prose-based co-mention analysis only
+- 💬 Every verdict MUST include evidence citations from the skills
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract integration claims from architecture document prose
+- 💾 Load skill API surfaces and cross-reference each integration pair
+- 📖 Append Integration Verdicts section to {outputFile}
+- 🚫 Only integration analysis — no requirements checking, no synthesis
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill SKILL.md and metadata.json files, integration verification rules
+- Focus: Pairwise integration compatibility between skills
+- Limits: Only verify pairs explicitly claimed in the architecture document — do not invent integration relationships
+- Dependencies: Step 01 (skill inventory), Step 02 (coverage matrix — only verify skills that exist)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Integration Verification Rules
+
+Load `{integrationRulesData}` for the cross-reference verification protocol.
+
+Extract: verification checks (language boundary, protocol compatibility, type compatibility, documentation cross-reference), verdict criteria, and evidence requirements.
+
+### 2. Extract Integration Claims
+
+Parse the architecture document for statements describing two or more technologies working together.
+
+**Detection method — prose-based co-mention analysis:**
+- Identify sentences or paragraphs where two or more technology names appear together
+- Look for integration verbs: "connects to", "communicates with", "wraps", "extends", "consumes", "produces", "bridges", "integrates with", "sits between"
+- Look for data flow descriptions: "{A} sends data to {B}", "{A} results are consumed by {B}"
+- Look for layer boundary descriptions: "{A} at the API layer connects to {B} at the data layer"
+
+**CRITICAL:** Do NOT parse Mermaid diagram syntax. Use only prose text for co-mention detection.
+
+**Build integration pairs list:**
+- Each pair: `{library_a, library_b, architectural_context}`
+- `architectural_context`: the quoted text or paraphrased description of their relationship
+
+**Filter:** Only include pairs where BOTH libraries have a corresponding skill (Covered in Step 02). Skip pairs involving Missing skills — they cannot be verified.
+
+### 3. Load Skill API Surfaces
+
+For each library in an integration pair, load the skill artifacts:
+
+**From SKILL.md, extract:**
+- Exported functions and their signatures
+- Exported types, interfaces, and classes
+- Protocol indicators (HTTP, gRPC, WebSocket, message queue, file I/O, IPC)
+- Data format indicators (JSON, protobuf, CSV, binary, streaming)
+
+**From metadata.json, extract:**
+- `language` — primary programming language
+- `exports` — export names array (populated for individual skills; empty for stack skills)
+- `stats.exports_documented` — export count
+- `confidence_tier` — extraction confidence level
+
+Store loaded API surfaces for cross-referencing.
+
+### 4. Cross-Reference Each Integration Pair
+
+For each integration pair `{library_a, library_b}`, apply the verification protocol from `{integrationRulesData}`:
+
+**Check 1 — Language Boundary:**
+- Same language → compatible
+- Different languages → check for FFI, IPC, or network protocol bridge
+- If no bridge mechanism documented → flag as risk
+
+**Check 2 — Protocol Compatibility:**
+- Both use same protocol (e.g., both HTTP) → compatible
+- Complementary protocols (e.g., HTTP client + HTTP server) → compatible
+- Incompatible protocols with no adapter → flag as risk
+
+**Check 3 — Type Compatibility:**
+- Shared types or compatible serialization formats → compatible
+- Incompatible type systems with no conversion layer → flag as risk
+
+**Check 4 — Documentation Cross-Reference:**
+- Skill A mentions skill B's library (or vice versa) → strong evidence
+- Neither skill mentions the other → weak evidence (plausible but unverified)
+
+**Assign verdict per pair:**
+- **Verified** — all checks pass with evidence from both skills
+- **Plausible** — checks pass but evidence is indirect or incomplete
+- **Risky** — one or more checks flag compatibility concerns
+- **Blocked** — fundamental incompatibility detected (language barrier with no bridge, incompatible protocols)
+
+**Each verdict MUST include:**
+- Which checks passed and which flagged
+- Evidence citations: specific exports, types, or protocol references from the skills
+
+### 5. Display Integration Results
+
+"**Pass 2: Integration Verification**
+
+| Library A | Library B | Context | Verdict | Evidence |
+|-----------|-----------|---------|---------|----------|
+| {lib_a} | {lib_b} | {brief context} | {Verified/Plausible/Risky/Blocked} | {key evidence} |
+
+**Summary:** {verified_count} Verified, {plausible_count} Plausible, {risky_count} Risky, {blocked_count} Blocked
+
+{IF zero integration pairs found:}
+**No integration claims detected in the architecture document prose.** Ensure your architecture document describes relationships between technologies in text form (not exclusively in Mermaid diagrams). Coverage-only analysis was performed.
+
+{IF any Risky:}
+**Risky Integrations — Recommendations:**
+{For each risky pair:}
+- `{lib_a}` ↔ `{lib_b}`: {specific concern}. **Recommendation:** {prescriptive action}
+
+{IF any Blocked:}
+**Blocked Integrations — Action Required:**
+{For each blocked pair:}
+- `{lib_a}` ↔ `{lib_b}`: {fundamental incompatibility}. **Recommendation:** {prescriptive action}"
+
+### 6. Append to Report
+
+Write the **Integration Verdicts** section to `{outputFile}`:
+- Include the full integration verdicts table with evidence
+- Include recommendations for Risky and Blocked pairs
+- Update frontmatter: append `'step-03-integrations'` to `stepsCompleted`
+- Set `integrations_verified`, `integrations_plausible`, `integrations_risky`, `integrations_blocked` counts
+
+### 7. Auto-Proceed to Next Step
+
+**Early halt guard:** If ALL integration pairs are Blocked, present: "**All integrations are Blocked** — fundamental incompatibilities detected across all library pairs. Remaining analysis will produce limited value. **[X] Halt workflow (recommended)** | **[C] Continue anyway**" — wait for user input. If X: halt with: "**Workflow halted — all integrations blocked.** Integration Verdicts saved to `{outputFile}`. Run **[VS]** after applying architectural changes. **Blocked integrations:** {list each blocked pair with reason}." If C: continue.
+
+{IF NOT halted (user selected C, or early halt guard did not trigger):}
+
+"**Proceeding to requirements verification...**"
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Integration rules loaded from {integrationRulesData}
+- Integration claims extracted from architecture document prose (not Mermaid diagrams)
+- Skill API surfaces loaded for each library in integration pairs
+- All four verification checks applied to each pair
+- Every verdict includes evidence citations from actual skill content
+- Recommendations provided for every Risky and Blocked integration
+- Integration Verdicts section appended to {outputFile}
+- Auto-proceeded to step 04
+
+### ❌ SYSTEM FAILURE:
+
+- Parsing Mermaid diagrams instead of using prose-based co-mention analysis
+- Verdicts without evidence citations from actual skills
+- Inventing integration relationships not described in the architecture document
+- Skipping any of the four verification checks
+- Evaluating requirements coverage (that is Step 04)
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.