@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/agent/steps-c/step-04-persona.md

@@ -0,0 +1,213 @@
+---
+name: 'step-04-persona'
+description: 'Shape the agent personality through four-field persona system'
+
+# File References
+nextStepFile: './step-05-commands-menu.md'
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+personaProperties: ../data/persona-properties.md
+principlesCrafting: ../data/principles-crafting.md
+communicationPresets: ../data/communication-presets.csv
+
+# Example Personas (for reference)
+simpleExample: ../data/reference/without-sidecar/commit-poet.agent.yaml
+expertExample: ../data/reference/with-sidecar/journal-keeper/journal-keeper.agent.yaml
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# STEP GOAL
+
+Develop a complete four-field persona that defines the agent's personality, expertise, communication approach, and guiding principles. This persona becomes the foundation for how the agent thinks, speaks, and makes decisions.
+
+# MANDATORY EXECUTION RULES
+
+**CRITICAL: Field Purity Enforcement**
+- Each persona field has ONE specific purpose
+- NO mixing concepts between fields
+- NO overlapping responsibilities
+- Every field must be distinct and non-redundant
+
+**Output Requirements:**
+- Produce structured YAML block ready for agent.yaml
+- Follow principles-crafting guidance exactly
+- First principle MUST be the "expert activator"
+- All fields must be populated before proceeding
+
+# EXECUTION PROTOCOLS
+
+## Protocol 1: Load Reference Materials
+
+Read and integrate:
+- `personaProperties.md` - Field definitions and boundaries
+- `principlesCrafting.md` - Principles composition guidance
+- `communicationPresets.csv` - Style options and templates
+- Reference examples for pattern recognition
+
+## Protocol 2: Four-Field System Education
+
+Explain each field clearly:
+
+**1. Role (WHAT they do)**
+- Professional identity and expertise domain
+- Capabilities and knowledge areas
+- NOT personality or communication style
+- Pure functional definition
+
+**2. Identity (WHO they are)**
+- Character, personality, attitude
+- Emotional intelligence and worldview
+- NOT job description or communication format
+- Pure personality definition
+
+**3. Communication Style (HOW they speak)**
+- Language patterns, tone, voice
+- Formality, verbosity, linguistic preferences
+- NOT expertise or personality traits
+- Pure expression definition
+
+**4. Principles (WHY they act)**
+- Decision-making framework and values
+- Behavioral constraints and priorities
+- First principle = expert activator (core mission)
+- Pure ethical/operational definition
+
+## Protocol 3: Progressive Field Development
+
+### 3.1 Role Development
+- Define primary expertise domain
+- Specify capabilities and knowledge areas
+- Identify what makes them an "expert"
+- Keep it functional, not personal
+
+**Role Quality Checks:**
+- Can I describe their job without personality?
+- Would this fit in a job description?
+- Is it purely about WHAT they do?
+
+### 3.2 Identity Development
+- Define personality type and character
+- Establish emotional approach
+- Set worldview and attitude
+- Keep it personal, not functional
+
+**Identity Quality Checks:**
+- Can I describe their character without job title?
+- Would this fit in a character profile?
+- Is it purely about WHO they are?
+
+### 3.3 Communication Style Development
+- Review preset options from CSV
+- Select or customize style pattern
+- Define tone, formality, voice
+- Set linguistic preferences
+
+**Communication Quality Checks:**
+- Can I describe their speech patterns without expertise?
+- Is it purely about HOW they express themselves?
+- Would this fit in a voice acting script?
+
+### 3.4 Principles Development
+Follow `principlesCrafting.md` guidance:
+1. **Principle 1: Expert Activator** - Core mission and primary directive
+2. **Principle 2-5: Decision Framework** - Values that guide choices
+3. **Principle 6+: Behavioral Constraints** - Operational boundaries
+
+**Principles Quality Checks:**
+- Does first principle activate expertise immediately?
+- Do principles create decision-making clarity?
+- Would following these produce the desired behavior?
+
+## Protocol 4: Structured YAML Generation
+
+Output the four-field persona in this exact format:
+
+```yaml
+role: >
+  [Single sentence defining expertise and capabilities]
+
+identity: >
+  [2-3 sentences describing personality and character]
+
+communication_style: >
+  [Specific patterns for tone, formality, and voice]
+
+principles:
+  - [Expert activator - core mission]
+  - [Decision framework value 1]
+  - [Decision framework value 2]
+  - [Behavioral constraint 1]
+  - [Behavioral constraint 2]
+```
+
+# CONTEXT BOUNDARIES
+
+**Include in Persona:**
+- Professional expertise and capabilities (role)
+- Personality traits and character (identity)
+- Language patterns and tone (communication)
+- Decision-making values (principles)
+
+**Exclude from Persona:**
+- Technical skills (belongs in knowledge)
+- Tool usage (belongs in commands)
+- Workflow steps (belongs in orchestration)
+- Data structures (belongs in implementation)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+1. **LOAD** personaProperties.md and principlesCrafting.md
+2. **EXPLAIN** four-field system with clear examples
+3. **DEVELOP** Role - define expertise domain and capabilities
+4. **DEVELOP** Identity - establish personality and character
+5. **DEVELOP** Communication Style - select/customize style preset
+6. **DEVELOP** Principles - craft 5-7 principles following guidance
+7. **OUTPUT** structured YAML block for agent.yaml
+8. **DOCUMENT** to agent-plan.md
+9. **PRESENT** completion menu
+
+## 9. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [AR] Adversarial Review [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 AR: Execute {project-root}/_bmad/core/tasks/review-adversarial-general.xml — pass the current editPlan (or plan document in context) as the content to review; display findings with recommendations; then redisplay this menu
+- IF C: Save content to {agentPlan}, 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](#9-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 [all four persona fields populated with DISTINCT content and field purity verified], will you then load and read fully `{nextStepFile}` to execute and begin command structure design.
+
+---
+
+# SUCCESS METRICS
+
+**Completion Indicators:**
+- Four distinct, non-overlapping persona fields
+- First principle activates expert capabilities
+- Communication style is specific and actionable
+- YAML structure is valid and ready for agent.yaml
+- User confirms persona accurately reflects vision
+
+**Failure Indicators:**
+- Role includes personality traits
+- Identity includes job descriptions
+- Communication includes expertise details
+- Principles lack expert activator
+- Fields overlap or repeat concepts
+- User expresses confusion or disagreement

package/src/bmb/workflows/agent/steps-c/step-05-commands-menu.md

@@ -0,0 +1,179 @@
+---
+name: 'step-05-commands-menu'
+description: 'Build capabilities and command structure'
+
+# File References
+nextStepFile: './step-06-activation.md'
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+agentMenuPatterns: ../data/agent-menu-patterns.md
+
+# Example Menus (for reference)
+simpleExample: ../data/reference/without-sidecar/commit-poet.agent.yaml
+expertExample: ../data/reference/with-sidecar/journal-keeper/journal-keeper.agent.yaml
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# STEP GOAL
+
+Transform discovered capabilities into structured menu commands following BMAD menu patterns, creating the agent's interaction interface.
+
+# MANDATORY EXECUTION RULES
+
+1. **MUST** load agent-menu-patterns.md before any conversation
+2. **MUST** use menu patterns as structural templates
+3. **MUST** keep final menu YAML under 100 lines
+4. **MUST** include trigger, description, and handler/action for each command
+5. **MUST NOT** add help or exit commands (auto-injected)
+6. **MUST** document menu YAML in agent-plan before completion
+7. **MUST** complete Menu [A][P][C] verification
+
+# EXECUTION PROTOCOLS
+
+## Load Menu Patterns
+
+Read agentMenuPatterns file to understand:
+- Command structure requirements
+- YAML formatting standards
+- Handler/action patterns
+- Best practices for menu design
+
+## Capability Discovery Conversation
+
+Guide collaborative conversation to:
+1. Review capabilities from previous step
+2. Identify which capabilities become commands
+3. Group related capabilities
+4. Define command scope and boundaries
+
+Ask targeted questions:
+- "Which capabilities are primary commands vs secondary actions?"
+- "Can related capabilities be grouped under single commands?"
+- "What should each command accomplish?"
+- "How should commands be triggered?"
+
+## Command Structure Development
+
+For each command, define:
+
+1. **Trigger** - User-facing command name
+   - Clear, intuitive, following naming conventions
+   - Examples: `/analyze`, `/create`, `/review`
+
+2. **Description** - What the command does
+   - Concise (one line preferred)
+   - Clear value proposition
+   - Examples: "Analyze code for issues", "Create new document"
+
+3. **Handler/Action** - How command executes
+   - Reference to specific capability or skill
+   - Include parameters if needed
+   - Follow pattern from agent-menu-patterns.md
+
+## Structure Best Practices
+
+- **Group related commands** logically
+- **Prioritize frequently used** commands early
+- **Use clear, action-oriented** trigger names
+- **Keep descriptions** concise and valuable
+- **Match handler names** to actual capabilities
+
+## Document Menu YAML
+
+Create structured menu YAML following format from agent-menu-patterns.md:
+
+```yaml
+menu:
+  commands:
+    - trigger: "/command-name"
+      description: "Clear description of what command does"
+      handler: "specific_capability_or_skill"
+      parameters:
+        - name: "param_name"
+          description: "Parameter description"
+          required: true/false
+```
+
+## Menu [A][P][C] Verification
+
+**[A]ccuracy**
+- All commands match defined capabilities
+- Triggers are clear and intuitive
+- Handlers reference actual capabilities
+
+**[P]attern Compliance**
+- Follows agent-menu-patterns.md structure
+- YAML formatting is correct
+- No help/exit commands included
+
+**[C]ompleteness**
+- All primary capabilities have commands
+- Commands cover agent's core functions
+- Menu is ready for next step
+
+# CONTEXT BOUNDARIES
+
+- **Focus on command structure**, not implementation details
+- **Reference example menus** for patterns, not copying
+- **Keep menu concise** - better fewer, clearer commands
+- **User-facing perspective** - triggers should feel natural
+- **Capability alignment** - every command maps to a capability
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+1. Load agent-menu-patterns.md to understand structure
+2. Review capabilities from agent-plan step 3
+3. Facilitate capability-to-command mapping conversation
+4. Develop command structure for each capability
+5. Define trigger, description, handler for each command
+6. Verify no help/exit commands (auto-injected)
+7. Document structured menu YAML to agent-plan
+8. Complete Menu [A][P][C] verification
+9. Confirm readiness for next step
+
+## 10. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [AR] Adversarial Review [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 AR: Execute {project-root}/_bmad/core/tasks/review-adversarial-general.xml — pass the current editPlan (or plan document in context) as the content to review; display findings with recommendations; then redisplay this menu
+- IF C: Save content to {agentPlan}, 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](#10-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 [menu YAML documented in agent-plan and all commands have trigger/description/handler], will you then load and read fully `{nextStepFile}` to execute and begin activation planning.
+
+---
+
+# SUCCESS METRICS
+
+✅ Menu YAML documented in agent-plan
+✅ All commands have trigger, description, handler
+✅ Menu follows agent-menu-patterns.md structure
+✅ No help/exit commands included
+✅ Menu [A][P][C] verification passed
+✅ Ready for activation phase
+
+# FAILURE INDICATORS
+
+❌ Menu YAML missing from agent-plan
+❌ Commands missing required elements (trigger/description/handler)
+❌ Menu doesn't follow pattern structure
+❌ Help/exit commands manually added
+❌ Menu [A][P][C] verification failed
+❌ Unclear command triggers or descriptions

package/src/bmb/workflows/agent/steps-c/step-06-activation.md

@@ -0,0 +1,278 @@
+---
+name: 'step-06-activation'
+description: 'Plan activation behavior and route to build'
+
+# File References
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+criticalActions: ../data/critical-actions.md
+
+# Build Step Route (determined by hasSidecar)
+agentBuild: './step-07-build-agent.md'
+
+# Example critical_actions (for reference)
+withSidecarExample: ../data/reference/with-sidecar/journal-keeper/journal-keeper.agent.yaml
+withoutSidecarExample: ../data/reference/without-sidecar/commit-poet.agent.yaml
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# STEP GOAL
+
+Define activation behavior through critical_actions and confirm routing to the build step based on hasSidecar decision.
+
+# MANDATORY EXECUTION RULES
+
+1. **MUST Load Reference Documents** Before any discussion
+   - Read criticalActions.md to understand activation patterns
+   - Read agentPlan to access all accumulated metadata
+   - These are non-negotiable prerequisites
+
+2. **MUST Confirm hasSidecar Decision**
+   - Check `hasSidecar` from plan metadata (decided in Step 3)
+   - This determines the build approach
+   - Inform user of routing decision
+
+3. **MUST Document Activation Decision**
+   - Either define critical_actions array explicitly
+   - OR document deliberate omission with rationale
+   - No middle ground - commit to one path
+
+4. **MUST Follow Simple Routing Logic**
+   ```yaml
+   # Route determination based on hasSidecar only
+   hasSidecar: false → Agent without sidecar (single YAML file)
+   hasSidecar: true → Agent with sidecar (YAML + sidecar folder)
+   ```
+
+5. **NEVER Skip Documentation**
+   - Every decision about activation must be recorded
+   - Every routing choice must be justified
+   - Plan file must reflect final state
+
+# EXECUTION PROTOCOLS
+
+## Protocol 1: Reference Loading
+Execute BEFORE engaging user:
+
+1. Load criticalActions.md
+2. Load agentPlan-{agent_name}.md
+3. Extract routing metadata:
+   - hasSidecar (boolean) - decided in Step 3
+   - All other metadata from prior steps
+4. Confirm build approach
+
+## Protocol 2: Routing Disclosure
+Inform user immediately of determined route:
+
+```
+"Based on your agent configuration:
+- hasSidecar: {hasSidecar}
+
+→ Building: Agent {WITH|WITHOUT} sidecar
+
+Now let's plan your activation behavior..."
+```
+
+## Protocol 3: Activation Planning
+Guide user through decision:
+
+1. **Explain critical_actions Purpose**
+   - What they are: autonomous triggers the agent can execute
+   - When they're useful: proactive capabilities, workflows, utilities
+   - When they're unnecessary: simple assistants, pure responders
+
+2. **Discuss Agent's Activation Needs**
+   - Does this agent need to run independently?
+   - Should it initiate actions without prompts?
+   - What workflows or capabilities should it trigger?
+
+3. **Decision Point**
+   - Define specific critical_actions if needed
+   - OR explicitly opt-out with rationale
+
+## Protocol 4: Documentation
+Update agentPlan with activation metadata:
+
+```yaml
+# Add to agent metadata
+activation:
+  hasCriticalActions: true/false
+  rationale: "Explanation of why or why not"
+  criticalActions: []  # Only if hasCriticalActions: true
+
+routing:
+  buildApproach: "Agent {with|without} sidecar"
+  hasSidecar: {boolean}
+```
+
+# CONTEXT BOUNDARIES
+
+## In Scope
+- Planning activation behavior for the agent
+- Defining critical_actions array
+- Confirming routing to build step
+- Documenting activation decisions
+
+## Out of Scope
+- Writing actual activation code (build step)
+- Designing sidecar workflows (build step)
+- Changing core agent metadata (locked after Step 4)
+- Implementing commands (build step)
+
+## Routing Boundaries
+- **Agent WITHOUT sidecar**: Single YAML file, no persistent memory
+- **Agent WITH sidecar**: YAML file + sidecar folder with persistent memory
+
+---
+
+# MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+## 1. Load Reference Documents
+```bash
+# Read these files FIRST
+cat {criticalActions}
+cat {agentPlan}
+```
+
+## 2. Confirm Routing Decision
+Verify hasSidecar decision from Step 3:
+
+```
+"Confirming your agent configuration from Step 3:
+- hasSidecar: {value from plan}
+- This means: {Agent will|will not} remember things between sessions
+- Build approach: {Single YAML file|YAML + sidecar folder}
+
+Is this still correct?"
+```
+
+## 3. Discuss Activation Needs
+Ask user:
+- "Should your agent be able to take autonomous actions?"
+- "Are there specific workflows it should trigger?"
+- "Should it run as a background process or scheduled task?"
+- "Or will it primarily respond to direct prompts?"
+
+## 4. Define critical_actions OR Explicitly Omit
+
+**If defining:**
+- Reference criticalActions.md patterns
+- List 3-7 specific actions
+- Each action should be clear and scoped
+- Document rationale for each
+
+**For agents WITH sidecar, critical_actions MUST include:**
+```
+- "Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md"
+- "Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md"
+- "ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/ - private space"
+```
+Plus any additional activation behaviors the agent needs.
+
+**For agents WITHOUT sidecar, critical_actions are OPTIONAL and can include:**
+```
+- "Give user an inspirational quote before showing menu"
+- "Fetch latest data from {project-root}/finances/ before displaying menu"
+- "Display a quick status summary on activation"
+```
+Agents without sidecar omit critical_actions entirely if no activation behavior is needed.
+
+**If omitting:**
+- State clearly: "This agent will not have critical_actions"
+- Explain why: "This agent is a responsive assistant that operates under direct user guidance"
+- Document the rationale
+
+## 5. Document to Plan
+
+Update agentPlan with:
+
+```yaml
+---
+activation:
+  hasCriticalActions: {true/false}
+  rationale: "Agent needs to autonomously trigger workflows for task automation" OR "Agent operates under direct user guidance"
+  criticalActions:
+    - name: "start-workflow"
+      description: "Initiate a predefined workflow for task execution"
+    # ... additional actions if needed
+
+routing:
+  buildApproach: "Agent {with|without} sidecar"
+  hasSidecar: {true/false}
+  rationale: "Agent {needs|does not need} persistent memory across sessions"
+---
+```
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [AR] Adversarial Review [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 AR: Execute {project-root}/_bmad/core/tasks/review-adversarial-general.xml — pass the current editPlan (or plan document in context) as the content to review; display findings with recommendations; then redisplay this menu
+- IF C: Save content to {agentPlan}, update frontmatter, then only then load, read entire file, then execute {agentBuild}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-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
+
+This is the **final planning step** before building. ONLY WHEN [C continue option] is selected and [activation needs documented], will you then load and read fully `{agentBuild}` to execute and build the agent.
+
+Routing logic:
+- hasSidecar: false → Agent WITHOUT sidecar (single YAML)
+- hasSidecar: true → Agent WITH sidecar (YAML + sidecar folder)
+
+You cannot proceed to build without completing activation planning.
+
+---
+
+# SUCCESS METRICS
+
+✅ **COMPLETION CRITERIA:**
+- [ ] criticalActions.md loaded and understood
+- [ ] agentPlan loaded with all prior metadata
+- [ ] Routing decision confirmed (hasSidecar from Step 3)
+- [ ] Activation needs discussed with user
+- [ ] critical_actions defined OR explicitly omitted with rationale
+- [ ] Plan updated with activation and routing metadata
+- [ ] User confirms ready to build
+
+✅ **SUCCESS INDICATORS:**
+- Clear activation decision documented
+- Route to build is unambiguous
+- User understands the build approach
+- Plan file reflects complete activation configuration
+
+❌ **FAILURE MODES:**
+- Attempting to define critical_actions without reading reference
+- Routing decision not documented in plan
+- User doesn't understand the build approach
+- Ambiguous activation configuration (neither defined nor omitted)
+- Skipping activation discussion entirely
+
+⚠️ **RECOVERY PATHS**
+If activation planning goes wrong:
+
+1. **Can't decide on activation?**
+   - Default: Omit critical_actions
+   - Can add later via edit-agent workflow
+
+2. **User wants to change hasSidecar?**
+   - Return to Step 3 to revise decision
+   - Update plan accordingly
+
+3. **Uncertain about routing?**
+   - Check hasSidecar value
+   - Apply simple routing logic