@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/agent/steps-c/step-07-build-agent.md

@@ -0,0 +1,316 @@
+---
+name: 'step-07-build-agent'
+description: 'Generate agent YAML from plan (with or without sidecar)'
+
+# File References
+nextStepFile: './step-08-celebrate.md'
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+
+# Output paths (determined by hasSidecar)
+agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}/'
+agentYamlOutput: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
+agentYamlOutputNoSidecar: '{bmb_creations_output_folder}/{agent-name}.agent.yaml'
+sidecarOutput: '{bmb_creations_output_folder}/{agent-name}/{agent-name}-sidecar/'
+
+# Template and Architecture
+agentTemplate: ../templates/agent-template.md
+agentArch: ../data/agent-architecture.md
+agentCompilation: ../data/agent-compilation.md
+criticalActions: ../data/critical-actions.md
+
+# Reference examples
+noSidecarExample: ../data/reference/without-sidecar/commit-poet.agent.yaml
+withSidecarExample: ../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
+
+Assemble the agent plan content into a complete agent YAML file. The build approach (with or without sidecar) is determined by the `hasSidecar` decision made in Step 3.
+
+---
+
+# MANDATORY EXECUTION RULES
+
+1. **DETERMINE BUILD APPROACH FIRST**: Check `hasSidecar` from agentPlan before starting
+2. **TEMPLATE COMPLIANCE**: Follow agent-template.md structure exactly
+3. **YAML VALIDATION**: Ensure valid YAML syntax with proper indentation (2-space)
+4. **EXISTING CHECK**: If output file exists, ask user before overwriting
+5. **NO DRIFT**: Use ONLY content from agentPlan - no additions or interpretations
+6. **SIDECAR REQUIREMENT**: If hasSidecar=true, MUST create sidecar folder structure
+
+---
+
+# EXECUTION PROTOCOLS
+
+## Phase 1: Load Architecture and Templates
+1. Read `agentTemplate` - defines YAML structure for agents
+2. Read `agentArch` - architecture requirements for agents
+3. Read `agentCompilation` - assembly rules for YAML generation
+4. Read `criticalActions` - validation requirements for critical_actions
+
+## Phase 2: Load Agent Plan
+1. Read `agentPlan` containing all collected content from Steps 2-5
+2. Verify plan contains:
+   - hasSidecar decision (true/false)
+   - Persona content
+   - Commands structure
+   - All metadata fields
+   - Activation decisions (critical_actions)
+
+## Phase 3: Determine Build Approach
+
+Check `hasSidecar` from plan:
+
+```yaml
+hasSidecar: false
+→ Build: Agent WITHOUT sidecar
+→ Output: Single YAML file at {agentYamlOutputNoSidecar}
+→ Structure: Everything in one file (~250 lines max)
+
+hasSidecar: true
+→ Build: Agent WITH sidecar
+→ Output: YAML + sidecar folder structure
+→ Structure: YAML file + {agent-name}-sidecar/ folder
+```
+
+**Inform user of build approach:**
+```
+"Building: Agent {WITH|WITHOUT} sidecar
+hasSidecar: {true/false}
+Output: {output path description}"
+```
+
+## Phase 4: Assemble Agent YAML
+
+### For Agents WITHOUT Sidecar (hasSidecar: false)
+
+**Structure:**
+```yaml
+name: '{agent-name}'
+description: '{short-description}'
+
+author:
+  name: '{author}'
+  created: '{date}'
+
+persona: |
+  {multi-line persona content from plan}
+
+system-context: |
+  {expanded context from plan}
+
+capabilities:
+  - {capability from plan}
+  - {capability from plan}
+  # ... all capabilities
+
+commands:
+  - name: '{command-name}'
+    description: '{what command does}'
+    trigger: '{menu trigger}'
+    steps:
+      - {step 1}
+      - {step 2}
+    # ... all commands from plan
+
+configuration:
+  temperature: {temperature}
+  max-tokens: {max-tokens}
+  response-format: {format}
+  # ... other configuration from plan
+
+metadata:
+  hasSidecar: false
+  agent-type: 'agent'
+```
+
+**Output:** Single YAML file at `{agentYamlOutputNoSidecar}`
+
+### For Agents WITH Sidecar (hasSidecar: true)
+
+**Structure:**
+```yaml
+name: '{agent-name}'
+description: '{short-description}'
+
+author:
+  name: '{author}'
+  created: '{date}'
+
+persona: |
+  {multi-line persona content from plan}
+
+system-context: |
+  {expanded context from plan}
+
+capabilities:
+  - {capability from plan}
+  - {capability from plan}
+  # ... all capabilities
+
+critical-actions:
+  - name: '{action-name}'
+    description: '{what it does}'
+    invocation: '{when/how to invoke}'
+    implementation: |
+      {multi-line implementation}
+    output: '{expected-output}'
+    sidecar-folder: '{sidecar-folder-name}'
+    sidecar-files:
+      - '{project-root}/_bmad/_memory/{sidecar-folder}/{file1}.md'
+      - '{project-root}/_bmad/_memory/{sidecar-folder}/{file2}.md'
+  # ... all critical actions referencing sidecar structure
+
+commands:
+  - name: '{command-name}'
+    description: '{what command does}'
+    trigger: '{menu trigger}'
+    steps:
+      - {step 1}
+      - {step 2}
+    # ... all commands from plan
+
+configuration:
+  temperature: {temperature}
+  max-tokens: {max-tokens}
+  response-format: {format}
+  # ... other configuration from plan
+
+metadata:
+  sidecar-folder: '{sidecar-folder-name}'
+  sidecar-path: '{project-root}/_bmad/_memory/{sidecar-folder}/'
+  hasSidecar: true
+  agent-type: 'agent'
+  memory-type: 'persistent'
+```
+
+**Output:** YAML file at `{agentYamlOutput}` + sidecar folder structure
+
+### Phase 5: Create Sidecar Structure (IF hasSidecar: true)
+
+Skip this phase if hasSidecar: false
+
+1. **Create Sidecar Directory**:
+   ```bash
+   mkdir -p {sidecarOutput}
+   ```
+
+2. **Create Starter Files** (if specified in critical_actions):
+   ```bash
+   touch {sidecarOutput}/memories.md
+   touch {sidecarOutput}/instructions.md
+   # ... additional files from critical_actions
+   ```
+
+3. **Add README to Sidecar**:
+   ```markdown
+   # {sidecar-folder} Sidecar
+
+   This folder stores persistent memory for the **{agent-name}** agent.
+
+   ## Purpose
+   {purpose from critical_actions}
+
+   ## Files
+   - memories.md: User profile, session history, patterns
+   - instructions.md: Protocols, boundaries, startup behavior
+   - {additional files}
+
+   ## Runtime Access
+   After BMAD installation, this folder will be accessible at:
+   `{project-root}/_bmad/_memory/{sidecar-folder}/{filename}.md`
+   ```
+
+### Phase 6: Write Agent YAML
+
+**If hasSidecar: false:**
+1. Write YAML to `{agentYamlOutputNoSidecar}`
+2. Confirm write success
+3. Display file location to user
+
+**If hasSidecar: true:**
+1. Create directory: `mkdir -p {agentBuildOutput}`
+2. Write YAML to `{agentYamlOutput}`
+3. Confirm write success
+4. Display file location to user
+
+## Phase 7: 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: Write agent YAML to appropriate output path (with or without sidecar), 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](#7-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
+
+---
+
+# CONTEXT BOUNDARIES
+
+**INCLUDE:**
+- Template structure exactly as provided
+- All agent metadata from agentPlan
+- Persona, commands, and rules from plan
+- Configuration options specified
+- Sidecar structure if hasSidecar: true
+
+**EXCLUDE:**
+- Any content not in agentPlan
+- Sidecar references if hasSidecar: false
+- Template placeholders (replace with actual content)
+- Comments or notes in final YAML
+
+---
+
+# CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [complete YAML generated and written to output], will you then load and read fully `{nextStepFile}` to execute and celebrate completion.
+
+**This step produces:**
+- **If hasSidecar: false**: Single agent YAML file
+- **If hasSidecar: true**: Agent YAML file + sidecar folder structure
+
+Both must exist (if applicable) before proceeding to validation.
+
+---
+
+# SUCCESS METRICS
+
+✅ **SUCCESS looks like:**
+- Agent YAML file exists at specified output path
+- YAML is syntactically valid and well-formed
+- All template fields populated with plan content
+- Structure matches agent architecture
+- If hasSidecar: true, sidecar folder created with starter files
+- User has selected continue to proceed
+
+❌ **FAILURE looks like:**
+- Template or architecture files not found
+- Agent plan missing required sections
+- YAML syntax errors in output
+- Content not properly mapped to template
+- File write operation fails
+- hasSidecar: true but sidecar folder not created
+
+---
+
+# TRANSITION CRITERIA
+
+**Ready for Step 8 when:**
+- Agent YAML successfully created (with or without sidecar as specified)
+- User selects continue
+- All build artifacts confirmed written

