@delorenj/pjangler 1.2.25 → 1.3.0

package/templates/commonproject/_bmad/bmb/workflows/workflow/data/menu-handling-standards.md

@@ -1,167 +0,0 @@
-# Menu Handling Standards
-
-**CRITICAL:** Every menu MUST have a handler section. No exceptions.
-
----
-
-## Reserved Letters
-
-| Letter | Purpose              | After Execution                |
-| ------ | -------------------- | ------------------------------ |
-| **A**  | Advanced Elicitation | Redisplay menu                |
-| **P**  | Party Mode           | Redisplay menu                |
-| **C**  | Continue/Accept      | Save → update → load next step |
-| **X**  | Exit/Cancel          | End workflow                  |
-
-**Custom letters** allowed (L/R/F/etc.) but don't conflict with reserved.
-
----
-
-## Required Structure
-
-### Section 1: Display
-```markdown
-### N. Present MENU OPTIONS
-
-Display: "**Select:** [A] [action] [P] [action] [C] Continue"
-```
-
-### Section 2: Handler (MANDATORY)
-```markdown
-#### 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: help user, then [Redisplay Menu Options](#n-present-menu-options)
-```
-
-### Section 3: Execution Rules
-```markdown
-#### 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
-```
-
----
-
-## When To Include A/P
-
-### DON'T Include A/P:
-- Step 1 (init) - no content to refine yet
-- Step 2 if only loading documents
-- Validation sequences - auto-flow instead
-- Simple data gathering
-
-### DO Include A/P:
-- Collaborative content creation
-- User might want alternatives
-- Quality gate before proceeding
-- Creative exploration valuable
-
----
-
-## Menu Patterns
-
-### Pattern 1: Standard A/P/C
-```markdown
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [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: help user, 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
-```
-
-### Pattern 2: C Only (No A/P)
-```markdown
-Display: "**Select:** [C] Continue"
-
-#### Menu Handling Logic:
-- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF Any other: help user, 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'
-```
-
-**Use for:** Step 1, document discovery, simple progression
-
-### Pattern 3: Auto-Proceed (No Menu)
-```markdown
-Display: "**Proceeding to [next step]...**"
-
-#### Menu Handling Logic:
-- After [completion condition], immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-- This is an [auto-proceed reason] step with no user choices
-- Proceed directly to next step after setup
-```
-
-**Use for:** Init steps, validation sequences
-
-### Pattern 4: Branching
-```markdown
-Display: "**Select:** [L] Load Existing [N] Create New [C] Continue"
-
-#### Menu Handling Logic:
-- IF L: Load existing document, then load, read entire file, then execute {stepForExisting}
-- IF N: Create new document, then load, read entire file, then execute {stepForNew}
-- IF C: Save content to {outputFile}, update frontmatter, check {condition}, then load appropriate step
-- IF Any other: help user, then [Redisplay Menu Options](#n-present-menu-options)
-
-#### EXECUTION RULES:
-- ALWAYS halt and wait for user input after presenting menu
-- Branching options load different steps based on user choice
-```
-
----
-
-## Critical Violations
-
-### ❌ DON'T:
-```markdown
-# Missing Handler Section
-Display: "**Select:** [C] Continue"
-[NO HANDLER - CRITICAL ERROR!]
-
-# A/P in Step 1 (doesn't make sense)
-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-# Forgetting redisplay
-- IF A: Execute {advancedElicitationTask}
-# Should end with: ", and when finished redisplay the menu"
-
-# Missing halt instruction
-#### EXECUTION RULES:
-- ONLY proceed to next step when user selects 'C'
-# MISSING: "ALWAYS halt and wait for user input after presenting menu"
-```
-
-### ✅ DO:
-- Handler section immediately follows Display
-- "Halt and wait" in EXECUTION RULES
-- Non-C options specify "redisplay menu"
-- A/P only when appropriate for step type
-
----
-
-## Validation Checklist
-
-For every menu:
-- [ ] Display section present
-- [ ] Handler section immediately follows
-- [ ] EXECUTION RULES section present
-- [ ] "Halt and wait" instruction included
-- [ ] A/P options appropriate for step type
-- [ ] Non-C options redisplay menu
-- [ ] C option: save → update → load next
-- [ ] All file references use variables

package/templates/commonproject/_bmad/bmb/workflows/workflow/data/output-format-standards.md

@@ -1,188 +0,0 @@
-# Output Format Standards
-
-**Purpose:** How workflows produce documents and handle step output.
-
----
-
-## 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
-
-**Use when:** Design/plan before building/creating
-
-```
-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
-```
-
-**Example:** Workflow creation - steps append to plan, build step generates files
-
-### Pattern 2: Direct-to-Final
-
-**Use when:** Each step contributes to final deliverable
-
-```
-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
-```
-
-**Example:** Meal prep nutrition plan - each step adds a section
-
----
-
-## Four Template Types
-
-### 1. Free-Form (RECOMMENDED)
-
-**Characteristics:** Minimal template, progressive append, final polish
-
-**Template:**
-```yaml
----
-stepsCompleted: []
-lastStep: ''
-date: ''
-user_name: ''
----
-
-# {{document_title}}
-
-[Content appended progressively by workflow steps]
-```
-
-**Use when:** Most workflows - flexible, collaborative
-
-### 2. Structured
-
-**Characteristics:** Single template with placeholders, clear sections
-
-**Template:**
-```markdown
-# {{title}}
-
-## {{section_1}}
-[Content to be filled]
-
-## {{section_2}}
-[Content to be filled]
-```
-
-**Use when:** Reports, proposals, documentation
-
-### 3. Semi-Structured
-
-**Characteristics:** Core required sections + optional additions
-
-**Use when:** Forms, checklists, meeting minutes
-
-### 4. Strict
-
-**Characteristics:** Multiple templates, exact field definitions
-
-**Use when:** Rarely - 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'
-```
-
----
-
-## Validation Checklist
-
-For workflow output design:
-- [ ] Output format type selected
-- [ ] Template created if needed
-- [ ] Steps ordered to match document structure
-- [ ] Each step outputs to document (except init/final)
-- [ ] Level 2 headers for main sections
-- [ ] Final polish step for free-form workflows
-- [ ] Frontmatter tracking for continuable workflows
-- [ ] Templates use consistent placeholder syntax

package/templates/commonproject/_bmad/bmb/workflows/workflow/data/step-file-rules.md

@@ -1,235 +0,0 @@
-# Step File Rules
-
-**Purpose:** Quick reference for step file 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 content 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 the complete step file before taking any 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 the 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`