whiteport-design-studio 0.1.0

package/src/templates/design-delivery.template.yaml

@@ -0,0 +1,104 @@
+# WDS Design Delivery Template
+# Copy this template to: deliveries/DD-XXX-name.yaml
+
+delivery:
+  id: "DD-XXX" # Format: DD-001, DD-002, etc.
+  name: "Feature Name" # Human-readable name
+  type: "user_flow" # user_flow | feature | component
+  status: "ready" # ready | in_progress | blocked
+  priority: "high" # high | medium | low
+  created_by: "wds-ux-expert"
+  created_at: "YYYY-MM-DDTHH:MM:SSZ"
+  updated_at: "YYYY-MM-DDTHH:MM:SSZ"
+  version: "1.0"
+
+description: |
+  [Describe what this delivery contains and why it matters.
+   Include the complete user flow and key features.]
+
+user_value:
+  problem: "[What user problem does this solve?]"
+  solution: "[How does this feature solve it?]"
+  success_criteria:
+    - "[Measurable success criterion 1]"
+    - "[Measurable success criterion 2]"
+    - "[Measurable success criterion 3]"
+
+design_artifacts:
+  scenarios:
+    - id: "XX-scenario-name"
+      path: "C-Scenarios/XX-scenario-name/"
+      screens: ["screen1", "screen2"]
+
+    - id: "XX-scenario-name"
+      path: "C-Scenarios/XX-scenario-name/"
+      screens: ["screen1"]
+
+  user_flows:
+    - name: "Flow Name"
+      path: "C-Scenarios/flows/flow-name.excalidraw"
+      entry: "entry-screen"
+      exit: "exit-screen"
+
+  design_system:
+    components:
+      - "Component Name (variants)"
+      - "Component Name (variants)"
+    path: "D-Design-System/"
+
+technical_requirements:
+  platform:
+    frontend: "framework-name" # From platform-requirements.yaml
+    backend: "framework-name" # From platform-requirements.yaml
+
+  integrations:
+    - name: "integration-name"
+      purpose: "[Why this integration is needed]"
+      required: true # true | false
+
+    - name: "integration-name"
+      purpose: "[Why this integration is needed]"
+      required: false
+
+  data_models:
+    - name: "ModelName"
+      fields: ["field1", "field2", "field3"]
+
+    - name: "ModelName"
+      fields: ["field1", "field2"]
+
+acceptance_criteria:
+  functional:
+    - "[Functional requirement 1]"
+    - "[Functional requirement 2]"
+    - "[Functional requirement 3]"
+
+  non_functional:
+    - "[Performance requirement]"
+    - "[Accessibility requirement]"
+    - "[Security requirement]"
+
+  edge_cases:
+    - "[Edge case 1] → [Expected behavior]"
+    - "[Edge case 2] → [Expected behavior]"
+    - "[Edge case 3] → [Expected behavior]"
+
+testing_guidance:
+  user_testing:
+    - "[User testing instruction 1]"
+    - "[User testing instruction 2]"
+
+  qa_testing:
+    - "[QA testing instruction 1]"
+    - "[QA testing instruction 2]"
+    - "[QA testing instruction 3]"
+
+estimated_complexity:
+  size: "medium" # small | medium | large
+  effort: "2-3 weeks" # Time estimate
+  risk: "low" # low | medium | high
+  dependencies: [] # List of DD-XXX IDs needed first
+
+notes: |
+  [Any special considerations, important context, or
+   critical details that the development team should know.]

package/src/templates/platform-requirements.template.yaml

