diff --git a/src/core/agents/workflow-executor.agent.yaml b/src/core/agents/workflow-executor.agent.yaml new file mode 100644 index 00000000..33ff3377 --- /dev/null +++ b/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: + - → 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 diff --git a/src/core/module-help.csv b/src/core/module-help.csv index 206f1cd3..f5d114d5 100644 --- a/src/core/module-help.csv +++ b/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,, diff --git a/src/core/tasks/step-enforcement.xml b/src/core/tasks/step-enforcement.xml new file mode 100644 index 00000000..ac5d57f3 --- /dev/null +++ b/src/core/tasks/step-enforcement.xml @@ -0,0 +1,199 @@ + + Enforce mandatory step execution with verification gates - prevent step skipping in multi-step workflows + + This enforcement layer provides optional verification gates for complex workflows + + + Multi-step workflows where step-skipping has been observed + Workflows requiring Task agent spawning (multi-agent coordination) + Workflows with quality gates that must be verified + Complex implementation pipelines where evidence of completion matters + + + + Before executing ANY step, verify PREVIOUS step completed with EVIDENCE + Each step must provide PROOF of completion (file created, Task agent ID, test results) + If step requires Task agent, VERIFY agent was spawned (check for task_id in evidence) + If step has quality_gate=true, VERIFY gate passed before proceeding + HALT if any verification fails - report what's missing + + + + Execute BEFORE each step transition when enforcement is active + + + Check state file: steps.{prev_step}.status == "completed" + + Previous step not marked complete: {prev_step} +Cannot proceed to {current_step} +Fix state file or complete previous step. + + + + + Check state file for evidence_{prev_step} + + + - files_created: [list] + - tests_passing: true + - commit_sha: {hash} + + + - review_invoked: true + - review_report_path: {path} + - issues_found: {count} + + + - tests_passed: true + - type_check_passed: true + - lint_passed: true + + + + + Step {prev_step} marked complete but missing required evidence: +{list_missing_evidence} +Provide evidence or re-execute step. + + + + + Read step file: {current_step_file} + Check for tags: invoke-workflow, spawn_agents, multi-agent + + + Check evidence for task_agent_ids: [list] + + 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. + + + + + + Check step file: quality_gate attribute + + + Verify gate criteria from evidence + + Step {prev_step} has quality_gate=true but criteria not met: +{list_failed_criteria} +Meet quality gate criteria before proceeding. + + + + + + + When step file contains invoke-workflow or spawn_agents tags + + + Parse step markdown/XML for: + + - "invoke-workflow" + - "multi-agent" + - "spawn agents" + - "Task agent" + + + + + + LLM MUST use Task or Skill tool to spawn agents + MUST record task_id or skill_execution_id in evidence + CANNOT proceed without agent spawn proof + + + Check evidence contains: + - agent_spawned: true + - agent_type: {type} + - task_id: {id} OR skill_id: {id} + + + + + + + After EVERY step, record evidence in state file + + + + + + How to activate enforcement in a workflow + + +```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 +``` + + + +```markdown + + + + +``` + + + + + + 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 + + + + - 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) + + + diff --git a/src/core/tasks/workflow.xml b/src/core/tasks/workflow.xml index 137b6dd5..7ced58da 100644 --- a/src/core/tasks/workflow.xml +++ b/src/core/tasks/workflow.xml @@ -9,6 +9,26 @@ NEVER skip a step - YOU are responsible for every steps execution without fail or excuse + + Optional step enforcement for complex workflows - activate via workflow.yaml enforcement.enabled: true + + + 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 + + + + Record evidence after each step in enforcement.state_file + Verify previous step evidence before proceeding to next + HALT if evidence missing - report what's needed + + + Steps execute in exact numerical order (1, 2, 3...) Optional steps: Ask user unless #yolo mode active @@ -46,6 +66,13 @@ For each step in instructions: + + Verify previous step has complete evidence in state file + Check for required Task agent spawns in previous step + If enforcement violation detected → HALT with explanation + See _bmad/core/tasks/step-enforcement.xml for full verification protocol + + If optional="true" and NOT #yolo → Ask user to include If if="condition" → Evaluate condition