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

package/src/modules/bmb/workflows/workflow/data/csv-data-file-standards.md

@@ -0,0 +1,81 @@
+# CSV Data File Standards
+
+**Purpose:** When workflows need structured data that LLMs cannot generate.
+
+---
+
+## When to Use CSV
+
+Use CSV for data that is:
+- Domain-specific and not in training data
+- Too large for prompt context
+- Needs structured lookup/reference
+- Must be consistent across sessions
+
+**Don't use for:**
+- Web-searchable information
+- Common programming syntax
+- General knowledge
+- Things LLMs can generate
+
+---
+
+## CSV Structure
+
+```csv
+category,name,pattern,description
+"collaboration","Think Aloud Protocol","user speaks thoughts → facilitator captures","Make thinking visible during work"
+"creative","SCAMPER","substitute→combine→adapt→modify→put→eliminate→reverse","Systematic creative thinking"
+```
+
+**Rules:**
+- Header row required, descriptive column names
+- Consistent data types per column
+- UTF-8 encoding
+- All columns must be used in workflow
+
+---
+
+## Common Use Cases
+
+### 1. Method Registry
+Advanced Elicitation uses CSV to select techniques dynamically:
+```csv
+category,name,pattern
+collaboration,Think Aloud,user speaks thoughts → facilitator captures
+advanced,Six Thinking Hats,view problem from 6 perspectives
+```
+
+### 2. Knowledge Base Index
+Map keywords to document locations for surgical lookup:
+```csv
+keywords,document_path,section
+"nutrition,macros",data/nutrition-reference.md,## Daily Targets
+```
+
+### 3. Configuration Lookup
+Map scenarios to parameters:
+```csv
+scenario,required_steps,output_sections
+"2D Platformer",step-01,step-03,step-07,movement,physics,collision
+```
+
+---
+
+## Best Practices
+
+- Keep files small (<1MB if possible)
+- No unused columns
+- Document each CSV's purpose
+- Validate data quality
+- Use efficient encoding (codes vs full descriptions)
+
+---
+
+## Validation Checklist
+
+For each CSV file:
+- [ ] Purpose is essential (can't be generated by LLM)
+- [ ] All columns are used somewhere
+- [ ] Properly formatted (consistent, UTF-8)
+- [ ] Documented with examples

package/src/modules/bmb/workflows/workflow/data/frontmatter-standards.md

@@ -0,0 +1,225 @@
+# Frontmatter Standards
+
+**Purpose:** Variables, paths, and frontmatter rules for workflow steps.
+
+---
+
+## Golden Rules
+
+1. **Only variables USED in the step** may be in frontmatter
+2. **All file references MUST use `{variable}` format** - no hardcoded paths
+3. **Paths within workflow folder MUST be relative** - NO `workflow_path` variable allowed
+
+---
+
+## Standard Variables (Always Available)
+
+| Variable                     | Example Value                        |
+| ---------------------------- | ------------------------------------ |
+| `{project-root}`             | `/Users/user/dev/BMAD-METHOD`        |
+| `{project_name}`             | `my-project`                         |
+| `{output_folder}`            | `/Users/user/dev/BMAD-METHOD/output` |
+| `{user_name}`                | `Brian`                              |
+| `{communication_language}`   | `english`                            |
+| `{document_output_language}` | `english`                            |
+
+---
+
+## Module-Specific Variables
+
+Workflows in a MODULE can access additional variables from its `module.yaml`.
+
+**BMB Module example:**
+```yaml
+bmb_creations_output_folder: '{project-root}/_bmad/bmb-creations'
+```
+
+**Standalone workflows:** Only have access to standard variables.
+
+---
+
+## Frontmatter Structure
+
+### Required Fields
+```yaml
+---
+name: 'step-[N]-[name]'
+description: '[what this step does]'
+---
+```
+
+### File References - ONLY variables used in this step
+```yaml
+---
+# Step to step (SAME folder) - use ./filename.md
+nextStepFile: './step-02-vision.md'
+
+# Step to template (PARENT folder) - use ../filename.md
+productBriefTemplate: '../product-brief.template.md'
+
+# Step to data (SUBFOLDER) - use ./data/filename.md
+someData: './data/config.csv'
+
+# Output files - use variable
+outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
+
+# External references - use {project-root}
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+```
+
+---
+
+## Critical Rule: Unused Variables Forbidden
+
+### ❌ VIOLATION - Variable defined but never used
+```yaml
+---
+outputFile: '{output_folder}/output.md'
+thisStepFile: './step-01-init.md'      # ❌ NEVER USED in body
+workflowFile: './workflow.md'           # ❌ NEVER USED in body
+---
+# Step body never mentions {thisStepFile} or {workflowFile}
+```
+
+### ✅ CORRECT - Only variables that are used
+```yaml
+---
+outputFile: '{output_folder}/output.md'
+nextStepFile: './step-02-foo.md'
+---
+# Step body uses {outputFile} and {nextStepFile}
+```
+
+**Detection Rule:** For EVERY variable in frontmatter, search the step body for `{variableName}`. If not found, it's a violation.
+
+---
+
+## Path Rules - NO EXCEPTIONS
+
+### 1. Step to Step (SAME folder) = ./filename.md
+```yaml
+# ❌ WRONG
+nextStepFile: './step-02.md'
+nextStepFile: '{project-root}/_bmad/bmm/workflows/foo/steps/step-02.md'
+
+# ✅ CORRECT
+nextStepFile: './step-02-vision.md'
+```
+
+### 2. Step to Template (PARENT folder) = ../filename.md
+```yaml
+# ❌ WRONG
+someTemplate: '{workflow_path}/templates/template.md'
+
+# ✅ CORRECT
+someTemplate: '../template.md'
+```
+
+### 3. Step to Subfolder = ./subfolder/file.md
+```yaml
+# ❌ WRONG
+dataFile: '{workflow_path}/data/config.csv'
+
+# ✅ CORRECT
+dataFile: './data/config.csv'
+```
+
+### 4. External References = {project-root}/...
+```yaml
+# ✅ CORRECT
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+```
+
+### 5. Output Files = Use folder variable
+```yaml
+# ✅ CORRECT
+outputFile: '{planning_artifacts}/workflow-output-{project_name}.md'
+outputFile: '{output_folder}/output.md'
+```
+
+---
+
+## ❌ FORBIDDEN Patterns
+
+These patterns are **NEVER ALLOWED** in workflow step frontmatter:
+
+| Pattern                               | Why It's Wrong                                        |
+| ------------------------------------- | ----------------------------------------------------- |
+| `workflow_path: '{project-root}/...'` | Use relative paths instead                            |
+| `thisStepFile: './step-XX.md'`        | Almost never used - remove unless actually referenced |
+| `workflowFile: './workflow.md'`       | Almost never used - remove unless actually referenced |
+| `./...`                               | Use `./step-XX.md` (same folder)                      |
+| `{workflow_path}/templates/...`       | Use `../template.md` (parent folder)                  |
+| `{workflow_path}/data/...`            | Use `./data/file.md` (subfolder)                      |
+
+---
+
+## Variable Naming
+
+Use `snake_case` with descriptive prefixes:
+
+| Pattern        | Usage               | Example                      |
+| -------------- | ------------------- | ---------------------------- |
+| `{*_File}`     | File references     | `outputFile`, `nextStepFile` |
+| `{*_Task}`     | Task references     | `advancedElicitationTask`    |
+| `{*_Workflow}` | Workflow references | `partyModeWorkflow`          |
+| `{*_Template}` | Templates           | `productBriefTemplate`       |
+| `{*_Data}`     | Data files          | `dietaryData`                |
+
+---
+
+## Defining New Variables
+
+Steps can define NEW variables that future steps will use.
+
+**Step 01 defines:**
+```yaml
+---
+targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
+---
+# Uses {targetWorkflowPath} in body
+```
+
+**Step 02 uses:**
+```yaml
+---
+targetWorkflowPath: '{bmb_creations_output_folder}/workflows/{workflow_name}'
+workflowPlanFile: '{targetWorkflowPath}/plan.md'
+---
+# Uses {targetWorkflowPath} and {workflowPlanFile} in body
+```
+
+---
+
+## Continuable Workflow Frontmatter
+
+```yaml
+---
+stepsCompleted: ['step-01-init', 'step-02-gather', 'step-03-design']
+lastStep: 'step-03-design'
+lastContinued: '2025-01-02'
+date: '2025-01-01'
+---
+```
+
+**Step tracking:** Each step appends its NAME to `stepsCompleted`.
+
+---
+
+## Validation Checklist
+
+For EVERY step frontmatter, verify:
+
+- [ ] `name` present, kebab-case format
+- [ ] `description` present
+- [ ] Extract ALL variable names from frontmatter (between `---` markers)
+- [ ] For EACH variable, search body: is `{variableName}` present?
+- [ ] If variable NOT in body → ❌ VIOLATION, remove from frontmatter
+- [ ] All step-to-step paths use `./filename.md` format (same folder)
+- [ ] All parent-folder paths use `../filename.md` format
+- [ ] All subfolder paths use `./subfolder/filename.md` format
+- [ ] NO `{workflow_path}` variable exists
+- [ ] External paths use `{project-root}` variable
+- [ ] Module variables only used if workflow belongs to that module

package/src/modules/bmb/workflows/workflow/data/input-discovery-standards.md

@@ -0,0 +1,269 @@
+# Input Document Discovery Standards
+
+**Purpose:** How workflows discover, validate, and select input documents from prior workflows or external sources.
+
+---
+
+## Discovery Patterns
+
+### Pattern 1: Prior Workflow Output
+**Use when:** Workflow is part of a sequence (e.g., PRD → Architecture → Epics)
+
+**Example:** BMM module pipeline - each of these are a workflow with many steps:
+```
+brainstorming → research → brief → PRD → UX → architecture → epics → sprint-planning
+```
+
+Each workflow checks for output from prior workflow(s).
+
+### Pattern 2: Module Folder Search
+**Use when:** Documents stored in known project location
+
+**Example:** Manager review workflow searches `{project_folder}/employee-notes/`
+
+### Pattern 3: User-Specified Paths
+**Use when:** User provides document locations
+
+**Example:** Tax workflow asks for financial statement paths
+
+### Pattern 4: Pattern-Based Discovery
+**Use when:** Search by file naming pattern
+
+**Example:** Find all `*-brief.md` files in `{planning_artifacts}/`
+
+---
+
+## Discovery Step Pattern
+
+**When:** Step 1 (init) or Step 2 (discovery)
+
+**Frontmatter:**
+```yaml
+---
+# Input discovery variables
+inputDocuments: []           # Populated with discovered docs
+requiredInputCount: 1         # Minimum required to proceed
+optionalInputCount: 0        # Additional docs user may provide
+moduleInputFolder: '{planning_artifacts}'  # Where to search
+inputFilePatterns:           # File patterns to match
+  - '*-prd.md'
+  - '*-ux.md'
+---
+```
+
+**Discovery Logic:**
+```markdown
+## 1. Check for Known Prior Workflow Outputs
+
+Search in order:
+1. {module_output_folder}/[known-prior-workflow-output].md
+2. {project_folder}/[standard-locations]/
+3. {planning_artifacts}/
+4. User-provided paths
+
+## 2. Pattern-Based Search
+
+If no known prior workflow, search by patterns:
+- Look for files matching {inputFilePatterns}
+- Search in {moduleInputFolder}
+- Search in {project_folder}/docs/
+
+## 3. Present Findings to User
+
+"Found these documents that may be relevant:
+- [1] prd-my-project.md (created 3 days ago)
+- [2] ux-research.md (created 1 week ago)
+- [3] competitor-analysis.md
+
+Which would you like to use? You can select multiple, or provide additional paths."
+
+## 4. Confirm and Load
+
+User confirms selection → Load selected documents
+Add to {inputDocuments} array in output frontmatter
+```
+
+---
+
+## Required vs Optional Inputs
+
+### Required Inputs
+Workflow cannot proceed without these.
+
+**Example:** Architecture workflow requires PRD
+
+```markdown
+## INPUT REQUIREMENT:
+
+This workflow requires a Product Requirements Document to proceed.
+
+Searching for PRD in:
+- {bmm_creations_output_folder}/prd-*.md
+- {planning_artifacts}/*-prd.md
+- {project_folder}/docs/*-prd.md
+
+[If found:]
+"Found PRD: prd-my-project.md. Use this?"
+[If not found:]
+"No PRD found. This workflow requires a PRD to continue.
+Please provide the path to your PRD, or run the PRD workflow first."
+```
+
+### Optional Inputs
+Workflow can proceed without these, but user may include.
+
+**Example:** UX workflow can use research docs if available
+
+```markdown
+## OPTIONAL INPUTS:
+
+This workflow can incorporate research documents if available.
+
+Searching for research in:
+- {bmm_creations_output_folder}/research-*.md
+- {project_folder}/research/
+
+[If found:]
+"Found these research documents:
+- [1] user-interviews.md
+- [2] competitive-analysis.md
+Include any? (None required to proceed)"
+```
+
+---
+
+## Module Workflow Chaining
+
+**For modules with sequential workflows:**
+
+**Frontmatter in workflow.md:**
+```yaml
+---
+## INPUT FROM PRIOR WORKFLOFS
+
+### Required Inputs:
+- {module_output_folder}/prd-{project_name}.md
+
+### Optional Inputs:
+- {module_output_folder}/ux-research-{project_name}.md
+- {project_folder}/docs/competitor-analysis.md
+---
+```
+
+**Step 1 discovery:**
+```markdown
+## 1. Discover Prior Workflow Outputs
+
+Check for required inputs:
+1. Look for {module_output_folder}/prd-{project_name}.md
+2. If missing → Error: "Please run PRD workflow first"
+3. If found → Confirm with user
+
+Check for optional inputs:
+1. Search {module_output_folder}/ for research-*.md
+2. Search {project_folder}/docs/ for *-analysis.md
+3. Present findings to user
+4. Add selections to {inputDocuments}
+```
+
+---
+
+## Input Validation
+
+After discovery, validate inputs:
+
+```markdown
+## INPUT VALIDATION:
+
+For each discovered document:
+1. Load and read frontmatter
+2. Check workflowType field (should match expected)
+3. Check completeness (stepsCompleted should be complete)
+4. Check date (warn if document is very old)
+
+[If validation fails:]
+"Document prd-my-project.md appears incomplete.
+Last step: step-06 (of 11)
+Recommend completing PRD workflow before proceeding.
+Proceed anyway? [Y]es [N]o"
+```
+
+---
+
+## Multiple Input Selection
+
+**When user can select multiple documents:**
+
+```markdown
+## Document Selection
+
+"Found these relevant documents:
+[1] prd-my-project.md (3 days ago) ✓ Recommended
+[2] prd-v1.md (2 months ago) ⚠ Older version
+[3] ux-research.md (1 week ago)
+
+Enter numbers to include (comma-separated), or 'none' to skip:
+> 1, 3
+
+Selected: prd-my-project.md, ux-research.md"
+```
+
+**Track in frontmatter:**
+```yaml
+---
+inputDocuments:
+  - path: '{output_folder}/prd-my-project.md'
+    type: 'prd'
+    source: 'prior-workflow'
+    selected: true
+  - path: '{output_folder}/ux-research.md'
+    type: 'research'
+    source: 'prior-workflow'
+    selected: true
+---
+```
+
+---
+
+## Search Path Variables
+
+Common module variables for input discovery:
+
+| Variable                 | Purpose                    |
+| ------------------------ | -------------------------- |
+| `{module_output_folder}` | Prior workflow outputs     |
+| `{planning_artifacts}`   | General planning docs      |
+| `{project_folder}/docs`  | Project documentation      |
+| `{product_knowledge}`    | Product-specific knowledge |
+| `{user_documents}`       | User-provided location     |
+
+---
+
+## Discovery Step Template
+
+```markdown
+---
+name: 'step-01-init'
+description: 'Initialize and discover input documents'
+
+# Input Discovery
+inputDocuments: []
+requiredInputCount: 1
+moduleInputFolder: '{module_output_folder}'
+inputFilePatterns:
+  - '*-prd.md'
+---
+```
+
+---
+
+## Validation Checklist
+
+For input discovery:
+- [ ] Required inputs defined in step frontmatter
+- [ ] Search paths defined (module variables or patterns)
+- [ ] User confirmation before using documents
+- [ ] Validation of document completeness
+- [ ] Clear error messages when required inputs missing
+- [ ] Support for multiple document selection
+- [ ] Optional inputs clearly marked as optional

package/src/modules/bmb/workflows/workflow/data/intent-vs-prescriptive-spectrum.md

@@ -0,0 +1,50 @@
+# Intent vs Prescriptive Spectrum
+
+**Principle:** Workflows lean toward **intent** (goals) not **prescription** (exact wording). The more intent-based, the more adaptive and creative the LLM can be.
+
+---
+
+## When to Use Each
+
+### Intent-Based (Default)
+**Use for:** Most workflows - creative, exploratory, collaborative
+**Step instruction:** "Help the user understand X using multi-turn conversation. Probe to get good answers. Ask 1-2 questions at a time, not a laundry list."
+**LLM figures out:** Exact wording, question order, how to respond
+
+### Prescriptive (Exception)
+**Use for:** Compliance, safety, legal, medical, regulated industries
+**Step instruction:** "Say exactly: 'Do you currently experience fever, cough, or fatigue?' Wait for response. Then ask exactly: 'When did symptoms begin?'"
+**LLM follows:** Exact script, specific order, no deviation
+
+---
+
+## Examples
+
+### Intent-Based (Good for most)
+```
+"Guide the user through discovering their ideal nutrition plan.
+Use multi-turn conversation. Ask 1-2 questions at a time.
+Think about their responses before asking follow-ups.
+Probe to understand preferences, restrictions, goals."
+```
+
+### Prescriptive (Only when required)
+```
+"Medical intake - ask exactly:
+1. 'Do you have any of these symptoms: fever, cough, fatigue?'
+2. 'When did symptoms begin?'
+3. 'Have you traveled recently in the last 14 days?'
+Follow sequence precisely. Do not deviate."
+```
+
+---
+
+## Step Writing Tips
+
+- **Default to intent** - give goals, not scripts
+- **Use "think"** - "Think about their response before..."
+- **Multi-turn** - "Use conversation, not interrogation"
+- **Progressive** - "Ask 1-2 questions at a time"
+- **Probe** - "Ask follow-ups to understand deeper"
+
+Only use prescriptive when compliance/regulation requires it.