@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md

@@ -0,0 +1,136 @@
+# Step 10: User Journey Flows
+
+Design detailed user journey flows for critical user interactions.
+
+## USER JOURNEY FLOWS SEQUENCE
+
+### 1. Load PRD User Journeys as Foundation
+
+"Great! Since we have the PRD available, let's build on the user journeys already documented there.
+
+**Existing User Journeys from PRD:**
+I've already loaded these user journeys from your PRD:
+[Journey narratives from PRD input documents]
+
+These journeys tell us **who** users are and **why** they take certain actions. Now we need to design **how** those journeys work in detail.
+
+**Critical Journeys to Design Flows For:**
+Looking at the PRD journeys, I need to design detailed interaction flows for:
+- [Critical journey 1 identified from PRD narratives]
+- [Critical journey 2 identified from PRD narratives]
+- [Critical journey 3 identified from PRD narratives]
+
+The PRD gave us the stories — now we design the mechanics!"
+
+### 2. Design Each Journey Flow
+
+For each critical journey:
+
+"Let's design the flow for users accomplishing [journey goal].
+
+**Flow Design Questions:**
+- How do users start this journey? (entry point)
+- What information do they need at each step?
+- What decisions do they need to make?
+- How do they know they're progressing successfully?
+- What does success look like for this journey?
+- Where might they get confused or stuck?
+- How do they recover from errors?"
+
+### 3. Create Flow Diagrams
+
+"I'll create detailed flow diagrams for each journey showing:
+
+**[Journey Name] Flow:**
+- Entry points and triggers
+- Decision points and branches
+- Success and failure paths
+- Error recovery mechanisms
+- Progressive disclosure of information
+
+Each diagram will map the complete user experience from start to finish."
+
+### 4. Optimize for Efficiency and Delight
+
+"**Flow Optimization:**
+For each journey, let's ensure we're:
+
+- Minimizing steps to value (getting users to success quickly)
+- Reducing cognitive load at each decision point
+- Providing clear feedback and progress indicators
+- Creating moments of delight or accomplishment
+- Handling edge cases and error recovery gracefully
+
+**Specific Optimizations:**
+- [Optimization 1 for journey efficiency]
+- [Optimization 2 for user delight]
+- [Optimization 3 for error handling]"
+
+### 5. Document Journey Patterns
+
+"**Journey Patterns:**
+Across these flows, I'm seeing some common patterns we can standardize:
+
+**Navigation Patterns:**
+- [Navigation pattern 1]
+- [Navigation pattern 2]
+
+**Decision Patterns:**
+- [Decision pattern 1]
+- [Decision pattern 2]
+
+**Feedback Patterns:**
+- [Feedback pattern 1]
+- [Feedback pattern 2]
+
+These patterns will ensure consistency across all user experiences."
+
+### 6. Generate User Journey Content
+
+When saving to document, append these sections:
+
+```markdown
+## User Journey Flows
+
+### [Journey 1 Name]
+
+[Journey 1 description and Mermaid diagram]
+
+### [Journey 2 Name]
+
+[Journey 2 description and Mermaid diagram]
+
+### Journey Patterns
+
+[Journey patterns identified based on conversation]
+
+### Flow Optimization Principles
+
+[Flow optimization principles based on conversation]
+```
+
+### 7. Present Content and Menu
+
+"I've designed detailed user journey flows for {{project_name}}. These flows will guide the detailed design of each user interaction.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our user journey designs
+[P] Party Mode - Bring different perspectives on user flows
+[AR] Adversarial Review [C] Continue - Save this to the document and move to component strategy"
+
+### 8. Handle Menu Selection
+
+**If A:** Read fully and follow `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` with the current content. Ask user to accept/reject improvements, then return to menu.
+
+**If P:** Read fully and follow `{project-root}/_bmad/core/workflows/party-mode/workflow.md` with the current content. Ask user to accept/reject changes, then return to menu.
+
+**If AR:** Execute `{project-root}/_bmad/core/tasks/review-adversarial-general.xml` — display findings with recommendations; then redisplay this menu.
+
+**If C:**
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md`

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md

@@ -0,0 +1,165 @@
+# Step 11: Component Strategy
+
+Define component library strategy and design custom components not covered by the design system.
+
+## COMPONENT STRATEGY SEQUENCE
+
+### 1. Analyze Design System Coverage
+
+"Based on our chosen design system [design system from step 6], let's identify what components are already available and what we need to create custom.
+
+**Available from Design System:**
+[List of components available in chosen design system]
+
+**Components Needed for {{project_name}}:**
+Looking at our user journeys and design direction, we need:
+
+- [Component need 1 from journey analysis]
+- [Component need 2 from design requirements]
+- [Component need 3 from core experience]
+
+**Gap Analysis:**
+
+- [Gap 1 - needed but not available]
+- [Gap 2 - needed but not available]"
+
+### 2. Design Custom Components
+
+For each custom component needed, first ask:
+
+"**[Component Name] — Let's define its Atomic classification:**
+
+Using Atomic Design, every component maps to a specific tier:
+
+- **Atom** — A single logicless UI element (Button, Icon, Input, Label). Must be a stateless pure function receiving only props.
+- **Molecule** — 2+ atoms composed together (SearchBar = Input + Button). Must be stateless/dumb, receives data via props only.
+- **Organism** — A complex section with its own state or data-fetching. May consume Context or call hooks.
+
+For [Component Name]:
+
+- Which tier does this belong to? (Atom / Molecule / Organism)
+- **Purpose:** What does this component do for users?
+- **Content:** What information or data does it display?
+- **Actions:** What can users do with this component?
+- **States:** What different states does it have? (default, hover, active, disabled, error, etc.)
+- **Variants:** Are there different sizes or styles needed?
+- **Accessibility:** What ARIA labels and keyboard support (tabIndex, Enter/Space) needed?
+
+Let's walk through each custom component systematically."
+
+### 3. Document Component Specifications
+
+Use this template for each component:
+
+```markdown
+### [Component Name] — [Atom | Molecule | Organism]
+
+**Atomic Tier:** [Atom | Molecule | Organism]
+**Data Pattern:** [Props-only (dumb) | Fetches via hook (smart)]
+**Purpose:** [Clear purpose statement]
+**Usage:** [When and how to use]
+**Composition:** [For Molecules: list constituent Atoms. For Organisms: list Molecules/Atoms used]
+**Composition Check:** [Which existing Atoms/Molecules were evaluated and why they could/could not be reused]
+**States:** [All possible states with descriptions]
+**Variants:** [Different sizes/styles if applicable]
+**Accessibility:** [ARIA labels, keyboard navigation, tabIndex, Enter/Space keypresses where appropriate]
+**Content Guidelines:** [What content works best]
+**Interaction Behavior:** [How users interact]
+```
+
+### 4. Define Component Strategy
+
+"**Component Strategy:**
+
+**Foundation Components:** (from design system)
+
+- [Foundation component 1]
+- [Foundation component 2]
+
+**Custom Components:** (designed in this step)
+
+- [Custom component 1 with rationale]
+- [Custom component 2 with rationale]
+
+**Implementation Approach:**
+
+- Build custom components using design system tokens
+- Ensure consistency with established patterns
+- Follow accessibility best practices
+- Create reusable patterns for common use cases"
+
+### 5. Plan Implementation Roadmap
+
+"**Implementation Roadmap:**
+
+**Phase 1 - Core Components:**
+
+- [Component 1] - needed for [critical flow]
+- [Component 2] - needed for [critical flow]
+
+**Phase 2 - Supporting Components:**
+
+- [Component 3] - enhances [user experience]
+- [Component 4] - supports [design pattern]
+
+**Phase 3 - Enhancement Components:**
+
+- [Component 5] - optimizes [user journey]
+- [Component 6] - adds [special feature]
+
+This roadmap helps prioritize development based on user journey criticality."
+
+### 6. Generate Component Strategy Content
+
+When saving to document, append these sections:
+
+```markdown
+## Component Strategy
+
+### Design System Components
+
+[Analysis of available design system components based on conversation — list which design system components will be used AS-IS without modification]
+
+### Custom Components
+
+> **Classification Rule:** All custom components MUST be categorized under exactly ONE of the three Atomic Design tiers below. Components that span tiers must be split. Execution agents must reject any component that does not fit cleanly.
+
+#### Atoms (Logicless, Stateless)
+
+[Atom component specifications from conversation — each using the component template above]
+
+#### Molecules (Stateless Compositions of Atoms)
+
+[Molecule component specifications from conversation — each listing its constituent Atoms]
+
+#### Organisms (Stateful or Context-Consuming)
+
+[Organism component specifications from conversation — each listing its constituent Molecules/Atoms and the data it fetches or the Context it consumes]
+
+### Composition Audit
+
+> **Mandate:** Before any new component was defined above, the existing component library was evaluated. This section documents that check.
+
+| Component Name       | Existing Component Evaluated | Outcome                                 |
+| -------------------- | ---------------------------- | --------------------------------------- |
+| [New component name] | [Existing component checked] | [Reused / Modified / New — explain why] |
+
+### Component Implementation Strategy
+
+[Component implementation strategy based on conversation]
+
+### Implementation Roadmap
+
+[Implementation roadmap based on conversation — ordered by user journey criticality, not implementation convenience]
+```
+
+### 7. Auto-Save and Advance
+
+Without presenting a menu or waiting for user input:
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Announce: `"✅ Component Strategy saved. Advancing to UX Patterns..."`
+- Immediately load and execute: `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md`
+
+> **HALT ONLY IF:** A component cannot be classified into any Atomic tier (Atom/Molecule/Organism). In that case, ask once: "I couldn't classify [component name] — can you clarify its scope and responsibilities?" Then continue without further gates.

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md

@@ -0,0 +1,135 @@
+# Step 12: UX Consistency Patterns
+
+Establish UX consistency patterns for common situations like buttons, forms, navigation, and feedback.
+
+## UX PATTERNS SEQUENCE
+
+### 1. Identify Pattern Categories
+
+"Let's establish consistency patterns for how {{project_name}} behaves in common situations.
+
+**Pattern Categories to Define:**
+
+- Button hierarchy and actions
+- Feedback patterns (success, error, warning, info)
+- Form patterns and validation
+- Navigation patterns
+- Modal and overlay patterns
+- Empty states and loading states
+- Search and filtering patterns
+
+Which categories are most critical for your product? We can go through each thoroughly or focus on the most important ones."
+
+### 2. Define Critical Patterns First
+
+For each priority pattern category:
+
+"**[Pattern Type] Patterns:**
+What should users see/do when they need to [pattern action]?
+
+**Considerations:**
+
+- Visual hierarchy (primary vs. secondary actions)
+- Feedback mechanisms
+- Error recovery
+- Accessibility requirements
+- Mobile vs. desktop considerations
+
+**Examples:**
+
+- [Example 1 for this pattern type]
+- [Example 2 for this pattern type]
+
+How should {{project_name}} handle [pattern type] interactions?"
+
+### 3. Establish Pattern Guidelines
+
+Use this template for each pattern:
+
+```markdown
+### [Pattern Type]
+
+**When to Use:** [Clear usage guidelines]
+**Visual Design:** [How it should look]
+**Behavior:** [How it should interact]
+**Accessibility:** [A11y requirements]
+**Mobile Considerations:** [Mobile-specific needs]
+**Variants:** [Different states or styles if applicable]
+```
+
+### 4. Design System Integration
+
+"**Integration with [Design System]:**
+
+- How do these patterns complement our design system components?
+- What customizations are needed?
+- How do we maintain consistency while meeting unique needs?
+
+**Custom Pattern Rules:**
+
+- [Custom rule 1]
+- [Custom rule 2]
+- [Custom rule 3]"
+
+### 5. Generate UX Patterns Content
+
+When saving to document, append these sections:
+
+```markdown
+## UX Consistency Patterns
+
+> **Non-Negotiable Execution Constraint:** ALL navigation in this product MUST use the project's native routing primitives (`<Link href>` in Next.js, `<Link to>` in React Router, or framework equivalent). Hardcoded `<a href>` anchor tags for internal navigation are FORBIDDEN. This mandate applies to every component generated from this specification.
+
+### Button Hierarchy
+
+[Button hierarchy patterns based on conversation]
+
+### Feedback Patterns
+
+[Feedback patterns based on conversation]
+
+### Form Patterns
+
+[Form patterns based on conversation]
+
+### Navigation Patterns
+
+[Navigation patterns based on conversation]
+
+### Modal & Overlay Patterns
+
+[Modal and overlay patterns based on conversation — include explicit z-index strategy and focus-trap requirements]
+
+### Empty & Loading States
+
+[Empty state and loading state patterns based on conversation]
+
+### Additional Patterns
+
+[Additional patterns based on conversation]
+
+### Optimistic UI Rules
+
+**Default Behavior:** All mutating actions (create, update, delete) MUST implement optimistic UI updates by default to provide instant user feedback.
+
+**Mandatory Rollback Strategy:** For every mutating endpoint, define a rollback strategy. If the Epic/PRD does not define one for a specific endpoint, the execution agent MUST halt and request it before proceeding.
+
+> **Completeness Rule:** The table below MUST contain an entry for EVERY mutating endpoint defined in this project's Epics and PRD. A partial table is a compliance failure.
+
+| Mutation            | Optimistic Action                    | Success State                  | Rollback Strategy                       |
+| ------------------- | ------------------------------------ | ------------------------------ | --------------------------------------- |
+| [e.g., Create item] | [e.g., Add to list immediately]      | [e.g., Persist with server ID] | [e.g., Remove item + error toast]       |
+| [e.g., Delete item] | [e.g., Remove from list immediately] | [e.g., Delete confirmed]       | [e.g., Re-add item + error toast]       |
+| [e.g., Update item] | [e.g., Show new value immediately]   | [e.g., Confirm update]         | [e.g., Restore old value + error toast] |
+```
+
+### 6. Auto-Save and Advance
+
+Without presenting a menu or waiting for user input:
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Announce: `"✅ UX Consistency Patterns saved. Advancing to Responsive & Accessibility..."`
+- Immediately load and execute: `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md`
+
+> **HALT ONLY IF:** A mutating endpoint has no rollback strategy in the Epic/PRD. In that case, ask once: "The PRD doesn't define a rollback strategy for [endpoint]. How should we handle failures?" Then continue without further gates.

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md

@@ -0,0 +1,192 @@
+# Step 13: Responsive Design & Accessibility
+
+Define responsive design strategy and accessibility requirements for the product.
+
+## RESPONSIVE & ACCESSIBILITY SEQUENCE
+
+### 1. Define Responsive Strategy
+
+"Let's define how {{project_name}} adapts across different screen sizes and devices.
+
+**Desktop Strategy:**
+
+- How should we use extra screen real estate?
+- Multi-column layouts, side navigation, or content density?
+- What desktop-specific features can we include?
+
+**Tablet Strategy:**
+
+- Should we use simplified layouts or touch-optimized interfaces?
+- How do gestures and touch interactions work on tablets?
+- What's the optimal information density for tablet screens?
+
+**Mobile Strategy:**
+
+- Bottom navigation or hamburger menu?
+- How do layouts collapse on small screens?
+- What's the most critical information to show mobile-first?"
+
+### 2. Establish Breakpoint Strategy
+
+"**Breakpoint Strategy:**
+We need to define screen size breakpoints where layouts adapt.
+
+**Common Breakpoints:**
+
+- Mobile: 320px - 767px
+- Tablet: 768px - 1023px
+- Desktop: 1024px+
+
+**For {{project_name}}, should we:**
+
+- Use standard breakpoints or custom ones?
+- Focus on mobile-first or desktop-first design?
+- Have specific breakpoints for your key use cases?"
+
+### 3. Design Accessibility Strategy
+
+"**Accessibility Strategy:**
+What level of WCAG compliance does {{project_name}} need?
+
+**WCAG Levels:**
+
+- **Level A (Basic)** - Essential accessibility for legal compliance
+- **Level AA (Recommended)** - Industry standard for good UX
+- **Level AAA (Highest)** - Exceptional accessibility (rarely needed)
+
+**Based on your product:** [Recommendation based on user base, legal requirements, etc.]
+
+**Key Accessibility Considerations:**
+
+- Color contrast ratios (4.5:1 for normal text)
+- Keyboard navigation support
+- Screen reader compatibility
+- Touch target sizes (minimum 44x44px)
+- Focus indicators and skip links"
+
+### 4. Define Testing Strategy
+
+"**Testing Strategy:**
+
+**Responsive Testing:**
+
+- Device testing on actual phones/tablets
+- Browser testing across Chrome, Firefox, Safari, Edge
+- Real device network performance testing
+
+**Accessibility Testing:**
+
+- Automated accessibility testing tools
+- Screen reader testing (VoiceOver, NVDA, JAWS)
+- Keyboard-only navigation testing
+- Color blindness simulation testing
+
+**User Testing:**
+
+- Include users with disabilities in testing
+- Test with diverse assistive technologies
+- Validate with actual target devices"
+
+### 5. Document Implementation Guidelines
+
+"**Implementation Guidelines:**
+
+**Responsive Development:**
+
+- Use relative units (rem, %, vw, vh) over fixed pixels
+- Implement mobile-first media queries
+- Test touch targets and gesture areas
+- Optimize images and assets for different devices
+
+**Accessibility Development:**
+
+- Semantic HTML structure
+- ARIA labels and roles
+- Keyboard navigation implementation
+- Focus management and skip links
+- High contrast mode support"
+
+### 6. Generate Responsive & Accessibility Content
+
+When saving to document, append these sections:
+
+```markdown
+## Responsive Design & Accessibility
+
+### Responsive Strategy
+
+**Mobile-First Mandate:** All components and layouts MUST be implemented mobile-first. Write base CSS/Tailwind classes for mobile, then use `md:` and `lg:` prefixes (or media query equivalents) to scale up. Desktop-first overrides are FORBIDDEN unless explicit technical constraints require them.
+
+[Responsive strategy detail based on conversation]
+
+### Breakpoint Strategy
+
+| Breakpoint | Range          | Tailwind Prefix   | Focus                                          |
+| ---------- | -------------- | ----------------- | ---------------------------------------------- |
+| Mobile     | 320px – 767px  | (base, no prefix) | Single column, bottom nav, large touch targets |
+| Tablet     | 768px – 1023px | `md:`             | Multi-column optional, touch/mouse hybrid      |
+| Desktop    | 1024px+        | `lg:`             | Full layout, hover states, side navigation     |
+
+[Custom breakpoints or deviations based on conversation]
+
+### Accessibility Strategy
+
+**WCAG Target Level:** [Level A / AA / AAA based on conversation]
+
+**Mandatory Requirements (non-negotiable for every component):**
+
+- Every interactive element MUST include `aria-label`, `aria-expanded`, `role`, or relevant ARIA attribute. The execution agent MUST reject component generation if ARIA attributes are missing.
+- All interactive elements MUST be keyboard navigable. Use `tabIndex={0}` for custom interactive elements and respond to `Enter` and `Space` key presses where semantically appropriate.
+- Color contrast ratio ≥ 4.5:1 for normal text, ≥ 3:1 for large text and UI components.
+- Skip links MUST be provided for pages with long content.
+- Decorative images/elements MUST have `aria-hidden="true"`.
+- Focus indicators MUST be visible and high-contrast — never use `outline: none` without a replacement focus style.
+
+**Overflow Visibility Rule:**
+Hover states, tooltips, and dropdown menus MUST NOT be clipped by `overflow-hidden` on parent containers (e.g., inside cards, modals, sticky headers). During implementation, audit all parent containers that use `overflow-hidden` and switch to `overflow-visible` or use portals for floating elements.
+
+### Testing Strategy
+
+[Testing strategy based on conversation]
+
+### Implementation Guidelines
+
+**Responsive Development:**
+
+- ALWAYS use relative units (`rem`, `%`, `vw`, `vh`) over fixed `px` values for layout dimensions
+- Write mobile-first Tailwind/CSS — base styles target mobile, then use responsive prefixes (`md:`, `lg:`) to progressively enhance
+- Touch targets MUST be minimum `44×44px` — enforce this for all interactive elements on mobile
+- Use `next/image` (or framework equivalent) with explicit `width` and `height` for all images to prevent layout shift (CLS)
+- Test on throttled network (Slow 3G) to validate skeleton loading states
+
+**Accessibility Development:**
+
+- Use semantic HTML elements (`<button>`, `<nav>`, `<main>`, `<article>`) rather than `<div>` for all structural and interactive elements
+- ARIA labels MUST be meaningful (e.g., `aria-label="Close dialog"`, not `aria-label="button"`)
+- Focus management: When opening a modal/sheet, focus MUST jump to the first focusable element inside it
+- When modal closes, focus MUST return to the triggering element
+- All form fields MUST have associated `<label>` tags or `aria-labelledby`
+```
+
+### 7. Auto-Save and Advance
+
+Without presenting a menu or waiting for user input:
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Announce: `"✅ Responsive Design & Accessibility Strategy saved. Advancing to completion..."`
+- Immediately load and execute: `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md`
+
+> **HALT ONLY IF:** The user has not confirmed a WCAG target level and the product type implies legal accessibility requirements (e.g., government, healthcare, finance). In that case, ask once: "This product type typically requires WCAG AA compliance — shall I set that as the target?" Then continue without further gates.
+
+**If A:** Read fully and follow `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` with the current content. Ask user to accept/reject improvements, then return to menu.
+
+**If P:** Read fully and follow `{project-root}/_bmad/core/workflows/party-mode/workflow.md` with the current content. Ask user to accept/reject changes, then return to menu.
+
+**If AR:** Execute `{project-root}/_bmad/core/tasks/review-adversarial-general.xml` — display findings with recommendations; then redisplay this menu.
+
+**If C:**
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md`