@orderful/droid 0.37.0 → 0.38.0

package/src/lib/types.ts

@@ -2,6 +2,7 @@ export enum Platform {
   ClaudeCode = 'claude-code',
   OpenCode = 'opencode',
   Cursor = 'cursor',
+  OpenAICodex = 'openai-codex',
 }
 
 // Backwards compatibility alias - using different names to avoid redeclare error

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "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",
@@ -12,5 +12,12 @@
     "droid",
     "ai",
     "brain"
+  ],
+  "skills": [
+    "./skills/brain/SKILL.md",
+    "./skills/brain-obsidian/SKILL.md"
+  ],
+  "commands": [
+    "./commands/brain.md"
   ]
 }

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.3.9
+version: 0.4.0
 status: beta
 
 includes:

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

@@ -32,6 +32,7 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 | -------------- | ------- | ------------------------------------------ |
 | `brain_dir`    | (none)  | Where docs are stored - **must be configured** |
 | `inbox_folder` | (empty) | Root folder for new docs (e.g., `0-Inbox`) |
+| `override`     | (none)  | User-defined behaviour overrides |
 
 **If not configured:** Ask the user:
 > "Where would you like to store brain docs? Common choices:
@@ -39,11 +40,13 @@ Your **scratchpad** (or **brain**) - a collaborative space for planning, researc
 > - `~/src/github.com/brain` - With your other repos
 > - An existing Obsidian vault path"
 
-Then write their choice to `~/.droid/skills/brain/overrides.yaml`:
-```yaml
-brain_dir: "{user's choice}"
+Then set their choice:
+```bash
+droid config --set tools.brain.brain_dir="{user's choice}"
 ```
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides for how to create, register, and use overrides.
+
 ## Commands
 
 **Reserved keywords:** `search`, `add`, `check`, `cleanup`, `done`

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

@@ -14,7 +14,11 @@ Detailed procedures for each brain operation.
    - If `brain_dir` is not configured, **ask the user** where they want brain docs stored
    - **Do NOT skip this step or assume defaults**
 
-2. **Search for matches**
+2. **Check for override** (see `/droid` skill § Override Lookup)
+   - If override applies for `search` command, follow override instructions instead of step 3
+   - Fall back to step 3 if override fails
+
+3. **Search for matches** (default behaviour)
 
    ```
    Glob: {brain_dir}/**/*{topic}*.md
@@ -22,20 +26,20 @@ Detailed procedures for each brain operation.
 
    Fuzzy match the topic against doc filenames
 
-3. **Handle results:**
+4. **Handle results:**
    - **No matches**: Offer to create a new doc with that topic
    - **One match**: Open it
    - **Multiple matches**: Present list, let user choose
 
-4. **Read the doc** and summarize key points:
+5. **Read the doc** and summarize key points:
    - Current status
    - Main topic/context
    - Any open `@droid` comments
    - Recent updates
 
-5. **Set as active doc** - Remember path for subsequent `/brain add` and `/brain check` commands
+6. **Set as active doc** - Remember path for subsequent `/brain add` and `/brain check` commands
 
-6. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded doc
+7. **If `-- {instruction}` provided:** Execute the follow-up instruction against the loaded doc
 
 ## Creating
 

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

@@ -33,6 +33,8 @@ droid config --set tools.brain.brain_dir=~/path/to/your/vault
 | `areas_folder`     | `1-Areas`     | Area docs (PARA only)           |
 | `resources_folder` | `3-Resources` | Reference material (PARA only)  |
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## What This Adds
 
 | Feature             | Description                                |

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "coach"
+  ],
+  "skills": [
+    "./skills/coach/SKILL.md"
+  ],
+  "commands": [
+    "./commands/coach.md"
   ]
 }

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

@@ -52,6 +52,9 @@ plan → AI scaffolds → human implements → AI coaches → iterate → ship
 | Setting              | Default  | Description                                             |
 | -------------------- | -------- | ------------------------------------------------------- |
 | `scaffold_verbosity` | `medium` | How detailed hints are: `minimal`, `medium`, `detailed` |
+| `override`           | (none)   | User-defined behaviour overrides                        |
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
 <!-- Note: @mention is the target, not author. @{user} = AI talking TO user, @droid = user talking TO AI -->
 > @{user} Not yet - droid currently shows config as free text input. But we could add an `enum` type to the config schema that presents as a select dropdown in the TUI. Good feature request - want me to create an issue for it?

package/src/tools/code-review/.claude-plugin/plugin.json

@@ -12,5 +12,17 @@
     "droid",
     "ai",
     "code-review"
