bahayonghang/fireworks-tech-graph

Generate a production-quality technical diagram from $ARGUMENTS.

Inputs

• Required: diagram description, system/process structure, or comparison axes
• Optional: output path, requested style, PNG export requirement, brand/product names

If the prompt is too vague to identify nodes and edges, ask for the missing structure before drawing.

Workflow

Follow this order:

1. Classify the request into a diagram type.
2. Extract the structure: layers, nodes, edges, flows, and semantic groups.
3. Plan the layout before drawing.
4. Load a style reference:
   • default: $SKILL_DIR/references/style-1-flat-icon.md
   • load another style-*.md file only when the user explicitly requests a different look
5. Map each concept to a consistent shape.
6. If branded products appear, read $SKILL_DIR/references/icons.md.
7. Resolve the output path:
   • use the user-provided file path when present
   • otherwise save the SVG in the current working directory with a descriptive filename
8. Write the SVG to disk.
9. If PNG was requested or would materially help, export PNG when local tooling is available.
10. Return the created file paths and clearly report whether PNG export succeeded, was skipped, or failed.

Output Contract

Always return:

• the SVG path
• the requested or inferred diagram type
• the style reference used
• PNG export status

If only SVG was produced, say so explicitly.

Diagram Types

Architecture Diagram

• Group services or components into horizontal or vertical layers.
• Common layers: Client → Gateway → Services → Data/Storage.
• Use dashed containers to group related components.
• Default viewBox: 0 0 960 600; use 0 0 960 800 for taller stacks.

Data Flow Diagram

• Emphasize what data moves where.
• Label every important arrow with the data type.
• Use thicker arrows for the primary data path.
• Use dashed arrows for triggers or control flow.

Flowchart / Process Flow

• Prefer top-to-bottom unless the flow is clearly wider than tall.
• Use diamonds for decisions, rounded rectangles for processes, and parallelograms for I/O.
• Keep node labels short; move extra detail into sub-labels.
• Snap to a readable grid.

Agent Architecture Diagram

• Consider these layers: Input, Agent Core, Memory, Tools, Output.
• Use loop arrows where reasoning or tool use iterates.
• Visually separate short-term and long-term memory.

Memory Architecture Diagram

• Separate read and write paths.
• Show tiers such as Working Memory, Short-term, Long-term, External Store.
• Label operations like store(), retrieve(), forget(), and consolidate().

Sequence Diagram

• Participants use vertical lifelines.
• Messages are horizontal arrows arranged top-to-bottom in time order.
• Use activation boxes or frames when the sequence has phases, loops, or alternatives.

Comparison / Feature Matrix

• Columns are systems; rows are attributes.
• Use alternating row fills for readability.
• If the comparison grows beyond 5 columns, split it into multiple diagrams.

Timeline / Gantt

• X-axis is time; Y-axis is phase, task, or milestone owner.
• Use bars for durations and diamonds or dots for milestones.

Mind Map / Concept Map

• Place the main concept at the center.
• First-level branches should be balanced around the center.
• Prefer curved branches instead of rigid straight spokes.

Shape Vocabulary

Use consistent semantics across diagrams:

| Concept | Shape | |---------|-------| | User / Human | circle or actor | | LLM / Model | double-border rounded rectangle | | Agent / Orchestrator | hexagon or emphasized controller box | | Short-term Memory | rounded rectangle with dashed border | | Long-term Memory | cylinder | | Vector Store | cylinder with inner rings | | Graph DB | clustered circular form or labeled store | | Tool / Function | utility box or gear-marked rectangle | | API / Gateway | hexagon | | Queue / Stream | horizontal pipe | | File / Document | folded-corner rectangle | | Browser / UI | browser frame | | Decision | diamond | | Process / Step | rounded rectangle | | External Service | cloud-like or dashed-border external node | | Data / Artifact | parallelogram |

Arrow Semantics

Use color and stroke to encode meaning:

| Flow Type | Suggested Meaning | |-----------|-------------------| | Blue solid | primary request or data flow | | Orange solid | control or trigger flow | | Green solid | memory read | | Green dashed | memory write | | Gray dashed | async or event-driven flow | | Purple solid | transform, embedding, or loopback |

When a diagram uses 2 or more arrow meanings, add a legend.

Layout Rules

• Keep related nodes aligned to a simple grid.
• Keep at least 60px between node edges where possible.
• Avoid routing arrows through nodes.
• The most important node should have the strongest visual emphasis.
• Keep arrow labels short and legible.
• Group related nodes with lightly tinted or dashed containers instead of cluttering labels.

SVG Technical Rules

• Default to viewBox="0 0 960 600" unless the diagram needs a taller or wider canvas.
• Use inline <style> and system fonts only.
• Do not use external @import font loading.
• Put reusable markers, gradients, filters, and clip paths in <defs>.
• Prefer 12-14px labels and 16-18px titles.
• Use marker arrows for directed edges.
• Use curved cubic paths for feedback loops and non-linear returns.

Platform & Export

Required deliverable

• Always deliver an .svg file.
• .png is an enhancement when local export tooling exists.

Export behavior

1. If rsvg-convert is available, use it for PNG export.
2. If it is not available:
   • still write the SVG
   • report that PNG export was skipped because the converter is unavailable
   • tell the user what command to check next based on their platform

Dependency checks

• In bash-like shells: command -v rsvg-convert
• In PowerShell: Get-Command rsvg-convert

Platform notes

• Windows: prefer PowerShell checks and quote paths that contain spaces. If the user gives a Windows path such as C:\Users\name\Desktop\diagram.svg, preserve it exactly.
• macOS: rsvg-convert is commonly provided by librsvg.
• Linux: rsvg-convert is commonly provided by librsvg2-bin or equivalent packages.

Path handling

• Use the user-provided output path when present.
• If no path is given, save in the current working directory.
• Do not rewrite a Windows path into POSIX form unless the user asked for that.
• Quote file paths with spaces when invoking export commands.

Failure handling

• If export fails, keep the SVG and report the exact output path.
• If only SVG was produced, say so explicitly instead of implying a full export succeeded.
• Do not invent download URLs or package-manager instructions you cannot verify from local context.

Final Checklist

• Main structure is readable at a glance
• Arrow semantics are consistent and labeled when needed
• Requested style reference was actually loaded
• SVG exists at the reported path

Styles

| # | Name | Best For | |---|------|----------| | 1 | Flat Icon (default) | blogs, docs, slides | | 2 | Dark Terminal | README, dev articles, dark presentations | | 3 | Blueprint | architecture and engineering documentation | | 4 | Notion Clean | internal docs, wikis, calm system diagrams | | 5 | Glassmorphism | keynotes or more polished visual storytelling |

Load the matching file from $SKILL_DIR/references/ when a style is selected.

AI / Agent Common Patterns

Internalize these recurring structures:

• RAG Pipeline: Query → Embed → Vector Search → Retrieve → LLM → Response
• Agentic RAG: query plus planner/tool loop before synthesis
• Agentic Search: Query → Planner → Tools → Synthesizer → Response
• Memory Layer: Input → Memory Manager → Store/Retrieve → Context
• Multi-Agent: Orchestrator → Sub-agents → Aggregator → Output
• Tool Call Flow: LLM → Tool Selector → Execution → Result Parser → back to LLM

Common Mistakes

• Arrow paths crossing through nodes
• Too many arrow colors with no legend
• Unlabeled important arrows
• No grouping in complex diagrams
• Text overflow inside nodes
• Reporting PNG output when only SVG exists
• Forgetting to load the requested style reference before drawing