@orderful/droid 0.31.0 → 0.31.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "droid",
       "description": "Core droid meta-skill for update awareness, tool discovery, and usage help. Checks for updates, helps users find tools, and answers 'how do I...' questions about droid workflows.",
-      "version": "0.5.2",
+      "version": "0.5.3",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -22,7 +22,7 @@
     {
       "name": "droid-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.3.1",
+      "version": "0.3.3",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -61,7 +61,7 @@
     {
       "name": "droid-codex",
       "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
-      "version": "0.1.7",
+      "version": "0.1.9",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -87,7 +87,7 @@
     {
       "name": "droid-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.1",
+      "version": "0.3.2",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/AGENTS.md

@@ -100,6 +100,7 @@ Things that will bite you if you don't know:
 | Bump tool version when skill content changes | Users won't get updates otherwise                                     | Patch bump the tool's TOOL.yaml version                                    |
 | Config-first in commands                     | User overrides must take precedence                                   | Always read `~/.droid/skills/{skill}/overrides.yaml` before using defaults |
 | Changeset package name                       | npm package is scoped                                                 | Use `"@orderful/droid"` not `"droid"` in changesets                        |
+| Run build before PR                          | Plugin manifests need regenerating when tools change                  | Run `bun run build` and commit plugin.json files before creating PR        |
 
 ## Testing
 

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @orderful/droid
 
+## 0.31.2
+
+### Patch Changes
+
+- [#190](https://github.com/Orderful/droid/pull/190) [`06e1d05`](https://github.com/Orderful/droid/commit/06e1d055e774ff8f996343ca7ca771477e300f7e) Thanks [@frytyler](https://github.com/frytyler)! - Condense skill docs for better context efficiency (Phase 3)
+
+  **droid skill** (450 → 89 lines, 80% reduction):
+  - Removed verbose example dialogues
+  - Condensed to tables + guidelines
+  - LLM generates natural responses from shorter guidance
+
+  **brain skill** (191 → 128 lines, 33% reduction):
+  - User-defined categories: any non-reserved word becomes a category
+  - `/brain spike auth` → `spikes/auth.md` (creates on the fly)
+  - Reserved keywords: `search`, `add`, `check`, `done`
+  - Collapsed repetitive per-category sections into single generic pattern
+
+  **codex skill** (454 → 405 lines, 11% reduction):
+  - Collapsed `/codex new {type}` commands into single pattern
+  - `/codex new {category} {name}` where category = project|domain|proposal|pattern|topic
+  - Removed `/codex new {name}` shorthand - must specify category explicitly
+
+  **Commands updated** to match new patterns:
+  - brain, scratchpad, codex, project commands now use explicit `search` keyword
+  - Added `--` delimiter examples
+  - Added category-scoped search examples for codex
+
+  **brain_dir config:** Removed default - now prompts user to choose location on first use.
+
+  **Reference files updated** to match Phase 1-3 changes:
+  - brain/references/workflows.md - explicit `search`, user-defined categories
+  - brain-obsidian/references/workflows.md - explicit search patterns
+  - codex/references/creating.md, decisions.md - explicit search patterns
+  - project/references/loading.md, creating.md - explicit search patterns, `--` delimiter examples
+
+  **Total savings:** ~470 lines removed across three skills. Smaller docs = more context for actual work.
+
+- [#189](https://github.com/Orderful/droid/pull/189) [`d9917c4`](https://github.com/Orderful/droid/commit/d9917c4630ac5c418d31a332b3114500bfa78fa3) Thanks [@frytyler](https://github.com/frytyler)! - Add search enhancements: `--` delimiter and category-scoped search
+
+  **`--` delimiter for follow-up instructions** (brain, codex, project):
+
+  ```bash
+  /brain search auth refactor -- what's left to do?
+  /project search droid -- show the changelog
+  /codex search transaction -- summarize the PRD
+  ```
+
+  Everything after `--` is executed as a follow-up instruction after loading the doc.
+
+  **Category-scoped search for codex**:
+
+  ```bash
+  /codex topics search auth        # Search within topics only
+  /codex patterns search webhook   # Search within patterns only
+  /codex projects search transaction
+  ```
+
+  Narrows search to a specific category instead of searching all categories.
+
+- [#187](https://github.com/Orderful/droid/pull/187) [`738bcec`](https://github.com/Orderful/droid/commit/738bcec4ffbe8ad5bff6a986838bf26fd6b6544a) Thanks [@frytyler](https://github.com/frytyler)! - Require explicit `search` keyword for /codex, /brain, and /project commands
+
+  Commands that support both reserved keywords and search had ambiguity issues (e.g., `/codex projects` - is this "list projects" or "search for 'projects'"?). This change removes implicit search patterns and requires the explicit `search` keyword:
+  - `/codex search {query}` (was `/codex {name}`)
+  - `/brain search {topic}` (was `/brain {topic}`)
+  - `/project search {keywords}` (was `/project {keywords}`)
+
+  Closes #139
+
+## 0.31.1
+
+### Patch Changes
+
+- [#185](https://github.com/Orderful/droid/pull/185) [`477a6ca`](https://github.com/Orderful/droid/commit/477a6ca608f63eb1e7571281a0fbe6c373141653) Thanks [@frytyler](https://github.com/frytyler)! - Fix Cursor command installation - install all commands for `/` autocomplete discovery
+
 ## 0.31.0
 
 ### Minor Changes

package/dist/bin/droid.js

@@ -1316,7 +1316,7 @@ function installSkill(skillName) {
         (cmd) => (typeof cmd === "string" ? cmd : cmd.name) === commandName
       );
       const isAlias = typeof commandMeta === "object" && commandMeta.is_alias;
-      const shouldInstall = config.platform === "opencode" /* OpenCode */ || isAlias;
+      const shouldInstall = config.platform === "opencode" /* OpenCode */ || config.platform === "cursor" /* Cursor */ || isAlias;
       if (shouldInstall) {
         const sourcePath = join7(commandsSource, file);
         const targetPath = join7(commandsPath, file);

package/dist/index.js

@@ -1265,7 +1265,7 @@ function installSkill(skillName) {
         (cmd) => (typeof cmd === "string" ? cmd : cmd.name) === commandName
       );
       const isAlias = typeof commandMeta === "object" && commandMeta.is_alias;
-      const shouldInstall = config.platform === "opencode" /* OpenCode */ || isAlias;
+      const shouldInstall = config.platform === "opencode" /* OpenCode */ || config.platform === "cursor" /* Cursor */ || isAlias;
       if (shouldInstall) {
         const sourcePath = join7(commandsSource, file);
         const targetPath = join7(commandsPath, file);

package/dist/lib/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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/dist/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.3.1
+version: 0.3.3
 status: beta
 
 includes:

package/dist/tools/brain/commands/brain.md

@@ -1,7 +1,7 @@
 ---
 name: brain
 description: "Collaborative scratchpad for planning and research"
-argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | check|done]"
+argument-hint: "[search {topic} | {category} {topic} | add {text} | check | done]"
 ---
 
 # /brain
@@ -14,20 +14,22 @@ argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | chec
 
 ## Examples
 
-- `/brain auth-refactor` → Search for existing doc about "auth-refactor"
-- `/brain plan new-feature` → Create a new planning doc for "new-feature"
-- `/brain add found a bug in the parser` → Append text to active doc
+- `/brain search auth-refactor` → Search for existing doc about "auth-refactor"
+- `/brain search droid -- what's left to do?` → Search, load, then answer question
+- `/brain plan new-feature` → Create a new planning doc
+- `/brain spike caching` → Create doc in custom category → `spikes/caching.md`
+- `/brain add found a bug` → Append text to active doc
 
 ## Quick Reference
 
 ```
-/brain {topic}              # SEARCH for existing doc (default action)
-/brain plan {topic}         # CREATE new planning doc
-/brain research {topic}     # CREATE new research doc
-/brain idea {text}          # Quick capture to ideas/
-/brain check                # Address @droid comments
+/brain search {topic}           # Search for existing doc
+/brain search {topic} -- {q}    # Search, load, then execute follow-up
+/brain {category} {topic}       # Create doc → {category}s/{topic}.md
+/brain add {text}               # Append to active doc
+/brain check                    # Address @droid comments
 ```
 
-**Default behavior:** When given just a topic, SEARCH first (don't create unless plan/research/review keyword is present).
+**Reserved keywords:** `search`, `add`, `check`, `done` - everything else is a category.
 
-See the **brain skill** for complete documentation and procedures.
+See the **brain skill** for complete documentation.

package/dist/tools/brain/commands/scratchpad.md

@@ -11,18 +11,16 @@ description: "Alias for brain. See brain skill for full behavior."
 
 ## Examples
 
-- `/scratchpad auth-refactor` → Search for existing doc about "auth-refactor"
-- `/scratchpad plan new-feature` → Create a new planning doc for "new-feature"
+- `/scratchpad search auth-refactor` → Search for existing doc
+- `/scratchpad plan new-feature` → Create a new planning doc
 
 ## Quick Reference
 
 Same as `/brain` - use whichever name feels natural:
 
 ```
-/scratchpad {topic}         # SEARCH for existing doc
-/scratchpad plan {topic}    # CREATE new planning doc
+/scratchpad search {topic}      # Search for existing doc
+/scratchpad {category} {topic}  # Create doc
 ```
 
-**Default behavior:** SEARCH first, don't create unless plan/research/review keyword is present.
-
 See `/brain` or the **brain skill** for complete documentation.

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

@@ -1,7 +1,7 @@
 ---
 name: brain
 description: "Collaborative scratchpad for planning and research. Use when planning a feature, exploring a problem, or capturing thinking that should persist across sessions. User prompts like 'let's think through', 'open a scratchpad', 'plan this out', 'use our brain'."
-argument-hint: "[{topic} | plan|research|review {topic} | idea|add {text} | check|done]"
+argument-hint: "[search {topic} | {category} {topic} | add {text} | check | done]"
 allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
@@ -11,21 +11,12 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 
 > **Alias:** All `/brain` commands also work as `/scratchpad` - use whichever feels natural.
 
-## Why Brain Docs?
-
-Ideas develop through iteration, not single prompts.
-
-- **Thinking space** - Work through problems before committing to code
-- **Async collaboration** - Leave `@mentions` for discussion across sessions (see comments skill for full support)
-- **Persistent context** - Docs survive after chat history disappears
-
 ## When to Use
 
 - Planning implementation for a feature
 - Researching a problem or technology
 - Design work that benefits from written iteration
 - User says "brain", "scratchpad", "let's think through", "plan this out"
-- Optionally, to capture output from plan mode sessions
 
 ## When NOT to Use
 
@@ -35,110 +26,86 @@ Ideas develop through iteration, not single prompts.
 
 ## Configuration
 
-**IMPORTANT:** Before using any default paths, ALWAYS read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is configured there, use that path. Only fall back to defaults if the file doesn't exist or lacks a `brain_dir` setting.
-
-| Setting        | Default     | Description                                |
-| -------------- | ----------- | ------------------------------------------ |
-| `brain_dir`    | (see below) | Where docs are stored                      |
-| `inbox_folder` | (empty)     | Root folder for new docs (e.g., `0-Inbox`) |
-
-Default `brain_dir` by AI tool (only if not configured):
+**IMPORTANT:** Read `~/.droid/skills/brain/overrides.yaml` first. If `brain_dir` is not configured, **ask the user** where they want brain docs stored.
 
-- **claude-code**: `~/.claude/brain`
-- **opencode**: `~/.config/opencode/brain`
+| Setting        | Default | Description                                |
+| -------------- | ------- | ------------------------------------------ |
+| `brain_dir`    | (none)  | Where docs are stored - **must be configured** |
+| `inbox_folder` | (empty) | Root folder for new docs (e.g., `0-Inbox`) |
 
-## Folder Structure
+**If not configured:** Ask the user:
+> "Where would you like to store brain docs? Common choices:
+> - `~/Documents/brain` - Easy to find in Finder
+> - `~/src/github.com/brain` - With your other repos
+> - An existing Obsidian vault path"
 
-Docs are organized by type into subfolders:
-
-```
-{brain_dir}/
-└── {inbox_folder}/     # e.g., "0-Inbox" (or root if not set)
-    ├── plans/          # Structured planning docs
-    ├── research/       # Open-ended exploration
-    ├── reviews/        # Code reviews, evaluations
-    └── ideas/          # Quick captures
+Then write their choice to `~/.droid/skills/brain/overrides.yaml`:
+```yaml
+brain_dir: "{user's choice}"
 ```
 
-Folders are created automatically when needed.
-
-## Core Concepts
+## Commands
 
-**Active doc:** Opening or creating a brain doc makes it "active" for the session. Subsequent `/brain add` commands append to it without specifying a path.
+**Reserved keywords:** `search`, `add`, `check`, `done`
 
-**Doc types:** (each stored in its own folder)
+| Command                                      | Action                                                 |
+| -------------------------------------------- | ------------------------------------------------------ |
+| `/brain`                                     | List recent docs or create new                         |
+| `/brain search {topic}`                      | Search for existing doc (fuzzy match) → becomes active |
+| `/brain search {topic} -- {instruction}`     | Search, load, then execute follow-up instruction       |
+| `/brain {category} {topic}`                  | Create doc → `{category}s/{topic}.md`                  |
+| `/brain add {text}`                          | Append to active doc                                   |
+| `/brain check`                               | Address @droid comments in active doc                  |
+| `/brain done`                                | Finalize active doc, update status                     |
 
+**Category is any non-reserved word.** Common categories:
 - `plan` → `plans/` - Structured: Context → Exploration → Decision → Next Steps
-- `research` → `research/` - Open-ended exploration of a topic
-- `review` → `reviews/` - Code review, document review, or any evaluation task
-- `idea` → `ideas/` - Quick capture (fire-and-forget, doesn't become active)
-
-**Comment conventions:** In markdown files, ALWAYS use blockquote `>` prefix for @mention comments:
-
-- `> @droid` - **User** leaves comment for AI to address
-- `> @{user}` - **AI** leaves comment for user to address
-
-**CRITICAL:** When YOU (the AI) respond to a comment or create a placeholder, you MUST use `> @{user_mention}` (e.g., `> @fry`). NEVER use `@droid` for your own responses - that tag is for the USER to address YOU.
-
-Example conversation:
-
-```markdown
-> @droid Should we add caching here?
-
-> @fry Yes, Redis would work well for this use case.
+- `research` → `research/` - Open-ended exploration
+- `review` → `reviews/` - Code review, evaluations
+- `idea` → `ideas/` - Quick captures
+
+But users can create any category on the fly:
+```bash
+/brain spike auth-caching        → spikes/auth-caching.md
+/brain meeting standup-jan-17    → meetings/standup-jan-17.md
+/brain design api-v2             → designs/api-v2.md
+/brain retro q4-launch           → retros/q4-launch.md
 ```
 
-Read user's configured mention from `~/.droid/config.yaml` → `user_mention` (e.g., `@fry`). If droid's `comments` skill is installed, use `/comments check` for full support.
-
-**Status lifecycle:** `exploring` → `drafting` → `decided` → `done`
-
-## Commands
-
-| Command                   | Action                                                     |
-| ------------------------- | ---------------------------------------------------------- |
-| `/brain`                  | List recent docs or create new                             |
-| `/brain {topic}`          | **Search** for existing doc (fuzzy match) → becomes active |
-| `/brain plan {topic}`     | Create planning doc → `plans/{topic}.md`                   |
-| `/brain research {topic}` | Create research doc → `research/{topic}.md`                |
-| `/brain review {topic}`   | Create review doc → `reviews/{topic}.md`                   |
-| `/brain idea {text}`      | Quick capture → `ideas/{date}-{slug}.md` (not active)      |
-| `/brain add {text}`       | Append to active doc                                       |
-| `/brain check`            | Address @droid comments in active doc                      |
-| `/brain done`             | Finalize active doc, update status                         |
-
-**IMPORTANT:** The default action for `/brain {topic}` is to **SEARCH** for existing docs, NOT create. Only use `/brain plan {topic}` or `/brain research {topic}` when the user explicitly wants to create a new doc.
-
 ## Opening a Doc
 
-**Trigger:** `/brain {topic}` or user asks to open a brain doc
+**Trigger:** `/brain search {topic}` or user asks to open a brain doc
 
-**TLDR:** Search for and open an existing doc. Fuzzy-match topic against existing docs, read content, set as active.
+Search for and open an existing doc. Fuzzy-match topic against existing docs, read content, set as active.
+
+**Follow-up instructions:** Use `--` to add an instruction to execute after loading:
+```bash
+/brain search auth refactor -- what's left to do?
+/brain search droid plans -- summarize the decisions
+```
 
 Full procedure: `references/workflows.md` § Opening
 
 ## Creating a Doc
 
-**Trigger:** `/brain plan {topic}` or `/brain research {topic}`
-
-**TLDR:** Create doc from template, set as active, gather initial context.
-
-Full procedure: `references/workflows.md` § Creating
-Templates: `references/templates.md`
-Naming: `references/naming.md`
+**Trigger:** `/brain {category} {topic}`
 
-## Quick Ideas
+1. Parse first arg - if not a reserved keyword, it's the category
+2. Pluralize category for folder name (add 's')
+3. Create `{brain_dir}/{inbox_folder}/{category}s/{topic}.md` from template
+4. Set as active doc for the session
 
-**Trigger:** `/brain idea {text}`
+Templates vary by category (see `references/templates.md`), but all follow the same creation flow.
 
-**TLDR:** Fire-and-forget capture to `ideas/` folder. Does not become active doc.
+**Note:** `idea` category docs do NOT become active (fire-and-forget capture).
 
-Full procedure: `references/workflows.md` § Ideas
+Full procedure: `references/workflows.md` § Creating
 
 ## Adding Content
 
 **Trigger:** `/brain add {text}`
 
-**TLDR:** Append text to active doc with timestamp.
+Append text to active doc with timestamp.
 
 Full procedure: `references/workflows.md` § Adding
 
@@ -146,7 +113,7 @@ Full procedure: `references/workflows.md` § Adding
 
 **Trigger:** `/brain check`
 
-**TLDR:** Invoke `/comments check {active_doc_path}`. If unavailable, find `> @droid` comments and address each (preserve original, add response below).
+Find `> @droid` comments in active doc and address each. Preserve original comment, add response below with `> @{user_mention}`.
 
 Full procedure: `references/workflows.md` § Checking
 
@@ -154,29 +121,19 @@ Full procedure: `references/workflows.md` § Checking
 
 **Trigger:** `/brain done`
 
-**TLDR:** Review doc, update status to `done`, suggest next steps.
+Review doc, update status to `done`, suggest next steps.
 
 Full procedure: `references/workflows.md` § Finalizing
 
-## Extensions
-
-Before creating or modifying brain docs, check if any `brain-*` extension skills are installed:
-
-```
-# Claude Code
-~/.claude/skills/brain-*/SKILL.md
+## Comment Conventions
 
-# OpenCode
-~/.config/opencode/skills/brain-*/SKILL.md
+In markdown files, use blockquote `>` prefix for @mention comments:
 
-# Shared (droid config)
-~/.droid/skills/brain-*/SKILL.md
-```
+- `> @droid` - **User** leaves comment for AI to address
+- `> @{user}` - **AI** leaves comment for user
 
-If found (e.g., `brain-obsidian`), **ALWAYS** use the extension's templates, workflows, and configuration instead of this skill's defaults. Extensions may provide:
+Get `user_mention` from `droid config brain`. If droid's `comments` skill is installed, use `/comments check` for full support.
 
-- Alternative template formats (YAML frontmatter, wikilinks)
-- Folder organization (PARA structure)
-- Additional commands or integrations
+## Extensions
 
-The base brain skill provides simple markdown. Extensions layer on advanced features.
+Check for `brain-*` extension skills in `~/.claude/skills/`, `~/.config/opencode/skills/`, or `~/.droid/skills/`. If found, use extension's templates and workflows instead of defaults.

package/dist/tools/brain/skills/brain/references/templates.md

@@ -1,8 +1,40 @@
 # Brain Doc Templates
 
-Templates for each doc type. All templates use simple markdown.
+Templates for brain docs. Use the **Generic Template** for user-defined categories.
 
-## Plan Template
+## Generic Template (for any category)
+
+Use this for user-defined categories like `spike`, `meeting`, `design`, `retro`, etc.
+
+```markdown
+# {Topic}
+
+**Type:** {category}
+**Status:** active
+**Created:** {date}
+
+{Brief description based on category and topic}.
+
+## Notes
+
+{Content area - adapt sections based on what makes sense for this category}
+```
+
+The AI should adapt the sections based on the category name:
+- `spike` → Background, Findings, Conclusion
+- `meeting` → Attendees, Discussion, Action Items
+- `design` → Context, Proposal, Trade-offs
+- `retro` → What Went Well, What Didn't, Actions
+
+Keep it simple - start with minimal structure and let the user expand.
+
+---
+
+## Common Category Templates
+
+These templates are for the most common categories. For any other category, use the Generic Template above.
+
+### Plan Template
 
 ```markdown
 # {Topic}
@@ -30,7 +62,7 @@ What we chose and why.
 - [ ] Action items
 ```
 
-## Research Template
+### Research Template
 
 ```markdown
 # {Topic}
@@ -54,7 +86,7 @@ What we've learned.
 Key takeaways.
 ```
 
-## Review Template
+### Review Template
 
 ```markdown
 # {Topic}
@@ -82,7 +114,7 @@ Suggested changes or actions.
 Overall assessment.
 ```
 
-## Idea Template
+### Idea Template
 
 ```markdown
 # {Brief Title}