@orderful/droid 0.31.0 → 0.31.2

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

@@ -169,22 +169,32 @@ The codex has five categories:
 | `/codex domains`                       | List all domains                                |
 | `/codex proposals`                     | List all proposals                              |
 | `/codex patterns`                      | List all patterns                               |
-| `/codex topics`                        | List all topics                                 |
-| `/codex {name}`                        | Load entry (searches all categories)            |
-| `/codex search {query}`                | Search across everything                        |
-| `/codex new {name}`                    | Scaffold new project (shorthand)                |
-| `/codex new project {name}`            | Scaffold new project from templates             |
-| `/codex new domain {name}`             | Scaffold new domain entry                       |
-| `/codex new proposal {name}`           | Scaffold new proposal entry                     |
-| `/codex new pattern {name}`            | Scaffold new pattern entry                      |
-| `/codex new topic {name}`              | Scaffold new topic entry                        |
-| `/codex decision {text}`               | Append to active project's DECISIONS.md         |
+| `/codex topics`                              | List all topics                                         |
+| `/codex search {query}`                      | Search and load entry (searches all categories)         |
+| `/codex search {query} -- {instruction}`     | Search, load, then execute follow-up instruction        |
+| `/codex {category} search {query}`           | Search within a specific category only                  |
+| `/codex new {category} {name}`               | Scaffold new entry (project/domain/proposal/pattern/topic) |
+| `/codex decision {text}`                     | Append to active project's DECISIONS.md                 |
 | `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent)       |
 | `/codex artifact {file} {project}`     | Add supporting artifact to project (uses agent) |
 
 ## Loading an Entry
 
-**Trigger:** `/codex {name}` or user asks to load/check codex for something
+**Trigger:** `/codex search {query}` or user asks to load/check codex for something
+
+**Category-scoped search:** Narrow search to a specific category:
+```bash
+/codex topics search auth           # Search within topics only
+/codex patterns search webhook      # Search within patterns only
+/codex projects search transaction  # Search within projects only
+```
+
+**Follow-up instructions:** Use `--` to add an instruction to execute after loading:
+```bash
+/codex search transaction-templates -- summarize the PRD
+/codex topics search auth -- is this still accurate?
+```
+Parse args by splitting on ` -- `. First part = search terms, second part = instruction to execute after loading.
 
 **Procedure:**
 
@@ -257,7 +267,7 @@ codebase_paths:
 
 Scoped operations (`decision`, `snapshot`) require an active project:
 
-- When user loads a project via `/codex {project-name}`, set it as active
+- When user loads a project via `/codex search {project-name}`, set it as active
 - Store active project name in session context
 - If scoped operation called with no active project → show project list, let user pick
 
@@ -352,59 +362,16 @@ Artifacts get lighter frontmatter with `type: artifact` and source like `intervi
 
 ## Creating New Entries
 
-The `/codex new` command scaffolds new entries from templates:
-
-```bash
-/codex new {name}              # Shorthand for new project
-/codex new project {name}      # Explicit project creation
-/codex new domain {name}       # New domain entry
-/codex new proposal {name}     # New proposal entry
-/codex new pattern {name}      # New pattern entry
-/codex new topic {name}        # New topic entry
-```
-
-### Projects
-
-**Trigger:** `/codex new {name}` or `/codex new project {name}`
-
-**Procedure:**
-
-1. **Run `git-start-write`** with branch `codex/new-{name}`
-2. Create `{codex_repo}/projects/{name}/`
-3. Copy templates: PRD.md, TECH-DESIGN.md, DECISIONS.md
-4. Fill in frontmatter with today's date
-5. **Run `git-finish-write`** with appropriate commit message and PR title
+**Trigger:** `/codex new {category} {name}`
 
-### Domains
+**Categories:** `project` | `domain` | `proposal` | `pattern` | `topic`
 
