create-byan-agent 2.1.1 → 2.2.2

package/install/templates/_byan/bmb/workflows/workflow/data/menu-handling-standards.md

@@ -0,0 +1,167 @@
+# 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/install/templates/_byan/bmb/workflows/workflow/data/output-format-standards.md

@@ -0,0 +1,188 @@
+# 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/install/templates/_byan/bmb/workflows/workflow/data/step-file-rules.md

@@ -0,0 +1,235 @@
+# 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`