@zeyue0329/xiaoma-cli 1.0.49 → 6.0.0-alpha.14

package/src/modules/xmb/docs/workflows/intent-vs-prescriptive-spectrum.md

@@ -0,0 +1,220 @@
+# Intent vs Prescriptive Spectrum
+
+## Core Philosophy
+
+The **Intent vs Prescriptive Spectrum** is a fundamental design principle for XIAOMA workflows and agents. It determines how much creative freedom an LLM has versus how strictly it must follow predefined instructions.
+
+**Key Principle:** The closer workflows stay to **intent**, the more creative and adaptive the LLM experience becomes. The closer they stay to **prescriptive**, the more consistent and controlled the output becomes.
+
+## Understanding the Spectrum
+
+### **Intent-Based Design** (Creative Freedom)
+
+**Focus**: What goal should be achieved
+**Approach**: Trust the LLM to determine the best method
+**Result**: Creative, adaptive, context-aware interactions
+**Best For**: Creative exploration, problem-solving, personalized experiences
+
+### **Prescriptive Design** (Structured Control)
+
+**Focus**: Exactly what to say and do
+**Approach**: Detailed scripts and specific instructions
+**Result**: Consistent, predictable, controlled outcomes
+**Best For**: Compliance, safety-critical, standardized processes
+
+## Spectrum Examples
+
+### **Highly Intent-Based** (Creative End)
+
+```markdown
+**Example:** Story Exploration Workflow
+**Instruction:** "Help the user explore their dream imagery to craft compelling narratives, use multiple turns of conversation to really push users to develop their ideas, giving them hints and ideas also to prime them effectively to bring out their creativity"
+**LLM Freedom:** Adapts questions, explores tangents, follows creative inspiration
+**Outcome:** Unique, personalized storytelling experiences
+```
+
+### **Balanced Middle** (Professional Services)
+
+```markdown
+**Example:** Business Strategy Workflow
+**Instruction:** "Guide the user through SWOT analysis using your business expertise. when complete tell them 'here is your final report {report output}'
+**LLM Freedom:** Professional judgment in analysis, structured but adaptive approach
+**Outcome:** Professional, consistent yet tailored business insights
+```
+
+### **Highly Prescriptive** (Control End)
+
+```markdown
+**Example:** Medical Intake Form
+**Instruction:** "Ask exactly: 'Do you currently experience any of the following symptoms: fever, cough, fatigue?' Wait for response, then ask exactly: 'When did these symptoms begin?'"
+**LLM Freedom:** Minimal - must follow exact script for medical compliance
+**Outcome:** Consistent, medically compliant patient data collection
+```
+
+## Spectrum Positioning Guide
+
+### **Choose Intent-Based When:**
+
+- ✅ Creative exploration and innovation are goals
+- ✅ Personalization and adaptation to user context are important
+- ✅ Human-like conversation and natural interaction are desired
+- ✅ Problem-solving requires flexible thinking
+- ✅ User experience and engagement are priorities
+
+**Examples:**
+
+- Creative brainstorming sessions
+- Personal coaching or mentoring
+- Exploratory research and discovery
+- Artistic content creation
+- Collaborative problem-solving
+
+### **Choose Prescriptive When:**
+
+- ✅ Compliance with regulations or standards is required
+- ✅ Safety or legal considerations are paramount
+- ✅ Exact consistency across multiple sessions is essential
+- ✅ Training new users on specific procedures
+- ✅ Data collection must follow specific protocols
+
+**Examples:**
+
+- Medical intake and symptom assessment
+- Legal compliance questionnaires
+- Safety checklists and procedures
+- Standardized testing protocols
+- Regulatory data collection
+
+### **Choose Balanced When:**
+
+- ✅ Professional expertise is required but adaptation is beneficial
+- ✅ Consistent quality with flexible application is needed
+- ✅ Domain expertise should guide but not constrain interactions
+- ✅ User trust and professional credibility are important
+- ✅ Complex processes require both structure and judgment
+
+**Examples:**
+
+- Business consulting and advisory
+- Technical support and troubleshooting
+- Educational tutoring and instruction
+- Financial planning and advice
+- Project management facilitation
+
+## Implementation Guidelines
+
+### **For Workflow Designers:**
+
+1. **Early Spectrum Decision**: Determine spectrum position during initial design
+2. **User Education**: Explain spectrum choice and its implications to users
+3. **Consistent Application**: Maintain chosen spectrum throughout workflow
+4. **Context Awareness**: Adjust spectrum based on specific use case requirements
+
+### **For Workflow Implementation:**
+
+**Intent-Based Patterns:**
+
+```markdown
+- "Help the user understand..." (vs "Explain that...")
+- "Guide the user through..." (vs "Follow these steps...")
+- "Use your professional judgment to..." (vs "Apply this specific method...")
+- "Adapt your approach based on..." (vs "Regardless of situation, always...")
+```
+
+**Prescriptive Patterns:**
+
+```markdown
+- "Say exactly: '...'" (vs "Communicate that...")
+- "Follow this script precisely: ..." (vs "Cover these points...")
+- "Do not deviate from: ..." (vs "Consider these options...")
+- "Must ask in this order: ..." (vs "Ensure you cover...")
+```
+
+### **For Agents:**
+
+**Intent-Based Agent Design:**
+
+```yaml
+persona:
+  communication_style: 'Adaptive professional who adjusts approach based on user context'
+  guiding_principles:
+    - 'Use creative problem-solving within professional boundaries'
+    - 'Personalize approach while maintaining expertise'
+    - 'Adapt conversation flow to user needs'
+```
+
+**Prescriptive Agent Design:**
+
+```yaml
+persona:
+  communication_style: 'Follows standardized protocols exactly'
+  governing_rules:
+    - 'Must use approved scripts without deviation'
+    - 'Follow sequence precisely as defined'
+    - 'No adaptation of prescribed procedures'
+```
+
+## Spectrum Calibration Questions
+
+**Ask these during workflow design:**
+
+1. **Consequence of Variation**: What happens if the LLM says something different?
+2. **User Expectation**: Does the user expect consistency or creativity?
+3. **Risk Level**: What are the risks of creative deviation vs. rigid adherence?
+4. **Expertise Required**: Is domain expertise application more important than consistency?
+5. **Regulatory Requirements**: Are there external compliance requirements?
+
+## Best Practices
+
+### **DO:**
+
+- ✅ Make conscious spectrum decisions during design
+- ✅ Explain spectrum choices to users
+- ✅ Use intent-based design for creative and adaptive experiences
+- ✅ Use prescriptive design for compliance and consistency requirements
+- ✅ Consider balanced approaches for professional services
+- ✅ Document spectrum rationale for future reference
+
+### **DON'T:**
+
+- ❌ Mix spectrum approaches inconsistently within workflows
+- ❌ Default to prescriptive when intent-based would be more effective
+- ❌ Use creative freedom when compliance is required
+- ❌ Forget to consider user expectations and experience
+- ❌ Overlook risk assessment in spectrum selection
+
+## Quality Assurance
+
+**When validating workflows:**
+
+- Check if spectrum position is intentional and consistent
+- Verify prescriptive elements are necessary and justified
+- Ensure intent-based elements have sufficient guidance
+- Confirm spectrum alignment with user needs and expectations
+- Validate that risks are appropriately managed
+
+## Examples in Practice
+
+### **Medical Intake (Highly Prescriptive):**
+
+- **Why**: Patient safety, regulatory compliance, consistent data collection
+- **Implementation**: Exact questions, specific order, no deviation permitted
+- **Benefit**: Reliable, medically compliant patient information
+
+### **Creative Writing Workshop (Highly Intent):**
+
+- **Why**: Creative exploration, personalized inspiration, artistic expression
+- **Implementation**: Goal guidance, creative freedom, adaptive prompts
+- **Benefit**: Unique, personalized creative works
+
+### **Business Strategy (Balanced):**
+
+- **Why**: Professional expertise with adaptive application
+- **Implementation**: Structured framework with professional judgment
+- **Benefit**: Professional, consistent yet tailored business insights
+
+## Conclusion
+
+The Intent vs Prescriptive Spectrum is not about good vs. bad - it's about **appropriate design choices**. The best workflows make conscious decisions about where they fall on this spectrum based on their specific requirements, user needs, and risk considerations.
+
+**Key Success Factor**: Choose your spectrum position intentionally, implement it consistently, and align it with your specific use case requirements.

