6.3 KiB

Raw Blame History

Project Structure System

Overview

WDS includes a centralized project initialization system that collects project structure metadata and makes it available to all agents throughout the workflow. This ensures proper folder organization from the start and eliminates confusion.

The Central Project Details File

All project configuration is stored in one central file:

📄 wds-workflow-status.yaml (in project docs root)

This file contains:

Project metadata (name, type, creation date)
Project structure (landing page, website, or application)
Delivery configuration (format, target platform, PRD requirements)
Language configuration
Folder naming preferences
Design system settings
Workflow progress tracking

All WDS agents read this file to understand project context and structure.

How It Works

Step 1: Workflow Init (Collection)

During initial project setup (workflow-init), the system asks:

"What are you designing?"

Separate pages - Individual pages or page variants
Single user flow - Multiple pages, single user journey
Multiple user flows - Multiple scenarios/journeys, interactive features

Step 2: Storage (Central Config)

This information is written to wds-workflow-status.yaml:

# Project information
project: "WDS Presentation Page"
project_type: "landing-page"

# Project structure (defines folder organization)
project_structure:
  type: "separate_pages"
  scenarios: "single"
  pages: "single"

# Delivery configuration (what gets handed off)
delivery:
  format: "wordpress"
  target_platform: "wordpress"
  requires_prd: false
  description: "WordPress page editor code with markup and content sections"

Key benefit: Since requires_prd: false, the system knows not to include PRD phases (Phase 3 Platform Requirements, Phase 6 PRD Finalization). The workflow focuses only on design specifications that translate directly to WordPress implementation.

Step 3: Application (All Agents)

When any agent starts work, they:

Read wds-workflow-status.yaml
Extract project_structure section
Apply appropriate folder organization rules

Example - Freya (UX Designer):

Reads config file before greeting user
Understands this is "separate pages"
Places pages directly in 4-scenarios/ (no scenario subfolders)
Numbers pages with individual identifiers

Information Flow

User Input → Workflow Init → wds-workflow-status.yaml → All Agents → Correct Structure
            (Step 2b)      (Central Storage)           (Read Config)  (Applied)

Key Principle: Define once, use everywhere.

Separate Pages

Structure: 4-scenarios/start-page/ or variants
Pattern: Pages directly in 4-scenarios/
Variants: start-page-variant-a/, start-page-variant-b/ (if A/B testing)
Use case: Landing pages, standalone pages, page variants

4-scenarios/
  start-page/
    start-page.md
    sketches/
    prototypes/
  start-page-variant-a/  (optional)
    start-page-variant-a.md
    sketches/

Single User Flow

Structure: 4-scenarios/1.1-home/, 4-scenarios/1.2-about/
Pattern: Pages directly in 4-scenarios/
Numbering: Sequential pages 1.1, 1.2, 1.3, etc.
No Scenario Subfolders: All pages at the same level
Use case: Simple websites, wizard flows, single-screen apps

4-scenarios/
  1.1-home/
    1.1-home.md
    sketches/
    prototypes/
  1.2-about/
    1.2-about.md
    sketches/
  1.3-contact/
    1.3-contact.md
    sketches/

Multiple User Flows

Structure: 4-scenarios/1-onboarding/, 4-scenarios/2-dashboard/
Pattern: Scenario subfolders, pages within scenarios
Numbering:
- Scenarios: 1-scenario-name, 2-scenario-name
- Pages within: 1.1-page, 1.2-page, 2.1-page, 2.2-page
Use case: Web applications, mobile apps, admin systems

4-scenarios/
  1-onboarding/
    00-scenario.md
    1.1-signup/
      1.1-signup.md
      sketches/
    1.2-verify-email/
      1.2-verify-email.md
      sketches/
  2-dashboard/
    00-scenario.md
    2.1-overview/
      2.1-overview.md
      sketches/
    2.2-settings/
      2.2-settings.md
      sketches/

Benefits

For Users

No confusion about folder structure
Consistent organization across projects
Correct setup from the start - no reorganization needed

For Agents

Clear instructions based on project type
No guesswork about where to place files
Proper structure enables smooth handoffs between phases

Implementation Files

1. Collection Phase

File: workflows/workflow-init/instructions.md
Step: Step 2 - "Project Structure"
When: During initial project setup
Action: Asks user to classify project structure

2. Central Storage

File: wds-workflow-status.yaml (project root)
Template: workflows/00-system/wds-workflow-status-template.yaml
Section: project_structure:
Fields:
- type - separate_pages | single_flow | multiple_flows
- scenarios - single | multiple
- pages - single | multiple

3. Application - All Phases

Every agent that needs structure information reads from wds-workflow-status.yaml:

Freya (UX Designer):

File: workflows/4-ux-design/steps/step-01-init.md
When: Before greeting user (initialization)
Action: Reads config, applies folder rules

Future agents can access the same information by reading the central config file.

Migration for Existing Projects

If a project was created before this system:

Add structure section to config (config.yaml or wds-workflow-status.yaml)
Identify the project type based on actual content
Reorganize folders if needed to match the standard
Update all internal references to reflect new structure

Example addition to config:

project:
  structure:
    type: "single_flow"
    scenarios: "single"
    pages: "multiple"

Future Enhancements

Potential additions to this system:

Multi-language variants (e.g., /en/, /sv/ folders)
Platform variants (e.g., /web/, /mobile/ folders)
Custom structure templates for specific industries
Validation tools to ensure structure compliance

Created: December 27, 2025
Status: Implemented in WDS v6

6.3 KiB Raw Blame History