ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

refactor(wds): Rewrite Module 02 for complete beginners 

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.
This commit is contained in:
Mårten Angner 2025-12-11 13:30:30 +01:00
parent e4ddb8e094
commit 9b145af460
2 changed files with 468 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
src/modules/wds/course/module-02-installation-setup/module-02-overview.md
View File

@ -1,6 +1,6 @@
# Module 02: Installation & Setup
**Get WDS running and create your first project structure**
**From zero to WDS-ready in one session - even if you've never used GitHub or an IDE before**
---
@ -8,13 +8,17 @@
In this module, you'll:
1. **Install WDS** - Clone the repository and verify it's working
2. **Understand the Structure** - Learn how WDS organizes your work
3. **Create Your Project** - Set up your first WDS project folder
4. **Meet the Agents** - Get introduced to Freyja, Saga, and Idunn
1. **Create Your GitHub Account** - Set up your professional home for projects
2. **Create Your Project Repository** - Decide on naming and structure
3. **Install Your IDE** - Get Cursor or VS Code running
4. **Clone Your Project** - Bring your repository to your computer
5. **Install WDS** - Add the methodology to your workspace
6. **Initiate with Mimir** - Drag the starter file and begin
**Time investment:** 30 minutes
**Result:** WDS installed and your first project ready to go
**Time investment:** 45-60 minutes (first time)
**Result:** Complete professional setup, ready to design
**Target audience:** Complete beginners welcome! No prior experience needed.
---
@ -93,14 +97,20 @@ Once you've completed Module 02:
## Prerequisites
Before starting this module:
**Absolute minimum to start this module:**
- ✅ Basic command line familiarity (copy-paste level)
- ✅ Code editor installed (VS Code, Cursor, or similar)
- ✅ Git installed on your system
- ✅ Node.js 18+ installed
- ✅ A computer (Windows, Mac, or Linux)
- ✅ Internet connection
- ✅ Email address for GitHub account
- ✅ Willingness to learn (we'll guide you through everything else!)
**New to command line?** No problem! We provide exact commands to copy and paste.
**You DON'T need:**
- ❌ Prior GitHub experience
- ❌ Command line knowledge
- ❌ Technical background
- ❌ Coding skills
**New to all of this?** Perfect! This module is designed for you.
---

586
src/modules/wds/course/module-02-installation-setup/tutorial-02.md
View File

@ -1,217 +1,521 @@
# Tutorial 02: Install WDS in 5 Minutes
# Tutorial 02: Complete Beginner Setup
**Quick, hands-on guide to get WDS running**
**From zero to WDS-ready - step by step, screenshot by screenshot**
---
## What You'll Do
## 🎯 What You'll Accomplish
1. Check prerequisites
2. Clone WDS repository
3. Verify installation
4. Create your first project
5. Meet Mimir
By the end of this tutorial:
**Total time:** 5-10 minutes
- ✅ GitHub account created
- ✅ Project repository set up
- ✅ IDE installed (Cursor or VS Code)
- ✅ Project cloned to your computer
- ✅ WDS added to workspace
- ✅ Mimir activated and ready to guide you
**Total time:** 45-60 minutes (first time)
**No prior experience needed!** We assume you're starting from zero.
---
## Step 1: Check Prerequisites ✅
## Step 1: Create Your GitHub Account 🌐
**Open your terminal and verify:**
**What is GitHub?** Think of it as a professional cloud storage + time machine for your project files. Every change is saved, you can go back to any version, and you can work with others.
### 1.1 Sign Up
1. Go to **https://github.com**
2. Click the green **"Sign up"** button (top right)
3. Enter your email address
4. Create a password (make it strong!)
5. Choose a username
**Username Tips:**
- Professional (you might share this with clients)
- Simple and memorable
- Examples: `john-designer`, `sarahux`, `mike-creates`
6. Verify you're human (solve the puzzle)
7. Check your email and click the verification link
**✅ Checkpoint:** You can log in to GitHub
---
## Step 2: Create Your Project Repository 📦
**What is a repository?** A folder that GitHub tracks. Every change you make is saved, and you can always go back.
### 2.1 Navigate to Repositories
1. After logging in, click your **profile icon** (top right)
2. Click **"Your repositories"**
3. Click the green **"New"** button
### 2.2 Repository Settings
**Repository Name:**
- Use lowercase with hyphens
- Descriptive and specific
- Examples: `dog-walker-app`, `recipe-sharing-platform`, `fitness-tracker-specs`
**Description:**
- Short one-liner about your project
- Example: "UX specifications for Dog Week family coordination app"
**Public vs Private:**
- **Public:** Anyone can see (good for portfolio projects)
- **Private:** Only you and invited collaborators (good for client work)
**Initialize with README:**
- ☑️ **Check this box!** It creates a starter file
**DO NOT** add .gitignore or license yet (we'll do this later)
### 2.3 Create Repository
Click the green **"Create repository"** button
**✅ Checkpoint:** You see your new repository with a README file
### 2.4 One Repo or Two?
**Important Decision:**
**Option A: Single Repository (Recommended for beginners)**
```
my-project/
├── docs/ ← Your WDS specifications
└── src/ ← Code (if building yourself)
```
**Pros:** Everything in one place, simpler
**Best for:** Solo projects, learning, full ownership
**Option B: Separate Repositories**
```
my-project-specs/ ← WDS specifications (this repo)
my-project-code/ ← Separate code repo
```
**Pros:** Clean separation, easier handoff to developers
**Best for:** Client projects, team collaboration
**For this tutorial, we'll use Option A (single repo).**
---
## Step 3: Install Your IDE 💻
**What is an IDE?** Your workspace for creating specifications. Like Microsoft Word, but for design files.
### 3.1 Choose: Cursor or VS Code?
**Cursor (Recommended)**
- Built for AI assistance
- Modern interface
- Perfect for WDS
- **Download:** https://cursor.sh
**VS Code (Alternative)**
- Industry standard
- More extensions
- Works great with WDS too
- **Download:** https://code.visualstudio.com
**For beginners:** Choose Cursor. It's designed for AI-augmented work.
### 3.2 Install Cursor
1. Download from **https://cursor.sh**
2. Run the installer
- **Windows:** Double-click the `.exe` file
- **Mac:** Drag Cursor to Applications folder
- **Linux:** Follow the Linux installation instructions
3. Open Cursor for the first time
4. Choose your theme (Light or Dark - you can change this later)
### 3.3 First Launch Setup
Cursor will ask you a few questions:
- **"Import settings from VS Code?"** → Skip (unless you already use VS Code)
- **"Sign in with GitHub?"** → Yes! (makes cloning easier)
- **"Install recommended extensions?"** → Yes
**✅ Checkpoint:** Cursor is open and ready
---
## Step 4: Install Git 🔧
**What is Git?** The behind-the-scenes tool that syncs your computer with GitHub.
### 4.1 Check if Git is Already Installed
In Cursor:
1. Press **Ctrl+`** (Windows/Linux) or **Cmd+`** (Mac) to open terminal
2. Type: `git --version`
3. Press Enter
**If you see a version number (like `git version 2.x.x`):**
✅ Git is installed! Skip to Step 5.
**If you see "command not found":**
Continue to 4.2 below.
### 4.2 Install Git
**Windows:**
1. Download from **https://git-scm.com/download/win**
2. Run the installer
3. Use all default settings (just keep clicking "Next")
4. Restart Cursor after installation
**Mac:**
1. In Cursor terminal, type: `git --version`
2. Mac will prompt you to install developer tools
3. Click "Install" and wait for it to complete
**Linux:**
```bash
# Check Node.js version (need 18+)
node --version
# Ubuntu/Debian
sudo apt-get install git
# Check Git
git --version
# Fedora
sudo dnf install git
```
**Expected output:**
- Node: `v18.x.x` or higher
- Git: `git version 2.x.x` or similar
### 4.3 Configure Git (First Time Only)
**Missing something?**
- Install Node.js: https://nodejs.org/
- Install Git: https://git-scm.com/
In Cursor terminal, type these commands (replace with YOUR info):
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```
**Use the same email you used for GitHub!**
**✅ Checkpoint:** `git --version` shows a version number
---
## Step 2: Clone WDS Repository 📦
## Step 5: Clone Your Project Repository 📥
**Choose your workspace location:**
**What is cloning?** Copying your GitHub repository to your computer so you can work on it.
### 5.1 Get Your Repository URL
1. Go to your repository on GitHub
2. Click the green **"Code"** button
3. Make sure **"HTTPS"** is selected
4. Click the **copy icon** (📋) to copy the URL
**Your URL looks like:** `https://github.com/your-username/your-project.git`
### 5.2 Choose Where to Clone
**Windows:** `C:\Users\YourName\Projects\`
**Mac/Linux:** `/Users/YourName/Projects/` or `~/Projects/`
**Don't have a Projects folder?** Let's create one:
In Cursor terminal:
```bash
# Windows
mkdir C:\Projects
cd C:\Projects
# Mac/Linux
mkdir ~/Projects
cd ~/Projects
```
### 5.3 Clone the Repository
In Cursor terminal, type:
```bash
# Navigate to where you want WDS
cd ~/projects # Mac/Linux
cd C:\dev # Windows
git clone [paste your URL here]
```
**Example:**
```bash
git clone https://github.com/john-designer/dog-walker-app.git
```
Press Enter and wait for it to download.
**✅ Checkpoint:** You see "Cloning into..." and then "done"
### 5.4 Open Your Project in Cursor
1. In Cursor: **File** → **Open Folder**
2. Navigate to your Projects folder
3. Select your project folder (e.g., `dog-walker-app`)
4. Click **"Select Folder"** or **"Open"**
**✅ Checkpoint:** You see your project name in the left sidebar with the README.md file
---
## Step 6: Add WDS to Your Workspace 🎨
**What is WDS?** The methodology files that contain agents, workflows, and training.
### 6.1 Decide: Clone WDS Inside or Beside?
**Option A: Inside Your Project (Simpler)**
```
my-project/
├── .wds/ ← WDS here
├── docs/ ← Your specs
└── README.md
```
**Option B: Separate in Workspace (Recommended)**
```
Workspace/
├── my-project/ ← Your project
└── whiteport-design-studio/ ← WDS here
```
**For beginners: Use Option B** (easier to update WDS later)
### 6.2 Add WDS to Workspace
**Method 1: Through Cursor (Easiest)**
1. In Cursor: **File** → **Add Folder to Workspace**
2. You'll now clone WDS
In Cursor terminal (make sure you're in your Projects folder):
```bash
# Navigate to Projects folder
cd ~/Projects # Mac/Linux
cd C:\Projects # Windows
# Clone WDS
git clone https://github.com/whiteport-collective/whiteport-design-studio.git
# Enter the directory
cd whiteport-design-studio
```
**✅ Checkpoint:** You should see WDS files in your directory
3. Back in Cursor: **File** → **Add Folder to Workspace**
4. Select the `whiteport-design-studio` folder
5. Click **"Add"**
**✅ Checkpoint:** You see both folders in your Cursor sidebar:
- your-project
- whiteport-design-studio
---
## Step 3: Verify Installation 🔍
## Step 7: Create Your Docs Structure 📁
**Check the structure:**
**What is the docs folder?** Where all your WDS specifications will live. This is your design source of truth.
### 7.1 Create the 8-Phase Structure
In Cursor terminal (make sure you're in YOUR project folder):
```bash
# List WDS contents
ls -la # Mac/Linux
dir # Windows
# Navigate to your project
cd ~/Projects/dog-walker-app # Change to YOUR project name
# Create docs structure
mkdir -p docs/1-project-brief
mkdir -p docs/2-trigger-mapping
mkdir -p docs/3-prd-platform
mkdir -p docs/4-ux-design
mkdir -p docs/5-design-system
mkdir -p docs/6-design-deliveries
mkdir -p docs/7-testing
mkdir -p docs/8-ongoing-development
```
**You should see:**
- `src/modules/wds/` - The WDS methodology
- `src/modules/wds/agents/` - Agent definitions
- `src/modules/wds/workflows/` - Workflow guides
- `src/modules/wds/course/` - This training
**✅ Checkpoint:** All folders present
---
## Step 4: Add WDS to Your IDE Workspace 🎨
**Option A: Cursor / VS Code**
1. Open your IDE
2. File → Add Folder to Workspace
3. Select the `whiteport-design-studio` folder
4. WDS is now in your workspace!
**Option B: Already have a project?**
Add WDS alongside your existing project:
```
YourWorkspace/
├── your-project/
└── whiteport-design-studio/ ← Add this
```
**✅ Checkpoint:** WDS appears in your IDE sidebar
---
## Step 5: Create Your First Project 📁
**In your project folder, create the docs structure:**
**Windows alternative (if mkdir -p doesn't work):**
```bash
# Navigate to your project (not WDS)
cd ../your-project
# Create docs folder with WDS structure
mkdir -p docs/{1-project-brief,2-trigger-mapping,3-prd-platform,4-ux-design,5-design-system,6-design-deliveries,7-testing,8-ongoing-development}
# Verify structure
ls docs/
mkdir docs
cd docs
mkdir 1-project-brief
mkdir 2-trigger-mapping
mkdir 3-prd-platform
mkdir 4-ux-design
mkdir 5-design-system
mkdir 6-design-deliveries
mkdir 7-testing
mkdir 8-ongoing-development
cd ..
```
**✅ Checkpoint:** You should see 8 numbered folders
**✅ Checkpoint:** You see a `docs/` folder with 8 numbered subfolders in your project
---
## Step 6: Meet Mimir 🧠
## Step 8: Initiate with Mimir 🧠
**Start a new conversation with your AI assistant:**
**What is Mimir?** Your WDS guide and orchestrator. He'll assess your needs and connect you with the right agents.
### 8.1 Find the Mimir File
In Cursor sidebar:
1. Expand `whiteport-design-studio`
2. Expand `src` → `modules` → `wds`
3. Find **`MIMIR-WDS-ORCHESTRATOR.md`**
### 8.2 Drag to AI Chat
1. **Open AI chat** in Cursor (usually the chat icon, or press Ctrl+L / Cmd+L)
2. **Drag** `MIMIR-WDS-ORCHESTRATOR.md` into the chat input area
3. **Press Enter** or click Send
**Alternative method:**
Type in chat:
```
@wds-mimir Hello! I just installed WDS and I'm ready to start.
@MIMIR-WDS-ORCHESTRATOR.md
```
**Mimir will:**
1. Welcome you
2. Assess your skill level
3. Check your installation
4. Guide your next steps
### 8.3 Your First Interaction
**Alternative:** You can drag the Mimir file to your chat:
`whiteport-design-studio/src/modules/wds/MIMIR-WDS-ORCHESTRATOR.md`
Mimir will introduce himself and ask you questions like:
- "What's your experience level with design tools?"
- "What project are you working on?"
- "How are you feeling about starting this?"
**Be honest!** Mimir adapts to YOUR level.
After assessment, Mimir will:
- ✅ Verify your installation
- ✅ Explain the next steps
- ✅ Introduce you to specialist agents
- ✅ Guide you to your first workflow
**✅ Checkpoint:** Mimir responds and welcomes you to WDS!
---
## 🎉 Congratulations! You're Set Up!
### What You Just Accomplished
In less than an hour, you:
1. ✅ Created a professional GitHub account
2. ✅ Set up your first project repository
3. ✅ Installed a modern IDE (Cursor)
4. ✅ Cloned your project to your computer
5. ✅ Added WDS methodology to your workspace
6. ✅ Created proper folder structure
7. ✅ Activated Mimir, your guide
8. ✅ Ready to start designing!
**This is a HUGE accomplishment!** Many designers never get past this step. You just did.
---
## Quick Reference: What Lives Where
```
Your Computer/
└── Projects/
├── your-project/ ← YOUR PROJECT
│ ├── docs/ ← Your specifications
│ │ ├── 1-project-brief/
│ │ ├── 2-trigger-mapping/
│ │ ├── 3-prd-platform/
│ │ ├── 4-ux-design/
│ │ ├── 5-design-system/
│ │ ├── 6-design-deliveries/
│ │ ├── 7-testing/
│ │ └── 8-ongoing-development/
│ ├── src/ ← Code (if building)
│ └── README.md ← Project description
│
└── whiteport-design-studio/ ← WDS METHODOLOGY
└── src/modules/wds/
├── agents/ ← Agent definitions
├── workflows/ ← Workflow guides
├── course/ ← Training modules
└── MIMIR-WDS-ORCHESTRATOR.md ← Your guide
```
---
## Troubleshooting 🔧
### Issue: "Command not found: git"
**Solution:** Install Git from https://git-scm.com/
### "Git command not found"
**Solution:** Install Git (see Step 4.2), then restart Cursor
### Issue: "Node version too old"
**Solution:** Update Node.js from https://nodejs.org/
### "Permission denied" when cloning
**Solution:** Make sure you're signed into GitHub in Cursor
### Issue: "Permission denied"
**Solution:**
- Mac/Linux: Try `sudo` if needed
- Windows: Run terminal as administrator
### "Can't find MIMIR file"
**Solution:** Make sure you added `whiteport-design-studio` folder to workspace (Step 6)
### Issue: "Can't find WDS in workspace"
**Solution:** Make sure you added the folder to your IDE workspace (Step 4)
### "Mimir doesn't respond"
**Solution:** Make sure you dragged the ENTIRE file, not just the filename
### "mkdir: cannot create directory"
**Solution:** Make sure you're in your project folder: `cd ~/Projects/your-project`
### Still stuck?
Ask Mimir: **"@wds-mimir I'm stuck on installation, can you help?"**
---
## Verification Checklist ✅
## Next Steps 🚀
Before moving on, confirm:
- ☑️ WDS repository cloned
- ☑️ WDS added to IDE workspace
- ☑️ Your project has `docs/` folder structure
- ☑️ 8 phase folders created (1- through 8-)
- ☑️ Mimir responds when called
**All checked?** You're ready for Module 03! 🎉
---
## What You Just Accomplished 🎊
In just 5-10 minutes, you:
1. ✅ Installed WDS
2. ✅ Set up proper project structure
3. ✅ Connected with Mimir
4. ✅ Ready to start designing
**This is a big deal!** Many designers struggle with setup. You just cleared that hurdle with ease.
---
## Next Steps
**Ready to keep going?**
**Now that you're set up:**
### Option 1: Continue Training
[→ Module 03: Create Project Brief](../module-03-project-brief/module-03-overview.md)
**Want to explore?**
### Option 2: Start Your Project
Ask Mimir:
```
@wds-mimir I want to start working on my project. Where should I begin?
```
- Try calling different agents: `@wds-mimir`, `@freyja-ux`, `@saga-analyst`, `@idunn-pm`
- Read about the 8-phase structure: [Understanding WDS Structure](lesson-02-understanding-structure.md)
- Learn the philosophy: [Module 01: Why WDS Matters](../module-01-why-wds-matters/module-01-overview.md)
### Option 3: Explore WDS
- Browse the workflows folder
- Read about the 8-phase structure
- Check out the other agents (Freyja, Saga, Idunn)
---
## Pro Tips 💡
## Pro Tips for Beginners 💡
**Tip 1:** Keep WDS in your workspace permanently. Reference it across all your projects.
**Tip 1: Commit Often**
Every time you make meaningful progress, save to GitHub:
```bash
git add .
git commit -m "Describe what you did"
git push
```
**Tip 2:** The `docs/` folder is your source of truth. Everything goes here.
**Tip 2: Keep WDS Updated**
Once a month, update WDS to get new features:
```bash
cd ~/Projects/whiteport-design-studio
git pull
```
**Tip 3:** Start every new project with the 8 phase folders. Even if you don't use all of them immediately.
**Tip 3: When in Doubt, Ask Mimir**
```
@wds-mimir [your question]
```
No question is too small!
**Tip 4:** Call Mimir whenever you're unsure. That's literally what he's there for.
**Tip 4: Save Your Workspace**
In Cursor: **File** → **Save Workspace As** → `my-project.code-workspace`
Next time, just open this file!
---
**Congratulations! WDS is ready to use.** 🌊
**You did it! Welcome to WDS.** 🌊
*Part of Module 02: Installation & Setup*
*[← Back to Module Overview](module-02-overview.md)*