bmad-plus 0.12.1 → 0.13.0

package/src/bmad-plus/packs/pack-dev-studio/shared/bwml-spec.md

@@ -1,328 +1,328 @@
-# BMAD+ Workflow Markup Language (BWML) — Specification v1.0
-
-> **Pack:** Dev Studio
-> **Purpose:** Define the BMAD+ proprietary workflow DSL that surpasses BMAD-METHOD v6 XML format
-> **Created by:** Laurent Rochetta — https://github.com/lrochetta/BMAD-PLUS
-> **License:** MIT
-
----
-
-## Overview
-
-BWML (BMAD+ Workflow Markup Language) is an XML-based DSL optimized for LLM execution. It extends the concepts from BMAD-METHOD v6 with advanced orchestration primitives: multi-agent delegation, parallel execution, validation gates, memory persistence, anti-regression guards, and structured artifact emission.
-
-LLMs parse XML natively and reliably. BWML leverages this with semantically meaningful tags that guide deterministic execution while preserving LLM reasoning flexibility.
-
----
-
-## Core Elements (inherited from BMAD v6, enhanced)
-
-### `<workflow>` — Root container
-```xml
-<workflow id="dev-story" version="1.0" agent="oholiab">
-  <!-- All steps live here -->
-</workflow>
-```
-
-### `<phase>` — Named execution phase (NEW)
-Groups steps into logical phases with optional gating.
-```xml
-<phase name="analysis" gate="required">
-  <step>...</step>
-  <step>...</step>
-</phase>
-```
-- `gate="required"` — Must complete before next phase
-- `gate="optional"` — Can be skipped
-
-### `<step>` — Numbered execution step
-```xml
-<step n="1" goal="Load project context" tag="init">
-  <action>...</action>
-</step>
-```
-
-### `<action>` — Single action to execute
-```xml
-<action>Read the complete story file</action>
-<action if="no stories found">HALT: inform user</action>
-```
-
-### `<check>` — Conditional branch
-```xml
-<check if="sprint_status file exists">
-  <action>Load sprint data</action>
-</check>
-```
-
-### `<critical>` — Must-follow rule (violation = HALT)
-```xml
-<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
-```
-
-### `<output>` — Formatted user-facing output
-```xml
-<output>✅ **Context Loaded** — Story and project context ready</output>
-```
-
-### `<ask>` — Prompt user for input
-```xml
-<ask>Which story would you like to develop?</ask>
-```
-
-### `<goto>` — Jump to step or anchor
-```xml
-<goto step="9">Completion sequence</goto>
-<goto anchor="task_check" />
-```
-
-### `<anchor>` — Jump target
-```xml
-<anchor id="task_check" />
-```
-
----
-
-## BMAD+ Extensions (NEW — our competitive advantage)
-
-### `<agent>` — Invoke another BMAD+ agent inline
-Enables cross-agent orchestration without leaving the workflow.
-```xml
-<agent name="bezalel" task="Review this architecture decision">
-  <context>Current PRD and technical constraints</context>
-  <expect>Architecture recommendation with trade-offs</expect>
-</agent>
-```
-- `name` — BMAD+ agent to invoke (specialist personas or pack agents)
-- `task` — What to ask the agent
-- `<context>` — What context to pass
-- `<expect>` — Expected output format
-
-### `<parallel>` — Execute multiple actions concurrently
-```xml
-<parallel>
-  <action>Run unit tests</action>
-  <action>Run linting checks</action>
-  <action>Validate acceptance criteria</action>
-</parallel>
-```
-
-### `<loop>` — Iterative execution with break conditions
-```xml
-<loop over="incomplete_tasks" as="task">
-  <action>Implement {{task}}</action>
-  <action>Run tests for {{task}}</action>
-  <validate>All tests pass for {{task}}</validate>
-  <action>Mark {{task}} complete</action>
-  <break if="HALT condition triggered" />
-</loop>
-```
-
-### `<validate>` — Built-in validation gate with pass/fail
-```xml
-<validate id="dod-check" severity="blocking">
-  <criterion>All tasks marked [x]</criterion>
-  <criterion>All acceptance criteria satisfied</criterion>
-  <criterion>Full test suite passes with 0 failures</criterion>
-  <criterion>No regressions detected</criterion>
-  <on-fail>HALT — Do NOT proceed until all criteria pass</on-fail>
-  <on-pass>Continue to next step</on-pass>
-</validate>
-```
-
-### `<guard>` — Anti-regression protection
-Prevents common AI mistakes explicitly.
-```xml
-<guard type="anti-regression">
-  Never delete existing code without explicit user approval
-</guard>
-<guard type="scope">
-  Only modify files listed in the story spec
-</guard>
-<guard type="quality">
-  Never mark a task complete without running tests
-</guard>
-```
-
-### `<emit>` — Produce structured artifacts
-```xml
-<emit type="story-status" format="yaml">
-  story_key: {{story_key}}
-  status: review
-  completed_tasks: {{completed_count}}
-  date: {{date}}
-</emit>
-```
-- `type` — Artifact type (story-status, report, checklist, etc.)
-- `format` — Output format (yaml, markdown, json)
-
-### `<context>` — Load external context
-```xml
-<context source="file" path="**/project-context.md" />
-<context source="file" path="architecture.md" optional="true" />
-<context source="memory" key="last-sprint-decisions" />
-```
-
-### `<memory>` — Persist/recall across sessions
-```xml
-<memory action="store" key="sprint-velocity" value="{{calculated_velocity}}" />
-<memory action="recall" key="last-review-findings" />
-```
-
-### `<escalate>` — Escalation to human or higher agent
-```xml
-<escalate to="user" severity="high">
-  Architecture decision required: monolith vs microservices.
-  Trade-offs documented in {{arch_doc_path}}.
-</escalate>
-<escalate to="bezalel" severity="medium">
-  Implementation diverges from architecture — review needed.
-</escalate>
-```
-
-### `<retry>` — Auto-retry with limits
-```xml
-<retry max="3" backoff="progressive">
-  <action>Run failing test suite</action>
-  <action>Fix identified issues</action>
-  <on-exhaust>HALT — 3 consecutive failures, request human guidance</on-exhaust>
-</retry>
-```
-
-### `<fallback>` — Graceful degradation
-```xml
-<fallback>
-  <try>
-    <agent name="miriam" task="Analyze market data" />
-  </try>
-  <catch>
-    <action>Perform analysis directly using available context</action>
-  </catch>
-</fallback>
-```
-
-### `<metric>` — Track quantitative progress
-```xml
-<metric name="test-coverage" target="80%" current="{{coverage}}" />
-<metric name="tasks-completed" value="{{done}}/{{total}}" />
-```
-
----
-
-## Composition Example
-
-```xml
-<workflow id="dev-story" version="1.0" agent="oholiab">
-  <critical>Execute ALL steps in exact order; do NOT skip</critical>
-  <critical>Never stop for "milestones" or "session boundaries"</critical>
-  
-  <guard type="anti-regression">
-    Never delete existing functionality without explicit approval
-  </guard>
-  <guard type="scope">
-    Only modify files specified in the story tasks
-  </guard>
-
-  <phase name="initialization" gate="required">
-    <step n="1" goal="Find and load story">
-      <context source="file" path="sprint-status.yaml" optional="true" />
-      <check if="story_path provided">
-        <action>Load story file directly</action>
-        <goto anchor="implementation" />
-      </check>
-      <check if="sprint status exists">
-        <action>Find first ready-for-dev story</action>
-      </check>
-      <escalate to="user" if="no ready stories found">
-        No stories available. Options: create-story, validate existing, or specify path.
-      </escalate>
-    </step>
-  </phase>
-
-  <phase name="implementation" gate="required">
-    <anchor id="implementation" />
-    <loop over="incomplete_tasks" as="task">
-      <step goal="Implement {{task}} following TDD">
-        <!-- RED -->
-        <action>Write FAILING tests first</action>
-        <validate severity="info">Tests fail as expected</validate>
-        
-        <!-- GREEN -->
-        <action>Implement MINIMAL code to pass tests</action>
-        <validate severity="blocking">All tests pass</validate>
-        
-        <!-- REFACTOR -->
-        <action>Improve code structure, keep tests green</action>
-        <validate severity="blocking">No regressions after refactor</validate>
-        
-        <action>Mark {{task}} [x] in story file</action>
-        <metric name="tasks-completed" value="{{done}}/{{total}}" />
-      </step>
-      
-      <retry max="3">
-        <action>Fix any failing tests</action>
-        <on-exhaust>
-          <escalate to="user">3 consecutive failures on {{task}}</escalate>
-        </on-exhaust>
-      </retry>
-    </loop>
-  </phase>
-
-  <phase name="completion" gate="required">
-    <step goal="Story completion and review">
-      <validate id="definition-of-done" severity="blocking">
-        <criterion>All tasks marked [x]</criterion>
-        <criterion>All acceptance criteria satisfied</criterion>
-        <criterion>Full test suite passes</criterion>
-        <criterion>File list complete</criterion>
-        <criterion>Dev notes documented</criterion>
-        <on-fail>HALT — Complete remaining items</on-fail>
-      </validate>
-      
-      <emit type="story-update" format="yaml">
-        status: review
-        completed: {{date}}
-      </emit>
-      
-      <output>✅ Story {{story_key}} complete and ready for review</output>
-      
-      <escalate to="user" severity="info">
-        Recommended: run code-review with a DIFFERENT LLM
-      </escalate>
-    </step>
-  </phase>
-</workflow>
-```
-
----
-
-## BWML vs BMAD v6 Comparison
-
-| Feature | BMAD v6 | BWML (BMAD+) |
-|---------|---------|--------------|
-| Steps & Actions | ✅ | ✅ |
-| Conditional checks | ✅ | ✅ |
-| Goto/Anchors | ✅ | ✅ |
-| Critical rules | ✅ | ✅ |
-| User prompts | ✅ | ✅ |
-| **Phases with gates** | ❌ | ✅ |
-| **Multi-agent delegation** | ❌ | ✅ `<agent>` |
-| **Parallel execution** | ❌ | ✅ `<parallel>` |
-| **Loops with break** | ❌ | ✅ `<loop>` |
-| **Validation gates** | ❌ | ✅ `<validate>` |
-| **Anti-regression guards** | ❌ | ✅ `<guard>` |
-| **Artifact emission** | ❌ | ✅ `<emit>` |
-| **Context loading** | ❌ | ✅ `<context>` |
-| **Memory persistence** | ❌ | ✅ `<memory>` |
-| **Escalation** | ❌ | ✅ `<escalate>` |
-| **Auto-retry** | ❌ | ✅ `<retry>` |
-| **Graceful fallback** | ❌ | ✅ `<fallback>` |
-| **Progress metrics** | ❌ | ✅ `<metric>` |
-| Python dependency | ✅ Required | ❌ None |
-| TOML config | ✅ Required | ❌ Self-contained |
-
----
-
-## Attribution
-
-BWML is inspired by the workflow DSL in [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) v6.6.0 by BMad Code, LLC (MIT License). Extended with BMAD+ proprietary orchestration primitives by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).
+# BMAD+ Workflow Markup Language (BWML) — Specification v1.0
+
+> **Pack:** Dev Studio
+> **Purpose:** Define the BMAD+ proprietary workflow DSL that surpasses BMAD-METHOD v6 XML format
+> **Created by:** Laurent Rochetta — https://github.com/lrochetta/BMAD-PLUS
+> **License:** MIT
+
+---
+
+## Overview
+
+BWML (BMAD+ Workflow Markup Language) is an XML-based DSL optimized for LLM execution. It extends the concepts from BMAD-METHOD v6 with advanced orchestration primitives: multi-agent delegation, parallel execution, validation gates, memory persistence, anti-regression guards, and structured artifact emission.
+
+LLMs parse XML natively and reliably. BWML leverages this with semantically meaningful tags that guide deterministic execution while preserving LLM reasoning flexibility.
+
+---
+
+## Core Elements (inherited from BMAD v6, enhanced)
+
+### `<workflow>` — Root container
+```xml
+<workflow id="dev-story" version="1.0" agent="oholiab">
+  <!-- All steps live here -->
+</workflow>
+```
+
+### `<phase>` — Named execution phase (NEW)
+Groups steps into logical phases with optional gating.
+```xml
+<phase name="analysis" gate="required">
+  <step>...</step>
+  <step>...</step>
+</phase>
+```
+- `gate="required"` — Must complete before next phase
+- `gate="optional"` — Can be skipped
+
+### `<step>` — Numbered execution step
+```xml
+<step n="1" goal="Load project context" tag="init">
+  <action>...</action>
+</step>
+```
+
+### `<action>` — Single action to execute
+```xml
+<action>Read the complete story file</action>
+<action if="no stories found">HALT: inform user</action>
+```
+
+### `<check>` — Conditional branch
+```xml
+<check if="sprint_status file exists">
+  <action>Load sprint data</action>
+</check>
+```
+
+### `<critical>` — Must-follow rule (violation = HALT)
+```xml
+<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
+```
+
+### `<output>` — Formatted user-facing output
+```xml
+<output>✅ **Context Loaded** — Story and project context ready</output>
+```
+
+### `<ask>` — Prompt user for input
+```xml
+<ask>Which story would you like to develop?</ask>
+```
+
+### `<goto>` — Jump to step or anchor
+```xml
+<goto step="9">Completion sequence</goto>
+<goto anchor="task_check" />
+```
+
+### `<anchor>` — Jump target
+```xml
+<anchor id="task_check" />
+```
+
+---
+
+## BMAD+ Extensions (NEW — our competitive advantage)
+
+### `<agent>` — Invoke another BMAD+ agent inline
+Enables cross-agent orchestration without leaving the workflow.
+```xml
+<agent name="bezalel" task="Review this architecture decision">
+  <context>Current PRD and technical constraints</context>
+  <expect>Architecture recommendation with trade-offs</expect>
+</agent>
+```
+- `name` — BMAD+ agent to invoke (specialist personas or pack agents)
+- `task` — What to ask the agent
+- `<context>` — What context to pass
+- `<expect>` — Expected output format
+
+### `<parallel>` — Execute multiple actions concurrently
+```xml
+<parallel>
+  <action>Run unit tests</action>
+  <action>Run linting checks</action>
+  <action>Validate acceptance criteria</action>
+</parallel>
+```
+
+### `<loop>` — Iterative execution with break conditions
+```xml
+<loop over="incomplete_tasks" as="task">
+  <action>Implement {{task}}</action>
+  <action>Run tests for {{task}}</action>
+  <validate>All tests pass for {{task}}</validate>
+  <action>Mark {{task}} complete</action>
+  <break if="HALT condition triggered" />
+</loop>
+```
+
+### `<validate>` — Built-in validation gate with pass/fail
+```xml
+<validate id="dod-check" severity="blocking">
+  <criterion>All tasks marked [x]</criterion>
+  <criterion>All acceptance criteria satisfied</criterion>
+  <criterion>Full test suite passes with 0 failures</criterion>
+  <criterion>No regressions detected</criterion>
+  <on-fail>HALT — Do NOT proceed until all criteria pass</on-fail>
+  <on-pass>Continue to next step</on-pass>
+</validate>
+```
+
+### `<guard>` — Anti-regression protection
+Prevents common AI mistakes explicitly.
+```xml
+<guard type="anti-regression">
+  Never delete existing code without explicit user approval
+</guard>
+<guard type="scope">
+  Only modify files listed in the story spec
+</guard>
+<guard type="quality">
+  Never mark a task complete without running tests
+</guard>
+```
+
+### `<emit>` — Produce structured artifacts
+```xml
+<emit type="story-status" format="yaml">
+  story_key: {{story_key}}
+  status: review
+  completed_tasks: {{completed_count}}
+  date: {{date}}
+</emit>
+```
+- `type` — Artifact type (story-status, report, checklist, etc.)
+- `format` — Output format (yaml, markdown, json)
+
+### `<context>` — Load external context
+```xml
+<context source="file" path="**/project-context.md" />
+<context source="file" path="architecture.md" optional="true" />
+<context source="memory" key="last-sprint-decisions" />
+```
+
+### `<memory>` — Persist/recall across sessions
+```xml
+<memory action="store" key="sprint-velocity" value="{{calculated_velocity}}" />
+<memory action="recall" key="last-review-findings" />
+```
+
+### `<escalate>` — Escalation to human or higher agent
+```xml
+<escalate to="user" severity="high">
+  Architecture decision required: monolith vs microservices.
+  Trade-offs documented in {{arch_doc_path}}.
+</escalate>
+<escalate to="bezalel" severity="medium">
+  Implementation diverges from architecture — review needed.
+</escalate>
+```
+
+### `<retry>` — Auto-retry with limits
+```xml
+<retry max="3" backoff="progressive">
+  <action>Run failing test suite</action>
+  <action>Fix identified issues</action>
+  <on-exhaust>HALT — 3 consecutive failures, request human guidance</on-exhaust>
+</retry>
+```
+
+### `<fallback>` — Graceful degradation
+```xml
+<fallback>
+  <try>
+    <agent name="miriam" task="Analyze market data" />
+  </try>
+  <catch>
+    <action>Perform analysis directly using available context</action>
+  </catch>
+</fallback>
+```
+
+### `<metric>` — Track quantitative progress
+```xml
+<metric name="test-coverage" target="80%" current="{{coverage}}" />
+<metric name="tasks-completed" value="{{done}}/{{total}}" />
+```
+
+---
+
+## Composition Example
+
+```xml
+<workflow id="dev-story" version="1.0" agent="oholiab">
+  <critical>Execute ALL steps in exact order; do NOT skip</critical>
+  <critical>Never stop for "milestones" or "session boundaries"</critical>
+  
+  <guard type="anti-regression">
+    Never delete existing functionality without explicit approval
+  </guard>
+  <guard type="scope">
+    Only modify files specified in the story tasks
+  </guard>
+
+  <phase name="initialization" gate="required">
+    <step n="1" goal="Find and load story">
+      <context source="file" path="sprint-status.yaml" optional="true" />
+      <check if="story_path provided">
+        <action>Load story file directly</action>
+        <goto anchor="implementation" />
+      </check>
+      <check if="sprint status exists">
+        <action>Find first ready-for-dev story</action>
+      </check>
+      <escalate to="user" if="no ready stories found">
+        No stories available. Options: create-story, validate existing, or specify path.
+      </escalate>
+    </step>
+  </phase>
+
+  <phase name="implementation" gate="required">
+    <anchor id="implementation" />
+    <loop over="incomplete_tasks" as="task">
+      <step goal="Implement {{task}} following TDD">
+        <!-- RED -->
+        <action>Write FAILING tests first</action>
+        <validate severity="info">Tests fail as expected</validate>
+        
+        <!-- GREEN -->
+        <action>Implement MINIMAL code to pass tests</action>
+        <validate severity="blocking">All tests pass</validate>
+        
+        <!-- REFACTOR -->
+        <action>Improve code structure, keep tests green</action>
+        <validate severity="blocking">No regressions after refactor</validate>
+        
+        <action>Mark {{task}} [x] in story file</action>
+        <metric name="tasks-completed" value="{{done}}/{{total}}" />
+      </step>
+      
+      <retry max="3">
+        <action>Fix any failing tests</action>
+        <on-exhaust>
+          <escalate to="user">3 consecutive failures on {{task}}</escalate>
+        </on-exhaust>
+      </retry>
+    </loop>
+  </phase>
+
+  <phase name="completion" gate="required">
+    <step goal="Story completion and review">
+      <validate id="definition-of-done" severity="blocking">
+        <criterion>All tasks marked [x]</criterion>
+        <criterion>All acceptance criteria satisfied</criterion>
+        <criterion>Full test suite passes</criterion>
+        <criterion>File list complete</criterion>
+        <criterion>Dev notes documented</criterion>
+        <on-fail>HALT — Complete remaining items</on-fail>
+      </validate>
+      
+      <emit type="story-update" format="yaml">
+        status: review
+        completed: {{date}}
+      </emit>
+      
+      <output>✅ Story {{story_key}} complete and ready for review</output>
+      
+      <escalate to="user" severity="info">
+        Recommended: run code-review with a DIFFERENT LLM
+      </escalate>
+    </step>
+  </phase>
+</workflow>
+```
+
+---
+
+## BWML vs BMAD v6 Comparison
+
+| Feature | BMAD v6 | BWML (BMAD+) |
+|---------|---------|--------------|
+| Steps & Actions | ✅ | ✅ |
+| Conditional checks | ✅ | ✅ |
+| Goto/Anchors | ✅ | ✅ |
+| Critical rules | ✅ | ✅ |
+| User prompts | ✅ | ✅ |
+| **Phases with gates** | ❌ | ✅ |
+| **Multi-agent delegation** | ❌ | ✅ `<agent>` |
+| **Parallel execution** | ❌ | ✅ `<parallel>` |
+| **Loops with break** | ❌ | ✅ `<loop>` |
+| **Validation gates** | ❌ | ✅ `<validate>` |
+| **Anti-regression guards** | ❌ | ✅ `<guard>` |
+| **Artifact emission** | ❌ | ✅ `<emit>` |
+| **Context loading** | ❌ | ✅ `<context>` |
+| **Memory persistence** | ❌ | ✅ `<memory>` |
+| **Escalation** | ❌ | ✅ `<escalate>` |
+| **Auto-retry** | ❌ | ✅ `<retry>` |
+| **Graceful fallback** | ❌ | ✅ `<fallback>` |
+| **Progress metrics** | ❌ | ✅ `<metric>` |
+| Python dependency | ✅ Required | ❌ None |
+| TOML config | ✅ Required | ❌ Self-contained |
+
+---
+
+## Attribution
+
+BWML is inspired by the workflow DSL in [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) v6.6.0 by BMad Code, LLC (MIT License). Extended with BMAD+ proprietary orchestration primitives by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).