@orderful/droid 0.47.0 → 0.48.0

package/src/tools/excalidraw/skills/excalidraw/references/element-templates.md

@@ -0,0 +1,336 @@
+# Element Templates and Colour Palette
+
+## Common Properties (all elements)
+
+Every element must include these fields:
+
+```json
+{
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a0",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+**Element ID convention:** Increment `index` for each element: `"a0"`, `"a1"`, `"a2"`, etc. Use short unique alphanumeric strings for `id` fields (e.g., `"box_api"`, `"text_api"`, `"arrow_api_db"`).
+
+## Rectangle (container)
+
+```json
+{
+  "type": "rectangle",
+  "id": "box_unique_id",
+  "x": 0, "y": 0,
+  "width": 260, "height": 120,
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "#d0ebff",
+  "fillStyle": "solid",
+  "strokeWidth": 2,
+  "roundness": { "type": 3 },
+  "boundElements": [
+    { "type": "text", "id": "text_for_this_box" }
+  ],
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a0",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+## Text (bound to container)
+
+Bound text lives inside a rectangle. The `containerId` on the text and the matching `boundElements` on the rectangle must reference each other.
+
+```json
+{
+  "type": "text",
+  "id": "text_for_this_box",
+  "x": 10, "y": 10,
+  "width": 240, "height": 100,
+  "text": "Service Name\n\nHandles auth\nManages sessions",
+  "fontSize": 16,
+  "fontFamily": 1,
+  "textAlign": "center",
+  "verticalAlign": "middle",
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "containerId": "box_unique_id",
+  "originalText": "Service Name\n\nHandles auth\nManages sessions",
+  "autoResize": true,
+  "lineHeight": 1.25,
+  "hasTextLink": false,
+  "rawText": "",
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a1",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+## Text (standalone — titles, labels)
+
+Same as bound text but with `"containerId": null` and no parent rectangle reference.
+
+```json
+{
+  "type": "text",
+  "id": "title_text",
+  "x": 100, "y": 20,
+  "width": 400, "height": 40,
+  "text": "My Architecture Diagram",
+  "fontSize": 28,
+  "fontFamily": 1,
+  "textAlign": "center",
+  "verticalAlign": "middle",
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "containerId": null,
+  "originalText": "My Architecture Diagram",
+  "autoResize": true,
+  "lineHeight": 1.25,
+  "hasTextLink": false,
+  "rawText": "",
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a0",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+## Arrow
+
+For connected arrows, `startBinding` and `endBinding` must reference the source and target element IDs. The `points` array defines the arrow path relative to the arrow's `x`/`y` origin.
+
+```json
+{
+  "type": "arrow",
+  "id": "arrow_unique_id",
+  "x": 260, "y": 60,
+  "width": 80, "height": 0,
+  "strokeColor": "#868e96",
+  "backgroundColor": "transparent",
+  "fillStyle": "solid",
+  "strokeWidth": 2,
+  "roundness": { "type": 2 },
+  "startBinding": { "elementId": "source_box_id", "focus": 0, "gap": 5 },
+  "endBinding": { "elementId": "target_box_id", "focus": 0, "gap": 5 },
+  "startArrowhead": null,
+  "endArrowhead": "arrow",
+  "points": [[0, 0], [80, 0]],
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a3",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "boundElements": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+For vertical arrows, adjust `height` instead of `width` and set points accordingly (e.g., `[[0, 0], [0, 80]]`).
+
+## Sticky Note
+
+A sticky note is a rectangle with bound text that auto-resizes to fit content. Useful for annotations, callouts, and concept maps.
+
+```json
+{
+  "type": "rectangle",
+  "id": "note_unique_id",
+  "x": 0, "y": 0,
+  "width": 200, "height": 80,
+  "strokeColor": "#e8590c",
+  "backgroundColor": "#ffe8cc",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "roundness": { "type": 3 },
+  "customData": { "legacyTextWrap": true },
+  "boundElements": [
+    { "type": "text", "id": "note_text_id" }
+  ],
+  "version": 1,
+  "seed": 1,
+  "versionNonce": 1,
+  "index": "a4",
+  "isDeleted": false,
+  "updated": 1,
+  "link": null,
+  "locked": false,
+  "groupIds": [],
+  "strokeStyle": "solid",
+  "frameId": null,
+  "opacity": 100,
+  "angle": 0,
+  "roughness": 1
+}
+```
+
+With matching bound text (same pattern as bound text above, with `"containerId": "note_unique_id"`).
+
+## Colour Palette
+
+Use Excalidraw's built-in colours for consistency:
+
+| Purpose | `strokeColor` | `backgroundColor` |
+|---------|--------------|------------------|
+| Primary / highlighted | `#2f9e44` | `#b2f2bb` (green) |
+| Secondary | `#1971c2` | `#d0ebff` (blue) |
+| Tertiary | `#e8590c` | `#ffe8cc` (orange) |
+| Neutral / supporting | `#868e96` | `#e9ecef` (grey) |
+| Warning / attention | `#e03131` | `#ffc9c9` (red) |
+| Purple / alternate | `#6741d9` | `#d0bfff` (purple) |
+| Labels / arrows | `#868e96` | `transparent` |
+| Title text | `#1e1e1e` | `transparent` |
+
+**Colour grouping rule:** Use one colour per logical group (e.g., all API services blue, all data stores green). Before generating, propose the colour assignments to the user so they can adjust. This ensures the legend is meaningful, not arbitrary.
+
+## Colour Legend
+
+**Every diagram must include a colour legend.** Place it in the bottom-left corner of the canvas, below and to the left of the main diagram content.
+
+The legend is a vertical stack of small colour swatches (rectangles) with labels explaining what each colour represents in this specific diagram. Only include colours that are actually used.
+
+```
+┌──────────────────┐
+│  Legend           │  ← title text (fontSize: 16, bold)
+│                   │
+│  ■ API Services   │  ← small coloured rectangle + label
+│  ■ Data Stores    │
+│  ■ External       │
+│  ■ Infrastructure │
+└──────────────────┘
+```
+
+**Implementation:** Use a group of elements:
+- One standalone title text element ("Legend", fontSize: 16)
+- For each colour: a small rectangle (30x20px) + standalone text label to its right
+- Stack vertically with 8px gap between rows
+- Position below the main diagram content with ~60px margin
+
+Example swatch element:
+```json
+{
+  "type": "rectangle",
+  "id": "legend_swatch_blue",
+  "x": 100, "y": 600,
+  "width": 30, "height": 20,
+  "strokeColor": "#1971c2",
+  "backgroundColor": "#d0ebff",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "roundness": { "type": 3 }
+}
+```
+
+With a matching label:
+```json
+{
+  "type": "text",
+  "id": "legend_label_blue",
+  "x": 140, "y": 600,
+  "width": 120, "height": 20,
+  "text": "API Services",
+  "fontSize": 14,
+  "fontFamily": 1,
+  "textAlign": "left",
+  "verticalAlign": "middle",
+  "strokeColor": "#1e1e1e",
+  "backgroundColor": "transparent",
+  "containerId": null
+}
+```
+
+Repeat for each colour used in the diagram, incrementing y by 28px per row.
+
+## Sizing Guidelines
+
+| Element | Recommended size |
+|---------|-----------------|
+| Box width | 200–300px (varies by text length) |
+| Box height | 80–160px (varies by content lines) |
+| Horizontal gap between boxes | 80–120px |
+| Vertical gap between rows | 60–100px |
+| Title font size | 28 |
+| Box text font size | 16–20 |
+| Label font size | 14 |
+
+**Text width estimate:** ~8px per character at `fontSize: 16`
+
+**Arrow labels:** Place as standalone text near the arrow midpoint.
+
+## Layout Style Guidance
+
+### Flow Chart
+For processes, workflows, request lifecycles. Arrange top-to-bottom or left-to-right with directional arrows. Each step is a box; decisions can use diamond shapes (rotated rectangles).
+
+### Architecture Diagram
+For system components, services, layers. Use grouped boxes with labels, arrows showing data flow between services. Group related services with a larger background rectangle.
+
+### Entity Relationship
+For data models, schemas, relationships. Boxes represent entities with field lists inside. Lines (not arrows) show relationships; label the line with cardinality (1:N, etc.).
+
+### Concept Map
+For brainstorming, exploring ideas. Loose arrangement, grouped by theme. Connecting lines with labels, sticky notes for annotations. Less rigid than a flow chart.
+
+## Tips
+
+- Keep text concise — bullet points over paragraphs
+- Add a title text element at the top of the canvas
+- For large diagrams, organise in clear rows/columns — the user can rearrange in Excalidraw
+- Start elements at coordinates (100, 100) or higher to leave canvas margin

package/src/tools/excalidraw/skills/excalidraw/references/format-spec.md

@@ -0,0 +1,102 @@
+# Excalidraw File Format Specification
+
+## Important: Use `.excalidraw.md`, NOT `.excalidraw`
+
+The Obsidian Excalidraw plugin uses `.excalidraw.md` files (a markdown wrapper format). Plain `.excalidraw` JSON opens in "compatibility mode" with limited functionality.
+
+## YAML Frontmatter
+
+The file MUST start with this frontmatter:
+
+```
+---
+excalidraw-plugin: parsed
+---
+```
+
+The `excalidraw-plugin: parsed` key is mandatory. Without it, Obsidian won't recognise the file as an Excalidraw drawing.
+
+## Full File Structure
+
+````markdown
+---
+excalidraw-plugin: parsed
+---
+
+# Drawing
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [],
+  "appState": {
+    "gridSize": null,
+    "viewBackgroundColor": "#ffffff"
+  },
+  "files": {}
+}
+```
+
+%%
+# Drawing
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [],
+  "appState": {
+    "gridSize": null,
+    "viewBackgroundColor": "#ffffff"
+  },
+  "files": {}
+}
+```
+%%
+````
+
+## Structure Explained
+
+The JSON appears **twice** in the file:
+
+1. **Visible block** — inside a fenced ` ```json ` code block after `# Drawing`. This is what shows in Obsidian's markdown preview.
+2. **Plugin working copy** — the same JSON repeated inside `%% ... %%` comment markers. This is what the Excalidraw plugin uses to render the drawing.
+
+**Both blocks must contain identical JSON.** The plugin reads from the `%%` block when rendering; the visible block is for human reference.
+
+## Top-Level JSON Schema
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [ /* all drawing elements go here */ ],
+  "appState": {
+    "gridSize": null,
+    "viewBackgroundColor": "#ffffff"
+  },
+  "files": {}
+}
+```
+
+| Field | Value | Notes |
+|-------|-------|-------|
+| `type` | `"excalidraw"` | Always this string |
+| `version` | `2` | Always 2 |
+| `source` | `"https://excalidraw.com"` | Always this URL |
+| `elements` | array | All drawing elements |
+| `appState.gridSize` | `null` | No grid by default |
+| `appState.viewBackgroundColor` | `"#ffffff"` | White background |
+| `files` | `{}` | Empty unless images embedded |
+
+## What Happens If Format Is Wrong
+
+| Problem | Result |
+|---------|--------|
+| Missing `excalidraw-plugin: parsed` frontmatter | File opens as plain markdown, not as a drawing |
+| JSON only in visible block, missing `%%` block | Drawing renders as JSON text only |
+| JSON mismatch between blocks | Plugin uses `%%` block; visible block shows stale content |
+| Using `.excalidraw` instead of `.excalidraw.md` | Opens in compatibility mode with limited functionality |

package/src/tools/plan/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-plan",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Task-scoped planning with portable, structured plans. Use when planning implementation for a PR, ticket, or small feature. User prompts like 'let's plan this', 'can we start a plan', 'think through the implementation'.",
   "author": {
     "name": "Orderful",

package/src/tools/plan/TOOL.yaml

@@ -1,6 +1,6 @@
 name: plan
 description: "Task-scoped planning with portable, structured plans. Use when planning implementation for a PR, ticket, or small feature. User prompts like 'let's plan this', 'can we start a plan', 'think through the implementation'."
-version: 0.1.5
+version: 0.1.6
 status: alpha
 
 includes:

package/src/tools/plan/skills/plan/SKILL.md

@@ -74,6 +74,8 @@ Example: `/plan new auth-refactor -- we must stay backward compatible with v1 cl
 2. Address each, respond with `> @{user_mention}`
 3. Update the doc
 