package/src/bmb/workflows/agent/steps-c/step-08-celebrate.md

@@ -0,0 +1,247 @@
+---
+name: 'step-08-celebrate'
+description: 'Celebrate completion and guide next steps for using the agent'
+
+# File References
+thisStepFile: ./step-08-celebrate.md
+workflowFile: ../workflow.md
+outputFile: {bmb_creations_output_folder}/agent-completion-{agent_name}.md
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+installationDocs: 'https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/modules/bmb-bmad-builder/custom-content-installation.md#standalone-content-agents-workflows-tasks-tools-templates-prompts'
+validationWorkflow: '{project-root}/src/modules/bmb/workflows/agent/steps-v/v-01-load-review.md'
+---
+
+# Step 8: Celebration and Installation Guidance
+
+## STEP GOAL:
+
+Celebrate the successful agent creation, recap the agent's capabilities, provide installation guidance, and mark workflow completion.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a celebration coordinator who guides users through agent installation and activation
+- ✅ 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 installation expertise, user brings their excitement about their new agent, together we ensure successful agent installation and usage
+- ✅ Maintain collaborative celebratory tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on celebrating completion and guiding installation
+- 🚫 FORBIDDEN to end without marking workflow completion in frontmatter
+- 💬 Approach: Celebrate enthusiastically while providing practical installation guidance
+- 📋 Ensure user understands installation steps and agent capabilities
+- 🔗 Always provide installation documentation link for reference
+
+## EXECUTION PROTOCOLS:
+
+- 🎉 Celebrate agent creation achievement enthusiastically
+- 💾 Mark workflow completion in frontmatter
+- 📖 Provide clear installation guidance
+- 🔗 Share installation documentation link
+- 🚫 FORBIDDEN to end workflow without proper completion marking
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete, validated, and built agent from previous steps
+- Focus: Celebration, installation guidance, and workflow completion
+- Limits: No agent modifications, only installation guidance and celebration
+- Dependencies: Complete agent ready for installation
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. (Do not deviate, skip, or optimize)
+
+### 1. Grand Celebration
+
+Present enthusiastic celebration:
+
+"🎉 Congratulations! We did it! {agent_name} is complete and ready to help users with {agent_purpose}!"
+
+**Journey Celebration:**
+"Let's celebrate what we accomplished together:
+
+- Started with an idea and discovered its true purpose
+- Crafted a unique personality with the four-field persona system
+- Built powerful capabilities and commands
+- Established a perfect name and identity
+- Created complete YAML configuration
+- Validated quality and prepared for deployment"
+
+### 2. Agent Capabilities Showcase
+
+**Agent Introduction:**
+"Meet {agent_name} - your {agent_type} agent ready to {agent_purpose}!"
+
+**Key Features:**
+"✨ **What makes {agent_name} special:**
+
+- {unique_personality_trait} personality that {communication_style_benefit}
+- Expert in {domain_expertise} with {specialized_knowledge}
+- {number_commands} powerful commands including {featured_command}
+- Ready to help with {specific_use_cases}"
+
+### 3. Activation Guidance
+
+**Getting Started:**
+"Here's how to start using {agent_name}:"
+
+**Activation Steps:**
+
+1. **Locate your agent files:** `{agent_file_location}`
+2. **If compiled:** Use the compiled version at `{compiled_location}`
+3. **For customization:** Edit the customization file at `{customization_location}`
+4. **First interaction:** Start by asking for help to see available commands
+
+**First Conversation Suggestions:**
+"Try starting with:
+
+- 'Hi {agent_name}, what can you help me with?'
+- 'Tell me about your capabilities'
+- 'Help me with [specific task related to agent purpose]'"
+
+### 4. Installation Guidance
+
+**Making Your Agent Installable:**
+"Now that {agent_name} is complete, let's get it installed and ready to use!"
+
+**Installation Overview:**
+"To make your agent installable and sharable, you'll need to package it as a standalone BMAD content module. Here's what you need to know:"
+
+**Key Steps:**
+1. **Create a module folder:** Name it something descriptive (e.g., `my-custom-stuff`)
+2. **Add module.yaml:** Include a `module.yaml` file with `code`, `name`, `version`
+3. **Copy your agent:** Copy the entire folder from `_bmad-creations/{agent-name}/` to `agents/`
+4. **The workflow handles structure:** Sidecar folders are already in the right place
+
+**Module Structure Example:**
+```
+my-custom-stuff/
+├── module.yaml
+├── agents/                              # Copy entire folder from _bmad-creations/
+│   └── {agent-name}/
+│       ├── {agent-name}.agent.yaml
+│       └── {agent-name}-sidecar/        # Already created by workflow if hasSidecar: true
+│           ├── memories.md
+│           └── instructions.md
+└── workflows/                           # Optional: standalone custom workflows
+    └── {workflow-name}/
+        └── workflow.md
+```
+
+**Note:** Your custom module can contain agents, workflows, or both. The `agents/` and `workflows/` folders are siblings alongside `module.yaml`.
+
+**Installation Methods:**
+- **New projects:** The BMAD installer will prompt for local custom modules
+- **Existing projects:** Use "Modify BMAD Installation" to add your module
+
+**Full Documentation:**
+"For complete details on packaging, sharing, and installing your custom agent, including all the configuration options and troubleshooting tips, see the official installation guide:"
+
+📖 **[BMAD Custom Content Installation Guide]({installationDocs})**
+
+### 5. Final Documentation
+
+#### Content to Append (if applicable):
+
+```markdown
+## Agent Creation Complete! 🎉
+
+### Agent Summary
+
+- **Name:** {agent_name}
+- **Type:** {agent_type}
+- **Purpose:** {agent_purpose}
+- **Status:** Ready for installation
+
+### File Locations
+
+- **Agent Config:** {agent_file_path}
+- **Compiled Version:** {compiled_agent_path}
+- **Customization:** {customization_file_path}
+
+### Installation
+
+Package your agent as a standalone module with a `module.yaml` file.
+See: {installationDocs}
+
+### Quick Start
+
+1. Create a module folder
+2. Add module.yaml with code, name, version
+3. Copy entire agent folder from `_bmad-creations/{agent-name}/` to `agents/`
+4. Install via BMAD installer
+```
+
+Save this content to `{outputFile}` for reference.
+
+### 6. Workflow Completion
+
+**Mark Complete:**
+"Agent creation workflow completed successfully! {agent_name} is ready to be installed and used. Amazing work!"
+
+**Final Achievement:**
+"You've successfully created a custom BMAD agent from concept to installation-ready configuration. The journey from idea to deployable agent is complete!"
+
+### 7. Present MENU OPTIONS
+
+Display: "**✅ Agent Build Complete! Select an Option:** [V] Run Validation [S] Skip - Complete Now [A] Advanced Elicitation [P] Party Mode"
+
+#### Menu Handling Logic:
+
+- IF V: "Loading validation phase..." → Save celebration content to {outputFile}, update frontmatter with build completion, then load, read entire file, then execute {validationWorkflow}
+- IF S: "Skipping validation. Completing workflow..." → Save content to {outputFile}, update frontmatter with workflow completion, then end workflow gracefully
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- User can choose validation (V), skip to complete (S), or use advanced elicitation (A) or party mode (P)
+- After other menu items execution (A/P), 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 [S skip option] is selected and [workflow completion marked in frontmatter], will the workflow end gracefully with agent ready for installation.
+IF [V validation option] is selected, the validation workflow will be loaded to perform comprehensive validation checks.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Enthusiastic celebration of agent creation achievement
+- Clear installation guidance provided
+- Agent capabilities and value clearly communicated
+- Installation documentation link shared with context
+- Module structure and packaging explained
+- User confidence in agent installation established
+- Workflow properly marked as complete in frontmatter
+- Content properly saved to output file
+- Menu presented with exit option
+
+### ❌ SYSTEM FAILURE:
+
+- Ending without marking workflow completion
+- Not providing clear installation guidance
+- Missing celebration of achievement
+- Not sharing installation documentation link
+- Not ensuring user understands installation steps
+- Failing to update frontmatter completion status
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.