bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/cis/workflows/storytelling/instructions.md

@@ -0,0 +1,275 @@
+# Storytelling Workflow Instructions
+
+## Workflow
+
+<workflow>
+<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>You MUST have already loaded and processed: {project_root}/bmad/cis/workflows/storytelling/workflow.yaml</critical>
+
+<step n="1" goal="Story Context Setup">
+
+<action>Check if context data was provided with workflow invocation</action>
+<check>If data attribute was passed to this workflow:</check>
+<action>Load the context document from the data file path</action>
+<action>Study the background information, brand details, or subject matter</action>
+<action>Use the provided context to inform story development</action>
+<action>Acknowledge the focused storytelling goal</action>
+<ask response="story_refinement">I see we're crafting a story based on the context provided. What specific angle or emphasis would you like?</ask>
+<check>Else (no context data provided):</check>
+<action>Proceed with context gathering</action>
+<ask response="story_purpose">1. What's the purpose of this story? (e.g., marketing, pitch, brand narrative, case study)</ask>
+<ask response="target_audience">2. Who is your target audience?</ask>
+<ask response="key_messages">3. What key messages or takeaways do you want the audience to have?</ask>
+<ask>4. Any constraints? (length, tone, medium, existing brand guidelines)</ask>
+
+<critical>Wait for user response before proceeding. This context shapes the narrative approach.</critical>
+
+<template-output>story_purpose, target_audience, key_messages</template-output>
+
+</step>
+
+<step n="2" goal="Select Story Framework">
+
+<action>Load story frameworks from {story_frameworks} CSV file</action>
+<action>Parse: story_type, name, description, key_elements, best_for</action>
+
+Based on the context from Step 1, present framework options:
+
+<ask response="framework_selection">
+I can help craft your story using these proven narrative frameworks:
+
+**Transformation Narratives:**
+
+1. **Hero's Journey** - Classic transformation arc with adventure and return
+2. **Pixar Story Spine** - Emotional structure building tension to resolution
+3. **Customer Journey Story** - Before/after transformation narrative
+4. **Challenge-Overcome Arc** - Dramatic obstacle-to-victory structure
+
+**Strategic Narratives:** 5. **Brand Story** - Values, mission, and unique positioning 6. **Pitch Narrative** - Persuasive problem-to-solution structure 7. **Vision Narrative** - Future-focused aspirational story 8. **Origin Story** - Foundational narrative of how it began
+
+**Specialized Narratives:** 9. **Data Storytelling** - Transform insights into compelling narrative 10. **Emotional Hooks** - Craft powerful opening and touchpoints
+
+Which framework best fits your purpose? (Enter 1-10, or ask for my recommendation)
+</ask>
+
+<check>If user asks for recommendation:</check>
+<action>Analyze story_purpose, target_audience, and key_messages</action>
+<action>Recommend best-fit framework with clear rationale</action>
+<example>
+Based on your {{story_purpose}} for {{target_audience}}, I recommend:
+**{{framework_name}}** because {{rationale}}
+</example>
+
+<template-output>story_type, framework_name</template-output>
+
+</step>
+
+<step n="3" goal="Gather Story Elements">
+
+<critical>
+YOU ARE A MASTER STORYTELLER: Guide through narrative development using the Socratic method. Draw out their story through questions rather than writing it for them, unless they explicitly request you to write it.
+</critical>
+
+<storytelling-principles>
+  - Every great story has conflict/tension - Find the struggle
+  - Show, don't tell - Use vivid, concrete details
+  - Change is essential - What transforms?
+  - Emotion drives memory - Find the feeling
+  - Authenticity resonates - Stay true to core truth
+</storytelling-principles>
+
+Based on selected framework, gather key story elements:
+
+<action>Reference key_elements from selected story_type in CSV</action>
+<action>Parse key_elements (pipe-separated) into individual components</action>
+<action>Guide user through each element with targeted questions</action>
+
+<framework-specific-guidance>
+
+For Hero's Journey:
+
+- <ask>Who/what is the hero of this story?</ask>
+- <ask>What's their ordinary world before the adventure?</ask>
+- <ask>What call to adventure disrupts their world?</ask>
+- <ask>What trials/challenges do they face?</ask>
+- <ask>How are they transformed by the journey?</ask>
+- <ask>What wisdom do they bring back?</ask>
+
+For Pixar Story Spine:
+
+- <ask>Once upon a time, what was the situation?</ask>
+- <ask>Every day, what was the routine?</ask>
+- <ask>Until one day, what changed?</ask>
+- <ask>Because of that, what happened next?</ask>
+- <ask>And because of that? (continue chain)</ask>
+- <ask>Until finally, how was it resolved?</ask>
+
+For Brand Story:
+
+- <ask>What was the origin spark for this brand?</ask>
+- <ask>What core values drive every decision?</ask>
+- <ask>How does this impact customers/users?</ask>
+- <ask>What makes this different from alternatives?</ask>
+- <ask>Where is this heading in the future?</ask>
+
+For Pitch Narrative:
+
+- <ask>What's the problem landscape you're addressing?</ask>
+- <ask>What's your vision for the solution?</ask>
+- <ask>What proof/traction validates this approach?</ask>
+- <ask>What action do you want the audience to take?</ask>
+
+For Data Storytelling:
+
+- <ask>What context does the audience need?</ask>
+- <ask>What's the key data revelation/insight?</ask>
+- <ask>What patterns explain this insight?</ask>
+- <ask>So what? Why does this matter?</ask>
+- <ask>What actions should this insight drive?</ask>
+
+</framework-specific-guidance>
+
+<template-output>story_beats, character_voice, conflict_tension, transformation</template-output>
+
+</step>
+
+<step n="4" goal="Craft Emotional Arc">
+
+Stories stick when they resonate emotionally. Develop the emotional journey:
+
+<ask>What emotion should the audience feel at the beginning?</ask>
+<ask>What emotional shift happens at the turning point?</ask>
+<ask>What emotion should they carry away at the end?</ask>
+<ask>Where are the emotional peaks (high tension/joy)?</ask>
+<ask>Where are the valleys (low points/struggle)?</ask>
+
+<guide>Help them identify:
+
+- Relatable struggles that create empathy
+- Surprising moments that capture attention
+- Personal stakes that make it matter
+- Satisfying payoffs that create resolution
+  </guide>
+
+<template-output>emotional_arc, emotional_touchpoints</template-output>
+
+</step>
+
+<step n="5" goal="Develop Opening Hook">
+
+The first moment determines if they keep reading/listening.
+
+<ask>What surprising fact, question, or statement could open this story?</ask>
+<ask>What's the most intriguing part of this story to lead with?</ask>
+
+<guide>A strong hook:
+
+- Surprises or challenges assumptions
+- Raises an urgent question
+- Creates immediate relatability
+- Promises valuable payoff
+- Uses vivid, concrete details
+  </guide>
+
+<template-output>opening_hook</template-output>
+
+</step>
+
+<step n="6" goal="Write Core Narrative">
+
+<check>Ask if user wants to write or wants AI to write</check>
+
+<ask>Would you like to:
+
+1. Draft the story yourself with my guidance
+2. Have me write the first draft based on what we've discussed
+3. Co-create it iteratively together
+   </ask>
+
+<if selection="1">
+  <action>Provide writing prompts and encouragement</action>
+  <action>Offer feedback on drafts they share</action>
+  <action>Suggest refinements for clarity, emotion, flow</action>
+</if>
+
+<if selection="2">
+  <action>Synthesize all gathered elements</action>
+  <action>Write complete narrative in appropriate tone/style</action>
+  <action>Structure according to chosen framework</action>
+  <action>Include vivid details and emotional beats</action>
+  <action>Present draft for feedback and refinement</action>
+</if>
+
+<if selection="3">
+  <action>Write opening paragraph</action>
+  <action>Get feedback and iterate</action>
+  <action>Build section by section collaboratively</action>
+</if>
+
+<template-output>complete_story, core_narrative</template-output>
+
+</step>
+
+<step n="7" goal="Create Story Variations">
+
+Adapt the story for different contexts and lengths:
+
+<ask>What channels or formats will you use this story in?</ask>
+
+Based on response, create appropriate variations:
+
+1. **Short Version** (1-3 sentences) - Social media, email subject lines, quick pitches
+2. **Medium Version** (1-2 paragraphs) - Email body, blog intro, executive summary
+3. **Extended Version** (full narrative) - Articles, presentations, case studies, website
+
+<template-output>short_version, medium_version, extended_version</template-output>
+
+</step>
+
+<step n="8" goal="Usage Guidelines">
+
+Provide strategic guidance for story deployment:
+
+<ask>Where and how will you use this story?</ask>
+
+<guide>Consider:
+
+- Best channels for this story type
+- Audience-specific adaptations needed
+- Tone/voice consistency with brand
+- Visual or multimedia enhancements
+- Testing and feedback approach
+  </guide>
+
+<template-output>best_channels, audience_considerations, tone_notes, adaptation_suggestions</template-output>
+
+</step>
+
+<step n="9" goal="Refinement & Next Steps">
+
+Polish and plan forward:
+
+<ask>What parts of the story feel strongest?</ask>
+<ask>What areas could use more refinement?</ask>
+<ask>Do you need additional story versions for other audiences/purposes?</ask>
+<ask>How will you test this story with your audience?</ask>
+
+<template-output>refinement_opportunities, additional_versions, feedback_plan</template-output>
+
+</step>
+
+<step n="10" goal="Generate Final Output">
+
+Compile all story components into the structured template:
+
+1. Ensure all story versions are complete and polished
+2. Format according to template structure
+3. Include all strategic guidance and usage notes
+4. Verify tone and voice consistency
+5. Fill all template placeholders with actual content
+
+<template-output>agent_role, agent_name, user_name, date</template-output>
+
+</step>
+
+</workflow>

