siesa-agents 2.1.36 → 2.1.38

package/_bmad/bmb/docs/workflows/step-file-rules.md

@@ -0,0 +1,469 @@
+# BMAD Step File Guidelines
+
+**Version:** 1.0
+**Module:** bmb (BMAD Builder)
+**Purpose:** Definitive guide for creating BMAD workflow step files
+
+---
+
+## Overview
+
+BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines.
+
+---
+
+## File Size Optimization
+
+**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum).
+
+If a step exceeds this limit:
+- Consider splitting into multiple steps
+- Extract content to `/data/` reference files
+- Optimize verbose explanations
+
+---
+
+## Required Frontmatter Structure
+
+CRITICAL: Frontmatter should only have items that are used in the step file!
+
+```yaml
+---
+name: 'step-2-foo.md'
+description: 'Brief description of what this step accomplishes'
+
+# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file!
+outputFile: {bmb_creations_output_folder}/output-file-name.md
+nextStepFile: './step-3-bar.md'
+
+# Task References (as needed)
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+# ... other task-specific references
+---
+```
+
+### Frontmatter Field Descriptions
+
+| Field           | Required  | Description                       |
+| --------------- | --------- | --------------------------------- |
+| `name`          | Yes       | Step identifier (kebab-case)      |
+| `description`   | Yes       | One-line summary of step purpose  |
+| `outputFile`    | Yes       | Where results are documented      |
+| Task references | As needed | Paths to external workflows/tasks |
+
+---
+
+## Document Structure
+
+### 1. Title
+
+```markdown
+# Step X: [Step Name]
+```
+
+### 2. STEP GOAL
+
+```markdown
+## STEP GOAL:
+
+[Single sentence stating what this step accomplishes]
+```
+
+### 3. Role Reinforcement
+
+```markdown
+### Role Reinforcement:
+
+- ✅ You are a [specific role] who [does what]
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], together we [achieve goal]
+- ✅ Maintain [tone/approach] throughout
+```
+
+### 4. Language Preference
+
+```markdown
+### Language Preference:
+The user has chosen to communicate in the **{language}** language.
+You MUST respond in **{language}** throughout this step.
+```
+
+**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it.
+
+### 5. Step-Specific Rules
+
+```markdown
+### Step-Specific Rules:
+
+- 🎯 Focus only on [specific scope]
+- 🚫 FORBIDDEN to [prohibited action]
+- 💬 Approach: [how to engage]
+- 📋 Ensure [specific outcome]
+```
+
+### 6. EXECUTION PROTOCOLS
+
+```markdown
+## EXECUTION PROTOCOLS:
+
+- [What to do - use verbs]
+- [Another action]
+- 🚫 FORBIDDEN to [prohibited action]
+```
+
+### 7. CONTEXT BOUNDARIES
+
+```markdown
+## CONTEXT BOUNDARIES:
+
+- Available context: [what's available]
+- Focus: [what to focus on]
+- Limits: [boundaries]
+- Dependencies: [what this step depends on]
+```
+
+### 8. Sequence of Instructions
+
+```markdown
+## Sequence of Instructions:
+
+### 1. [First Action]
+
+**[Action Description]**
+
+### 2. [Second Action]
+
+...
+```
+
+### 9. MENU OPTIONS
+
+```markdown
+### X. Present MENU OPTIONS
+
+Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]"
+
+#### 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](#x-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
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`...
+```
+
+### 10. SYSTEM SUCCESS/FAILURE METRICS
+
+```markdown
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- [Success criterion 1]
+- [Success criterion 2]
+- ...
+
+### ❌ SYSTEM FAILURE:
+- [Failure criterion 1]
+- [Failure criterion 2]
+- ...
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+```
+
+---
+
+## A/P/C Menu Convention
+
+BMAD workflows use a fixed menu structure:
+
+| Option | Meaning              | Behavior                                             |
+| ------ | -------------------- | ---------------------------------------------------- |
+| **A**  | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu |
+| **P**  | Party Mode           | Execute partyModeWorkflow, then redisplay menu       |
+| **C**  | Continue/Accept      | Save output, update frontmatter, load nextStepFile   |
+| Other  | Custom               | Defined per step (e.g., F = Fix, X = Exit)           |
+
+**Rules:**
+- A and P MUST always be present
+- C MUST be present except in final step (use X or similar for exit)
+- After A/P → redisplay menu
+- After C → proceed to next step
+- Custom letters can be used for step-specific options
+
+---
+
+## Progressive Disclosure
+
+**Core Principle:** Each step only knows about its immediate next step.
+
+### Implementation
+
+1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C]
+
+2. **Mode-aware routing** (for shared steps):
+   ```markdown
+   ## MODE-AWARE ROUTING:
+   ### If entered from CREATE mode:
+   Load ./s-next-step.md
+
+   ### If entered from EDIT mode:
+   Load ./e-next-step.md
+
+   ### If entered from VALIDATE mode:
+   Load ./v-next-step.md
+   ```
+
+3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing
+
+---
+
+## Mode-Aware Routing (Shared Steps)
+
+Shared steps (`s-*.md`) must route based on the mode stored in the tracking file.
+
+### Tracking File Frontmatter
+
+```yaml
+---
+mode: create              # or edit | validate
+stepsCompleted:
+  - c-01-brainstorm.md
+  - s-01-discovery.md
+# ... other tracking fields
+---
+```
+
+### Routing Implementation
+
+```markdown
+## COMPLETION ROUTING:
+
+1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted
+2. Save content to {trackingFile}
+3. Read {trackingFile}.mode
+4. Route based on mode:
+
+### IF mode == create:
+Load ./s-next-create-step.md
+
+### IF mode == edit:
+Load ./e-next-edit-step.md
+
+### IF mode == validate:
+Load ./s-next-validate-step.md
+```
+
+---
+
+## File Naming Conventions
+
+### Tri-Modal Workflows
+
+| Prefix | Meaning            | Example                |
+| ------ | ------------------ | ---------------------- |
+| `c-`   | Create-specific    | `c-01-brainstorm.md`   |
+| `e-`   | Edit-specific      | `e-01-load-analyze.md` |
+| `v-`   | Validate-specific  | `v-01-load-review.md`  |
+| `s-`   | Shared by 2+ modes | `s-05-activation.md`   |
+
+### Numbering
+
+- Within each prefix type, number sequentially
+- Restart numbering for each prefix type (c-01, e-01, v-01, s-01)
+- Use letters for sub-steps (s-06a, s-06b, s-06c)
+
+---
+
+## Language Preference Enforcement
+
+**CRITICAL:** Every step MUST respect the user's chosen language.
+
+### Implementation
+
+```markdown
+### Language Preference:
+The user has chosen to communicate in the **{language}** language.
+You MUST respond in **{language}** throughout this step.
+```
+
+### Reading Language Preference
+
+From tracking file frontmatter:
+```yaml
+---
+userPreferences:
+  language: spanish    # or any language
+---
+```
+
+### Rules
+
+- **MUST** read language preference from tracking file at step start
+- **MUST** respond in user's chosen language for ALL content
+- **MUST** include menu options in user's chosen language
+- **EXCEPTION:** Technical terms, file names, and code remain in English
+
+---
+
+## Data File References
+
+When step content becomes too large (>200 lines), extract to `/data/` files:
+
+### When to Extract
+
+- Step file exceeds 200 lines
+- Content is reference material (rules, examples, patterns)
+- Content is reused across multiple steps
+
+### How to Reference
+
+```markdown
+## Reference Material:
+
+Load and reference: `../data/{data-file-name}.md`
+
+Key points from that file:
+- [Point 1]
+- [Point 2]
+```
+
+### Data File Best Practices
+
+- Keep data files focused on single topic
+- Use clear, descriptive names
+- Include examples and non-examples
+- Optimize for LLM usage (concise, structured)
+
+---
+
+## Common Pitfalls to Avoid
+
+### ❌ DON'T:
+
+- Pre-load future steps (violates progressive disclosure)
+- Exceed 250 lines without splitting
+- Forget to update `stepsCompleted` array
+- Ignore user's language preference
+- Skip mode checking in shared steps
+- Use vague menu option letters (stick to A/P/C plus 1-2 custom)
+
+### ✅ DO:
+
+- Keep files under 200 lines
+- Read tracking file first thing
+- Route based on `mode` field
+- Include A/P in every menu
+- Use descriptive step names
+- Extract complex content to data files
+
+---
+
+## Template: New Step File
+
+```markdown
+---
+name: 'step-name'
+description: 'What this step does'
+
+# File References
+thisStepFile: ./step-name.md
+workflowFile: ../workflow.md
+outputFile: {bmb_creations_output_folder}/output.md
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step X: [Step Name]
+
+## STEP GOAL:
+
+[Single sentence goal]
+
+### Role Reinforcement:
+
+- ✅ You are a [role] who [does what]
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [expertise], user brings [expertise], together we [achieve]
+- ✅ Maintain [tone] throughout
+
+### Language Preference:
+The user has chosen to communicate in the **{language}** language.
+You MUST respond in **{language}** throughout this step.
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on [scope]
+- 🚫 FORBIDDEN to [prohibited action]
+- 💬 Approach: [how to engage]
+- 📋 Ensure [outcome]
+
+## EXECUTION PROTOCOLS:
+
+- [Action 1]
+- [Action 2]
+- 🚫 FORBIDDEN to [prohibited action]
+
+## CONTEXT BOUNDARIES:
+
+- Available context: [what's available]
+- Focus: [what to focus on]
+- Limits: [boundaries]
+- Dependencies: [what depends on what]
+
+## Sequence of Instructions:
+
+### 1. [First Action]
+
+**Description of first action**
+
+### 2. [Second Action]
+
+**Description of second action**
+
+...
+
+### X. Present MENU OPTIONS
+
+Display: "**Select:** [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 comments or queries: help user respond then [Redisplay Menu Options](#x-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
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`...
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- [Success criteria]
+
+### ❌ SYSTEM FAILURE:
+- [Failure criteria]
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+```
+
+---
+
+**End of Guidelines**

package/_bmad/bmb/docs/workflows/templates/step-01-init-continuable-template.md

@@ -0,0 +1,241 @@
+# BMAD Continuable Step 01 Init Template
+
+This template provides the standard structure for step-01-init files that support workflow continuation. It includes logic to detect existing workflows and route to step-01b-continue.md for resumption.
+
+Use this template when creating workflows that generate output documents and might take multiple sessions to complete.
+
+<!-- TEMPLATE START -->
+
+---
+
+name: 'step-01-init'
+description: 'Initialize the [workflow-type] workflow by detecting continuation state and creating output document'
+
+<!-- Path Definitions -->
+
+workflow\*path: `{project-root}/_bmad/[module-path]/workflows/[workflow-name]`
+
+# File References (all use {variable} format in file)
+
+thisStepFile: `{workflow_path}/steps/step-01-init.md`
+nextStepFile: `{workflow_path}/steps/step-02-[step-name].md`
+workflowFile: `{workflow_path}/workflow.md`
+outputFile: `{output_folder}/[output-file-name]-{project_name}.md`
+continueFile: `{workflow_path}/steps/step-01b-continue.md`
+templateFile: `{workflow_path}/templates/[main-template].md`
+
+# Template References
+
+# This step doesn't use content templates, only the main template
+
+---
+
+# Step 1: Workflow Initialization
+
+## 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, e.g., "business analyst" or "technical architect"]
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring [your expertise], user brings [their expertise], and together we produce something better than we could on our own
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization and setup
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## STEP GOAL:
+
+To initialize the [workflow-type] workflow by detecting continuation state, creating the output document, and preparing for the first collaborative session.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/[output-file-name]-{project_name}.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Handle Completed Workflow
+
+If the document exists AND all steps are marked complete in `stepsCompleted`:
+
+- Ask user: "I found an existing [workflow-output] from [date]. Would you like to:
+  1. Create a new [workflow-output]
+  2. Update/modify the existing [workflow-output]"
+- If option 1: Create new document with timestamp suffix
+- If option 2: Load step-01b-continue.md
+
+### 4. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+This workflow requires [describe input documents if any]:
+
+**[Document Type] Documents (Optional):**
+
+- Look for: `{output_folder}/*[pattern1]*.md`
+- Look for: `{output_folder}/*[pattern2]*.md`
+- If found, load completely and add to `inputDocuments` frontmatter
+
+#### B. Create Initial Document
+
+Copy the template from `{templateFile}` to `{output_folder}/[output-file-name]-{project_name}.md`
+
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: [1]
+lastStep: 'init'
+inputDocuments: []
+date: [current date]
+user_name: { user_name }
+[additional workflow-specific fields]
+---
+```
+
+#### C. Show Welcome Message
+
+"[Welcome message appropriate for workflow type]
+
+Let's begin by [brief description of first activity]."
+
+## ✅ SUCCESS METRICS:
+
+- Document created from template (for fresh workflows)
+- Frontmatter initialized with step 1 marked complete
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR continuation properly routed to step-01b-continue.md
+
+## ❌ FAILURE MODES TO AVOID:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when needed
+
+### 5. Present MENU OPTIONS
+
+Display: **Proceeding to [next step description]...**
+
+#### EXECUTION RULES:
+
+- This is an initialization step with no user choices
+- Proceed directly to next step after setup
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- After setup completion, immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description]
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Document created from template (for fresh workflows)
+- update frontmatter `stepsCompleted` to add 1 at the end of the array before loading next step
+- Frontmatter initialized with `stepsCompleted: [1]`
+- User welcomed to the process
+- Ready to proceed to step 2
+- OR existing workflow properly routed to step-01b-continue.md
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+- Not routing to step-01b-continue.md when appropriate
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete and document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin [next step description].
+
+<!-- TEMPLATE END -->
+
+## Customization Guidelines
+
+When adapting this template for your specific workflow:
+
+### 1. Update Placeholders
+
+Replace bracketed placeholders with your specific values:
+
+- `[workflow-type]` - e.g., "nutrition planning", "project requirements"
+- `[module-path]` - e.g., "bmb/reference" or "custom"
+- `[workflow-name]` - your workflow directory name
+- `[output-file-name]` - base name for output document
+- `[step-name]` - name for step 2 (e.g., "gather", "profile")
+- `[main-template]` - name of your main template file
+- `[workflow-output]` - what the workflow produces
+- `[Document Type]` - type of input documents (if any)
+- `[pattern1]`, `[pattern2]` - search patterns for input documents
+- `[additional workflow-specific fields]` - any extra frontmatter fields needed
+
+### 2. Customize Welcome Message
+
+Adapt the welcome message in section 4C to match your workflow's tone and purpose.
+
+### 3. Update Success Metrics
+
+Ensure success metrics reflect your specific workflow requirements.
+
+### 4. Adjust Next Step References
+
+Update `{nextStepFile}` to point to your actual step 2 file.
+
+## Implementation Notes
+
+1. **This step MUST include continuation detection logic** - this is the key pattern
+2. **Always include `continueFile` reference** in frontmatter
+3. **Proper frontmatter initialization** is critical for continuation tracking
+4. **Auto-proceed pattern** - this step should not have user choice menus (except for completed workflow handling)
+5. **Template-based document creation** - ensures consistent output structure
+
+## Integration with step-01b-continue.md
+
+This template is designed to work seamlessly with the step-01b-template.md continuation step. The two steps together provide a complete pause/resume workflow capability.