bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

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

@@ -0,0 +1,201 @@
+---
+name: 'step-06-build-expert'
+description: 'Generate Expert agent YAML with sidecar from plan'
+
+# File References
+nextStepFile: './step-08-celebrate.md'
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}/'
+agentYamlOutput: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
+
+# Template and Architecture
+expertTemplate: ../templates/expert-agent-template/expert-agent.template.md
+expertArch: ../data/expert-agent-architecture.md
+agentCompilation: ../data/agent-compilation.md
+criticalActions: ../data/critical-actions.md
+
+# 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 Expert agent YAML file with sidecar folder structure. Expert agents require persistent memory storage, so the build creates a sidecar folder next to the agent.yaml (which gets installed to `_bmad/_memory/` during BMAD installation).
+
+## MANDATORY EXECUTION RULES
+
+1. **EXPERT AGENT = SIDECAR REQUIRED**: Every Expert agent MUST have a sidecar folder created next to agent.yaml (build location), which will be installed to `_bmad/_memory/` during BMAD installation
+2. **CRITICAL_ACTIONS FORMAT**: All critical_actions MUST use `{project-root}/_bmad/_memory/{sidecar-folder}/` for file operations (runtime path)
+3. **TEMPLATE COMPLIANCE**: Follow expert-agent-template.md structure exactly
+4. **YAML VALIDATION**: Ensure valid YAML syntax with proper indentation (2-space)
+5. **EXISTING CHECK**: If agentYamlOutput exists, ask user before overwriting
+6. **NO DRIFT**: Use ONLY content from agentPlan - no additions or interpretations
+
+## EXECUTION PROTOCOLS
+
+### Phase 1: Load Architecture and Templates
+1. Read `expertTemplate` - defines YAML structure for Expert agents
+2. Read `expertArch` - architecture requirements for Expert-level 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 1-5
+2. Verify plan contains:
+   - Agent type: "expert"
+   - Sidecar folder name
+   - Persona content
+   - Commands structure
+   - Critical actions (if applicable)
+
+### Phase 3: Assemble Expert YAML
+Using expertTemplate as 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}'
+    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}/'
+  agent-type: 'expert'
+  memory-type: 'persistent'
+```
+
+### Phase 4: Create Sidecar Structure
+
+1. **Create Sidecar Directory** (NEXT TO agent.yaml):
+   - Path: `{agentBuildOutput}/{agent-name}-sidecar/`
+   - Use `mkdir -p` to create full path
+   - Note: This folder gets installed to `_bmad/_memory/` during BMAD installation
+
+2. **Create Starter Files** (if specified in critical_actions):
+   ```bash
+   touch {agentBuildOutput}/{agent-name}-sidecar/{file1}.md
+   touch {agentBuildOutput}/{agent-name}-sidecar/{file2}.md
+   ```
+
+3. **Add README to Sidecar**:
+   ```markdown
+   # {sidecar-folder} Sidecar
+
+   This folder stores persistent memory for the **{agent-name}** Expert agent.
+
+   ## Purpose
+   {purpose from critical_actions}
+
+   ## Files
+   - {file1}.md: {description}
+   - {file2}.md: {description}
+
+   ## Runtime Access
+   After BMAD installation, this folder will be accessible at:
+   `{project-root}/_bmad/_memory/{sidecar-folder}/{filename}.md`
+   ```
+
+### Phase 5: Write Agent YAML
+
+1. Create `agentBuildOutput` directory: `mkdir -p {agentBuildOutput}`
+2. Write YAML to `agentYamlOutput`
+3. Confirm write success
+4. Display file location to user
+
+### Phase 6: Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [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 C: Write agent YAML to {agentBuildOutput}/{agent-name}/{agent-name}.agent.yaml (or appropriate output path), 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](#phase-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
+
+## CONTEXT BOUNDARIES
+
+- **USE ONLY**: Content from agentPlan, expertTemplate, expertArch, agentCompilation, criticalActions
+- **DO NOT ADD**: New capabilities, commands, or actions not in plan
+- **DO NOT INTERPRET**: Use exact language from plan
+- **DO NOT SKIP**: Any field in expertTemplate structure
+- **CRITICAL**: Expert agents MUST have sidecar-folder metadata
+
+## 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 TWO artifacts:
+1. **Agent YAML**: Complete expert agent definition at `{agentYamlOutput}`
+2. **Sidecar Structure**: Folder and files at `{agentBuildOutput}/{agent-name}-sidecar/` (build location, installs to `_bmad/_memory/` during BMAD installation)
+
+Both must exist before proceeding to validation.
+
+## SUCCESS METRICS
+
+✅ Agent YAML file created at expected location
+✅ Valid YAML syntax (no parse errors)
+✅ All template fields populated
+✅ Sidecar folder created at `{agentBuildOutput}/{agent-name}-sidecar/` (build location)
+✅ Sidecar folder contains starter files from critical_actions
+✅ critical_actions reference `{project-root}/_bmad/_memory/{sidecar-folder}/` paths
+✅ metadata.sidecar-folder populated
+✅ metadata.agent-type = "expert"
+✅ User validation choice received (one-at-a-time or YOLO)
+
+## FAILURE MODES
+
+❌ Missing required template fields
+❌ Invalid YAML syntax
+❌ Sidecar folder creation failed
+❌ critical_actions missing sidecar-folder references
+❌ agentPlan missing expert-specific content (sidecar-folder name)
+❌ File write permission errors

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

@@ -0,0 +1,258 @@
+---
+name: 'step-06-build-module'
+description: 'Generate Module agent YAML from plan'
+
+# File References
+nextStepFile: './step-08-celebrate.md'
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+agentBuildOutput: '{bmb_creations_output_folder}/{agent-name}/'
+agentYamlOutput: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml'
+
+# Template and Architecture (use expert as baseline)
+expertTemplate: ../templates/expert-agent-template/expert-agent.template.md
+expertArch: ../data/expert-agent-architecture.md
+agentCompilation: ../data/agent-compilation.md
+criticalActions: ../data/critical-actions.md
+
+# 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 Module agent YAML file from the approved plan, using the expert agent template as the baseline architecture and adding module-specific workflow integration paths and sidecar configuration.
+
+# MANDATORY EXECUTION RULES
+
+1. **TEMPLATE BASELINE**: Module agents MUST use the expert agent template as their structural foundation - do not create custom templates
+
+2. **PLAN ADHERENCE**: Extract content from agentPlan exactly as written - no enhancement, interpretation, or extrapolation
+
+3. **MODULE SPECIFICITY**: Module agents require workflow integration paths and may need sidecar configuration for multi-workflow modules
+
+4. **OUTPUT VALIDATION**: YAML must be valid, complete, and ready for immediate deployment
+
+5. **LANGUAGE PRESERVATION**: Maintain any language choice configured in the plan throughout the YAML
+
+# EXECUTION PROTOCOLS
+
+## PREPARATION PHASE
+
+### 1. Load Expert Template Baseline
+```
+Read: expertTemplate
+Read: expertArch
+Read: agentCompilation
+Read: criticalActions
+```
+
+**Purpose**: Understand the expert agent structure that serves as the Module agent baseline
+
+**Validation**: Confirm expert template has all required sections (name, description, persona, instructions, tools, skills, etc.)
+
+### 2. Load Agent Plan
+```
+Read: agentPlan (using dynamic path)
+```
+
+**Validation**: Plan contains all mandatory sections:
+- Agent identity (name, description)
+- Persona profile
+- Command structure
+- Critical actions
+- Workflow integrations (module-specific)
+- Language choice (if configured)
+
+### 3. Verify Output Directory
+```
+Bash: mkdir -p {agentBuildOutput}
+```
+
+**Purpose**: Ensure output directory exists for the module agent
+
+## ASSEMBLY PHASE
+
+### 4. Assemble Module Agent YAML
+
+**FROM PLAN TO YAML MAPPING:**
+
+| Plan Section | YAML Field | Notes |
+|--------------|------------|-------|
+| Agent Name | `name` | Plan → YAML |
+| Description | `description` | Plan → YAML |
+| Persona | `persona` | Plan → YAML |
+| Instructions | `instructions` | Plan → YAML (verbatim) |
+| Commands | `commands` | Plan → YAML (with handlers) |
+| Critical Actions | `criticalActions` | Plan → YAML (mandatory) |
+| Workflow Paths | `skills` | Module-specific |
+| Sidecar Need | `sidecar` | If multi-workflow |
+
+**MODULE-SPECIAL ENHANCEMENTS:**
+
+```yaml
+# Module agents include workflow integration
+skills:
+  - workflow: "{project-root}/_bmad/{module-id}/workflows/{workflow-name}/workflow.md"
+    description: "From plan workflow list"
+  - workflow: "{project-root}/_bmad/{module-id}/workflows/{another-workflow}/workflow.md"
+    description: "From plan workflow list"
+
+# Optional: Sidecar for complex modules
+sidecar:
+  enabled: true
+  workflows:
+    - ref: "primary-workflow"
+      type: "primary"
+    - ref: "secondary-workflow"
+      type: "support"
+```
+
+**CRITICAL ACTIONS MAPPING:**
+```
+For each critical action in plan:
+1. Identify matching command in YAML
+2. Add `critical: true` flag
+3. Ensure handler references agent function
+```
+
+### 5. Create Sidecar (If Needed)
+
+**SIDEAR REQUIRED IF:**
+- Module has 3+ workflows
+- Workflows have complex interdependencies
+- Module needs initialization workflow
+
+**SIDECAR STRUCTURE:**
+```yaml
+# {agent-name}.sidecar.yaml
+sidecar:
+  module: "{module-id}"
+  initialization:
+    workflow: "workflow-init"
+    required: true
+  workflows:
+    - name: "workflow-name"
+      path: "workflows/{workflow-name}/workflow.md"
+      type: "primary|support|utility"
+      dependencies: []
+  agent:
+    path: "{agent-name}.agent.yaml"
+```
+
+**IF SIDEAR NOT NEEDED**: Skip this step
+
+### 6. Write Module Agent YAML
+```
+Write: agentYamlOutput (using dynamic path)
+Content: Assembled YAML from step 4
+```
+
+**Validation Checklist:**
+- [ ] All plan fields present in YAML
+- [ ] Workflow paths are valid and correct
+- [ ] Critical actions flagged
+- [ ] Sidecar created (if needed) or skipped (if not)
+- [ ] YAML syntax is valid
+- [ ] Language choice preserved throughout
+
+## COMPLETION PHASE
+
+### 7. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [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 C: Write agent YAML to {agentBuildOutput}/{agent-name}/{agent-name}.agent.yaml (or appropriate output path), 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
+
+**USER RESPONSE HANDLING:**
+- **Option 1**: Proceed to step-07a-plan-traceability.md with sequential mode
+- **Option 2**: Proceed to step-07a-plan-traceability.md with yolo mode
+- **Invalid input**: Re-ask with options
+
+# CONTEXT BOUNDARIES
+
+**IN SCOPE:**
+- Reading expert template and architecture
+- Loading agent plan
+- Assembling Module agent YAML
+- Creating sidecar (if needed)
+- Writing valid YAML output
+
+**OUT OF SCOPE:**
+- Modifying plan content
+- Creating new template structures
+- Implementing agent code
+- Writing workflow files
+- Testing agent functionality
+
+**DO NOT:**
+- Add commands not in plan
+- Modify persona from plan
+- Create custom template structures
+- Skip critical actions mapping
+- Assume sidecar need - evaluate based on workflow count
+
+# 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 IS COMPLETE WHEN:**
+1. Module agent YAML file exists at agentYamlOutput path
+2. YAML contains all plan content correctly mapped
+3. Module-specific workflow paths are configured
+4. Sidecar is created (if needed) or correctly skipped (if not)
+5. User has chosen review mode (one-at-a-time or YOLO)
+6. Ready to proceed to step-07a-plan-traceability.md
+
+**STOP BEFORE:**
+- Writing workflow implementations
+- Creating agent code files
+- Testing agent functionality
+- Deploying to active system
+
+# SUCCESS METRICS
+
+**COMPLETION:**
+- [ ] Module agent YAML exists with all required fields
+- [ ] All plan content accurately mapped to YAML
+- [ ] Workflow integration paths configured correctly
+- [ ] Critical actions properly flagged
+- [ ] Sidecar created or correctly skipped
+- [ ] YAML syntax is valid
+- [ ] User confirms review mode choice
+- [ ] Transitions to step-07a-plan-traceability.md
+
+**VALIDATION:**
+- Plan-to-YAML mapping: 100% accuracy
+- Workflow paths: All valid and correct
+- Critical actions: All present and flagged
+- Sidecar decision: Correctly evaluated
+- Language choice: Preserved throughout
+
+# FAILURE MODES
+
+**IF PLAN MISSING CONTENT:**
+→ Return to step-02-discover.md to complete plan
+
+**IF EXPERT TEMPLATE MISSING:**
+→ Raise error - template is mandatory baseline
+
+**IF YAML SYNTAX ERROR:**
+→ Fix and retry write operation
+
+**IF WORKFLOW PATHS INVALID:**
+→ Flag for review in traceability step
+
+**IF USER ASKS FOR MODIFICATIONS:**
+→ Return to appropriate planning step (03-persona, 04-commands, or 05-name)