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

feat(wds): Add comprehensive content to all Module 02 lesson tutorials 

Expanded all 5 lessons from basic outlines to complete detailed tutorials:

Lesson 01: GitHub Setup (187 lines)
- Complete GitHub account creation walkthrough
- Repository creation with single vs separate decision
- Joining existing repository scenario with email template
- Comprehensive troubleshooting

Lesson 02: IDE Installation (107 lines)
- Cursor vs VS Code comparison and download
- Platform-specific installation instructions
- First-launch setup wizard guidance
- Terminal verification steps

Lesson 03: Git Configuration (122 lines)
- Repository structure recap
- Three options: Cursor auto-install, GitHub Desktop, Terminal
- Detailed pros/cons for each approach
- Professional workflow validation

Lesson 04: Repository Cloning & WDS Integration (151 lines)
- Projects folder creation
- Repository cloning with examples
- WDS repository integration
- 8-phase docs structure creation
- Visual reference diagram

Lesson 05: Mimir Activation (163 lines)
- Finding Mimir file step-by-step
- AI chat activation instructions
- Example conversation flow
- Celebration of completion
- Pro tips for ongoing use

Total: ~730 lines of detailed beginner-friendly content
Source: Split from comprehensive tutorial-02.md (648 lines)

Benefits:
- Self-contained lessons with full instructions
- No need to reference external file
- Can be taught individually
- Complete troubleshooting in each lesson
- Progressive confidence building
This commit is contained in:
Mårten Angner 2025-12-11 14:16:33 +01:00
parent 21d0a9421d
commit cb2b9c92a6
5 changed files with 143 additions and 191 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
src/modules/wds/course/module-02-installation-setup/lesson-01-setting-up-github/tutorial.md
View File