@@ -0,0 +1,69 @@
+# WDS Platform Requirements Template
+# Save to: A-Project-Brief/platform-requirements.yaml
+
+project:
+  name: "Project Name"
+  type: "mobile_app" # mobile_app | web_app | desktop_app | api
+  wds_version: "6.0"
+  created_at: "YYYY-MM-DDTHH:MM:SSZ"
+
+platform:
+  frontend:
+    framework: "framework-name" # react_native | react | vue | angular | svelte
+    version: "X.X"
+    state_management: "library" # zustand | redux | mobx | context
+    navigation: "library" # react_navigation | react_router | vue_router
+    styling: "approach" # tailwind | styled_components | css_modules
+    ui_library: "library" # shadcn | mui | chakra (optional)
+
+  backend:
+    framework: "framework-name" # supabase | firebase | express | fastapi | django
+    version: "X.X"
+    auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom
+    database: "database-type" # postgresql | mysql | mongodb | firestore
+    storage: "storage-provider" # supabase_storage | s3 | cloudinary
+    api: "api-type" # rest | graphql | grpc
+
+  database:
+    type: "database-type" # postgresql | mysql | mongodb
+    version: "XX"
+    orm: "orm-library" # prisma | typeorm | mongoose (optional)
+
+  deployment:
+    frontend: "platform" # expo_eas | vercel | netlify | aws
+    backend: "platform" # supabase_cloud | firebase | heroku | aws
+    ci_cd: "platform" # github_actions | gitlab_ci | circle_ci
+    hosting: "platform" # vercel | netlify | aws (if web app)
+
+integrations:
+  - name: "integration-name"
+    provider: "provider-name"
+    required: true # true | false
+    purpose: "[Why this integration is needed]"
+
+  - name: "integration-name"
+    provider: "provider-name"
+    required: false
+    purpose: "[Why this integration is needed]"
+
+constraints:
+  - "[Technical constraint 1]"
+  - "[Technical constraint 2]"
+  - "[Business constraint 1]"
+  - "[Regulatory constraint 1]"
+
+performance_requirements:
+  - "[Performance requirement 1]"
+  - "[Performance requirement 2]"
+  - "[Performance requirement 3]"
+
+security_requirements:
+  - "[Security requirement 1]"
+  - "[Security requirement 2]"
+  - "[Security requirement 3]"
+
+wds_metadata:
+  project_brief: "A-Project-Brief/project-brief.md"
+  trigger_map: "B-Trigger-Map/trigger-map.md"
+  scenarios: "C-Scenarios/"
+  design_system: "D-Design-System/"

package/src/templates/test-scenario.template.yaml

@@ -0,0 +1,192 @@
+# WDS Test Scenario Template
+# Save to: test-scenarios/TS-XXX-name.yaml
+
+test_scenario:
+  id: "TS-XXX" # Format: TS-001, TS-002, etc.
+  name: "Feature Testing" # Human-readable name
+  delivery_id: "DD-XXX" # Related Design Delivery
+  type: "user_acceptance" # user_acceptance | integration | e2e
+  status: "ready" # ready | in_progress | blocked
+  tester: "designer" # designer | qa | developer
+  created_at: "YYYY-MM-DDTHH:MM:SSZ"
+
+test_objectives:
+  - "Validate implementation matches design specifications"
+  - "Verify user flow is intuitive and smooth"
+  - "Confirm all edge cases are handled"
+  - "Ensure design system components are used correctly"
+  - "Test accessibility and usability"
+
+test_environment:
+  devices:
+    - "Device 1 (OS version)"
+    - "Device 2 (OS version)"
+
+  test_data:
+    - field: "value"
+    - field: "value"
+
+# Happy Path Tests
+happy_path:
+  - id: "HP-001"
+    name: "Main User Flow"
+    priority: "critical" # critical | high | medium | low
+
+    steps:
+      - action: "[User action]"
+        expected: "[Expected result]"
+        design_ref: "[Path to specification]#[section]"
+
+      - action: "[User action]"
+        expected: "[Expected result]"
+        design_ref: "[Path to specification]#[section]"
+
+    success_criteria:
+      - "[Success criterion 1]"
+      - "[Success criterion 2]"
+      - "[Success criterion 3]"
+
+# Error State Tests
+error_states:
+  - id: "ES-001"
+    name: "Error Scenario"
+    priority: "high"
+
+    steps:
+      - action: "[Action that triggers error]"
+      - expected: "[Expected error message]"
+      - expected: "[Expected recovery option]"
+      - design_ref: "[Path to specification]#[error-section]"
+
+    success_criteria:
+      - "[Error handling criterion 1]"
+      - "[Error handling criterion 2]"
+
+# Edge Case Tests
+edge_cases:
+  - id: "EC-001"
+    name: "Edge Case Scenario"
+    priority: "medium"
+
+    steps:
+      - action: "[Unusual action]"
+      - expected: "[Expected handling]"
+      - design_ref: "[Path to specification]#[edge-case-section]"
+
+    success_criteria:
+      - "[Edge case criterion 1]"
+
+# Design System Validation
+design_system_checks:
+  - id: "DS-001"
+    name: "Component Validation"
+    checks:
+      - component: "Component Name"
+        instances: ["Location 1", "Location 2"]
+        verify:
+          - "[Visual property 1]"
+          - "[Visual property 2]"
+          - "[State behavior 1]"
+        design_ref: "D-Design-System/path/to/component.md"
+
+# Accessibility Tests
+accessibility:
+  - id: "A11Y-001"
+    name: "Screen Reader Navigation"
+    priority: "high"
+
+    setup: "Enable screen reader (VoiceOver/TalkBack)"
+
+    steps:
+      - action: "[Navigate with screen reader]"
+      - verify:
+          - "[Accessibility check 1]"
+          - "[Accessibility check 2]"
+
+    success_criteria:
+      - "[Accessibility criterion 1]"
+      - "[Accessibility criterion 2]"
+
+# Usability Tests
+usability:
+  - id: "UX-001"
+    name: "First Impression"
+    type: "observational"
+
+    instructions: |
+      [Instructions for conducting usability test]
+
+    success_criteria:
+      - "[Usability criterion 1]"
+      - "[Usability criterion 2]"
+
+# Performance Tests
+performance:
+  - id: "PERF-001"
+    name: "Performance Check"
+
+    verify:
+      - "[Performance metric 1]"
+      - "[Performance metric 2]"
+
+    success_criteria:
+      - "[Performance target 1]"
+      - "[Performance target 2]"
+
+# Test Report Template
+report_template:
+  sections:
+    - name: "Test Summary"
+      fields:
+        - "Date tested"
+        - "Tester name"
+        - "Device tested"
+        - "Build version"
+        - "Overall result (Pass/Fail/Partial)"
+
+    - name: "Happy Path Results"
+      fields:
+        - "Test ID"
+        - "Result (Pass/Fail)"
+        - "Notes"
+        - "Screenshots"
+
+    - name: "Issues Found"
+      fields:
+        - "Issue ID"
+        - "Severity (Critical/High/Medium/Low)"
+        - "Description"
+        - "Steps to reproduce"
+        - "Expected vs Actual"
+        - "Screenshot/Video"
+        - "Design reference violated"
+
+    - name: "Design System Compliance"
+      fields:
+        - "Component"
+        - "Compliant (Yes/No)"
+        - "Deviations noted"
+
+    - name: "Recommendations"
+      fields:
+        - "What worked well"
+        - "What needs improvement"
+        - "Suggested changes"
+
+# Sign-off Criteria
+sign_off:
+  required_for_approval:
+    - "All critical tests pass"
+    - "No critical or high severity issues"
+    - "Design system compliance > 95%"
+    - "Accessibility tests pass"
+    - "Usability metrics meet targets"
+
+  designer_approval:
+    statement: |
+      I confirm that the implemented feature matches the design
+      specifications and meets the quality standards defined in
+      this test scenario.
+
+    signature: "________________"
+    date: "________________"

package/src/workflows/00-system/FILE-NAMING-CONVENTIONS.md

@@ -0,0 +1,286 @@
+# WDS Agent File Naming Conventions
+
+**For**: All WDS Agents (Freya, Saga, Idunn)  
+**Purpose**: Consistent file naming across all WDS projects  
+**Version**: 1.0
+
+---
+
+## 🎯 Core Principle
+
+**Use descriptive, specific file names - NOT generic names like "README"**
+
+---
+
+## ❌ DON'T Use Generic Names
+
+### Never Create:
+- ❌ `README.md` (too generic, confusing when multiple exist)
+- ❌ `INSTRUCTIONS.md` (instructions for what?)
+- ❌ `GUIDE.md` (guide for what?)
+- ❌ `NOTES.md` (notes about what?)
+- ❌ `INFO.md` (info about what?)
+
+**Problem**: When there are 5 README files, which one do you read?
+
+---
+
+## ✅ DO Use Specific Names
+
+### Always Create:
+- ✅ `AGENTIC-DEVELOPMENT-GUIDE.md` (specific topic)
+- ✅ `FREYA-WORKFLOW-INSTRUCTIONS.md` (specific agent + purpose)
+- ✅ `PROTOTYPE-ROADMAP.md` (specific purpose)
+- ✅ `PROJECT-ANALYSIS-ROUTER.md` (specific function)
+- ✅ `COMPONENT-NAMING-CONVENTIONS.md` (specific topic)
+
+**Benefit**: Clear, self-documenting, no confusion
+
+---
+
+## 📋 Naming Patterns
+
+### Pattern 1: [TOPIC]-GUIDE.md
+**When**: Overview/introduction to a topic  
+**Examples**:
+- `AGENTIC-DEVELOPMENT-GUIDE.md`
+- `DESIGN-SYSTEM-GUIDE.md`
+- `TESTING-GUIDE.md`
+
+---
+
+### Pattern 2: [AGENT]-[PURPOSE]-INSTRUCTIONS.md
+**When**: Step-by-step instructions for specific agent  
+**Examples**:
+- `FREYA-WORKFLOW-INSTRUCTIONS.md`
+- `SAGA-ANALYSIS-INSTRUCTIONS.md`
+- `IDUNN-HANDOFF-INSTRUCTIONS.md`
+
+---
+
+### Pattern 3: [PURPOSE]-TEMPLATE.[ext]
+**When**: Reusable template files  
+**Examples**:
+- `work-file-template.yaml`
+- `story-file-template.md`
+- `page-template.html`
+- `demo-data-template.json`
+
+---
+
+### Pattern 4: [SPECIFIC-TOPIC].md
+**When**: Documentation for specific feature/concept  
+**Examples**:
+- `PROTOTYPE-ROADMAP.md`
+- `SYSTEM-GUIDE.md`
+- `FILE-INDEX.md`
+- `PROTOTYPE-ANALYSIS.md`
+
+---
+
+### Pattern 5: [function]-[purpose].md
+**When**: Instruction files for specific workflows  
+**Examples**:
+- `project-analysis-router.md`
+- `outline-based-analysis.md`
+- `strategy-work.md`
+- `design-work.md`
+
+---
+
+## 🗂️ Folder Organization
+
+### Documentation Folders Should Contain:
+
+```
+workflow-folder/
+├── [TOPIC]-GUIDE.md                 ← Main entry point
+├── [AGENT]-INSTRUCTIONS.md          ← Agent-specific steps
+├── [SPECIFIC-TOPIC].md              ← Supporting docs
+├── templates/
+│   ├── [name]-template.[ext]
+│   └── ...
+└── examples/
+    └── ...
+```
+
+**NOT**:
+```
+workflow-folder/
+├── README.md                        ← ❌ Too generic
+├── README-2.md                      ← ❌ Even worse!
+├── INSTRUCTIONS.md                  ← ❌ Instructions for what?
+└── GUIDE.md                         ← ❌ Guide for what?
+```
+
+---
+
+## 💡 Benefits of Specific Naming
+
+| Benefit | Description |
+|---------|-------------|
+| **Self-documenting** | File name tells you what it contains |
+| **No confusion** | Can't mistake one file for another |
+| **Easy search** | Find exact file you need |
+| **Better IDE** | File tabs show meaningful names |
+| **Team clarity** | Everyone knows what's what |
+| **Future-proof** | Scales to 100+ files without confusion |
+
+---
+
+## 🎯 Examples in WDS
+
+### Good (Current WDS Structure)
+
+```
+project-analysis/
+├── instructions.md                  ← Entry point (clear function)
+├── project-analysis-router.md       ← Router (specific purpose)
+├── SYSTEM-GUIDE.md                  ← System overview (specific)
+├── analysis-types/
+│   ├── outline-based-analysis.md
+│   ├── folder-based-analysis.md
+│   └── empty-project-response.md
+└── work-types/
+    ├── strategy-work.md
+    └── design-work.md
+```
+
+### Bad (Old Pattern - Don't Do This)
+
+```
+project-analysis/
+├── README.md                        ← ❌ Which readme?
+├── instructions.md
+├── GUIDE.md                         ← ❌ Guide for what?
+├── analysis-types/
+│   ├── README.md                    ← ❌ Another readme!
+│   └── instructions.md              ← ❌ Confusing
+└── work-types/
+    └── README.md                    ← ❌ Yet another readme!
+```
+
+---
+
+## 🚀 Action Items for Agents
+
+### When Creating New Documentation
+
+**Before creating file, ask**:
+1. What is the specific purpose of this file?
+2. Is there already a file with this name nearby?
+3. Can I make the name more descriptive?
+
+**Then name it**: `[SPECIFIC-TOPIC]-[TYPE].md`
+
+---
+
+### When You See Generic Names
+
+**If you encounter**:
+- `README.md` without clear context
+- Multiple `README.md` files in related folders
+- `INSTRUCTIONS.md` without specificity
+
+**Recommend renaming** to more specific names and document the change.
+
+---
+
+## 📝 File Type Suffixes
+
+**Use these suffixes for clarity**:
+
+- `-GUIDE.md` - Comprehensive overview/introduction
+- `-INSTRUCTIONS.md` - Step-by-step how-to
+- `-TEMPLATE.[ext]` - Reusable template
+- `-ANALYSIS.md` - Analysis/research document
+- `-REFERENCE.md` - Quick reference/cheat sheet
+- `-INDEX.md` - Index/directory of files
+- `-ROADMAP.md` - Status/plan tracking
+
+**Examples**:
+- `AGENTIC-DEVELOPMENT-GUIDE.md`
+- `FREYA-WORKFLOW-INSTRUCTIONS.md`
+- `page-template.html`
+- `PROTOTYPE-ANALYSIS.md`
+- `TAILWIND-REFERENCE.md`
+- `FILE-INDEX.md`
+- `PROTOTYPE-ROADMAP.md`
+
+---
+
+## ✅ Checklist: Good File Name?
+
+- [ ] Is it specific (not generic)?
+- [ ] Does it describe the content?
+- [ ] Is it unique in its folder?
+- [ ] Would a new team member understand it?
+- [ ] Does it include topic + type?
+
+**If all YES → Good name!**  
+**If any NO → Make more specific!**
+
+---
+
+## 🎓 Examples
+
+### Generic → Specific
+
+| ❌ Generic | ✅ Specific |
+|-----------|------------|
+| `README.md` | `AGENTIC-DEVELOPMENT-GUIDE.md` |
+| `INSTRUCTIONS.md` | `FREYA-WORKFLOW-INSTRUCTIONS.md` |
+| `GUIDE.md` | `DESIGN-SYSTEM-GUIDE.md` |
+| `template.yaml` | `work-file-template.yaml` |
+| `example.json` | `demo-data-template.json` |
+
+---
+
+## 📊 Impact
+
+**Before (Generic Naming)**:
+```
+project/
+├── README.md                        ← Which one to read?
+├── folder1/
+│   └── README.md                    ← Too many READMEs!
+├── folder2/
+│   ├── README.md                    ← Confusing!
+│   └── INSTRUCTIONS.md              ← Instructions for what?
+└── folder3/
+    └── README.md                    ← Stop!
+```
+
+**After (Specific Naming)**:
+```
+project/
+├── PROJECT-OVERVIEW-GUIDE.md        ← Clear!
+├── folder1/
+│   └── FEATURE-X-GUIDE.md           ← Specific!
+├── folder2/
+│   ├── AGENT-Y-INSTRUCTIONS.md      ← Clear purpose!
+│   └── WORKFLOW-Z-INSTRUCTIONS.md   ← Specific!
+└── folder3/
+    └── COMPONENT-W-GUIDE.md         ← Self-documenting!
+```
+
+---
+
+## 🎯 Apply This Rule Everywhere
+
+**WDS Projects**:
+- ✅ Use specific names
+- ✅ Include topic in name
+- ✅ Include type suffix
+- ✅ Make self-documenting
+
+**Agent Behavior**:
+- ✅ Never create generic `README.md`
+- ✅ Always use specific names
+- ✅ Recommend renaming when you see generic names
+- ✅ Update references when renaming
+
+---
+
+**Consistency creates clarity. Specific names eliminate confusion.** 📚
+