@orderful/droid 0.47.0 → 0.48.0

package/dist/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/dist/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/dist/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/dist/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/dist/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions.",
   "author": {
     "name": "Orderful",

package/src/tools/brain/TOOL.yaml

@@ -1,6 +1,6 @@
 name: brain
 description: "Your scratchpad (or brain) - a collaborative space for planning and research. Create docs with /brain plan, /brain research, or /brain review. Use @mentions for async discussion. Docs persist across sessions."
-version: 0.4.1
+version: 0.4.2
 status: beta
 
 includes:

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

@@ -121,10 +121,12 @@ Full procedure: `references/workflows.md` § Adding
 
 ## Checking Comments
 
-**Trigger:** `/brain check`
+**Trigger:** `/brain check` or `/brain check --holistic`
 
 Find `> @droid` comments in active doc and address each. Preserve original comment, add response below with `> @{user_mention}`.
 
+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.
+
 Full procedure: `references/workflows.md` § Checking
 
 ## Cleaning Up Resolved Threads

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

@@ -150,9 +150,11 @@ Detailed procedures for each brain operation.
 
 ## Checking
 
-**Trigger:** `/brain check`
+**Trigger:** `/brain check` or `/brain check --holistic`
 
-**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+**Prefer `comments` skill:** If the `comments` skill is installed, use `/comments check` (or `/comments check --holistic`) instead - it provides better comment detection, cleanup workflows, and supports the full `@droid`/`@user` convention. The workflow below is a fallback for basic comment handling.
+
+**Holistic mode (`--holistic`):** Pass the flag through to the comments skill. If using the fallback workflow below, apply the same principle: after step 4 (finding all comments), group related comments into thematic clusters and respond cohesively to each cluster at the last comment in the group. Unrelated comments get individual responses as normal.
 
 **Directionality:** The @mention is the **target**, not the author:
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-comments",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
   "author": {
     "name": "Orderful",

package/src/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.3.6
+version: 0.3.7
 status: beta
 
 includes:

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

@@ -82,6 +82,7 @@ When you find a `@droid` marker:
 
 - `/comments check` - Scan for AI markers and address each one
 - `/comments check {path}` - Scope to specific file or directory
+- `/comments check --holistic` - Read all comments, then respond cohesively to related clusters
 - `/comments cleanup` - Find resolved comment threads and remove them
 
 ## Behavior
@@ -101,6 +102,8 @@ When you find a `@droid` marker:
 
 #### Pass 2: Respond & Write
 
+**Default mode (no flag):** Respond to each comment individually, in order.
+
 1. For each comment, determine intent:
    - **Action request** ("do X", "add Y", "fix Z") → Execute the action
    - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`
@@ -109,6 +112,17 @@ When you find a `@droid` marker:
    - If `preserve_comments: true` → Keep the original `@droid` comment (add response below it)
    - If `preserve_comments: false` → Remove the original comment after addressing
 
+**Holistic mode (`--holistic`):** Respond cohesively to related comments instead of one-by-one.
+
+1. **Group related comments** — identify thematic clusters (comments exploring the same question, building on each other, or pulling in different directions on the same topic). Comments that are unrelated stay standalone.
+2. **For each cluster of related comments:**
+   - Synthesize the thread of thought — what is the user working through?
+   - Respond once at the **last comment in the cluster** with a cohesive answer that addresses the whole group
+   - Earlier comments in the cluster get a brief forward-reference: `> @{user_mention} Addressed below with the related comments.`
+   - The synthesized response should feel like engaging with a complete idea, not stitching together fragments
+3. **For standalone (unrelated) comments:** Respond individually, same as default mode
+4. **Handle `preserve_comments`** the same as default mode
+
 ### On `/comments cleanup`:
 
 1. Find AI tag and `> @{user_mention}` pairs where conversation appears resolved

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

@@ -0,0 +1,22 @@
+{
+  "name": "droid-excalidraw",
+  "version": "0.1.0",
+  "description": "Generate Excalidraw diagrams from conversation context and save them to your Obsidian brain vault. Requires brain tool configured, Obsidian, and the Excalidraw plugin.",
+  "author": {
+    "name": "Orderful",
+    "url": "https://github.com/orderful"
+  },
+  "repository": "https://github.com/orderful/droid",
+  "license": "MIT",
+  "keywords": [
+    "droid",
+    "ai",
+    "excalidraw"
+  ],
+  "skills": [
+    "./skills/excalidraw/SKILL.md"
+  ],
+  "commands": [
+    "./commands/excalidraw.md"
+  ]
+}

package/src/tools/excalidraw/TOOL.yaml

@@ -0,0 +1,16 @@
+name: excalidraw
+description: "Generate Excalidraw diagrams from conversation context and save them to your Obsidian brain vault. Requires brain tool configured, Obsidian, and the Excalidraw plugin."
+version: 0.1.0
+status: experimental
+
+includes:
+  skills:
+    - name: excalidraw
+      required: true
+  commands:
+    - name: excalidraw
+      is_alias: false
+  agents: []
+
+dependencies:
+  - brain

package/src/tools/excalidraw/commands/excalidraw.md

@@ -0,0 +1,34 @@
+---
+name: excalidraw
+description: "Generate Excalidraw diagrams in your Obsidian brain vault"
+argument-hint: "[{description} | check]"
+---
+
+# /excalidraw
+
+**User invoked:** `/excalidraw $ARGUMENTS`
+
+**Your task:** Invoke the **excalidraw skill** with these arguments.
+
+## Usage
+
+```
+/excalidraw {description}    # Generate a new diagram from context
+/excalidraw check            # Review changes in the active drawing
+```
+
+## Examples
+
+- `/excalidraw flow chart of the auth system` → Generate an auth flow diagram
+- `/excalidraw architecture for the orders service` → Generate a system architecture diagram
+- `/excalidraw ER diagram for orders and products` → Generate an entity relationship diagram
+- `/excalidraw check` → Read the active drawing and describe what's in it
+
+## Notes
+
+- Diagrams are saved to your Obsidian brain vault as `.excalidraw.md` files
+- Requires the brain tool configured with a `brain_dir`
+- Requires Obsidian with the Excalidraw plugin installed
+- See the **excalidraw skill** for complete documentation
+
+**Reserved keywords:** `check`

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

@@ -0,0 +1,100 @@
+---
+name: excalidraw
+description: "Generate Excalidraw diagrams from conversation context and write them to the Obsidian brain vault. Use when user says 'draw this', 'diagram this flow', 'visualize this architecture', 'sketch this out', or '/excalidraw'. Also '/excalidraw check' to review changes in the active drawing."
+argument-hint: "[{description} | check]"
+allowed-tools: [Read, Write, Glob, Bash]
+---
+
+# Excalidraw
+
+Generate `.excalidraw.md` diagrams from conversation context — architecture diagrams, flow charts, system overviews, entity relationships. Files land in the brain vault and open directly in Obsidian's Excalidraw plugin.
+
+## Hard Dependencies
+
+This tool requires **all three** of the following:
+
+| Dependency | Why |
+|-----------|-----|
+| **brain tool configured** | Uses `brain_dir` for file placement |
+| **Obsidian** | Files use `.excalidraw.md` — Obsidian-specific format |
+| **Excalidraw plugin for Obsidian** | Required to render `.excalidraw.md` files |
+
+**Dependency check (run first, every time):**
+
+```bash
+droid config --get tools.brain
+```
+
+Parse the JSON output. If `brain_dir` is missing or empty, **stop and inform the user:**
+
+> The excalidraw tool requires the brain tool to be configured with a `brain_dir`. Run `droid config --set tools.brain.brain_dir=/path/to/vault` to configure it. You also need Obsidian with the Excalidraw plugin installed to open the generated files.
+
+Do not proceed until `brain_dir` is confirmed.
+
+## Commands
+
+**Reserved keywords:** `check`
+
+| Command | Action |
+|---------|--------|
+| `/excalidraw {description}` | Generate a new diagram from conversation context |
+| `/excalidraw check` | Review changes in the active drawing |
+
+## `/excalidraw {description}`
+
+1. **Check dependencies** — run `droid config --get tools.brain`, abort if `brain_dir` not set
+2. **Analyse context** — read the conversation to understand what to diagram. If unclear, ask what the user wants visualised
+3. **Pick a layout style** — flow chart, architecture, entity relationship, or concept map (see `references/element-templates.md` § Layout Styles)
+4. **Propose colour assignments** — before generating, present the user with a short table mapping each colour to a logical group in the diagram (e.g., "Blue = API services, Green = data stores, Orange = external systems"). Ask if they'd like to adjust. This ensures the legend is meaningful, not arbitrary.
+5. **Determine file placement:**
+   - If there's an active brain doc in the session, place the `.excalidraw.md` next to it (same directory, matching name prefix)
+   - Otherwise, place in `{brain_dir}/0-Inbox/diagrams/`
+6. **Create the target directory** if it doesn't exist:
+   ```bash
+   mkdir -p "{target_directory}"
+   ```
+7. **Generate the `.excalidraw.md` file** — see `references/format-spec.md` for the exact file format, `references/element-templates.md` for element JSON templates and the colour palette. **Always include a colour legend** in the bottom-left corner of the canvas (see `references/element-templates.md` § Colour Legend)
+8. **Write the file** using the Write tool
+9. **Emit an Obsidian link:**
+   ```
+   obsidian://open?vault={vault_name}&file={url-encoded-relative-path}
+   ```
+   Where `vault_name` = last path component of `brain_dir` (strip trailing slashes), and `relative_path` is the file path relative to `brain_dir`.
+
+## `/excalidraw check`
+
+1. **Find the active drawing** — the most recently discussed or generated `.excalidraw.md` file in the session. If none, search `{brain_dir}` for recently modified `.excalidraw.md` files and ask which one
+2. **Read the file** using the Read tool and parse the JSON from the `%%` block (that's the plugin's working copy)
+3. **Extract all elements** and build a mental model of the diagram:
+   - List all boxes/rectangles with their text content and colours
+   - List all arrows and what they connect
+   - List all standalone text labels
+   - Note spatial grouping (what's near what)
+4. **Summarise what you see** — describe the diagram in plain language
+5. **If you generated the original:** compare against what you wrote and call out what the user added, moved, removed, or changed
+6. **Offer next steps:** add more elements, reflect changes into a brain doc, or flesh out specific elements
+
+**Tips for Check:**
+- Focus on content and relationships, not pixel positions
+- Call out new elements by name: "You added a 'Redis Cache' box between the API and DB"
+- If the user added sticky notes, treat them like comments — respond to them
+- If the diagram diverged significantly, offer to regenerate with the new structure as baseline
+
+## File Placement Rules
+
+| Situation | Target directory |
+|-----------|-----------------|
+| Active brain doc in session | Same directory as the brain doc |
+| No active brain doc | `{brain_dir}/0-Inbox/diagrams/` |
+
+File name: use a kebab-case slug from the diagram description (e.g., `auth-flow.excalidraw.md`).
+
+## When NOT to Use
+
+- User wants a polished presentation diagram (suggest FigJam/Figma instead)
+- Simple lists or tables that don't benefit from spatial layout
+
+## Reference Files
+
+- `references/format-spec.md` — `.excalidraw.md` file format specification
+- `references/element-templates.md` — Element JSON templates, colour palette, sizing guidelines