From 8f52d40da5dcdfc077bf274a25c11f16f2fe8b0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Angner?= Date: Sat, 7 Feb 2026 07:42:51 +0100 Subject: [PATCH] Add Phase 0: Project Setup workflow - New entry point that asks Greenfield vs Brownfield upfront - Prevents users from going through Phase 1-3 with existing codebases - Adds project configuration questions - Updates routing to direct brownfield projects to Phase 8 Synced from bmad-method-wds-expansion. Co-Authored-By: Claude Opus 4.5 --- .../0-project-setup/steps/step-0.1-welcome.md | 213 ++++++++++++++++ .../steps/step-0.2-structure.md | 236 ++++++++++++++++++ src/workflows/0-project-setup/workflow.md | 98 ++++++++ .../analysis-types/new-project-response.md | 45 +++- .../project-analysis/instructions.md | 59 ++++- 5 files changed, 633 insertions(+), 18 deletions(-) create mode 100644 src/workflows/0-project-setup/steps/step-0.1-welcome.md create mode 100644 src/workflows/0-project-setup/steps/step-0.2-structure.md create mode 100644 src/workflows/0-project-setup/workflow.md diff --git a/src/workflows/0-project-setup/steps/step-0.1-welcome.md b/src/workflows/0-project-setup/steps/step-0.1-welcome.md new file mode 100644 index 000000000..771031134 --- /dev/null +++ b/src/workflows/0-project-setup/steps/step-0.1-welcome.md @@ -0,0 +1,213 @@ +# Step 0.1: Welcome & Orientation + +## PRESENT WDS INTRODUCTION + + +**Welcome to Whiteport Design Studio (WDS)** + +WDS is a **design methodology** that helps you create great digital products through structured workflows. + +--- + +### What WDS Does + +**For NEW products** (Greenfield): +- Phase 1: Define your vision (Project Brief) +- Phase 2: Understand your users (Trigger Mapping) +- Phase 3: Specify features (PRD Platform) +- Phase 4: Design the experience (UX Design) +- Phase 5: Build consistency (Design System) +- Phase 6: Hand off to developers (Design Deliveries) +- Phase 7: Validate quality (Testing) + +**For EXISTING products** (Brownfield): +- Phase 8: Strategic improvements (Kaizen approach) +- Limited Brief (document what exists) +- Focused improvements (not complete redesigns) +- Continuous iteration cycles + +--- + +### What WDS is NOT + +- Not a code framework +- Not a UI library +- Not a one-size-fits-all template + +WDS is a **thinking framework** with templates to guide your design decisions. + +--- + +### The Agents + +Three specialized agents help you: + +| Agent | Domain | Specialty | +|-------|--------|-----------| +| **Saga** | Strategy | Project Briefs, user research, requirements | +| **Freya** | Design | UX/UI, wireframes, specifications, prototypes | +| **Idunn** | Technical | Architecture, APIs, implementation specs | + +You're currently working with one of these agents. + + +--- + +## ASK PROJECT TYPE + + +**What type of project is this?** + +Understanding your starting point ensures you follow the right workflow. + +--- + +**[A] NEW Product (Greenfield)** + +You're building something from scratch: +- No existing codebase (or starting fresh) +- Defining the product vision +- Designing before coding + +→ *Leads to Phase 1: Project Brief* + +--- + +**[B] EXISTING Product (Brownfield)** + +You're improving something that exists: +- Working codebase already built +- Want to add features or fix issues +- Improving, not rebuilding + +→ *Leads to Phase 8: Existing Product Entry* + +--- + +**[C] NOT SURE** + +You have some code but unsure of the approach: +- Partial implementation exists +- Unclear if you should continue or restart +- Need help deciding + +→ *We'll analyze your project together* + +--- + +**Your choice (A, B, or C):** + + +--- + +## ROUTING + + +Based on user response: + +**If [A] NEW Product:** +1. Confirm: "Great! You'll follow Phases 1-7 to build your product." +2. Continue to: `step-0.2-structure.md` (setup greenfield structure) +3. Then route to: Phase 1 Project Brief + +**If [B] EXISTING Product:** +1. Confirm: "Perfect! You'll use Phase 8 with the Kaizen approach." +2. Continue to: `step-0.2-structure.md` (setup brownfield structure) +3. Then route to: Phase 8.1 Identify Opportunity + +**If [C] NOT SURE:** +1. Ask: "Let me scan your project to understand what exists." +2. Scan for: + - `src/` or `app/` folders with code + - `package.json` with dependencies + - Existing documentation +3. Based on scan: + - Significant code exists → Recommend [B] Brownfield + - Minimal/no code → Recommend [A] Greenfield + - Ask user to confirm recommendation + + +--- + +## EXAMPLES + +### Example: User chooses [A] NEW + +``` +User: A + +Agent: Great! You're building a new product from scratch. + +You'll follow the Greenfield workflow: +├─ Phase 1: Project Brief (define vision) +├─ Phase 2: Trigger Mapping (understand users) +├─ Phase 3: PRD Platform (specify features) +├─ Phase 4: UX Design (design experience) +├─ Phase 5: Design System (build consistency) +├─ Phase 6: Design Deliveries (hand off) +└─ Phase 7: Testing (validate quality) + +Let's set up your project structure first... +``` + +### Example: User chooses [B] EXISTING + +``` +User: B + +Agent: Perfect! You're improving an existing product. + +You'll use the Brownfield workflow (Phase 8): +├─ Create Limited Brief (document what exists) +├─ Identify improvement opportunities +├─ Design focused updates (not complete redesigns) +├─ Implement incrementally (Kaizen approach) +└─ Monitor and iterate + +This approach respects your existing codebase while +making strategic improvements. + +Let's set up your project structure... +``` + +### Example: User chooses [C] NOT SURE + +``` +User: C + +Agent: No problem! Let me scan your project... + +Scanning... +├─ Found: src/ with 45 component files +├─ Found: package.json (React, TypeScript) +├─ Found: Functional authentication flow +├─ Found: Database integration (Supabase) +└─ No WDS documentation found + +Analysis: You have a substantial existing codebase. + +Recommendation: Use the BROWNFIELD workflow (Phase 8) +- Document what exists with a Limited Brief +- Identify specific improvements to make +- Use Kaizen approach for incremental changes + +This preserves your work while adding WDS methodology. + +Does this recommendation sound right? (Y/N) +``` + +--- + +## COMPLETION + + +Project type confirmed: [Greenfield/Brownfield] + +Next: Set up your project structure. + +[Continue to Step 0.2: Project Structure] + + +--- + +_Phase 0: Project Setup — Step 0.1: Welcome & Orientation_ diff --git a/src/workflows/0-project-setup/steps/step-0.2-structure.md b/src/workflows/0-project-setup/steps/step-0.2-structure.md new file mode 100644 index 000000000..6c79299ab --- /dev/null +++ b/src/workflows/0-project-setup/steps/step-0.2-structure.md @@ -0,0 +1,236 @@ +# Step 0.2: Project Configuration & Structure + +## CONTEXT + +Project type is confirmed (Greenfield or Brownfield). Now we configure the project and create the folder structure. + +--- + +## 1. PROJECT NAME + + +**What's your project name?** + +Project name: + + +--- + +## 2. WHAT ARE YOU BUILDING? + + +**What type of product is this?** + +[A] **Landing Page** - Single page, marketing focused + → Simplified workflow, minimal phases + +[B] **Website** - Multiple pages, content focused + → Standard workflow, most phases + +[C] **Web Application** - Complex features, user interactions + → Full workflow, all phases + +[D] **Mobile App** - iOS/Android application + → Full workflow + platform considerations + +Choice: + + + +Store as `product_complexity`: +- A → simple (skip Phase 2, 3, 5) +- B → standard (optional Phase 5) +- C → complex (all phases) +- D → complex (all phases + mobile config) + + +--- + +## 3. TECH STACK (Optional) + + +**Do you know your tech stack?** (Skip if undecided) + +[A] **React / Next.js** - Modern React ecosystem +[B] **Vue / Nuxt** - Vue.js ecosystem +[C] **WordPress** - CMS-based +[D] **Static HTML** - Simple HTML/CSS/JS +[E] **Other** - Different framework +[F] **Skip** - Decide later + +Choice: + + +Store as `tech_stack` (or null if skipped) + +--- + +## 4. COMPONENT LIBRARY (Optional) + + +**Using a component library?** (Skip if not applicable) + +[A] **shadcn/ui** - Tailwind-based components + → Skip Phase 5 (Design System) + +[B] **Tailwind only** - Utility CSS, custom components + → Phase 5 optional + +[C] **Material UI** - Google's design system + → Skip Phase 5 + +[D] **Custom** - Building your own + → Phase 5 recommended + +[E] **None / Skip** - Decide later + +Choice: + + + +Store as `component_library` +If A, C → set `skip_design_system: true` + + +--- + +## 5. BRIEF LEVEL (Greenfield only) + + +**How thorough should the Project Brief be?** + +[A] **Complete** (Recommended) + - 14 steps, ~2-3 hours + - Vision, positioning, business model, users, success criteria + - Best for: Complex products, teams, investor pitches + +[B] **Simplified** + - 5 steps, ~30 minutes + - Core vision, basic constraints, quick start + - Best for: Personal projects, prototypes, clear vision + +Choice: + + +Store as `brief_level`: complete | simplified + +--- + +## 6. CREATE STRUCTURE + + +**Check for existing structure first:** +- Look for `docs/` folder +- Look for `.wds-project-outline.yaml` + +**If exists:** Ask to keep or reset + + +### Greenfield Structure + +``` +docs/ +├── .wds-project-outline.yaml +├── 1-project-brief/ +├── 2-trigger-map/ # Skip if simple +├── 3-prd/ # Skip if simple +├── 4-ux-design/ +├── 5-design-system/ # Skip if using library +├── 6-deliveries/ +└── 7-testing/ +``` + +### Brownfield Structure + +``` +docs/ +├── .wds-project-outline.yaml +├── A-project-brief/ +│ └── limited-brief.md +├── improvements/ +└── deliveries/ +``` + +--- + +## 7. GENERATE PROJECT OUTLINE + + +**Create `.wds-project-outline.yaml` with all config:** + +```yaml +# WDS Project Outline +# Generated: {{date}} + +project: + name: "{{project_name}}" + type: {{greenfield|brownfield}} + created: {{date}} + +config: + product_complexity: {{simple|standard|complex}} + tech_stack: {{tech_stack|null}} + component_library: {{component_library|null}} + brief_level: {{complete|simplified}} # Greenfield only + skip_design_system: {{true|false}} + +phases: + # Phases configured based on complexity and config + {{generated_phases}} + +notes: | + Configuration captured during Phase 0 setup. + Phases marked 'skip' will not appear in workflow. +``` + + +--- + +## 8. SUMMARY & NEXT STEPS + + +**Project configured!** + +| Setting | Value | +|---------|-------| +| Name | {{project_name}} | +| Type | {{greenfield/brownfield}} | +| Complexity | {{product_complexity}} | +| Tech Stack | {{tech_stack or "Not set"}} | +| Brief Level | {{brief_level}} | + +**Phases:** {{enabled_phases}} enabled, {{skipped_phases}} skipped + +--- + +**[GREENFIELD]** Ready for Phase 1: Project Brief +- {{brief_level}} mode ({{brief_level == "complete" ? "14 steps" : "5 steps"}}) + +[A] Start Phase 1 now +[B] Hand off to Saga (specialist) + +**[BROWNFIELD]** Ready for Phase 8: Existing Product + +[A] Create Limited Brief now +[B] Scan my codebase first +[C] I know what to improve - go + + +--- + +## ROUTING + + +**Greenfield:** +- [A] → Phase 1 workflow (brief_level determines which) +- [B] → Hand off to Saga + +**Brownfield:** +- [A] → Load Limited Brief template +- [B] → Scan codebase, then brief +- [C] → Phase 8.1 Identify Opportunity + + +--- + +_Phase 0: Project Setup — Step 0.2: Configuration & Structure_ diff --git a/src/workflows/0-project-setup/workflow.md b/src/workflows/0-project-setup/workflow.md new file mode 100644 index 000000000..de35fef1d --- /dev/null +++ b/src/workflows/0-project-setup/workflow.md @@ -0,0 +1,98 @@ +# Phase 0: Project Setup + +**The starting point for every WDS project.** + +--- + +## Purpose + +Phase 0 ensures you start on the right path. Before diving into design work, we need to understand: + +1. **What is WDS?** - So you know what you're getting +2. **What type of project?** - New product vs existing product +3. **How complex?** - Landing page vs web application +4. **What tech?** - Framework and component library choices +5. **What's the right workflow?** - Route to the correct phase with right config + +--- + +## Why This Matters + +**The #1 mistake**: Starting Phase 1 with an existing codebase. + +- **Phase 1-7** = Building something NEW (Greenfield) +- **Phase 8** = Improving something EXISTING (Brownfield) + +Wrong path = wasted work. Phase 0 prevents this. + +--- + +## The Flow + +``` +Phase 0: Project Setup + │ + ├─→ Step 0.1: Welcome + │ ├─→ "What is WDS?" (quick intro) + │ └─→ "Greenfield or Brownfield?" + │ + └─→ Step 0.2: Configuration + ├─→ Project name + ├─→ Product complexity (landing/website/app) + ├─→ Tech stack (optional) + ├─→ Component library (optional) + ├─→ Brief level (complete/simplified) + ├─→ Create folder structure + └─→ Generate project outline + │ + ├─→ Greenfield → Phase 1 + └─→ Brownfield → Phase 8 +``` + +--- + +## Steps + +| Step | Name | Purpose | +|------|------|---------| +| 0.1 | [Welcome & Orientation](steps/step-0.1-welcome.md) | Introduce WDS, determine greenfield vs brownfield | +| 0.2 | [Configuration & Structure](steps/step-0.2-structure.md) | Configure project, create folders, generate outline | + +--- + +## Entry Point + +**Start here**: `steps/step-0.1-welcome.md` + +--- + +## When to Use Phase 0 + +- First time using WDS +- Starting a new project +- Joining an existing project +- Unsure which workflow to use + +--- + +## When to Skip Phase 0 + +- Project outline already exists (`.wds-project-outline.yaml`) +- You know exactly which phase you need +- Continuing work on established WDS project + +--- + +**Phase 0 takes 3-5 minutes. It saves hours of wrong-path work.** + +--- + +## Configuration Options + +| Option | Values | Impact | +|--------|--------|--------| +| Project Type | greenfield / brownfield | Determines Phase 1-7 vs Phase 8 | +| Complexity | simple / standard / complex | Which phases are enabled | +| Tech Stack | react / vue / wordpress / etc. | Delivery format guidance | +| Component Library | shadcn / tailwind / custom | Skip or enable Phase 5 | +| Brief Level | complete / simplified | Depth of Phase 1 | diff --git a/src/workflows/project-analysis/analysis-types/new-project-response.md b/src/workflows/project-analysis/analysis-types/new-project-response.md index 955cb6dc4..7b8ca5014 100644 --- a/src/workflows/project-analysis/analysis-types/new-project-response.md +++ b/src/workflows/project-analysis/analysis-types/new-project-response.md @@ -88,30 +88,49 @@ Would you like me to hand over to Saga to get started? --- [SCENARIO B - Code Without Docs]: -Project Status: Active development, no WDS documentation +Project Status: BROWNFIELD - Existing product, no WDS documentation ├─ Implementation: [X] files in [app/src/] directory ├─ Tech Stack: [List detected technologies] -└─ Status: Reverse-document needed +└─ Status: Ready for Phase 8 entry Implementation found: ├─ [Feature/file 1] ├─ [Feature/file 2] └─ [Feature/file 3] -💡 Observation: -This project has active development but hasn't adopted WDS methodology yet. +⚠️ IMPORTANT: This is a BROWNFIELD project! -Recommended Next Steps: -1. Create docs/ folder structure -2. Reverse-engineer Product Brief from existing code -3. Document implemented features as scenarios -4. Create project outline to track status +You have existing code. DO NOT start with Phase 1-3. +Those phases are for NEW products (greenfield). -**Saga WDS Analyst Agent** can help reverse-document your project. -Would you like me to hand over to Saga? +✅ Recommended Path: **Phase 8 - Existing Product Entry** -Alternatively, I can help you: -[Suggest domain-specific tasks] +Phase 8 uses the Kaizen (改善) approach: +├─ Create Limited Brief (document what exists) +├─ Identify specific improvements +├─ Design focused updates (not complete redesigns) +├─ Implement incrementally +└─ Monitor and iterate + +Next Steps: +1. Create docs/ folder with brownfield structure +2. Create Limited Brief (what exists + what you want to change) +3. Identify your first improvement opportunity +4. Begin Phase 8.1 + +**Options:** + +[A] Set up brownfield structure now + → Creates docs/ with Phase 8 templates + → Guides you through Limited Brief + +[B] Tell me what you want to improve + → Skip straight to improvement design + → I'll help document as we go + +[C] Hand off to Saga for Limited Brief + → Saga specializes in strategic documentation + → Will reverse-engineer your product brief --- diff --git a/src/workflows/project-analysis/instructions.md b/src/workflows/project-analysis/instructions.md index 7e808ce5d..c6ee758f8 100644 --- a/src/workflows/project-analysis/instructions.md +++ b/src/workflows/project-analysis/instructions.md @@ -6,7 +6,21 @@ ## What to Do -### Step 1: Show Your Presentation +### Step 1: Check for Project Outline + +**Look for**: `docs/.wds-project-outline.yaml` OR `.wds-project-outline.yaml` + +**If FOUND** → Fast path: +- Read outline for project type and status +- Route to `project-analysis-router.md` +- Skip Phase 0 (already set up) + +**If NOT FOUND** → New project: +- Continue to Step 2 + +--- + +### Step 2: Show Your Presentation Present your complete agent introduction: @@ -18,13 +32,48 @@ Present your complete agent introduction: --- -## What Happens Next +### Step 3: Route to Phase 0 -Your presentation file will automatically direct you to the project analysis router. +**After presentation, go to Phase 0: Project Setup** + +Route to: `../0-project-setup/steps/step-0.1-welcome.md` + +**Why Phase 0 first?** +- Introduces WDS to new users +- Asks the critical question: Greenfield vs Brownfield? +- Prevents wrong-path work (existing code going through Phase 1-3) +- Sets up proper project structure + +--- + +## Flow Summary + +``` +New User Arrives + │ + ├─→ Check for project outline + │ │ + │ ├─→ FOUND → project-analysis-router.md (fast path) + │ │ + │ └─→ NOT FOUND + │ │ + │ ├─→ Show agent presentation + │ │ + │ └─→ Phase 0: Project Setup + │ │ + │ ├─→ WDS Introduction + │ ├─→ Project Type Question + │ ├─→ Create Structure + │ │ + │ └─→ Route to correct phase + │ │ + │ ├─→ Greenfield → Phase 1 + │ └─→ Brownfield → Phase 8 +``` --- ## Alternative: If You Can't Find Presentation -If the presentation file is missing, continue to: -`project-analysis-router.md` +If the presentation file is missing, go directly to: +`../0-project-setup/steps/step-0.1-welcome.md`