Installer updates
This commit is contained in:
Mårten Angner
parent
57d091e368
commit
1453c050ac
|
|
@ -0,0 +1,3 @@
|
|||
# Exclude internal material from npm package
|
||||
docs/learn-wds/course-explainers/
|
||||
docs/learn-wds/Webinars/
|
||||
14
CHANGELOG.md
14
CHANGELOG.md
|
|
@ -0,0 +1,14 @@
|
|||
# Changelog
|
||||
|
||||
## 0.1.0 (2026-01-29)
|
||||
|
||||
Initial public release on npm.
|
||||
|
||||
### Features
|
||||
- **npm installer** - `npx whiteport-design-studio install` sets up WDS in any project
|
||||
- **4 AI agents** - Mimir (Orchestrator), Saga (Analyst), Idunn (PM), Freya (Designer)
|
||||
- **17 IDE configurations** - Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, and more
|
||||
- **Agent compiler** - Compiles `.agent.yaml` definitions into ready-to-use `.md` files
|
||||
- **Project scaffolding** - Creates `docs/` folder structure (A-F) with `.gitkeep` files
|
||||
- **Learning material** - Optional inclusion of training courses, method guides, and tool references
|
||||
- **Update support** - Re-run the installer to update WDS files while preserving your `config.yaml`
|
||||
278
CONTRIBUTING.md
278
CONTRIBUTING.md
|
|
@ -1,268 +1,42 @@
|
|||
# Contributing to BMad
|
||||
# Contributing to Whiteport Design Studio
|
||||
|
||||
Thank you for considering contributing to the BMad project! We believe in **Human Amplification, Not Replacement** - bringing out the best thinking in both humans and AI through guided collaboration.
|
||||
Thank you for your interest in contributing to WDS.
|
||||
|
||||
💬 **Discord Community**: Join our [Discord server](https://discord.gg/gk8jAdXWmj) for real-time discussions:
|
||||
## Project Overview
|
||||
|
||||
- **#bmad-development** - Technical discussions and development questions
|
||||
- **#suggestions-feedback** - Feature ideas and suggestions
|
||||
- **#report-bugs-and-issues** - Bug reports and issue discussions
|
||||
Whiteport Design Studio (WDS) is a strategic design methodology that uses AI agents to guide product design, from initial strategy to developer-ready specifications.
|
||||
|
||||
## Our Philosophy
|
||||
The repository contains:
|
||||
- `src/` - Agent definitions, workflows, data, templates (the WDS module)
|
||||
- `docs/` - Learning material, method guides, tool guides
|
||||
- `tools/` - npm installer CLI
|
||||
|
||||
### BMad Core™: Universal Foundation
|
||||
## How to Contribute
|
||||
|
||||
BMad Core empowers humans and AI agents working together in true partnership across any domain through our **C.O.R.E. Framework** (Collaboration Optimized Reflection Engine):
|
||||
### Reporting Issues
|
||||
|
||||
- **Collaboration**: Human-AI partnership where both contribute unique strengths
|
||||
- **Optimized**: The collaborative process refined for maximum effectiveness
|
||||
- **Reflection**: Guided thinking that helps discover better solutions and insights
|
||||
- **Engine**: The powerful framework that orchestrates specialized agents and workflows
|
||||
Open an issue at [github.com/whiteport-collective/whiteport-design-studio/issues](https://github.com/whiteport-collective/whiteport-design-studio/issues).
|
||||
|
||||
### BMad Method™: Agile AI-Driven Development
|
||||
### Development
|
||||
|
||||
The BMad Method is the flagship bmad module for agile AI-driven software development. It emphasizes thorough planning and solid architectural foundations to provide detailed context for developer agents, mirroring real-world agile best practices.
|
||||
1. Fork and clone the repository
|
||||
2. Install dependencies: `npm install`
|
||||
3. Test the installer locally: `node tools/cli/wds-cli.js install`
|
||||
4. Make your changes
|
||||
5. Submit a pull request
|
||||
|
||||
### Core Principles
|
||||
### Areas of Interest
|
||||
|
||||
**Partnership Over Automation** - AI agents act as expert coaches, mentors, and collaborators who amplify human capability rather than replace it.
|
||||
- **Agent improvements** - Better prompts, new workflows, enhanced teaching
|
||||
- **IDE support** - New IDE configurations in `tools/cli/lib/ide-configs.js`
|
||||
- **Documentation** - Method guides, tutorials, examples
|
||||
- **Installer** - CLI improvements, new commands
|
||||
|
||||
**Bidirectional Guidance** - Agents guide users through structured workflows while users push agents with advanced prompting. Both sides actively work to extract better information from each other.
|
||||
## Code Style
|
||||
|
||||
**Systems of Workflows** - BMad Core builds comprehensive systems of guided workflows with specialized agent teams for any domain.
|
||||
|
||||
**Tool-Agnostic Foundation** - BMad Core remains tool-agnostic, providing stable, extensible groundwork that adapts to any domain.
|
||||
|
||||
## What Makes a Good Contribution?
|
||||
|
||||
Every contribution should strengthen human-AI collaboration. Ask yourself: **"Does this make humans and AI better together?"**
|
||||
|
||||
**✅ Contributions that align:**
|
||||
|
||||
- Enhance universal collaboration patterns
|
||||
- Improve agent personas and workflows
|
||||
- Strengthen planning and context continuity
|
||||
- Increase cross-domain accessibility
|
||||
- Add domain-specific modules leveraging BMad Core
|
||||
|
||||
**❌ What detracts from our mission:**
|
||||
|
||||
- Purely automated solutions that sideline humans
|
||||
- Tools that don't improve the partnership
|
||||
- Complexity that creates barriers to adoption
|
||||
- Features that fragment BMad Core's foundation
|
||||
|
||||
## Before You Contribute
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
1. **Check existing issues** first to avoid duplicates
|
||||
2. **Consider discussing in Discord** (#report-bugs-and-issues channel) for quick help
|
||||
3. **Use the bug report template** when creating a new issue - it guides you through providing:
|
||||
- Clear bug description
|
||||
- Steps to reproduce
|
||||
- Expected vs actual behavior
|
||||
- Model/IDE/BMad version details
|
||||
- Screenshots or links if applicable
|
||||
4. **Indicate if you're working on a fix** to avoid duplicate efforts
|
||||
|
||||
### Suggesting Features or New Modules
|
||||
|
||||
1. **Discuss first in Discord** (#suggestions-feedback channel) - the feature request template asks if you've done this
|
||||
2. **Check existing issues and discussions** to avoid duplicates
|
||||
3. **Use the feature request template** when creating an issue
|
||||
4. **Be specific** about why this feature would benefit the BMad community and strengthen human-AI collaboration
|
||||
|
||||
### Before Starting Work
|
||||
|
||||
⚠️ **Required before submitting PRs:**
|
||||
|
||||
1. **For bugs**: Check if an issue exists (create one using the bug template if not)
|
||||
2. **For features**: Discuss in Discord (#suggestions-feedback) AND create a feature request issue
|
||||
3. **For large changes**: Always open an issue first to discuss alignment
|
||||
|
||||
Please propose small, granular changes! For large or significant changes, discuss in Discord and open an issue first. This prevents wasted effort on PRs that may not align with planned changes.
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Which Branch?
|
||||
|
||||
**Submit PR's to `main` branch** (critical only):
|
||||
|
||||
- 🚨 Critical bug fixes that break basic functionality
|
||||
- 🔒 Security patches
|
||||
- 📚 Fixing dangerously incorrect documentation
|
||||
- 🐛 Bugs preventing installation or basic usage
|
||||
|
||||
### PR Size Guidelines
|
||||
|
||||
- **Ideal PR size**: 200-400 lines of code changes
|
||||
- **Maximum PR size**: 800 lines (excluding generated files)
|
||||
- **One feature/fix per PR**: Each PR should address a single issue or add one feature
|
||||
- **If your change is larger**: Break it into multiple smaller PRs that can be reviewed independently
|
||||
- **Related changes**: Even related changes should be separate PRs if they deliver independent value
|
||||
|
||||
### Breaking Down Large PRs
|
||||
|
||||
If your change exceeds 800 lines, use this checklist to split it:
|
||||
|
||||
- [ ] Can I separate the refactoring from the feature implementation?
|
||||
- [ ] Can I introduce the new API/interface in one PR and implementation in another?
|
||||
- [ ] Can I split by file or module?
|
||||
- [ ] Can I create a base PR with shared utilities first?
|
||||
- [ ] Can I separate test additions from implementation?
|
||||
- [ ] Even if changes are related, can they deliver value independently?
|
||||
- [ ] Can these changes be merged in any order without breaking things?
|
||||
|
||||
Example breakdown:
|
||||
|
||||
1. PR #1: Add utility functions and types (100 lines)
|
||||
2. PR #2: Refactor existing code to use utilities (200 lines)
|
||||
3. PR #3: Implement new feature using refactored code (300 lines)
|
||||
4. PR #4: Add comprehensive tests (200 lines)
|
||||
|
||||
**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value.
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
#### New to Pull Requests?
|
||||
|
||||
If you're new to GitHub or pull requests, here's a quick guide:
|
||||
|
||||
1. **Fork the repository** - Click the "Fork" button on GitHub to create your own copy
|
||||
2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/bmad-module-creative-intelligence-suite.git`
|
||||
3. **Create a new branch** - Never work on `main` directly!
|
||||
```bash
|
||||
git checkout -b fix/description
|
||||
# or
|
||||
git checkout -b feature/description
|
||||
```
|
||||
4. **Make your changes** - Edit files, keeping changes small and focused
|
||||
5. **Commit your changes** - Use clear, descriptive commit messages
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "fix: correct typo in README"
|
||||
```
|
||||
6. **Push to your fork** - `git push origin fix/description`
|
||||
7. **Create the Pull Request** - Go to your fork on GitHub and click "Compare & pull request"
|
||||
|
||||
### PR Description Template
|
||||
|
||||
Keep your PR description concise and focused. Use this template:
|
||||
|
||||
```markdown
|
||||
## What
|
||||
|
||||
[1-2 sentences describing WHAT changed]
|
||||
|
||||
## Why
|
||||
|
||||
[1-2 sentences explaining WHY this change is needed]
|
||||
Fixes #[issue number] (if applicable)
|
||||
|
||||
## How
|
||||
|
||||
## [2-3 bullets listing HOW you implemented it]
|
||||
|
||||
-
|
||||
-
|
||||
|
||||
## Testing
|
||||
|
||||
[1-2 sentences on how you tested this]
|
||||
```
|
||||
|
||||
**Maximum PR description length: 200 words** (excluding code examples if needed)
|
||||
|
||||
### Good vs Bad PR Descriptions
|
||||
|
||||
❌ **Bad Example:**
|
||||
|
||||
> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics...
|
||||
|
||||
✅ **Good Example:**
|
||||
|
||||
> **What:** Added validation for agent dependency resolution
|
||||
> **Why:** Build was failing silently when agents had circular dependencies
|
||||
> **How:**
|
||||
>
|
||||
> - Added cycle detection in dependency-resolver.js
|
||||
> - Throws clear error with dependency chain
|
||||
> **Testing:** Tested with circular deps between 3 agents
|
||||
|
||||
### Commit Message Convention
|
||||
|
||||
Use conventional commits format:
|
||||
|
||||
- `feat:` New feature
|
||||
- `fix:` Bug fix
|
||||
- `docs:` Documentation only
|
||||
- `refactor:` Code change that neither fixes a bug nor adds a feature
|
||||
- `test:` Adding missing tests
|
||||
- `chore:` Changes to build process or auxiliary tools
|
||||
|
||||
Keep commit messages under 72 characters.
|
||||
|
||||
### Atomic Commits
|
||||
|
||||
Each commit should represent one logical change:
|
||||
|
||||
- **Do:** One bug fix per commit
|
||||
- **Do:** One feature addition per commit
|
||||
- **Don't:** Mix refactoring with bug fixes
|
||||
- **Don't:** Combine unrelated changes
|
||||
|
||||
## What Makes a Good Pull Request?
|
||||
|
||||
✅ **Good PRs:**
|
||||
|
||||
- Change one thing at a time
|
||||
- Have clear, descriptive titles
|
||||
- Explain what and why in the description
|
||||
- Include only the files that need to change
|
||||
- Reference related issue numbers
|
||||
|
||||
❌ **Avoid:**
|
||||
|
||||
- Changing formatting of entire files
|
||||
- Multiple unrelated changes in one PR
|
||||
- Copying your entire project/repo into the PR
|
||||
- Changes without explanation
|
||||
- Working directly on `main` branch
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
1. **Don't reformat entire files** - only change what's necessary
|
||||
2. **Don't include unrelated changes** - stick to one fix/feature per PR
|
||||
3. **Don't paste code in issues** - create a proper PR instead
|
||||
4. **Don't submit your whole project** - contribute specific improvements
|
||||
|
||||
## Prompt & Agent Guidelines
|
||||
|
||||
- Keep dev agents lean - they need context for coding, not documentation
|
||||
- Web/planning agents can be larger with more complex tasks
|
||||
- Everything is natural language (markdown) - no code in core framework
|
||||
- Use bmad modules for domain-specific features
|
||||
- Validate YAML schemas with `npm run validate:schemas` before committing
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
By participating in this project, you agree to abide by our Code of Conduct. We foster a collaborative, respectful environment focused on building better human-AI partnerships.
|
||||
|
||||
## Need Help?
|
||||
|
||||
- 💬 Join our [Discord Community](https://discord.gg/gk8jAdXWmj):
|
||||
- **#bmad-development** - Technical questions and discussions
|
||||
- **#suggestions-feedback** - Feature ideas and suggestions
|
||||
- **#report-bugs-and-issues** - Get help with bugs before filing issues
|
||||
- 🐛 Report bugs using the [bug report template](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/issues/new?template=bug_report.md)
|
||||
- 💡 Suggest features using the [feature request template](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/issues/new?template=feature_request.md)
|
||||
- 📖 Browse the [GitHub Discussions](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/discussions)
|
||||
|
||||
---
|
||||
|
||||
**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner. Together, we're building a future where humans and AI work better together.
|
||||
- Use CommonJS (`require`/`module.exports`) for Node.js compatibility
|
||||
- Follow existing patterns in the codebase
|
||||
|
||||
## License
|
||||
|
||||
By contributing to this project, you agree that your contributions will be licensed under the same license as the project.
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
|
|
|
|||
327
README.md
327
README.md
|
|
@ -1,196 +1,183 @@
|
|||
# Whiteport Design Studio (WDS) 🎨
|
||||
# Whiteport Design Studio (WDS)
|
||||
|
||||
**Strategic design methodology for creating products users love**
|
||||
**Strategic design methodology for creating products users love, powered by AI agents.**
|
||||
|
||||
## What You Can Accomplish with WDS
|
||||
|
||||
As a designer using WDS, you'll be able to:
|
||||
|
||||
🎯 **Create strategic designs** - Connect every design decision to business goals and user psychology
|
||||
📋 **Produce complete specifications** - Generate developer-ready page specs with all details defined
|
||||
✨ **Explore with AI image generation** - Use NanoBanana/Eira to generate design concepts and establish visual identity
|
||||
🎨 **Design with Figma** - Open your prototype in Figma, refine the design, export it back to update the design system and generate new code
|
||||
🤖 **Leverage AI agents** - Work with Saga, Idunn, and Freya to accelerate your workflow
|
||||
📦 **Deliver with confidence** - Hand off complete, tested prototypes with clear documentation
|
||||
|
||||
### What You Need to Learn
|
||||
|
||||
To get the most out of WDS, you'll need to understand:
|
||||
|
||||
1. **The WDS workflow** - How phases connect and when to use each one
|
||||
2. **Agent collaboration** - Working with Saga, Idunn, and Freya to accomplish tasks
|
||||
3. **Tool integration** - Using Figma MCP, NanoBanana, and other design tools
|
||||
|
||||
<EFBFBD> **Start learning:** [docs/learn-wds/](docs/learn-wds/) - Interactive courses and tutorials
|
||||
[](https://www.npmjs.com/package/whiteport-design-studio)
|
||||
[](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## Module Structure
|
||||
## Installation
|
||||
|
||||
```
|
||||
wds/
|
||||
├── _module-installer/ # Installation configuration
|
||||
├── agents/ # WDS specialized agents (Norse Pantheon)
|
||||
│ ├── saga-analyst.agent.yaml # Saga-Analyst - Business & Product Analyst
|
||||
│ ├── idunn-pm.agent.yaml # Idunn-WDS-PM - Product Manager
|
||||
│ └── freya-ux.agent.yaml # Freya-WDS-Designer - UX/UI Designer
|
||||
├── workflows/ # Phase-selectable design workflows
|
||||
├── data/ # Standards, frameworks, presentations
|
||||
│ └── presentations/ # Agent introduction presentations
|
||||
├── docs/ # Module documentation
|
||||
│ ├── method/ # Methodology deep-dives
|
||||
│ └── images/ # Diagrams and visuals
|
||||
├── examples/ # Real-world usage examples
|
||||
│ └── dog-week-patterns/ # Patterns from Dog Week project
|
||||
├── reference/ # Templates and checklists
|
||||
│ ├── templates/ # Document templates
|
||||
│ └── checklists/ # Phase completion checklists
|
||||
├── teams/ # Team configurations
|
||||
└── README.md # This file (only README in module)
|
||||
```bash
|
||||
npx whiteport-design-studio install
|
||||
```
|
||||
|
||||
## 📁 Output Structure
|
||||
|
||||
WDS creates a clean, alphabetized folder structure in your project's `docs/` folder:
|
||||
|
||||
| Folder | Phase | Purpose | Timing |
|
||||
| ------------------ | ----- | -------------------------------------------- | ------------------- |
|
||||
| `A-Product-Brief/` | 1 | Strategic foundation & vision | Start here |
|
||||
| `B-Trigger-Map/` | 2 | User psychology & business goals | After Phase 1 |
|
||||
| `C-Scenarios/` | 4 | UX specifications (HOW it works) | After Phase 2 |
|
||||
| `D-Design-System/` | 5 | Visual identity & components (HOW it looks) | **Anytime** 🎨 |
|
||||
| `D-PRD/` | 3 | Technical requirements (optional) | Before development |
|
||||
| `E-UI-Roadmap/` | 6 | Development handoff | After Phase 4 |
|
||||
|
||||
## 🎯 Design Phases
|
||||
|
||||
### Core Workflow
|
||||
|
||||
**Phase 1: Product Exploration** → `A-Product-Brief/`
|
||||
Define vision, positioning, and success criteria
|
||||
|
||||
**Phase 2: User Research** → `B-Trigger-Map/`
|
||||
Connect business goals to user psychology and triggers
|
||||
|
||||
**Phase 4: UX Design** → `C-Scenarios/`
|
||||
**HOW it works** - Functionality, interactions, content structure
|
||||
|
||||
**Phase 5: Visual Design** → `D-Design-System/`
|
||||
**HOW it looks** - Tie UX to brand, create visual system
|
||||
⚡ **Can start anytime** - Brand identity is independent of product!
|
||||
|
||||
### Optional Phases
|
||||
|
||||
**Phase 3: Requirements** → `D-PRD/` (for technical products)
|
||||
**Phase 6: Dev Integration** → `E-UI-Roadmap/` (handoff to development)
|
||||
The installer will guide you through setup: project type, experience level, and IDE configuration. Everything gets installed into a `_wds/` folder in your project.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Key Concepts
|
||||
## What is WDS?
|
||||
|
||||
WDS is a structured design methodology that uses AI agents to guide you through product design, from initial strategy to developer-ready specifications.
|
||||
|
||||
- **Strategic foundation** - Connect every design decision to business goals and user psychology
|
||||
- **Complete specifications** - Generate developer-ready page specs with all details defined
|
||||
- **AI-powered workflow** - Four specialized agents guide you through each phase
|
||||
- **IDE-native** - Works inside your AI coding tool (Claude Code, Cursor, Windsurf, and 14 more)
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
WDS uses four specialized AI agents (the Norse Pantheon):
|
||||
|
||||
| Agent | Role | What they do |
|
||||
|-------|------|-------------|
|
||||
| **Mimir** (Orchestrator) | Coach & Guide | Greets you, assesses your level, guides you through the entire process. Start here. |
|
||||
| **Saga** (Analyst) | Business & Product Analyst | Product Brief (Phase 1) and Trigger Mapping (Phase 2) |
|
||||
| **Idunn** (Product Manager) | Platform Requirements | Platform architecture (Phase 3) and design deliveries (Phase 6) |
|
||||
| **Freya** (Designer) | UX/UI Designer | UX Design (Phase 4), Design System (Phase 5), and testing (Phases 7-8) |
|
||||
|
||||
### Activating an agent
|
||||
|
||||
Tell your AI IDE:
|
||||
|
||||
```
|
||||
Read and activate the agent in _wds/agents/mimir-orchestrator.md
|
||||
```
|
||||
|
||||
Mimir will greet you, assess your situation, and guide you to the right specialist.
|
||||
|
||||
---
|
||||
|
||||
## Design Phases
|
||||
|
||||
| Phase | Focus | Output folder |
|
||||
|-------|-------|--------------|
|
||||
| 1. Product Exploration | Vision, positioning, success criteria | `docs/A-Product-Brief/` |
|
||||
| 2. Trigger Mapping | User psychology, business goals | `docs/B-Trigger-Map/` |
|
||||
| 3. Platform Architecture | Technical requirements (optional) | `docs/C-Platform-Requirements/` |
|
||||
| 4. UX Design | Scenarios, interactions, content structure | `docs/C-Scenarios/` |
|
||||
| 5. Visual Design | Brand identity, design system, components | `docs/D-Design-System/` |
|
||||
| 6. Design Delivery | Developer handoff, PRD finalization | `docs/E-PRD/Design-Deliveries/` |
|
||||
|
||||
Agent dialogs and conversation logs are saved to `docs/F-Agent-Dialogs/`.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
After installation, your project will have:
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── _wds/ # WDS system files
|
||||
│ ├── agents/ # Compiled agent files (.md)
|
||||
│ ├── workflows/ # Phase workflows
|
||||
│ ├── data/ # Standards, frameworks, agent guides
|
||||
│ ├── gems/ # Reusable prompt components
|
||||
│ ├── templates/ # Document templates
|
||||
│ ├── config.yaml # Your project configuration
|
||||
│ └── module.yaml # Module definition
|
||||
├── _wds-learn/ # Learning material (optional, safe to delete)
|
||||
│ ├── getting-started/
|
||||
│ ├── learn-wds/
|
||||
│ ├── method/
|
||||
│ ├── models/
|
||||
│ └── tools/
|
||||
├── docs/ # Design output (created by agents)
|
||||
│ ├── A-Product-Brief/
|
||||
│ ├── B-Trigger-Map/
|
||||
│ ├── C-Platform-Requirements/
|
||||
│ ├── C-Scenarios/
|
||||
│ ├── D-Design-System/
|
||||
│ ├── E-PRD/Design-Deliveries/
|
||||
│ └── F-Agent-Dialogs/
|
||||
└── .claude/instructions.md # IDE configuration (varies by IDE)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Install WDS** in your project directory:
|
||||
```bash
|
||||
npx whiteport-design-studio install
|
||||
```
|
||||
|
||||
2. **Open your project** in your AI IDE (Claude Code, Cursor, Windsurf, etc.)
|
||||
|
||||
3. **Activate Mimir** - tell the AI:
|
||||
```
|
||||
Read and activate the agent in _wds/agents/mimir-orchestrator.md
|
||||
```
|
||||
|
||||
4. **Follow Mimir's guidance** - Mimir will greet you, assess your experience level, and walk you through project setup. When you're ready for specific work, Mimir connects you to the right specialist agent.
|
||||
|
||||
---
|
||||
|
||||
## Supported IDEs
|
||||
|
||||
WDS works with any AI-powered IDE or coding tool:
|
||||
|
||||
Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, Roo Code, Codex, Gemini, Qwen, Trae, Kiro CLI, Rovo Dev, Crush, Auggie, Antigravity, iFlow, OpenCode
|
||||
|
||||
The installer configures your selected IDE(s) automatically.
|
||||
|
||||
---
|
||||
|
||||
## Tools Integration
|
||||
|
||||
WDS integrates with design and prototyping tools:
|
||||
|
||||
- **Figma MCP** - Bidirectional sync between AI-generated designs and Figma
|
||||
- **html.to.design** - Import HTML prototypes into Figma
|
||||
- **NanoBanana/Eira** - AI-powered image generation for brand exploration
|
||||
- **Excalidraw** - Sketch analysis and wireframing
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### UX vs Visual Design
|
||||
|
||||
```
|
||||
Phase 4 (UX Design)
|
||||
├─ Defines HOW it works
|
||||
├─ Functionality & interactions
|
||||
├─ Content structure & hierarchy
|
||||
└─ Question: "What does this do?"
|
||||
Phase 4 (UX Design) defines **how it works** - functionality, interactions, content structure.
|
||||
Phase 5 (Visual Design) defines **how it looks** - brand expression, design tokens, component library.
|
||||
|
||||
Phase 5 (Visual Design)
|
||||
├─ Defines HOW it looks and feels
|
||||
├─ Brand expression & visual language
|
||||
├─ Design tokens & system
|
||||
└─ Question: "How does this feel like our brand?"
|
||||
```
|
||||
Visual design can start at any time - brand identity is independent of product strategy.
|
||||
|
||||
### Brand Independence
|
||||
### Adaptive Teaching
|
||||
|
||||
**Visual design is NOT tied to product timing!**
|
||||
|
||||
- ✅ Before product work (brand-first approach)
|
||||
- ✅ Parallel to strategy (simultaneous development)
|
||||
- ✅ After strategy (informed by insights)
|
||||
|
||||
**Output location:** `D-Design-System/01-Visual-Design/`
|
||||
|
||||
## Agents - The Norse Pantheon 🏔️
|
||||
|
||||
| Agent | File | Role | Norse Meaning |
|
||||
| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- |
|
||||
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
|
||||
| **Idunn the PM** | `idunn-pm.agent.yaml` | Product Manager | Goddess of renewal & youth |
|
||||
| **Freya the Designer** | `freya-ux.agent.yaml` | UX/UI Designer | Goddess of beauty, magic & strategy |
|
||||
|
||||
## 🛠️ Tools & Integration
|
||||
|
||||
### Visual Design Tools
|
||||
|
||||
- **Figma MCP** - Automated bidirectional sync with Object IDs
|
||||
- **NanoBanana/Eira** - AI-powered image generation for brand exploration
|
||||
- **html.to.design** - Import HTML prototypes into Figma
|
||||
|
||||
### Workflow Tools
|
||||
|
||||
- **Excalidraw** - Sketch analysis and wireframing
|
||||
- **Git** - Version control and collaboration
|
||||
- **Cursor/Windsurf** - AI-powered IDE integration
|
||||
|
||||
📖 **Full tools guide:** [docs/tools/wds-tools-guide.md](docs/tools/wds-tools-guide.md)
|
||||
Mimir adapts to your experience level:
|
||||
- **Beginner** - Detailed guidance, one step at a time
|
||||
- **Intermediate** - Balanced approach, builds on existing knowledge
|
||||
- **Expert** - Direct and efficient, respects your time
|
||||
|
||||
---
|
||||
|
||||
## 📋 Conventions
|
||||
## Learning Material
|
||||
|
||||
- **One README rule** - Only this README.md; all other docs use `xxx-guide.md` naming
|
||||
- **Alphabetized output** - A-B-C-D-E folder prefix for clean organization
|
||||
- **Design focus** - No development artifacts (handled by BMM)
|
||||
- **Phase-selectable** - Choose phases based on project needs
|
||||
- **Tool-agnostic** - Works with any design/development tools
|
||||
The installer can optionally include learning and reference material in `_wds-learn/`. This includes:
|
||||
|
||||
## 🚀 Getting Started
|
||||
- **Getting Started** - Quick onboarding guides
|
||||
- **Course modules** - Complete 12-module training course (Module 00-13)
|
||||
- **Method guides** - Deep-dive into each design phase
|
||||
- **Models** - Strategic frameworks (Golden Circle, Customer Awareness, etc.)
|
||||
- **Tool guides** - Integration guides for Figma, Git, and more
|
||||
|
||||
### 1. Sideload Agents (Manual Installation)
|
||||
|
||||
Since the installer isn't working, manually copy agents:
|
||||
|
||||
```bash
|
||||
# Copy agent files to your IDE's agent folder
|
||||
cp src/modules/wds/agents/*.yaml <your-ide-agent-folder>/
|
||||
```
|
||||
|
||||
### 2. Activate an Agent
|
||||
|
||||
In your IDE, activate one of the WDS agents:
|
||||
- **Saga** - Business & Product Analyst
|
||||
- **Idunn** - Product Manager
|
||||
- **Freya** - UX/UI Designer
|
||||
|
||||
### 3. Initialize Workflow
|
||||
|
||||
```
|
||||
*workflow-init
|
||||
```
|
||||
|
||||
The agent will guide you through project setup and phase selection.
|
||||
|
||||
📖 **Detailed setup guide:** [docs/how-to/installation/install-bmad.md](../../docs/how-to/installation/install-bmad.md)
|
||||
|
||||
## 🔗 Integration with BMM
|
||||
|
||||
WDS design artifacts feed directly into BMad Method (BMM) development workflows:
|
||||
|
||||
```
|
||||
WDS Design System → E-UI-Roadmap/ → BMM Architecture & Stories → Development
|
||||
```
|
||||
|
||||
**Handoff includes:**
|
||||
- Component specifications with Object IDs
|
||||
- Design tokens (colors, typography, spacing)
|
||||
- Interactive HTML prototypes
|
||||
- User flow documentation
|
||||
- Acceptance criteria
|
||||
You can safely delete `_wds-learn/` at any time without affecting the agents or workflows.
|
||||
|
||||
---
|
||||
|
||||
<sub>Part of the BMad ecosystem • Contributed by Whiteport Collective</sub>
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## License
|
||||
|
||||
MIT - see [LICENSE](LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
Built by [Whiteport Collective](https://github.com/whiteport-collective)
|
||||
|
|
|
|||
|
|
@ -1,261 +0,0 @@
|
|||
# Workflow Optimization Complete ✅
|
||||
|
||||
**Date:** 2026-01-22
|
||||
**Status:** All workflows now compliant with BMAD v6 standards
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Total Workflows Scanned:** 6
|
||||
**Workflows Optimized:** 3
|
||||
**Total Files Optimized:** 6
|
||||
**Total Lines Reduced:** 779 lines (28% reduction)
|
||||
|
||||
---
|
||||
|
||||
## Optimization Results by Workflow
|
||||
|
||||
### 1. ✅ Content Creation Workshop
|
||||
|
||||
**Location:** `src/workflows/shared/content-creation-workshop/steps-c/`
|
||||
|
||||
**Files Optimized:** 5 files
|
||||
|
||||
| File | Before | After | Reduction | Status |
|
||||
|------|--------|-------|-----------|--------|
|
||||
| step-00-define-purpose.md | 291 | 196 | -95 (-33%) | ✅ |
|
||||
| step-03-action-filter.md | 265 | 230 | -35 (-13%) | ✅ |
|
||||
| step-04-empowerment-frame.md | 322 | 248 | -74 (-23%) | ✅ |
|
||||
| step-05-structural-order.md | 341 | 227 | -114 (-33%) | ✅ |
|
||||
| step-06-generate-content.md | 430 | 247 | -183 (-43%) | ✅ |
|
||||
|
||||
**Total:** 2,020 → 1,519 lines (-501 lines, -25%)
|
||||
|
||||
**Substeps Created:** 9 files
|
||||
- Purpose examples, action filter example
|
||||
- Badass Users principles & example
|
||||
- Golden Circle guide & example
|
||||
- Generation instructions, example, template
|
||||
|
||||
---
|
||||
|
||||
### 2. ✅ Project Brief (Complete)
|
||||
|
||||
**Location:** `src/workflows/1-project-brief/project-brief/complete/steps-c/`
|
||||
|
||||
**Files Optimized:** 1 file
|
||||
|
||||
| File | Before | After | Reduction | Status |
|
||||
|------|--------|-------|-----------|--------|
|
||||
| step-11-tone-of-voice.md | 258 | 233 | -25 (-10%) | ✅ |
|
||||
|
||||
**Total:** 957 → 932 lines (-25 lines, -3%)
|
||||
|
||||
**Substeps Created:** 1 file
|
||||
- Tone of Voice example (SaaS onboarding tool)
|
||||
|
||||
---
|
||||
|
||||
### 3. ✅ Document Generation
|
||||
|
||||
**Location:** `src/workflows/2-trigger-mapping/document-generation/steps-c/`
|
||||
|
||||
**Files Optimized:** 2 files
|
||||
|
||||
| File | Before | After | Reduction | Status |
|
||||
|------|--------|-------|-----------|--------|
|
||||
| step-04-generate-key-insights.md | 258 | 88 | -170 (-66%) | ✅ |
|
||||
| step-05-quality-check.md | 251 | 68 | -183 (-73%) | ✅ |
|
||||
|
||||
**Total:** 1,066 → 713 lines (-353 lines, -33%)
|
||||
|
||||
**Substeps Created:** 2 files
|
||||
- Key Insights document structure guide
|
||||
- Complete quality verification checklist
|
||||
|
||||
---
|
||||
|
||||
## Already Compliant Workflows
|
||||
|
||||
### ✅ Alignment Signoff
|
||||
**Location:** `src/workflows/1-project-brief/alignment-signoff/steps-c/`
|
||||
**Largest File:** 159 lines
|
||||
**Status:** All files under 250 lines
|
||||
|
||||
### ✅ Mermaid Diagram
|
||||
**Location:** `src/workflows/2-trigger-mapping/mermaid-diagram/steps-c/`
|
||||
**Largest File:** 183 lines
|
||||
**Status:** All files under 250 lines
|
||||
|
||||
### ✅ Page Specification Quality
|
||||
**Location:** `src/workflows/4-ux-design/page-specification-quality/steps-v/`
|
||||
**Largest File:** 92 lines
|
||||
**Status:** All files under 250 lines
|
||||
|
||||
---
|
||||
|
||||
## Optimization Strategy Applied
|
||||
|
||||
### Primary Focus: One Task Per Step
|
||||
|
||||
**Key Principle:** "Let's make sure characters is not the benchmark. Let's instead focus on one task per step."
|
||||
|
||||
Every step file now has ONE clear, focused task:
|
||||
- Define purpose
|
||||
- Load context
|
||||
- Apply framework
|
||||
- Generate content
|
||||
- Verify quality
|
||||
|
||||
### Substep Extraction Pattern
|
||||
|
||||
Created **12 substep files** total across all workflows:
|
||||
|
||||
**Pattern:**
|
||||
1. Extract detailed examples (50-150 lines)
|
||||
2. Extract framework guides (100+ lines)
|
||||
3. Extract complete templates (40+ lines)
|
||||
4. Replace with condensed summary + reference link
|
||||
|
||||
**Reference Format:**
|
||||
```markdown
|
||||
**See:** [substeps/XX-descriptive-name.md](substeps/XX-descriptive-name.md)
|
||||
|
||||
Brief description of what the substep contains and why it's useful.
|
||||
```
|
||||
|
||||
### Quality Preserved
|
||||
|
||||
- ✅ All examples preserved (not deleted)
|
||||
- ✅ All frameworks accessible via references
|
||||
- ✅ Educational value maintained
|
||||
- ✅ Implementation guidance intact
|
||||
- ✅ One-task-per-step focus achieved
|
||||
|
||||
---
|
||||
|
||||
## BMAD v6 Compliance
|
||||
|
||||
### All Workflows Now Meet Standards
|
||||
|
||||
**250-Line Limit:** ✅ All step files under 250 lines
|
||||
**Micro-File Design:** ✅ Substeps enable just-in-time loading
|
||||
**Task Focus:** ✅ Each step has ONE clear task
|
||||
**Maintainability:** ✅ Easier to scan and understand
|
||||
|
||||
### Files by Size Range
|
||||
|
||||
**Under 100 lines:** 8 files
|
||||
**100-200 lines:** 9 files
|
||||
**200-250 lines:** 6 files
|
||||
**Over 250 lines:** 0 files ✅
|
||||
|
||||
---
|
||||
|
||||
## Impact Summary
|
||||
|
||||
**Before Optimization:**
|
||||
- 8 files over 250-line limit (up to 430 lines)
|
||||
- Examples inline bloating main files
|
||||
- Harder to scan and understand steps
|
||||
- Multiple tasks per step in some files
|
||||
|
||||
**After Optimization:**
|
||||
- 0 files over limit (largest: 248 lines)
|
||||
- Examples in dedicated substeps
|
||||
- Clear one-task-per-step structure
|
||||
- 28% reduction in main step files
|
||||
- Educational content fully preserved
|
||||
- 12 new substep reference files
|
||||
|
||||
---
|
||||
|
||||
## Breakdown by Reduction Size
|
||||
|
||||
**Major Reductions (150+ lines):**
|
||||
- step-06-generate-content.md: -183 lines
|
||||
- step-05-quality-check.md: -183 lines
|
||||
- step-04-generate-key-insights.md: -170 lines
|
||||
|
||||
**Moderate Reductions (50-150 lines):**
|
||||
- step-05-structural-order.md: -114 lines
|
||||
- step-00-define-purpose.md: -95 lines
|
||||
- step-04-empowerment-frame.md: -74 lines
|
||||
|
||||
**Minor Reductions (<50 lines):**
|
||||
- step-03-action-filter.md: -35 lines
|
||||
- step-11-tone-of-voice.md: -25 lines
|
||||
|
||||
---
|
||||
|
||||
## Methodology Success Factors
|
||||
|
||||
### What Worked Well
|
||||
|
||||
1. **Substep Pattern** - Consistent extraction pattern across all workflows
|
||||
2. **Reference Links** - Clear "See: substeps/XX-name.md" pattern
|
||||
3. **Context Preservation** - Brief descriptions explain what's in substeps
|
||||
4. **One-Task Focus** - Prioritizing task clarity over arbitrary line counts
|
||||
5. **Quality Maintenance** - Nothing deleted, everything accessible
|
||||
|
||||
### User Feedback Integration
|
||||
|
||||
**Initial Guidance:** "Let's make sure characters is not the benchmark. Let's instead focus on one task per step."
|
||||
|
||||
**Response:** Shifted from purely line-count reduction to ensuring:
|
||||
- Each step has ONE clear task
|
||||
- Line count became validation metric, not primary goal
|
||||
- Examples and frameworks moved to substeps for reference
|
||||
- Main files focus on the core task workflow
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
All workflows in the WDS BMAD Method expansion are now optimized and compliant with BMAD v6 standards.
|
||||
|
||||
**Current Status:**
|
||||
- ✅ 6 workflows validated
|
||||
- ✅ 3 workflows optimized
|
||||
- ✅ 0 workflows over limit
|
||||
- ✅ 12 substep files created
|
||||
- ✅ 779 lines optimized
|
||||
|
||||
**Ready for:**
|
||||
- Production use
|
||||
- Further workflow development
|
||||
- Additional quality validation
|
||||
- Integration testing
|
||||
|
||||
---
|
||||
|
||||
## Files Created
|
||||
|
||||
**Substep Files (12 total):**
|
||||
|
||||
**Content Creation Workshop (9):**
|
||||
1. `substeps/00-purpose-examples.md`
|
||||
2. `substeps/03-action-filter-example.md`
|
||||
3. `substeps/04-badass-users-principles.md`
|
||||
4. `substeps/04-example-empowerment-frame.md`
|
||||
5. `substeps/05-golden-circle-guide.md`
|
||||
6. `substeps/05-example-golden-circle.md`
|
||||
7. `substeps/06-generation-instructions.md`
|
||||
8. `substeps/06-example-hairdresser-newsletter.md`
|
||||
9. `substeps/06-content-output-template.md`
|
||||
|
||||
**Project Brief Complete (1):**
|
||||
1. `substeps/11-tone-of-voice-example.md`
|
||||
|
||||
**Document Generation (2):**
|
||||
1. `substeps/04-key-insights-structure.md`
|
||||
2. `substeps/05-quality-checklist.md`
|
||||
|
||||
**Documentation:**
|
||||
- `OPTIMIZATION-COMPLETE.md` (in content-creation-workshop)
|
||||
- `WORKFLOW-OPTIMIZATION-COMPLETE.md` (this file)
|
||||
|
||||
---
|
||||
|
||||
**Optimization completed successfully. All WDS BMAD Method workflows now meet v6 standards while maintaining educational quality and one-task-per-step focus.** 🎉
|
||||
|
|
@ -130,8 +130,8 @@ class Installer {
|
|||
if (config.include_learning) {
|
||||
const learnSpinner = ora('Copying learning & reference material...').start();
|
||||
try {
|
||||
await this.copyLearningMaterial(wdsDir);
|
||||
learnSpinner.succeed('Learning & reference material added');
|
||||
await this.copyLearningMaterial(projectDir);
|
||||
learnSpinner.succeed('Learning material added to _wds-learn/ (safe to remove when no longer needed)');
|
||||
} catch (err) {
|
||||
learnSpinner.fail('Failed to copy learning material');
|
||||
throw err;
|
||||
|
|
@ -205,15 +205,17 @@ class Installer {
|
|||
}
|
||||
|
||||
/**
|
||||
* Copy learning & reference material into the WDS directory
|
||||
* Copy learning & reference material into _wds-learn/ at project root.
|
||||
* Users can safely delete this folder without affecting agents or workflows.
|
||||
*/
|
||||
async copyLearningMaterial(wdsDir) {
|
||||
async copyLearningMaterial(projectDir) {
|
||||
const learnDir = path.join(projectDir, '_wds-learn');
|
||||
const learningDirs = ['getting-started', 'learn-wds', 'method', 'models', 'tools'];
|
||||
const excludeDirs = ['course-explainers', 'Webinars'];
|
||||
|
||||
for (const dir of learningDirs) {
|
||||
const src = path.join(this.docsDir, dir);
|
||||
const dest = path.join(wdsDir, dir);
|
||||
const dest = path.join(learnDir, dir);
|
||||
if (await fs.pathExists(src)) {
|
||||
await fs.copy(src, dest, {
|
||||
filter: (srcPath) => {
|
||||
|
|
|
|||
|
|
@ -81,7 +81,7 @@ class UI {
|
|||
{
|
||||
type: 'confirm',
|
||||
name: 'include_learning',
|
||||
message: 'Include learning & reference material in _wds/?',
|
||||
message: 'Include learning & reference material in _wds-learn/?',
|
||||
default: true,
|
||||
},
|
||||
{
|
||||
|
|
@ -108,18 +108,19 @@ class UI {
|
|||
console.log('');
|
||||
console.log(chalk.green.bold(' Installation complete!'));
|
||||
console.log('');
|
||||
console.log(chalk.white(' Next steps:'));
|
||||
console.log(chalk.white(' Getting started:'));
|
||||
console.log(chalk.dim(` 1. Open your project in your AI IDE`));
|
||||
console.log(chalk.dim(` 2. Ask the AI to activate an agent from ${chalk.cyan(wdsFolder + '/agents/')}:`));
|
||||
console.log(chalk.dim(` 2. Tell the AI:`));
|
||||
console.log(chalk.cyan(` "Read and activate the agent in ${wdsFolder}/agents/mimir-orchestrator.md"`));
|
||||
console.log(chalk.dim(` 3. Mimir will greet you and guide you through project setup`));
|
||||
console.log('');
|
||||
console.log(chalk.white(` Agents installed in ${chalk.cyan(wdsFolder + '/agents/')}:`));
|
||||
console.log(chalk.dim(` - Mimir (Orchestrator) - Start here if you're new`));
|
||||
console.log(chalk.white(` Agents in ${chalk.cyan(wdsFolder + '/agents/')}:`));
|
||||
console.log(chalk.dim(` - Mimir (Orchestrator) - Your guide. Start here.`));
|
||||
console.log(chalk.dim(` - Saga (Analyst) - Product Brief & Trigger Mapping`));
|
||||
console.log(chalk.dim(` - Idunn (PM) - Platform Requirements & Deliveries`));
|
||||
console.log(chalk.dim(` - Freya (Designer) - UX Design & Testing`));
|
||||
console.log('');
|
||||
console.log(chalk.dim(' Learn more: https://github.com/whiteport-collective/whiteport-design-studio'));
|
||||
console.log(chalk.dim(' https://github.com/whiteport-collective/whiteport-design-studio'));
|
||||
console.log('');
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue