bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/src/modules/bmb/workflows/workflow/data/step-type-patterns.md

@@ -0,0 +1,311 @@
+# Step Type Patterns
+
+**Purpose:** Templates for different step types.
+
+---
+
+## Core Step Structure
+
+All steps share this skeleton:
+```markdown
+---
+name: 'step-[N]-[name]'
+description: '[what it does]'
+[file references - relative path and only if used in this steps file]
+---
+
+# Step [N]: [Name]
+
+## STEP GOAL:
+[Single sentence goal]
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+### Universal Rules:
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read complete step file before action
+- 🔄 CRITICAL: When loading next with 'C', read entire file
+- 📋 YOU ARE A FACILITATOR, not content generator
+
+### Role Reinforcement:
+- ✅ You are [specific role]
+- ✅ Collaborative dialogue, not command-response
+- ✅ You bring [expertise], user brings [theirs]
+
+### Step-Specific Rules:
+- 🎯 Focus only on [specific task]
+- 🚫 FORBIDDEN to [prohibited action]
+- 💬 Approach: [how to engage]
+
+## EXECUTION PROTOCOLS:
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 [Additional protocol]
+- 📖 [Additional protocol]
+
+## CONTEXT BOUNDARIES:
+- Available context: [what's available]
+- Focus: [what to focus on]
+- Limits: [boundaries]
+- Dependencies: [what this depends on]
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. [First action]
+[Instructions]
+
+### N. Present MENU OPTIONS
+[Menu section - see menu-handling-standards.md]
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+### ✅ SUCCESS: [criteria]
+### ❌ SYSTEM FAILURE: [criteria]
+**Master Rule:** Skipping steps is FORBIDDEN.
+```
+
+---
+
+## Step Types
+
+### 1. Init Step (Non-Continuable)
+
+**Use:** Single-session workflow
+
+**Frontmatter:**
+```yaml
+---
+name: 'step-01-init'
+description: 'Initialize [workflow]'
+nextStepFile: './step-02-[name].md'
+outputFile: '{output_folder}/[output].md'
+templateFile: '../templates/[template].md'
+---
+```
+
+**Characteristics:**
+- No continuation detection
+- Auto-proceeds to step 2
+- No A/P menu
+- Creates output from template
+
+**Menu:** Auto-proceed (no user choice)
+
+### 2. Init Step (Continuable)
+
+**Use:** Multi-session workflow
+
+**Frontmatter:** Add `continueFile` reference
+```yaml
+continueFile: './step-01b-continue.md'
+```
+
+**Logic:**
+```markdown
+## 1. Check for Existing Workflow
+- Look for {outputFile}
+- If exists AND has stepsCompleted → STOP, load {continueFile}
+- If not exists → continue to setup
+```
+
+**Reference:** `step-01-init-continuable-template.md`
+
+### 3. Continuation Step (01b)
+
+**Use:** Paired with continuable init
+
+**Frontmatter:**
+```yaml
+---
+name: 'step-01b-continue'
+description: 'Handle workflow continuation'
+outputFile: '{output_folder}/[output].md'
+workflowFile: '{workflow_path}/workflow.md'
+---
+```
+
+**Logic:**
+1. Read `stepsCompleted` array from output
+2. Read last completed step file to find nextStep
+3. Welcome user back
+4. Route to appropriate step
+
+**Reference:** `step-1b-template.md`
+
+### 4. Middle Step (Standard)
+
+**Use:** Collaborative content generation
+
+**Frontmatter:**
+```yaml
+---
+name: 'step-[N]-[name]'
+nextStepFile: './step-[N+1]-[name].md'
+outputFile: '{output_folder}/[output].md'
+advancedElicitationTask: '{project-root}/.../advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/.../party-mode/workflow.md'
+---
+```
+
+**Menu:** A/P/C pattern
+
+### 5. Middle Step (Simple)
+
+**Use:** Data gathering, no refinement needed
+
+**Menu:** C only (no A/P)
+
+### 6. Branch Step
+
+**Use:** User choice determines next path
+
+**Frontmatter:**
+```yaml
+nextStepFile: './step-[default].md'
+altStepFile: './step-[alternate].md'
+```
+
+**Menu:** Custom letters (L/R/etc.) with branching logic
+
+### 7. Validation Sequence Step
+
+**Use:** Multiple checks without user interruption
+
+**Menu:** Auto-proceed to next validation
+
+**Pattern:**
+```markdown
+## 1. Perform validation check
+[Check logic]
+
+## 2. Write results to {outputFile}
+Append findings
+
+## 3. Proceed to next validation
+Display: "**Proceeding to next check...**"
+→ Immediately load {nextValidationStep}
+```
+
+### 8. Init Step (With Input Discovery)
+
+**Use:** Workflow that requires documents from prior workflows or external sources
+
+**Frontmatter:**
+```yaml
+---
+name: 'step-01-init'
+description: 'Initialize and discover input documents'
+inputDocuments: []
+requiredInputCount: 1
+moduleInputFolder: '{module_output_folder}'
+inputFilePatterns:
+  - '*-prd.md'
+  - '*-ux.md'
+---
+```
+
+**Characteristics:**
+- Discovers documents from prior workflows
+- Searches by folder, pattern, or user-provided paths
+- Validates inputs are complete
+- User confirms which documents to use
+- Auto-proceeds when required inputs found
+
+**Logic:**
+```markdown
+## 1. Discover Required Inputs
+Search {moduleInputFolder} for {inputFilePatterns}
+Search {project_folder}/docs/ for {inputFilePatterns}
+
+## 2. Present Findings
+"Found these documents:
+[1] prd-my-project.md (3 days ago) ✓
+[2] ux-research.md (1 week ago)
+Which would you like to use?"
+
+## 3. Validate and Load
+Check workflowType, stepsCompleted, date
+Load selected documents
+Add to {inputDocuments} array
+
+## 4. Auto-Proceed
+If all required inputs found → proceed to step 2
+If missing → Error with guidance
+```
+
+**Reference:** `input-discovery-standards.md`
+
+### 9. Final Polish Step
+
+**Use:** Optimizes document built section-by-section
+
+**Frontmatter:**
+```yaml
+---
+name: 'step-[N]-polish'
+description: 'Optimize and finalize document'
+outputFile: '{output_folder}/[document].md'
+---
+```
+
+**Characteristics:**
+- Loads entire document
+- Reviews for flow and coherence
+- Reduces duplication
+- Ensures proper ## Level 2 headers
+- Improves transitions
+- Keeps general order but optimizes readability
+
+**Logic:**
+```markdown
+## 1. Load Complete Document
+Read {outputFile} entirely
+
+## 2. Document Optimization
+Review entire document for:
+1. Flow and coherence
+2. Duplication (remove while preserving essential info)
+3. Proper ## Level 2 section headers
+4. Smooth transitions between sections
+5. Overall readability
+
+## 3. Optimize
+Make improvements while maintaining:
+- General order of sections
+- Essential information
+- User's voice and intent
+
+## 4. Final Output
+Save optimized document
+Mark workflow complete
+```
+
+**Use for:** Free-form output workflows (most document-producing workflows)
+
+### 10. Final Step
+
+**Use:** Last step, completion
+
+**Frontmatter:** No `nextStepFile`
+
+**Logic:**
+- Update frontmatter to mark workflow complete
+- Provide final summary
+- No next step
+
+---
+
+## Step Size Guidelines
+
+| Type                  | Recommended | Maximum |
+| --------------------- | ----------- | ------- |
+| Init                  | < 100       | 150     |
+| Init (with discovery) | < 150       | 200     |
+| Continuation          | < 150       | 200     |
+| Middle (simple)       | < 150       | 200     |
+| Middle (complex)      | < 200       | 250     |
+| Branch                | < 150       | 200     |
+| Validation sequence   | < 100       | 150     |
+| Final polish          | < 150       | 200     |
+| Final                 | < 150       | 200     |
+
+**If exceeded:** Split into multiple steps or extract to `/data/` files.