package/src/modules/cis/workflows/storytelling/story-types.csv

@@ -0,0 +1,26 @@
+category,story_type,name,description,key_questions
+transformation,hero-journey,Hero's Journey,Classic transformation arc following protagonist through adventure and return with wisdom,Who is the hero?|What's their ordinary world?|What call disrupts their world?|What trials do they face?|How are they transformed?
+transformation,pixar-spine,Pixar Story Spine,Emotional narrative structure using once upon a time framework that builds tension to resolution,Once upon a time what?|Every day what happened?|Until one day what changed?|Because of that what?|Until finally how resolved?
+transformation,customer-journey,Customer Journey,Narrative following customer transformation from pain point through solution to success,What was the before struggle?|What discovery moment occurred?|How did they implement?|What transformation happened?|What's their new reality?
+transformation,challenge-overcome,Challenge Overcome,Dramatic structure centered on confronting and conquering significant obstacles,What obstacle blocked progress?|How did stakes escalate?|What was the darkest moment?|What breakthrough occurred?|What was learned?
+transformation,character-arc,Character Arc,Personal evolution story showing growth through experience and struggle,Who are they at start?|What forces change?|What do they resist?|What breakthrough shifts them?|Who have they become?
+strategic,brand-story,Brand Story,Authentic narrative communicating brand values mission and unique market position,What sparked this brand?|What core values drive it?|How does it impact customers?|What makes it different?|Where is it heading?
+strategic,vision-narrative,Vision Narrative,Future-focused story painting vivid picture of desired state and path to get there,What's the current reality?|What opportunity emerges?|What's the bold vision?|What's the strategic path?|What does transformed future look like?
+strategic,origin-story,Origin Story,Foundational narrative explaining how something came to be and why it matters today,What was the spark moment?|What early struggles occurred?|What key breakthrough happened?|How did it evolve?|What's the current mission?
+strategic,positioning-story,Positioning Story,Narrative establishing unique market position and competitive differentiation,What market gap exists?|How are you uniquely qualified?|What makes your approach different?|Why should audience care?|What future do you enable?
+strategic,culture-story,Culture Story,Internal narrative defining organizational values behaviors and identity,What principles guide decisions?|What behaviors exemplify culture?|What stories illustrate values?|How do people experience it?|What culture are you building?
+persuasive,pitch-narrative,Pitch Narrative,Compelling story structure designed to inspire action investment or partnership,What problem landscape exists?|What's your vision for solution?|What proof validates approach?|What's the opportunity size?|What action do you want?
+persuasive,sales-story,Sales Story,Customer-centric narrative demonstrating value and building desire for solution,What pain do they feel?|How do you understand it?|What solution transforms situation?|What results can they expect?|What's the path forward?
+persuasive,change-story,Change Story,Narrative making case for transformation and mobilizing people through transition,Why can't we stay here?|What does better look like?|What's at stake if we don't?|How do we get there?|What's in it for them?
+persuasive,fundraising-story,Fundraising Story,Emotionally compelling narrative connecting donor values to mission impact,What problem breaks hearts?|What solution creates hope?|What impact will investment make?|Why is this urgent?|How can they help?
+persuasive,advocacy-story,Advocacy Story,Story galvanizing support for cause movement or policy change,What injustice demands attention?|Who is affected and how?|What change is needed?|What happens if we act?|How can they join?
+analytical,data-story,Data Storytelling,Transform data insights into compelling narrative with clear actionable takeaways,What context is needed?|What data reveals insight?|What patterns explain it?|So what why does it matter?|What actions should follow?
+analytical,case-study,Case Study,Detailed narrative documenting real-world application results and learnings,What was the situation?|What approach was taken?|What challenges emerged?|What results were achieved?|What lessons transfer?
+analytical,research-story,Research Narrative,Story structure presenting research findings in accessible engaging way,What question drove research?|How was it investigated?|What did you discover?|What does it mean?|What are implications?
+analytical,insight-narrative,Insight Narrative,Narrative revealing non-obvious truth or pattern that shifts understanding,What did everyone assume?|What did you notice?|What deeper pattern emerged?|Why does it matter?|What should change?
+analytical,process-story,Process Story,Behind-the-scenes narrative showing how something was made or accomplished,What was being created?|What approach was chosen?|What challenges arose?|How were they solved?|What was learned?
+emotional,hook-driven,Hook Driven,Story structure maximizing emotional engagement through powerful opening and touchpoints,What surprising fact opens?|What urgent question emerges?|Where are emotional peaks?|What creates relatability?|What payoff satisfies?
+emotional,conflict-resolution,Conflict Resolution,Narrative centered on tension building and satisfying resolution of core conflict,What's the central conflict?|Who wants what and why?|What prevents resolution?|How does tension escalate?|How is it resolved?
+emotional,empathy-story,Empathy Story,Story designed to create emotional connection and understanding of other perspectives,Whose perspective are we taking?|What do they experience?|What do they feel?|Why should audience care?|What common ground exists?
+emotional,human-interest,Human Interest,Personal story highlighting universal human experiences and emotions,Who is at the center?|What personal stakes exist?|What universal themes emerge?|What emotional journey occurs?|What makes it relatable?
+emotional,vulnerable-story,Vulnerable Story,Authentic personal narrative sharing struggle failure or raw truth to build connection,What truth is hard to share?|What struggle was faced?|What was learned?|Why share this now?|What hope does it offer?

