Create Diagram - Workflow Instructions
<critical>The workflow execution engine is governed by: {project_root}/.faos/core/tasks/workflow.xml</critical>
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
<critical>This workflow creates system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format.</critical>
<workflow>
<step n="0" goal="Contextual Analysis">
<action>Review user's request and extract: diagram type, components/entities, relationships, notation preferences</action>
<check if="ALL requirements clear"><action>Skip to Step 6</action></check>
<check if="SOME requirements clear"><action>Only ask about missing info in Steps 2-3</action></check>
</step>
<step n="1" goal="Assess Depth and Select Visual Pattern">
<action>Based on the user's request, determine the diagram depth level per {{helpers}} Depth Assessment:</action>
<action>Present assessment:
- Simple/Conceptual (10-20 elements): High-level overview, explain a concept
- Standard (20-40 elements): Document a system, show a process
- Comprehensive/Technical (40-80 elements): Detailed audit, implementation guide
</action>
<action>State your assessment: "This looks like a [depth] diagram because [reason]"</action>
<action>Select the best visual pattern from {{helpers}} Visual Pattern Library. For technical diagrams, common patterns are:
- pipeline: For request processing chains, data transformation flows
- tree: For class hierarchies, org structures, inheritance
- fan-out: For API gateways, event distribution, load balancing
- cluster: For microservice groups, technology stacks
- lines-as-structure: For sequence diagrams, dependency graphs
- side-by-side: For current vs proposed, option comparisons
</action>
<action>State: "I recommend the [pattern] pattern because it argues that [specific argument the diagram makes]"</action>
<action>Ask: "Does this depth level and visual pattern match your intent? (yes/adjust)"</action>
<action>WAIT for confirmation</action>
<check if="user says adjust">
<action>Revise depth and/or pattern based on feedback</action>
<action>Confirm revised choices</action>
</check>
</step>
<step n="2" goal="Identify Diagram Type" elicit="true">
<action>Ask: "What type of technical diagram do you need?"</action>
<action>Present options:
1. System Architecture
2. Entity-Relationship Diagram (ERD)
3. UML Class Diagram
4. UML Sequence Diagram
5. UML Use Case Diagram
6. Network Diagram
7. Other
</action>
<action>WAIT for selection</action>
</step>
<step n="3" goal="Gather Requirements" elicit="true">
<action>Ask: "Describe the components/entities and their relationships"</action>
<action>Ask: "What notation standard? (Standard/Simplified/Strict UML-ERD)"</action>
<action>WAIT for user input</action>
<action>Summarize what will be included and confirm with user</action>
</step>
<step n="4" goal="Check for Existing Theme" elicit="true">
<action>Check if theme.json exists at output location</action>
<check if="exists"><action>Ask to use it, load if yes, else proceed to Step 5</action></check>
<check if="not exists"><action>Proceed to Step 5</action></check>
</step>
<step n="5" goal="Create Theme" elicit="true">
<action>Ask: "Choose a color scheme for your diagram:"</action>
<action>Present numbered options:
1. Professional
- Component: #e3f2fd (light blue)
- Database: #e8f5e9 (light green)
- Service: #fff3e0 (light orange)
- Border: #1976d2 (blue)
2. Colorful
- Component: #e1bee7 (light purple)
- Database: #c5e1a5 (light lime)
- Service: #ffccbc (light coral)
- Border: #7b1fa2 (purple)
3. Minimal
- Component: #f5f5f5 (light gray)
- Database: #eeeeee (gray)
- Service: #e0e0e0 (medium gray)
- Border: #616161 (dark gray)
4. Custom - Define your own colors
</action>
<action>WAIT for selection</action>
<action>Create theme.json based on selection, including semantic color mapping per {{helpers}}</action>
<action>Show preview and confirm</action>
</step>
<step n="6" goal="Plan Diagram Structure">
<action>List all components/entities</action>
<action>Map all relationships</action>
<action>Apply the selected visual pattern to the layout plan</action>
<action>Show planned layout</action>
<action>Ask: "Structure looks correct? (yes/no)"</action>
<check if="no"><action>Adjust and repeat</action></check>
</step>
<step n="7" goal="Load Resources">
<action>Load {{templates}} and extract `diagram` section</action>
<action>Load visual_patterns from {{templates}} for the selected pattern</action>
<action>Load {{library}}</action>
<action>Load theme.json and merge with template</action>
<action>Load {{helpers}} for guidelines</action>
</step>
<step n="8" goal="Build Diagram Elements">
<critical>Apply the design philosophy from {{helpers}}: This diagram must ARGUE a point, not just DISPLAY components. Follow the selected visual pattern for layout.</critical>
<critical>Use descriptive string IDs per {{helpers}} ID conventions (e.g., "auth_service_rect" not "rect_1")</critical>
<critical>Prefer free-floating text for section labels, annotations, and callouts. Target less than 30% containerized text per {{helpers}} Text Strategy.</critical>
<substep>For Each Component:
- Generate descriptive string IDs per {{helpers}} ID conventions (e.g., auth_service_rect, auth_service_txt, auth_service_grp)
- Create shape with groupIds
- Calculate text width
- Create text with containerId and matching groupIds
- Add boundElements
- Apply semantic color based on the component's role (primary/secondary/accent) per {{helpers}}
</substep>
<substep>For Each Connection:
- Determine arrow type (straight/elbow)
- Create with startBinding and endBinding
- Update boundElements on both components
- Apply semantic color to arrows (success for happy path, warning for conditional, danger for error)
</substep>
<substep>Add Free-Floating Text:
- Section titles above each logical group
- Annotations near complex relationships
- Version or metadata notes in a corner
</substep>
<substep>Build Order by Type:
- Architecture: Services -> Databases -> Connections -> Labels -> Annotations
- ERD: Entities -> Attributes -> Relationships -> Cardinality -> Annotations
- UML Class: Classes -> Attributes -> Methods -> Relationships -> Notes
- UML Sequence: Actors -> Lifelines -> Messages -> Returns -> Notes
- UML Use Case: Actors -> Use Cases -> Relationships -> Notes
</substep>
<substep>Alignment:
- Snap to 20px grid
- Space: 40px between components, 60px between sections
- Follow the selected visual pattern's layout rules from {{templates}}
</substep>
<check if="planned element count exceeds 30">
<action>Switch to section-by-section generation per {{helpers}} Section-by-Section Generation Protocol</action>
<action>Identify logical sections based on diagram type (e.g., by service layer for architecture)</action>
<action>Generate each section separately, using namespaced seeds</action>
<action>After all sections: merge, validate cross-section arrows, verify boundElements</action>
</check>
<check if="depth is Comprehensive/Technical">
<action>Add evidence artifacts per {{helpers}} Evidence Artifacts guide</action>
<action>Embed real code/JSON/API shapes next to relevant components (max 5)</action>
</check>
</step>
<step n="9" goal="Optimize and Save">
<action>Strip unused elements and elements with isDeleted: true</action>
<action>Save to {{default_output_file}}</action>
</step>
<step n="10" goal="Validate JSON Syntax">
<critical>NEVER delete the file if validation fails - always fix syntax errors</critical>
<action>Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('Valid JSON')"</action>
<check if="validation fails (exit code 1)">
<action>Read the error message carefully - it shows the syntax error and position</action>
<action>Open the file and navigate to the error location</action>
<action>Fix the syntax error (add missing comma, bracket, or quote as indicated)</action>
<action>Save the file</action>
<action>Re-run validation with the same command</action>
<action>Repeat until validation passes</action>
</check>
<action>Once validation passes, confirm: "Diagram created at {{default_output_file}}. Open to view?"</action>
</step>
<step n="11" goal="Visual Preview (Optional)" optional="true">
<action>Load {{render_validate}}</action>
<action>Run: python3 {{render_script}} {{default_output_file}}</action>
<check if="exit code is 2 (Playwright not installed)">
<action>Skip: "Playwright not available — skipping PNG preview. Diagram is still valid."</action>
</check>
<check if="exit code is 0">
<action>View the generated PNG file</action>
<action>Audit against design vision: Does the diagram ARGUE its point?</action>
<action>Check: overlapping text, misaligned arrows, spacing issues, color rendering</action>
<check if="issues found">
<action>Fix the JSON</action>
<action>Re-render (max 3 cycles)</action>
</check>
<action>Ask: "Keep the PNG preview file? (yes/no)"</action>
</check>
</step>
<step n="12" goal="Validate Content">
<invoke-task>Validate against {{validation}} using {faos}/core/tasks/validate-workflow.xml</invoke-task>
</step>
</workflow>
Quality Checklist
Create Diagram - Validation Checklist
Design Quality
Generation Quality
Element Structure
Layout and Alignment
Connections
Notation and Standards
Theme and Styling
Output Quality
1---2name: excalidraw-diagram3description: "Create system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format."4tags: [excalidraw, diagrams, diagram, visualization]5metadata:6 source: https://skillmd.com/skills/frank-luongt/excalidraw-diagram7---89# Create Diagram - Workflow Instructions1011```xml12<critical>The workflow execution engine is governed by: {project_root}/.faos/core/tasks/workflow.xml</critical>13<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>14<critical>This workflow creates system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format.</critical>1516<workflow>1718 <step n="0" goal="Contextual Analysis">19 <action>Review user's request and extract: diagram type, components/entities, relationships, notation preferences</action>20 <check if="ALL requirements clear"><action>Skip to Step 6</action></check>21 <check if="SOME requirements clear"><action>Only ask about missing info in Steps 2-3</action></check>22 </step>2324 <step n="1" goal="Assess Depth and Select Visual Pattern">25 <action>Based on the user's request, determine the diagram depth level per {{helpers}} Depth Assessment:</action>26 <action>Present assessment:27 - Simple/Conceptual (10-20 elements): High-level overview, explain a concept28 - Standard (20-40 elements): Document a system, show a process29 - Comprehensive/Technical (40-80 elements): Detailed audit, implementation guide30 </action>31 <action>State your assessment: "This looks like a [depth] diagram because [reason]"</action>32 <action>Select the best visual pattern from {{helpers}} Visual Pattern Library. For technical diagrams, common patterns are:33 - pipeline: For request processing chains, data transformation flows34 - tree: For class hierarchies, org structures, inheritance35 - fan-out: For API gateways, event distribution, load balancing36 - cluster: For microservice groups, technology stacks37 - lines-as-structure: For sequence diagrams, dependency graphs38 - side-by-side: For current vs proposed, option comparisons39 </action>40 <action>State: "I recommend the [pattern] pattern because it argues that [specific argument the diagram makes]"</action>41 <action>Ask: "Does this depth level and visual pattern match your intent? (yes/adjust)"</action>42 <action>WAIT for confirmation</action>43 <check if="user says adjust">44 <action>Revise depth and/or pattern based on feedback</action>45 <action>Confirm revised choices</action>46 </check>47 </step>4849 <step n="2" goal="Identify Diagram Type" elicit="true">50 <action>Ask: "What type of technical diagram do you need?"</action>51 <action>Present options:52 1. System Architecture53 2. Entity-Relationship Diagram (ERD)54 3. UML Class Diagram55 4. UML Sequence Diagram56 5. UML Use Case Diagram57 6. Network Diagram58 7. Other59 </action>60 <action>WAIT for selection</action>61 </step>6263 <step n="3" goal="Gather Requirements" elicit="true">64 <action>Ask: "Describe the components/entities and their relationships"</action>65 <action>Ask: "What notation standard? (Standard/Simplified/Strict UML-ERD)"</action>66 <action>WAIT for user input</action>67 <action>Summarize what will be included and confirm with user</action>68 </step>6970 <step n="4" goal="Check for Existing Theme" elicit="true">71 <action>Check if theme.json exists at output location</action>72 <check if="exists"><action>Ask to use it, load if yes, else proceed to Step 5</action></check>73 <check if="not exists"><action>Proceed to Step 5</action></check>74 </step>7576 <step n="5" goal="Create Theme" elicit="true">77 <action>Ask: "Choose a color scheme for your diagram:"</action>78 <action>Present numbered options:79 1. Professional80 - Component: #e3f2fd (light blue)81 - Database: #e8f5e9 (light green)82 - Service: #fff3e0 (light orange)83 - Border: #1976d2 (blue)8485 2. Colorful86 - Component: #e1bee7 (light purple)87 - Database: #c5e1a5 (light lime)88 - Service: #ffccbc (light coral)89 - Border: #7b1fa2 (purple)9091 3. Minimal92 - Component: #f5f5f5 (light gray)93 - Database: #eeeeee (gray)94 - Service: #e0e0e0 (medium gray)95 - Border: #616161 (dark gray)9697 4. Custom - Define your own colors98 </action>99 <action>WAIT for selection</action>100 <action>Create theme.json based on selection, including semantic color mapping per {{helpers}}</action>101 <action>Show preview and confirm</action>102 </step>103104 <step n="6" goal="Plan Diagram Structure">105 <action>List all components/entities</action>106 <action>Map all relationships</action>107 <action>Apply the selected visual pattern to the layout plan</action>108 <action>Show planned layout</action>109 <action>Ask: "Structure looks correct? (yes/no)"</action>110 <check if="no"><action>Adjust and repeat</action></check>111 </step>112113 <step n="7" goal="Load Resources">114 <action>Load {{templates}} and extract `diagram` section</action>115 <action>Load visual_patterns from {{templates}} for the selected pattern</action>116 <action>Load {{library}}</action>117 <action>Load theme.json and merge with template</action>118 <action>Load {{helpers}} for guidelines</action>119 </step>120121 <step n="8" goal="Build Diagram Elements">122 <critical>Apply the design philosophy from {{helpers}}: This diagram must ARGUE a point, not just DISPLAY components. Follow the selected visual pattern for layout.</critical>123 <critical>Use descriptive string IDs per {{helpers}} ID conventions (e.g., "auth_service_rect" not "rect_1")</critical>124 <critical>Prefer free-floating text for section labels, annotations, and callouts. Target less than 30% containerized text per {{helpers}} Text Strategy.</critical>125126 <substep>For Each Component:127 - Generate descriptive string IDs per {{helpers}} ID conventions (e.g., auth_service_rect, auth_service_txt, auth_service_grp)128 - Create shape with groupIds129 - Calculate text width130 - Create text with containerId and matching groupIds131 - Add boundElements132 - Apply semantic color based on the component's role (primary/secondary/accent) per {{helpers}}133 </substep>134135 <substep>For Each Connection:136 - Determine arrow type (straight/elbow)137 - Create with startBinding and endBinding138 - Update boundElements on both components139 - Apply semantic color to arrows (success for happy path, warning for conditional, danger for error)140 </substep>141142 <substep>Add Free-Floating Text:143 - Section titles above each logical group144 - Annotations near complex relationships145 - Version or metadata notes in a corner146 </substep>147148 <substep>Build Order by Type:149 - Architecture: Services -> Databases -> Connections -> Labels -> Annotations150 - ERD: Entities -> Attributes -> Relationships -> Cardinality -> Annotations151 - UML Class: Classes -> Attributes -> Methods -> Relationships -> Notes152 - UML Sequence: Actors -> Lifelines -> Messages -> Returns -> Notes153 - UML Use Case: Actors -> Use Cases -> Relationships -> Notes154 </substep>155156 <substep>Alignment:157 - Snap to 20px grid158 - Space: 40px between components, 60px between sections159 - Follow the selected visual pattern's layout rules from {{templates}}160 </substep>161162 <check if="planned element count exceeds 30">163 <action>Switch to section-by-section generation per {{helpers}} Section-by-Section Generation Protocol</action>164 <action>Identify logical sections based on diagram type (e.g., by service layer for architecture)</action>165 <action>Generate each section separately, using namespaced seeds</action>166 <action>After all sections: merge, validate cross-section arrows, verify boundElements</action>167 </check>168169 <check if="depth is Comprehensive/Technical">170 <action>Add evidence artifacts per {{helpers}} Evidence Artifacts guide</action>171 <action>Embed real code/JSON/API shapes next to relevant components (max 5)</action>172 </check>173 </step>174175 <step n="9" goal="Optimize and Save">176 <action>Strip unused elements and elements with isDeleted: true</action>177 <action>Save to {{default_output_file}}</action>178 </step>179180 <step n="10" goal="Validate JSON Syntax">181 <critical>NEVER delete the file if validation fails - always fix syntax errors</critical>182 <action>Run: node -e "JSON.parse(require('fs').readFileSync('{{default_output_file}}', 'utf8')); console.log('Valid JSON')"</action>183 <check if="validation fails (exit code 1)">184 <action>Read the error message carefully - it shows the syntax error and position</action>185 <action>Open the file and navigate to the error location</action>186 <action>Fix the syntax error (add missing comma, bracket, or quote as indicated)</action>187 <action>Save the file</action>188 <action>Re-run validation with the same command</action>189 <action>Repeat until validation passes</action>190 </check>191 <action>Once validation passes, confirm: "Diagram created at {{default_output_file}}. Open to view?"</action>192 </step>193194 <step n="11" goal="Visual Preview (Optional)" optional="true">195 <action>Load {{render_validate}}</action>196 <action>Run: python3 {{render_script}} {{default_output_file}}</action>197 <check if="exit code is 2 (Playwright not installed)">198 <action>Skip: "Playwright not available — skipping PNG preview. Diagram is still valid."</action>199 </check>200 <check if="exit code is 0">201 <action>View the generated PNG file</action>202 <action>Audit against design vision: Does the diagram ARGUE its point?</action>203 <action>Check: overlapping text, misaligned arrows, spacing issues, color rendering</action>204 <check if="issues found">205 <action>Fix the JSON</action>206 <action>Re-render (max 3 cycles)</action>207 </check>208 <action>Ask: "Keep the PNG preview file? (yes/no)"</action>209 </check>210 </step>211212 <step n="12" goal="Validate Content">213 <invoke-task>Validate against {{validation}} using {faos}/core/tasks/validate-workflow.xml</invoke-task>214 </step>215216</workflow>217```218219220## Quality Checklist221222# Create Diagram - Validation Checklist223224## Design Quality225226- [ ] Diagram makes a clear visual argument (not just displaying components)227- [ ] Isomorphism Test: Structure communicates without labels228- [ ] Education Test: Unfamiliar viewer learns something in 30 seconds229- [ ] Visual pattern applied consistently throughout the diagram230- [ ] Depth level matches user intent (Simple/Standard/Comprehensive)231- [ ] Free-floating text used for labels and annotations (target <30% containerized)232- [ ] Semantic colors encode element roles (primary/secondary/accent/success/warning/danger)233- [ ] All IDs are descriptive strings (e.g., "auth_service_rect" not "rect_1")234235## Generation Quality236237- [ ] If >30 elements: section-by-section generation used with namespaced seeds238- [ ] Descriptive string IDs follow `{component}_{role}_{type}` pattern239- [ ] Cross-section arrows have valid startBinding and endBinding240- [ ] Evidence artifacts present for Comprehensive/Technical depth (if applicable)241- [ ] Evidence artifacts use dark rectangle styling with monospace text242- [ ] Element count within limit (under 80)243244## Element Structure245246- [ ] All components with labels have matching `groupIds`247- [ ] All text elements have `containerId` pointing to parent component248- [ ] Text width calculated properly (no cutoff)249- [ ] Text alignment appropriate for diagram type250251## Layout and Alignment252253- [ ] All elements snapped to 20px grid254- [ ] Component spacing consistent (40px/60px)255- [ ] Hierarchical alignment maintained256- [ ] No overlapping elements257258## Connections259260- [ ] All arrows have `startBinding` and `endBinding`261- [ ] `boundElements` array updated on connected components262- [ ] Arrow routing avoids overlaps263- [ ] Relationship types clearly indicated264265## Notation and Standards266267- [ ] Follows specified notation standard (UML/ERD/etc)268- [ ] Symbols used correctly269- [ ] Cardinality/multiplicity shown where needed270- [ ] Labels and annotations clear271272## Theme and Styling273274- [ ] Theme colors applied consistently275- [ ] Component types visually distinguishable276- [ ] Text is readable277- [ ] Professional appearance278279## Output Quality280281- [ ] Element count under 80282- [ ] No elements with `isDeleted: true`283- [ ] JSON is valid284- [ ] File saved to correct location285