plcode-linux-arm64-musl 2.1.0

package/.plcode/skill/experimental/domain-driven-design/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: domain-driven-design
+description: "Plan and route Domain-Driven Design work from strategic modeling to tactical implementation and evented architecture patterns."
+category: backend
+risk: safe
+source: self
+tags: "[ddd, domain, bounded-context, architecture]"
+date_added: "2026-02-27"
+---
+
+# Domain-Driven Design
+
+## Use this skill when
+
+- You need to model a complex business domain with explicit boundaries.
+- You want to decide whether full DDD is worth the added complexity.
+- You need to connect strategic design decisions to implementation patterns.
+- You are planning CQRS, event sourcing, sagas, or projections from domain needs.
+
+## Do not use this skill when
+
+- The problem is simple CRUD with low business complexity.
+- You only need localized bug fixes.
+- There is no access to domain knowledge and no proxy product expert.
+
+## Instructions
+
+1. Run a viability check before committing to full DDD.
+2. Produce strategic artifacts first: subdomains, bounded contexts, language glossary.
+3. Route to specialized skills based on current task.
+4. Define success criteria and evidence for each stage.
+
+### Viability check
+
+Use full DDD only when at least two of these are true:
+
+- Business rules are complex or fast-changing.
+- Multiple teams are causing model collisions.
+- Integration contracts are unstable.
+- Auditability and explicit invariants are critical.
+
+### Routing map
+
+- Strategic model and boundaries: `@ddd-strategic-design`
+- Cross-context integrations and translation: `@ddd-context-mapping`
+- Tactical code modeling: `@ddd-tactical-patterns`
+- Read/write separation: `@cqrs-implementation`
+- Event history as source of truth: `@event-sourcing-architect` and `@event-store-design`
+- Long-running workflows: `@saga-orchestration`
+- Read models: `@projection-patterns`
+- Decision log: `@architecture-decision-records`
+
+If templates are needed, open `references/ddd-deliverables.md`.
+
+## Output requirements
+
+Always return:
+
+- Scope and assumptions
+- Current stage (strategic, tactical, or evented)
+- Explicit artifacts produced
+- Open risks and next step recommendation
+
+## Examples
+
+```text
+Use @domain-driven-design to assess if this billing platform should adopt full DDD.
+Then route to the right next skill and list artifacts we must produce this week.
+```
+
+## Limitations
+
+- This skill does not replace direct workshops with domain experts.
+- It does not provide framework-specific code generation.
+- It should not be used as a justification to over-engineer simple systems.

package/.plcode/skill/experimental/domain-driven-design/references/ddd-deliverables.md

@@ -0,0 +1,24 @@
+# DDD Deliverables Checklist
+
+Use this checklist to keep DDD adoption practical and measurable.
+
+## Strategic deliverables
+
+- Subdomain map (core, supporting, generic)
+- Bounded context map and ownership
+- Ubiquitous language glossary
+- 1-2 ADRs documenting critical boundary decisions
+
+## Tactical deliverables
+
+- Aggregate list with invariants
+- Value object list
+- Domain events list
+- Repository contracts and transaction boundaries
+
+## Evented deliverables (only when required)
+
+- Command and query separation rationale
+- Event schema versioning policy
+- Saga compensation matrix
+- Projection rebuild strategy

package/.plcode/skill/experimental/excalidraw/SKILL.md