package/src/modules/cis/workflows/storytelling/template.md

@@ -0,0 +1,113 @@
+# Story Output
+
+**Created:** {{date}}
+**Storyteller:** {{agent_role}} {{agent_name}}
+**Author:** {{user_name}}
+
+## Story Information
+
+**Story Type:** {{story_type}}
+
+**Framework Used:** {{framework_name}}
+
+**Purpose:** {{story_purpose}}
+
+**Target Audience:** {{target_audience}}
+
+## Story Structure
+
+### Opening Hook
+
+{{opening_hook}}
+
+### Core Narrative
+
+{{core_narrative}}
+
+### Key Story Beats
+
+{{story_beats}}
+
+### Emotional Arc
+
+{{emotional_arc}}
+
+### Resolution/Call to Action
+
+{{resolution}}
+
+## Complete Story
+
+{{complete_story}}
+
+## Story Elements Analysis
+
+### Character/Voice
+
+{{character_voice}}
+
+### Conflict/Tension
+
+{{conflict_tension}}
+
+### Transformation/Change
+
+{{transformation}}
+
+### Emotional Touchpoints
+
+{{emotional_touchpoints}}
+
+### Key Messages
+
+{{key_messages}}
+
+## Variations & Adaptations
+
+### Short Version (Tweet/Social)
+
+{{short_version}}
+
+### Medium Version (Email/Blog)
+
+{{medium_version}}
+
+### Extended Version (Article/Presentation)
+
+{{extended_version}}
+
+## Usage Guidelines
+
+### Best Channels
+
+{{best_channels}}
+
+### Audience Considerations
+
+{{audience_considerations}}
+
+### Tone & Voice Notes
+
+{{tone_notes}}
+
+### Adaptation Suggestions
+
+{{adaptation_suggestions}}
+
+## Next Steps
+
+### Refinement Opportunities
+
+{{refinement_opportunities}}
+
+### Additional Versions Needed
+
+{{additional_versions}}
+
+### Testing/Feedback Plan
+
+{{feedback_plan}}
+
+---
+
+_Story crafted using the BMAD CIS storytelling framework_

