---
description: Design system architecture with ER diagram, API contracts, and UI structure
allowed-tools: Read, Write, Edit, Bash, Task, TodoWrite
---

# Workflow Design - System Architecture Phase

**Input**: "$ARGUMENTS"

---

## PURPOSE

This command creates a comprehensive **design document** that serves as the source of truth for implementation. It defines:

1. **Data Layer** - ER diagram with models, fields, relations
2. **API Layer** - REST endpoints with request/response contracts
3. **UI Layer** - Pages and components with data requirements
4. **Dependency Graph** - Layered execution order for parallel tasks

---

## ⛔ CRITICAL RULES

### MUST DO
1. **MUST** create `design_document.yml` with ALL layers defined
2. **MUST** run `validate_design.py` to generate dependency graph
3. **MUST** verify no circular dependencies before proceeding
4. **MUST** show layered execution plan to user

### CANNOT DO
1. **CANNOT** create tasks without design document
2. **CANNOT** skip validation step
3. **CANNOT** proceed if validation fails

---

## EXECUTION FLOW

### ═══════════════════════════════════════════════════════════════
### STEP 1: Initialize Design Session
### ═══════════════════════════════════════════════════════════════

#### 1.1: Get Current Version
```bash
# Get active version from workflow
VERSION_ID=$(cat .workflow/current.yml 2>/dev/null | grep "active_version:" | awk '{print $2}')
if [ -z "$VERSION_ID" ]; then
  echo "ERROR: No active workflow. Run /workflow:spawn first"
  exit 1
fi
echo "VERSION_ID=$VERSION_ID"
```

#### 1.2: Create Design Directory
```bash
mkdir -p .workflow/versions/$VERSION_ID/design
mkdir -p .workflow/versions/$VERSION_ID/contexts
mkdir -p .workflow/versions/$VERSION_ID/tasks
```

#### 1.3: Display Design Start Banner
```
╔══════════════════════════════════════════════════════════════╗
║ 📐 SYSTEM DESIGN PHASE                                       ║
╠══════════════════════════════════════════════════════════════╣
║ Feature:  $ARGUMENTS                                         ║
║ Version:  $VERSION_ID                                        ║
╠══════════════════════════════════════════════════════════════╣
║ You will define:                                             ║
║   Layer 1: Data Models (ER Diagram)                          ║
║   Layer 2: API Endpoints (REST Contracts)                    ║
║   Layer 3: Pages & Components (UI Structure)                 ║
╚══════════════════════════════════════════════════════════════╝
```

---

### ═══════════════════════════════════════════════════════════════
### STEP 2: Analyze Requirements & Design System
### ═══════════════════════════════════════════════════════════════

**Use Task tool with system-architect agent:**

