create-yss-spec 2.1.5 → 2.1.7

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

@@ -1,350 +0,0 @@
-# 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

@@ -1,193 +0,0 @@
-# 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

package/template/.pi/skills/excalidraw-diagram-generator/scripts/__yss_dotfile__.gitignore

@@ -1,34 +0,0 @@
-# Avoid accidentally committing local Python artifacts produced when running these scripts.
-
-# Byte-compiled / cache files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# Virtual environments (people often create these next to scripts)
-.venv/
-venv/
-env/
-ENV/
-
-# Tool caches
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-.tox/
-.nox/
-
-# Coverage outputs
-.coverage
-.coverage.*
-htmlcov/
-
-# Packaging/build outputs (rare here, but harmless)
-build/
-dist/
-*.egg-info/
-.eggs/
-
-# OS cruft
-.DS_Store
-Thumbs.db