package/src/modules/cis/workflows/storytelling/workflow.yaml

@@ -0,0 +1,29 @@
+# Storytelling Workflow Configuration
+name: "storytelling"
+description: "Craft compelling narratives using proven story frameworks and techniques. This workflow guides users through structured narrative development, applying appropriate story frameworks to create emotionally resonant and engaging stories for any purpose."
+author: "BMad"
+
+# Critical variables load from config_source
+config_source: "{project-root}/bmad/cis/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+date: system-generated
+
+# Optional inputs for context
+recommended_inputs:
+  - story_context: "Context document passed via data attribute"
+  - previous_stories: "{output_folder}/story-*.md"
+
+# Context can be provided via data attribute when invoking
+# Example: data="{path}/brand-info.md" provides brand context
+
+# Module path and component files
+installed_path: "{project-root}/bmad/cis/workflows/storytelling"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+
+# Required Data Files
+story_frameworks: "{installed_path}/story-types.csv"
+
+# Output configuration
+default_output_file: "{output_folder}/story-{{date}}.md"

package/src/utility/models/agent-activation-ide.xml

@@ -0,0 +1,51 @@
+<activation critical="MANDATORY">
+  <init>
+    <step n="1">Load persona from this current file containing this activation you are reading now</step>
+    <step n="2">Override with {project-root}/bmad/_cfg/agents/{agent-filename} if exists (replace, not merge)</step>
+    <step n="3">Execute critical-actions section if present in current agent XML</step>
+    <step n="4">Show greeting + numbered list of ALL commands IN ORDER from current agent's cmds section</step>
+    <step n="5">CRITICAL HALT. AWAIT user input. NEVER continue without it.</step>
+  </init>
+  <commands critical="MANDATORY">
+    <input>Number → cmd[n] | Text → fuzzy match *commands</input>
+    <extract>exec, tmpl, data, action, run-workflow, validate-workflow</extract>
+    <handlers>
+      <handler type="run-workflow">
+        When command has: run-workflow="path/to/x.yaml" You MUST:
+        1. CRITICAL: Always LOAD {project-root}/bmad/core/tasks/workflow.md
+        2. READ its entire contents - the is the CORE OS for EXECUTING modules
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Follow workflow.md instructions EXACTLY as written
+        5. Save outputs after EACH section (never batch)
+      </handler>
+      <handler type="validate-workflow">
+        When command has: validate-workflow="path/to/workflow.yaml" You MUST:
+        1. You MUST LOAD the file at: {project-root}/bmad/core/tasks/validate-workflow.md
+        2. READ its entire contents and EXECUTE all instructions in that file
+        3. Pass the workflow, and also check the workflow location for a checklist.md to pass as the checklist
+        4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify
+      </handler>
+      <handler type="action">
+        When command has: action="#id" → Find prompt with id="id" in current agent XML, execute its content
+        When command has: action="text" → Execute the text directly as a critical action prompt
+      </handler>
+      <handler type="data">
+        When command has: data="path/to/x.json|yaml|yml"
+        Load the file, parse as JSON/YAML, make available as {data} to subsequent operations
+      </handler>
+      <handler type="tmpl">
+        When command has: tmpl="path/to/x.md"
+        Load file, parse as markdown with {{mustache}} templates, make available to action/exec/workflow
+      </handler>
+      <handler type="exec">
+        When command has: exec="path"
+        Actually LOAD and EXECUTE the file at that path - do not improvise
+      </handler>
+    </handlers>
+  </commands>
+  <rules critical="MANDATORY">
+    Stay in character until *exit
+    Number all option lists, use letters for sub-options
+    Load files ONLY when executing
+  </rules>
+</activation>

