@devo-bmad-custom/agent-orchestration 1.0.0

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

@@ -0,0 +1,188 @@
+# 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**
+3. **Always provide graceful fallback** for LLMs without subprocess capability
+4. **Match pattern to operation type** - grep/regex, deep analysis, or data operations
+
+---
+
+## Pattern 1: Single Subprocess for Grep/Regex Across Many Files
+
+**Use when:** One command across many files, only need matches/failures
+**Context savings:** Massive (1000:1 ratio)
+
+**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
+```
+
+**Good:** "Launch subprocess to grep all files for pattern, return only matches"
+**Bad:** "For EACH file, load the file and search for pattern"
+
+**Example return:**
+```json
+{"violations": [{"file": "step-02.md", "line": 45, "match": "..."}], "summary": {"total_files_checked": 10, "violations_found": 3}}
+```
+
+---
+
+## Pattern 2: Separate Subprocess Per File for Deep Analysis
+
+**Use when:** Reading prose, logic, quality, or flow of each file
+**Context savings:** High (10:1 ratio)
+
+**Template:**
+```markdown
+DO NOT BE LAZY - For EACH file, launch a subprocess that:
+1. Loads that file
+2. Reads and analyzes content deeply
+3. Returns structured analysis findings to parent
+```
+
+**Good:** "DO NOT BE LAZY - For EACH step file, launch subprocess to analyze instruction style, return findings"
+**Bad:** "Load every step file and analyze its instruction style"
+
+**Use cases:** Instruction style validation, collaborative quality assessment, frontmatter compliance, step type validation
+
+---
+
+## Pattern 3: Subprocess for Data File Operations
+
+**Use when:** Loading reference data, fuzzy/best matching, summarizing large datasets
+**Context savings:** Massive (100:1 ratio)
+
+**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
+```
+
+**Good:** "Launch subprocess to load {dataFile}, find applicable rules, return only those"
+**Bad:** "Load {dataFile} with 500 rules and find applicable ones"
+
+**Use cases:** Reference rules lookup, CSV fuzzy matching, document summarization, knowledge base search
+
+---
+
+## Pattern 4: Parallel Execution Opportunities
+
+**Use when:** Multiple independent operations could run simultaneously
+**Performance gain:** Reduced total execution time
+
+**Template:**
+```markdown
+Launch subprocesses in parallel that:
+1. Each handles one independent operation
+2. All run simultaneously
+3. Parent aggregates results when complete
+```
+
+**Example:** Instead of sequential checks, launch 3 subprocesses in parallel (frontmatter, menu, step types), then aggregate.
+
+---
+
+## Graceful Fallback Pattern (CRITICAL)
+
+**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
+```
+
+---
+
+## Return Pattern for Subprocesses
+
+**Subprocesses must either:**
+
+**Option A: Update report directly** - "Subprocess loads validation report, appends findings, saves"
+
+**Option B: Return structured findings to parent** - "Subprocess returns JSON findings to parent for aggregation"
+
+**Good return:** `{"file": "step-02.md", "violations": ["..."], "opportunities": ["..."], "priority": "HIGH"}`
+**Bad:** "Subprocess loads file and returns full content to parent"
+
+---
+
+## When to Use Each Pattern
+
+| Pattern | Use When | Context Savings |
+| -------- | -------- | --------------- |
+| Pattern 1: Grep/regex | Finding patterns across many files | Massive (1000:1) |
+| Pattern 2: Per-file analysis | Understanding prose, logic, quality | High (10:1) |
+| Pattern 3: Data operations | Reference data, matching, summarizing | Massive (100:1) |
+| Pattern 4: Parallel execution | Independent operations | Performance gain |
+
+---
+
+## Step File Integration
+
+### Universal Rule (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
+```
+
+### Step-Specific Rules
+```markdown
+### Step-Specific Rules:
+- 🎯 [which pattern applies]
+- 💬 Subprocess must either update report OR return findings to parent
+- 🚫 DO NOT BE LAZY - [specific guidance for Pattern 2]
+```
+
+### Command Directives
+- Pattern 1: "Launch subprocess that runs [command] across all files, returns [results]"
+- Pattern 2: "DO NOT BE LAZY - For EACH file, launch subprocess that [analyzes], returns [findings]"
+- Pattern 3: "Launch subprocess that loads [data file], performs [operation], returns [results]"
+
+---
+
+## Validation Checklist
+
+- [ ] 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
+- [ ] Pattern matches operation type (grep/regex, deep analysis, or data ops)
+
+---
+
+## Anti-Patterns to Avoid
+
+| ❌ Anti-Pattern | ✅ Correct Approach |
+| --------------- | ------------------- |
+| "For EACH file, load the file, analyze it" | "Launch subprocess per file that returns analysis" |
+| "Subprocess loads file and returns content" | "Subprocess returns structured findings only" |
+| "Use subprocess to [operation]" (no fallback) | Include fallback rule for non-subprocess LLMs |
+| "Launch subprocess per file to grep" | Use Pattern 1 (single subprocess for grep) |
+| "Launch subprocess to analyze files" | Specify what subprocess returns |
+
+---
+
+## See Also
+
+- `step-file-rules.md` - When to extract content to data files
+- `step-08b-subprocess-optimization.md` - Validation step for optimization opportunities
+- `../steps-v/step-02b-path-violations.md` - Example of Pattern 1
+- `../steps-v/step-08b-subprocess-optimization.md` - Example of Pattern 2

