586 lines
30 KiB
Markdown
586 lines
30 KiB
Markdown
---
|
||
description: Design system architecture with ER diagram, API contracts, and UI structure
|
||
allowed-tools: Read, Write, Edit, Bash, Task, TodoWrite
|
||
agents: workflow-reviewer, type-generator
|
||
---
|
||
|
||
# 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: Generate ASCII Page Visualizations
|
||
### ═══════════════════════════════════════════════════════════════
|
||
|
||
**For each page in the design, generate an ASCII wireframe visualization:**
|
||
|
||
Read the design document and for each page, display an ASCII visualization:
|
||
|
||
```
|
||
╔══════════════════════════════════════════════════════════════════════════╗
|
||
║ 📄 PAGE VISUALIZATIONS ║
|
||
╠══════════════════════════════════════════════════════════════════════════╣
|
||
║ ║
|
||
║ Page: /songs (page_songs_list) ║
|
||
║ ──────────────────────────────────────────────────────────────────── ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 🔍 SearchBar [component_search_bar] │ ║
|
||
║ │ ┌─────────────────────────────────────┐ ┌──────────────┐ │ ║
|
||
║ │ │ Search songs... │ │ Search │ │ ║
|
||
║ │ └─────────────────────────────────────┘ └──────────────┘ │ ║
|
||
║ └──────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 📋 SongList [component_song_list] │ ║
|
||
║ │ │ ║
|
||
║ │ ┌────────────────────────────────────────────────────────┐ │ ║
|
||
║ │ │ 🎵 SongCard [component_song_card] │ │ ║
|
||
║ │ │ ┌───────┐ │ │ ║
|
||
║ │ │ │ 🖼️ │ Song Title │ │ ║
|
||
║ │ │ │ cover │ Artist Name [▶️] [➕] │ │ ║
|
||
║ │ │ └───────┘ │ │ ║
|
||
║ │ └────────────────────────────────────────────────────────┘ │ ║
|
||
║ │ │ ║
|
||
║ │ ┌────────────────────────────────────────────────────────┐ │ ║
|
||
║ │ │ 🎵 SongCard [component_song_card] │ │ ║
|
||
║ │ │ ... │ │ ║
|
||
║ │ └────────────────────────────────────────────────────────┘ │ ║
|
||
║ └──────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ Data: api_get_songs (on_load: true) ║
|
||
║ Events: onPlay → api_play_song, onAddToPlaylist → shows modal ║
|
||
║ ║
|
||
╠══════════════════════════════════════════════════════════════════════════╣
|
||
║ ║
|
||
║ Page: /songs/[id] (page_song_detail) ║
|
||
║ ──────────────────────────────────────────────────────────────────── ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 🎵 SongHeader [component_song_header] │ ║
|
||
║ │ ┌─────────────┐ │ ║
|
||
║ │ │ │ Song Title │ ║
|
||
║ │ │ 🖼️ Cover │ by Artist Name │ ║
|
||
║ │ │ (large) │ Album: Album Name │ ║
|
||
║ │ │ │ Duration: 3:45 │ ║
|
||
║ │ └─────────────┘ │ ║
|
||
║ │ [▶️ Play] [➕ Add to Playlist] │ ║
|
||
║ └──────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 📝 LyricsSection [component_lyrics] │ ║
|
||
║ │ │ ║
|
||
║ │ Verse 1: │ ║
|
||
║ │ Lorem ipsum dolor sit amet... │ ║
|
||
║ │ │ ║
|
||
║ └──────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 🎵 RelatedSongs [component_related_songs] │ ║
|
||
║ │ Similar songs you might like: │ ║
|
||
║ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ ║
|
||
║ │ │ Song 1 │ │ Song 2 │ │ Song 3 │ │ ║
|
||
║ │ └─────────┘ └─────────┘ └─────────┘ │ ║
|
||
║ └──────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ Data: api_get_song (on_load: true), api_get_related_songs ║
|
||
║ ║
|
||
╚══════════════════════════════════════════════════════════════════════════╝
|
||
```
|
||
|
||
**Visualization Guidelines:**
|
||
|
||
For each page in design_document.yml:
|
||
1. **Draw page container** with route path and page_id
|
||
2. **Draw each component** as a box with:
|
||
- Component name and component_id
|
||
- Visual representation of what it contains
|
||
- Event handlers shown as buttons [▶️] [➕]
|
||
3. **Show component hierarchy** with nesting
|
||
4. **List data requirements** at the bottom:
|
||
- Which APIs are called
|
||
- on_load triggers
|
||
- User action triggers
|
||
|
||
**Component Visual Patterns:**
|
||
|
||
| Component Type | ASCII Pattern |
|
||
|---------------|---------------|
|
||
| Card | `┌──────┐` with content inside |
|
||
| Button | `[Label]` |
|
||
| Input | `┌────────────────┐` empty box |
|
||
| List | Multiple cards stacked |
|
||
| Grid | Cards side by side |
|
||
| Image | `🖼️` emoji placeholder |
|
||
| Icon | Appropriate emoji |
|
||
|
||
---
|
||
|
||
### ═══════════════════════════════════════════════════════════════
|
||
### STEP 5: 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 6: 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 7: 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
|
||
```
|