From 2819a58fe63b5bca1aa89af36b1d4e12720c3d3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Angner?= Date: Fri, 20 Mar 2026 10:05:27 +0100 Subject: [PATCH] docs: update README for v0.4.0 Added: Design Space, build specifications, material analysis, BMad skill conversion, project structure with design-space module. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 110 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 71 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index f022020ec..411e57ede 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ npx whiteport-design-studio install [![npm version](https://img.shields.io/npm/v/whiteport-design-studio.svg)](https://www.npmjs.com/package/whiteport-design-studio) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +**v0.4.0** — BMad Skills + Design Space + Build Specifications --- @@ -15,21 +16,50 @@ npx whiteport-design-studio install 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** - Two specialized agents guide you through each phase -- **IDE-native** - Works inside your AI coding tool (Claude Code, Cursor, Windsurf, and 16 more) +- **Strategic foundation** — Connect every design decision to business goals and user psychology +- **Build specifications** — From Product Brief to complete database schema, state machines, API surface, and business logic +- **Shared agent memory** — Design Space: semantic knowledge base where agents search, capture, and communicate across sessions +- **Self-contained skills** — BMad-compliant agents with progressive disclosure, portable across any IDE +- **IDE-native** — Works inside your AI coding tool (Claude Code, Cursor, Windsurf, and 16 more) --- -## Agents +## What's New in v0.4.0 -WDS uses two specialized AI agents (the Norse Pantheon): +**BMad Skill Conversion** — Saga and Freya are now self-contained BMad skills with progressive disclosure, capability menus, and bundled references. No more routing through separate workflow files. -| Agent | Role | What they do | +**Design Space** — Shared knowledge base and agent messaging system, now a core WDS skill. Database-agnostic: SQLite for local solo work, Supabase for team collaboration. Same API, same agents, different backend. The installer handles setup. + +**Material Analysis Phase** — When users provide existing documents (PRD, brief, research), Saga analyzes them before asking questions. Extract, present for confirmation, identify gaps, only ask about what's missing. A 60-minute session becomes 15 minutes. + +**Platform Requirements → Build Specification** — The Platform Requirements step now produces a complete build specification: database schema (every table, column, type), state machines (every entity lifecycle), business logic (pseudocode, not prose), and API surface (every endpoint). Litmus test: *Can a coding agent build the entire platform from this document alone?* + +--- + +## Skills + +WDS ships three self-contained skills: + +``` +src/skills/ +├── saga/ # Strategic analyst — Product Brief + Trigger Map +│ ├── SKILL.md +│ ├── bmad-manifest.json +│ └── references/ +├── freya/ # UX designer — Scenarios + Design Loop +│ ├── SKILL.md +│ ├── bmad-manifest.json +│ └── references/ +└── design-space/ # Knowledge base + agent messaging + work orders + ├── SKILL.md + └── bmad-manifest.json +``` + +| Skill | Role | What they do | |-------|------|-------------| -| **Saga** (Analyst) | Business & Product Analyst | Product Brief (Phase 1), Trigger Mapping (Phase 2). Start here. | -| **Freya** (Designer) | UX/UI Designer & Developer | UX Scenarios (Phase 3), UX Design (Phase 4), Agentic Development (Phase 5), Asset Generation (Phase 6), Design System (Phase 7), Product Evolution (Phase 8) | +| **Saga** | Business & Product Analyst | Product Brief (Phase 1), Trigger Mapping (Phase 2). Start here. | +| **Freya** | UX/UI Designer | UX Scenarios (Phase 3), UX Design (Phase 4), Asset Generation, Design System | +| **Design Space** | Agent Memory | Semantic knowledge search, cross-agent messaging, work orders, presence | ### Activating an agent @@ -48,7 +78,7 @@ Saga will greet you by name and guide you through creating your Product Brief. | Phase | Focus | Agent | Output folder | |-------|-------|-------|--------------| | 0. Alignment & Signoff | Stakeholder alignment before starting | Saga | — | -| 1. Product Brief | Vision, positioning, success criteria | Saga | `A-Product-Brief/` | +| 1. Product Brief | Vision, positioning, success criteria, build specification | Saga | `A-Product-Brief/` | | 2. Trigger Mapping | User psychology, business goals | Saga | `B-Trigger-Map/` | | 3. UX Scenarios | Scenario outlines via 8-question dialog | Freya | `C-UX-Scenarios/` | | 4. UX Design | Page specifications, interactions | Freya | `C-UX-Scenarios/` | @@ -61,9 +91,19 @@ Output folders are created inside your configured design output directory (defau --- -## Supported Design Tools +## Design Space -WDS offers agentic design capabilities with several visual design and prototyping services on the market: +Shared knowledge base and agent communication layer. Agents search design knowledge, message each other, and track work across sessions. + +**Database-agnostic** — same API regardless of backend: +- **SQLite** — local file, zero infrastructure, data stays on your machine +- **Supabase** — cloud database, team collaboration, multi-machine + +The installer asks during setup: "Install Design Space?" → choose your backend → done. + +--- + +## Supported Design Tools | Tool | What it does | MCP | |------|-------------|-----| @@ -74,36 +114,29 @@ WDS offers agentic design capabilities with several visual design and prototypin | **html.to.design** | Import HTML prototypes into Figma | Figma plugin | | **NanoBanana** | AI image generation for brand exploration | — | -The design loop works with any combination: wireframe in Excalidraw, generate screens with Stitch or Pencil, refine in Figma, pull back via MCP. - --- ## Project Structure -After installation, your project will have: +After installation: ``` your-project/ -├── _bmad/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/ -│ ├── method/ -│ ├── models/ -│ └── tools/ -├── design-process/ # Design output (created by agents) +├── _bmad/ +│ ├── wds/ # WDS system files +│ │ ├── skills/ # Saga, Freya, Design Space +│ │ ├── agents/ # Compiled agent files +│ │ ├── workflows/ # Phase workflows +│ │ ├── data/ # Standards, frameworks, agent guides +│ │ └── config.yaml # Your project configuration +│ └── design-space/ # Agent memory (optional, name configurable) +│ └── config.yaml # Backend config (SQLite or Supabase) +├── design-process/ # Design output (created by agents) │ ├── A-Product-Brief/ │ ├── B-Trigger-Map/ │ ├── C-UX-Scenarios/ │ └── D-Design-System/ -└── .claude/instructions.md # IDE configuration (varies by IDE) +└── .claude/instructions.md # IDE configuration (varies by IDE) ``` --- @@ -122,7 +155,7 @@ your-project/ Read and activate _bmad/wds/agents/saga-analyst.md ``` -4. **Follow Saga's guidance** — Saga will greet you by name and walk you through creating your Product Brief. When you're ready for design work, switch to Freya. +4. **Follow Saga's guidance** — she'll greet you by name and walk you through creating your Product Brief. If you have existing documents, upload them — she analyzes before asking questions. --- @@ -136,16 +169,15 @@ The installer configures your selected IDE(s) automatically. --- - ## Learning Material The installer can optionally include learning and reference material in `_wds-learn/`. This includes: -- **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 +- **Getting Started** — Quick onboarding guides +- **Course modules** — Complete training course +- **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 You can safely delete `_wds-learn/` at any time without affecting the agents or workflows. @@ -157,7 +189,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License -MIT - see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](LICENSE) for details. ---