diff --git a/docs/bmad-workflow-guide.md b/docs/bmad-workflow-guide.md
new file mode 100644
index 00000000..27683d36
--- /dev/null
+++ b/docs/bmad-workflow-guide.md
@@ -0,0 +1,187 @@
+# BMad Method Universal Workflow Guide
+
+This guide outlines the core BMad workflow that applies regardless of which AI-powered IDE you're using.
+
+## Overview
+
+The BMad Method follows a structured approach to AI-assisted software development:
+
+1. **Install BMad** in your project
+2. **Plan with Gemini** using team-fullstack
+3. **Organize with bmad-master** (document sharding)
+4. **Develop iteratively** with SM → Dev cycles
+
+## The Complete Workflow
+
+### Phase 1: Project Setup
+
+1. **Install BMad in your project**:
+
+   ```bash
+   npx bmad-method install
+   ```
+
+   - Choose "Complete installation"
+   - Select your IDE (Cursor, Claude Code, Windsurf, Trae, Roo Code, or GitHub Copilot)
+
+2. **Verify installation**:
+   - `.bmad-core/` folder created with all agents
+   - IDE-specific integration files created
+   - All agent commands/rules/modes available
+
+### Phase 2: Ideation & Planning (Gemini)
+
+Use Google's Gemini for collaborative planning with the full team:
+
+1. **Open [Google Gems](https://gemini.google.com/gems/view)**
+2. **Create a new Gem**:
+   - Give it a title and description (e.g., "BMad Team Fullstack")
+3. **Load team-fullstack**:
+   - Copy contents of: `web-bundles/teams/team-fullstack.txt` from your project
+   - Paste this content into the Gem setup to configure the team
+4. **Collaborate with the team**:
+
+   - Business Analyst: Requirements gathering
+   - Product Manager: Feature prioritization
+   - Solution Architect: Technical design
+   - UX Expert: User experience design
+
+   **Example Gemini Sessions**
+
+   ```text
+   "I want to build a [type] application that [core purpose].
+   Help me brainstorm features and create a comprehensive PRD."
+
+   "Based on this PRD, design a scalable technical architecture
+   that can handle [specific requirements]."
+   ```
+
+5. **Export planning documents**:
+   - Copy the PRD output and save as `docs/prd.md` in your project
+   - Copy the architecture output and save as `docs/architecture.md` in your project
+
+### Phase 3: Document Organization (IDE)
+
+Switch back to your IDE for document management:
+
+1. **Load bmad-master agent** (syntax varies by IDE)
+2. **Shard the PRD**:
+
+   ```text
+   *shard-doc docs/prd.md prd
+   ```
+
+3. **Shard the architecture**:
+
+   ```text
+   *shard-doc docs/architecture.md architecture
+   ```
+
+**Result**: Organized folder structure:
+
+- `docs/prd/` - Broken down PRD sections
+- `docs/architecture/` - Broken down architecture sections
+
+### Phase 4: Iterative Development
+
+Follow the SM → Dev cycle for systematic story development:
+
+#### Create new Branch
+
+1. **Start new branch**
+
+#### Story Creation (Scrum Master)
+
+1. **Start new chat/conversation**
+2. **Load SM agent**
+3. **Execute**: `*create` (runs create-next-story task)
+4. **Review generated story** in `docs/stories/`
+5. **Update status**: Change from "Draft" to "Approved"
+
+#### Story Implementation (Developer)
+
+1. **Start new chat/conversation**
+2. **Load Dev agent**
+3. **Execute**: `*develop-story {selected-story}` (runs execute-checklist task)
+4. **Review generated report** in `{selected-story}`
+
+#### Story Review (Quality Assurance)
+
+1. **Start new chat/conversation**
+2. **Load QA agent**
+3. **Execute**: `*review {selected-story}` (runs review-story task)
+4. **Review generated report** in `{selected-story}`
+
+#### Commit Changes and Push
+
+1. **Commit changes**
+2. **Push to remote**
+
+#### Repeat Until Complete
+
+- **SM**: Create next story → Review → Approve
+- **Dev**: Implement story → Complete → Mark Ready for Review
+- **QA**: Review story → Mark done
+- **Commit**: All changes
+- **Push**: To remote
+- **Continue**: Until all features implemented
+
+## IDE-Specific Syntax
+
+### Agent Loading Syntax by IDE
+
+- **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
+- **Cursor**: `@agent-name` (e.g., `@bmad-master`)
+- **Gemini CLI**: `*agent-name` (e.g., `*bmad-master`)
+- **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
+- **Trae**: `@agent-name` (e.g., `@bmad-master`)
+- **Roo Code**: Select mode from mode selector (e.g., `bmad-master`)
+- **GitHub Copilot**: Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.
+
+### Chat Management
+
+- **Claude Code, Cursor, Windsurf, Trae**: Start new chats when switching agents
+- **Roo Code**: Switch modes within the same conversation
+
+## Available Agents
+
+### Core Development Agents
+
+- **bmad-master**: Universal task executor, document management
+- **sm**: Scrum Master for story creation and agile process
+- **dev**: Full-stack developer for implementation
+- **architect**: Solution architect for technical design
+
+### Specialized Agents
+
+- **pm**: Product manager for planning and prioritization
+- **analyst**: Business analyst for requirements
+- **qa**: QA specialist for testing strategies
+- **po**: Product owner for backlog management
+- **ux-expert**: UX specialist for design
+
+## Key Principles
+
+1. **Agent Specialization**: Each agent has specific expertise and responsibilities
+2. **Clean Handoffs**: Always start fresh when switching between agents
+3. **Status Tracking**: Maintain story statuses (Draft → Approved → InProgress → Done)
+4. **Iterative Development**: Complete one story before starting the next
+5. **Documentation First**: Always start with solid PRD and architecture
+
+## Common Commands
+
+Every agent supports these core commands:
+
+- `*help` - Show available commands
+- `*status` - Show current context/progress
+- `*exit` - Exit the agent mode
+
+## Success Tips
+
+- **Use Gemini for big picture planning** - The team-fullstack bundle provides collaborative expertise
+- **Use bmad-master for document organization** - Sharding creates manageable chunks
+- **Follow the SM → Dev cycle religiously** - This ensures systematic progress
+- **Keep conversations focused** - One agent, one task per conversation
+- **Review everything** - Always review and approve before marking complete
+
+This workflow ensures systematic, AI-assisted development following agile principles with clear separation of concerns and consistent progress tracking.
diff --git a/package.json b/package.json
index 63bea203..14ae9369 100644
--- a/package.json
+++ b/package.json
@@ -43,6 +43,8 @@
     "inquirer": "^8.2.6",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.0.3",
+    "ora": "^8.2.0"
+    "minimatch": "^10.0.3",
     "ora": "^5.4.1"
   },
   "keywords": [
@@ -67,6 +69,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "husky": "^9.1.7",
+    "jest": "^30.0.4",
     "lint-staged": "^16.1.1",
     "prettier": "^3.5.3",
     "semantic-release": "^22.0.0",
diff --git a/z2/.roomodes b/z2/.roomodes
new file mode 100644
index 00000000..dbd39467
--- /dev/null
+++ b/z2/.roomodes
@@ -0,0 +1,95 @@
+customModes:
+ - slug: bmad-ux-expert
+   name: '🎨 UX Expert'
+   roleDefinition: You are a UX Expert specializing in ux expert tasks and responsibilities.
+   whenToUse: Use for UX Expert tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/ux-expert.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(md|css|scss|html|jsx|tsx)$
+        description: Design-related files
+ - slug: bmad-sm
+   name: '🏃 Scrum Master'
+   roleDefinition: You are a Scrum Master specializing in scrum master tasks and responsibilities.
+   whenToUse: Use for Scrum Master tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/sm.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(md|txt)$
+        description: Process and planning docs
+ - slug: bmad-qa
+   name: '🧪 Senior Developer & QA Architect'
+   roleDefinition: You are a Senior Developer & QA Architect specializing in senior developer & qa architect tasks and responsibilities.
+   whenToUse: Use for Senior Developer & QA Architect tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/qa.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(test|spec)\.(js|ts|jsx|tsx)$|\.md$
+        description: Test files and documentation
+ - slug: bmad-po
+   name: '📝 Product Owner'
+   roleDefinition: You are a Product Owner specializing in product owner tasks and responsibilities.
+   whenToUse: Use for Product Owner tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/po.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(md|txt)$
+        description: Story and requirement docs
+ - slug: bmad-pm
+   name: '📋 Product Manager'
+   roleDefinition: You are a Product Manager specializing in product manager tasks and responsibilities.
+   whenToUse: Use for Product Manager tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/pm.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(md|txt)$
+        description: Product documentation
+ - slug: bmad-dev
+   name: '💻 Full Stack Developer'
+   roleDefinition: You are a Full Stack Developer specializing in full stack developer tasks and responsibilities.
+   whenToUse: Use for code implementation, debugging, refactoring, and development best practices
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/dev.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - edit
+ - slug: bmad-orchestrator
+   name: '🎭 BMad Master Orchestrator'
+   roleDefinition: You are a BMad Master Orchestrator specializing in bmad master orchestrator tasks and responsibilities.
+   whenToUse: Use for BMad Master Orchestrator tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/bmad-orchestrator.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - edit
+ - slug: bmad-master
+   name: '🧙 BMad Master Task Executor'
+   roleDefinition: You are a BMad Master Task Executor specializing in bmad master task executor tasks and responsibilities.
+   whenToUse: Use for BMad Master Task Executor tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/bmad-master.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - edit
+ - slug: bmad-architect
+   name: '🏗️ Architect'
+   roleDefinition: You are a Architect specializing in architect tasks and responsibilities.
+   whenToUse: Use for Architect tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/architect.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(md|txt|yml|yaml|json)$
+        description: Architecture docs and configs
+ - slug: bmad-analyst
+   name: '📊 Business Analyst'
+   roleDefinition: You are a Business Analyst specializing in business analyst tasks and responsibilities.
+   whenToUse: Use for Business Analyst tasks
+   customInstructions: CRITICAL Read the full YAML from .bmad-core/agents/analyst.md start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode
+   groups:
+    - read
+    - - edit
+      - fileRegex: \.(md|txt)$
+        description: Documentation and text files