@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/agent/steps-v/v-02e-validate-sidecar.md

@@ -0,0 +1,134 @@
+---
+name: 'v-02e-validate-sidecar'
+description: 'Validate sidecar structure and append to report'
+
+nextStepFile: './v-03-summary.md'
+validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
+agentValidation: ../data/agent-validation.md
+criticalActions: ../data/critical-actions.md
+agentFile: '{agent-file-path}'
+sidecarFolder: '{agent-sidecar-folder}'
+---
+
+# Validate Step 2e: Validate Sidecar
+
+## STEP GOAL
+
+Validate the agent's sidecar structure (if hasSidecar: true) against BMAD standards as defined in agentValidation.md. Append findings to validation report and auto-advance.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Read validationReport and agentValidation first
+- 🔄 CRITICAL: Load the actual agent file to check for sidecar
+- 🚫 NO MENU - append findings and auto-advance
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Step-Specific Rules:
+
+- 🎯 Validate sidecar against agentValidation.md rules (for agents with sidecar)
+- 📊 Append findings to validation report
+- 🚫 FORBIDDEN to present menu
+
+## EXECUTION PROTOCOLS
+
+- 🎯 Load agentValidation.md reference
+- 🎯 Load the actual agent file for validation
+- 📊 Validate sidecar if hasSidecar: true, skip for hasSidecar: false
+- 💾 Append findings to validation report
+- ➡️ Auto-advance to summary step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load References
+
+Read `{agentValidation}`, `{criticalActions}`, `{validationReport}`, and `{agentFile}`.
+
+### 2. Conditional Validation
+
+**IF hasSidecar = true:**
+Perform these checks systematically - validate EVERY rule specified in agentValidation.md:
+
+#### A. Sidecar Folder Validation
+- [ ] Sidecar folder exists at specified path
+- [ ] Sidecar folder is accessible and readable
+- [ ] Sidecar folder path in metadata matches actual location
+- [ ] Folder naming follows convention: `{agent-name}-sidecar`
+
+#### B. Sidecar File Inventory
+- [ ] List all files in sidecar folder
+- [ ] Verify expected files are present (memories.md, instructions.md recommended)
+- [ ] Check for unexpected files
+- [ ] Validate file names follow conventions
+
+#### C. Path Reference Validation
+For each sidecar path reference in agent YAML:
+- [ ] Extract path from YAML reference
+- [ ] Verify path format is correct: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
+- [ ] `{project-root}` is literal
+- [ ] `{sidecar-folder}` is actual folder name
+- [ ] Validate no broken path references
+
+#### D. Critical Actions Validation (MANDATORY for hasSidecar: true)
+- [ ] critical_actions section exists in agent YAML
+- [ ] Contains at minimum 3 actions
+- [ ] Loads sidecar memories: `{project-root}/_bmad/_memory/{sidecar-folder}/memories.md`
+- [ ] Loads sidecar instructions: `{project-root}/_bmad/_memory/{sidecar-folder}/instructions.md`
+- [ ] Restricts file access: `ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/`
+- [ ] No placeholder text in critical_actions
+- [ ] No compiler-injected steps
+
+#### E. Sidecar Structure Completeness
+- [ ] All referenced sidecar files present
+- [ ] No orphaned references (files referenced but not present)
+- [ ] No unreferenced files (files present but not referenced)
+- [ ] File structure matches agent requirements
+
+**IF hasSidecar = false:**
+- [ ] Mark sidecar validation as N/A
+- [ ] Confirm no sidecar-folder path in metadata
+- [ ] Confirm no sidecar references in critical_actions (if present)
+- [ ] Confirm no sidecar references in menu handlers
+
+### 3. Append Findings to Report
+
+Append to `{validationReport}`:
+
+```markdown
+### Sidecar Validation
+
+**Status:** {✅ PASS / ⚠️ WARNING / ❌ FAIL / N/A}
+
+**hasSidecar:** {true|false}
+
+**Checks:**
+- [ ] metadata.sidecar-folder present (if hasSidecar: true)
+- [ ] Sidecar path format correct: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
+- [ ] Sidecar files exist at specified path (if hasSidecar: true)
+- [ ] All referenced files present
+- [ ] No broken path references
+
+**Detailed Findings:**
+
+*PASSING (for agents WITH sidecar):*
+{List of passing checks}
+
+*WARNINGS:*
+{List of non-blocking issues}
+
+*FAILURES:*
+{List of blocking issues that must be fixed}
+
+*N/A (for agents WITHOUT sidecar):*
+N/A - Agent has hasSidecar: false, no sidecar required
+```
+
+### 4. Auto-Advance
+
+Load and execute `{nextStepFile}` immediately.
+
+---
+
+**Compiling validation summary...**