+  ],
+  "skills": [
+    "./skills/code-review/SKILL.md"
+  ],
+  "commands": [
+    "./commands/code-review.md"
+  ],
+  "agents": [
+    "./agents/edi-standards-reviewer.md",
+    "./agents/error-handling-reviewer.md",
+    "./agents/test-coverage-analyzer.md",
+    "./agents/type-reviewer.md"
   ]
 }

package/src/tools/code-review/skills/code-review/SKILL.md

@@ -16,6 +16,8 @@ Code-review has no configuration of its own. Optional integration with other too
 - **Brain skill** (optional): If installed, offers to save review results to a `/brain review` doc
   - Check with: `droid config --get tools.brain` to see if `brain_dir` is configured
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## How It Works
 
 The `/code-review` command orchestrates multiple specialized agents in parallel:

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

@@ -12,5 +12,14 @@
     "droid",
     "ai",
     "codex"
+  ],
+  "skills": [
+    "./skills/codex/SKILL.md"
+  ],
+  "commands": [
+    "./commands/codex.md"
+  ],
+  "agents": [
+    "./agents/codex-document-processor.md"
   ]
 }

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

@@ -82,6 +82,9 @@ If prerequisites fail, guide user to fix:
 |---------|---------|-------------|
 | codex_repo | ~/src/github.com/orderful-codex | Path to local codex repo |
 | freshness_days | 30 | Days before staleness warning |
+| override | (none) | User-defined behaviour overrides |
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
 ## Commands
 

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "comments"
+  ],
+  "skills": [
+    "./skills/comments/SKILL.md"
+  ],
+  "commands": [
+    "./commands/comments.md"
   ]
 }

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

@@ -122,8 +122,13 @@ ai_mentions: "@claude"
 
 # Keep comments after addressing them (default: true)
 preserve_comments: true