@@ -0,0 +1,537 @@
+---
+name: excalidraw
+description: "Create hand-drawn style Excalidraw JSON diagrams — architecture diagrams, flowcharts, sequence diagrams, concept maps, entity-relationship diagrams. Produces .excalidraw files that open at excalidraw.com or in VS Code with the Excalidraw extension. Use when the user says 'draw a diagram', 'excalidraw this', 'flowchart for X', 'architecture diagram', 'sequence diagram', 'concept map', 'ER diagram', or 'visualize this flow'. No rendering libraries, no API keys — just JSON."
+category: design
+---
+
+# Excalidraw Diagram Skill
+
+Create diagrams by writing standard Excalidraw element JSON and saving as `.excalidraw` files. These files can be drag-and-dropped onto [excalidraw.com](https://excalidraw.com) for viewing and editing, or opened directly in VS Code with the Excalidraw extension. No accounts, no API keys, no rendering libraries — just JSON.
+
+## When to Use
+
+- "Draw a diagram of this system"
+- "Excalidraw this architecture"
+- "Flowchart for our auth flow"
+- "Sequence diagram for the API calls"
+- "Concept map of our domain model"
+- "ER diagram for the database"
+- "Visualize this flow"
+- Any time the user wants a quick, editable, hand-drawn-style diagram
+
+## When NOT to Use
+
+- User wants a **polished dark-themed SVG architecture diagram** — use `architecture-diagram`
+- User wants a **production React component** — build it properly
+- User wants **interactive HTML mockups** — use `sketch`
+- User wants **presentation slides** — use `document-pptx`
+
+## Workflow
+
+1. **User describes** what they want diagrammed
+2. **Plan the layout** — identify nodes, groups, connections, and flow direction
+3. **Write the elements JSON** — an array of Excalidraw element objects
+4. **Save the file** using `write_file` to create a `.excalidraw` file
+5. **Tell the user** how to view it
+
+### Saving a Diagram
+
+Wrap your elements array in the standard `.excalidraw` envelope:
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "plcode",
+  "elements": [ ...your elements array here... ],
+  "appState": {
+    "viewBackgroundColor": "#ffffff"
+  }
+}
+```
+
+Save to a descriptive path in the project, e.g.:
+
+```
+./diagrams/auth-flow.excalidraw
+./diagrams/system-architecture.excalidraw
+```
+
+### Viewing the Diagram
+
+Tell the user their options:
+
+- **excalidraw.com** — drag-and-drop the file onto the page
+- **VS Code** — install the "Excalidraw" extension, then open the file directly
+- **Share** — upload to excalidraw.com for a shareable link (no account needed)
+
+---
+
+## Element Format Reference
+
+### Required Fields (all elements)
+
+`type`, `id` (unique string), `x`, `y`, `width`, `height`
+
+### Defaults (skip these — they're applied automatically)
+
+- `strokeColor`: `"#1e1e1e"`
+- `backgroundColor`: `"transparent"`
+- `fillStyle`: `"solid"`
+- `strokeWidth`: `2`
+- `roughness`: `1` (hand-drawn look)
+- `opacity`: `100`
+
+Canvas background is white.
+
+### Element Types
+
+**Rectangle:**
+
+```json
+{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 100 }
+```
+
+- `roundness: { "type": 3 }` for rounded corners
+- `backgroundColor: "#a5d8ff"`, `fillStyle: "solid"` for filled
+
+**Ellipse:**
+
+```json
+{ "type": "ellipse", "id": "e1", "x": 100, "y": 100, "width": 150, "height": 150 }
+```
+
+**Diamond:**
+
+```json
+{ "type": "diamond", "id": "d1", "x": 100, "y": 100, "width": 150, "height": 150 }
+```
+
+**Labeled shape (container binding)** — create a text element bound to the shape:
+
+> **WARNING:** Do NOT use `"label": { "text": "..." }` on shapes. This is NOT a valid
+> Excalidraw property and will be silently ignored, producing blank shapes. You MUST
+> use the container binding approach below.
+
+The shape needs `boundElements` listing the text, and the text needs `containerId` pointing back:
+
+```json
+{ "type": "rectangle", "id": "r1", "x": 100, "y": 100, "width": 200, "height": 80,
+  "roundness": { "type": 3 }, "backgroundColor": "#a5d8ff", "fillStyle": "solid",
+  "boundElements": [{ "id": "t_r1", "type": "text" }] },
+{ "type": "text", "id": "t_r1", "x": 105, "y": 110, "width": 190, "height": 25,
+  "text": "Hello", "fontSize": 20, "fontFamily": 1, "strokeColor": "#1e1e1e",
+  "textAlign": "center", "verticalAlign": "middle",
+  "containerId": "r1", "originalText": "Hello", "autoResize": true }
+```
+
+- Works on rectangle, ellipse, diamond
+- Text is auto-centered by Excalidraw when `containerId` is set
+- The text `x`/`y`/`width`/`height` are approximate — Excalidraw recalculates them on load
+- `originalText` should match `text`
+- Always include `fontFamily: 1` (Virgil/hand-drawn font)
+
+**Labeled arrow** — same container binding approach:
+
+```json
+{ "type": "arrow", "id": "a1", "x": 300, "y": 150, "width": 200, "height": 0,
+  "points": [[0,0],[200,0]], "endArrowhead": "arrow",
+  "boundElements": [{ "id": "t_a1", "type": "text" }] },
+{ "type": "text", "id": "t_a1", "x": 370, "y": 130, "width": 60, "height": 20,
+  "text": "connects", "fontSize": 16, "fontFamily": 1, "strokeColor": "#1e1e1e",
+  "textAlign": "center", "verticalAlign": "middle",
+  "containerId": "a1", "originalText": "connects", "autoResize": true }
+```
+
+**Standalone text** (titles and annotations only — no container):
+
+```json
+{
+  "type": "text",
+  "id": "t1",
+  "x": 150,
+  "y": 138,
+  "text": "Hello",
+  "fontSize": 20,
+  "fontFamily": 1,
+  "strokeColor": "#1e1e1e",
+  "originalText": "Hello",
+  "autoResize": true
+}
+```
+
+- `x` is the LEFT edge. To center at position `cx`: `x = cx - (text.length * fontSize * 0.5) / 2`
+- Do NOT rely on `textAlign` or `width` for positioning standalone text
+
+**Arrow:**
+
+```json
+{
+  "type": "arrow",
+  "id": "a1",
+  "x": 300,
+  "y": 150,
+  "width": 200,
+  "height": 0,
+  "points": [
+    [0, 0],
+    [200, 0]
+  ],
+  "endArrowhead": "arrow"
+}
+```
+
+- `points`: `[dx, dy]` offsets from element `x`, `y`
+- `endArrowhead`: `null` | `"arrow"` | `"bar"` | `"dot"` | `"triangle"`
+- `strokeStyle`: `"solid"` (default) | `"dashed"` | `"dotted"`
+
+**Line** (no arrowheads):
+
+```json
+{
+  "type": "line",
+  "id": "l1",
+  "x": 100,
+  "y": 200,
+  "width": 300,
+  "height": 0,
+  "points": [
+    [0, 0],
+    [300, 0]
+  ]
+}
+```
+
+### Arrow Bindings (connect arrows to shapes)
+
+```json
+{
+  "type": "arrow",
+  "id": "a1",
+  "x": 300,
+  "y": 150,
+  "width": 150,
+  "height": 0,
+  "points": [
+    [0, 0],
+    [150, 0]
+  ],
+  "endArrowhead": "arrow",
+  "startBinding": { "elementId": "r1", "fixedPoint": [1, 0.5] },
+  "endBinding": { "elementId": "r2", "fixedPoint": [0, 0.5] }
+}
+```
+
+`fixedPoint` coordinates: `top=[0.5,0]`, `bottom=[0.5,1]`, `left=[0,0.5]`, `right=[1,0.5]`
+
+Also add the arrow to each shape's `boundElements`:
+
+```json
+{ "type": "rectangle", "id": "r1", ...,
+  "boundElements": [{ "id": "t_r1", "type": "text" }, { "id": "a1", "type": "arrow" }] }
+```
+
+### Drawing Order (z-order)
+
+- Array order = z-order (first = back, last = front)
+- Emit progressively: background zones → shape → its bound text → its arrows → next shape
+- BAD: all rectangles, then all texts, then all arrows
+- GOOD: bg_zone → shape1 → text_for_shape1 → arrow1 → arrow_label_text → shape2 → text_for_shape2 → ...
+- Always place the bound text element immediately after its container shape
+
+### Sizing Guidelines
+
+**Font sizes:**
+
+- Minimum `fontSize`: **16** for body text, labels, descriptions
+- Minimum `fontSize`: **20** for titles and headings
+- Minimum `fontSize`: **14** for secondary annotations only (sparingly)
+- NEVER use `fontSize` below 14
+
+**Element sizes:**
+
+- Minimum shape size: 120x60 for labeled rectangles/ellipses
+- Leave 20-30px gaps between elements minimum
+- Prefer fewer, larger elements over many tiny ones
+
+### Color Palette
+
+Use these fill colors consistently across diagrams. All use `fillStyle: "solid"`.
+
+| Use                       | Fill Color   | Hex       |
+| ------------------------- | ------------ | --------- |
+| Primary / Input           | Light Blue   | `#a5d8ff` |
+| Success / Output          | Light Green  | `#b2f2bb` |
+| Warning / External        | Light Orange | `#ffd8a8` |
+| Processing / Special      | Light Purple | `#d0bfff` |
+| Error / Critical          | Light Red    | `#ffc9c9` |
+| Notes / Decisions         | Light Yellow | `#fff3bf` |
+| Storage / Data            | Light Teal   | `#c3fae8` |
+| Infrastructure / Platform | Light Gray   | `#e9ecef` |
+
+#### PLCODE Stack Color Mapping
+
+When diagramming a PLCODE/Next.js project specifically:
+
+| Component Type     | Fill Color   | Hex       |
+| ------------------ | ------------ | --------- |
+| React / Frontend   | Light Blue   | `#a5d8ff` |
+| Next.js API Routes | Light Green  | `#b2f2bb` |
+| Database / Prisma  | Light Purple | `#d0bfff` |
+| External APIs      | Light Orange | `#ffd8a8` |
+| Auth / Security    | Light Red    | `#ffc9c9` |
+| Message Queue      | Light Yellow | `#fff3bf` |
+| Storage / CDN      | Light Teal   | `#c3fae8` |
+| Bun Runtime        | Light Gray   | `#e9ecef` |
+
+### Grouping with Background Zones
+
+Use large, semi-transparent rectangles behind groups of related elements:
+
+```json
+{ "type": "rectangle", "id": "zone1", "x": 80, "y": 70, "width": 460, "height": 250,
+  "backgroundColor": "#f8f9fa", "fillStyle": "solid", "strokeColor": "#dee2e6",
+  "strokeWidth": 1, "roughness": 0, "opacity": 50,
+  "boundElements": [{ "id": "t_zone1", "type": "text" }] },
+{ "type": "text", "id": "t_zone1", "x": 85, "y": 75, "width": 100, "height": 20,
+  "text": "Frontend Layer", "fontSize": 14, "fontFamily": 1, "strokeColor": "#868e96",
+  "containerId": "zone1", "originalText": "Frontend Layer", "autoResize": true,
+  "textAlign": "left", "verticalAlign": "top" }
+```
+
+- Place zones FIRST in the elements array (behind everything)
+- Use `roughness: 0` for clean zone borders
+- Use `opacity: 50` so shapes inside are visible
+
+---
+
+## Diagram Patterns
+
+### Architecture Diagram
+
+Layout: top-to-bottom layers (Client → Frontend → Backend → Data)
+
+```
+[Client/Browser]
+       ↓
+[Next.js App]  [CDN/Static]
+       ↓
+[API Routes]  [Auth Service]
+       ↓           ↓
+[Database]    [Cache]    [Storage]
+```
+
+- Use background zones for each layer
+- Horizontal spacing: 250px between nodes in a row
+- Vertical spacing: 150px between layers
+- Connect with arrows using bindings
+
+### Flowchart
+
+Layout: top-to-bottom or left-to-right decision flow
+
+- Rectangles for process steps
+- Diamonds for decisions (Yes/No branches)
+- Rounded rectangles for start/end
+- Label arrows with "Yes" / "No" / condition text
+
+### Sequence Diagram
+
+Layout: participants across the top, time flows downward
+
+- Rectangles at the top for each participant/service
+- Vertical dashed lines below each participant (use `line` elements with `strokeStyle: "dashed"`)
+- Horizontal arrows between lifelines for messages
+- Label each arrow with the message/API call name
+- Stagger arrows vertically with 60px spacing
+
+### Concept Map / ER Diagram
+
+Layout: central concept with radiating connections
+
+- Rectangles for entities/concepts
+- Labeled arrows for relationships
+- Use color to distinguish entity types
+- Diamond shapes for relationship labels in ER diagrams
+
+---
+
+## Complete Example: Simple Architecture
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "plcode",
+  "elements": [
+    {
+      "type": "rectangle",
+      "id": "zone_fe",
+      "x": 50,
+      "y": 50,
+      "width": 500,
+      "height": 120,
+      "backgroundColor": "#f8f9fa",
+      "fillStyle": "solid",
+      "strokeColor": "#dee2e6",
+      "strokeWidth": 1,
+      "roughness": 0,
+      "opacity": 50
+    },
+    {
+      "type": "rectangle",
+      "id": "r_client",
+      "x": 80,
+      "y": 80,
+      "width": 180,
+      "height": 60,
+      "roundness": { "type": 3 },
+      "backgroundColor": "#a5d8ff",
+      "fillStyle": "solid",
+      "boundElements": [
+        { "id": "t_client", "type": "text" },
+        { "id": "a1", "type": "arrow" }
+      ]
+    },
+    {
+      "type": "text",
+      "id": "t_client",
+      "x": 85,
+      "y": 90,
+      "width": 170,
+      "height": 25,
+      "text": "React Frontend",
+      "fontSize": 20,
+      "fontFamily": 1,
+      "strokeColor": "#1e1e1e",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": "r_client",
+      "originalText": "React Frontend",
+      "autoResize": true
+    },
+    {
+      "type": "rectangle",
+      "id": "r_api",
+      "x": 80,
+      "y": 240,
+      "width": 180,
+      "height": 60,
+      "roundness": { "type": 3 },
+      "backgroundColor": "#b2f2bb",
+      "fillStyle": "solid",
+      "boundElements": [
+        { "id": "t_api", "type": "text" },
+        { "id": "a1", "type": "arrow" },
+        { "id": "a2", "type": "arrow" }
+      ]
+    },
+    {
+      "type": "text",
+      "id": "t_api",
+      "x": 85,
+      "y": 250,
+      "width": 170,
+      "height": 25,
+      "text": "API Routes",
+      "fontSize": 20,
+      "fontFamily": 1,
+      "strokeColor": "#1e1e1e",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": "r_api",
+      "originalText": "API Routes",
+      "autoResize": true
+    },
+    {
+      "type": "arrow",
+      "id": "a1",
+      "x": 170,
+      "y": 140,
+      "width": 0,
+      "height": 100,
+      "points": [
+        [0, 0],
+        [0, 100]
+      ],
+      "endArrowhead": "arrow",
+      "startBinding": { "elementId": "r_client", "fixedPoint": [0.5, 1] },
+      "endBinding": { "elementId": "r_api", "fixedPoint": [0.5, 0] }
+    },
+    {
+      "type": "rectangle",
+      "id": "r_db",
+      "x": 80,
+      "y": 400,
+      "width": 180,
+      "height": 60,
+      "roundness": { "type": 3 },
+      "backgroundColor": "#d0bfff",
+      "fillStyle": "solid",
+      "boundElements": [
+        { "id": "t_db", "type": "text" },
+        { "id": "a2", "type": "arrow" }
+      ]
+    },
+    {
+      "type": "text",
+      "id": "t_db",
+      "x": 85,
+      "y": 410,
+      "width": 170,
+      "height": 25,
+      "text": "PostgreSQL",
+      "fontSize": 20,
+      "fontFamily": 1,
+      "strokeColor": "#1e1e1e",
+      "textAlign": "center",
+      "verticalAlign": "middle",
+      "containerId": "r_db",
+      "originalText": "PostgreSQL",
+      "autoResize": true
+    },
+    {
+      "type": "arrow",
+      "id": "a2",
+      "x": 170,
+      "y": 300,
+      "width": 0,
+      "height": 100,
+      "points": [
+        [0, 0],
+        [0, 100]
+      ],
+      "endArrowhead": "arrow",
+      "startBinding": { "elementId": "r_api", "fixedPoint": [0.5, 1] },
+      "endBinding": { "elementId": "r_db", "fixedPoint": [0.5, 0] }
+    }
+  ],
+  "appState": {
+    "viewBackgroundColor": "#ffffff"
+  }
+}
+```
+
+## Checklist Before Saving
+
+- [ ] Every labeled shape uses container binding (`boundElements` + `containerId`), NOT `label: {}`
+- [ ] Every text element has `fontFamily: 1`, `originalText` matching `text`, and `autoResize: true`
+- [ ] Bound text appears immediately after its container in the array
+- [ ] Background zones are first in the array
+- [ ] Arrow bindings reference valid element IDs
+- [ ] Shapes referenced by arrows include the arrow in their `boundElements`
+- [ ] No `fontSize` below 14
+- [ ] No emoji in text (Excalidraw's font doesn't render them)
+- [ ] Color palette is used consistently
+- [ ] File extension is `.excalidraw`
+- [ ] JSON is wrapped in the standard envelope with `"type": "excalidraw"` and `"version": 2`
+- [ ] File saved to `diagrams/` directory with a descriptive name
+
+## Tips
+
+- Use the color palette consistently across the diagram
+- **Text contrast is CRITICAL** — never use light gray text. Minimum text `strokeColor` on white: `#757575`
+- Do NOT use emoji in text — they don't render in Excalidraw's font
+- For complex diagrams, plan the layout on a grid first: X at 80, 330, 580... and Y at 80, 240, 400...
+- Keep diagrams focused — split complex systems into multiple `.excalidraw` files rather than cramming everything into one
+- The hand-drawn style (`roughness: 1`) is the default and makes diagrams feel approachable — use `roughness: 0` only for background zones