```
Use Task tool with:
  subagent_type: "system-architect"
  prompt: |
    # SYSTEM ARCHITECT - Design Document Creation

    ## INPUT
    Feature: "$ARGUMENTS"
    Version: $VERSION_ID
    Output: .workflow/versions/$VERSION_ID/design/design_document.yml

    ## YOUR MISSION
    Create a comprehensive design document following the schema in:
    skills/guardrail-orchestrator/schemas/design_document.yml

    ## ANALYSIS PROCESS

    ### Phase A: Understand Requirements
    1. Read the feature description carefully
    2. Identify the core user flows
    3. Determine what data needs to be stored
    4. Identify what APIs are needed
    5. Plan the UI structure

    ### Phase B: Design Data Layer (ER Diagram)
    For each entity needed:
    - Define fields with types and constraints
    - Define relations to other entities
    - Define validations
    - Consider indexes for performance

    ### Phase C: Design API Layer
    For each endpoint needed:
    - Define HTTP method and path
    - Define request body schema (for POST/PUT/PATCH)
    - Define response schemas for all status codes
    - Define authentication requirements
    - Link to data models used

    ### Phase D: Design UI Layer
    For each page needed:
    - Define route path
    - List data requirements (which APIs)
    - List components used
    - Define auth requirements

    For each component needed:
    - Define props interface
    - Define events emitted
    - List child components
    - List APIs called directly (if any)

    ## OUTPUT FORMAT

    Create `.workflow/versions/$VERSION_ID/design/design_document.yml`:

    ```yaml
    # Design Document
    workflow_version: "$VERSION_ID"
    feature: "$ARGUMENTS"
    created_at: <timestamp>
    status: draft
    revision: 1

    # LAYER 1: DATA MODELS
    data_models:
      - id: model_<name>
        name: <PascalCase>
        description: "<what this model represents>"
        table_name: <snake_case>
        fields:
          - name: id
            type: uuid
            constraints: [primary_key]
          - name: <field_name>
            type: <string|integer|boolean|datetime|uuid|json|text|float|enum>
            constraints: [<unique|not_null|indexed|default>]
            # If enum:
            enum_values: [<value1>, <value2>]
        relations:
          - type: <has_one|has_many|belongs_to|many_to_many>
            target: model_<other>
            foreign_key: <fk_field>
            on_delete: <cascade|set_null|restrict>
        timestamps: true
        validations:
          - field: <field_name>
            rule: "<validation_rule>"
            message: "<error message>"

    # LAYER 2: API ENDPOINTS
    api_endpoints:
      - id: api_<verb>_<resource>
        method: <GET|POST|PUT|PATCH|DELETE>
        path: /api/<path>
        summary: "<short description>"
        description: "<detailed description>"
        # For POST/PUT/PATCH:
        request_body:
          content_type: application/json
          schema:
            type: object
            properties:
              - name: <field>
                type: <type>
                required: <true|false>
                validations: [<rules>]
        responses:
          - status: 200
            description: "Success"
            schema:
              type: object
              properties:
                - name: <field>
                  type: <type>
          - status: 400
            description: "Validation error"
            schema:
              type: object
              properties:
                - name: error
                  type: string
        depends_on_models: [model_<name>]
        auth:
          required: <true|false>
          roles: [<role1>, <role2>]

    # LAYER 3: PAGES
    pages:
      - id: page_<name>
        name: "<Human Name>"
        path: /<route>
        layout: <layout_component>
        data_needs:
          - api_id: api_<name>
            purpose: "<why needed>"
            on_load: <true|false>
        components: [component_<name1>, component_<name2>]
        auth:
          required: <true|false>
          roles: []
          redirect: /login

    # LAYER 3: COMPONENTS
    components:
      - id: component_<name>
        name: <PascalCaseName>
        props:
          - name: <propName>
            type: <TypeScript type>
            required: <true|false>
            description: "<what this prop does>"
        events:
          - name: <onEventName>
            payload: "<payload type>"
            description: "<when this fires>"
        uses_apis: []
        uses_components: [component_<child>]
        variants: [<variant1>, <variant2>]
    ```

    ## DESIGN PRINCIPLES

    1. **Start with Data**: What data is needed? Design models first.
    2. **APIs Serve UI**: What operations does UI need? Design APIs next.
    3. **UI Consumes APIs**: Pages/Components use APIs. Design UI last.
    4. **Explicit Dependencies**: Every relation must be clearly defined.
    5. **Contracts First**: API request/response schemas are contracts.

    ## VERIFICATION

    After creating the design document, verify:
    1. Every API references existing models
    2. Every page references existing APIs and components
    3. Every component references existing child components
    4. No circular dependencies

    ## OUTPUT

    After creating the file, output:
    ```
    === DESIGN DOCUMENT CREATED ===

    Data Models:     X
    API Endpoints:   X
    Pages:           X
    Components:      X

    File: .workflow/versions/$VERSION_ID/design/design_document.yml
    ```
```

---

### ═══════════════════════════════════════════════════════════════
### STEP 3: Validate Design & Generate Dependency Graph
### ═══════════════════════════════════════════════════════════════

#### 3.1: Run Design Validation [MANDATORY]
```bash
python3 skills/guardrail-orchestrator/scripts/validate_design.py \
  .workflow/versions/$VERSION_ID/design/design_document.yml \
  --output-dir .workflow/versions/$VERSION_ID
```

**This generates:**
- `.workflow/versions/$VERSION_ID/dependency_graph.yml` - Layered execution order
- `.workflow/versions/$VERSION_ID/contexts/*.yml` - Per-entity context snapshots
- `.workflow/versions/$VERSION_ID/tasks/*.yml` - Tasks with full context

#### 3.2: Check Validation Result
```bash
VALIDATION_EXIT=$?
if [ $VALIDATION_EXIT -ne 0 ]; then
  echo "❌ Design validation failed. Fix errors and re-run."
  exit 1
fi
```

**BLOCK IF**: Validation fails → Display errors, do not proceed

---

### ═══════════════════════════════════════════════════════════════
### STEP 4: Display Layered Execution Plan
### ═══════════════════════════════════════════════════════════════

Read the generated dependency graph and display:

