@orderful/droid 0.35.4 → 0.37.0

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.7",
+      "version": "0.3.9",
       "source": {
         "source": "github",
         "repo": "orderful/droid",
@@ -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",
@@ -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.4",
+      "version": "0.3.5",
       "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.2",
+      "version": "0.1.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.4",
+      "version": "0.2.5",
       "source": {
         "source": "github",
         "repo": "orderful/droid",

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @orderful/droid
 
+## 0.37.0
+
+### Minor Changes
+
+- [#227](https://github.com/Orderful/droid/pull/227) [`22f0e2c`](https://github.com/Orderful/droid/commit/22f0e2caad64564bedcacce5c77509d28402d9f0) Thanks [@frytyler](https://github.com/frytyler)! - Add `/brain cleanup` and `/plan cleanup` commands to resolve discussion threads
+  - Identifies resolved @droid/@{user_mention} threads
+  - Applies any agreed changes if not already done
+  - Logs decisions to Decision Log (one-liners) and Discussion Log (full threads)
+  - Natural language triggers: "clean up", "lock in decisions", "resolve threads"
+
+### Patch Changes
+
+- [#227](https://github.com/Orderful/droid/pull/227) [`22f0e2c`](https://github.com/Orderful/droid/commit/22f0e2caad64564bedcacce5c77509d28402d9f0) Thanks [@frytyler](https://github.com/frytyler)! - Clarify comment target conventions across all skills - AI responses should use `@{user_mention}` (e.g., `@fry`), never `@droid`
+
+  Updated skills: brain, plan, comments, tech-design
+
+## 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

package/README.md

@@ -59,9 +59,24 @@ When droid auto-updates (or you run `droid update`), the package updates but you
 
 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: Claude Code Plugin (Recommended for Claude Code users)
+### Option A: TUI Dashboard (Recommended)
+
+```bash
+npm install -g @orderful/droid
+droid
+```
+
+The TUI guides you through setup and tool installation. Works with both Claude Code and OpenCode.
+
+### 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:
 
@@ -75,17 +90,6 @@ Install individual tools directly through Claude Code's plugin system:
 /plugin install droid-code-review@droid
 ```
 
-### Option B: TUI Dashboard (For OpenCode or if you prefer a visual interface)
-
-```bash
-npm install -g @orderful/droid
-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.
-
 ## The TUI
 
 Run `droid` to launch the interactive dashboard:
@@ -109,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 |
@@ -183,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/brain/.claude-plugin/plugin.json

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

package/dist/tools/brain/commands/brain.md

@@ -1,7 +1,7 @@
 ---
 name: brain
 description: "Collaborative scratchpad for planning and research"
-argument-hint: "[search {topic} | {category} {topic} | add {text} | check | done]"
+argument-hint: "[search {topic} | {category} {topic} | add {text} | check | cleanup | done]"
 ---
 
 # /brain
@@ -28,8 +28,9 @@ argument-hint: "[search {topic} | {category} {topic} | add {text} | check | done
 /brain {category} {topic}       # Create doc → {category}s/{topic}.md
 /brain add {text}               # Append to active doc
 /brain check                    # Address @droid comments
+/brain cleanup                  # Resolve threads, log decisions
 ```
 
-**Reserved keywords:** `search`, `add`, `check`, `done` - everything else is a category.
+**Reserved keywords:** `search`, `add`, `check`, `cleanup`, `done` - everything else is a category.
 
 See the **brain skill** for complete documentation.

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

@@ -1,7 +1,7 @@
 ---
 name: brain
 description: "Collaborative scratchpad for planning and research. Use when planning a feature, exploring a problem, or capturing thinking that should persist across sessions. User prompts like 'let's think through', 'open a scratchpad', 'plan this out', 'use our brain'."
-argument-hint: "[search {topic} | {category} {topic} | add {text} | check | done]"
+argument-hint: "[search {topic} | {category} {topic} | add {text} | check | cleanup | done]"
 allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
@@ -46,7 +46,7 @@ brain_dir: "{user's choice}"
 
 ## Commands
 
-**Reserved keywords:** `search`, `add`, `check`, `done`
+**Reserved keywords:** `search`, `add`, `check`, `cleanup`, `done`
 
 | Command                                      | Action                                                 |
 | -------------------------------------------- | ------------------------------------------------------ |
@@ -56,6 +56,7 @@ brain_dir: "{user's choice}"
 | `/brain {category} {topic}`                  | Create doc → `{category}s/{topic}.md`                  |
 | `/brain add {text}`                          | Append to active doc                                   |
 | `/brain check`                               | Address @droid comments in active doc                  |
+| `/brain cleanup`                             | Resolve threads, apply changes, log decisions          |
 | `/brain done`                                | Finalize active doc, update status                     |
 
 **Category is any non-reserved word.** Common categories:
@@ -117,6 +118,21 @@ Find `> @droid` comments in active doc and address each. Preserve original comme
 
 Full procedure: `references/workflows.md` § Checking
 
+## Cleaning Up Resolved Threads
+
+**Trigger:** `/brain cleanup` or user says "let's clean up", "resolve these threads", "lock in decisions"
+
+Find resolved discussion threads (where a decision was reached or question answered), apply any agreed changes, and log to the bottom of the file.
+
+1. Scan for `@droid` / `@{user_mention}` comment threads
+2. Identify threads where a decision was made, idea was locked in, or question was resolved
+3. Apply any agreed changes to the doc if not already done
+4. Move resolved threads to logs at the bottom:
+   - **Decision Log** — What was decided (one-liner per decision)
+   - **Discussion Log** — Full thread history for reference
+
+Full procedure: `references/workflows.md` § Cleanup
+
 ## Finalizing
 
 **Trigger:** `/brain done`
@@ -129,12 +145,24 @@ Full procedure: `references/workflows.md` § Finalizing
 
 In markdown files, use blockquote `>` prefix for @mention comments. The @mention is the **target**, not the author:
 
-| Comment        | Author | Target | Meaning                    |
-| -------------- | ------ | ------ | -------------------------- |
-| `> @droid ...` | User   | AI     | User asking/telling the AI |
-| `> @user ...`  | AI     | User   | AI asking/telling the user |
+| Comment                  | Author | Target | Meaning                    |
+| ------------------------ | ------ | ------ | -------------------------- |
+| `> @droid ...`           | User   | AI     | User asking/telling the AI |
+| `> @{user_mention} ...`  | AI     | User   | AI asking/telling the user |
+
+Get `user_mention` from `droid config --get user_mention`.
+
+**CRITICAL:** When the AI writes comments to address the user, ALWAYS use `@{user_mention}`. NEVER use `@droid` — that's reserved for user-to-AI comments only.
+
+If droid's `comments` skill is installed, use `/comments check` for full support.
+
+## Natural Language Triggers
 
-Get `user_mention` from `droid config --get user_mention`. If droid's `comments` skill is installed, use `/comments check` for full support.
+Recognise cleanup intent and offer `/brain cleanup`:
+- "Let's clean up these threads"
+- "Can we resolve these discussions?"
+- "Lock in these decisions"
+- "Archive the resolved stuff"
 
 ## Extensions
 

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

@@ -133,3 +133,64 @@ Overall assessment.
 | `{date}`              | Current date (YYYY-MM-DD) | "2025-01-15"                            |
 | `{brief description}` | Context from conversation | "refactoring the authentication system" |
 | `{content}`           | User-provided text        | (for notes)                             |
+
+---
+
+## Log Templates
+
+These logs are appended to the bottom of brain docs by `/brain cleanup`. They preserve the history of how decisions were made without cluttering the main content.
+
+### Decision Log
+
+A table of one-liner decisions for quick reference:
+
+```markdown
+---
+
+## Decision Log
+
+| Date       | Decision                                              |
+| ---------- | ----------------------------------------------------- |
+| 2026-01-28 | Use Redis for rate limiting (distributed counters)    |
+| 2026-01-27 | Prefer composition over inheritance for handlers      |
+| 2026-01-25 | Ship MVP without webhooks, add in v2                  |
+```
+
+### Discussion Log
+
+Full conversation threads preserved for context. Useful when you need to remember *why* something was decided:
+
+```markdown
+## Discussion Log
+
+### Storage choice (2026-01-28)
+
+> @droid Should we use Redis or Postgres for rate limit state?
+
+> @{user_mention} Redis is better here - rate limiting needs fast atomic increments across distributed instances. Postgres would add latency and connection overhead.
+
+> @droid Makes sense. What about persistence if Redis restarts?
+
+> @{user_mention} We'll use Redis persistence (RDB snapshots) but also design the system to handle cold starts gracefully - worst case, limits reset.
+
+**Resolved:** Use Redis with RDB persistence, design for graceful cold starts.
+
+---
+
+### API versioning (2026-01-27)
+
+> @droid How should we handle API versioning?
+
+> @{user_mention} URL path versioning (`/v1/`, `/v2/`) is clearest for consumers. Header-based is cleaner but causes confusion.
+
+**Resolved:** Use URL path versioning.
+```
+
+### When to Use Each Log
+
+| Scenario | Where it goes |
+| -------- | ------------- |
+| Quick decision, obvious rationale | Decision Log only |
+| Decision with nuanced reasoning | Both logs |
+| Long exploration that didn't lead to decision | Discussion Log only (mark as "Explored, no decision") |
+| Thread that's just Q&A, no decision | Discussion Log only (mark as "Answered") |

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

@@ -152,10 +152,12 @@ Detailed procedures for each brain operation.
 
 **Directionality:** The @mention is the **target**, not the author:
 
-| Comment        | Author | Target | Meaning                    |
-| -------------- | ------ | ------ | -------------------------- |
-| `> @droid ...` | User   | AI     | User asking/telling the AI |
-| `> @user ...`  | AI     | User   | AI asking/telling the user |
+| Comment                  | Author | Target | Meaning                    |
+| ------------------------ | ------ | ------ | -------------------------- |
+| `> @droid ...`           | User   | AI     | User asking/telling the AI |
+| `> @{user_mention} ...`  | AI     | User   | AI asking/telling the user |
+
+**CRITICAL:** When the AI writes comments to address the user, ALWAYS use `@{user_mention}`. NEVER use `@droid` — that's reserved for user-to-AI comments only.
 
 **Steps:**
 
@@ -197,6 +199,69 @@ Detailed procedures for each brain operation.
 
 7. **Summarize** what was addressed
 
+## Cleanup
+
+**Trigger:** `/brain cleanup` or natural language ("clean up these threads", "lock in decisions")
+
+**Purpose:** Graduate resolved discussion threads into permanent logs. Unlike `/brain check` (which addresses open comments), cleanup finds threads where decisions were already made and archives them properly.
+
+**Steps:**
+
+1. **Check for active doc**
+   - If no active doc: Ask which doc to clean up
+
+2. **Read active doc** and find all comment threads
+
+3. **Identify resolved threads:**
+   - Look for `@droid` → `@{user_mention}` exchanges
+   - Check for resolution signals:
+     - Explicit: "sounds good", "let's do that", "agreed", "locked in", "resolved"
+     - Implicit: No follow-up questions, thread went quiet after answer
+   - Present uncertain threads to user: "Is this resolved?"
+
+4. **For each resolved thread:**
+
+   a. **Check if changes were applied:**
+      - Did the agreed change get made to the doc?
+      - If not, apply it now (with user confirmation)
+
+   b. **Extract the decision:**
+      - One-liner summary of what was decided
+      - Example: "Use Redis for rate limiting (better for distributed counters)"
+
+   c. **Archive the thread:**
+      - Remove from current location in doc
+      - Add to Discussion Log at bottom (full thread preserved)
+      - Add to Decision Log at bottom (one-liner)
+
+5. **Update logs at bottom of doc:**
+
+   ```markdown
+   ---
+
+   ## Decision Log
+
+   | Date | Decision |
+   | ---- | -------- |
+   | {date} | {one-liner decision} |
+
+   ## Discussion Log
+
+   ### {topic} ({date})
+
+   > @droid {original question}
+
+   > @{user_mention} {response}
+
+   **Resolved:** {summary}
+   ```
+
+6. **Summarize** what was cleaned up:
+   - "Cleaned up 3 threads, logged 2 decisions"
+   - List the decisions briefly
+
+See `references/templates.md` § Log Templates for format details.
+
 ## Finalizing
 
 **Trigger:** `/brain done`

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}]"
 ---