20 KiB
20 KiB
WDS v6 Conversion Roadmap
Document Purpose: Complete record of all decisions, context, and progress for converting Whiteport Design Studio to BMad Method v6 format. This document allows continuation of work if the conversation is lost.
Created: December 2, 2025
Last Updated: December 2, 2025
Status: In Progress - Foundation Phase
Table of Contents
- Project Overview
- Key Decisions Made
- Repository Setup
- Module Architecture
- Output Folder Structure
- Design Philosophy
- Development Order
- Files Created So Far
- Next Steps
- Reference Information
1. Project Overview
What is WDS?
Whiteport Design Studio (WDS) is a design-focused methodology module for the BMad Method ecosystem. It provides a complete UX/UI design workflow from product exploration through detailed component specifications.
Origin
WDS evolves from Whiteport Sketch-to-Code (WPS2C), a BMad v4 "expansion pack." The v6 conversion transforms it into a proper BMad module following v6 architecture.
Core Purpose
WDS focuses exclusively on design - it creates the design artifacts that feed into development modules like BMad Method (BMM). WDS does NOT include development/backlog functionality.
Integration Model
WDS (Design) ────────► E-UI-Roadmap/ ────────► BMM (Development)
│ │ │
│ Creates: │ Bridge: │ Consumes:
│ • Product Brief │ • Priority mapping │ • Architecture
│ • Trigger Map │ • Technical notes │ • Stories
│ • Scenarios │ • Handoff checklist │ • Implementation
│ • PRD │ │
│ • Design System │ │
2. Key Decisions Made
2.1 Module Name
Decision: Whiteport Design Studio (WDS)
Alternatives Considered:
- BMad Design Studio
- BMad UX
Reasoning: Preserve brand identity, acknowledge contribution origin, maintain "Whiteport" recognition.
2.2 Repository Approach
Decision: Fork BMad-METHOD repository
Alternatives Considered:
- Standalone repository
- Rename existing WPS2C repo
Reasoning:
- Maximum adoption through BMad ecosystem
- Path to official module status via PR
- Shared core infrastructure
- Automatic ecosystem integration
Fork Details:
- Origin:
https://github.com/whiteport-collective/whiteport-design-studio.git - Upstream:
https://github.com/bmad-code-org/BMAD-METHOD.git
2.3 Working Branch
Decision: Work directly on main branch
Reasoning:
- Simpler workflow during development
- WDS is substantial addition, not small tweak
- Fork effectively becomes WDS home
- Will switch to feature branches after official adoption
2.4 Workflow Approach
Decision: Phase-selectable (not rigid tracks)
Description: Users select individual phases based on project needs rather than choosing from predefined tracks.
Examples:
- Landing page → Phases 1, 4, 5
- Full product → All 6 phases
- Design system only → Phases 4, 5
2.5 Development Handoff
Decision: No development artifacts in WDS
Description: WDS creates design artifacts only. Development (backlog, stories, architecture) handled by BMM. E-UI-Roadmap/ serves as the integration bridge.
2.6 README Convention
Decision: One README.md per repository
Convention: Only README.md at module root; all other documentation uses xxx-guide.md naming pattern.
Examples:
- ✅
wds/README.md(only one) - ✅
wds/docs/method/wds-method-guide.md - ✅
wds/docs/quick-start-guide.md - ❌
wds/docs/README.md(not allowed) - ❌
wds/examples/README.md(not allowed)
3. Repository Setup
3.1 Local Path
C:\dev\WDS\whiteport-design-studio
3.2 Git Remotes
origin → https://github.com/whiteport-collective/whiteport-design-studio.git
upstream → https://github.com/bmad-code-org/BMAD-METHOD.git
3.3 Syncing with Upstream
git fetch upstream
git merge upstream/main
git push origin main
4. Module Architecture
4.1 Module Location
src/modules/wds/
4.2 Folder Structure
src/modules/wds/
├── _module-installer/ # Installation configuration
│ └── install-config.yaml # TO CREATE
│
├── agents/ # WDS agents (v6 YAML format) - Norse Pantheon
│ ├── saga-analyst.agent.yaml # Saga-Analyst - TO CREATE
│ ├── freyja-pm.agent.yaml # Freyja-PM - TO CREATE
│ └── baldr-ux.agent.yaml # Baldr-UX - TO CREATE
│
├── workflows/ # Phase workflows
│ ├── 0-init/ # Entry point - TO CREATE
│ ├── 1-product-exploration/ # Phase 1 - TO CREATE
│ ├── 2-user-research/ # Phase 2 - TO CREATE
│ ├── 3-requirements/ # Phase 3 - TO CREATE
│ ├── 4-conceptual-design/ # Phase 4 - TO CREATE
│ ├── 5-component-design/ # Phase 5 - TO CREATE
│ └── 6-dev-integration/ # Phase 6 - TO CREATE
│
├── data/ # Standards, frameworks
│ ├── presentations/ # Agent intro presentations
│ ├── positioning-framework.md # ICP framework - TO CREATE
│ └── ...
│
├── docs/ # Documentation (xxx-guide.md)
│ ├── method/ # Methodology guides
│ │ ├── wds-method-guide.md # Main overview - TO CREATE
│ │ └── phase-guides/ # Per-phase guides - TO CREATE
│ └── images/ # Diagrams, visuals
│
├── examples/ # Example projects
│ ├── dog-week-patterns/ # Full reference implementation
│ ├── conversation-examples/ # Dialog flow examples
│ └── starter-project/ # Try-it-yourself project
│
├── reference/ # Templates, checklists
│ ├── templates/ # Document templates
│ └── checklists/ # Phase completion checklists
│
├── teams/ # Team configurations
│
└── README.md # Module entry point ✅ CREATED
4.3 Agents - The Norse Pantheon 🏔️
| Agent | File | Role | Norse Meaning | Status |
|---|---|---|---|---|
| Saga-Analyst | saga-analyst.agent.yaml |
Business & Product Analyst | Goddess of stories & wisdom | TO CREATE |
| Freyja-PM | freyja-pm.agent.yaml |
Product Manager | Goddess of love, war & strategy | TO CREATE |
| Baldr-UX | baldr-ux.agent.yaml |
UX/UI Designer | God of light & beauty | TO CREATE |
Why Norse Mythology + Role Suffix?
- Distinctive and memorable mythology names
- Role suffix makes function immediately clear
- Not too obvious (avoided Thor, Odin)
- Creates unique WDS brand identity
5. Output Folder Structure
5.1 The A-B-C-D-E Convention
WDS creates an alphabetized folder structure in the user's project docs/ folder:
docs/
├── A-Product-Brief/ # Phase 1 outputs
├── B-Trigger-Map/ # Phase 2 outputs
├── C-Scenarios/ # Phase 4 outputs
├── D-PRD/ # Phase 3 outputs
├── D-Design-System/ # Phase 5 outputs
└── E-UI-Roadmap/ # Phase 6 outputs (dev bridge)
5.2 Why Alphabetical Prefix?
| Reason | Benefit |
|---|---|
| Visual namespace | Clearly grouped in file explorers |
| Brand signature | "A-B-C-D-E = WDS" recognition |
| Non-conflicting | Won't clash with other docs folders |
| Natural sort | Always grouped together |
| Professional | Enterprise documentation feel |
5.3 Phase-to-Folder Mapping
| Phase | # | Name | Output Folder |
|---|---|---|---|
| 1 | Product Exploration | Strategic foundation | A-Product-Brief/ |
| 2 | User Research | Personas, business goals | B-Trigger-Map/ |
| 3 | Requirements | Functional & technical | D-PRD/ |
| 4 | Conceptual Design | Scenarios, sketches | C-Scenarios/ |
| 5 | Component Design | Design system | D-Design-System/ |
| 6 | Dev Integration | Handoff bridge | E-UI-Roadmap/ |
5.4 E-UI-Roadmap Contents
The integration bridge folder contains:
E-UI-Roadmap/
├── ui-roadmap-guide.md # Overview
├── priority-sequence.md # What to build first
├── scenario-mapping.md # Scenarios → Dev order
├── component-inventory.md # All components needed
├── technical-notes.md # Design constraints
└── open-questions.md # For dev team to decide
6. Design Philosophy
6.1 Core Principles
Principle 1: Soft Language
Instead of: "MUST", "FORBIDDEN", "NEVER", "SYSTEM FAILURE"
Use: Collaborative, identity-based guidance
Reasoning: User experience shows that harsh enforcement language makes agents MORE likely to ignore instructions, not less.
Example - Before:
## MANDATORY RULES
- 🛑 NEVER generate without input
- 🚫 FORBIDDEN: Multiple questions
- ❌ SYSTEM FAILURE if you skip
Example - After:
## How We Work Together
You're a thoughtful guide who helps designers create great products.
Your rhythm:
- Ask one question, then listen
- Reflect back what you heard
- Build the document together
Principle 2: Show, Don't Tell
Instead of: Explaining rules
Use: Concrete examples
Reasoning: People (and LLMs) learn better from examples than abstract rules.
Implementation:
- Complete artifacts as examples (not rule descriptions)
- Conversation flow examples
- Dog Week as reference implementation
Principle 3: Example Projects for Adoption
Purpose:
- Let people try before adopting
- Show what success looks like
- Lower barrier to entry
- Build credibility
Implementation:
- Dog Week patterns as full reference
- Starter project for practice
- Conversation examples showing dialog flow
6.2 Known Problems to Mitigate
| Problem | Observed Behavior | WDS Solution |
|---|---|---|
| Agents ignore instructions | Generate without thinking | Identity-based personas + examples |
| Inconsistent output formats | Specs look different each time | Complete template examples |
| Question dumping | 20 questions at once | Conversation examples showing one-at-a-time |
6.3 Instruction Style
Identity-First:
## Who You Are
You're Mary, a thoughtful business analyst who genuinely cares
about understanding the product before documenting it.
You prefer deep conversations over quick surveys. You ask one
thing at a time because you're actually listening.
Experience-Focused:
## The Conversation Style
A good session feels like coffee with a wise mentor:
- They ask something interesting
- You share your thinking
- They reflect it back
- Together you discover something new
Gentle Reminders:
## Helpful Patterns
What works well:
- One question at a time keeps things focused
- Reflecting back shows you're listening
What to avoid:
- Listing many questions (feels like a survey)
- Generating without checking in
7. Development Order
7.1 Chosen Approach: Methodology-First
Order:
- Define the methodology (phases, outputs, connections)
- Create workflows that implement the methodology
- Create agents that guide users through workflows
- Create examples that demonstrate the methodology
Reasoning:
- The methodology IS the product
- Agents serve the methodology, not vice versa
- User is crystal clear on the workflow (already proven in WPS2C v4)
- Not inventing new process, porting existing one
7.2 Detailed Order
Phase 1: Define the Methodology
| Order | Component | File | Status |
|---|---|---|---|
| 1 | Method Overview | docs/method/wds-method-guide.md |
✅ CREATED |
| 2 | Phase 1 Guide | docs/method/phase-1-exploration-guide.md |
TO CREATE |
| 3 | Phase 2 Guide | docs/method/phase-2-research-guide.md |
TO CREATE |
| 4 | Phase 3 Guide | docs/method/phase-3-requirements-guide.md |
TO CREATE |
| 5 | Phase 4 Guide | docs/method/phase-4-conceptual-guide.md |
TO CREATE |
| 6 | Phase 5 Guide | docs/method/phase-5-components-guide.md |
TO CREATE |
| 7 | Phase 6 Guide | docs/method/phase-6-integration-guide.md |
TO CREATE |
Phase 2: Create Examples
| Order | Component | Location | Status |
|---|---|---|---|
| 8 | Dog Week Examples | examples/dog-week-patterns/ |
TO CREATE |
| 9 | Conversation Examples | examples/conversation-examples/ |
TO CREATE |
| 10 | Starter Project | examples/starter-project/ |
TO CREATE |
Phase 3: Create Workflows
| Order | Component | Location | Status |
|---|---|---|---|
| 11 | workflow-init | workflows/0-init/ |
TO CREATE |
| 12 | Phase Workflows | workflows/1-6/ |
TO CREATE |
Phase 4: Create Agents (The Norse Pantheon)
| Order | Component | File | Status |
|---|---|---|---|
| 13 | Saga-Analyst | agents/saga-analyst.agent.yaml |
TO CREATE |
| 14 | Freyja-PM | agents/freyja-pm.agent.yaml |
TO CREATE |
| 15 | Baldr-UX | agents/baldr-ux.agent.yaml |
TO CREATE |
Phase 5: Finalize
| Order | Component | File | Status |
|---|---|---|---|
| 16 | Install Config | _module-installer/install-config.yaml |
TO CREATE |
| 17 | Teams | teams/ |
TO CREATE |
8. Files Created So Far
8.1 Repository Root
| File | Purpose | Status |
|---|---|---|
README.md |
Fork overview, WDS contribution explanation | ✅ CREATED |
WDS-V6-CONVERSION-ROADMAP.md |
This document | ✅ CREATED |
8.2 Module Structure
| Path | Purpose | Status |
|---|---|---|
src/modules/wds/ |
Module root | ✅ CREATED |
src/modules/wds/README.md |
Module entry point | ✅ CREATED |
src/modules/wds/_module-installer/ |
Install config folder | ✅ CREATED (empty) |
src/modules/wds/agents/ |
Agents folder | ✅ CREATED (empty) |
src/modules/wds/workflows/ |
Workflows folder | ✅ CREATED (empty) |
src/modules/wds/data/ |
Data folder | ✅ CREATED (empty) |
src/modules/wds/data/presentations/ |
Agent presentations | ✅ CREATED (empty) |
src/modules/wds/docs/ |
Documentation folder | ✅ CREATED (empty) |
src/modules/wds/docs/method/ |
Methodology guides | ✅ CREATED (empty) |
src/modules/wds/docs/images/ |
Images folder | ✅ CREATED (empty) |
src/modules/wds/examples/ |
Examples folder | ✅ CREATED (empty) |
src/modules/wds/examples/dog-week-patterns/ |
Dog Week examples | ✅ CREATED (empty) |
src/modules/wds/reference/ |
Reference materials | ✅ CREATED (empty) |
src/modules/wds/reference/templates/ |
Templates | ✅ CREATED (empty) |
src/modules/wds/reference/checklists/ |
Checklists | ✅ CREATED (empty) |
src/modules/wds/teams/ |
Team configs | ✅ CREATED (empty) |
9. Next Steps
Immediate Next Action
Create wds-method-guide.md - The methodology overview document
This will include:
- Overview of the 6 phases
- What each phase produces
- When to use each phase
- How phases connect
- The A-B-C-D-E folder structure
- Links to examples (not rules)
Short-term Roadmap
- Create
wds-method-guide.md - Create phase guide for each phase (6 files)
- Port Dog Week examples to
examples/dog-week-patterns/ - Create conversation examples
- Create workflow-init workflow
- Create first phase workflow (Phase 1)
- Create first agent (Saga-Analyst)
Commit Checkpoint
After creating methodology docs, commit with message:
feat(wds): Add WDS methodology documentation
- Add wds-method-guide.md with 6-phase overview
- Add phase-specific guides
- Establish show-don't-tell documentation approach
10. Reference Information
10.1 Open Design Decisions
To resolve during porting Phase 1 & 2:
| Decision | Options | Resolve When |
|---|---|---|
| ICP/Positioning placement | Phase 1 as hypothesis → Phase 2 validates, OR fully in Phase 2 | Porting Phase 1-2 |
| Prioritization Reasoning | Formal step with output, OR internal thinking process | Porting Phase 2 |
| Business Goals flow | Initial in Brief → Refined in Trigger Map, OR single location | Porting Phase 1-2 |
Context: The Trigger Mapping (Effect Mapping) methodology is very strong. The prioritization reasoning step (column-by-column) is specifically valuable for generating product ideas but may not need formal documentation.
10.2 Product Positioning Framework
To be included in WDS workflows (stored in memory, ID: 11785915):
Positioning Statement Format:
For (target customer)
Who (statement of need or opportunity)
And want (statement of experience expectations)
The (product/service name)
Is (product category)
That (statement of key benefits)
Unlike (primary competitive alternative)
Our product (statement of primary differentiators)
ICP Framework (8 Components):
- My ICP (Who I Serve Best)
- My Positioning (How I'm Different)
- The Outcomes I Drive
- My Offerings (What I Sell)
- Social Proof (Who Can Vouch)
- My Frameworks/Models/Tools (How I Work)
- The Pains My ICP Articulates (Triggers/Frustrations)
- Pricing Anchoring (Cost of Inaction, Bad Hire, % Revenue, Speed)
CTA Elements:
- Website link
- Discovery call link
- Newsletter subscription
- Social follows
- Events attending
10.2 BMad v6 Resources
| Resource | Location |
|---|---|
| BMM Module | src/modules/bmm/ |
| BMB Builder | src/modules/bmb/ |
| CIS Module | src/modules/cis/ |
| Agent Schema | src/modules/bmb/docs/agents/ |
| Workflow Docs | src/modules/bmb/docs/workflows/ |
10.3 Original WPS2C
| Resource | Location |
|---|---|
| WPS2C Repo | C:\dev\whiteport-sketch-to-code-bmad-expansion |
| Method Overview | Method/00-Whiteport-Method.md |
| Agents (v4 format) | bmad-whiteport-sketch/agents/ |
10.4 Dog Week Project
| Resource | Location |
|---|---|
| Project Root | C:\dev\dogweek\dogweek-dev |
| Product Brief | docs/A-Product-Brief/ |
| Trigger Map | docs/B-Trigger-Map/ |
| Scenarios | docs/C-Scenarios/ |
| PRD | docs/D-PRD/ |
Conversation Summary
Key Discussion Points
- Fork vs Standalone: Decided on fork for maximum adoption
- Module Name: Whiteport Design Studio (WDS) to preserve brand
- Branch Strategy: Work on main, switch to feature branches after adoption
- Folder Structure: A-B-C-D-E alphabetical prefix for visual namespace
- Phase Approach: Phase-selectable (not rigid tracks)
- Scope: Design only, no development/backlog (handled by BMM)
- E-UI-Roadmap: Integration bridge to development modules
- Development Order: Methodology-first approach
- Language Style: Soft, collaborative (not MUST/FORBIDDEN)
- Teaching Style: Show, don't tell (examples over rules)
User's Stated Experience
- WPS2C v4 works well, proven methodology
- Strong language (MUST/FORBIDDEN) makes agents ignore instructions
- Softer language gets better compliance
- Examples work better than rules
- Agents tend to question-dump (20 questions at once)
- Output format inconsistency is a problem
Design Philosophy Established
- Soft language by design
- Show, don't tell (examples over explanations)
- Example projects for adoption/training
- Identity-based agent personas
- Conversation examples showing dialog flow
End of Roadmap Document
To continue: Open this document, review "Next Steps" section, and proceed with creating wds-method-guide.md