@ -15,20 +15,13 @@
---
## Part 1: Create Your GitHub Account
## Step 1: Create Your GitHub Account
### What is GitHub?
Think of GitHub as:
- **Professional cloud storage** for your project files
- **Time machine** - every change saved, can go back to any version
- **Collaboration tool** - work with others seamlessly
Think of GitHub 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.
**For designers:** GitHub is where your WDS specifications will live, backed up and version-controlled.
---
### Step 1: Sign Up
### 1.1 Sign Up
1. Go to **https://github.com**
2. Click the green **"Sign up"** button (top right)
@ -37,70 +30,61 @@ Think of GitHub as:
5. Choose a username
**Username Tips:**
✅ **Professional** - You might share this with clients
✅ **Simple** - Easy to remember and spell
✅ **Memorable** - Represents you or your work
**Good Examples:**
- `john-designer`
- `sarahux`
- `mike-creates`
- `[yourname]-design`
- 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!
**✅ Checkpoint:** You can log in to GitHub
---
## Part 2: Create Your Project Repository
## Step 2: Create Your Project Repository
### What is a Repository?
A **repository** is a folder that GitHub tracks. Every change you make is saved, and you can always go back to any version.
A folder that GitHub tracks. Every change you make is saved, and you can always go back.
---
### 2.1 Three Scenarios
### Step 2: Choose Your Scenario
**Before creating a repository, determine which scenario applies to you:**
**Which situation applies to you?**
**Scenario A: Starting a New Project** (Continue to Step 3 below)
**Scenario A: Starting a New Project** (Continue to 2.2 below)
- You're starting fresh
- No existing repository
- You control the setup
**Scenario B: Joining an Existing Project** (Skip to Step 7 below)
**Scenario B: Joining an Existing Project** (Skip to 2.6 below)
- Team project already exists
- Client has existing repository
- Contributing to ongoing work
**Scenario C: Just Learning WDS** (Skip this lesson)
**Scenario C: Using WDS as a Reference Only** (Skip this lesson)
- You're just learning WDS methodology
- Not starting a project yet
- **→ [Continue to Lesson 02: Install IDE](../lesson-02-install-ide/tutorial.md)**
- **→ [Continue to Lesson 02: IDE Installation](../lesson-02-install-ide/tutorial.md)**
**Most beginners: Use Scenario A**
**Most beginners: Use Scenario A (start new project)**
---
## Scenario A: Create New Repository
### Step 3: Navigate to Repositories
### 2.2 Navigate to Repositories
1. After logging in, click your **profile icon** (top right)
2. Click **"Your repositories"**
3. Click the green **"New"** button
---
### Step 4: Choose Repository Structure
### 2.3 Repository Settings
**IMPORTANT: Your naming choice determines your structure!**
#### Option A: Single Repository
#### Single Repo or Separate Specs Repo?
**Option A: Single Repository**
**Name it simply:**
- `dog-walker-app`
@ -122,9 +106,7 @@ dog-walker-app/
- ✅ Small team with full ownership
- ✅ Rapid iteration and feedback
---
#### Option B: Separate Specifications Repository
**Option B: Separate Specifications Repository**
**Name with `-specs` suffix:**
- `dog-walker-app-specs`
@ -134,7 +116,7 @@ dog-walker-app/
**Structure:**
```
dog-walker-app-specs/ ← This repo (specifications only)
dog-walker-app/ ← Separate code repo (create later)
dog-walker-app/ ← Separate code repo
```
**Use when:**
@ -145,9 +127,13 @@ dog-walker-app/ ← Separate code repo (create later)
- ✅ Clear handoff boundaries needed
- ✅ Design and dev have separate workflows
---
**For this tutorial:**
- Beginners: Use **Option A** (single repo like `dog-walker-app`)
- Corporate/Enterprise: Use **Option B** (separate like `dog-walker-app-specs`)
### Step 5: Repository Settings
**Choose your name now based on your situation!**
---
**Repository Name:**
- Use lowercase with hyphens
@ -167,9 +153,7 @@ dog-walker-app/ ← Separate code repo (create later)
**DO NOT** add .gitignore or license yet (we'll do this later)
---
### Step 6: Create Repository
### 2.4 Create Repository
Click the green **"Create repository"** button
@ -179,15 +163,17 @@ Click the green **"Create repository"** button
- Single repo (`my-project`)? Specs and code together
- Separate repo (`my-project-specs`)? You'll create a second repo for code later
**[Continue to Lesson 02: Install IDE →](../lesson-02-install-ide/tutorial.md)**
**[Continue to Lesson 02: IDE Installation →](../lesson-02-install-ide/tutorial.md)**
---
## Scenario B: Joining Existing Repository
### Step 7: Request Repository Access
### 2.6 Request Repository Access
**Email template for repository owner or team lead:**
**If you're joining a team project or client repository:**
**Ask the repository owner or team lead:**
```
Hi [Name],
@ -206,35 +192,31 @@ Thank you!
3. Add your GitHub username
4. You'll receive an email invitation
---
### Step 8: Accept the Invitation
### 2.7 Accept the Invitation
1. Check your email for GitHub invitation
2. Click **"Accept invitation"**
3. Or go to the repository URL directly
4. You'll see an invitation banner → Click **"Accept"**
---
### Step 9: Understand the Existing Structure
### 2.8 Understand the Existing Structure
**Before cloning, check what structure they're using:**
**Look at the repository name:**
Look at the repository name:
- `project-name` → Likely single repo (specs + code together)
- `project-name-specs` → Separate specs repo (code elsewhere)
**Browse the repository:**
Browse the repository:
- Has `docs/` folder? → Probably already using WDS!
- Has `src/` or `app/` folder? → Code lives here too (single repo)
- Only documentation? → Separate specs repo
**When in doubt:** Ask the team lead!
**Ask the team lead if unsure!**
**✅ Checkpoint:** Invitation accepted, you understand the structure
**[Continue to Lesson 02: Install IDE →](../lesson-02-install-ide/tutorial.md)**
**[Continue to Lesson 02: IDE Installation →](../lesson-02-install-ide/tutorial.md)**
---
@ -261,10 +243,9 @@ Thank you!
GitHub is set up and your repository is ready! Now let's install your IDE.
**[Continue to Lesson 02: Install IDE →](../lesson-02-install-ide/tutorial.md)**
**[Continue to Lesson 02: IDE Installation →](../lesson-02-install-ide/tutorial.md)**
---
*Part of Module 02: Installation & Setup*
*[← Back to Module Overview](../module-02-overview.md)*

112
src/modules/wds/course/module-02-installation-setup/lesson-02-install-ide/tutorial.md
View File

@ -19,104 +19,73 @@
**IDE = Integrated Development Environment**
Think of it as your workspace for creating specifications. Like Microsoft Word, but designed for:
- Writing markdown specifications
- Managing project files
- Working with AI assistants
- Version control integration
Your workspace for creating specifications. Like Microsoft Word, but for design files.
---
## Choose Your IDE
## Step 1: Choose Your IDE
### Cursor (Recommended for WDS)
### Cursor (Recommended)
**Why Cursor:**
- ✅ Built specifically for AI-augmented work
- ✅ Modern, clean interface
- ✅ Perfect for WDS methodology
- ✅ Excellent AI chat integration
- Built for AI assistance
- Modern interface
- Perfect for WDS
- **Download:** https://cursor.sh
**Download:** https://cursor.sh
---
### VS Code (Solid Alternative)
### VS Code (Alternative)
**Why VS Code:**
- ✅ Industry standard
- ✅ Huge extension marketplace
- ✅ Works great with WDS
- ✅ What many developers use
- Industry standard
- More extensions
- Works great with WDS too
- **Download:** https://code.visualstudio.com
**Download:** https://code.visualstudio.com
**For beginners:** Choose Cursor. It's designed for AI-augmented work.
---
**For complete beginners:** Choose **Cursor**. It's designed for the way you'll work with WDS.
## Step 2: Install Cursor
---
## Install Cursor
### Step 1: Download
### 2.1 Download
1. Go to **https://cursor.sh**
2. Click the download button for your platform
3. Wait for download to complete
2. Click download button for your platform
3. Wait for download
### Step 2: Install
### 2.2 Install
**Windows:**
1. Double-click the `.exe` file
2. Follow installer prompts
3. Use default settings (just click "Next")
3. Use default settings
4. Click "Finish"
**Mac:**
1. Open the `.dmg` file
1. Open the download
2. Drag Cursor to Applications folder
3. Open Applications folder
4. Double-click Cursor to launch
**Linux:**
1. Follow the installation instructions for your distribution
2. Usually involves extracting and running an installer
1. Follow installation instructions for your distribution
---
### Step 3: First Launch
## Step 3: First Launch Setup
1. Open Cursor for the first time
2. Choose your theme:
- **Light** - Bright background
- **Dark** - Dark background (easier on eyes)
- You can change this later!
2. Choose your theme (Light or Dark - you can change this later)
---
### 3.1 Setup Wizard
### Step 4: Sign In with GitHub
Cursor will ask you a few questions:
**This is important!** Signing in makes cloning repositories much easier.
- **"Import settings from VS Code?"** → Skip (unless you already use VS Code)
- **"Sign in with GitHub?"** → Yes! (makes cloning easier)
- **"Install recommended extensions?"** → Yes
1. Cursor will prompt: **"Sign in with GitHub?"**
2. Click **"Yes"** or **"Sign in"**
3. Your browser will open
4. Click **"Authorize Cursor"**
5. Return to Cursor (should be signed in)
**✅ Checkpoint:** Cursor is open, you're signed into GitHub
---
### Step 5: Install Recommended Extensions (Optional)
Cursor may ask: **"Install recommended extensions?"**
**Click "Yes"** - These extensions are helpful for:
- Markdown previews
- File icons
- Git integration
**✅ Checkpoint:** Cursor is open and ready
---
@ -124,21 +93,13 @@ Cursor may ask: **"Install recommended extensions?"**
If you chose VS Code instead:
### Step 1: Download
### Download and Install
1. Go to **https://code.visualstudio.com**
2. Download for your platform
3. Wait for download
### Step 2: Install
Follow the same installation steps as Cursor above.
### Step 3: First Launch & Setup
1. Choose theme (Light/Dark)
2. Sign in with GitHub when prompted
3. Install recommended extensions
3. Follow same installation steps as Cursor above
4. Complete first-launch setup
5. Sign in with GitHub when prompted
---
@ -146,7 +107,7 @@ Follow the same installation steps as Cursor above.
### Open the Terminal
This is important for upcoming steps!
This is important for upcoming lessons!
**Windows / Linux:**
- Press **Ctrl + `** (backtick key, usually above Tab)
@ -172,7 +133,7 @@ This is important for upcoming steps!
**Solution:** View menu → Terminal → New Terminal
**Issue:** GitHub sign-in fails
**Solution:** You can skip for now, we'll handle it in Lesson 05
**Solution:** You can skip for now, we'll handle it later
---
@ -180,10 +141,9 @@ This is important for upcoming steps!
Your IDE is ready! Now let's understand Git and how your IDE handles it automatically.
**[Continue to Lesson 03: Git Setup →](../lesson-03-git-setup/tutorial.md)**
**[Continue to Lesson 03: Git Configuration →](../lesson-03-git-setup/tutorial.md)**
---
*Part of Module 02: Installation & Setup*
*[← Back to Module Overview](../module-02-overview.md)*

38
src/modules/wds/course/module-02-installation-setup/lesson-03-git-setup/tutorial.md
View File

@ -19,18 +19,13 @@
**Git** is the behind-the-scenes tool that syncs your computer with GitHub.
**Think of it as:**
- The sync engine between your computer and GitHub
- Like Dropbox, but smarter (tracks every change)
- Built into most modern IDEs
**Good news:** You don't need to install it manually!
**Good news:** You don't need to install it manually! Modern IDEs like Cursor handle this for you.
---
## Recap: Your Repository Structure
## Step 1: Recap Your Repository Structure
**You already decided this in Lesson 02 when naming your repo!**
**You already decided this in Lesson 01 when naming your repo!**
### Single Repo (named `my-project`)
```
@ -45,13 +40,17 @@ my-project-specs/ ← This repo (specifications only)
← Code repo created separately
```
**For this tutorial, we assume single repo** (`dog-walker-app`)
---
## Option 1: Let Cursor Handle It (Recommended)
## Step 2: Choose Your Git Approach
### Option 1: Let Cursor Handle It (Recommended)
**The easiest way:** Do nothing!
When you try to clone a repository in Lesson 05, Cursor will:
When you try to clone a repository in Lesson 04, Cursor will:
1. Check if Git is installed
2. If not, **automatically prompt you**: "Install Git?"
@ -64,11 +63,11 @@ When you try to clone a repository in Lesson 05, Cursor will:
---
## Option 2: GitHub Desktop (Visual Alternative)
### Option 2: GitHub Desktop (Visual Alternative)
**For designers who prefer visual tools:**
### Why GitHub Desktop?
#### Why GitHub Desktop?
- ✅ No terminal commands needed
- ✅ Visual interface for everything
@ -76,7 +75,7 @@ When you try to clone a repository in Lesson 05, Cursor will:
- ✅ Many professional designers use it
- ✅ Works perfectly with Cursor
### Install GitHub Desktop
#### Install GitHub Desktop
1. Download from **https://desktop.github.com**
2. Install it (follow standard installer)
@ -84,7 +83,7 @@ When you try to clone a repository in Lesson 05, Cursor will:
4. Sign in with your GitHub account
5. Done!
### How it Works
#### How it Works
- Use GitHub Desktop to **clone** repositories
- Use GitHub Desktop to **commit** and **push** changes
@ -93,9 +92,11 @@ When you try to clone a repository in Lesson 05, Cursor will:
**This is a perfectly valid professional workflow.**
**Bonus:** GitHub Desktop also helps you decide between single vs separate repos visually!
---
## Option 3: Already Comfortable with Terminal?
### Option 3: Already Comfortable with Terminal?
**Optional check for those who want to know:**
@ -112,7 +113,7 @@ git version 2.x.x
✅ Git is installed!
**If you see "command not found":**
No problem! Continue to Lesson 05, Cursor will prompt you.
No problem! Continue to Lesson 04, Cursor will prompt you.
---
@ -121,7 +122,7 @@ No problem! Continue to Lesson 05, Cursor will prompt you.
**Choose Option 1 (Let Cursor Handle It) if:**
- You're a complete beginner
- You want the simplest path
- You're comfortable with terminal appearing in Lesson 05
- You're comfortable with terminal appearing in Lesson 04
**Choose Option 2 (GitHub Desktop) if:**
- You prefer visual interfaces
@ -150,10 +151,9 @@ No problem! Continue to Lesson 05, Cursor will prompt you.
Git will be ready when you need it! Now it's time to clone your repository and add WDS to your workspace.
**[Continue to Lesson 04: Clone & Add WDS →](../lesson-04-clone-and-wds/tutorial.md)**
**[Continue to Lesson 04: Repository Cloning & WDS Integration →](../lesson-04-clone-and-wds/tutorial.md)**
---
*Part of Module 02: Installation & Setup*
*[← Back to Module Overview](../module-02-overview.md)*

15
src/modules/wds/course/module-02-installation-setup/lesson-04-clone-and-wds/tutorial.md
View File

@ -41,7 +41,9 @@ cd ~/Projects
## Step 2: Clone Your Project Repository
### Get Your Repository URL
**What is cloning?** Copying your GitHub repository to your computer so you can work on it.
### 2.1 Get Your Repository URL
1. Go to your repository on GitHub
2. Click the green **"Code"** button
@ -50,7 +52,7 @@ cd ~/Projects
**Your URL looks like:** `https://github.com/your-username/your-project.git`
### Clone the Repository
### 2.2 Clone the Repository
In Cursor terminal:
@ -82,6 +84,8 @@ git clone https://github.com/john-designer/dog-walker-app.git
## Step 4: Clone WDS Repository
**What is WDS?** The methodology files that contain agents, workflows, and training.
**WDS lives separately from your project.**
In Cursor terminal (make sure you're in Projects folder):
@ -114,6 +118,8 @@ git clone https://github.com/whiteport-collective/whiteport-design-studio.git
## Step 6: Create Docs Folder Structure
**What is the docs folder?** Where all your WDS specifications will live. This is your design source of truth.
**Navigate to YOUR project (not WDS):**
```bash
@ -192,7 +198,7 @@ Your Computer/
**Solution:** Make sure you're signed into GitHub in Cursor
**Issue:** "Can't find MIMIR file"
**Solution:** Make sure you added `whiteport-design-studio` folder to workspace
**Solution:** Make sure you added `whiteport-design-studio` folder to workspace (Step 5)
**Issue:** "mkdir: cannot create directory"
**Solution:** Make sure you're in your project folder: `cd ~/Projects/your-project`
@ -203,10 +209,9 @@ Your Computer/
Everything is set up! Now let's activate Mimir and begin your WDS journey.
**[Continue to Lesson 05: Initiate Mimir →](../lesson-05-initiate-mimir/tutorial.md)**
**[Continue to Lesson 05: Mimir Activation →](../lesson-05-initiate-mimir/tutorial.md)**
---
*Part of Module 02: Installation & Setup*
*[← Back to Module Overview](../module-02-overview.md)*

66
src/modules/wds/course/module-02-installation-setup/lesson-05-initiate-mimir/tutorial.md
View File

@ -61,6 +61,12 @@ In Cursor:
**You should see the file attached to your message!**
**Alternative method:**
Type in chat:
```
@MIMIR-WDS-ORCHESTRATOR.md
```
---
## Step 4: Send Your First Message
@ -130,34 +136,6 @@ If you're confused → Mimir will slow down
---
## Alternative: Type Instead of Drag
**If dragging doesn't work:**
In the AI chat, type:
```
@MIMIR-WDS-ORCHESTRATOR.md
Hello Mimir! I just completed the installation setup and I'm ready to start.
```
This references the file and sends your message.
---
## What Happens Next?
**After your conversation with Mimir, you'll either:**
1. **Start WDS Training** - If you want to learn methodology first
2. **Begin Project Brief** - If you're ready to dive into your project
3. **Meet Specialist Agents** - Freyja (UX), Saga (Analyst), or Idunn (PM)
**Mimir will guide you to the right path based on your situation.**
---
## Whenever You Need Help
**Remember this simple command:**
@ -179,7 +157,7 @@ This references the file and sends your message.
## Troubleshooting
**Issue:** Can't find MIMIR file
**Solution:** Make sure you added `whiteport-design-studio` to workspace (Lesson 05, Step 5)
**Solution:** Make sure you added `whiteport-design-studio` to workspace (Lesson 04, Step 5)
**Issue:** Drag doesn't work
**Solution:** Use `@MIMIR-WDS-ORCHESTRATOR.md` instead
@ -221,6 +199,35 @@ You've completed the entire Module 02: Installation & Setup!
---
## Pro Tips for Beginners
**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: Keep WDS Updated**
Once a month, update WDS to get new features:
```bash
cd ~/Projects/whiteport-design-studio
git pull
```
**Tip 3: When in Doubt, Ask Mimir**
```
@wds-mimir [your question]
```
No question is too small!
**Tip 4: Save Your Workspace**
In Cursor: **File** → **Save Workspace As** → `my-project.code-workspace`
Next time, just open this file!
---
## Remember
**Whenever in doubt:**
@ -235,4 +242,3 @@ You've completed the entire Module 02: Installation & Setup!
*Part of Module 02: Installation & Setup*
*[← Back to Module Overview](../module-02-overview.md)*