package/src/bmb/workflows/workflow/data/trimodal-workflow-structure.md

@@ -0,0 +1,164 @@
+# Tri-Modal Workflow Structure
+
+## Golden Rule
+
+**For complex critical workflows: Implement tri-modal structure (create/validate/edit) with cross-mode integration.**
+
+**Cross-mode integration patterns:**
+- Create → Validation (handoff after build)
+- Edit → Validation (verify changes)
+- Edit → Create/conversion (for non-compliant input)
+- Validation → Edit (fix issues found)
+- All modes run standalone via workflow.md routing
+
+## Directory Structure
+
+```
+workflow-name/
+├── workflow.md                    # Entry point with mode routing
+├── data/                          # SHARED standards and reference
+│   ├── [domain]-standards.md
+│   └── [domain]-patterns.md
+├── steps-c/                       # Create (self-contained)
+│   ├── step-00-conversion.md     # Entry for non-compliant input
+│   ├── step-01-init.md
+│   └── step-N-complete.md
+├── steps-e/                       # Edit (self-contained)
+│   ├── step-01-assess.md          # Checks compliance, routes if needed
+│   └── step-N-complete.md
+└── steps-v/                       # Validate (self-contained, runs standalone)
+    └── step-01-validate.md
+```
+
+## Mode Responsibilities
+
+### Create Mode (steps-c/)
+- **Primary:** Build new entities from scratch
+- **Secondary:** Convert non-compliant input via step-00-conversion
+
+**Key patterns:**
+- step-00-conversion: Loads non-compliant input, extracts essence, creates plan with `conversionFrom` metadata
+- Final step routes to validation (optional but recommended)
+- Confirmation step checks `conversionFrom` to verify coverage vs new workflow
+
+### Edit Mode (steps-e/)
+- **Primary:** Modify existing compliant entities
+- **Secondary:** Detect non-compliance and route to conversion
+
+**Key patterns:**
+- step-01-assess: Checks compliance first
+- Non-compliant → Offer route to step-00-conversion (not step-01-discovery)
+- Post-edit → Offer validation (reuse validation workflow)
+- During edits → Check standards, offer to fix non-compliance
+
+### Validate Mode (steps-v/)
+- **Primary:** Standalone validation against standards
+- **Secondary:** Generates actionable reports
+
+**Key patterns:**
+- Runs standalone (invoked via -v flag or direct call)
+- Auto-proceeds through all checks
+- Generates report with issue severity
+- Report consumed by edit mode for fixes
+
+## workflow.md Routing Pattern
+
+```yaml
+## INITIALIZATION SEQUENCE
+
+### 1. Mode Determination
+
+**Check invocation:**
+- "create" / -c → mode = create
+- "validate" / -v → mode = validate
+- "edit" / -e → mode = edit
+
+**If create mode:** Ask "From scratch or convert existing?"
+- From scratch → steps-c/step-01-init.md
+- Convert → steps-c/step-00-conversion.md
+
+**If unclear:** Ask user to select mode
+
+### 2. Route to First Step
+
+**IF mode == create:**
+Route to appropriate create entry (init or conversion)
+
+**IF mode == validate:**
+Prompt for path → load steps-v/step-01-validate.md
+
+**IF mode == edit:**
+Prompt for path → load steps-e/step-01-assess.md
+```
+
+**Critical:** workflow.md is lean. No step listings. Only routing logic.
+
+## Cross-Mode Integration Points
+
+### 1. Edit → Create (Non-Compliant Detection)
+```yaml
+Check workflow compliance:
+  - Compliant → Continue to edit steps
+  - Non-compliant → Offer conversion
+    - IF user accepts: Load steps-c/step-00-conversion.md with sourceWorkflowPath
+```
+
+### 2. Create/Edit → Validation
+```yaml
+# In create final step or edit post-edit step
+Offer: "Run validation?"
+  - IF yes: Load ../steps-v/step-01-validate.md
+  - Validation runs standalone, returns report
+  - Resume create/edit with validation results
+```
+
+### 3. Validation → Edit
+```yaml
+# User can invoke edit mode with report as input
+"Fix issues found?"
+  - IF yes: Load steps-e/step-01-assess.md with validationReport path
+```
+
+### 4. Conversion Coverage Tracking
+```yaml
+# In create step-10-confirmation
+Check workflowPlan metadata:
+  - IF conversionFrom exists:
+    - Load original workflow
+    - Compare each step/instruction
+    - Report coverage percentage
+  - ELSE (new workflow):
+    - Validate all plan requirements implemented
+```
+
+## When to Use Tri-Modal
+
+**Use Tri-Modal for:**
+- Complex workflows requiring quality assurance
+- Workflows that will be maintained over time
+- Workflows where non-compliant input may be offered
+- Critical workflows where standards compliance matters
+
+**Use Create-Only for:**
+- Simple one-off workflows
+- Experimental workflows
+- Workflows unlikely to need editing or validation
+
+## Frontmatter Standards for Cross-Mode References
+
+Never inline file paths. Always use frontmatter variables:
+
+```yaml
+---
+# Create mode step calling validation
+validationWorkflow: '../steps-v/step-01-validate.md'
+---
+
+# Edit mode step routing to conversion
+conversionStep: '../steps-c/step-00-conversion.md'
+---
+
+# Create conversion step receiving from edit
+sourceWorkflowPath: '{targetWorkflowPath}'  # Passed from edit
+---
+```

