Merge cd07df1a33 into 542a7429ec

src/core/agents/workflow-executor.agent.yaml

@@ -0,0 +1,107 @@
+# Workflow Executor Agent
+# Specialized agent for executing complex workflows with step enforcement
+
+agent:
+  metadata:
+    id: "_bmad/core/agents/workflow-executor.md"
+    name: "Workflow Executor"
+    title: "Disciplined Workflow Executor with Step Enforcement"
+    icon: "🎯"
+    hasSidecar: false
+
+  persona:
+    role: "Disciplined Workflow Executor"
+    identity: "A methodical executor that follows workflow steps exactly as written. Loads all step files upfront, executes in strict order, records evidence after each step, and halts on violations. Zero improvisation - maximum reliability."
+    communication_style: "Precise and systematic. Reports each step clearly before and after execution. Provides evidence of completion. Halts immediately on any violation with clear explanation."
+    principles: |
+      - "Load ALL step files into context at workflow start - no lazy loading"
+      - "Execute steps in exact numerical order - no skipping, no reordering"
+      - "Record evidence after EVERY step - no exceptions"
+      - "HALT on any violation - never proceed with incomplete evidence"
+      - "When step says spawn agents → use Task tool, record task_id"
+      - "When step says invoke-workflow → use Skill tool, record result"
+
+  critical_actions:
+    - "At workflow start: Load workflow.yaml AND all step files into context"
+    - "Before each step: Display 'Executing Step {n}: {name}'"
+    - "During step: Follow instructions literally, use required tools"
+    - "After each step: Record evidence in state file"
+    - "Before next step: Verify previous step has complete evidence"
+    - "On violation: HALT with clear explanation of what's missing"
+
+  execution_protocol:
+    initialization: |
+      1. Read workflow.yaml completely
+      2. Read ALL step files into context (step-01-*.md, step-02-*.md, etc.)
+      3. Read _bmad/core/tasks/step-enforcement.xml for enforcement rules
+      4. Initialize state file for evidence tracking
+
+      Why: All instructions in context = no discretion about "should I read this?"
+
+    step_execution: |
+      For each step (in exact order, no skipping):
+
+      1. Display: "Executing Step {n}: {name}"
+
+      2. Parse step for MANDATORY actions:
+         - <invoke-workflow path="X"> → MUST use Skill tool
+         - spawn agents / multi-agent → MUST use Task tool
+         - quality_gate: true → MUST verify criteria
+
+      3. Execute ALL actions in step
+
+      4. Record evidence:
+         ```yaml
+         step-{n}:
+           status: completed
+           evidence:
+             step_file_loaded: "{path}"
+             {step-specific evidence}
+         ```
+
+      5. Verify evidence complete before proceeding
+
+      6. If evidence incomplete → HALT
+
+    evidence_requirements:
+      implementation_step:
+        - files_created: "[list of paths]"
+        - tests_passing: "true"
+        - commit_sha: "{hash}"
+
+      code_review_step:
+        - review_invoked: "true"
+        - review_report: "{path}"
+        - issues_found: "{count}"
+        - task_agents: "[ids if multi-agent]"
+
+      quality_check_step:
+        - test_output: "{results}"
+        - type_check_output: "success"
+        - lint_output: "success"
+
+  enforcement_guarantees:
+    prevents:
+      - "Skipping steps (all loaded, must execute sequentially)"
+      - "Not spawning Task agents when required"
+      - "Skipping quality gates"
+      - "Proceeding without evidence"
+      - "Improvising instead of following instructions"
+
+  usage:
+    description: "Use this agent for complex multi-step workflows where reliability matters"
+    when_to_use:
+      - "Workflows with 5+ steps"
+      - "Workflows requiring multi-agent coordination"
+      - "Workflows with quality gates"
+      - "When step-skipping has been observed"
+
+    invocation_example: |
+      Task agent: workflow-executor
+      Prompt: Execute {workflow-name} for {context}
+        - Load ALL step files into context at start
+        - Execute steps in exact order
+        - Spawn Task agents when step requires it
+        - Record evidence after each step
+        - HALT if any step incomplete
+        - Report back when ALL steps done

src/core/module-help.csv

@@ -7,3 +7,5 @@ core,,Shard Document,SD,70,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,false,,
 core,,Editorial Review - Prose,EP,80,_bmad/core/tasks/editorial-review-prose.xml,bmad-editorial-review-prose,false,,,Clinical copy-editor that reviews text for communication issues,,"three-column markdown table with suggested fixes",
 core,,Editorial Review - Structure,ES,90,_bmad/core/tasks/editorial-review-structure.xml,bmad-editorial-review-structure,false,,,Structural editor that proposes cuts reorganization and simplification while preserving comprehension,,
 core,,Adversarial Review (General),AR,100,_bmad/core/tasks/review-adversarial-general.xml,bmad-review-adversarial-general,false,,,Cynically review content and produce findings,,
+core,,Step Enforcement,SE,110,_bmad/core/tasks/step-enforcement.xml,,false,,,Optional enforcement system for multi-step workflows - prevents step skipping and requires evidence,,
+core,,Workflow Executor Agent,WE,120,_bmad/core/agents/workflow-executor.agent.yaml,,false,workflow-executor,,Disciplined workflow executor with step enforcement - use for complex multi-step workflows,,

src/core/tasks/step-enforcement.xml

@@ -0,0 +1,199 @@
+<task id="_bmad/core/tasks/step-enforcement.xml" name="Step Enforcement System" standalone="false">
+  <objective>Enforce mandatory step execution with verification gates - prevent step skipping in multi-step workflows</objective>
+
+  <critical>This enforcement layer provides optional verification gates for complex workflows</critical>
+
+  <when-to-use>
+    <scenario>Multi-step workflows where step-skipping has been observed</scenario>
+    <scenario>Workflows requiring Task agent spawning (multi-agent coordination)</scenario>
+    <scenario>Workflows with quality gates that must be verified</scenario>
+    <scenario>Complex implementation pipelines where evidence of completion matters</scenario>
+  </when-to-use>
+
+  <enforcement-rules>
+    <rule n="1">Before executing ANY step, verify PREVIOUS step completed with EVIDENCE</rule>
+    <rule n="2">Each step must provide PROOF of completion (file created, Task agent ID, test results)</rule>
+    <rule n="3">If step requires Task agent, VERIFY agent was spawned (check for task_id in evidence)</rule>
+    <rule n="4">If step has quality_gate=true, VERIFY gate passed before proceeding</rule>
+    <rule n="5">HALT if any verification fails - report what's missing</rule>
+  </enforcement-rules>
+
+  <step-verification-gate>
+    <mandate>Execute BEFORE each step transition when enforcement is active</mandate>
+
+    <check n="1" desc="Verify previous step completed">
+      <action>Check state file: steps.{prev_step}.status == "completed"</action>
+      <if condition="status != completed">
+        <halt>Previous step not marked complete: {prev_step}
+Cannot proceed to {current_step}
+Fix state file or complete previous step.</halt>
+      </if>
+    </check>
+
+    <check n="2" desc="Verify evidence exists">
+      <action>Check state file for evidence_{prev_step}</action>
+      <required-evidence>
+        <if step_type="implementation">
+          - files_created: [list]
+          - tests_passing: true
+          - commit_sha: {hash}
+        </if>
+        <if step_type="code_review">
+          - review_invoked: true
+          - review_report_path: {path}
+          - issues_found: {count}
+        </if>
+        <if step_type="quality_checks">
+          - tests_passed: true
+          - type_check_passed: true
+          - lint_passed: true
+        </if>
+      </required-evidence>
+
+      <if condition="evidence missing or incomplete">
+        <halt>Step {prev_step} marked complete but missing required evidence:
+{list_missing_evidence}
+Provide evidence or re-execute step.</halt>
+      </if>
+    </check>
+
+    <check n="3" desc="Verify Task agents spawned when required">
+      <action>Read step file: {current_step_file}</action>
+      <action>Check for tags: invoke-workflow, spawn_agents, multi-agent</action>
+
+      <if condition="step requires Task agents">
+        <action>Check evidence for task_agent_ids: [list]</action>
+        <if condition="no task_agent_ids in evidence">
+          <halt>Step {current_step} requires Task agents but none were spawned.
+Required: {agent_count} agents for {purpose}
+Found: 0 agents in evidence
+Spawn required Task agents.</halt>
+        </if>
+      </if>
+    </check>
+
+    <check n="4" desc="Verify quality gates passed">
+      <action>Check step file: quality_gate attribute</action>
+
+      <if condition="quality_gate == true">
+        <action>Verify gate criteria from evidence</action>
+        <if condition="gate criteria not met">
+          <halt>Step {prev_step} has quality_gate=true but criteria not met:
+{list_failed_criteria}
+Meet quality gate criteria before proceeding.</halt>
+        </if>
+      </if>
+    </check>
+  </step-verification-gate>
+
+  <task-agent-enforcement>
+    <mandate>When step file contains invoke-workflow or spawn_agents tags</mandate>
+
+    <detection>
+      <action>Parse step markdown/XML for:</action>
+      <patterns>
+        - "invoke-workflow"
+        - "multi-agent"
+        - "spawn agents"
+        - "Task agent"
+      </patterns>
+    </detection>
+
+    <enforcement>
+      <if condition="patterns detected">
+        <mandate>LLM MUST use Task or Skill tool to spawn agents</mandate>
+        <mandate>MUST record task_id or skill_execution_id in evidence</mandate>
+        <mandate>CANNOT proceed without agent spawn proof</mandate>
+
+        <verification>
+          Check evidence contains:
+          - agent_spawned: true
+          - agent_type: {type}
+          - task_id: {id} OR skill_id: {id}
+        </verification>
+      </if>
+    </enforcement>
+  </task-agent-enforcement>
+
+  <evidence-recording-protocol>
+    <mandate>After EVERY step, record evidence in state file</mandate>
+
+    <template>
+```yaml
+steps:
+  step-{n}-{name}:
+    status: completed
+    completed_at: "{timestamp}"
+    evidence:
+      # MANDATORY for all steps
+      step_file_loaded: "{path}"  # Proves step file was read
+
+      # Step-specific evidence (include what applies)
+      files_created: ["{paths}"]
+      commit_sha: "{hash}"
+      tests_passing: true
+      review_invoked: true
+      review_report: "{path}"
+      issues_found: {count}
+      task_agents_spawned: {count}
+```
+    </template>
+  </evidence-recording-protocol>
+
+  <integration>
+    <desc>How to activate enforcement in a workflow</desc>
+
+    <in-workflow-yaml>
+```yaml
+# Add to workflow.yaml to enable enforcement
+enforcement:
+  enabled: true
+  state_file: "{sprint_artifacts}/workflow-state-{{id}}.yaml"
+  require_evidence: true
+  halt_on_missing: true
+```
+    </in-workflow-yaml>
+
+    <in-workflow-instructions>
+```markdown
+<!-- Add at start of instructions to activate -->
+<enforcement active="true" />
+
+<!-- Enforcement gate runs automatically between steps -->
+```
+    </in-workflow-instructions>
+  </integration>
+
+  <llm-instructions>
+    <critical-mandate>
+      When executing workflows with enforcement active:
+
+      1. **BEFORE each step:**
+         - Read current step file COMPLETELY
+         - Parse for requirements (invoke-workflow, spawn_agents, quality_gate)
+         - Record what will be required as evidence
+
+      2. **DURING step:**
+         - If step says invoke-workflow → MUST use Skill tool
+         - If step says spawn agents → MUST use Task tool
+         - If step has quality_gate → MUST verify criteria
+
+      3. **AFTER step:**
+         - Record ALL evidence in state file
+         - Verify evidence is complete
+         - Mark step.status = completed ONLY if evidence present
+
+      4. **BEFORE next step:**
+         - Run step-enforcement gate
+         - Provide prev_step evidence
+         - If gate HALTS → STOP, don't proceed
+    </critical-mandate>
+
+    <failure-modes-prevented>
+      - Skipping steps → HALTED (no evidence for skipped step)
+      - Not spawning Task agents → HALTED (missing agent IDs in evidence)
+      - Skipping quality gates → HALTED (criteria not met in evidence)
+      - Not reading step files → HALTED (can't provide evidence of what step said)
+    </failure-modes-prevented>
+  </llm-instructions>
+</task>

src/core/tasks/workflow.xml

@@ -9,6 +9,26 @@
     <mandate>NEVER skip a step - YOU are responsible for every steps execution without fail or excuse</mandate>
   </llm>
 
+  <enforcement-mode optional="true">
+    <desc>Optional step enforcement for complex workflows - activate via workflow.yaml enforcement.enabled: true</desc>
+
+    <check name="interactive_workflow_detection">
+      IF this conversation has a command-name tag (e.g., /bmad_bmm_workflow):
+        → This is USER-INITIATED, continue in main context
+        → Interactive workflows need user prompts and responses
+
+      IF NO command-name tag AND enforcement.enabled:
+        → This is an INTERNAL workflow call
+        → Consider delegating to workflow-executor Task agent for fresh context
+    </check>
+
+    <evidence-tracking if="enforcement.enabled">
+      <mandate>Record evidence after each step in enforcement.state_file</mandate>
+      <mandate>Verify previous step evidence before proceeding to next</mandate>
+      <mandate>HALT if evidence missing - report what's needed</mandate>
+    </evidence-tracking>
+  </enforcement-mode>
+
   <WORKFLOW-RULES critical="true">
     <rule n="1">Steps execute in exact numerical order (1, 2, 3...)</rule>
     <rule n="2">Optional steps: Ask user unless #yolo mode active</rule>
@@ -46,6 +66,13 @@
     <step n="2" title="Process Each Instruction Step in Order">
       <iterate>For each step in instructions:</iterate>
 
+      <substep n="2.0" title="Enforcement Gate" if="enforcement.enabled">
+        <action>Verify previous step has complete evidence in state file</action>
+        <action>Check for required Task agent spawns in previous step</action>
+        <action>If enforcement violation detected → HALT with explanation</action>
+        <note>See _bmad/core/tasks/step-enforcement.xml for full verification protocol</note>
+      </substep>
+
       <substep n="2a" title="Handle Step Attributes">
         <check>If optional="true" and NOT #yolo → Ask user to include</check>
         <check>If if="condition" → Evaluate condition</check>