-**Trigger:** `/codex new domain {name}`
-
-**Procedure:**
-
-1. **Run `git-start-write`** with branch `codex/domain-{name}`
-2. Create `{codex_repo}/domains/{name}.md` from template
-3. Fill in frontmatter, guide user through sections
-4. **Run `git-finish-write`** with appropriate commit message and PR title
-
-### Proposals
-
-**Trigger:** `/codex new proposal {name}`
-
-**Procedure:**
-
-1. **Run `git-start-write`** with branch `codex/proposal-{name}`
-2. Create `{codex_repo}/proposals/{name}.md` from template
-3. Fill in frontmatter, guide user through sections
-4. **Run `git-finish-write`** with appropriate commit message and PR title
-
-### Patterns and Topics
-
-**Trigger:** `/codex new pattern {name}` or `/codex new topic {name}`
-
-**Procedure:**
+**Procedure** (same for all categories):
 
-1. **Run `git-start-write`** with branch `codex/{pattern|topic}-{name}`
-2. Create file from template
+1. **Run `git-start-write`** with branch `codex/{category}-{name}`
+2. Create entry from template:
+   - `project` → folder with PRD.md, TECH-DESIGN.md, DECISIONS.md
+   - Others → single file at `{codex_repo}/{category}s/{name}.md`
 3. Fill in frontmatter with today's date
 4. **Run `git-finish-write`** with appropriate commit message and PR title
 
@@ -415,7 +382,7 @@ Full procedure: `references/creating.md`
 The codex holds **shared** organizational knowledge. The `/project` skill holds **personal** working memory.
 
 ```
-/codex transaction-templates              → load shared context
+/codex search transaction-templates       → load shared context
 /project create --from codex:{name}       → seed personal PROJECT.md
 /codex publish                            → promote learnings back (future)
 ```

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

@@ -5,7 +5,7 @@ Detailed procedure for scaffolding new project entries in the codex.
 ## When to Use
 
 - Starting work on a new feature/project
-- `/codex new {name}` command
+- `/codex new project {name}` command
 - User asks to create a codex entry for something new
 
 ## Procedure
@@ -25,7 +25,7 @@ ls {codex_repo}/projects/ | grep -i {name}
 If exists:
 ```
 A project named '{name}' already exists. Did you mean to load it?
-→ /codex {name}
+→ /codex search {name}
 ```
 
 ### 3. Start Write Operation

package/src/tools/codex/skills/codex/references/decisions.md

@@ -10,7 +10,7 @@ Detailed procedure for capturing decisions during implementation.
 
 ## Prerequisites
 
-- **Active project** must be set (from previous `/codex {project}` load)
+- **Active project** must be set (from previous `/codex search {project}` load)
 - If no active project, prompt user to select one first
 
 ## Procedure

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

