windowook-skills 1.0.0

package/skills/excalidraw/README.md

@@ -0,0 +1,76 @@
+# Excalidraw - Architecture Diagram Generator
+
+Generate architecture diagrams as `.excalidraw` files from codebase analysis, with optional PNG and SVG export.
+
+---
+
+## Installation
+
+```bash
+# Add the ccc marketplace (if not already added)
+/plugin marketplace add ooiyeefei/ccc
+
+# Install the skills collection
+/plugin install ccc-skills@ccc
+```
+
+## Quick Start
+
+After installing, just ask Claude Code:
+
+```
+"Generate an architecture diagram for this project"
+"Create an excalidraw diagram of the system"
+"Visualize this codebase as an excalidraw file"
+```
+
+Claude Code will analyze any codebase (Node.js, Python, Java, Go, etc.), identify components, map relationships, and generate a valid `.excalidraw` JSON file.
+
+## Features
+
+- **Any codebase**: Discovers services, databases, APIs, and infrastructure from source code
+- **No prerequisites**: Works without existing diagrams, Terraform, or specific file types
+- **Proper arrows**: 90-degree elbow arrows with correct edge binding (not curved)
+- **Color-coded**: Components styled by type (database, API, storage, AI/ML, etc.)
+- **Cloud palettes**: AWS, Azure, GCP, and Kubernetes color schemes
+- **Multiple layouts**: Vertical flow, horizontal pipeline, hub-and-spoke patterns
+- **PNG/SVG export**: Optionally export to PNG and/or SVG via Playwright
+
+## PNG/SVG Export
+
+After generating a diagram, Claude Code will ask if you want to export to PNG, SVG, or both.
+
+The export uses `@excalidraw/utils` loaded in a Playwright browser — fully programmatic, no manual upload to excalidraw.com needed.
+
+**Requirements:** Playwright MCP tools must be available.
+
+**Output:** Exported files are saved alongside the `.excalidraw` file:
+```
+docs/architecture/
+├── system-architecture.excalidraw    # Editable diagram
+├── system-architecture.svg           # Vector export
+└── system-architecture.png           # Raster export
+```
+
+## Output
+
+- **Location**: `docs/architecture/` or user-specified path
+- **Format**: `.excalidraw` JSON (editable in [excalidraw.com](https://excalidraw.com) or VS Code extension)
+- **Exports**: `.svg` and `.png` viewable directly or embeddable in documentation
+
+## Reference Files
+
+The skill includes detailed reference documentation:
+
+| File | Contents |
+|------|----------|
+| `references/json-format.md` | Element types, required properties, text bindings |
+| `references/arrows.md` | Routing algorithm, patterns, bindings, staggering |
+| `references/colors.md` | Default, AWS, Azure, GCP, K8s palettes |
+| `references/examples.md` | Complete JSON examples, layout patterns |
+| `references/validation.md` | Checklists, validation algorithm, bug fixes |
+| `references/export.md` | PNG/SVG export procedure via Playwright |
+
+## License
+
+MIT

package/skills/excalidraw/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: excalidraw
+description: Generate architecture diagrams as .excalidraw files from codebase analysis, with optional PNG/SVG export. Use when the user asks to create architecture diagrams, system diagrams, visualize codebase structure, generate excalidraw files, export excalidraw diagrams to PNG or SVG, or convert .excalidraw files to image formats.
+argument-hint: "[시각화할 대상 경로]"
+disable-model-invocation: false
+---
+
+# Excalidraw Diagram Generator
+
+Generate architecture diagrams as `.excalidraw` files directly from codebase analysis, with optional export to PNG and SVG.
+
+---
+
+## Quick Start
+
+**User just asks:**
+```
+"Generate an architecture diagram for this project"
+"Create an excalidraw diagram of the system"
+"Visualize this codebase as an excalidraw file"
+```
+
+**Claude Code will:**
+1. Analyze the codebase (any language/framework)
+2. Identify components, services, databases, APIs
+3. Map relationships and data flows
+4. Generate valid `.excalidraw` JSON with dynamic IDs and labels
+5. Optionally export to PNG and/or SVG using Playwright
+
+**No prerequisites:** Works without existing diagrams, Terraform, or specific file types.
+
+---
+
+## Critical Rules
+
+### 1. NEVER Use Diamond Shapes
+
+Diamond arrow connections are broken in raw Excalidraw JSON. Use styled rectangles instead:
+
+| Semantic Meaning | Rectangle Style |
+|------------------|-----------------|
+| Orchestrator/Hub | Coral (`#ffa8a8`/`#c92a2a`) + strokeWidth: 3 |
+| Decision Point | Orange (`#ffd8a8`/`#e8590c`) + dashed stroke |
+
+### 2. Labels Require TWO Elements
+
+The `label` property does NOT work in raw JSON. Every labeled shape needs:
+
+```json
+// 1. Shape with boundElements reference
+{
+  "id": "my-box",
+  "type": "rectangle",
+  "boundElements": [{ "type": "text", "id": "my-box-text" }]
+}
+
+// 2. Separate text element with containerId
+{
+  "id": "my-box-text",
+  "type": "text",
+  "containerId": "my-box",
+  "text": "My Label"
+}
+```
+
+### 3. Elbow Arrows Need Three Properties
+
+For 90-degree corners (not curved):
+
+```json
+{
+  "type": "arrow",
+  "roughness": 0,        // Clean lines
+  "roundness": null,     // Sharp corners
+  "elbowed": true        // 90-degree mode
+}
+```
+
+### 4. Arrow Edge Calculations
+
+Arrows must start/end at shape edges, not centers:
+
+| Edge | Formula |
+|------|---------|
+| Top | `(x + width/2, y)` |
+| Bottom | `(x + width/2, y + height)` |
+| Left | `(x, y + height/2)` |
+| Right | `(x + width, y + height/2)` |
+
+**Detailed arrow routing:** See `references/arrows.md`
+
+---
+
+## Element Types
+
+| Type | Use For |
+|------|---------|
+| `rectangle` | Services, databases, containers, orchestrators |
+| `ellipse` | Users, external systems, start/end points |
+| `text` | Labels inside shapes, titles, annotations |
+| `arrow` | Data flow, connections, dependencies |
+| `line` | Grouping boundaries, separators |
+
+**Full JSON format:** See `references/json-format.md`
+
+---
+
+## Workflow
+
+### Step 1: Analyze Codebase
+
+Discover components by looking for:
+
+| Codebase Type | What to Look For |
+|---------------|------------------|
+| Monorepo | `packages/*/package.json`, workspace configs |
+| Microservices | `docker-compose.yml`, k8s manifests |
+| IaC | Terraform/Pulumi resource definitions |
+| Backend API | Route definitions, controllers, DB models |
+| Frontend | Component hierarchy, API calls |
+
+**Use tools:**
+- `Glob` → `**/package.json`, `**/Dockerfile`, `**/*.tf`
+- `Grep` → `app.get`, `@Controller`, `CREATE TABLE`
+- `Read` → README, config files, entry points
+
+### Step 2: Plan Layout
+
+**Vertical flow (most common):**
+```
+Row 1: Users/Entry points (y: 100)
+Row 2: Frontend/Gateway (y: 230)
+Row 3: Orchestration (y: 380)
+Row 4: Services (y: 530)
+Row 5: Data layer (y: 680)
+
+Columns: x = 100, 300, 500, 700, 900
+Element size: 160-200px x 80-90px
+```
+
+**Other patterns:** See `references/examples.md`
+
+### Step 3: Generate Elements
+
+For each component:
+1. Create shape with unique `id`
+2. Add `boundElements` referencing text
+3. Create text with `containerId`
+4. Choose color based on type
+
+**Color palettes:** See `references/colors.md`
+
+### Step 4: Add Connections
+
+For each relationship:
+1. Calculate source edge point
+2. Plan elbow route (avoid overlaps)
+3. Create arrow with `points` array
+4. Match stroke color to destination type
+
+**Arrow patterns:** See `references/arrows.md`
+
+### Step 5: Add Grouping (Optional)
+
+For logical groupings:
+- Large transparent rectangle with `strokeStyle: "dashed"`
+- Standalone text label at top-left
+
+### Step 6: Validate and Write
+
+Run validation before writing. Save to `docs/` or user-specified path.
+
+**Validation checklist:** See `references/validation.md`
+
+### Step 7: Export to PNG/SVG (Optional)
+
+After writing the `.excalidraw` file, ask the user if they want PNG, SVG, or both exports.
+
+Uses Playwright MCP tools and `@excalidraw/utils` to programmatically render the diagram — no manual upload to excalidraw.com needed.
+
+**Requires:** Playwright MCP tools (`browser_navigate`, `browser_run_code`, `browser_close`).
+
+**Full export procedure:** See `references/export.md`
+
+---
+
+## Quick Arrow Reference
+
+**Straight down:**
+```json
+{ "points": [[0, 0], [0, 110]], "x": 590, "y": 290 }
+```
+
+**L-shape (left then down):**
+```json
+{ "points": [[0, 0], [-325, 0], [-325, 125]], "x": 525, "y": 420 }
+```
+
+**U-turn (callback):**
+```json
+{ "points": [[0, 0], [50, 0], [50, -125], [20, -125]], "x": 710, "y": 440 }
+```
+
+**Arrow width/height** = bounding box of points:
+```
+points [[0,0], [-440,0], [-440,70]] → width=440, height=70
+```
+
+**Multiple arrows from same edge** - stagger positions:
+```
+5 arrows: 20%, 35%, 50%, 65%, 80% across edge width
+```
+
+---
+
+## Default Color Palette
+
+| Component | Background | Stroke |
+|-----------|------------|--------|
+| Frontend | `#a5d8ff` | `#1971c2` |
+| Backend/API | `#d0bfff` | `#7048e8` |
+| Database | `#b2f2bb` | `#2f9e44` |
+| Storage | `#ffec99` | `#f08c00` |
+| AI/ML | `#e599f7` | `#9c36b5` |
+| External APIs | `#ffc9c9` | `#e03131` |
+| Orchestration | `#ffa8a8` | `#c92a2a` |
+| Message Queue | `#fff3bf` | `#fab005` |
+| Cache | `#ffe8cc` | `#fd7e14` |
+| Users | `#e7f5ff` | `#1971c2` |
+
+**Cloud-specific palettes:** See `references/colors.md`
+
+---
+
+## Quick Validation Checklist
+
+Before writing file:
+- [ ] Every shape with label has boundElements + text element
+- [ ] Text elements have containerId matching shape
+- [ ] Multi-point arrows have `elbowed: true`, `roundness: null`
+- [ ] Arrow x,y = source shape edge point
+- [ ] Arrow final point offset reaches target edge
+- [ ] No diamond shapes
+- [ ] No duplicate IDs
+
+**Full validation algorithm:** See `references/validation.md`
+
+---
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Labels don't appear | Use TWO elements (shape + text), not `label` property |
+| Arrows curved | Add `elbowed: true`, `roundness: null`, `roughness: 0` |
+| Arrows floating | Calculate x,y from shape edge, not center |
+| Arrows overlapping | Stagger start positions across edge |
+
+**Detailed bug fixes:** See `references/validation.md`
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/json-format.md` | Element types, required properties, text bindings |
+| `references/arrows.md` | Routing algorithm, patterns, bindings, staggering |
+| `references/colors.md` | Default, AWS, Azure, GCP, K8s palettes |
+| `references/examples.md` | Complete JSON examples, layout patterns |
+| `references/validation.md` | Checklists, validation algorithm, bug fixes |
+| `references/export.md` | PNG/SVG export procedure via Playwright |
+
+---
+
+## Output
+
+- **Location:** `docs/architecture/` or user-specified
+- **Filename:** Descriptive, e.g., `system-architecture.excalidraw`
+- **Exports (optional):** `system-architecture.svg` and/or `system-architecture.png` in same directory
+- **Testing:** Open `.excalidraw` in https://excalidraw.com or VS Code extension; `.svg` and `.png` can be viewed directly or embedded in documentation

package/skills/excalidraw/references/arrows.md

@@ -0,0 +1,288 @@
+# Arrow Routing Reference
+
+Complete guide for creating elbow arrows with proper connections.
+
+---
+
+## Critical: Elbow Arrow Properties
+
+Three required properties for 90-degree corners:
+
+```json
+{
+  "type": "arrow",
+  "roughness": 0,        // Clean lines
+  "roundness": null,     // Sharp corners (not curved)
+  "elbowed": true        // Enables elbow mode
+}
+```
+
+**Without these, arrows will be curved, not 90-degree elbows.**
+
+---
+
+## Edge Calculation Formulas
+
+| Shape Type | Edge | Formula |
+|------------|------|---------|
+| Rectangle | Top | `(x + width/2, y)` |
+| Rectangle | Bottom | `(x + width/2, y + height)` |
+| Rectangle | Left | `(x, y + height/2)` |
+| Rectangle | Right | `(x + width, y + height/2)` |
+| Ellipse | Top | `(x + width/2, y)` |
+| Ellipse | Bottom | `(x + width/2, y + height)` |
+
+---
+
+## Universal Arrow Routing Algorithm
+
+```
+FUNCTION createArrow(source, target, sourceEdge, targetEdge):
+  // Step 1: Get source edge point
+  sourcePoint = getEdgePoint(source, sourceEdge)
+
+  // Step 2: Get target edge point
+  targetPoint = getEdgePoint(target, targetEdge)
+
+  // Step 3: Calculate offsets
+  dx = targetPoint.x - sourcePoint.x
+  dy = targetPoint.y - sourcePoint.y
+
+  // Step 4: Determine routing pattern
+  IF sourceEdge == "bottom" AND targetEdge == "top":
+    IF abs(dx) < 10:  // Nearly aligned
+      points = [[0, 0], [0, dy]]
+    ELSE:  // Need L-shape
+      points = [[0, 0], [dx, 0], [dx, dy]]
+
+  ELSE IF sourceEdge == "right" AND targetEdge == "left":
+    IF abs(dy) < 10:
+      points = [[0, 0], [dx, 0]]
+    ELSE:
+      points = [[0, 0], [0, dy], [dx, dy]]
+
+  ELSE IF sourceEdge == targetEdge:  // U-turn
+    clearance = 50
+    IF sourceEdge == "right":
+      points = [[0, 0], [clearance, 0], [clearance, dy], [dx, dy]]
+    ELSE IF sourceEdge == "bottom":
+      points = [[0, 0], [0, clearance], [dx, clearance], [dx, dy]]
+
+  // Step 5: Calculate bounding box
+  width = max(abs(p[0]) for p in points)
+  height = max(abs(p[1]) for p in points)
+
+  RETURN {x: sourcePoint.x, y: sourcePoint.y, points, width, height}
+
+FUNCTION getEdgePoint(shape, edge):
+  SWITCH edge:
+    "top":    RETURN (shape.x + shape.width/2, shape.y)
+    "bottom": RETURN (shape.x + shape.width/2, shape.y + shape.height)
+    "left":   RETURN (shape.x, shape.y + shape.height/2)
+    "right":  RETURN (shape.x + shape.width, shape.y + shape.height/2)
+```
+
+---
+
+## Arrow Patterns Reference
+
+| Pattern | Points | Use Case |
+|---------|--------|----------|
+| Down | `[[0,0], [0,h]]` | Vertical connection |
+| Right | `[[0,0], [w,0]]` | Horizontal connection |
+| L-left-down | `[[0,0], [-w,0], [-w,h]]` | Go left, then down |
+| L-right-down | `[[0,0], [w,0], [w,h]]` | Go right, then down |
+| L-down-left | `[[0,0], [0,h], [-w,h]]` | Go down, then left |
+| L-down-right | `[[0,0], [0,h], [w,h]]` | Go down, then right |
+| S-shape | `[[0,0], [0,h1], [w,h1], [w,h2]]` | Navigate around obstacles |
+| U-turn | `[[0,0], [w,0], [w,-h], [0,-h]]` | Callback/return arrows |
+
+---
+
+## Worked Examples
+
+### Vertical Connection (Bottom to Top)
+
+```
+Source: x=500, y=200, width=180, height=90
+Target: x=500, y=400, width=180, height=90
+
+source_bottom = (500 + 180/2, 200 + 90) = (590, 290)
+target_top = (500 + 180/2, 400) = (590, 400)
+
+Arrow x = 590, y = 290
+Distance = 400 - 290 = 110
+Points = [[0, 0], [0, 110]]
+```
+
+### Fan-out (One to Many)
+
+```
+Orchestrator: x=570, y=400, width=140, height=80
+Target: x=120, y=550, width=160, height=80
+
+orchestrator_bottom = (570 + 140/2, 400 + 80) = (640, 480)
+target_top = (120 + 160/2, 550) = (200, 550)
+
+Arrow x = 640, y = 480
+Horizontal offset = 200 - 640 = -440
+Vertical offset = 550 - 480 = 70
+
+Points = [[0, 0], [-440, 0], [-440, 70]]  // Left first, then down
+```
+
+### U-turn (Callback)
+
+```
+Source: x=570, y=400, width=140, height=80
+Target: x=550, y=270, width=180, height=90
+Connection: Right of source -> Right of target
+
+source_right = (570 + 140, 400 + 80/2) = (710, 440)
+target_right = (550 + 180, 270 + 90/2) = (730, 315)
+
+Arrow x = 710, y = 440
+Vertical distance = 315 - 440 = -125
+Final x offset = 730 - 710 = 20
+
+Points = [[0, 0], [50, 0], [50, -125], [20, -125]]
+// Right 50px (clearance), up 125px, left 30px
+```
+
+---
+
+## Staggering Multiple Arrows
+
+When N arrows leave from same edge, spread evenly:
+
+```
+FUNCTION getStaggeredPositions(shape, edge, numArrows):
+  positions = []
+  FOR i FROM 0 TO numArrows-1:
+    percentage = 0.2 + (0.6 * i / (numArrows - 1))
+
+    IF edge == "bottom" OR edge == "top":
+      x = shape.x + shape.width * percentage
+      y = (edge == "bottom") ? shape.y + shape.height : shape.y
+    ELSE:
+      x = (edge == "right") ? shape.x + shape.width : shape.x
+      y = shape.y + shape.height * percentage
+
+    positions.append({x, y})
+  RETURN positions
+
+// Examples:
+// 2 arrows: 20%, 80%
+// 3 arrows: 20%, 50%, 80%
+// 5 arrows: 20%, 35%, 50%, 65%, 80%
+```
+
+---
+
+## Arrow Bindings
+
+For better visual attachment, use `startBinding` and `endBinding`:
+
+```json
+{
+  "id": "arrow-workflow-convert",
+  "type": "arrow",
+  "x": 525,
+  "y": 420,
+  "width": 325,
+  "height": 125,
+  "points": [[0, 0], [-325, 0], [-325, 125]],
+  "roughness": 0,
+  "roundness": null,
+  "elbowed": true,
+  "startBinding": {
+    "elementId": "cloud-workflows",
+    "focus": 0,
+    "gap": 1,
+    "fixedPoint": [0.5, 1]
+  },
+  "endBinding": {
+    "elementId": "convert-pdf-service",
+    "focus": 0,
+    "gap": 1,
+    "fixedPoint": [0.5, 0]
+  },
+  "startArrowhead": null,
+  "endArrowhead": "arrow"
+}
+```
+
+### fixedPoint Values
+
+- Top center: `[0.5, 0]`
+- Bottom center: `[0.5, 1]`
+- Left center: `[0, 0.5]`
+- Right center: `[1, 0.5]`
+
+### Update Shape boundElements
+
+```json
+{
+  "id": "cloud-workflows",
+  "boundElements": [
+    { "type": "text", "id": "cloud-workflows-text" },
+    { "type": "arrow", "id": "arrow-workflow-convert" }
+  ]
+}
+```
+
+---
+
+## Bidirectional Arrows
+
+For two-way data flows:
+
+```json
+{
+  "type": "arrow",
+  "startArrowhead": "arrow",
+  "endArrowhead": "arrow"
+}
+```
+
+Arrowhead options: `null`, `"arrow"`, `"bar"`, `"dot"`, `"triangle"`
+
+---
+
+## Arrow Labels
+
+Position standalone text near arrow midpoint:
+
+```json
+{
+  "id": "arrow-api-db-label",
+  "type": "text",
+  "x": 305,                        // Arrow x + offset
+  "y": 245,                        // Arrow midpoint
+  "text": "SQL",
+  "fontSize": 12,
+  "containerId": null,
+  "backgroundColor": "#ffffff"
+}
+```
+
+**Positioning formula:**
+- Vertical: `label.y = arrow.y + (total_height / 2)`
+- Horizontal: `label.x = arrow.x + (total_width / 2)`
+- L-shaped: Position at corner or longest segment midpoint
+
+---
+
+## Width/Height Calculation
+
+Arrow `width` and `height` = bounding box of path:
+
+```
+points = [[0, 0], [-440, 0], [-440, 70]]
+width = abs(-440) = 440
+height = abs(70) = 70
+
+points = [[0, 0], [50, 0], [50, -125], [20, -125]]
+width = max(abs(50), abs(20)) = 50
+height = abs(-125) = 125
+```