package/src/utility/models/agent-config-template.md

@@ -0,0 +1,23 @@
+```xml
+<agent-config name="" title="">
+
+    <llm critical="true">
+        <i>ALWAYS respond in {core:communication_language}.</i>
+    </llm>
+
+    <!-- Standard Agent Persona Configuration -->
+
+    <role></role>
+    <identity></identity>
+    <communication_style></communication_style>
+    <principles></principles>
+    <memories>
+        <memory>The users name is {core:user_name}</memory>
+    </memories>
+
+    <!-- User Added custom Agent Configuration Nodes -->
+
+    <!-- Agent-specific configuration nodes -->
+
+</agent-config>
+```

package/tools/cli/bmad-cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// Load package.json from root for version info
+const packageJson = require('../../package.json');
+
+// Load all command modules
+const commandsPath = path.join(__dirname, 'commands');
+const commandFiles = fs.readdirSync(commandsPath).filter((file) => file.endsWith('.js'));
+
+const commands = {};
+for (const file of commandFiles) {
+  const command = require(path.join(commandsPath, file));
+  commands[command.command] = command;
+}
+
+// Set up main program
+program.version(packageJson.version).description('BMAD Core CLI - Universal AI agent framework');
+
+// Register all commands
+for (const [name, cmd] of Object.entries(commands)) {
+  const command = program.command(name).description(cmd.description);
+
+  // Add options
+  for (const option of cmd.options || []) {
+    command.option(...option);
+  }
+
+  // Set action
+  command.action(cmd.action);
+}
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (process.argv.slice(2).length === 0) {
+  program.outputHelp();
+}