package/src/bmb/workflows/agent/steps-v/v-03-summary.md

@@ -0,0 +1,104 @@
+---
+name: 'v-03-summary'
+description: 'Display complete validation report and offer next steps'
+
+validationReport: '{bmb_creations_output_folder}/validation-report-{agent-name}.md'
+
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Validate Step 3: Validation Summary
+
+## STEP GOAL:
+
+Display the complete validation report to the user and offer options for fixing issues or improving the agent.
+
+## MANDATORY EXECUTION RULES:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Read validationReport to display findings
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Step-Specific Rules:
+
+- 🎯 Display complete validation report clearly
+- 📊 Offer options for fixing issues
+- 💬 Present next step choices
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Read validation report to collect all findings
+- 📊 Display organized summary
+- 💾 Allow user to decide next steps
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Validation Report
+
+Read `{validationReport}` to collect all validation findings.
+
+### 2. Display Complete Report
+
+```markdown
+## Validation Complete: {agent-name}
+
+### Overall Status
+
+{Summary table: Metadata | Persona | Menu | Structure | Sidecar}
+
+### Detailed Findings
+
+{Display all sections from the validation report}
+```
+
+### 3. Present Next Steps
+
+"What would you like to do?
+
+**[E]dit Agent** - Launch edit workflow to fix issues or make improvements
+**[F]ix in Place** - Confirm which fixes you would like right now and we can fix without loading the full agent edit workflow
+**[S]ave Report** - Save this validation report and exit
+**[R]etry** - Run validation again (if you've made external changes)"
+
+### 4. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [E] Edit Agent [S] Save & Exit [R] Retry Validation"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF E: Inform user they can launch edit workflow with the same agent file, then redisplay menu
+- IF F; Attempt to make users desired fixes without loading the full edit workflow
+- IF S: Save final report to {validationReport} and end workflow
+- IF R: Restart validation from step v-01
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#4-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+The validation workflow is complete when user selects [S] to save the report, or [E] to proceed to edit workflow.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete validation report displayed
+- All findings clearly organized
+- User offered clear next steps
+
+### ❌ SYSTEM FAILURE:
+
+- Findings not displayed to user
+- No clear next steps offered
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/bmb/workflows/agent/templates/agent-plan.template.md

@@ -0,0 +1,5 @@
+---
+stepsCompleted: []
+---
+
+# Agent Design and Build Plan

package/src/bmb/workflows/agent/templates/agent-template.md

@@ -0,0 +1,89 @@
+{{#if comment}}
+------------------------------------------------------------------------------
+Agent Handlebars Template (Unified)
+Used by: step-07-build-agent.md to generate final agent YAML
+Documentation: ../data/agent-architecture.md
+------------------------------------------------------------------------------
+{{/if}}
+agent:
+  metadata:
+    id: {{agent_id}}
+    name: {{agent_name}}
+    title: {{agent_title}}
+    icon: {{agent_icon}}
+    module: {{agent_module}}{{#if agent_module_comment}}  {{!-- stand-alone, bmm, cis, bmgd, or other module --}}{{/if}}
+    hasSidecar: {{has_sidecar}}{{#if has_sidecar_comment}}  {{!-- true if agent has a sidecar folder, false otherwise --}}{{/if}}
+    {{#if has_sidecar}}
+    sidecar-folder: {{sidecar_folder}}
+    sidecar-path: '{project-root}/_bmad/_memory/{{sidecar_folder}}/'
+    {{/if}}
+
+  persona:
+    role: |
+      {{persona_role}}{{#if persona_role_note}}
+      {{!-- 1-2 sentences, first person, what the agent does --}}{{/if}}
+
+    identity: |
+      {{persona_identity}}{{#if persona_identity_note}}
+      {{!-- 2-5 sentences, first person, background/specializations --}}{{/if}}
+
+    communication_style: |
+      {{communication_style}}{{#if communication_style_note}}
+      {{!-- How the agent speaks: tone, voice, mannerisms --}}
+      {{#if has_sidecar}}
+      {{!-- Include memory reference patterns: "Last time you mentioned..." or "I've noticed patterns..." --}}
+      {{/if}}
+      {{/if}}
+
+    principles:
+      {{#each principles}}
+      - {{this}}
+      {{/each}}
+
+  {{#if has_critical_actions}}
+  critical_actions:
+    {{#each critical_actions}}
+    - '{{{this}}}'
+    {{/each}}
+  {{/if}}
+
+  {{#if has_prompts}}
+  prompts:
+    {{#each prompts}}
+    - id: {{id}}
+      content: |
+        {{{content}}}
+    {{/each}}
+  {{/if}}
+
+  menu:
+    {{#each menu_items}}
+    - trigger: {{trigger_code}} or fuzzy match on {{trigger_command}}
+      {{#if action_is_prompt}}
+      action: '#{{action_id}}'
+      {{else if action_updates_sidecar}}
+      action: {{{action_inline}}}
+      {{else}}
+      action: {{{action_inline}}}
+      {{/if}}
+      description: '[{{trigger_code}}] {{{description}}}'
+    {{/each}}
+
+  {{#if has_install_config}}
+  install_config:
+    compile_time_only: true
+    description: '{{install_description}}'
+    questions:
+      {{#each install_questions}}
+      - var: {{var_name}}
+        prompt: '{{prompt}}'
+        type: {{question_type}}{{#if question_options}}
+        options:
+          {{#each question_options}}
+          - label: '{{label}}'
+            value: '{{value}}'
+          {{/each}}
+        {{/if}}
+        default: {{{default_value}}}
+      {{/each}}
+  {{/if}}

package/src/bmb/workflows/agent/workflow-create-agent.md

@@ -0,0 +1,72 @@
+---
+name: create-agent
+description: Create a new BMAD agent with best practices and compliance
+web_bundle: true
+createWorkflow: './steps-c/step-01-brainstorm.md'
+---
+
+# Create Agent
+
+**Goal:** Collaboratively create BMAD Core compliant agents through guided discovery and systematic execution.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an expert agent architect specializing in BMAD Core agent creation. You guide users through creating new agents with best practices and full compliance.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file
+- **Just-In-Time Loading**: Only the current step file is in memory
+- **Sequential Enforcement**: Steps completed in order
+- **State Tracking**: Document progress in tracking files (agentPlan)
+- **Mode-Aware Routing**: Create-specific step flow
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute numbered sections in order
+3. **WAIT FOR INPUT**: Halt at menus and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed when user selects appropriate option
+5. **SAVE STATE**: Update progress before loading next step
+6. **LOAD NEXT**: When directed, load and execute the next step file
+
+### Critical Rules
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps unless explicitly optional
+- 💾 **ALWAYS** save progress and outputs
+- 🎯 **ALWAYS** follow exact instructions in step files
+- ⏸️ **ALWAYS** halt at menus and wait for input
+- 📋 **NEVER** pre-load future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. Route to Create Workflow
+
+"**Create Mode: Building a new BMAD Core compliant agent from scratch.**"
+
+Load, read completely, then execute `{createWorkflow}` (steps-c/step-01-brainstorm.md)
+
+---
+
+## CREATE MODE NOTES
+
+- Starts with optional brainstorming
+- Progresses through discovery, metadata, persona, commands, activation
+- Builds agent based on type (Simple/Expert/Module)
+- Validates built agent
+- Celebrates completion with installation guidance

package/src/bmb/workflows/agent/workflow-edit-agent.md

@@ -0,0 +1,75 @@
+---
+name: edit-agent
+description: Edit existing BMAD agents while maintaining compliance
+web_bundle: true
+editWorkflow: './steps-e/e-01-load-existing.md'
+---
+
+# Edit Agent
+
+**Goal:** Modify existing BMAD Core compliant agents while maintaining their integrity and compliance.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an expert agent architect specializing in BMAD Core agent lifecycle management. You guide users through editing existing agents while preserving their core functionality and compliance.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file
+- **Just-In-Time Loading**: Only the current step file is in memory
+- **Sequential Enforcement**: Steps completed in order
+- **State Tracking**: Document progress in tracking files (editPlan)
+- **Mode-Aware Routing**: Edit-specific step flow
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute numbered sections in order
+3. **WAIT FOR INPUT**: Halt at menus and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed when user selects appropriate option
+5. **SAVE STATE**: Update progress before loading next step
+6. **LOAD NEXT**: When directed, load and execute the next step file
+
+### Critical Rules
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps unless explicitly optional
+- 💾 **ALWAYS** save progress and outputs
+- 🎯 **ALWAYS** follow exact instructions in step files
+- ⏸️ **ALWAYS** halt at menus and wait for input
+- 📋 **NEVER** pre-load future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. Route to Edit Workflow
+
+"**Edit Mode: Modifying an existing BMAD Core compliant agent.**"
+
+Prompt for agent file path: "Which agent would you like to edit? Please provide the path to the `.agent.yaml` file."
+
+Then load, read completely, and execute `{editWorkflow}` (steps-e/e-01-load-existing.md)
+
+---
+
+## EDIT MODE NOTES
+
+- Loads existing agent first
+- Discovers what user wants to change
+- Validates current agent before editing
+- Creates structured edit plan
+- Applies changes with validation
+- Celebrates successful edit

package/src/bmb/workflows/agent/workflow-validate-agent.md

@@ -0,0 +1,73 @@
+---
+name: validate-agent
+description: Validate existing BMAD agents and offer to improve deficiencies
+web_bundle: true
+validateWorkflow: './steps-v/v-01-load-review.md'
+---
+
+# Validate Agent
+
+**Goal:** Review existing BMAD Core compliant agents through systematic validation and generate comprehensive reports.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a validation specialist and quality assurance expert for BMAD Core agents. You conduct systematic reviews and provide actionable improvement recommendations.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file
+- **Just-In-Time Loading**: Only the current step file is in memory
+- **Sequential Enforcement**: Steps completed in order
+- **State Tracking**: Document progress in tracking files (validationReport)
+- **Mode-Aware Routing**: Validate-specific step flow
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute numbered sections in order
+3. **WAIT FOR INPUT**: Halt at menus and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed when user selects appropriate option
+5. **SAVE STATE**: Update progress before loading next step
+6. **LOAD NEXT**: When directed, load and execute the next step file
+
+### Critical Rules
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps unless explicitly optional
+- 💾 **ALWAYS** save progress and outputs
+- 🎯 **ALWAYS** follow exact instructions in step files
+- ⏸️ **ALWAYS** halt at menus and wait for input
+- 📋 **NEVER** pre-load future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### 2. Route to Validate Workflow
+
+"**Validate Mode: Reviewing an existing BMAD Core compliant agent.**"
+
+Prompt for agent file path: "Which agent would you like to validate? Please provide the path to the `.agent.yaml` file."
+
+Then load, read completely, and execute `{validateWorkflow}` (steps-v/v-01-load-review.md)
+
+---
+
+## VALIDATE MODE NOTES
+
+- Loads existing agent
+- Runs systematic validation (metadata, persona, menu, structure, sidecar)
+- Generates comprehensive validation report
+- Offers option to apply fixes if user desires