@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/workflow/data/output-format-standards.md

@@ -0,0 +1,135 @@
+# Output Format Standards
+
+## Golden Rule
+
+**Every step MUST output to a document BEFORE loading the next step.**
+
+Two patterns:
+1. **Direct-to-Final:** Steps append to final document
+2. **Plan-then-Build:** Steps append to plan → build step consumes plan
+
+## Menu C Option Sequence
+
+When user selects **C (Continue)**:
+1. **Append/Write** to document (plan or final)
+2. **Update frontmatter** (append this step to `stepsCompleted`)
+3. **THEN** load next step
+
+```markdown
+- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+```
+
+## Output Patterns
+
+### Pattern 1: Plan-then-Build
+
+```
+Step 1 (init)     → Creates plan.md from template
+Step 2 (gather)   → Appends requirements to plan.md
+Step 3 (design)   → Appends design decisions to plan.md
+Step 4 (review)   → Appends review/approval to plan.md
+Step 5 (build)    → READS plan.md, CREATES final artifacts
+```
+
+**Plan frontmatter:**
+```yaml
+workflowName: [name]
+creationDate: [date]
+stepsCompleted: ['step-01-init', 'step-02-gather']
+status: PLANNING_COMPLETE
+```
+
+### Pattern 2: Direct-to-Final
+
+```
+Step 1 (init)     → Creates final-doc.md from minimal template
+Step 2 (section)  → Appends Section 1
+Step 3 (section)  → Appends Section 2
+Step 4 (section)  → Appends Section 3
+Step 5 (polish)   → Optimizes entire document
+```
+
+## Four Template Types
+
+### 1. Free-Form (RECOMMENDED)
+- Minimal template, progressive append, final polish
+
+```yaml
+---
+stepsCompleted: []
+lastStep: ''
+date: ''
+user_name: ''
+---
+
+# {{document_title}}
+
+[Content appended progressively by workflow steps]
+```
+
+### 2. Structured
+- Single template with placeholders, clear sections
+
+```markdown
+# {{title}}
+
+## {{section_1}}
+[Content to be filled]
+
+## {{section_2}}
+[Content to be filled]
+```
+
+### 3. Semi-Structured
+- Core required sections + optional additions
+
+### 4. Strict
+- Multiple templates, exact field definitions
+- Use for: compliance, legal, regulated
+
+## Template Syntax
+
+```markdown
+{{variable}}    # Handlebars style (preferred)
+[variable]      # Bracket style (also supported)
+```
+
+Keep templates lean - structure only, not content.
+
+## Step-to-Output Mapping
+
+Steps should be in ORDER of document appearance:
+
+```
+Step 1: Init (creates doc)
+Step 2: → ## Section 1
+Step 3: → ## Section 2
+Step 4: → ## Section 3
+Step 5: → ## Section 4
+Step 6: Polish (optimizes entire doc)
+```
+
+**Critical:** Use ## Level 2 headers for main sections - allows document splitting if needed.
+
+## Final Polish Step
+
+For free-form workflows, include a polish step that:
+1. Loads entire document
+2. Reviews for flow and coherence
+3. Reduces duplication
+4. Ensures proper ## Level 2 headers
+5. Improves transitions
+6. Keeps general order but optimizes readability
+
+## Output File Patterns
+
+```yaml
+# Single output
+outputFile: '{output_folder}/document-{project_name}.md'
+
+# Time-stamped
+outputFile: '{output_folder}/document-{project_name}-{timestamp}.md'
+
+# User-specific
+outputFile: '{output_folder}/document-{user_name}-{project_name}.md'
+```

package/src/bmb/workflows/workflow/data/step-file-rules.md

@@ -0,0 +1,235 @@
+# Step File Rules
+
+**Purpose:** Quick reference for step structure and compliance. See linked data files for detailed standards.
+
+---
+
+## File Size Limits
+
+| Metric      | Value    |
+| ----------- | -------- |
+| Recommended | < 200 lines |
+| Absolute Maximum | 250 lines |
+
+**If exceeded:** Split into multiple steps or extract to `/data/` files.
+
+---
+
+## Required Step Structure
+
+```markdown
+---
+name: 'step-[N]-[name]'
+description: '[what this step does]'
+
+# File References (ONLY variables used in this step!)
+[file references in {variable} format
+---
+
+# Step [N]: [Name]
+
+## STEP GOAL:
+[Single sentence: what this step accomplishes]
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+### Universal Rules:
+- NEVER generate content without user input
+- CRITICAL: Read complete step file before taking action
+- CRITICAL: When loading next step with 'C', ensure entire file is read
+- YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+- You are a [specific role]
+- We engage in collaborative dialogue, not command-response
+- You bring [expertise], user brings [theirs]
+- Together we produce something better
+
+### Step-Specific Rules:
+- Focus only on [specific task]
+- FORBIDDEN to [prohibited action]
+- Approach: [how to engage]
+
+## EXECUTION PROTOCOLS:
+- [Protocol 1]
+- [Protocol 2 - save/update]
+- [Protocol 3 - tracking]
+
+## CONTEXT BOUNDARIES:
+- Available context: [what's available]
+- Focus: [what to focus on]
+- Limits: [boundaries]
+- Dependencies: [what this depends on]
+
+## Sequence of Instructions:
+### 1. [Action]
+[Instructions]
+
+### N. Present MENU OPTIONS
+[Menu section - see menu-handling-standards.md]
+
+## SYSTEM SUCCESS/FAILURE METRICS:
+### SUCCESS:
+[Success criteria]
+### SYSTEM FAILURE:
+[Failure criteria]
+**Master Rule:** Skipping steps is FORBIDDEN.
+```
+
+---
+
+## Critical Rules (Quick Reference)
+
+### Frontmatter
+- Only variables USED in step body
+- All file references use `{variable}` format
+- Relative paths within workflow folder
+- See: `frontmatter-standards.md`
+
+### Menus
+- Handler section MUST follow display
+- "Halt and wait" in execution rules
+- A/P options only when appropriate
+- Non-C options redisplay menu
+- See: `menu-handling-standards.md`
+
+### Progressive Disclosure
+- Only load next step when user selects 'C'
+- Read entire step file before execution
+- Don't create mental todos from future steps
+
+### Continuable Workflows
+- Append step number to `stepsCompleted`
+- Don't hardcode full array
+- See: `workflow-type-criteria.md`
+
+---
+
+## Data Files Reference
+
+| File | Purpose |
+| --- | --- |
+| `frontmatter-standards.md` | Variables, paths, frontmatter rules |
+| `menu-handling-standards.md` | Menu patterns, handler requirements |
+| `output-format-standards.md` | Document output, template types |
+| `workflow-type-criteria.md` | Continuable, module, tri-modal decisions |
+| `step-type-patterns.md` | Templates for init/middle/final/branch steps |
+| `trimodal-workflow-structure.md` | Create/Edit/Validate folder structure |
+
+---
+
+## Step Type Reference
+
+| Step Type | Template/Reference |
+| --- | --- |
+| Init (non-continuable) | Auto-proceed, no continuation logic |
+| Init (continuable) | `step-01-init-continuable-template.md` |
+| Continuation (01b) | `step-1b-template.md` |
+| Middle (standard) | A/P/C menu, collaborative content |
+| Middle (simple) | C only menu, no A/P |
+| Branch/Conditional | Custom menu options, routing to different steps |
+| Validation sequence | Auto-proceed through checks |
+| Final | No next step, completion message |
+
+See: `step-type-patterns.md`
+
+---
+
+## Frontmatter Variables
+
+### Standard (Always Available)
+- `{project-root}`
+- `{project_name}`
+- `{output_folder}`
+- `{user_name}`
+- `{communication_language}`
+- `{document_output_language}`
+
+### Module-Specific (e.g., BMB)
+- `{bmb_creations_output_folder}`
+
+### User-Defined
+- New variables can be defined in steps for future steps
+
+See: `frontmatter-standards.md`
+
+---
+
+## Validation Checklist
+
+For every step file:
+
+- [ ] File < 200 lines (250 max)
+- [ ] `name` and `description` in frontmatter
+- [ ] All frontmatter variables are used
+- [ ] File references use `{variable}` format
+- [ ] Relative paths within workflow folder
+- [ ] Handler section follows menu display
+- [ ] "Halt and wait" in execution rules
+- [ ] A/P options appropriate for step type
+- [ ] C option saves and loads next step
+- [ ] Non-C options redisplay menu
+- [ ] StepsCompleted appended (if continuable)
+- [ ] Success/failure metrics present
+
+---
+
+## Quick Menu Reference
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select:** [A] [action A] [P] [action P] [C] Continue"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+```
+
+---
+
+## Common Violations
+
+| Violation | Fix |
+| --- | --- |
+| Unused variable in frontmatter | Remove unused variables |
+| Hardcoded file path | Use `{variable}` format |
+| A/P menu in step 1 | Remove A/P (inappropriate for init) |
+| Missing handler section | Add handler after menu display |
+| No "halt and wait" instruction | Add to EXECUTION RULES |
+| Hardcoded `stepsCompleted: [1,2,3]` | Append: "update stepsCompleted to add this step" |
+| File > 250 lines | Split into multiple steps or extract to /data/ |
+| Absolute path for same-folder ref | Use relative path or `{workflow_path}` |
+
+---
+
+## When to Extract to Data Files
+
+Extract step content to `/data/` when:
+- Step file exceeds 200 lines
+- Content is reference material
+- Content is reused across steps
+- Content is domain-specific (examples, patterns)
+
+**Data file types:**
+- `.md` - Reference documentation
+- `.csv` - Structured data for lookup
+- `examples/` - Reference implementations
+
+---
+
+## Tri-Modal Workflow Note
+
+For Create/Edit/Validate workflows:
+- Each mode has its own `steps-c/`, `steps-e/`, `steps-v/` folder
+- NO shared step files (`s-*.md`) between modes
+- All modes share `/data/` folder
+- This prevents confusion and routing errors
+
+See: `trimodal-workflow-structure.md`

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