package/src/bmb/workflows/workflow/data/workflow-chaining-standards.md

@@ -0,0 +1,222 @@
+# Workflow Chaining Standards
+
+## Module Workflow Pipeline
+
+**Example:** BMM Module - Idea to Implementation
+
+```
+brainstorming → research → brief → PRD → UX → architecture → epics → sprint-planning
+                                                        ↓
+                                            implement-story → review → repeat
+```
+
+Each workflow:
+1. Checks for required inputs from prior workflows
+2. Validates inputs are complete
+3. Produces output for next workflow
+4. Recommends next workflow in sequence
+
+## Input/Output Contract
+
+### Output Contract
+
+**Every workflow should:**
+1. Create output document with predictable filename
+2. Include `workflowType` in frontmatter for identification
+3. Mark `stepsCompleted: [all steps]` when complete
+4. Store in known location (`{module_output_folder}`)
+
+**Example frontmatter:**
+```yaml
+---
+workflowType: 'prd'
+stepsCompleted: ['step-01-init', ..., 'step-11-complete']
+project_name: 'my-project'
+date: '2025-01-02'
+nextWorkflow: 'create-ux'
+previousWorkflow: 'create-brief'
+---
+```
+
+### Input Contract
+
+**Every workflow should:**
+1. Define required inputs in Step 1
+2. Search in `{module_output_folder}` for prior outputs
+3. Validate inputs are complete
+4. Allow user to select from discovered documents
+
+## Step 1: Input Discovery Pattern
+
+```markdown
+## 1. Discover Required Inputs
+
+### Required Inputs:
+- {module_output_folder}/prd-{project_name}.md
+
+### Search:
+1. Look for prd-{project_name}.md in {module_output_folder}
+2. If found → validate completeness
+3. If missing or incomplete → error with guidance
+
+"Error: This workflow requires a completed PRD.
+Expected location: {module_output_folder}/prd-{project_name}.md
+To fix: Run the PRD workflow first, or provide the path to your PRD."
+```
+
+## Final Step: Next Workflow Recommendation
+
+```markdown
+## Next Steps
+
+Based on your completed [workflow], recommended next workflows:
+
+1. **[next-workflow-name]** - [why it's next]
+2. **[alternative-workflow]** - [when to use this instead]
+
+Would you like to:
+- Run [next-workflow-name] now?
+- Run a different workflow?
+- Exit for now?
+```
+
+**Update output frontmatter:**
+```yaml
+nextWorkflow: 'create-ux'
+nextWorkflowRecommended: true
+```
+
+## Cross-Workflow Status Tracking
+
+**Optional:** Module can maintain `workflow-status.yaml`:
+
+```yaml
+---
+current_workflow: 'create-prd'
+completed_workflows:
+  - brainstorming
+  - research
+  - brief
+pending_workflows:
+  - create-ux
+  - create-architecture
+  - create-epics
+  - sprint-planning
+outputs:
+  brief: '{module_output_folder}/brief-{project_name}.md'
+  prd: '{module_output_folder}/prd-{project_name}.md'
+---
+```
+
+**Workflow checks this file to:**
+- Validate sequence (don't run UX before PRD)
+- Find output locations
+- Track overall progress
+
+## Branching Workflows
+
+```markdown
+## Next Steps
+
+Based on your project type:
+
+**For software projects:**
+- create-architecture - Technical architecture
+- create-epics - Break down into epics
+
+**For data projects:**
+- data-modeling - Database schema design
+- etl-pipeline - Data pipeline design
+
+Which workflow would you like to run next?
+```
+
+## Required vs Optional Sequences
+
+### Required Sequence
+**PRD must come before Architecture:**
+
+```yaml
+# In architecture workflow.md
+## PREREQUISITE:
+This workflow requires a completed PRD.
+
+## INITIALIZATION:
+IF prd-{project_name}.md exists AND is complete:
+  → Proceed with architecture workflow
+ELSE:
+  → Error: "Please complete PRD workflow first"
+```
+
+### Optional Sequence
+**UX research helps Architecture but isn't required:**
+
+```yaml
+# In architecture workflow.md
+## OPTIONAL INPUTS:
+UX research documents can inform technical decisions.
+
+IF ux-research-{project_name}.md exists:
+  → "Found UX research. Include findings in architecture design?"
+ELSE:
+  → "No UX research found. Continuing without it."
+```
+
+## Filename Conventions for Chaining
+
+**Standard pattern:** `{workflow-name}-{project-name}.md`
+
+| Workflow | Output Filename Pattern |
+|----------| ---------------------- |
+| brainstorming | `brainstorming-{project_name}.md` |
+| brief | `brief-{project_name}.md` |
+| PRD | `prd-{project_name}.md` |
+| UX | `ux-design-{project_name}.md` |
+| architecture | `architecture-{project_name}.md` |
+| epics | `epics-{project_name}.md` |
+
+## Module-Level Workflow Registry
+
+**Module can define `workflows.yaml`:**
+
+```yaml
+---
+module: 'bmm'
+workflows:
+  brainstorming:
+    output: 'brainstorming-{project_name}.md'
+    next: ['research']
+  research:
+    output: 'research-{project_name}.md'
+    next: ['brief']
+  brief:
+    output: 'brief-{project_name}.md'
+    next: ['prd']
+  prd:
+    output: 'prd-{project_name}.md'
+    next: ['create-ux', 'create-architecture']
+  create-ux:
+    output: 'ux-design-{project_name}.md'
+    next: ['create-architecture']
+  create-architecture:
+    output: 'architecture-{project_name}.md'
+    next: ['create-epics']
+  create-epics:
+    output: 'epics-{project_name}.md'
+    next: ['sprint-planning']
+---
+```
+
+## Cross-Module Dependencies
+
+```yaml
+# In BMGD narrative workflow
+## INPUT REQUIREMENTS:
+
+### Required:
+- {bmm_output_folder}/prd-{project_name}.md
+- {bmm_output_folder}/architecture-{project_name}.md
+
+### From BMGD:
+- {bmgd_output_folder}/gdd-{project_name}.md (Game Design Document)
+```