@orderful/droid 0.35.3 → 0.35.4

package/.claude-plugin/marketplace.json

@@ -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,17 @@
 # @orderful/droid
 
+## 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,6 +12,53 @@ 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
 
+## Prerequisites
+
+Before installing droid:
+
+| 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
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+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
+```
+
+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.
+
 ## Quick Start
 
 ### Option A: Claude Code Plugin (Recommended for Claude Code users)

package/dist/tools/codex/skills/codex/scripts/git-finish-write.d.ts

@@ -16,6 +16,7 @@
  *   --message <text>    Commit message (required)
  *   --pr-title <text>   PR title (required)
  *   --pr-body <text>    PR body (optional, defaults to commit message)
+ *   --labels <text>     Comma-separated labels (optional)
  *
  * What it does:
  *   1. Stage all changes

package/dist/tools/codex/skills/codex/scripts/git-finish-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-finish-write.d.ts","sourceRoot":"","sources":["../../../../../../src/tools/codex/skills/codex/scripts/git-finish-write.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}
+{"version":3,"file":"git-finish-write.d.ts","sourceRoot":"","sources":["../../../../../../src/tools/codex/skills/codex/scripts/git-finish-write.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/tools/codex/skills/codex/scripts/git-finish-write.ts

@@ -16,6 +16,7 @@
  *   --message <text>    Commit message (required)
  *   --pr-title <text>   PR title (required)
  *   --pr-body <text>    PR body (optional, defaults to commit message)
+ *   --labels <text>     Comma-separated labels (optional)
  *
  * What it does:
  *   1. Stage all changes
@@ -47,11 +48,13 @@ function parseArgs(args: string[]): {
   message: string | null;
   prTitle: string | null;
   prBody: string | null;
+  labels: string | null;
 } {
   let config: Config | null = null;
   let message: string | null = null;
   let prTitle: string | null = null;
   let prBody: string | null = null;
+  let labels: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -69,10 +72,12 @@ function parseArgs(args: string[]): {
       prTitle = args[++i];
     } else if (arg === '--pr-body' && args[i + 1]) {
       prBody = args[++i];
+    } else if (arg === '--labels' && args[i + 1]) {
+      labels = args[++i];
     }
   }
 
-  return { config, message, prTitle, prBody };
+  return { config, message, prTitle, prBody, labels };
 }
 
 function expandPath(p: string): string {
@@ -100,7 +105,8 @@ function gitFinishWrite(
   repoPath: string,
   commitMessage: string,
   prTitle: string,
-  prBody: string
+  prBody: string,
+  labels?: string
 ): Result {
   const cwd = expandPath(repoPath);
 
@@ -173,6 +179,14 @@ function gitFinishWrite(
     }
   }
 
+  // 4.5. Add labels if specified
+  if (labels) {
+    const addLabels = run(`gh pr edit --add-label "${labels}"`, cwd);
+    if (!addLabels.ok) {
+      console.error(`Warning: Failed to add labels: ${addLabels.output}`);
+    }
+  }
+
   // 5. Return to main
   const checkoutMain = run('git checkout main', cwd);
   if (!checkoutMain.ok) {
@@ -189,7 +203,7 @@ function gitFinishWrite(
 
 // Main
 const args = process.argv.slice(2);
-const { config, message, prTitle, prBody } = parseArgs(args);
+const { config, message, prTitle, prBody, labels } = parseArgs(args);
 
 if (!config) {
   console.log(JSON.stringify({
@@ -227,7 +241,8 @@ const result = gitFinishWrite(
   config.codex_repo,
   message,
   prTitle,
-  prBody || message
+  prBody || message,
+  labels || undefined
 );
 console.log(JSON.stringify(result, null, 2));
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-plan",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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/dist/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.1
+version: 0.1.2
 status: alpha
 
 includes:

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

@@ -1,6 +1,7 @@
 ---
 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'."
+argument-hint: "[new {topic} | search {topic} | check | ready | implement]"
 allowed-tools: [Read, Edit, Write, Glob, Grep, Bash, Task, AskUserQuestion]
 ---
 

package/dist/tools/tech-design/skills/tech-design/SKILL.md

@@ -68,6 +68,13 @@ Tech-design has no configuration of its own. It delegates to:
    - Iterates with `@droid`/`@user` comments (the @mention is the **target**: `@droid` = user asking AI, `@user` = AI asking user)
    - Captures the "why" behind choices
 
+**Comment conventions for async back-and-forth:**
+
+| Comment        | Author | Target | Meaning                    |
+| -------------- | ------ | ------ | -------------------------- |
+| `> @droid ...` | User   | AI     | User asking/telling the AI |
+| `> @user ...`  | AI     | User   | AI asking/telling the user |
+
 3. **Roll-up** = Reviewer artifact
    - Synthesized from thought doc
    - Decision-focused, no exploration noise
@@ -79,16 +86,13 @@ Both thought doc and roll-up are published to codex. Research doc stays in brain
 
 ## Commands
 
-| Command                                     | Action                                                   | Status |
-| ------------------------------------------- | -------------------------------------------------------- | ------ |
-| `/tech-design start --from codex:{project}` | Create research + thought docs, pull PRD/DESIGN context  | v1     |
-| `/tech-design draft [section]`              | Auto-generate from research doc + codebase exploration   | v1     |
-| `/tech-design think [topic]`                | Guided exploration, updates research doc with findings   | v1     |
-| `/tech-design gaps`                         | Checklist of missing/empty sections                      | v1     |
-| `/tech-design publish`                      | Generate roll-up, publish thought doc + roll-up to codex | v1     |
-| `/tech-design critic [persona]`             | Multi-persona review with severity scoring               | v2     |
-| `/tech-design respond {question}`           | Author tool: search thought doc to draft reply           | v2     |
-| `/tech-design ask {question}`               | Reviewer tool: search both docs to answer questions      | v2     |
+| Command                                     | Action                                                   |
+| ------------------------------------------- | -------------------------------------------------------- |
+| `/tech-design start --from codex:{project}` | Create research + thought docs, pull PRD/DESIGN context  |
+| `/tech-design draft [section]`              | Auto-generate from research doc + codebase exploration   |
+| `/tech-design think [topic]`                | Guided exploration, updates research doc with findings   |
+| `/tech-design gaps`                         | Checklist of missing/empty sections                      |
+| `/tech-design publish`                      | Generate roll-up, publish thought doc + roll-up to codex |
 
 ## Conversational Skill Matching
 

package/dist/tools/tech-design/skills/tech-design/references/publish.md

@@ -231,12 +231,13 @@ After approval:
 - [ ] Add key decisions to DECISIONS.md
 - [ ] Begin implementation"
 
-# Use codex skill's git-finish-write script
+# Use codex skill's git-finish-write script with needs-review label
 droid config --get tools.codex | droid exec droid-codex git-finish-write \
   --config - \
   --message "$commit_msg" \
   --pr-title "$pr_title" \
-  --pr-body "$pr_body"
+  --pr-body "$pr_body" \
+  --labels "needs-review"
 ```
 
 ### 8. Output Success

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orderful/droid",
-  "version": "0.35.3",
+  "version": "0.35.4",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

package/src/tools/codex/skills/codex/scripts/git-finish-write.ts

@@ -16,6 +16,7 @@
  *   --message <text>    Commit message (required)
  *   --pr-title <text>   PR title (required)
  *   --pr-body <text>    PR body (optional, defaults to commit message)
+ *   --labels <text>     Comma-separated labels (optional)
  *
  * What it does:
  *   1. Stage all changes
@@ -47,11 +48,13 @@ function parseArgs(args: string[]): {
   message: string | null;
   prTitle: string | null;
   prBody: string | null;
+  labels: string | null;
 } {
   let config: Config | null = null;
   let message: string | null = null;
   let prTitle: string | null = null;
   let prBody: string | null = null;
+  let labels: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -69,10 +72,12 @@ function parseArgs(args: string[]): {
       prTitle = args[++i];
     } else if (arg === '--pr-body' && args[i + 1]) {
       prBody = args[++i];
+    } else if (arg === '--labels' && args[i + 1]) {
+      labels = args[++i];
     }
   }
 
-  return { config, message, prTitle, prBody };
+  return { config, message, prTitle, prBody, labels };
 }
 
 function expandPath(p: string): string {
@@ -100,7 +105,8 @@ function gitFinishWrite(
   repoPath: string,
   commitMessage: string,
   prTitle: string,
-  prBody: string
+  prBody: string,
+  labels?: string
 ): Result {
   const cwd = expandPath(repoPath);
 
@@ -173,6 +179,14 @@ function gitFinishWrite(
     }
   }
 
+  // 4.5. Add labels if specified
+  if (labels) {
+    const addLabels = run(`gh pr edit --add-label "${labels}"`, cwd);
+    if (!addLabels.ok) {
+      console.error(`Warning: Failed to add labels: ${addLabels.output}`);
+    }
+  }
+
   // 5. Return to main
   const checkoutMain = run('git checkout main', cwd);
   if (!checkoutMain.ok) {
@@ -189,7 +203,7 @@ function gitFinishWrite(
 
 // Main
 const args = process.argv.slice(2);
-const { config, message, prTitle, prBody } = parseArgs(args);
+const { config, message, prTitle, prBody, labels } = parseArgs(args);
 
 if (!config) {
   console.log(JSON.stringify({
@@ -227,7 +241,8 @@ const result = gitFinishWrite(
   config.codex_repo,
   message,
   prTitle,
-  prBody || message
+  prBody || message,
+  labels || undefined
 );
 console.log(JSON.stringify(result, null, 2));
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-plan",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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.1
+version: 0.1.2
 status: alpha
 
 includes:

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

@@ -1,6 +1,7 @@
 ---
 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'."
+argument-hint: "[new {topic} | search {topic} | check | ready | implement]"
 allowed-tools: [Read, Edit, Write, Glob, Grep, Bash, Task, AskUserQuestion]
 ---
 

package/src/tools/tech-design/skills/tech-design/SKILL.md

@@ -68,6 +68,13 @@ Tech-design has no configuration of its own. It delegates to:
    - Iterates with `@droid`/`@user` comments (the @mention is the **target**: `@droid` = user asking AI, `@user` = AI asking user)
    - Captures the "why" behind choices
 
+**Comment conventions for async back-and-forth:**
+
+| Comment        | Author | Target | Meaning                    |
+| -------------- | ------ | ------ | -------------------------- |
+| `> @droid ...` | User   | AI     | User asking/telling the AI |
+| `> @user ...`  | AI     | User   | AI asking/telling the user |
+
 3. **Roll-up** = Reviewer artifact
    - Synthesized from thought doc
    - Decision-focused, no exploration noise
@@ -79,16 +86,13 @@ Both thought doc and roll-up are published to codex. Research doc stays in brain
 
 ## Commands
 
-| Command                                     | Action                                                   | Status |
-| ------------------------------------------- | -------------------------------------------------------- | ------ |
-| `/tech-design start --from codex:{project}` | Create research + thought docs, pull PRD/DESIGN context  | v1     |
-| `/tech-design draft [section]`              | Auto-generate from research doc + codebase exploration   | v1     |
-| `/tech-design think [topic]`                | Guided exploration, updates research doc with findings   | v1     |
-| `/tech-design gaps`                         | Checklist of missing/empty sections                      | v1     |
-| `/tech-design publish`                      | Generate roll-up, publish thought doc + roll-up to codex | v1     |
-| `/tech-design critic [persona]`             | Multi-persona review with severity scoring               | v2     |
-| `/tech-design respond {question}`           | Author tool: search thought doc to draft reply           | v2     |
-| `/tech-design ask {question}`               | Reviewer tool: search both docs to answer questions      | v2     |
+| Command                                     | Action                                                   |
+| ------------------------------------------- | -------------------------------------------------------- |
+| `/tech-design start --from codex:{project}` | Create research + thought docs, pull PRD/DESIGN context  |
+| `/tech-design draft [section]`              | Auto-generate from research doc + codebase exploration   |
+| `/tech-design think [topic]`                | Guided exploration, updates research doc with findings   |
+| `/tech-design gaps`                         | Checklist of missing/empty sections                      |
+| `/tech-design publish`                      | Generate roll-up, publish thought doc + roll-up to codex |
 
 ## Conversational Skill Matching
 

package/src/tools/tech-design/skills/tech-design/references/publish.md

@@ -231,12 +231,13 @@ After approval:
 - [ ] Add key decisions to DECISIONS.md
 - [ ] Begin implementation"
 
-# Use codex skill's git-finish-write script
+# Use codex skill's git-finish-write script with needs-review label
 droid config --get tools.codex | droid exec droid-codex git-finish-write \
   --config - \
   --message "$commit_msg" \
   --pr-title "$pr_title" \
-  --pr-body "$pr_body"
+  --pr-body "$pr_body" \
+  --labels "needs-review"
 ```
 
 ### 8. Output Success