siesa-agents 2.1.36 → 2.1.38

package/_bmad/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-08a-plan-traceability.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 for specialized operations, accessed via `{project-root}/_bmad/_memory/{sidecar-folder}/` paths in critical_actions.
+
+## MANDATORY EXECUTION RULES
+
+1. **EXPERT AGENT = SIDECAR REQUIRED**: Every Expert agent MUST have a sidecar folder created under `_bmad/_memory/`
+2. **CRITICAL_ACTIONS FORMAT**: All critical_actions MUST use `{project-root}/_bmad/_memory/{sidecar-folder}/` for file operations
+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}'
+type: 'expert'
+version: '1.0.0'
+
+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**:
+   - Path: `{project-root}/_bmad/_memory/{sidecar-folder}/`
+   - Use `mkdir -p` to create full path
+
+2. **Create Starter Files** (if specified in critical_actions):
+   ```bash
+   touch _bmad/_memory/{sidecar-folder}/{file1}.md
+   touch _bmad/_memory/{sidecar-folder}/{file2}.md
+   ```
+
+3. **Add README to Sidecar**:
+   ```markdown
+   # {sidecar-folder} Memory
+
+   This folder stores persistent memory for the **{agent-name}** Expert agent.
+
+   ## Purpose
+   {purpose from critical_actions}
+
+   ## Files
+   - {file1}.md: {description}
+   - {file2}.md: {description}
+
+   ## Access Pattern
+   Agent accesses these files via: `{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 begin validation.
+
+This step produces TWO artifacts:
+1. **Agent YAML**: Complete expert agent definition at `{agentYamlOutput}`
+2. **Sidecar Structure**: Folder and files at `{project-root}/_bmad/_memory/{sidecar-folder}/`
+
+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 under `_bmad/_memory/`
+✅ 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/_bmad/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-08a-plan-traceability.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 begin validation.
+
+**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)

package/_bmad/bmb/workflows/agent/steps-c/step-08a-plan-traceability.md

@@ -0,0 +1,203 @@
+---
+name: 'step-07a-plan-traceability'
+description: 'Verify build matches original plan'
+
+# File References
+nextStepFile: './step-08b-metadata-validation.md'
+agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
+builtYaml: '{bmb_creations_output_folder}/{agent-name}/{agent-name}.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
+Verify that the built agent YAML file contains all elements specified in the original agent plan. This step ensures plan traceability - confirming that what we planned is what we actually built.
+
+# MANDATORY EXECUTION RULES
+- MUST load both agentPlan and builtYaml files before comparison
+- MUST compare ALL planned elements against built implementation
+- MUST report specific missing items, not just "something is missing"
+- MUST offer fix option before proceeding to next validation
+- MUST handle missing files gracefully (report clearly, don't crash)
+- MUST respect YOLO mode behavior (part of combined validation report)
+
+# EXECUTION PROTOCOLS
+
+## File Loading Protocol
+1. Load agentPlan from `{bmb_creations_output_folder}/agent-plan-{agent_name}.md`
+2. Load builtYaml from `{bmb_creations_output_folder}/{agent-name}/{agent-name}.agent.yaml`
+3. If either file is missing, report the specific missing file and stop comparison
+4. Use Read tool to access both files with absolute paths
+
+## Comparison Protocol
+Compare the following categories systematically:
+
+### 1. Metadata Comparison
+- Agent name
+- Description
+- Version
+- Author/creator information
+- Location/module path
+- Language settings (if specified in plan)
+
+### 2. Persona Field Comparison
+For each field in persona section:
+- Check presence in built YAML
+- Verify field content matches planned intent
+- Note any significant deviations (minor wording differences ok)
+
+### 3. Commands Comparison
+- Verify all planned commands are present
+- Check command names match
+- Verify command descriptions are present
+- Confirm critical actions are referenced
+
+### 4. Critical Actions Comparison
+- Verify all planned critical_actions are present
+- Check action names match exactly
+- Verify action descriptions are present
+- Confirm each action has required fields
+
+### 5. Additional Elements
+- Dependencies (if planned)
+- Configuration (if planned)
+- Installation instructions (if planned)
+
+## Reporting Protocol
+Present findings in clear, structured format:
+
+```
+PLAN TRACEABILITY REPORT
+========================
+
+Agent: {agent_name}
+Plan File: {path to agent plan}
+Build File: {path to built YAML}
+
+COMPARISON RESULTS:
+-------------------
+
+✅ Metadata: All present / Missing: {list}
+✅ Persona Fields: All present / Missing: {list}
+✅ Commands: All present / Missing: {list}
+✅ Critical Actions: All present / Missing: {list}
+✅ Other Elements: All present / Missing: {list}
+
+OVERALL STATUS: [PASS / FAIL]
+
+```
+
+If ANY elements are missing:
+- List each missing element with category
+- Provide specific location reference (what was planned)
+- Ask if user wants to fix items or continue anyway
+
+## Menu Protocol
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [F] Fix Findings [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF F: Apply auto-fixes to {builtYaml} for identified missing elements, then redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF C: Proceed to next validation step, 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](#8-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
+
+If YOLO mode:
+- Include this report in combined validation report
+- Auto-select [C] Continue if all elements present
+- Auto-select [F] Fix if missing critical elements (name, commands)
+- Flag non-critical missing items in summary
+
+# CONTEXT BOUNDARIES
+- ONLY compare plan vs build - do NOT evaluate quality or correctness
+- Do NOT suggest improvements or changes beyond planned elements
+- Do NOT re-open persona/commands discovery - this is verification only
+- Fix option should return to step-06-build, not earlier steps
+- If plan file is ambiguous, note ambiguity but use reasonable interpretation
+
+# SEQUENCE
+
+## 1. Load Required Files
+```yaml
+action: read
+target:
+  - agentPlan
+  - builtYaml
+on_failure: report which file is missing and suggest resolution
+```
+
+## 2. Perform Structured Comparison
+```yaml
+action: compare
+categories:
+  - metadata
+  - persona_fields
+  - commands
+  - critical_actions
+  - other_elements
+method: systematic category-by-category check
+```
+
+## 3. Generate Comparison Report
+```yaml
+action: report
+format: structured pass/fail with specific missing items
+output: console display + optional save to validation log
+```
+
+## 4. Present Menu Options
+```yaml
+action: menu
+options:
+  - F: Fix missing items
+  - C: Continue to metadata validation
+  - V: View detailed comparison (optional)
+default: C if pass, F if fail
+```
+
+## 5. Handle User Choice
+- **[F] Fix Findings**: Apply auto-fixes to {builtYaml} for identified missing elements, then re-present menu
+- **[C] Continue**: Proceed to step-07b-metadata-validation
+- **[A] Advanced Elicitation**: Execute advanced elicitation workflow, then re-present menu
+- **[P] Party Mode**: Execute party mode workflow, then re-present menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [validation complete with any findings addressed], will you then load and read fully `{nextStepFile}` to execute and begin [metadata validation].
+
+# SUCCESS/FAILURE METRICS
+
+## Success Criteria
+- All planned elements present in built YAML: **COMPLETE PASS**
+- Minor deviations (wording, formatting) but all core elements present: **PASS**
+- Missing elements identified and user chooses to continue: **PASS WITH NOTED DEFICIENCIES**
+
+## Failure Criteria
+- Unable to load plan or build file: **BLOCKING FAILURE**
+- Critical elements missing (name, commands, or critical_actions): **FAIL**
+- Comparison cannot be completed due to file corruption: **BLOCKING FAILURE**
+
+## Next Step Triggers
+- **PASS → step-07b-metadata-validation**
+- **PASS WITH DEFICIENCIES → step-07b-metadata-validation** (user choice)
+- **FAIL → step-06-build** (with specific fix instructions)
+- **BLOCKING FAILURE → STOP** (resolve file access issues first)
+
+## YOLO Mode Behavior
+- Auto-fix missing critical elements by returning to build step
+- Log non-critical missing items for review but continue validation
+- Include traceability report in final YOLO summary
+- Do NOT stop for user confirmation unless plan file is completely missing