@orderful/droid 0.35.3 → 0.36.0

package/.claude-plugin/marketplace.json

@@ -60,8 +60,8 @@
     },
     {
       "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.2.2",
+      "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
+      "version": "0.3.0",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -87,7 +87,7 @@
     {
       "name": "droid-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.1",
+      "version": "0.1.2",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @orderful/droid
 
+## 0.36.0
+
+### Minor Changes
+
+- [#225](https://github.com/Orderful/droid/pull/225) [`d6e3fea`](https://github.com/Orderful/droid/commit/d6e3fea047a45d66d46301c7fba253aa0ab3680e) Thanks [@frytyler](https://github.com/frytyler)! - **codex tool: self-describing integration**
+
+  The codex skill now reads structure and workflows from the codex repo's .codex/ folder instead of hardcoded assumptions. This makes the skill stable and rarely needing updates when the codex structure evolves.
+
+  **Changes:**
+  - Skill reads .codex/manifest.yaml for structure definitions
+  - Skill reads .codex/workflows/\*.md for operation instructions
+  - Removed duplicated workflow content from references/
+  - Added references/reading-workflows.md guide
+  - Simplified SKILL.md from 421 to 214 lines (49% reduction)
+  - Kept references/review/ with type-specific facilitation (tech-design, prd)
+  - Added PRD review support
+  - Codex structural changes no longer require droid updates
+
+  **Breaking:** Requires codex repo with .codex/ folder (PR #181)
+
+## 0.35.4
+
+### Patch Changes
+
+- [#220](https://github.com/Orderful/droid/pull/220) [`cbe48f7`](https://github.com/Orderful/droid/commit/cbe48f71f177465886f65f27b914edf990612203) Thanks [@frytyler](https://github.com/frytyler)! - Add argument-hint to plan skill for better CLI discoverability
+
+- [#218](https://github.com/Orderful/droid/pull/218) [`47ba4ac`](https://github.com/Orderful/droid/commit/47ba4acf690595ed5c0f20645b5b5c20dcc9610a) Thanks [@frytyler](https://github.com/frytyler)! - Improve tech-design skill documentation and add needs-review label support
+  - Add comment convention table clarifying @droid/@user mention semantics
+  - Add --labels parameter to git-finish-write script for PR label support
+  - Configure tech-design publish to add needs-review label (prevents auto-merge)
+  - Remove unimplemented v2 commands from main Commands table
+
 ## 0.35.3
 
 ### Patch Changes

package/README.md

@@ -12,23 +12,60 @@ AI workflow toolkit for sharing tools, commands, and agents across the engineeri
 - **Share what works** - Power users discover great workflows, everyone benefits
 - **Consistent experience** - Common patterns like `@droid`/`@user` comments work the same across the team
 
-## Quick Start
+## Prerequisites
 
-### Option A: Claude Code Plugin (Recommended for Claude Code users)
+Before installing droid:
 
-Install individual tools directly through Claude Code's plugin system:
+| Requirement | Why | Install |
+|-------------|-----|---------|
+| **npm login to @orderful** | Droid is published to our private npm org | `npm login` (use Orderful credentials) |
+| **bun** | Required for `droid exec` scripts | [bun.sh](https://bun.sh) |
+| **gh** (GitHub CLI) | Highly recommended for PR workflows | [cli.github.com](https://cli.github.com) |
+| **Obsidian** | Recommended for brain/codex markdown editing | [obsidian.md](https://obsidian.md) |
+
+## Setup Gotchas
+
+Things that trip people up:
+
+### Claude Code not found after install
+
+If `claude` command isn't found in new terminal windows, add to your shell rc file (`.bashrc`, `.zshrc`):
 
 ```bash
-# Add the Droid marketplace
-/plugin marketplace add orderful/droid
+export PATH="$HOME/.local/bin:$PATH"
+```
 
-# Install the tools you want
-/plugin install droid-brain@droid
-/plugin install droid-comments@droid
-/plugin install droid-code-review@droid
+Then restart your terminal or `source` the file.
+
+### Check your settings before diving in
+
+After install, review your configuration before starting a session:
+
+```bash
+droid config                    # View global settings
+droid                           # TUI → Settings tab for tool-specific config
 ```
 
-### Option B: TUI Dashboard (For OpenCode or if you prefer a visual interface)
+Make sure username, paths, and tool settings match what you want.
+
+### Updates require restart
+
+When droid auto-updates (or you run `droid update`), the package updates but you need to:
+
+1. Restart droid to pick up the new version
+2. Run tool updates separately if needed (`droid update` in TUI)
+
+### Cursor support
+
+Cursor integration currently requires the **nightly build** of Cursor.
+
+### nodenv/nvm/asdf users
+
+After global npm install, run `nodenv rehash` (or equivalent for your version manager) to update shims.
+
+## Quick Start
+
+### Option A: TUI Dashboard (Recommended)
 
 ```bash
 npm install -g @orderful/droid
@@ -37,7 +74,21 @@ droid
 
 The TUI guides you through setup and tool installation. Works with both Claude Code and OpenCode.
 
-> **Note for nodenv/nvm/asdf users:** After global install, run `nodenv rehash` (or equivalent) to update your shims.
+### Option B: Claude Code Plugin (Alpha)
+
+> **Note:** Plugin support is experimental. The TUI is more stable and feature-complete.
+
+Install individual tools directly through Claude Code's plugin system:
+
+```bash
+# Add the Droid marketplace
+/plugin marketplace add orderful/droid
+
+# Install the tools you want
+/plugin install droid-brain@droid
+/plugin install droid-comments@droid
+/plugin install droid-code-review@droid
+```
 
 ## The TUI
 
@@ -62,6 +113,7 @@ Browse available tools, see what's installed, and manage everything from one pla
 | **comments** | Inline `@droid`/`@user` conversations in any file | beta |
 | **project** | Persistent project context across sessions | beta |
 | **brain** | Collaborative scratch pad for planning & research | beta |
+| **plan** | Task-scoped planning with portable, structured plans | alpha |
 | **coach** | Learning-mode AI - scaffolds don't implement, questions don't fix | beta |
 | **codex** | Shared organizational knowledge - PRDs, tech designs, patterns | beta |
 | **code-review** | Multi-agent code review with specialized checkers | alpha |
@@ -136,15 +188,25 @@ Config lives in `~/.droid/`:
 
 ```
 ~/.droid/
-├── config.yaml                    # Global config
-└── skills/
-    └── {skill}/
-        └── overrides.yaml         # Per-skill overrides
+└── config.yaml                    # Global config (platform, user settings, tool config)
 ```
 
-Tools install to your AI platform's location:
-- **Claude Code**: `~/.claude/skills/`, `~/.claude/commands/`, `~/.claude/agents/`
-- **OpenCode**: `~/.config/opencode/skills/`, `~/.config/opencode/commands/`
+Key sections in `config.yaml`:
+- `platform` - Primary platform (claude-code, opencode, cursor)
+- `user_mention` - Your @mention for comments (e.g., `@fry`)
+- `tools` - Per-tool configuration (brain paths, codex repo, etc.)
+- `auto_update` - Auto-update settings for app and tools
+- `repos` - Known repositories for context
+
+**Where tools install:**
+
+Skills are unified across all platforms to `~/.claude/skills/`. Commands and agents are platform-specific:
+
+| Platform | Skills | Commands | Agents |
+|----------|--------|----------|--------|
+| Claude Code | `~/.claude/skills/` | `~/.claude/commands/` | `~/.claude/agents/` |
+| OpenCode | `~/.claude/skills/` | `~/.config/opencode/command/` | `~/.config/opencode/agent/` |
+| Cursor | `~/.claude/skills/` | `~/.cursor/commands/` | `~/.cursor/agents/` |
 
 ## CLI Reference
 

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

@@ -1,7 +1,7 @@
 {
   "name": "droid-codex",
-  "version": "0.2.2",
-  "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.3.0",
+  "description": "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries.",
   "author": {
     "name": "Orderful",
     "url": "https://github.com/orderful"

package/dist/tools/codex/TOOL.yaml

@@ -1,6 +1,6 @@
 name: 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.2.2
+description: "Shared organizational knowledge - PRDs, tech designs, domains, proposals, patterns, and explored topics. Self-describing: structure and workflows defined in codex repo. Use when loading project context, searching codex, capturing decisions, or creating new entries."
+version: 0.3.0
 status: beta
 
 includes:

package/dist/tools/codex/commands/codex.md

@@ -1,6 +1,6 @@
 ---
 name: codex
-description: "Shared organizational knowledge - PRDs, tech designs, patterns, domains, proposals, and explored topics"
+description: "Shared organizational knowledge - PRDs, tech designs, patterns, domains, proposals, and explored topics. Self-describing: structure and workflows defined in codex repo."
 argument-hint: "[projects | search {query} | {category} search {query} | new {category} {name} | decision {text}]"
 ---