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.
Mårten Angner