Complete restructure with logical separation:
Lesson 01: Git Setup (15-20 min)
- GitHub account creation
- Repository creation or joining existing
- Single vs separate repo decision at naming
Lesson 02: IDE Installation (10 min)
- Cursor or VS Code choice and installation
- First launch setup
- Terminal verification
Lesson 03: Git Repository Cloning (10 min)
- Create Projects folder
- Clone your repository
- Open in IDE
- Git auto-installation by IDE
Lesson 04: WDS Project Initialization (15-20 min)
- Clone WDS repository
- Add WDS to workspace
- Create 8-phase docs structure
- Activate Mimir
Each lesson:
- 01-quick-checklist.md (checkbox action list)
- 02-full-lesson.md (detailed explanation)
Also organized course explainers:
- Created course-explainers/ folder at course root
- Moved all NotebookLM and YouTube content there
- Cleaner module folders
Benefits:
- Clear logical separation of concerns
- Mimir integrated with WDS init (natural fit)
- Git cloning separate from WDS setup
- Each lesson focused on single topic
- Dual format for all learning styles
Renamed all lesson files with clear numbered prefixes:
Before:
- checklist.md
- lesson.md
After:
- 01-quick-checklist.md
- 02-full-lesson.md
Benefits:
- Clear ordering in file browser
- Easy to see which is quick vs full
- Professional file naming
- Better for navigation
- Consistent across all 4 lessons
Updated module overview with new filenames.
Each lesson now has two files:
- checklist.md: Quick action list with checkboxes
- lesson.md: Full detailed explanation
Overview updated to show both options per lesson.
Updated all Module 02 lesson titles for better scannability:
Before (verb-first):
- Setting Up GitHub
- Install IDE
- Git Setup
- Clone & Add WDS
- Initiate Mimir
After (value-first):
- GitHub Setup
- IDE Installation
- Git Configuration
- Repository Cloning & WDS Integration
- Mimir Activation
Benefits:
- Immediate understanding of what's covered
- Better scannability in overview
- Professional terminology
- Clear value proposition
- Easier to reference specific lessons
Follows principle: Value word should appear as early as possible
in titles for maximum comprehension speed.
Major restructure for better organization and navigation:
New Structure:
- module-02-overview.md (minimal, just links to lessons)
- lesson-01-github-account/tutorial.md
- lesson-02-create-repository/tutorial.md
- lesson-03-install-ide/tutorial.md
- lesson-04-git-setup/tutorial.md
- lesson-05-clone-and-wds/tutorial.md
- lesson-06-initiate-mimir/tutorial.md
Each Lesson Contains:
- Focused tutorial on one specific task
- Clear time estimate
- Step-by-step instructions
- Troubleshooting section
- Navigation to next lesson
Overview Benefits:
- Minimal and scannable
- Easy to navigate between lessons
- See progress through module
- Jump to specific lesson easily
Lesson Benefits:
- Self-contained tutorials
- Focused on single topic
- Can be referenced individually
- Progressive complexity
- Clear completion criteria
Old tutorial-02.md kept for reference until verified working.
Critical UX improvement: Decision happens at the RIGHT moment.
Changes to Step 2.2 (Repository Settings):
- ADDED: Comprehensive 'Single vs Separate Repo' decision framework
- Decision now happens DURING naming (not after)
- Clear naming convention: 'my-project' vs 'my-project-specs'
Single Repository Use Cases:
✅ Close to development team
✅ Simple, direct communication needed
✅ Building the project yourself
✅ Working closely with other designers
✅ Small team with full ownership
✅ Rapid iteration and feedback
Separate Repository Use Cases:
✅ Corporate or enterprise environment
✅ Specifications serve multiple products/platforms
✅ Development team has many developers
✅ Extensive or complex codebase
✅ Clear handoff boundaries needed
✅ Design and dev have separate workflows
Changes to Step 2.3:
- Acknowledge decision was made
- Remind about implications
Changes to Step 4.1:
- SIMPLIFIED: Just recap the decision made in Step 2
- No longer presenting options (already decided!)
- Cleaner flow
Reasoning:
Repository NAME determines structure. The decision must happen when
naming the repository, not later. This is when GitHub asks 'what do
you want to call this?' - that's the natural decision point.
Benefits:
- Decision at natural moment (when naming)
- Clear naming conventions prevent confusion
- Users understand implications before creating
- No 'oops, I named it wrong' moments
- Professional guidance on when to use each approach
Reorganization for better logical flow:
Changes:
- MOVED: 'One Repo or Two?' decision from Step 2.4 to Step 4.1
- Placed BEFORE Git installation discussion
- Added note in Step 2 pointing forward to Step 4
Reasoning:
- Repository structure decision affects how you'll set up Git workflow
- Makes more sense alongside Git/GitHub Desktop discussion
- GitHub Desktop can help visualize the single vs separate decision
- Users make informed choice before cloning
- Better pedagogical flow: Create repo → Understand structure → Clone it
Benefits:
- Decision happens at the right moment (before cloning)
- Connected to tooling discussion (Git/GitHub Desktop)
- Eliminates duplicate content
- Clearer mental model for beginners
Major UX improvement for complete beginners:
Tutorial Changes (Step 4):
- REMOVED: Manual Git installation steps with command line
- ADDED: Explanation that IDE handles Git automatically
- ADDED: GitHub Desktop as visual alternative for non-technical users
- NEW APPROACH: Let Cursor prompt for Git installation when needed
Key improvements:
- Beginners don't need to manually install Git
- Cursor/VS Code will automatically prompt when cloning
- Optional GitHub Desktop path for visual learners
- Reduces friction and confusion for designers
- Eliminates 'why am I doing this?' questions
Overview Changes:
- Updated lesson descriptions to match tutorial flow
- Clarified Git is handled automatically
- Updated completion checklist
- Improved tutorial description
Reasoning:
Complete beginners don't need to understand Git installation.
Modern IDEs handle this transparently. Let the tools do the work.
Designers can focus on design, not developer tooling.
Complete rewrite of Installation & Setup module targeting designers with
zero technical experience:
Overview Changes:
- Expanded from 30min to 45-60min to accommodate beginners
- Added GitHub account creation as first step
- Added repository setup and naming guidance
- Added IDE installation (Cursor vs VS Code comparison)
- Reduced prerequisites to absolute minimum (just computer + internet)
- New lesson structure: GitHub → Repository → IDE → Clone → WDS → Mimir
Tutorial Changes (8 detailed steps):
1. Create GitHub Account - Username tips, verification
2. Create Project Repository - Naming, public/private, one vs two repos
3. Install IDE - Cursor vs VS Code, first launch setup
4. Install Git - Check, install, configure
5. Clone Repository - URL, location, terminal commands
6. Add WDS to Workspace - Inside vs beside decision
7. Create Docs Structure - 8-phase folders with platform-specific commands
8. Initiate with Mimir - Drag file, first interaction
New Features:
- Screenshot-worthy step-by-step instructions
- Platform-specific commands (Windows/Mac/Linux)
- Troubleshooting section for common beginner issues
- Visual file structure diagrams
- Pro tips for ongoing use
- Quick reference for 'what lives where'
- Encouragement and celebration at each checkpoint
Target: Designer who has never used GitHub, Git, or an IDE before.
- Add training course section to orchestrator with module overview
- Update presentation to suggest training for new users
- Expand Patient Trainer role to include course guidance
- Provide @wds-mimir training invocation example
Users can now be guided through comprehensive WDS training with:
@wds-mimir Take me through the WDS training
- Add mimir-presentation.md introducing the WDS guide/coach/trainer persona
- Create MIMIR-WDS-ORCHESTRATOR.md with complete orchestration logic
- Include initialization sequence: presentation → assessment → environment check → routing
- Add adaptive teaching based on skill levels (beginner to experienced)
- Integrate with existing project-analysis-router.md workflow
- Add @wds-mimir chat invocation instructions
- Fix workflow folder names in MANUAL-INIT-GUIDE.md
Mimir serves as the welcoming entry point, assessing user needs and routing to
specialist agents (Freyja, Idunn, Saga) when appropriate.
- Created DRAG-ME-TO-AI-CHAT-TO-GET-STARTED.md for AI agent context
- AI automatically checks if WDS repo exists
- AI offers to clone WDS if not found
- Zero manual setup required - just drag file to chat
- Supports both workspace and copied setups
AGENTS COMPLETE (3 files):
- Created saga-analyst.agent.yaml (Saga - WDS Analyst)
- Created idunn-pm.agent.yaml (Idunn - WDS PM)
- Created freyja-ux.agent.yaml (Freyja - WDS Designer)
- All agents include presentations, personas, and full menu integration
- Norse mythology theme unified across all agents
DOCUMENTATION UPDATES:
- Updated README with complete 8-phase structure
- Updated folder structure to show
- Added language configuration options for specification and product languages in the workflow setup.
- Updated workflow YAML files to include descriptive metadata for better clarity and organization.
- Enhanced the workflow initialization instructions to guide users in configuring language settings.
- Revised project brief and PRD platform workflows to reflect the latest structural changes and improve usability.
- Documented new features and improvements in the WDS conversion roadmap, emphasizing the completion of Phase 4 workflows.
- Updated the WDS conversion roadmap with the latest phase naming conventions and statuses.
- Introduced a new section detailing key methodology refinements, including scoring systems for feature prioritization and clarifications on the design system's optional and parallel nature.
- Enhanced the PRD platform phase to emphasize technical foundations and proofs of concept.
- Revised phase outputs and documentation structure for improved clarity and organization.
- Completed all phase guides with positive language and unified naming conventions for better integration with design tools.
- Updated the WDS conversion roadmap to include Positive Language Guidelines, emphasizing the use of constructive language in documentation.
- Removed outdated phase documents for Product Exploration, User Research, and Requirements, streamlining the method guide.
- Revised the UX Design phase to focus on UX-Sketches and Usage Scenarios, improving clarity on design processes.
- Finalized the PRD structure in the integration guide, ensuring comprehensive coverage of functional requirements and development priorities.
- Enhanced documentation for the Design System phase, detailing component extraction and integration with design tools.
- Renamed specialized design agents in README and related documents to include "the" in their titles for consistency and clarity.
- Updated references to agents in the WDS conversion roadmap and method guide to reflect the new naming convention.
- Enhanced documentation to improve readability and user understanding of agent roles within the WDS framework.
- Renamed the project from BMad Method to Whiteport Design Studio (WDS)
- Added new badges for WDS and updated project status
- Introduced WDS as a design-focused methodology module complementing BMad Method
- Detailed the folder structure and workflow phases for WDS
- Included information about specialized design agents and their roles
- Enhanced documentation for clarity and organization
This update aligns the README with the current project structure and goals, emphasizing the integration of design workflows into the BMad ecosystem.
## Major Features Added
- **Step-file workflow architecture**: Transform monolithic workflows into granular step files for improved LLM adherence and consistency
- **Multi-menu handler system**: New `handler-multi.xml` enables grouped menu items with fuzzy matching
- **Workflow compliance checker**: Added automated compliance validation for all workflows
- **Create/edit agent workflows**: New structured workflows for agent creation and editing
## Workflow Enhancements
- **Create-workflow**: Expanded from 6 to 14 detailed steps covering tools, design, compliance
- **Granular step execution**: Each workflow step now has dedicated files for focused execution
- **New documentation**: Added CSV data standards, intent vs prescriptive spectrum, and common tools reference
## Complete Migration Status
- **4 workflows fully migrated**: `create-agent`, `edit-agent`, `create-workflow`, and `edit-workflow` now use the new granular step-file architecture
- **Legacy transformation**: `edit-workflow` includes built-in capability to transform legacy single-file workflows into the new improved granular format
- **Future cleanup**: Legacy versions will be removed in a future commit after validation
## Schema Updates
- **Multi-menu support**: Updated agent schema to support `triggers` array for grouped menu items
- **Legacy compatibility**: Maintains backward compatibility with single `trigger` field
- **Discussion enhancements**: Added conversational_knowledge recommendation for discussion agents
## File Structure Changes
- Added: `create-agent/`, `edit-agent/`, `edit-workflow/`, `workflow-compliance-check/` workflows
- Added: Documentation standards and CSV reference files
- Refactored: `create-workflow/steps/` with detailed granular step files
## Handler Improvements
- Enhanced `handler-exec.xml` with clearer execution instructions
- Improved data passing context for executed files
- Better error handling and user guidance
This architectural change significantly improves workflow execution consistency across all LLM models by breaking complex processes into manageable, focused steps. The edit-workflow transformation tool ensures smooth migration of existing workflows to the new format.
- Removed all references to Phase 0 (should be Documentation prerequisite)
- Updated phase transitions from 'Phase 3→4' to 'Phase 3 to Phase 4'
- Ensured all phases are numbered 1-4 consistently
- Documentation for brownfield projects is now correctly referred to as 'Documentation prerequisite' rather than Phase 0
- Updated workflows-implementation.md: removed validate workflows, epic-tech-context, story-context
- Updated workflows-analysis.md: removed brainstorm-game, game-brief, added domain-research
- Updated workflows-planning.md: removed gdd, narrative, moved create-epics-and-stories to Phase 3
- Updated workflows-solutioning.md: already correct with create-epics-and-stories in Phase 3
- Removed all Mermaid diagrams and replaced with text descriptions
- Updated quick reference tables to reflect actual workflows
- Fixed flow examples to match current implementation
Mårten Angner
Alex Verkhovsky
Brian Madison