create-yss-spec 1.0.0

package/template/.pi/skills/excalidraw-diagram-generator/references/excalidraw-schema.md

@@ -0,0 +1,350 @@
+# Excalidraw JSON Schema Reference
+
+This document describes the structure of Excalidraw `.excalidraw` files for diagram generation.
+
+## Top-Level Structure
+
+```typescript
+interface ExcalidrawFile {
+  type: "excalidraw";
+  version: number;           // Always 2
+  source: string;            // "https://excalidraw.com"
+  elements: ExcalidrawElement[];
+  appState: AppState;
+  files: Record<string, any>; // Usually empty {}
+}
+```
+
+## AppState
+
+```typescript
+interface AppState {
+  viewBackgroundColor: string; // Hex color, e.g., "#ffffff"
+  gridSize: number;            // Typically 20
+}
+```
+
+## ExcalidrawElement Base Properties
+
+All elements share these common properties:
+
+```typescript
+interface BaseElement {
+  id: string;                  // Unique identifier
+  type: ElementType;           // See Element Types below
+  x: number;                   // X coordinate (pixels from top-left)
+  y: number;                   // Y coordinate (pixels from top-left)
+  width: number;               // Width in pixels
+  height: number;              // Height in pixels
+  angle: number;               // Rotation angle in radians (usually 0)
+  strokeColor: string;         // Hex color, e.g., "#1e1e1e"
+  backgroundColor: string;     // Hex color or "transparent"
+  fillStyle: "solid" | "hachure" | "cross-hatch";
+  strokeWidth: number;         // 1-4 typically
+  strokeStyle: "solid" | "dashed" | "dotted";
+  roughness: number;           // 0-2, controls hand-drawn effect (1 = default)
+  opacity: number;             // 0-100
+  groupIds: string[];          // IDs of groups this element belongs to
+  frameId: null;               // Usually null
+  index: string;               // Stacking order identifier
+  roundness: Roundness | null;
+  seed: number;                // Random seed for deterministic rendering
+  version: number;             // Element version (increment on edit)
+  versionNonce: number;        // Random number changed on edit
+  isDeleted: boolean;          // Should be false
+  boundElements: any;          // Usually null
+  updated: number;             // Timestamp in milliseconds
+  link: null;                  // External link (usually null)
+  locked: boolean;             // Whether element is locked
+}
+```
+
+## Element Types
+
+### Rectangle
+
+```typescript
+interface RectangleElement extends BaseElement {
+  type: "rectangle";
+  roundness: { type: 3 };      // 3 = rounded corners
+  text?: string;               // Optional text inside
+  fontSize?: number;           // Font size (16-32 typical)
+  fontFamily?: number;         // 1 = Virgil, 2 = Helvetica, 3 = Cascadia
+  textAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+}
+```
+
+**Example:**
+```json
+{
+  "id": "rect1",
+  "type": "rectangle",
+  "x": 100,
+  "y": 100,
+  "width": 200,
+  "height": 100,
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "#a5d8ff",
+  "text": "My Box",
+  "fontSize": 20,
+  "textAlign": "center",
+  "verticalAlign": "middle",
+  "roundness": { "type": 3 }
+}
+```
+
+### Ellipse
+
+```typescript
+interface EllipseElement extends BaseElement {
+  type: "ellipse";
+  text?: string;
+  fontSize?: number;
+  fontFamily?: number;
+  textAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+}
+```
+
+### Diamond
+
+```typescript
+interface DiamondElement extends BaseElement {
+  type: "diamond";
+  text?: string;
+  fontSize?: number;
+  fontFamily?: number;
+  textAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+}
+```
+
+### Arrow
+
+```typescript
+interface ArrowElement extends BaseElement {
+  type: "arrow";
+  points: [number, number][];  // Array of [x, y] coordinates relative to element
+  startBinding: Binding | null;
+  endBinding: Binding | null;
+  roundness: { type: 2 };      // 2 = curved arrow
+}
+```
+
+**Example:**
+```json
+{
+  "id": "arrow1",
+  "type": "arrow",
+  "x": 100,
+  "y": 100,
+  "width": 200,
+  "height": 0,
+  "points": [
+    [0, 0],
+    [200, 0]
+  ],
+  "roundness": { "type": 2 },
+  "startBinding": null,
+  "endBinding": null
+}
+```
+
+**Points explanation:**
+- First point `[0, 0]` is relative to `(x, y)`
+- Subsequent points are relative to the first point
+- For straight horizontal arrow: `[[0, 0], [width, 0]]`
+- For straight vertical arrow: `[[0, 0], [0, height]]`
+
+### Line
+
+```typescript
+interface LineElement extends BaseElement {
+  type: "line";
+  points: [number, number][];
+  startBinding: Binding | null;
+  endBinding: Binding | null;
+  roundness: { type: 2 } | null;
+}
+```
+
+### Text
+
+```typescript
+interface TextElement extends BaseElement {
+  type: "text";
+  text: string;
+  fontSize: number;
+  fontFamily: number;          // 1-3
+  textAlign: "left" | "center" | "right";
+  verticalAlign: "top" | "middle" | "bottom";
+  roundness: null;             // Text has no roundness
+}
+```
+
+**Example:**
+```json
+{
+  "id": "text1",
+  "type": "text",
+  "x": 100,
+  "y": 100,
+  "width": 150,
+  "height": 25,
+  "text": "Hello World",
+  "fontSize": 20,
+  "fontFamily": 1,
+  "textAlign": "left",
+  "verticalAlign": "top",
+  "roundness": null
+}
+```
+
+**Width/Height calculation:**
+- Width ≈ `text.length * fontSize * 0.6`
+- Height ≈ `fontSize * 1.2 * numberOfLines`
+
+## Bindings
+
+Bindings connect arrows to shapes:
+
+```typescript
+interface Binding {
+  elementId: string;           // ID of bound element
+  focus: number;               // -1 to 1, position along edge
+  gap: number;                 // Distance from element edge
+}
+```
+
+## Common Colors
+
+| Color Name | Hex Code | Use Case |
+|------------|----------|----------|
+| Black | `#1e1e1e` | Default stroke |
+| Light Blue | `#a5d8ff` | Primary entities |
+| Light Green | `#b2f2bb` | Process steps |
+| Yellow | `#ffd43b` | Important/Central |
+| Light Red | `#ffc9c9` | Warnings/Errors |
+| Cyan | `#96f2d7` | Secondary items |
+| Transparent | `transparent` | No fill |
+| White | `#ffffff` | Background |
+
+## ID Generation
+
+IDs should be unique strings. Common patterns:
+
+```javascript
+// Timestamp-based
+const id = Date.now().toString(36) + Math.random().toString(36).substr(2);
+
+// Sequential
+const id = "element-" + counter++;
+
+// Descriptive
+const id = "step-1", "entity-user", "arrow-1-to-2";
+```
+
+## Seed Generation
+
+Seeds are used for deterministic randomness in hand-drawn effect:
+
+```javascript
+const seed = Math.floor(Math.random() * 2147483647);
+```
+
+## Version and VersionNonce
+
+```javascript
+const version = 1;  // Increment when element is edited
+const versionNonce = Math.floor(Math.random() * 2147483647);
+```
+
+## Coordinate System
+
+- Origin `(0, 0)` is top-left corner
+- X increases to the right
+- Y increases downward
+- All units are in pixels
+
+## Recommended Spacing
+
+| Context | Spacing |
+|---------|---------|
+| Horizontal gap between elements | 200-300px |
+| Vertical gap between rows | 100-150px |
+| Minimum margin from edge | 50px |
+| Arrow-to-box clearance | 20-30px |
+
+## Font Families
+
+| ID | Name | Description |
+|----|------|-------------|
+| 1 | Virgil | Hand-drawn style (default) |
+| 2 | Helvetica | Clean sans-serif |
+| 3 | Cascadia | Monospace |
+
+## Validation Rules
+
+✅ **Required:**
+- All IDs must be unique
+- `type` must match actual element type
+- `version` must be an integer ≥ 1
+- `opacity` must be 0-100
+
+⚠️ **Recommended:**
+- Keep `roughness` at 1 for consistency
+- Use `strokeWidth` of 2 for clarity
+- Set `isDeleted` to `false`
+- Set `locked` to `false`
+- Keep `frameId`, `boundElements`, `link` as `null`
+
+## Complete Minimal Example
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [
+    {
+      "id": "box1",
+      "type": "rectangle",
+      "x": 100,
+      "y": 100,
+      "width": 200,
+      "height": 100,
+      "angle": 0,
+      "strokeColor": "#1e1e1e",
+      "backgroundColor": "#a5d8ff",
+      "fillStyle": "solid",
+      "strokeWidth": 2,
+      "strokeStyle": "solid",
+      "roughness": 1,
+      "opacity": 100,
+      "groupIds": [],
+      "frameId": null,
+      "index": "a0",
+      "roundness": { "type": 3 },
+      "seed": 1234567890,
+      "version": 1,
+      "versionNonce": 987654321,
+      "isDeleted": false,
+      "boundElements": null,
+      "updated": 1706659200000,
+      "link": null,
+      "locked": false,
+      "text": "Hello",
+      "fontSize": 20,
+      "fontFamily": 1,
+      "textAlign": "center",
+      "verticalAlign": "middle"
+    }
+  ],
+  "appState": {
+    "viewBackgroundColor": "#ffffff",
+    "gridSize": 20
+  },
+  "files": {}
+}
+```

package/template/.pi/skills/excalidraw-diagram-generator/scripts/README.md

@@ -0,0 +1,193 @@
+# Excalidraw Library Tools
+
+This directory contains scripts for working with Excalidraw libraries.
+
+## split-excalidraw-library.py
+
+Splits an Excalidraw library file (`*.excalidrawlib`) into individual icon JSON files for efficient token usage by AI assistants.
+
+### Prerequisites
+
+- Python 3.6 or higher
+- No additional dependencies required (uses only standard library)
+
+### Usage
+
+```bash
+python split-excalidraw-library.py <path-to-library-directory>
+```
+
+### Step-by-Step Workflow
+
+1. **Create library directory**:
+   ```bash
+   mkdir -p skills/excalidraw-diagram-generator/libraries/aws-architecture-icons
+   ```
+
+2. **Download and place library file**:
+   - Visit: https://libraries.excalidraw.com/
+   - Search for "AWS Architecture Icons" and download the `.excalidrawlib` file
+   - Rename it to match the directory name: `aws-architecture-icons.excalidrawlib`
+   - Place it in the directory created in step 1
+
+3. **Run the script**:
+   ```bash
+   python skills/excalidraw-diagram-generator/scripts/split-excalidraw-library.py skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
+   ```
+
+### Output Structure
+
+The script creates the following structure in the library directory:
+
+```
+skills/excalidraw-diagram-generator/libraries/aws-architecture-icons/
+  aws-architecture-icons.excalidrawlib  # Original file (kept)
+  reference.md                          # Generated: Quick reference table
+  icons/                                # Generated: Individual icon files
+    API-Gateway.json
+    CloudFront.json
+    EC2.json
+    S3.json
+    ...
+```
+
+### What the Script Does
+
+1. **Reads** the `.excalidrawlib` file
+2. **Extracts** each icon from the `libraryItems` array
+3. **Sanitizes** icon names to create valid filenames (spaces → hyphens, removes special characters)
+4. **Saves** each icon as a separate JSON file in the `icons/` directory
+5. **Generates** a `reference.md` file with a table mapping icon names to filenames
+
+### Benefits
+
+- **Token Efficiency**: AI can first read the lightweight `reference.md` to find relevant icons, then load only the specific icon files needed
+- **Organization**: Icons are organized in a clear directory structure
+- **Extensibility**: Users can add multiple library sets side-by-side
+
+### Recommended Workflow
+
+1. Download desired Excalidraw libraries from https://libraries.excalidraw.com/
+2. Run this script on each library file
+3. Move the generated folders to `../libraries/`
+4. The AI assistant will use `reference.md` files to locate and use icons efficiently
+
+### Library Sources (Examples — verify availability)
+
+- Examples found on https://libraries.excalidraw.com/ may include cloud/service icon sets.
+- Availability changes over time; verify the exact library names on the site before use.
+- This script works with any valid `.excalidrawlib` file you provide.
+
+### Troubleshooting
+
+**Error: File not found**
+- Check that the file path is correct
+- Make sure the file has a `.excalidrawlib` extension
+
+**Error: Invalid library file format**
+- Ensure the file is a valid Excalidraw library file
+- Check that it contains a `libraryItems` array
+
+### License Considerations
+
+When using third-party icon libraries:
+- **AWS Architecture Icons**: Subject to AWS Content License
+- **GCP Icons**: Subject to Google's terms
+- **Other libraries**: Check each library's license
+
+This script is for personal/organizational use. Redistribution of split icon files should comply with the original library's license terms.
+
+## add-icon-to-diagram.py
+
+Adds a specific icon from a split Excalidraw library into an existing `.excalidraw` diagram. The script handles coordinate translation and ID collision avoidance, and can optionally add a label under the icon.
+
+### Prerequisites
+
+- Python 3.6 or higher
+- A diagram file (`.excalidraw`)
+- A split icon library directory (created by `split-excalidraw-library.py`)
+
+### Usage
+
+```bash
+python add-icon-to-diagram.py <diagram-path> <icon-name> <x> <y> [OPTIONS]
+```
+
+**Options**
+- `--library-path PATH` : Path to the icon library directory (default: `aws-architecture-icons`)
+- `--label TEXT` : Add a text label below the icon
+-- `--use-edit-suffix` : Edit via `.excalidraw.edit` to avoid editor overwrite issues (enabled by default; pass `--no-use-edit-suffix` to disable)
+
+### Examples
+
+```bash
+# Add EC2 icon at position (400, 300)
+python add-icon-to-diagram.py diagram.excalidraw EC2 400 300
+
+# Add VPC icon with label
+python add-icon-to-diagram.py diagram.excalidraw VPC 200 150 --label "VPC"
+
+# Safe edit mode is enabled by default (avoids editor overwrite issues)
+# Use `--no-use-edit-suffix` to disable
+python add-icon-to-diagram.py diagram.excalidraw EC2 500 300
+
+# Add icon from another library
+python add-icon-to-diagram.py diagram.excalidraw Compute-Engine 500 200 \
+   --library-path libraries/gcp-icons --label "API Server"
+```
+
+### What the Script Does
+
+1. **Loads** the icon JSON from the library’s `icons/` directory
+2. **Calculates** the icon’s bounding box
+3. **Offsets** all coordinates to the target position
+4. **Generates** unique IDs for all elements and groups
+5. **Appends** the transformed elements to the diagram
+6. **(Optional)** Adds a label beneath the icon
+
+---
+
+## add-arrow.py
+
+Adds a straight arrow between two points in an existing `.excalidraw` diagram. Supports optional labels and line styles.
+
+### Prerequisites
+
+- Python 3.6 or higher
+- A diagram file (`.excalidraw`)
+
+### Usage
+
+```bash
+python add-arrow.py <diagram-path> <from-x> <from-y> <to-x> <to-y> [OPTIONS]
+```
+
+**Options**
+- `--style {solid|dashed|dotted}` : Line style (default: `solid`)
+- `--color HEX` : Arrow color (default: `#1e1e1e`)
+- `--label TEXT` : Add a text label on the arrow
+-- `--use-edit-suffix` : Edit via `.excalidraw.edit` to avoid editor overwrite issues (enabled by default; pass `--no-use-edit-suffix` to disable)
+
+### Examples
+
+```bash
+# Simple arrow
+python add-arrow.py diagram.excalidraw 300 200 500 300
+
+# Arrow with label
+python add-arrow.py diagram.excalidraw 300 200 500 300 --label "HTTPS"
+
+# Dashed arrow with custom color
+python add-arrow.py diagram.excalidraw 400 350 600 400 --style dashed --color "#7950f2"
+
+# Safe edit mode is enabled by default (avoids editor overwrite issues)
+# Use `--no-use-edit-suffix` to disable
+python add-arrow.py diagram.excalidraw 300 200 500 300
+```
+
+### What the Script Does
+
+1. **Creates** an arrow element from the given coordinates
+2. **(Optional)** Adds a label near the arrow midpoint
+3. **Appends** elements to the diagram
+4. **Saves** the updated file