package/src/modules/xmb/docs/workflows/step-template.md

@@ -0,0 +1,283 @@
+# XIAOMA Workflow Step Template
+
+This template provides the standard structure for all XIAOMA workflow step files. Copy and modify this template for each new step you create.
+
+---
+
+```yaml
+---
+name: 'step-[N]-[short-name]'
+description: '[Brief description of what this step accomplishes]'
+
+# Path Definitions
+workflow_path: '{project-root}/{xiaoma_folder}/xmb/reference/workflows/[workflow-name]'
+
+# File References (all use {variable} format in file)
+thisStepFile: '{workflow_path}/steps/step-[N]-[short-name].md'
+nextStepFile: '{workflow_path}/steps/step-[N+1]-[next-short-name].md' # Remove for final step
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/[output-file-name]-{project_name}.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/{xiaoma_folder}/core/tasks/advanced-elicitation.xml'
+partyModeWorkflow: '{project-root}/{xiaoma_folder}/core/workflows/party-mode/workflow.md'
+
+# Template References (if this step uses templates)
+profileTemplate: '{workflow_path}/templates/profile-section.md'
+assessmentTemplate: '{workflow_path}/templates/assessment-section.md'
+strategyTemplate: '{workflow_path}/templates/strategy-section.md'
+# Add more as needed
+---
+```
+
+# Step [N]: [Step Name]
+
+## STEP GOAL:
+
+[State the goal in context of the overall workflow goal. Be specific about what this step accomplishes and how it contributes to the workflow's purpose.]
+
+Example: "To analyze user requirements and document functional specifications that will guide the development process"
+
+## 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"]
+- ✅ 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], and together we produce something better than the sum of our own parts
+- ✅ Maintain collaborative [adjective] tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on [specific task for this step]
+- 🚫 FORBIDDEN to [what not to do in this step]
+- 💬 Approach: [how to handle this specific task]
+- 📋 Additional rule relevant to this step
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 [Step-specific protocol 1]
+- 💾 [Step-specific protocol 2 - e.g., document updates]
+- 📖 [Step-specific protocol 3 - e.g., tracking requirements]
+- 🚫 [Step-specific restriction]
+
+## CONTEXT BOUNDARIES:
+
+- Available context: [what context is available from previous steps]
+- Focus: [what this step should concentrate on]
+- Limits: [what not to assume or do]
+- Dependencies: [what this step depends on]
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+[Detailed instructions for the step's work]
+
+### 1. Title
+
+[Specific instructions for first part of the work]
+
+### 2. Title
+
+[Specific instructions for second part of the work]
+
+#### Content to Append (if applicable):
+
+```markdown
+## [Section Title]
+
+[Content template or instructions for what to append]
+```
+
+### N. (Continue as needed)
+
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask} # Or custom action
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content to {outputFile}, update frontmatter, then only 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
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+[Specific conditions for completing this step and transitioning to the next, such as output to file being created with this tasks updates]
+
+ONLY WHEN [C continue option] is selected and [completion requirements], will you then load and read fully `[installed_path]/step-[next-number]-[name].md` to execute and begin [next step description].
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- [Step-specific success criteria 1]
+- [Step-specific success criteria 2]
+- Content properly saved/document updated
+- Menu presented and user input handled correctly
+- [General success criteria]
+
+### ❌ SYSTEM FAILURE:
+
+- [Step-specific failure mode 1]
+- [Step-specific failure mode 2]
+- Proceeding without user input/selection
+- Not updating required documents/frontmatter
+- [General failure modes]
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+---
+
+## Common Menu Patterns
+
+### Standard Menu (A/P/C)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Advanced Elicitation] [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content to {outputFile}, update frontmatter, then only 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
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+### Auto-Proceed Menu (No User Choice)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Proceeding to [next action]...**"
+
+#### 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
+```
+
+### Custom Menu Options
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Custom Action 1] [B] [Custom Action 2] [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: [Custom handler for option A]
+- IF B: [Custom handler for option B]
+- IF C: Save content to {outputFile}, update frontmatter, then only 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
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+### Conditional Menu (Based on Workflow State)
+
+```markdown
+### N. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] [Custom Label] [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {customAction}
+- IF C: Save content to {outputFile}, update frontmatter, check [condition]:
+  - IF [condition true]: load, read entire file, then execute {pathA}
+  - IF [condition false]: load, read entire file, then execute {pathB}
+- 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
+- User can chat or ask questions - always respond and then end with display again of the menu options
+```
+
+## Example Step Implementations
+
+### Initialization Step Example
+
+See [step-01-init.md](../reference/workflows/meal-prep-nutrition/steps/step-01-init.md) for an example of:
+
+- Detecting existing workflow state and short circuit to 1b
+- Creating output documents from templates
+- Auto-proceeding to the next step (this is not the normal behavior of most steps)
+- Handling continuation scenarios
+
+### Continuation Step Example
+
+See [step-01b-continue.md](../reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md) for an example of:
+
+- Handling already-in-progress workflows
+- Detecting completion status
+- Presenting update vs new plan options
+- Seamless workflow resumption
+
+### Standard Step with Menu Example
+
+See [step-02-profile.md](../reference/workflows/meal-prep-nutrition/steps/step-02-profile.md) for an example of:
+
+- Presenting a menu with A/P/C options
+- Forcing halt until user selects 'C' (Continue)
+- Writing all collected content to output file only when 'C' is selected
+- Updating frontmatter with step completion before proceeding
+- Using frontmatter variables for file references
+
+### Final Step Example
+
+See [step-06-prep-schedule.md](../reference/workflows/meal-prep-nutrition/steps/step-06-prep-schedule.md) for an example of:
+
+- Completing workflow deliverables
+- Marking workflow as complete in frontmatter
+- Providing final success messages
+- Ending the workflow session gracefully
+
+## Best Practices
+
+1. **Keep step files focused** - Each step should do one thing well
+2. **Be explicit in instructions** - No ambiguity about what to do
+3. **Include all critical rules** - Don't assume anything from other steps
+4. **Use clear, concise language** - Avoid jargon unless necessary
+5. **Ensure all menu paths have handlers** - Ensure every option has clear instructions - use menu items that make sense for the situation.
+6. **Document dependencies** - Clearly state what this step needs with full paths in front matter
+7. **Define success and failure clearly** - Both for the step and the workflow
+8. **Mark completion clearly** - Ensure final steps update frontmatter to indicate workflow completion

package/src/modules/xmb/docs/workflows/terms.md

@@ -0,0 +1,97 @@
+# XIAOMA Workflow Terms
+
+## Core Components
+
+### XIAOMA Workflow
+
+A facilitated, guided process where the AI acts as a facilitator working collaboratively with a human. Workflows can serve any purpose - from document creation to brainstorming, technical implementation, or decision-making. The human may be a collaborative partner, beginner seeking guidance, or someone who wants the AI to execute specific tasks. Each workflow is self-contained and follows a disciplined execution model.
+
+### workflow.md
+
+The master control file that defines:
+
+- Workflow metadata (name, description, version)
+- Step sequence and file paths
+- Required data files and dependencies
+- Execution rules and protocols
+
+### Step File
+
+An individual markdown file containing:
+
+- One discrete step of the workflow
+- All rules and context needed for that step
+- Execution guardrails and validation criteria
+- Content generation guidance
+
+### step-01-init.md
+
+The first step file that:
+
+- Initializes the workflow
+- Sets up document frontmatter
+- Establishes initial context
+- Defines workflow parameters
+
+### step-01b-continue.md
+
+A continuation step file that:
+
+- Resumes a workflow that was paused
+- Reloads context from saved state
+- Validates current document state
+- Continues from the last completed step
+
+### CSV Data Files
+
+Structured data files that provide:
+
+- Domain-specific knowledge and complexity mappings
+- Project-type-specific requirements
+- Decision matrices and lookup tables
+- Dynamic workflow behavior based on input
+
+## Dialog Styles
+
+### Prescriptive Dialog
+
+Structured interaction with:
+
+- Exact questions and specific options
+- Consistent format across all executions
+- Finite, well-defined choices
+- High reliability and repeatability
+
+### Intent-Based Dialog
+
+Adaptive interaction with:
+
+- Goals and principles instead of scripts
+- Open-ended exploration and discovery
+- Context-aware question adaptation
+- Flexible, conversational flow
+
+### Template
+
+A markdown file that:
+
+- Starts with frontmatter (metadata)
+- Has content built through append-only operations
+- Contains no placeholder tags
+- Grows progressively as the workflow executes
+- Used when the workflow produces a document output
+
+## Execution Concepts
+
+### JIT Step Loading
+
+Just-In-Time step loading ensures:
+
+- Only the current step file is in memory
+- Complete focus on the step being executed
+- Minimal context to prevent information leakage
+- Sequential progression through workflow steps
+
+---
+
+_These terms form the foundation of the XIAOMA workflow system._