+With `--holistic`: group related comments into thematic clusters and respond cohesively to each cluster instead of one-by-one. Unrelated comments still get individual responses. See `comments` skill for full holistic mode behaviour.
+
 ## `/plan cleanup`
 
 **Trigger:** `/plan cleanup` or user says "clean up", "lock in decisions", "resolve these threads"

package/src/tools/plan/skills/plan/references/workflows.md

@@ -126,6 +126,8 @@ Store as active plan for session.
 
 ## `/plan check`
 
+Supports `--holistic` flag for cohesive responses to related comments.
+
 ### Step 1: Load Active Plan
 
 If no active plan, prompt to search for one.
@@ -138,13 +140,20 @@ Search for `> @droid` lines (user comments addressed to AI):
 grep -n "> @droid" {plan_path}
 ```
 
-### Step 3: Address Each Comment
+### Step 3: Address Comments
 
-For each comment:
+**Default mode:** For each comment:
 
 1. **Read context** - surrounding lines, section it's in
 2. **Respond** - add response below with `> @{user_mention}`
 
+**Holistic mode (`--holistic`):**
+
+1. **Read all comments first** with their surrounding context
+2. **Group related comments** — identify thematic clusters (comments exploring the same question, building on each other, or pulling in different directions on the same topic)
+3. **For each cluster:** respond once at the last comment in the group with a cohesive answer that addresses the whole cluster. Earlier comments get a brief forward-reference: `> @{user_mention} Addressed below with the related comments.`
+4. **Standalone comments:** respond individually as normal
+
 ### Step 4: Update Doc
 
 Write changes back to plan file.