+
+# User-defined behaviour overrides (see /droid skill)
+override: ...
 ```
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## File Type Support
 
 Works in any text file. Respects `.gitignore` and skips common build directories (node_modules, dist, .git, etc.).

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

@@ -1,6 +1,6 @@
 {
   "name": "droid",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "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.",
   "author": {
     "name": "Orderful",
@@ -11,5 +11,12 @@
   "keywords": [
     "droid",
     "ai"
+  ],
+  "skills": [
+    "./skills/droid/SKILL.md",
+    "./skills/droid-bootstrap/SKILL.md"
+  ],
+  "commands": [
+    "./commands/setup.md"
   ]
 }

package/src/tools/droid/TOOL.yaml

@@ -1,6 +1,6 @@
 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.3
+version: 0.7.0
 status: beta
 
 # System tool - always stays current regardless of auto-update settings
@@ -12,7 +12,9 @@ includes:
       required: true
     - name: droid-bootstrap
       required: true
-  commands: []
+  commands:
+    - name: setup
+      is_alias: false
   agents: []
 
 dependencies: []

package/src/tools/droid/commands/setup.md

@@ -0,0 +1,125 @@
+---
+name: setup
+description: "Configure Droid after marketplace installation"
+argument-hint: ""
+---
+
+# /setup
+
+**User invoked:** `/setup`
+
+**Your task:** Guide the user through initial Droid configuration.
+
+## When to Use
+
+Run this command after installing Droid plugins via the marketplace (when `~/.droid/config.yaml` doesn't exist).
+
+## Configuration Flow
+
+### 1. Check Existing Configuration
+
+```bash
+ls -la ~/.droid/config.yaml 2>/dev/null || echo "No config found"
+```
+
+- If config exists: Ask "You already have a config. Reconfigure? [y/N]"
+- If no config: Proceed with setup
+
+### 2. Create Config Directory
+
+```bash
+mkdir -p ~/.droid
+```
+
+### 3. Detect Git Username
+
+```bash
+git config user.name
+```
+
+Store this for `git_username` in config.
+
+### 4. Gather Global Settings
+
+Ask the user:
+
+> **What handle should be used for @mentions in code comments?**
+> (This is used by the comments tool for async collaboration)
+> Default: `@droid`
+
+### 5. Detect Installed Tools
+
+Check which Droid plugins are installed by looking for skill files:
+
+```bash
+# Check Claude Code skills directory and plugin cache
+ls ~/.claude/skills/ 2>/dev/null | grep -E '^(brain|project|codex|wrapup|code-review|tech-design|comments|coach|plan)-' || true
+find ~/.claude/plugins/cache -name "SKILL.md" -path "*droid*" 2>/dev/null | head -20 || true
+```
+
+### 6. Configure Tools That Need Settings
+
+For each detected tool that requires configuration:
+
+**brain:**
+> **Where should brain docs be stored?**
+> Default: `~/brain`
+> (This directory will be created if it doesn't exist)
+
+**project:**
+> **Where are your projects located?**
+> Default: `~/Projects`
+> (Used to find and link project-level context)
+
+**codex:**
+> **Where is your shared codex repository?**
+> Default: `~/codex`
+> (Leave blank to skip codex configuration)
+
+### 7. Write Configuration
+
+Create `~/.droid/config.yaml` with the gathered settings:
+
+```yaml
+# Droid global configuration
+# Generated by /setup
+
+user_mention: "@droid"  # Or user's chosen handle
+git_username: "detected-name"
+
+# Tool-specific settings
+brain:
+  brain_dir: "~/brain"
+
+project:
+  projects_dir: "~/Projects"
+
+codex:
+  codex_dir: "~/codex"  # Only if provided
+```
+
+### 8. Confirm Success
+
+Display a summary:
+
+```
+Droid configured successfully!
+
+Global settings:
+  - User mention: @droid
+  - Git username: Your Name
+
+Tool settings:
+  - brain: ~/brain
+  - project: ~/Projects
+  - codex: ~/codex
+
+You can edit these settings anytime at ~/.droid/config.yaml
+```
+
+## Notes
+
+- All paths should be expanded (~ to full home directory) when written
+- Only include tool sections for tools that are actually installed
+- If a required directory doesn't exist, offer to create it
+- Skip tools that aren't installed rather than configuring them

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

@@ -1,7 +1,7 @@
 ---
 name: droid
-description: "Core droid meta-skill for updates, tool discovery, and usage help. Use when checking for droid updates, discovering available tools, or answering 'how do I...' questions about droid workflows. User prompts like 'any droid updates?', 'what tools do I have?', 'what tools do you have?', 'remind me what tools you have', 'hey droid what can you do', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?'."
-allowed-tools: [Bash]
+description: "Core droid meta-skill for updates, tool discovery, usage help, and skill overrides. Use when checking for droid updates, discovering available tools, answering 'how do I...' questions about droid workflows, or customizing skill behaviour. User prompts like 'any droid updates?', 'what tools do I have?', 'what tools do you have?', 'remind me what tools you have', 'hey droid what can you do', 'how do I add context?', 'remind me how to use codex', 'what's the best way to start a session?', 'customize brain search', 'create an override for brain'."
+allowed-tools: [Bash, Read, Write]
 ---
 
 # Droid
@@ -87,3 +87,118 @@ When answering "how do I..." questions:
 1. `/project search {name}` - Load working context
 2. `/codex search {topic}` - Find relevant org knowledge (if needed)
 3. Then start working with full context
+
+## Skill Overrides
+
+Users can customize skill behaviour by creating override files in `~/.droid/skill_overrides/`.
+
+**When:** User asks to customize a skill, use a different tool for a command, or mentions overrides.
+
+### Creating an Override
+
+1. **Explain** the override system:
+   - Override files live in `~/.droid/skill_overrides/{skill}.md`
+   - Use YAML frontmatter to declare which commands are overridden
+   - Template available at `~/.droid/skill_overrides/_template.md`
+
+2. **Create** the override file with proper structure:
+   ```markdown
+   ---
+   overrides: [command1, command2]
+   ---
+
+   ## command1
+
+   Custom instructions for this command...
+   ```
+
+3. **Register** the override in config:
+   ```bash
+   # Set override path (use tool name in config path, skill name for file)
+   droid config --set tools.{tool}.override.path="~/.droid/skill_overrides/{skill}.md"
+
+   # Set overridden commands (as JSON array)
+   droid config --set tools.{tool}.override.commands='["command1", "command2"]'
+
+   # Enable the override (can toggle off later)
+   droid config --set tools.{tool}.override.enabled=true
+   ```
+
+   Note: Config uses tool name (e.g., `tools.brain`), file uses skill name. Usually the same, but tools can contain multiple skills.
+
+   **Toggle off:** `droid config --set tools.{tool}.override.enabled=false` to disable without removing.
+
+4. **Confirm** the override is active
+
+### Registering an Existing Override
+
+If user says "I added an override for {tool}" or "register my {tool} override":
+
+1. **Read** `~/.droid/skill_overrides/{skill}.md`
+2. **Parse** YAML frontmatter to extract `overrides: [...]` array
+3. **Register** using the config commands above (with tool name in config path)
+4. **Confirm** registration
+
+### Override Visibility
+
+When an override is active, skills show:
+```
+[override] brain/search → ~/.droid/skill_overrides/brain.md
+```
+
+This helps users know customisation is being used and where to find it.
+
+### Example: qmd for Brain Search
+
+User: "I want brain search to use qmd for semantic search"
+
+Create `~/.droid/skill_overrides/brain.md`:
+```markdown
+---
+overrides: [search]
+---
+
+## search
+
+Use qmd for semantic search instead of filename matching.
+
+**Prerequisites:** qmd installed, brain collection indexed (`qmd index brain -p {brain_dir}`)
+
+**Workflow:**
+
+1. Check if qmd collection exists: `qmd ls brain`
+2. If exists, run: `qmd query "{query}" -c brain -n 10 --files`
+3. Parse CSV output (format: `docid,score,filepath,context`)
+4. Extract filepath (field 3) from each row
+5. Present matches sorted by score
+6. If qmd fails or collection doesn't exist, fall back to Glob: `{brain_dir}/**/*{query}*.md`
+```
+
+Then register:
+```bash
+droid config --set tools.brain.override.path="~/.droid/skill_overrides/brain.md"
+droid config --set tools.brain.override.commands='["search"]'
+droid config --set tools.brain.override.enabled=true
+```
+
+### Override Lookup (for all skills)
+
+When executing any skill command, check for overrides:
+
+1. **Get tool config:** `droid config --get tools.{tool}`
+
+2. **Check if override applies:**
+   - Config has `override` section AND
+   - `override.enabled` is `true` (or not set) AND
+   - `override.commands` includes the current command
+
+3. **If override applies:**
+   - Show: `[override] {skill}/{command} → {override.path}`
+   - Read the override file at `override.path`
+   - Find the `## {command}` section
+   - Follow those instructions instead of default workflow
+   - If override fails or instructions unclear, fall back to default
+
+4. **If no override:** Use default skill behaviour
+
+This lookup is the same for all skills - config is per-tool, but the lookup workflow is universal.

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "plan"
+  ],
+  "skills": [
+    "./skills/plan/SKILL.md"
+  ],
+  "commands": [
+    "./commands/plan.md"
   ]
 }

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