@@ -0,0 +1,257 @@
+# Step Type Patterns
+
+## Core Skeleton
+```markdown
+---
+name: 'step-[N]-[name]'
+description: '[action]'
+[file refs only if used]
+---
+
+# Step [N]: [Name]
+
+## STEP GOAL:
+[single sentence]
+
+## MANDATORY EXECUTION RULES:
+### Universal:
+- 🛑 NEVER generate without user input
+- 📖 Read complete step file before action
+- 🔄 When loading with 'C', read entire file
+- 📋 Facilitator, not generator
+
+### Role:
+- ✅ Role: [specific]
+- ✅ Collaborative dialogue
+- ✅ You bring [expertise], user brings [theirs]
+
+### Step-Specific:
+- 🎯 Focus: [task]
+- 🚫 Forbidden: [action]
+- 💬 Approach: [method]
+
+## EXECUTION PROTOCOLS:
+- 🎯 Follow MANDATORY SEQUENCE exactly
+- 💾 [protocol]
+- 📖 [protocol]
+
+## CONTEXT BOUNDARIES:
+- Available: [context]
+- Focus: [scope]
+- Limits: [bounds]
+- Dependencies: [reqs]
+
+## MANDATORY SEQUENCE
+**Follow exactly. No skip/reorder without user request.**
+
+### 1. [action]
+[instructions]
+
+### N. MENU OPTIONS
+[see menu-handling-standards.md]
+
+## 🚨 SUCCESS/FAILURE:
+### ✅ SUCCESS: [criteria]
+### ❌ FAILURE: [criteria]
+**Master Rule:** Skipping steps FORBIDDEN.
+```
+
+## Step Types
+
+### 1. Init (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'
+---
+```
+- No continuation detection
+- Auto-proceeds to step 2
+- No A/P menu
+- Creates output from template
+
+### 2. Init (Continuable)
+**Use:** Multi-session workflow
+
+**Frontmatter:** Add `continueFile: './step-01b-continue.md'` <!-- validate-file-refs:ignore -->
+
+**Logic:**
+```markdown
+## 1. Check Existing Workflow
+- Look for {outputFile}
+- If exists + has stepsCompleted → load {continueFile}
+- If not → continue to setup
+```
+**Ref:** `step-01-init-continuable-template.md`
+
+### 3. Continuation (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` from output
+2. Read last completed step file to find nextStep
+3. Welcome user back
+4. Route to appropriate step
+
+**Ref:** `step-1b-template.md`
+
+### 4. Middle (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
+
+### 5. Middle (Simple)
+**Use:** Data gathering, no refinement
+
+**Menu:** C only
+
+### 6. Branch Step
+**Use:** User choice determines path
+
+**Frontmatter:**
+```yaml
+nextStepFile: './step-[default].md'
+altStepFile: './step-[alternate].md'
+```
+**Menu:** Custom letters (L/R/etc.)
+
+### 7. Validation Sequence
+**Use:** Multiple checks without interruption
+
+**Menu:** Auto-proceed
+
+**Pattern:**
+```markdown
+## 1. Perform validation check
+[logic]
+
+## 2. Write results to {outputFile}
+Append findings
+
+## 3. Proceed to next validation
+"**Proceeding to next check...**"
+→ Load {nextValidationStep}
+```
+
+### 8. Init (With Input Discovery)
+**Use:** Requires documents from prior workflows/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'
+---
+```
+**Logic:**
+```markdown
+## 1. Discover Inputs
+Search {moduleInputFolder} + {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 docs
+Add to {inputDocuments}
+
+## 4. Auto-Proceed
+If all required inputs → step 2
+If missing → Error with guidance
+```
+**Ref:** `input-discovery-standards.md`
+
+### 9. Final Polish
+**Use:** Optimizes document section-by-section
+
+**Frontmatter:**
+```yaml
+---
+name: 'step-[N]-polish'
+description: 'Optimize and finalize document'
+outputFile: '{output_folder}/[document].md'
+---
+```
+**Logic:**
+```markdown
+## 1. Load Complete Document
+Read {outputFile}
+
+## 2. Document Optimization
+Review for:
+1. Flow/coherence
+2. Duplication (remove, preserve essential)
+3. Proper ## Level 2 headers
+4. Smooth transitions
+5. Readability
+
+## 3. Optimize
+Maintain:
+- General order
+- Essential info
+- User's voice
+
+## 4. Final Output
+Save, mark complete
+```
+**Use for:** Free-form output workflows
+
+### 10. Final Step
+**Use:** Last step, completion
+
+**Frontmatter:** No `nextStepFile`
+
+**Logic:**
+- Update frontmatter (mark complete)
+- Final summary
+- No next step
+
+## Step Size Limits
+| Type                  | Max    |
+| --------------------- | ------ |
+| Init                  | 150    |
+| Init (with discovery) | 200    |
+| Continuation          | 200    |
+| Middle (simple)       | 200    |
+| Middle (complex)      | 250    |
+| Branch                | 200    |
+| Validation sequence   | 150    |
+| Final polish          | 200    |
+| Final                 | 200    |
+
+**If exceeded:** Split steps or extract to `/data/`.