ma-agents 3.12.3 → 3.13.1

package/lib/bmad-cache/wds/src/workflows/wds-4-ux-design/workflow-specify.xml

@@ -0,0 +1,387 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<workflow id="wds-4-specify" name="WDS Phase 4 — Specify Page" version="1.0">
+  <description>
+    Create a complete, implementation-ready page specification: layout, components with Object IDs,
+    multilingual content, interactions, states, validation, spacing, and typography.
+    All 9 steps must be completed in sequence before the specification is considered done.
+    Validation runs at step 9 before the spec is written to disk.
+  </description>
+
+  <prerequisites>
+    <require file="{output_folder}/C-UX-Scenarios/{scenario-slug}/{scenario-slug}.md" label="Scenario outline"/>
+    <require file="{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/" label="Page folder from Phase 3 or design activity"/>
+    <require file="{output_folder}/_progress/00-design-log.md" label="Design log"/>
+  </prerequisites>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- INITIALIZATION — runs before step 1                                -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <initialization>
+    <instruction>
+      Read the design log at {output_folder}/_progress/00-design-log.md before starting.
+      Check Current table for any in-progress work from a previous session.
+    </instruction>
+    <instruction>
+      Load page context from the existing page folder:
+      {output_folder}/C-UX-Scenarios/[NN-slug]/pages/[NN].[step]-[page-slug]/
+      The page boilerplate created in Phase 3 contains scenario, page number, platform,
+      page purpose, entry context, exit action, and on-page interactions.
+    </instruction>
+    <instruction>
+      Update the design log Current table: add this page with status "specifying".
+    </instruction>
+    <gate type="file-exists" path="{output_folder}/C-UX-Scenarios/{scenario-slug}/{scenario-slug}.md"
+          failure-message="Scenario outline must exist. Select a scenario from the design log before running Specify."/>
+    <gate type="folder-exists" path="{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/"
+          failure-message="Page folder must exist. Run Phase 3 or a design activity (Suggest/Dream) to create the page structure before specifying."/>
+  </initialization>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 1 — Page Basics                                               -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="1-page-basics" name="Capture page metadata and entry/exit points" step-file="steps-p/step-01-page-basics.md">
+    <instruction>
+      Present the page basics form to the user and collect all required fields:
+      - Page name/title
+      - URL/route (if applicable)
+      - Main user goal (one sentence)
+      - Entry points (where users come from)
+      - Exit points (where users go next)
+
+      For public pages, also collect SEO data — check the project brief's SEO Strategy for target keywords:
+      - Primary keyword
+      - Secondary keywords
+      - URL slug (from keyword map)
+    </instruction>
+    <instruction>
+      Store all captured values as page_basics:
+      page_title, url_route, user_goal, entry_points, exit_points,
+      primary_keyword (public pages), secondary_keywords (public pages), url_slug (public pages).
+    </instruction>
+
+    <gate type="data-captured" required="page_title url_route user_goal entry_points exit_points"
+          failure-message="All basic page fields must be captured before proceeding. Do not skip any field."/>
+    <gate type="seo-data-captured" condition="page-is-public"
+          required="primary_keyword secondary_keywords url_slug"
+          failure-message="SEO data is mandatory for public pages. Check the project brief's SEO Strategy section."/>
+    <gate type="user-confirms" prompt="All page basics captured and confirmed by user?"/>
+
+    <output>page_basics stored — title, route, goal, entry/exit points, and SEO data (if public page).</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 2 — Layout Sections                                           -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="2-layout-sections" name="Define major page sections" step-file="steps-p/step-02-layout-sections.md">
+    <instruction>
+      Ask the user to describe the major areas of the page (header, hero, main content, sidebar,
+      footer, etc.). Do not define individual components yet — only high-level sections.
+    </instruction>
+    <instruction>
+      For each section described, store:
+      - section_name
+      - section_purpose
+      - section_priority (primary / secondary)
+    </instruction>
+    <instruction>
+      Confirm the section list with the user before proceeding.
+    </instruction>
+
+    <gate type="data-captured" required="layout_sections" minimum-count="1"
+          failure-message="At least one layout section must be defined. Do not proceed to components without a section structure."/>
+    <gate type="section-attributes-complete" required-per-section="name purpose priority"
+          failure-message="Each section must have a name, purpose, and priority before proceeding."/>
+    <gate type="user-confirms" prompt="Layout sections defined and confirmed?"/>
+
+    <output>layout_sections stored — section names, purposes, and priorities captured.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 3 — Components and Object IDs                                 -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="3-components-objects" name="Identify components and assign Object IDs" step-file="steps-p/step-03-components-objects.md">
+    <instruction>
+      Work through each section identified in step 2. For each section, go top-to-bottom,
+      left-to-right. Ask the user to describe the next object in the section.
+    </instruction>
+    <instruction>
+      For each object described, load and execute the object router:
+      data/object-types/object-router.md
+      The router will: ask for object type, load the correct object-type template, guide through
+      complete documentation, generate a specification with an Object ID, then return here.
+    </instruction>
+    <instruction>
+      After each component specification is complete, check project config:
+      if design system is enabled, run workflows/wds-7-design-system/design-system-router.md
+      to check for similar components and extract component-level info. Update page spec with
+      the reference. If design system is disabled, keep the full specification on the page.
+    </instruction>
+    <instruction>
+      Continue until the user confirms all objects in the section are documented.
+      Move to the next section. Continue until all sections are complete.
+      Present a summary: sections processed, total components, components by type, all Object IDs assigned.
+    </instruction>
+
+    <gate type="all-sections-processed" rule="every-layout-section-has-been-worked-through"
+          failure-message="All sections from step 2 must be processed. Do not skip any section."/>
+    <gate type="object-ids-assigned" rule="every-component-has-an-object-id"
+          failure-message="Every documented component must have an Object ID before proceeding to content. Missing IDs block downstream steps."/>
+    <gate type="object-router-used" rule="every-component-routed-through-object-router"
+          failure-message="Object-type routing must be used for every component. Do not document components without using the router."/>
+    <gate type="design-system-check-performed" condition="design-system-enabled"
+          failure-message="Design system check must be performed after every component when design system is enabled."/>
+    <gate type="user-confirms" prompt="All components documented with Object IDs, design system checks complete?"/>
+
+    <output>Component registry complete — all Object IDs assigned, design system references updated where applicable.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 4 — Content and Languages                                     -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="4-content-languages" name="Specify all text content in all languages" step-file="steps-p/step-04-content-languages.md">
+    <instruction>
+      Ask the user what languages this page supports. Store as supported_languages array.
+    </instruction>
+    <instruction>
+      For every text element on the page (labels, buttons, headings, messages, placeholders,
+      error text — derived from the component list), ask the user to provide content in every
+      supported language. Primary language first, then each additional language.
+    </instruction>
+    <instruction>
+      Store multilingual_content keyed by element and language.
+      No text element may have content in only a subset of languages — full coverage is required.
+    </instruction>
+
+    <gate type="languages-defined" required="supported_languages-array-not-empty"
+          failure-message="Supported languages must be defined before collecting content. Ask the user for the language list first."/>
+    <gate type="multilingual-coverage" rule="every-text-element-has-content-in-every-language"
+          failure-message="Every text element must have content in ALL supported languages. Do not proceed with incomplete language coverage."/>
+    <gate type="user-confirms" prompt="All text content specified in all supported languages?"/>
+
+    <output>multilingual_content stored — all text elements captured in all supported languages.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 5 — Interactions                                              -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="5-interactions" name="Define interaction behaviors per component" step-file="steps-p/step-05-interactions.md">
+    <instruction>
+      For each interactive component in the registry (from step 3), ask the user what happens
+      when the user interacts with it. Cover: on click / on input / on focus,
+      immediate response, state changes, navigation (if applicable), data sent/received.
+    </instruction>
+    <instruction>
+      Store interaction_behavior keyed by Object ID. Do not generate behaviors without
+      user input — ask for each component individually.
+    </instruction>
+    <instruction>
+      Do not define visual states in this step — that is step 6.
+    </instruction>
+
+    <gate type="all-interactive-components-covered" rule="every-interactive-object-id-has-interaction-behavior"
+          failure-message="Every interactive component must have defined behaviors. Do not skip any."/>
+    <gate type="interaction-types-covered" rule="click-input-focus-navigation-data-considered-per-component"
+          failure-message="Consider all relevant interaction types for each component before moving on."/>
+    <gate type="user-confirms" prompt="All interaction behaviors defined for every interactive component?"/>
+
+    <output>interaction_behavior stored per Object ID — all interactive components covered.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 6 — States                                                    -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="6-states" name="Define page-level and component-level states" step-file="steps-p/step-06-states.md">
+    <instruction>
+      Define page-level states first. Ask the user to describe each situation:
+      default/loaded, empty (no data), loading (fetching), error (something went wrong),
+      success (after action completes). For each: when it occurs, what user sees, available actions.
+    </instruction>
+    <instruction>
+      For each component with multiple possible appearances, ask the user to define applicable states:
+      default, hover, active/pressed, focus, disabled, loading, error, success.
+      Only specify states that actually apply to each component.
+    </instruction>
+    <instruction>
+      Store page_states and component_states.
+      Do not define validation rules in this step — that is step 7.
+    </instruction>
+
+    <gate type="page-states-defined" required="default-state-minimum"
+          failure-message="At minimum, the default page state must be defined."/>
+    <gate type="component-states-defined" rule="multi-state-components-have-all-applicable-states"
+          failure-message="Components with multiple appearances must have all applicable states documented. Do not skip multi-state components."/>
+    <gate type="user-confirms" prompt="All page-level and component-level states defined?"/>
+
+    <output>page_states and component_states stored — all state variations documented.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 7 — Validation                                                -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="7-validation" name="Define validation rules and error messages" step-file="steps-p/step-07-validation.md">
+    <instruction>
+      Identify all fields and inputs that require validation. For each, ask:
+      - What makes it valid / invalid?
+      - Required or optional?
+      - Format rules and length limits?
+      - Custom rules?
+      - Validation timing: on blur, on submit, or real-time?
+    </instruction>
+    <instruction>
+      For each validation rule, define error messages in ALL supported languages.
+      Assign an error code (e.g., ERR_EMAIL_INVALID) to every message.
+    </instruction>
+    <instruction>
+      Store validation_rules and error_messages per field, with codes and translations.
+      Do not generate the specification document yet — that is step 9.
+    </instruction>
+
+    <check-if condition="page-has-input-fields-or-forms">
+      <then>
+        Proceed with full validation definition. Every input field must have rules and error messages.
+      </then>
+      <else>
+        No validated fields on this page. Store an empty validation_rules object and note
+        "No form inputs on this page" before proceeding to step 8.
+      </else>
+    </check-if>
+
+    <gate type="validation-rules-complete" rule="every-input-field-has-rules"
+          condition="page-has-input-fields"
+          failure-message="Every input field must have validation rules defined. Do not skip any field."/>
+    <gate type="error-messages-translated" rule="every-error-code-has-message-in-every-language"
+          condition="page-has-input-fields"
+          failure-message="Error messages must be provided in ALL supported languages. Incomplete translations block step 9."/>
+    <gate type="error-codes-assigned" rule="every-error-message-has-a-code"
+          condition="page-has-input-fields"
+          failure-message="Every error message must have an error code (e.g., ERR_EMAIL_INVALID)."/>
+    <gate type="user-confirms" prompt="Validation rules and error messages complete?"/>
+
+    <output>validation_rules and error_messages stored — all fields covered, all languages translated, all codes assigned.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 8 — Spacing and Typography                                    -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="8-spacing-typography" name="Define spacing objects and typography tokens" step-file="steps-p/step-08-spacing-typography.md">
+    <instruction>
+      Walk through adjacent section pairs top-to-bottom. For each pair, ask the user which
+      spacing token applies. Present the full table of gaps at once for efficiency.
+
+      Available tokens: zero, sm, md, lg, xl, 2xl, 3xl.
+      Zero-spacing is an intentional design choice — document it, never skip it.
+
+      Store spacing objects using naming convention:
+      - {page-slug}-v-space-{size} for vertical spacing
+      - {page-slug}-v-separator-{size} for lines/dividers with spacing
+
+      Also capture grid gaps for sections with repeated items (card grids, lists).
+    </instruction>
+    <instruction>
+      For each heading in the content (from step 4), define typography tokens.
+      Collect from the user: semantic tag (h1/h2/h3) and visual size per breakpoint
+      (mobile / tablet / desktop).
+
+      Available heading tokens: heading-xxs (14px), heading-xs (16px), heading-sm (18px),
+      heading-md (20px), heading-lg (24px), heading-xl (30px), heading-2xl (36px),
+      heading-3xl (44px), heading-4xl (56px).
+
+      Rule: use token names only — never arbitrary pixel values.
+      Rule: step up one token size per breakpoint (mobile → tablet → desktop) as a guide.
+
+      Store typography_tokens with Object ID, tag, and visual size per breakpoint.
+    </instruction>
+    <instruction>
+      Present the complete invisible layer to the user — spacing objects and typography tokens.
+      Ask if anything needs adjusting before generating the specification.
+    </instruction>
+
+    <gate type="spacing-complete" rule="every-section-boundary-has-spacing-object"
+          failure-message="Every adjacent section pair must have a spacing object. Including zero-spacing decisions."/>
+    <gate type="no-pixel-values" rule="only-token-names-used-in-spacing-and-typography"
+          failure-message="Only token names are allowed (zero, sm, md, lg, xl, 2xl, 3xl for spacing; heading-xxs through heading-4xl for typography). No pixel values."/>
+    <gate type="typography-complete" rule="every-heading-has-tag-and-responsive-token"
+          failure-message="Every heading must have a semantic tag and visual token for all three breakpoints."/>
+    <gate type="grid-gaps-documented" condition="page-has-card-grids-or-repeated-items"
+          failure-message="Grid gaps must be documented for sections containing repeated items (card grids, lists)."/>
+    <gate type="user-confirms" prompt="Spacing objects and typography tokens reviewed and approved?"/>
+
+    <output>spacing_objects and typography_tokens stored — every section boundary and heading documented with tokens.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- STEP 9 — Generate Specification                                    -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <step id="9-generate-spec" name="Compile and save the complete page specification" step-file="steps-p/step-09-generate-spec.md">
+    <instruction>
+      Verify all data from steps 1-8 is present before generating:
+      page_basics, layout_sections, component registry with Object IDs, multilingual_content,
+      interaction_behavior, page_states, component_states, validation_rules, error_messages,
+      spacing_objects, typography_tokens.
+      If any section is missing, return to the relevant step to complete it first.
+    </instruction>
+    <instruction>
+      Generate the complete specification document using the template at:
+      templates/page-specification.template.md
+
+      Fill ALL sections with data from steps 1-8. Do not invent new formats —
+      the template defines the structure.
+    </instruction>
+    <instruction>
+      Run the validation script before saving:
+      wds-validate.js --page {current-page-path}
+      Review any errors or warnings reported. Fix issues in the relevant data sections
+      and re-run until validation passes.
+    </instruction>
+    <instruction>
+      Save the complete specification to:
+      {output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/{NN}.{step}-{page-slug}.md
+
+      Present the summary to the user: sections, components, languages, interactions, states,
+      validation rules, spacing objects, typography tokens — with counts.
+    </instruction>
+    <instruction>
+      Update the design log: append a row to the Design Loop Status table with status "specified":
+      | [scenario-slug] | [NN.step] | [page-name] | specified | [YYYY-MM-DD] |
+
+      Remove this page from the Current table. Do NOT skip this — the design log drives the
+      adaptive dashboard across sessions.
+    </instruction>
+
+    <gate type="all-data-sections-present" required="page_basics layout_sections components multilingual_content interaction_behavior page_states validation_rules spacing_objects typography_tokens"
+          failure-message="All data sections from steps 1-8 must be present before generating the specification. Return to incomplete steps."/>
+    <gate type="script-run" script="src/scripts/wds-validate.js" args="--page {current-page-path}"
+          failure-message="Validation script must pass before saving the specification. Fix reported issues and re-run."/>
+    <gate type="file-saved" path="{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/{NN}.{step}-{page-slug}.md"
+          failure-message="Specification file must be saved to the correct path before this step is complete."/>
+    <gate type="design-log-updated" rule="design-loop-status-row-appended-with-status-specified"
+          failure-message="Design log must be updated with 'specified' status before this step is complete. This is not optional."/>
+
+    <output>Complete page specification generated, validated, saved, and design log updated with 'specified' status.</output>
+  </step>
+
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+  <!-- COMPLETION                                                         -->
+  <!-- ═══════════════════════════════════════════════════════════════════ -->
+
+  <completion>
+    <require step="all" failure-message="All 9 steps must be completed. The specification is not valid until step 9 passes validation and saves the file."/>
+    <output-file>{output_folder}/C-UX-Scenarios/{scenario-slug}/pages/{NN}.{step}-{page-slug}/{NN}.{step}-{page-slug}.md</output-file>
+    <post-completion>
+      Return to the calling workflow's transition logic. If called from step-01-exploration.md (Discuss)
+      or workflow-suggest.md (Suggest), the calling step determines what comes next.
+      The design log status "specified" is the signal that this page is done.
+    </post-completion>
+  </completion>
+
+</workflow>

package/lib/bmad-extension/.claude-plugin/marketplace.json.template

@@ -39,7 +39,7 @@
     "roo-code",
     "kilocode"
   ],
-  "bmad_min_version": "6.6.0",
+  "bmad_min_version": "6.8.0",
   "plugins": [
     {
       "name": "ma-skills",

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -31,13 +31,13 @@
     "roo-code",
     "kilocode"
   ],
-  "bmad_min_version": "6.6.0",
+  "bmad_min_version": "6.8.0",
   "plugins": [
     {
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.12.3",
+      "version": "3.13.1",
       "author": {
         "name": "Alon Mayaffit"
       },