@@ -28,6 +28,8 @@ Uses config from dependencies:
 - `droid config --get tools.brain` → `brain_dir`, `inbox_folder`
 - `droid config --get user_mention` → `user_mention` (global config)
 
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
+
 ## Commands
 
 | Command                | Action                                              |

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

@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "project"
+  ],
+  "skills": [
+    "./skills/project/SKILL.md"
+  ],
+  "commands": [
+    "./commands/project.md"
   ]
 }

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

@@ -32,6 +32,9 @@ Chat history disappears. Projects persist.
 | -------------- | ------------ | -------------------------------------------------- |
 | `projects_dir` | **required** | Where projects are stored (must be configured)     |
 | `preset`       | `markdown`   | Output format: `markdown` or `obsidian`            |
+| `override`     | (none)       | User-defined behaviour overrides                   |
+
+**Overrides:** This skill supports user-defined overrides. See `/droid` skill § Skill Overrides.
 
 If `projects_dir` is not configured, inform the user they need to set it up:
 ```bash

package/src/tools/tech-design/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-tech-design",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review).",
   "author": {
     "name": "Orderful",
@@ -12,5 +12,11 @@
     "droid",
     "ai",
     "tech-design"
+  ],
+  "skills": [
+    "./skills/tech-design/SKILL.md"
+  ],
+  "commands": [
+    "./commands/tech-design.md"
   ]
 }

package/src/tools/tech-design/TOOL.yaml

@@ -1,6 +1,6 @@
 name: tech-design
 description: "Technical design authoring tool for engineers. Create structured tech design docs with /tech-design start, iterate in brain, publish to codex. Three-document approach: research doc (codebase discoveries) + thought doc (design workspace) + roll-up (clean summary for review)."
-version: 0.2.5
+version: 0.3.0
 status: beta
 
 includes:

package/src/tools/tech-design/commands/tech-design.md

@@ -13,6 +13,7 @@ argument-hint: "[start --from codex:{project} | draft [section] | think [topic]
 ## Examples
 
 - `/tech-design start --from codex:billing-v2` → Create research + thought docs from codex project
+- `/tech-design search billing` → Find and resume existing billing design
 - `/tech-design draft rollout` → Auto-generate the rollout section
 - `/tech-design think API design` → Guided exploration of API design, update research doc
 - `/tech-design gaps` → Show checklist of missing/empty sections
@@ -22,6 +23,7 @@ argument-hint: "[start --from codex:{project} | draft [section] | think [topic]
 
 ```
 /tech-design start --from codex:{project}  # Create research + thought docs
+/tech-design search {term}                 # Find and resume existing design
 /tech-design draft [section]               # Auto-generate section
 /tech-design think [topic]                 # Guided exploration
 /tech-design gaps                          # Missing sections checklist