bmad-plus 0.12.2 → 0.14.0

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

@@ -1,328 +1,51 @@
-# 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).
+# BWML migration note
+
+Earlier Dev Studio documents described XML-like instructions as the BMAD+
+Workflow Markup Language, or BWML. The pack did not ship an interpreter that
+implemented those tags as runtime operations. A tag in a prompt does not by
+itself create an agent, run a test, persist memory or enforce a validation gate.
+
+The maintained workflows now use original Markdown procedures and the
+[execution guide](execution.md). The [catalog](catalog.json) resolves stable
+workflow IDs to shipped files. The host assistant reads those instructions and
+uses its available tools; the CLI only prepares a read-only context bundle.
+
+## How earlier notation maps to supported behavior
+
+| Earlier notation | Current explicit behavior |
+| --- | --- |
+| Workflow, phase and step tags | Read the selected workflow and perform its numbered procedure |
+| Context tags and interpolated paths | Resolve the selected project, supported YAML config and real catalog resources |
+| Agent and parallel tags | Create actual independent host agents when supported and appropriate; record assignments |
+| Validation and guard tags | Run the named checks and record evidence, failures and unavailable checks |
+| Memory tags | Read or write an actual authorized project report; record the path and what changed |
+| Emit tags | Write the specified artifact and inspect it; no implicit event bus exists |
+| Retry tags | Retry only when useful and justified by new evidence; record the attempt and remaining problem |
+| Escalation and notification tags | Explain the specific dependency to the user; external messages need authorization |
+| Fallback tags | State the available execution mode and its limitations without converting missing evidence into success |
+
+Existing workflow IDs and persona names remain the public navigation contract.
+Retained support files are compatibility instructions, not a second execution
+engine. Consult the [pack README](../README.md) for the complete route list.
+
+## Configuration migration
+
+Dev Studio reads `_bmad/config.yaml` in the selected project with explicit
+defaults. It does not resolve `config.toml`, `config.user.toml`, per-agent TOML
+overrides or imported placeholder paths. Review existing custom settings and map
+only supported fields through the [customize workflow](../categories/utilities/customize.md).
+Preserve the originals and unrelated project settings; a prose description of
+merge rules cannot make an absent resolver work.
+
+For custom workflow instructions, keep the user's changes and deliberately adapt
+their required behavior to the common guide. Do not overwrite a locally modified
+file merely because a new framework version exists. Read previous reports as
+context and revalidate changed inputs before resuming.
+
+## What validation establishes
+
+Catalog and package checks establish that declared routes and resources exist.
+Preparation checks establish that inputs and configuration were loaded within
+the supported boundaries. Neither establishes that an LLM executed a workflow,
+that independent review occurred or that a project passed tests. Those claims
+require actual host execution and recorded evidence.