ai-apps
/
project-standalo-sonic-cloud
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
project-standalo-sonic-cloud/.claude/commands/workflow/design.md

477 lines
19 KiB
Markdown
Raw Blame History

---
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
```
Reference in New Issue View Git Blame Copy Permalink