package/src/modules/bmb/workflows/workflow/data/subprocess-optimization-patterns.md

@@ -0,0 +1,386 @@
+# Subprocess Optimization Patterns
+
+**Purpose:** Context-saving and performance patterns for subprocess/subagent usage in BMAD workflows.
+
+---
+
+## Golden Rules
+
+1. **Subprocess when operations benefit from parallelization or context isolation**
+2. **Return ONLY findings to parent, not full file contents** (massive context savings)
+3. **Always provide graceful fallback** for LLMs without subprocess capability
+4. **Match pattern to operation type** - grep/regex, deep analysis, or data operations
+
+---
+
+## The Three Patterns
+
+### Pattern 1: Single Subprocess for Grep/Regex Across Many Files
+
+**Use when:** You can run one command across many files and just need matches/failures
+
+**Context savings:** Massive - returns only matching lines, not full file contents
+
+**Template:**
+```markdown
+**Launch a subprocess that:**
+
+1. Runs grep/regex across all target files
+2. Extracts only matching lines or failures
+3. Returns structured findings to parent
+
+```bash
+# Example: Find hardcoded paths across all files
+for file in steps-c/*.md; do
+  grep -n "{project-root}/" "$file" || echo "No matches in: $file"
+done
+```
+
+**Subprocess returns to parent:**
+```json
+{
+  "violations": [
+    {"file": "step-02.md", "line": 45, "match": "{project-root}/_bmad/bmb/..."}
+  ],
+  "summary": {"total_files_checked": 10, "violations_found": 3}
+}
+```
+
+**❌ BAD - Loads all files into parent:**
+```markdown
+"For EACH file, load the file and search for {project-root}/"
+# Parent context gets 10 full files × 200 lines = 2000 lines loaded
+```
+
+**✅ GOOD - Single subprocess returns only matches:**
+```markdown
+"Launch a subprocess to grep all files for {project-root}/, return only matches"
+# Parent context gets only matching lines = ~50 lines returned
+```
+
+---
+
+### Pattern 2: Separate Subprocess Per File for Deep Analysis
+
+**Use when:** You need to read and understand each file's prose, logic, quality, or flow
+
+**Context savings:** High - each subprocess returns analysis, not full content
+
+**Template:**
+```markdown
+**DO NOT BE LAZY - For EACH file, launch a subprocess that:**
+
+1. Loads that file
+2. Reads and analyzes content deeply (prose, logic, flow, quality)
+3. Returns structured analysis findings to parent for aggregation
+
+**Subprocess returns to parent:**
+```json
+{
+  "file": "step-03-inquiry.md",
+  "analysis": {
+    "instruction_style": "Intent-based ✅",
+    "collaborative_quality": "Good - asks 1-2 questions at a time",
+    "issues": ["Line 67: Laundry list of 7 questions detected"]
+  },
+  "optimization_opportunities": ["Could use Pattern 1 for menu validation checks"]
+}
+```
+
+**Example use cases:**
+- Instruction style validation (read prose, classify intent vs prescriptive)
+- Collaborative quality assessment (analyze question patterns)
+- Frontmatter compliance (check each variable is used)
+- Step type validation (verify step follows its type pattern)
+
+**❌ BAD - Parent loads all files:**
+```markdown
+"Load every step file and analyze its instruction style"
+# Parent context: 10 files × 200 lines = 2000 lines
+```
+
+**✅ GOOD - Per-file subprocess returns analysis:**
+```markdown
+"DO NOT BE LAZY - For EACH step file, launch a subprocess to analyze instruction style, return findings"
+# Parent context: 10 structured analysis objects = ~200 lines
+```
+
+---
+
+### Pattern 3: Subprocess for Data File Operations
+
+**Use when:** Loading reference data, finding fuzzy/best matches, summarizing key findings from large datasets
+
+**Context savings:** Massive - returns only matching rows or summaries, not entire data file
+
+**Template:**
+```markdown
+**Launch a subprocess that:**
+
+1. Loads the data file (reference docs, CSV, knowledge base)
+2. Performs lookup, matching, or summarization
+3. Returns ONLY relevant rows or key findings to parent
+
+**Subprocess returns to parent:**
+```json
+{
+  "matches": [
+    {"row": 42, "rule": "Frontmatter variables must be used in body", "applies": true},
+    {"row": 87, "rule": "Relative paths for same-folder refs", "applies": true}
+  ],
+  "summary": {"total_rules": 150, "applicable_rules": 2}
+}
+```
+
+**Example use cases:**
+- **Reference rules lookup**: Load 500-line standards file, return only applicable rules
+- **CSV fuzzy matching**: Load product database, find best matching category
+- **Document summarization**: Review 10 documents, extract only key requirements
+- **Knowledge base search**: Search large knowledge base, return only top matches
+
+**❌ BAD - Parent loads entire data file:**
+```markdown
+"Load {dataFile} with 500 rules and find applicable ones"
+# Parent context: All 500 rules loaded (5000+ lines)
+```
+
+**✅ GOOD - Subprocess returns only matches:**
+```markdown
+"Launch subprocess to load {dataFile}, find applicable rules, return only those"
+# Parent context: Only 2 applicable rules returned (~50 lines)
+```
+
+**Advanced example - Document review:**
+```markdown
+**Review 10 requirement documents to extract key details:**
+
+"DO NOT BE LAZY - For EACH document, launch a subprocess that:
+1. Loads that document
+2. Extracts key requirements, decisions, constraints
+3. Returns structured summary to parent
+
+**Subprocess returns:**
+```json
+{
+  "document": "prd-requirements.md",
+  "key_findings": {
+    "requirements": ["User auth", "Data export", "API integration"],
+    "decisions": ["Use JWT", "PostgreSQL", "REST API"],
+    "constraints": ["HIPAA compliant", "Max 100ms response"]
+  }
+}
+```
+
+# Parent gets summaries, not 10 full documents
+```
+
+---
+
+## Pattern 4: Parallel Execution Opportunities
+
+**Use when:** Multiple independent operations could run simultaneously
+
+**Performance gain:** Reduced total execution time via parallelization
+
+**Template:**
+```markdown
+**Launch subprocesses in parallel that:**
+
+1. Each subprocess handles one independent operation
+2. All subprocesses run simultaneously
+3. Parent aggregates results when all complete
+
+**Example:**
+```markdown
+# Instead of sequential (3× time):
+"Check frontmatter, then check menu, then check step types"
+
+# Use parallel (1× time):
+"Launch 3 subprocesses in parallel:
+- Subprocess 1: Check frontmatter compliance
+- Subprocess 2: Check menu compliance
+- Subprocess 3: Check step type compliance
+Aggregate all findings"
+```
+
+---
+
+## Graceful Fallback Pattern
+
+**CRITICAL:** Always ensure LLMs without subprocess capability can still execute
+
+**Universal Rule:**
+```markdown
+- ⚙️ 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
+```
+
+**Implementation:**
+```markdown
+### Step-Specific Rules:
+- 🎯 Use subprocess optimization when available - [pattern description]
+- 💬 If subprocess unavailable, perform operations in main thread
+
+### Execution:
+- LLMs with subprocess: Launch subprocess, aggregate findings
+- LLMs without subprocess: Perform same operations sequentially in main context
+```
+
+---
+
+## Return Pattern for Subprocesses
+
+**Subprocesses must either:**
+
+**Option A: Update report directly**
+```markdown
+"Subprocess loads validation report, appends findings, saves"
+# Parent doesn't need to aggregate
+```
+
+**Option B: Return structured findings to parent**
+```markdown
+"Subprocess returns JSON findings to parent for aggregation"
+# Parent compiles all subprocess results into report
+```
+
+**✅ GOOD - Structured return:**
+```json
+{
+  "file": "step-02.md",
+  "violations": ["..."],
+  "opportunities": ["..."],
+  "priority": "HIGH"
+}
+```
+
+**❌ BAD - Returns full content:**
+```markdown
+"Subprocess loads file and returns full content to parent"
+# Defeats purpose - parent gets full context anyway
+```
+
+---
+
+## When to Use Each Pattern
+
+| Pattern | Use When | Context Savings | Example |
+| -------- | -------- | --------------- | ------- |
+| **Pattern 1: Single subprocess for grep/regex** | Finding patterns across many files | Massive (1000:1 ratio) | Validate frontmatter across all steps |
+| **Pattern 2: Per-file subprocess for deep analysis** | Understanding prose, logic, quality | High (10:1 ratio) | Instruction style validation |
+| **Pattern 3: Data file operations** | Loading reference data, matching, summarizing | Massive (100:1 ratio) | Find applicable rules from standards |
+| **Pattern 4: Parallel execution** | Independent operations that can run simultaneously | Performance gain | Frontmatter + Menu + Step type checks |
+
+---
+
+## Step File Integration
+
+**How to add subprocess patterns to step files:**
+
+### 1. Universal Rule (add to all steps)
+```markdown
+### Universal Rules:
+- ⚙️ 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
+```
+
+### 2. Step-Specific Rules (pattern-specific)
+```markdown
+### Step-Specific Rules:
+- 🎯 [Brief: which pattern applies]
+- 💬 Subprocess must either update report OR return findings to parent
+- 🚫 DO NOT BE LAZY - [specific "do not be lazy" guidance if applicable]
+```
+
+### 3. Command Sequence (detailed pattern)
+```markdown
+### 1. [Operation Name]
+
+**[Appropriate subprocess directive]:**
+
+For [Pattern 1 - grep/regex]:
+"Launch a subprocess that runs [command] across all files, returns [results]"
+
+For [Pattern 2 - per-file analysis]:
+"DO NOT BE LAZY - For EACH file, launch a subprocess that [analyzes], returns [findings]"
+
+For [Pattern 3 - data ops]:
+"Launch a subprocess that loads [data file], performs [operation], returns [results]"
+```
+
+---
+
+## Subprocess Loading Reference Data (Meta-Pattern!)
+
+**Context-saving optimization:**
+
+When a step needs to understand subprocess patterns with examples, load this reference file in a subprocess:
+
+```markdown
+### Step-Specific Rules:
+- 🎯 Analyze subprocess optimization opportunities - use subprocess to load reference patterns for detailed examples
+- 💬 Subprocess loads {subprocessPatterns} to understand patterns deeply, returns specific opportunities
+- 🚫 If subprocess unavailable: Load {subprocessPatterns} in main context
+
+**Execution:**
+- With subprocess: Launch subprocess to load this file, understand patterns, identify opportunities
+- Without subprocess: Load this file in main context (larger context but still functional)
+```
+
+**This step file (step-08b) demonstrates this pattern!**
+
+---
+
+## Validation Checklist
+
+For subprocess optimization in step files:
+
+- [ ] Universal fallback rule present
+- [ ] Step-specific rules mention which pattern applies
+- [ ] Command sequence uses appropriate subprocess directive
+- [ ] "DO NOT BE LAZY" language included for Pattern 2
+- [ ] Return pattern specified (update report OR return to parent)
+- [ ] Graceful fallback addressed
+- [ ] Context savings estimated (if applicable)
+- [ ] Pattern matches operation type (grep/regex, deep analysis, or data ops)
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Loading full files into parent
+```markdown
+"For EACH file, load the file, analyze it, and add to report"
+# Defeats purpose - parent gets full context
+```
+
+### ❌ Subprocess returns raw content
+```markdown
+"Subprocess loads file and returns content to parent"
+# Parent gets full content anyway
+```
+
+### ❌ No graceful fallback
+```markdown
+"Use subprocess to [operation]"
+# LLMs without subprocess cannot proceed
+```
+
+### ❌ Wrong pattern for operation
+```markdown
+"Launch a subprocess per file to grep for pattern"
+# Should use Pattern 1 (single subprocess for all files)
+```
+
+### ❌ Missing return specification
+```markdown
+"Launch a subprocess to analyze files"
+# Unclear what subprocess returns to parent
+```
+
+---
+
+## See Also
+
+- `step-file-rules.md` - When to extract content to data files
+- `step-08b-subprocess-optimization.md` - Validation step that identifies optimization opportunities
+- `../steps-v/step-02b-path-violations.md` - Example of Pattern 1 (grep across files)
+- `../steps-v/step-08b-subprocess-optimization.md` - Example of Pattern 2 (per-file analysis)