bmad-module-skill-forge 0.6.0 → 0.7.0

package/src/workflows/refine-architecture/steps-c/step-02-gap-analysis.md

@@ -0,0 +1,179 @@
+---
+name: 'step-02-gap-analysis'
+description: 'Find undocumented integration paths that the architecture does not describe but skill APIs suggest'
+
+nextStepFile: './step-03-issue-detection.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 2: Gap Analysis
+
+## STEP GOAL:
+
+Find undocumented integration paths — library pairs that have compatible APIs (from the generated skills) but are not described in the architecture document. For each gap, document what APIs connect and propose an architecture section describing the 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 an architecture refinement analyst performing gap detection
+- ✅ Every gap must cite specific APIs from the generated skills — no speculation
+- ✅ Apply the gap detection rules from {refinementRulesData} strictly
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on undocumented integration paths (gaps)
+- 🚫 FORBIDDEN to detect contradictions or issues — that is Step 03
+- 🚫 FORBIDDEN to suggest capability expansions or improvements — that is Step 04
+- 💬 Every gap MUST include evidence citations from actual skill content
+
+## EXECUTION PROTOCOLS:
+
+- Load refinement rules for gap detection criteria
+- Extract integration claims from architecture document using prose co-mention analysis
+- Generate all possible library pairs and cross-reference against architecture
+- Append gap analysis findings as workflow state for Step 05
+- Only gap detection — no issue detection, no improvement suggestions
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory from Step 01, SKILL.md and metadata.json files, refinement rules
+- Focus: Finding library pairs with compatible APIs that the architecture does not describe
+- Limits: Only detect gaps — do not flag issues or suggest improvements
+- 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. Reference Refinement Rules
+
+Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+
+Extract: gap classification (Missing Integration Path, Undocumented Data Flow, Absent Bridge Layer), detection method, and citation format.
+
+### 2. Extract Integration Claims from Architecture
+
+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", "feeds into", "receives from"
+- 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.
+
+**Mermaid Limitation Warning:** If `` ```mermaid `` blocks are present in the architecture document, inform the user: "Integration paths documented exclusively in Mermaid diagrams are excluded from co-mention analysis and may appear as false-positive gaps. Consider adding prose descriptions for diagram-only integration paths." Display this warning informatively and immediately continue — this does not halt or modify the analysis sequence.
+
+**Build documented pairs list:**
+- Each pair: `{library_a, library_b, architectural_context}`
+- `architectural_context`: the quoted text or paraphrased description of their relationship
+
+### 3. Generate All Possible Library Pairs
+
+From the skill inventory, generate all unique combinations of library pairs.
+
+For N skills, this produces N*(N-1)/2 unique pairs.
+
+### 4. Load Skill API Surfaces for Cross-Reference
+
+For each library in the skill inventory, 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 count and names
+
+### 5. Cross-Reference: Identify Gaps
+
+For each possible library pair NOT already documented in the architecture:
+
+**Check API compatibility:**
+- Does Library A export types or data that Library B can consume?
+- Do both libraries share a compatible protocol or data format?
+- Are they in the same language or is there a bridge mechanism available?
+
+**If compatible APIs exist but NO architecture mention:**
+- Classify the gap type (Missing Integration Path, Undocumented Data Flow, or Absent Bridge Layer)
+- Document the connecting APIs from both skills
+- Propose a brief architecture section describing the integration
+
+**Apply the citation format from {refinementRulesData}:**
+```
+**[GAP]**: {description}
+
+Evidence:
+- {skill_a} exports: `{function}({params}) -> {return_type}`
+- {skill_b} accepts: `{function}({params})`
+- Compatibility: {explanation}
+
+Suggestion: {proposed architecture section content}
+```
+
+**If no compatible APIs:** Skip this pair — not all pairs need to integrate.
+
+### 6. Display Gap Analysis Results
+
+"**Pass 1: Gap Analysis — Undocumented Integration Paths**
+
+**Gaps Found:** {count}
+
+{IF gaps found:}
+| # | Library A | Library B | Gap Type | Connecting APIs |
+|---|-----------|-----------|----------|-----------------|
+| {n} | {lib_a} | {lib_b} | {gap_type} | {brief API description} |
+
+{For each gap, display the full citation with evidence and suggestion}
+
+{IF no gaps found AND N > 1:}
+**No undocumented integration paths detected.** The architecture document covers all compatible library pairs.
+
+{IF no gaps found AND N == 1:}
+**⚠️ Gap analysis skipped — only 1 skill loaded.** Pairwise integration analysis requires at least 2 skills. If the architecture references multiple libraries, those without a matching skill are invisible to gap analysis. **Recommendation:** Generate skills for all architecture libraries with [CS] or [QS] before running [RA] for comprehensive gap detection.
+
+**Proceeding to issue detection (still produces value with 1 skill)...**"
+
+Store all gap findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-GAPS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted gap findings** (full citation blocks with evidence and suggestions, not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+
+### 7. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refinement rules loaded from {refinementRulesData}
+- Integration claims extracted from architecture document using prose co-mention analysis
+- All possible library pairs generated from skill inventory
+- Skill API surfaces loaded for cross-reference
+- Each gap includes evidence citations from actual skill content
+- Gap analysis results displayed with count and details
+- Gap findings stored as workflow state for Step 05
+- Auto-proceeded to step 03
+
+### ❌ SYSTEM FAILURE:
+
+- Inventing APIs not present in the actual skills
+- Flagging contradictions or issues (that is Step 03)
+- Suggesting capability improvements (that is Step 04)
+- Gaps without evidence citations from generated skills
+- Parsing Mermaid diagrams instead of using prose-based co-mention analysis
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/steps-c/step-03-issue-detection.md

@@ -0,0 +1,182 @@
+---
+name: 'step-03-issue-detection'
+description: 'Find contradictions between architecture claims and verified API reality from skills and optional VS report'
+
+nextStepFile: './step-04-improvements.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 3: Issue Detection
+
+## STEP GOAL:
+
+Find contradictions between what the architecture document claims and what the generated skills reveal about actual API surfaces. Detect language boundary issues not addressed, protocol mismatches assumed away, and missing bridge layers. If a VS feasibility report is available, incorporate RISKY and BLOCKED verdicts as confirmed issues.
+
+## 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 an architecture refinement analyst performing contradiction detection
+- ✅ Every issue must cite evidence from actual skill content AND the architecture claim it contradicts
+- ✅ Apply the issue detection rules from {refinementRulesData} strictly
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on contradictions between architecture claims and skill API reality
+- 🚫 FORBIDDEN to detect undocumented integration paths — that was Step 02
+- 🚫 FORBIDDEN to suggest capability expansions — that is Step 04
+- 💬 Every issue MUST cite both the architecture claim AND the contradicting skill evidence
+
+## EXECUTION PROTOCOLS:
+
+- Load refinement rules for issue detection criteria
+- Extract all integration claims from the architecture document
+- Verify each claim against skill API surfaces
+- Incorporate VS report verdicts if available
+- Append issue findings as workflow state for Step 05
+- Only issue detection — no gap analysis, no improvement suggestions
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory and SKILL.md files, VS feasibility report (if provided), refinement rules
+- Focus: Finding contradictions between documented claims and verified API reality
+- Limits: Only detect issues — do not fill gaps or suggest improvements
+- Dependencies: Step 01 (skill inventory, architecture doc, VS report status), Step 02 (gap analysis complete)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Reference Refinement Rules
+
+Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+
+Extract: issue classification (API Mismatch, Protocol Contradiction, Language Boundary Ignored, Type Incompatibility), VS report integration rules, and citation format.
+
+### 2. Extract Integration Claims from Architecture
+
+Parse the architecture document for specific claims about how technologies interact.
+
+**Claim types to extract:**
+- **API claims:** "Library X provides/exposes/exports {function/endpoint}"
+- **Protocol claims:** "Library X communicates via {protocol}"
+- **Data flow claims:** "Data flows from X to Y as {format}"
+- **Integration claims:** "X and Y integrate through {mechanism}"
+- **Capability claims:** "Library X handles {capability}"
+
+For each claim, record:
+- The exact text or paraphrase from the architecture
+- The section where it appears
+- The libraries referenced
+
+### 3. Verify Claims Against Skill API Surfaces
+
+For each extracted claim, load the relevant skill(s) and check:
+
+**API Mismatch check:**
+- Does the claimed API actually exist in the skill's export list?
+- Does the function signature match what the architecture describes?
+- If the architecture describes an API that does not appear in the skill: flag as issue
+
+**Protocol Contradiction check:**
+- Does the skill document the protocol the architecture assumes?
+- If the architecture claims gRPC but the skill shows HTTP-only: flag as issue
+
+**Language Boundary check:**
+- If two libraries are in different languages, does the architecture describe a bridge mechanism?
+- If the architecture assumes direct calls across language boundaries without FFI/IPC: flag as issue
+
+**Type Incompatibility check:**
+- Does the architecture assume type compatibility that the skills contradict?
+- If Library A exports Type X but the architecture claims Library B consumes it, and Library B expects Type Y: flag as issue
+
+### 4. Incorporate VS Report (If Available)
+
+If `vs_report_available` is true:
+
+**Load the VS feasibility report and extract verdicts:**
+- **Risky verdicts** (match case-insensitively: "Risky", "RISKY", "risky"): Promote to confirmed issues with the VS evidence as additional citation
+- **Blocked verdicts** (match case-insensitively: "Blocked", "BLOCKED", "blocked"): Promote to critical issues requiring architecture redesign
+- **Plausible verdicts:** Note informatively — Plausible is not an issue by itself. Only flag as a potential issue if the VS rationale text explicitly states "no direct API evidence" or "weak evidence"
+
+**For each VS-sourced issue, include dual citations:**
+- Evidence from the skill content
+- Verdict and rationale from the VS report
+
+If `vs_report_available` is false: Skip this section. Issue detection proceeds with skill data only.
+
+### 5. Document Each Issue
+
+For each detected issue, apply the citation format from {refinementRulesData}:
+
+```
+**[ISSUE]**: {description}
+
+Architecture states: "{quoted claim from original document}" (Section: {section_name})
+Skill reality: {skill_name} exports: `{actual_api}` — {explanation of contradiction}
+{IF VS report}: VS verdict: {Risky|Blocked} for {pair} — {VS rationale}
+
+Suggestion: {specific correction with API evidence}
+```
+
+**Severity classification:**
+- **Critical:** Blocked VS verdicts, fundamental language barriers with no bridge
+- **Major:** Risky VS verdicts, protocol mismatches, missing bridge layers
+- **Minor:** Plausible VS verdicts where the VS rationale explicitly states "no direct API evidence" or "weak evidence", minor type differences with easy conversion
+
+### 6. Display Issue Detection Results
+
+"**Pass 2: Issue Detection — Architecture vs. API Reality**
+
+**Issues Found:** {count} ({critical_count} critical, {major_count} major, {minor_count} minor)
+
+{IF issues found:}
+| # | Libraries | Issue Type | Severity | Summary |
+|---|-----------|-----------|----------|---------|
+| {n} | {libs} | {issue_type} | {severity} | {brief description} |
+
+{For each issue, display the full citation with evidence and suggestion}
+
+{IF no issues found:}
+**No contradictions detected.** Architecture claims align with verified skill API surfaces.
+
+**Proceeding to improvement detection...**"
+
+Store all issue findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-ISSUES] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted issue findings** (full citation blocks with architecture claims, skill evidence, VS verdicts, severity, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+
+### 7. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refinement rules loaded from {refinementRulesData}
+- All integration claims extracted from architecture document
+- Each claim verified against actual skill API surfaces
+- VS report verdicts incorporated if report was provided
+- Every issue includes both architecture citation AND contradicting skill evidence
+- Issues classified by severity (Critical, Major, Minor)
+- Issue detection results displayed with count and details
+- Issue findings stored as workflow state for Step 05
+- Auto-proceeded to step 04
+
+### ❌ SYSTEM FAILURE:
+
+- Issues without evidence from actual skills (speculation)
+- Not citing the architecture claim that is contradicted
+- Filling gaps (that was Step 02) or suggesting improvements (that is Step 04)
+- Ignoring VS report verdicts when the report was provided
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/steps-c/step-04-improvements.md

@@ -0,0 +1,169 @@
+---
+name: 'step-04-improvements'
+description: 'Suggest capability expansions from skill data not leveraged in the architecture'
+
+nextStepFile: './step-05-compile.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 4: Improvement Detection
+
+## STEP GOAL:
+
+Identify capability expansions — library features documented in the generated skills that the architecture does not leverage. Detect unused capabilities, cross-library synergies visible from skill API surfaces, and alternative patterns that could strengthen the architecture. For each improvement, document the capability and suggest how to incorporate it.
+
+## 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 an architecture refinement analyst identifying untapped capabilities
+- ✅ Every improvement must cite specific APIs from the generated skills — no speculation
+- ✅ Improvements are suggestions, not mandates — present them as optional enhancements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on capability expansions not leveraged in the architecture
+- 🚫 FORBIDDEN to detect gaps (Step 02) or issues (Step 03) — those are already captured
+- 🎯 Improvements are ADDITIVE suggestions — they enhance, not contradict, the architecture
+- 💬 Every improvement MUST include evidence citations from actual skill content
+
+## EXECUTION PROTOCOLS:
+
+- Load refinement rules for improvement detection criteria
+- Compare full skill API surfaces against architecture usage
+- Detect unused capabilities, cross-library synergies, and alternative patterns
+- Append improvement findings as workflow state for Step 05
+- Only improvement detection — no gap or issue analysis
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory and SKILL.md files, refinement rules
+- Focus: Finding capabilities in skills that the architecture does not use
+- Limits: Only detect improvements — do not re-detect gaps or issues from earlier steps
+- Dependencies: Step 01 (skill inventory), Steps 02-03 (complete — do not duplicate findings)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Reference Refinement Rules
+
+Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+
+Extract: improvement classification (Unused Capability, Cross-Library Synergy, Alternative Pattern), detection method, and citation format.
+
+### 2. Build Architecture Usage Map
+
+For each library referenced in the architecture document, extract how it is used:
+
+- What capabilities are described (e.g., "Loro for real-time data sync")
+- What APIs or features are referenced
+- What role it plays in the architecture
+
+This creates a map of `{library} -> {described_usage[]}` for comparison against full skill API surfaces.
+
+### 3. Compare Skill API Surfaces Against Architecture Usage
+
+For each skill in the inventory:
+
+**Load the full API surface from SKILL.md:**
+- All exported functions with signatures
+- All exported types and interfaces
+- All documented capabilities and features
+- All protocol support indicators
+
+**Compare against the architecture usage map:**
+- Which exports does the architecture reference or imply usage of?
+- Which exports are NOT referenced in the architecture at all?
+
+**For each unreferenced capability:**
+- Evaluate relevance: would this capability strengthen the architecture?
+- Skip trivial or internal-only exports (utilities, helpers, debug functions)
+- Flag capabilities that could address architectural concerns or expand functionality
+
+### 4. Detect Cross-Library Synergies
+
+Examine pairs of skills for complementary capabilities not exploited in the architecture:
+
+- Does Library A export an event system that Library B could consume?
+- Does Library A produce a data format that Library B has an optimized processor for?
+- Do two libraries offer overlapping capabilities that could be unified?
+
+**Only flag synergies where both sides have documented APIs** — do not speculate about undocumented features.
+
+### 5. Document Each Improvement
+
+For each detected improvement, apply the citation format from {refinementRulesData}:
+
+```
+**[IMPROVEMENT]**: {description}
+
+Evidence:
+- {skill_name} exports: `{function}({params}) -> {return_type}`
+- Architecture uses: {what the architecture currently describes}
+- Untapped: {what the skill offers that the architecture does not mention}
+
+Suggestion: {how to incorporate this capability into the architecture}
+```
+
+**Categorize improvements:**
+- **High:** Capabilities that address known architectural concerns or significantly expand functionality
+- **Medium:** Capabilities that add convenience or efficiency improvements
+- **Low:** Capabilities that are nice-to-have but not impactful
+
+### 6. Display Improvement Suggestions
+
+"**Pass 3: Improvement Detection — Untapped Capabilities**
+
+**Improvements Found:** {count} ({high_count} high value, {medium_count} medium, {low_count} low)
+
+{IF improvements found:}
+| # | Library | Improvement Type | Value | Summary |
+|---|---------|-----------------|-------|---------|
+| {n} | {lib} | {type} | {value} | {brief description} |
+
+{For each improvement, display the full citation with evidence and suggestion}
+
+{IF no improvements found:}
+**No untapped capabilities detected.** The architecture fully leverages the skill API surfaces.
+
+**Proceeding to compile refined architecture...**"
+
+Store all improvement findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-IMPROVEMENTS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted improvement findings** (full citation blocks with evidence, value ratings, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+
+### 7. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refinement rules loaded from {refinementRulesData}
+- Architecture usage map built for each referenced library
+- Full skill API surfaces compared against architecture usage
+- Cross-library synergies checked for complementary capabilities
+- Every improvement includes evidence citations from actual skill content
+- Improvements categorized by value (High, Medium, Low)
+- Improvement results displayed with count and details
+- Improvement findings stored as workflow state for Step 05
+- Auto-proceeded to step 05
+
+### ❌ SYSTEM FAILURE:
+
+- Improvements without evidence from actual skills (speculation)
+- Re-detecting gaps (Step 02) or issues (Step 03)
+- Presenting trivial internal-only exports as improvements
+- Not categorizing improvements by value
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.