@orderful/droid 0.46.0 → 0.48.0

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.

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-project",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features.",
   "author": {
     "name": "Orderful",

package/src/tools/project/TOOL.yaml

@@ -1,6 +1,6 @@
 name: project
 description: "Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features."
-version: 0.3.6
+version: 0.4.0
 status: beta
 
 includes:
@@ -21,7 +21,7 @@ config_schema:
     required: true
   preset:
     type: select
-    description: Output format for templates
+    description: "Link style: obsidian uses [[wikilinks]], markdown uses [standard](links)"
     default: "markdown"
     options:
       - markdown

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

@@ -7,7 +7,7 @@ allowed-tools: [Read, Write, Glob, Grep, Bash]
 
 # Project Skill
 
-Persistent project context that survives across sessions. Projects are folders containing `PROJECT.md` + `CHANGELOG.md`.
+Persistent project context that survives across sessions. Projects are folders containing `PROJECT.md` + `CHANGELOG.md`, with optional companion docs (`DECISIONS.md`, `WORKLOG.md`) that emerge as the project grows.
 
 ## Why Projects?
 
@@ -31,7 +31,7 @@ Chat history disappears. Projects persist.
 | Setting        | Default      | Description                                        |
 | -------------- | ------------ | -------------------------------------------------- |
 | `projects_dir` | **required** | Where projects are stored (must be configured)     |
-| `preset`       | `markdown`   | Output format: `markdown` or `obsidian`            |
+| `preset`       | `markdown`   | Link style: `obsidian` uses `[[wikilinks]]`, `markdown` uses `[standard](links)` |
 | `override`     | (none)       | User-defined behaviour overrides                   |
 
 **Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
@@ -106,6 +106,7 @@ Projects work best in a cycle:
 3. **Document** - Capture decisions in PROJECT.md before implementing
 4. **Implement** - Build with full context of why decisions were made
 5. **Capture** - `/project update` saves new learnings
-6. **Repeat** - Next session starts with accumulated knowledge
+6. **Prune** - If PROJECT.md exceeds ~300 lines, archive completed work to WORKLOG.md
+7. **Repeat** - Next session starts with accumulated knowledge
 
 Each cycle starts further ahead than the last.

package/src/tools/project/skills/project/references/changelog.md

@@ -5,7 +5,7 @@ Projects use a split file pattern to minimize context usage when loading.
 ## File Structure
 
 - `CHANGELOG.md` (sibling to PROJECT.md) - Complete version history
-- `PROJECT.md` - Only 3 most recent entries + link to full history
+- `PROJECT.md` - Link to full history only (version number lives in the metadata table)
 
 ## On Update
 
@@ -15,8 +15,8 @@ Projects use a split file pattern to minimize context usage when loading.
 2. **Add new entry to CHANGELOG.md** (prepend after header)
 
 3. **Update PROJECT.md changelog section**
-   - Keep only 3 most recent entries
-   - Ensure link to full history exists
+   - Keep only a link to CHANGELOG.md — no inline entries
+   - The version number in the metadata table is the quick-glance indicator
 
 ## CHANGELOG.md Format
 
@@ -35,31 +35,20 @@ All notable changes to the {Project Name} project.
 
 ## PROJECT.md Changelog Section Format
 
-**Markdown preset:**
 ```markdown
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-### X.Y.Z - YYYY-MM-DD
-- [Most recent]
-
-### X.Y.Z - YYYY-MM-DD
-- [Second most recent]
-
-### X.Y.Z - YYYY-MM-DD
-- [Third most recent]
 ```
 
-**Obsidian preset:**
-```markdown
-## Changelog
+When `preset` is `obsidian`, use `See [[CHANGELOG|full history]].` instead.
 
-See [[CHANGELOG|full history]].
+## Migration
 
-### X.Y.Z - YYYY-MM-DD
-- [Most recent]
-```
+If an existing PROJECT.md has inline changelog entries:
+1. Ensure all entries exist in CHANGELOG.md
+2. Replace the inline entries with just the link
+3. This happens naturally during `/project update` — no need to proactively migrate
 
 ## Guidelines
 
@@ -67,4 +56,4 @@ See [[CHANGELOG|full history]].
 - Keep entries concise but descriptive
 - Group related changes in a single bullet when appropriate
 - Most recent version at the top
-- Use `##` headers in CHANGELOG.md, `###` in PROJECT.md
+- Use `##` headers in CHANGELOG.md

package/src/tools/project/skills/project/references/creating.md

@@ -7,7 +7,6 @@
 1. **Read config first**
    - Run `droid config --get tools.project` and parse the JSON output
    - Use `projects_dir` (required - if not configured, inform user to set it up)
-   - Use `preset` if configured (markdown or obsidian)
 
 2. **Get project name**
    - Use provided name, or ask if not provided
@@ -21,7 +20,6 @@
 4. **Create files from templates** (see `templates.md`)
    - `PROJECT.md` - Main context file
    - `CHANGELOG.md` - Version history
-   - Format varies by `preset` config (markdown vs obsidian)
 
 5. **Confirm creation**
    - Show created folder path
@@ -62,6 +60,18 @@ New projects start minimal and grow organically. Common sections added over time
 
 See `templates.md` for the full initial template.
 
+### Companion Docs
+
+Projects may grow companion docs over time. These are **never** created at project creation — they emerge as the project grows.
+
+| Doc | Created When | Purpose |
+|-----|-------------|---------|
+| `CHANGELOG.md` | At project creation (the one exception) | Version history |
+| `DECISIONS.md` | 3+ decisions accumulate in PROJECT.md | Dedicated decisions log |
+| `WORKLOG.md` | PROJECT.md exceeds ~300 lines with completed items | Archive of completed work |
+
+The `/project update` procedure handles creation and migration automatically — see `updating.md` for details.
+
 ---
 
 ## Creating from Codex

package/src/tools/project/skills/project/references/loading.md

@@ -32,7 +32,8 @@
    - Confirm which project was loaded
    - Summarize key context (2-3 sentences)
    - Use project contents for all subsequent work in the session
-   - **Do NOT read CHANGELOG.md** — it exists for on-demand lookup only. PROJECT.md already references it; that is enough context.
+   - **Do NOT read companion docs by default** — CHANGELOG.md, DECISIONS.md, and WORKLOG.md exist for on-demand lookup only. PROJECT.md already references them; that is enough context.
+   - If the user asks about decisions, past work, or history, THEN read the relevant companion doc.
 
 7. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded project
 

package/src/tools/project/skills/project/references/templates.md

@@ -1,14 +1,13 @@
 # Project Templates
 
-Templates vary by `preset` setting.
-
-## Markdown Preset (default)
-
-### PROJECT.md
+## PROJECT.md
 
 ```markdown
 ---
+type: project
 status: active
+created: {today}
+updated: {today}
 ---
 
 # Project: {Name}
@@ -33,15 +32,16 @@ status: active
 
 {Architecture, key files, patterns}
 
+## Related
+
+- {Links to related notes}
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-### 0.1.0 - {today}
-- Initial project setup
 ```
 
-### CHANGELOG.md
+## CHANGELOG.md
 
 ```markdown
 # Changelog
@@ -54,58 +54,6 @@ All notable changes to the {Name} project.
 
 ---
 
-## Obsidian Preset
-
-### PROJECT.md
-
-```markdown
----
-type: project
-status: active
-created: {today}
-updated: {today}
----
-
-# Project: {Name}
-
-{Brief description}
-
-| | |
-|---|---|
-| **Version** | 0.1.0 |
-| **Started** | {today} |
-| **Status** | Active |
-
-## Overview
-
-{**What** this project does, **why** it exists}
-
-## Goals
-
-- {Goal 1}
-
-## Technical Details
-
-{Architecture, key files, patterns}
-
-## Related
-
-- {Links to related notes}
-
-## Changelog
-
-See [[CHANGELOG|full history]].
-
-### 0.1.0 - {today}
-- Initial project setup
-```
-
-### CHANGELOG.md
-
-Same as markdown preset.
-
----
-
 ## Template Variables
 
 | Variable | Expands To |
@@ -115,19 +63,23 @@ Same as markdown preset.
 | `{name}` | Project name (lowercase) |
 | `{kebab-name}` | Folder name (kebab-case) |
 
-## Preset Differences Summary
+## Link Style
+
+Templates show standard markdown links. When `preset` is `obsidian`, substitute wikilinks:
 
-| Feature | Markdown | Obsidian |
-|---------|----------|----------|
-| Links | `[text](path)` | `[[path\|text]]` |
-| YAML properties | Minimal (`status`) | Rich (`type`, `created`, `updated`) |
-| Related section | Optional | Included |
+| Standard (markdown) | Wikilink (obsidian) |
+|---------------------|---------------------|
+| `[CHANGELOG.md](CHANGELOG.md)` | `[[CHANGELOG]]` |
+| `[DECISIONS.md](DECISIONS.md)` | `[[DECISIONS]]` |
+| `[WORKLOG.md](WORKLOG.md)` | `[[WORKLOG]]` |
+
+This is the only difference between presets — structure, frontmatter, and sections are identical.
 
 ---
 
 ## Seeded from Codex
 
-When creating with `--from codex:{name}`, use this template variant. Works with both markdown and obsidian presets.
+When creating with `--from codex:{name}`, use this template variant.
 
 ### Additional Variables
 
@@ -145,7 +97,10 @@ When creating with `--from codex:{name}`, use this template variant. Works with
 
 ```markdown
 ---
+type: project
 status: active
+created: {today}
+updated: {today}
 codex_source: projects/{codex-name}
 ---
 
@@ -190,9 +145,6 @@ Personal working memory for {Name}, seeded from shared codex context.
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-### 0.1.0 - {today}
-- Project created from codex:{codex-name}
 ```
 
 ### CHANGELOG.md (Seeded)
@@ -218,3 +170,95 @@ When extracting content from codex files:
 
 If a section is missing, use placeholder text:
 - `{To be extracted from codex or filled manually}`
+
+---
+
+## Companion Doc Templates
+
+Companion docs are **never** created at project start. They emerge when a project grows enough to benefit from them. See `creating.md` for when each is created.
+
+### DECISIONS.md
+
+Create when 3+ decisions have accumulated in PROJECT.md.
+
+**Table format (default)** — scales well for projects with many decisions:
+
+```markdown
+---
+type: decisions
+project: {Name}
+created: {today}
+updated: {today}
+---
+
+# Decisions
+
+Key decisions for the {Name} project.
+
+| # | Decision | Date | Context |
+|---|----------|------|---------|
+| 1 | {Decision title} | {YYYY-MM-DD} | {Brief rationale or link to discussion} |
+```
+
+**Rich format (alternative)** — for fewer, more significant decisions:
+
+```markdown
+---
+type: decisions
+project: {Name}
+created: {today}
+updated: {today}
+---
+
+# Decisions
+
+Key decisions for the {Name} project.
+
+## 1. {Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** Accepted
+
+{2-3 sentences of context and rationale. Link to plan or research doc if one exists.}
+```
+
+Choose the format that fits the project. Table for many small decisions, rich for fewer important ones. Mixing is fine — start with table, expand significant entries to rich format if needed.
+
+### WORKLOG.md
+
+Create when PROJECT.md exceeds ~300 lines with completed work items that can be archived.
+
+```markdown
+---
+type: worklog
+project: {Name}
+created: {today}
+updated: {today}
+---
+
+# Worklog
+
+Completed work for the {Name} project. Newest first.
+
+## {Title of completed work}
+
+{YYYY-MM-DD} · PR #{number} · [plan link if exists]
+
+{1-3 sentence narrative of what was done and why it mattered.}
+
+---
+
+## {Older completed work}
+
+{YYYY-MM-DD}
+
+{Brief narrative.}
+```
+
+### Worklog Entry Guidelines
+
+- **Title:** Descriptive, in past tense ("Restructured PROJECT.md", "Added permission controls")
+- **Metadata line:** Date is required, PR and plan links are optional
+- **Narrative:** Brief — it's an index, not a retelling. Link out to plans, research, PRs for detail.
+- **Order:** Reverse chronological (newest first)
+- **Separator:** Use `---` between entries for readability

package/src/tools/project/skills/project/references/updating.md

@@ -17,18 +17,25 @@
    - Important file paths or code locations
    - Bug fixes or gotchas encountered
 
-3. **If significant new information found:**
+3. **Size check** (read current PROJECT.md and count lines):
+   - **Under ~300 lines:** Proceed normally
+   - **300–400 lines:** Look for archival opportunities — mention them in your proposal
+   - **Over 400 lines:** Actively identify content to archive (see "Archival to WORKLOG.md" below)
+
+4. **If significant new information found:**
    - Propose specific sections/content to add or update
+   - Include archival proposals if the size check warrants it
    - Show what will be changed
    - Ask for confirmation before proceeding
 
-4. **If no obvious updates:**
+5. **If no obvious updates:**
    - Ask what the user would like to update
    - Suggest sections: metadata, implementation details, technical decisions, notes
 
-5. **After approval:**
+6. **After approval:**
    - Read current project file
    - Make approved updates, preserving existing structure
+   - Route decisions appropriately (see "Decisions Routing" below)
    - Determine version bump (see `versioning.md`)
    - Add changelog entry (see `changelog.md`)
    - Confirm what was updated
@@ -46,7 +53,74 @@ Good project updates include:
 | **Progress** | "Completed validation layer, starting on UI" |
 | **File locations** | "Key files: `src/services/template.service.ts`" |
 
-## Example
+## Decisions Routing
+
+Decisions are captured differently depending on whether the project has a DECISIONS.md companion doc:
+
+1. **DECISIONS.md exists** → Add new decisions there. Add a brief reference in PROJECT.md only when the decision directly affects active work.
+2. **DECISIONS.md does not exist AND 3+ decisions in PROJECT.md** → Offer to create DECISIONS.md (from template in `templates.md`) and migrate existing decisions. Keep a summary reference in PROJECT.md.
+3. **Fewer than 3 decisions** → Keep inline in PROJECT.md as usual.
+
+When migrating, preserve the original decision date and context. Remove the detailed decision content from PROJECT.md, leaving just a "See DECISIONS.md" reference in the relevant section.
+
+## Archival to WORKLOG.md
+
+When the size check identifies archival opportunities, propose moving completed work items to a WORKLOG.md companion doc.
+
+### What to archive
+
+- **Completed** Current Work items (fully shipped, no active follow-ups)
+- **Previous Work** or **Done** sections
+- Inline decision tables with 5+ entries (migrate to DECISIONS.md instead)
+- Historical context that's useful for reference but not needed in active context
+
+### What NOT to archive
+
+- Active or in-progress work items
+- Technical details still relevant to current work
+- Architectural patterns or constraints that guide ongoing development
+- The Overview, Goals, or metadata sections
+
+### Archival procedure
+
+1. **Identify candidates** — List completed items with their approximate line counts
+2. **Propose archival** — Show before/after line counts so the user sees the impact:
+   ```
+   PROJECT.md is currently 427 lines. Proposed archival:
+   - "Completed: Permission Controls" (~35 lines) → WORKLOG.md
+   - "Completed: Template Rendering" (~28 lines) → WORKLOG.md
+   - Inline decisions table (12 entries) → DECISIONS.md
+
+   After: ~340 lines (saved ~87 lines)
+   ```
+3. **Create companion doc** if needed — Use templates from `templates.md`
+4. **Convert to worklog entries** — Condense each item to title + metadata line + 1-3 sentence narrative (see template guidelines)
+5. **Remove from PROJECT.md** — Delete the detailed content, not the section headers
+6. **Verify** — Confirm the archived content is preserved in the companion doc
+
+### Example
+
+```
+User: /project update
+
+Claude: I'll update #project-transaction-templates with learnings from this session.
+
+PROJECT.md is 382 lines — I also found archival opportunities.
+
+Proposed changes:
+- Add "Batch Processing" to Current Work with the patterns we established
+- Note the decision to use streaming for large payloads
+
+Proposed archival (saves ~45 lines):
+- "Permission Controls" (completed 2026-01-15) → WORKLOG.md
+- "Template Validation" (completed 2026-02-01) → WORKLOG.md
+
+This is a minor version bump (0.16.0 → 0.17.0).
+
+Proceed with these updates?
+```
+
+## Example (standard update)
 
 ```
 User: /project update