@@ -1,6 +1,6 @@
 {
   "name": "droid",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "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",

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.2
+version: 0.5.3
 status: beta
 
 # System tool - always stays current regardless of auto-update settings

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

@@ -6,44 +6,22 @@ allowed-tools: [Bash]
 
 # Droid
 
-Core meta-skill for droid update awareness, tool discovery, and usage guidance.
-
-## Purpose
-
-1. **Update awareness** - Notify users about droid CLI updates from within Claude Code
-2. **Tool discovery** - Help users find the right tools for their workflow
+Core meta-skill for update awareness, tool discovery, and usage guidance.
 
 ## Update Checking
 
-### When to Check
-
-1. **Proactively** - Check for **droid CLI updates** once near the start of each session. This is specifically about the `@orderful/droid` npm package, not general software updates.
-2. **On request** - When user explicitly asks about droid updates ("any droid updates?", "is droid up to date?", "check droid version")
-
-### How to Check
-
-Run this command to get the latest published version:
+**When:** Once per session (proactively), or when user asks about updates.
 
+**How:**
 ```bash
+# Get latest version
 npm view @orderful/droid version 2>/dev/null
-```
 
-Compare against the installed version. To find the installed version, check:
-
-```bash
+# Get installed version
 cat ~/.droid/config.yaml | grep -A1 "droid:" | grep "version:" | awk '{print $2}'
 ```
 
-Or if droid skill isn't in config yet, check the npm global:
-
-```bash
-npm list -g @orderful/droid --depth=0 2>/dev/null | grep @orderful/droid | awk -F@ '{print $NF}'
-```
-
-### Update Notification Format
-
-When an update is available, output this notification:
-
+**Notification format** (when update available):
 ```
 [● ●] "I suggest a new strategy: let the Wookiee update."
 
@@ -51,400 +29,61 @@ Droid v{latest} is available (you have v{current}).
 Run `droid` to update, then restart Claude Code.
 ```
 
-Replace `{latest}` with the npm version and `{current}` with the installed version.
-
-### Session Tracking
-
-**Important:** Only show the update notification ONCE per session. After showing it:
-- Do not show it again in the same conversation
-- Do not repeat it even if user continues chatting
-
-If the user explicitly asks about updates again, you can confirm whether they're up to date.
-
-## Examples
-
-### Proactive Check (Session Start)
-
-User: "Help me refactor this function"
-
-*[Claude checks for droid updates as part of initial response]*
-
-```
-[● ●] "I suggest a new strategy: let the Wookiee update."
-
-Droid v0.12.0 is available (you have v0.11.0).
-Run `droid` to update, then restart Claude Code.
-
----
-
-Now, let me help you refactor that function...
-```
-
-### User Request
-
-User: "Is droid up to date?"
-
-```
-Let me check...
-
-[● ●] "I suggest a new strategy: let the Wookiee update."
-
-Droid v0.12.0 is available (you have v0.11.0).
-Run `droid` to update, then restart Claude Code.
-```
-
-Or if already up to date:
-
-```
-[● ●] Droid is up to date (v0.12.0).
-```
-
-### Already Notified This Session
-
-User: "Any other updates?"
-
-```
-I already mentioned the droid update earlier. You're on v0.11.0, latest is v0.12.0.
-Run `droid` when you're ready to update.
-```
-
-## Behaviour Notes
-
-- Keep the check quick (timeout after 3 seconds)
-- If the npm check fails (network issues), silently skip - don't error
-- The droid eyes `[● ●]` and Star Wars quote are intentional branding - always include them
-- Be helpful but not annoying - one nudge per session is enough
-
----
+**Rules:**
+- Show notification ONCE per session only
+- Keep check quick (timeout 3s)
+- If npm check fails, silently skip
+- Always include droid eyes `[● ●]` and Star Wars quote
 
 ## Tool Catalog
 
-When users ask about droid tools ("what tools do I have?", "what's available?", "what can droid do?"), use this catalog.
-
-### Checking Installed Tools
-
+**Check installed tools:**
 ```bash
 cat ~/.droid/config.yaml
 ```
 
-Look for the `tools:` section under the current platform (e.g., `claude_code:`).
-
-### Available Tools
-
-To get tool info (version, status, description), read TOOL.yaml from the droid package:
-
-```bash
-for f in $(npm root -g)/@orderful/droid/dist/tools/*/TOOL.yaml; do echo "---"; cat "$f"; done
-```
-
-**Tools:**
-
-| Tool | Description |
-|------|-------------|
-| **brain** | Collaborative scratchpad for planning and research |
-| **coach** | Learning-mode AI - scaffolds don't implement, questions don't fix |
-| **code-review** | Code review with specialized agents and confidence scoring |
-| **codex** | Shared organizational knowledge - PRDs, tech designs, patterns, topics |
-| **comments** | Inline conversations using @droid/@user markers |
-| **project** | Project context for persistent AI memory across sessions |
-
-### Tool Details
-
-#### brain
-Collaborative scratchpad for planning and research. Create docs with `/brain plan`, `/brain research`, or `/brain review`. Use @mentions for async discussion. Docs persist across sessions.
-
-**Commands:** `/brain`, `/scratchpad`
-**Optional extension:** brain-obsidian (Obsidian vault integration with YAML frontmatter and wikilinks)
-
-#### coach
-Learning-mode AI assistance - AI as coach, not crutch. Use `/coach plan` for co-authored planning, `/coach scaffold` for structure with hints, `/coach review` for Socratic questions.
-
-**Commands:** `/coach`
-**Requires:** comments tool
-
-#### code-review
-Comprehensive code review using specialized agents. Reviews PRs, staged changes, branches, or specific files with confidence scoring.
-
-**Commands:** `/code-review`
-**Agents:** edi-standards-reviewer, error-handling-reviewer, test-coverage-analyzer, type-reviewer
-
-#### codex
-Shared organizational knowledge - PRDs, tech designs, patterns, and explored topics. Load project context, search across the codex, capture decisions during implementation.
-
-**Commands:** `/codex`, `/codex projects`, `/codex search`, `/codex decision`, `/codex add topic`
-**Requires:** gh CLI, orderful-codex repo cloned locally
-
-#### comments
-Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Ideal for code review notes and async collaboration.
-
-**Commands:** `/comments check`, `/comments cleanup`
-
-#### project
-Manage project context files for persistent AI memory across sessions. Load, update, or create project context before working on multi-session features.
-
-**Commands:** `/project`, `/project update`, `/project create`
-
-### Installing Tools
-
-To install a tool:
-```bash
-droid install <tool-name>
-```
-
-Or run `droid` to open the TUI and browse available tools.
-
-### Example Responses
-
-**User:** "What droid tools do I have installed?"
-
-```
-Let me check your installed tools...
-
-[● ●] You have these droid tools installed:
-
-- **comments** (v0.2.3) - Inline @droid/@user conversations
-- **brain** (v0.2.0) - Planning and research scratchpad
-- **project** (v0.1.2) - Project context management
-
-Run `droid` to see all available tools or install new ones.
-```
-
-**User:** "What tools are available?"
-
-```
-[● ●] Here are the droid tools you can install:
-
-| Tool | What it does |
-|------|--------------|
-| brain | Planning and research scratchpad with `/brain` commands |
-| coach | Learning-mode AI that asks questions instead of giving answers |
-| code-review | PR review with specialized agents |
-| codex | Shared knowledge - PRDs, tech designs, patterns, topics |
-| comments | Inline @droid/@user conversations in any file |
-| project | Persistent project context across sessions |
-
-Run `droid install <tool>` or just `droid` to browse and install.
-```
-
-**User:** "What's the difference between brain and project?"
-
-```
-[● ●] Good question!
-
-**brain** - For ephemeral thinking: plans, research, reviews. Use `/brain plan auth-refactor` to start a planning doc, iterate with @mentions, then archive when done.
-
-**project** - For persistent context: what the project is, key decisions, current work. Load with `/project myapp` at the start of a session so I have context.
-
-They work well together: research in brain docs, capture decisions in project files.
-```
-
----
-
-## Usage Guides
-
-When users ask "how do I..." questions about droid workflows, use these guides.
-
-### Starting a Session Right
-
-**User asks:** "How do I add context?", "How do I start a session?", "Remind me how to set up context"
-
-**Answer:**
-
-```
-[● ●] Great question! Starting with context makes everything better.
-
-**Option 1: Load project context**
-`/project {name}` - Loads your project file with goals, decisions, and current work.
-
-**Option 2: Load shared knowledge**
-`/codex search {topic}` - Find relevant PRDs, tech designs, or patterns from the codex.
-
-**Option 3: Both**
-Start with `/project` for your working context, then `/codex search` if you need org knowledge.
-
-**Pro tip:** Context at the start of a thread beats adding it mid-conversation.
-```
-
-### Finding Things in the Codex
-
-**User asks:** "How do I find something in the codex?", "How do I search codex?"
-
-**Answer:**
-
-```
-[● ●] Use `/codex search {keywords}` to find content across the codex.
-
-Examples:
-- `/codex search webhooks` - Find docs mentioning webhooks
-- `/codex search partnership automation` - Find the partnership automation PRD
-- `/codex search error handling patterns` - Find relevant patterns
-
-The search looks across PRDs, tech designs, patterns, and explored topics.
-```
-
-### Loading Project Context
-
-**User asks:** "How do I load my project?", "How does project work?"
-
-**Answer:**
-
-```
-[● ●] Use `/project {name}` to load a project file.
-
-Examples:
-- `/project transaction-templates` - Load the transaction templates project
-- `/project droid` - Load the droid project context
-
-**What it gives me:**
-- Project goals and background
-- Key technical decisions and rationale
-- Current work in progress
-- Relevant code locations
-
-**Pro tip:** Load your project at the start of each session. I'll have full context immediately.
-```
-
-### Planning Before Implementing
-
-**User asks:** "How do I plan something?", "Should I plan first?"
-
-**Answer:**
-
-```
-[● ●] Yes! Planning before implementing helps me help you better.
-
-**Option 1: Brain doc (async, iterative)**
-`/brain plan {topic}` - Creates a planning doc you can iterate on with @mentions.
-
-**Option 2: Tech design (larger features)**
-`/tech-design {feature}` - For features that need research, alternatives, and rollout plans.
-
-**Why plan?**
-- I understand the full scope before writing code
-- We catch issues early, not mid-implementation
-- The plan becomes documentation
-```
-
-### Using Comments for Async Work
+**Available tools:**
 
-**User asks:** "How do comments work?", "How do I leave notes for the AI?"
+| Tool | Purpose | Key Commands |
+|------|---------|--------------|
+| **brain** | Planning and research scratchpad | `/brain {category} {topic}`, `/brain search` |
+| **coach** | Learning-mode AI (scaffolds, doesn't implement) | `/coach plan`, `/coach scaffold`, `/coach review` |
+| **code-review** | PR review with specialized agents | `/code-review`, `/code-review --pr 123` |
+| **codex** | Shared org knowledge (PRDs, tech designs, patterns) | `/codex search`, `/codex new`, `/codex decision` |
+| **comments** | Inline @droid/@user conversations | `/comments check`, `/comments cleanup` |
+| **project** | Persistent project context across sessions | `/project search`, `/project update`, `/project create` |
+| **tech-design** | Tech design authoring (three-doc approach) | `/tech-design start`, `/tech-design draft` |
 
-**Answer:**
+**Install:** `droid install <tool>` or run `droid` for TUI.
 
-```
-[● ●] Use @mentions to have async conversations in any file.
-
-**Leave a question:**
-Add `> @droid why is this pattern used here?` in a comment
-
-**Check for questions:**
-`/comments check` - I'll find and respond to all @droid mentions
-
-**Clean up:**
-`/comments cleanup` - Remove resolved comment threads
-
-Works great for code review notes and async collaboration.
-```
+## Usage Quick Reference
 
-### Learning vs Velocity Mode
+| User wants to... | Command |
+|------------------|---------|
+| Add context to thread | `/project search {name}` or `/codex search {topic}` |
+| Find something in codex | `/codex search {keywords}` |
+| Start planning | `/brain plan {topic}` or `/tech-design start` |
+| Leave note for AI | Add `> @droid {question}` then `/comments check` |
+| Learn instead of copy-paste | `/coach {command}` |
+| Review code | `/code-review` |
+| Capture a decision | `/codex decision {summary}` |
+| Update project context | `/project update` |
 
-**User asks:** "What's coach mode?", "How do I learn instead of just getting answers?"
+## Response Guidelines
 
-**Answer:**
-
-```
-[● ●] Use `/coach` when you want to learn, not just ship.
-
-**Normal mode:** I implement for you (fast, but you don't learn)
-**Coach mode:** I guide you to implement yourself (slower, but you grow)
-
-Examples:
-- `/coach plan auth-refactor` - I'll ask questions to help YOU design it
-- `/coach review my-code.ts` - I'll ask Socratic questions, not give answers
-
-Good for: learning new codebases, building skills, understanding deeply.
-```
-
-### Code Review
-
-**User asks:** "How do I get a code review?", "Can you review my changes?"
-
-**Answer:**
-
-```
-[● ●] Use `/code-review` to review code with specialized agents.
+When answering "how do I..." questions:
 
-Examples:
-- `/code-review` - Review staged changes
-- `/code-review --pr 123` - Review a specific PR
-- `/code-review src/auth/` - Review specific files
+1. **Be concise** - Give the command first, explain second
+2. **Include droid eyes** - `[● ●]` for branded responses
+3. **Suggest workflow** - Often multiple tools work together
+4. **Pro tips welcome** - Share efficiency tricks
 
-**What I check:**
-- Error handling and edge cases
-- Test coverage gaps
-- Type safety issues
-- EDI/partnership patterns (if applicable)
+**Tool comparisons:**
+- **brain vs project** - Brain for ephemeral thinking (plans, research), project for persistent context (goals, decisions)
+- **codex vs project** - Codex is shared org knowledge, project is personal working memory
+- **coach vs normal** - Coach asks questions to help you learn, normal implements for you
 
-Each finding has a confidence score so you can prioritize.
-```
-
-### Quick Reference
-
-| Question | Answer |
-|----------|--------|
-| "Add context to my thread" | `/project {name}` or `/codex search {topic}` |
-| "Find something in the codex" | `/codex search {keywords}` |
-| "Start planning" | `/brain plan {topic}` or `/tech-design {feature}` |
-| "Leave a note for AI" | Add `> @droid {question}` then `/comments check` |
-| "Learn instead of copy-paste" | `/coach {command}` |
-| "Review my code" | `/code-review` |
-| "Capture a decision" | `/codex decision {summary}` |
-| "Update project context" | `/project update` |
-
-### Example Dialogue
-
-**User:** "Hey droid, remind me the tools you have"
-
-```
-[● ●] Here's what you have installed:
-
-**Context loading:**
-- `/project {name}` - Load your project's working context
-- `/codex search {topic}` - Find shared knowledge (PRDs, tech designs, patterns)
-
-**Planning & thinking:**
-- `/brain plan {topic}` - Create a planning scratchpad
-- `/tech-design {feature}` - Design larger features
-
-**Collaboration:**
-- `/comments check` - Respond to @droid mentions
-- `/code-review` - Get AI code review with specialized agents
-
-**Learning:**
-- `/coach` - AI as guide, not implementer
-
-**Pro tip:** Start threads with `/project` or `/codex search` for best results.
-```
-
-**User:** "How should I approach this new feature?"
-
-```
-[● ●] Here's my suggested workflow:
-
-1. **Load context first**
-   `/project {your-project}` - So I know the codebase
-   `/codex search {related-topic}` - For any relevant patterns
-
-2. **Plan before coding**
-   `/brain plan {feature}` - Sketch out the approach
-   Iterate with @droid/@{you} comments until it feels right
-
-3. **Implement with context**
-   Now I have full context - ask me to implement
-
-4. **Review before shipping**
-   `/code-review` - Catch issues before PR
-
-5. **Capture learnings**
-   `/project update` - Save decisions for next session
-```
+**Recommended session start:**
+1. `/project search {name}` - Load working context
+2. `/codex search {topic}` - Find relevant org knowledge (if needed)
+3. Then start working with full context

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-project",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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.1
+version: 0.3.2
 status: beta
 
 includes: