@orderful/droid 0.35.2 → 0.35.4

package/.claude-plugin/marketplace.json

@@ -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.6",
+      "version": "0.3.7",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -35,7 +35,7 @@
     {
       "name": "droid-coach",
       "description": "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.",
-      "version": "0.2.3",
+      "version": "0.2.4",
       "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.2.1",
+      "version": "0.2.2",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -74,7 +74,7 @@
     {
       "name": "droid-comments",
       "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
-      "version": "0.3.3",
+      "version": "0.3.4",
       "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",
@@ -100,7 +100,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.3",
+      "version": "0.3.4",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -113,7 +113,7 @@
     {
       "name": "droid-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.3",
+      "version": "0.2.4",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @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
+
+- [#215](https://github.com/Orderful/droid/pull/215) [`5241570`](https://github.com/Orderful/droid/commit/5241570ab1b14bb819c5635834706ad67f0525a2) Thanks [@frytyler](https://github.com/frytyler)! - Fix brain comment responses blockquoting section content
+
+  When responding to `> @droid` comments in brain docs, Claude was wrapping all subsequent section content in blockquotes. Now only the `> @fry` response line is blockquoted, with substantive content (sections, analysis) in regular markdown for better readability.
+
+- [#217](https://github.com/Orderful/droid/pull/217) [`6484016`](https://github.com/Orderful/droid/commit/648401686c3e6c5f59ccb08d55947beb3170d352) Thanks [@frytyler](https://github.com/frytyler)! - fix(skills): add Bash to allowed-tools for skills using droid config commands
+
+  Multiple skills require running `droid config --get` commands but didn't have Bash in their allowed-tools list. This caused them to fail when trying to read configuration.
+
+  Fixed skills:
+  - coach (0.2.4): Added Bash to allowed-tools
+  - codex (0.2.2): Added Bash(droid:\*) to allowed-tools
+  - comments (0.3.4): Added Bash to allowed-tools
+  - tech-design (0.2.4): Added Bash(droid:\*) to allowed-tools
+  - project (0.3.4): Added Bash to allowed-tools
+
 ## 0.35.2
 
 ### 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/brain/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-brain",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "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.6
+version: 0.3.7
 status: beta
 
 includes:

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

@@ -177,8 +177,21 @@ Detailed procedures for each brain operation.
    - Add response as blockquote with user's mention (from `droid config --get tools.brain`): `> @{user_mention} Your response here`
    - Example: `> @{user} Yes, the index covers that query pattern.`
    - **CRITICAL:** NEVER use `@droid` in your responses. Use `@{user_mention}` from config (e.g., `@{user}`)
-   - **CRITICAL:** Always include the `>` prefix to maintain blockquote formatting
+   - **CRITICAL:** Always include the `>` prefix for the @mention response line to maintain blockquote formatting
    - **CRITICAL:** If `preserve_comments: true`, keep the original `@droid` comment and add your response below it. Do NOT remove the original comment.
+   - **CRITICAL:** When adding substantive content (sections, analysis, etc.) AFTER your `> @{user_mention}` response, use regular markdown formatting (NOT blockquoted). Only the @mention line should be blockquoted.
+
+   **Format example:**
+   ```markdown
+   > @droid Show me the architecture section
+
+   > @{user_mention} Here's the architecture section.
+
+   ## Architecture
+
+   The system uses a three-tier architecture...
+   (regular markdown, NOT blockquoted)
+   ```
 
 6. **Update the doc** with responses
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-coach",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "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.",
   "author": {
     "name": "Orderful",

package/dist/tools/coach/TOOL.yaml

@@ -1,6 +1,6 @@
 name: coach
 description: "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."
-version: 0.2.3
+version: 0.2.4
 status: beta
 
 includes:

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

@@ -2,7 +2,7 @@
 name: coach
 description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix. Use when learning a new codebase, wanting to understand deeply, or building skills to retain. User prompts like 'coach me on', 'help me think through', 'I want to learn how to', 'don't just give me the answer'."
 argument-hint: "[plan {task} | scaffold [{path}] | review [{path}] | check | challenge [{path}]]"
-allowed-tools: [Read, Grep, Glob]
+allowed-tools: [Read, Grep, Glob, Bash]
 ---
 
 # Coach Skill

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-codex",
-  "version": "0.2.1",
+  "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.",
   "author": {
     "name": "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.1
+version: 0.2.2
 status: beta
 
 includes:

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

@@ -13,6 +13,7 @@ allowed-tools:
     Bash(git:*),
     Bash(ls:*),
     Bash(mkdir:*),
+    Bash(droid:*),
   ]
 ---
 

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/comments/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-comments",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
   "author": {
     "name": "Orderful",

package/dist/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.3.3
+version: 0.3.4
 status: beta
 
 includes:

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

@@ -2,7 +2,7 @@
 name: comments
 description: "Inline conversations using @droid/@user markers in any file. Use when leaving async questions in code or having discussion that should stay near the code. User prompts like 'check for comments', 'address the @droid markers', 'clean up resolved comments'."
 argument-hint: "[check [{path}] | cleanup]"
-allowed-tools: [Read, Grep, Glob, Edit]
+allowed-tools: [Read, Grep, Glob, Edit, Bash]
 ---
 
 # Comments Skill

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/project/.claude-plugin/plugin.json

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

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

@@ -2,7 +2,7 @@
 name: project
 description: "Persistent project context for AI memory across sessions. Use when working on multi-session features, refactors, or any work that benefits from accumulated context. User prompts like 'load the project', 'update project context', 'what's the current project?'."
 argument-hint: "[{keywords} | update | create {name}]"
-allowed-tools: [Read, Write, Glob, Grep]
+allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
 # Project Skill

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-tech-design",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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",

package/dist/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.3
+version: 0.2.4
 status: beta
 
 includes:

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

@@ -3,7 +3,7 @@ name: tech-design
 description: "Technical design authoring with three-document approach - research doc (codebase discoveries), thought doc (design iteration), and roll-up (clean summary). Use when writing tech designs, drafting sections, exploring architectural ideas, or publishing to codex. User prompts like 'start tech design for X', 'draft the rollout section', 'let's think through the API design', 'publish this to codex'."
 argument-hint: "[start --from codex:{project} | draft [section] | think [topic] | gaps | publish]"
 allowed-tools:
-  [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Task]
+  [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Bash(droid:*), Task]
 ---
 
 # Tech Design Skill
@@ -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.2",
+  "version": "0.35.4",
   "description": "AI workflow toolkit for sharing skills, commands, and agents across the team",
   "type": "module",
   "bin": {

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

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

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

@@ -177,8 +177,21 @@ Detailed procedures for each brain operation.
    - Add response as blockquote with user's mention (from `droid config --get tools.brain`): `> @{user_mention} Your response here`
    - Example: `> @{user} Yes, the index covers that query pattern.`
    - **CRITICAL:** NEVER use `@droid` in your responses. Use `@{user_mention}` from config (e.g., `@{user}`)
-   - **CRITICAL:** Always include the `>` prefix to maintain blockquote formatting
+   - **CRITICAL:** Always include the `>` prefix for the @mention response line to maintain blockquote formatting
    - **CRITICAL:** If `preserve_comments: true`, keep the original `@droid` comment and add your response below it. Do NOT remove the original comment.
+   - **CRITICAL:** When adding substantive content (sections, analysis, etc.) AFTER your `> @{user_mention}` response, use regular markdown formatting (NOT blockquoted). Only the @mention line should be blockquoted.
+
+   **Format example:**
+   ```markdown
+   > @droid Show me the architecture section
+
+   > @{user_mention} Here's the architecture section.
+
+   ## Architecture
+
+   The system uses a three-tier architecture...
+   (regular markdown, NOT blockquoted)
+   ```
 
 6. **Update the doc** with responses
 

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-coach",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "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.",
   "author": {
     "name": "Orderful",

package/src/tools/coach/TOOL.yaml

@@ -1,6 +1,6 @@
 name: coach
 description: "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."
-version: 0.2.3
+version: 0.2.4
 status: beta
 
 includes:

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

@@ -2,7 +2,7 @@
 name: coach
 description: "Learning-mode AI assistance - scaffolds don't implement, questions don't fix. Use when learning a new codebase, wanting to understand deeply, or building skills to retain. User prompts like 'coach me on', 'help me think through', 'I want to learn how to', 'don't just give me the answer'."
 argument-hint: "[plan {task} | scaffold [{path}] | review [{path}] | check | challenge [{path}]]"
-allowed-tools: [Read, Grep, Glob]
+allowed-tools: [Read, Grep, Glob, Bash]
 ---
 
 # Coach Skill

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-codex",
-  "version": "0.2.1",
+  "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.",
   "author": {
     "name": "Orderful",

package/src/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.1
+version: 0.2.2
 status: beta
 
 includes:

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

@@ -13,6 +13,7 @@ allowed-tools:
     Bash(git:*),
     Bash(ls:*),
     Bash(mkdir:*),
+    Bash(droid:*),
   ]
 ---
 

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/comments/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "droid-comments",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration.",
   "author": {
     "name": "Orderful",

package/src/tools/comments/TOOL.yaml

@@ -1,6 +1,6 @@
 name: comments
 description: "Enable inline conversations using @droid/@user markers. Tag @droid to ask the AI, AI responds with @{your-name}. Use /comments check to address markers, /comments cleanup to remove resolved threads. Ideal for code review notes and async collaboration."
-version: 0.3.3
+version: 0.3.4
 status: beta
 
 includes:

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

@@ -2,7 +2,7 @@
 name: comments
 description: "Inline conversations using @droid/@user markers in any file. Use when leaving async questions in code or having discussion that should stay near the code. User prompts like 'check for comments', 'address the @droid markers', 'clean up resolved comments'."
 argument-hint: "[check [{path}] | cleanup]"
-allowed-tools: [Read, Grep, Glob, Edit]
+allowed-tools: [Read, Grep, Glob, Edit, Bash]
 ---
 
 # Comments Skill

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/project/.claude-plugin/plugin.json

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

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

@@ -2,7 +2,7 @@
 name: project
 description: "Persistent project context for AI memory across sessions. Use when working on multi-session features, refactors, or any work that benefits from accumulated context. User prompts like 'load the project', 'update project context', 'what's the current project?'."
 argument-hint: "[{keywords} | update | create {name}]"
-allowed-tools: [Read, Write, Glob, Grep]
+allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
 # Project Skill

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-tech-design",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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",

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.3
+version: 0.2.4
 status: beta
 
 includes:

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

@@ -3,7 +3,7 @@ name: tech-design
 description: "Technical design authoring with three-document approach - research doc (codebase discoveries), thought doc (design iteration), and roll-up (clean summary). Use when writing tech designs, drafting sections, exploring architectural ideas, or publishing to codex. User prompts like 'start tech design for X', 'draft the rollout section', 'let's think through the API design', 'publish this to codex'."
 argument-hint: "[start --from codex:{project} | draft [section] | think [topic] | gaps | publish]"
 allowed-tools:
-  [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Task]
+  [Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*), Bash(mkdir:*), Bash(droid:*), Task]
 ---
 
 # Tech Design Skill
@@ -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