```
╔══════════════════════════════════════════════════════════════╗
║ 📊 DEPENDENCY GRAPH - EXECUTION LAYERS                       ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║ Layer 1: DATA MODELS (Parallel)                              ║
║ ─────────────────────────────────────────────                ║
║   📦 model_user      → backend                               ║
║   📦 model_post      → backend                               ║
║                                                              ║
║ Layer 2: API ENDPOINTS (Parallel, after Layer 1)             ║
║ ─────────────────────────────────────────────                ║
║   🔌 api_create_user → backend (needs: model_user)           ║
║   🔌 api_list_users  → backend (needs: model_user)           ║
║   🔌 api_create_post → backend (needs: model_user, model_post)║
║                                                              ║
║ Layer 3: UI (Parallel, after Layer 2)                        ║
║ ─────────────────────────────────────────────                ║
║   🧩 component_user_card → frontend                          ║
║   📄 page_users          → frontend (needs: api_list_users)  ║
║                                                              ║
╠══════════════════════════════════════════════════════════════╣
║ EXECUTION SUMMARY                                            ║
║   Total entities:     X                                      ║
║   Total layers:       X                                      ║
║   Max parallelism:    X (tasks can run simultaneously)       ║
║   Critical path:      X layers deep                          ║
╚══════════════════════════════════════════════════════════════╝
```

---

### ═══════════════════════════════════════════════════════════════
### STEP 5: Display Design Summary for Approval
### ═══════════════════════════════════════════════════════════════

```
╔══════════════════════════════════════════════════════════════╗
║ 🛑 DESIGN APPROVAL REQUIRED                                  ║
╠══════════════════════════════════════════════════════════════╣
║ Feature:  $ARGUMENTS                                         ║
║ Version:  $VERSION_ID                                        ║
╠══════════════════════════════════════════════════════════════╣
║ DESIGN DOCUMENT                                              ║
║   📦 Data Models:     X                                      ║
║   🔌 API Endpoints:   X                                      ║
║   📄 Pages:           X                                      ║
║   🧩 Components:      X                                      ║
╠══════════════════════════════════════════════════════════════╣
║ GENERATED ARTIFACTS                                          ║
║   ✅ Dependency graph calculated                             ║
║   ✅ Context snapshots created (X files)                     ║
║   ✅ Implementation tasks created (X tasks)                  ║
╠══════════════════════════════════════════════════════════════╣
║ EXECUTION PLAN                                               ║
║   Layer 1: X tasks (parallel) → backend                      ║
║   Layer 2: X tasks (parallel) → backend                      ║
║   Layer 3: X tasks (parallel) → frontend                     ║
╠══════════════════════════════════════════════════════════════╣
║ FILES CREATED                                                ║
║   .workflow/versions/$VERSION_ID/design/design_document.yml  ║
║   .workflow/versions/$VERSION_ID/dependency_graph.yml        ║
║   .workflow/versions/$VERSION_ID/contexts/*.yml              ║
║   .workflow/versions/$VERSION_ID/tasks/*.yml                 ║
╠══════════════════════════════════════════════════════════════╣
║ NEXT STEPS                                                   ║
║   Review the design above, then:                             ║
║     /workflow:approve    - Proceed to implementation         ║
║     /workflow:reject     - Request design changes            ║
╚══════════════════════════════════════════════════════════════╝
```

---

### ═══════════════════════════════════════════════════════════════
### STEP 6: Transition Workflow State
### ═══════════════════════════════════════════════════════════════

```bash
# Update progress
TASK_COUNT=$(ls .workflow/versions/$VERSION_ID/tasks/*.yml 2>/dev/null | wc -l)
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py progress \
  --tasks-created $TASK_COUNT

# Transition to awaiting approval
python3 skills/guardrail-orchestrator/scripts/workflow_manager.py transition AWAITING_DESIGN_APPROVAL
```

---

## CONTEXT SNAPSHOT EXAMPLE

Each task gets a context file like `.workflow/versions/$VERSION_ID/contexts/api_create_user.yml`:

```yaml
task_id: task_create_api_create_user
entity_id: api_create_user
workflow_version: v001

target:
  type: api
  definition:
    method: POST
    path: /api/users
    request_body:
      properties:
        - name: email
          type: string
          required: true
          validations: [email]
        - name: password
          type: string
          required: true
          validations: [min:8]
    responses:
      - status: 201
        schema: { id, email, name, created_at }
      - status: 400
        schema: { error, details }
      - status: 409
        schema: { error }

related:
  models:
    - id: model_user
      definition:
        name: User
        fields:
          - { name: id, type: uuid }
          - { name: email, type: string }
          - { name: password_hash, type: string }

dependencies:
  entity_ids: [model_user]

files:
  to_create:
    - app/api/users/route.ts
  reference:
    - path: app/api/health/route.ts
      purpose: "API route pattern"

acceptance:
  - criterion: "POST /api/users returns 201 on success"
    verification: "curl -X POST /api/users with valid data"
  - criterion: "Returns 409 if email exists"
    verification: "Test with duplicate email"
```

---

## USAGE

```bash
# After /workflow:spawn, run design:
/workflow:design

# This will:
# 1. Create comprehensive design document
# 2. Validate and generate dependency graph
# 3. Create tasks with full context
# 4. Wait for approval before implementation
```