@orderful/droid 0.36.0 → 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",
@@ -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,21 @@
 # @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

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

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

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

@@ -31,10 +31,12 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 
 The directionality can be confusing. 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.
 
 Think of it like addressing someone in conversation:
 

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

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

package/dist/tools/plan/commands/plan.md

@@ -1,7 +1,7 @@
 ---
 name: plan
 description: "Task-scoped planning with portable, structured plans"
-argument-hint: "new|search|check|ready|implement [topic]"
+argument-hint: "new|search|check|cleanup|ready|implement [topic]"
 ---
 
 # /plan
@@ -17,6 +17,7 @@ argument-hint: "new|search|check|ready|implement [topic]"
 | `/plan new {topic}` | Create new plan, offer context loading |
 | `/plan search {topic}` | Find and load existing plan |
 | `/plan check` | Address @droid comments |
+| `/plan cleanup` | Resolve threads, log decisions |
 | `/plan ready` | Finalize and validate |
 | `/plan implement` | Execute the plan |
 
@@ -26,6 +27,7 @@ argument-hint: "new|search|check|ready|implement [topic]"
 /plan new auth-refactor      # Start planning auth refactor
 /plan search rate-limit      # Find existing rate limit plan
 /plan check                  # Address open comments
+/plan cleanup                # Resolve threads, log decisions
 /plan ready                  # Mark plan as ready
 /plan implement              # Execute the plan
 ```

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

@@ -1,7 +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]"
+argument-hint: "[new {topic} | search {topic} | check | cleanup | ready | implement]"
 allowed-tools: [Read, Edit, Write, Glob, Grep, Bash, Task, AskUserQuestion]
 ---
 
@@ -34,7 +34,8 @@ Uses config from dependencies:
 | ---------------------- | --------------------------------------------------- |
 | `/plan new {topic}`    | Create plan doc, offer context loading              |
 | `/plan search {topic}` | Find and load existing plan                         |
-| `/plan check`          | Address `@droid` comments, graduate to decisions    |
+| `/plan check`          | Address `@droid` comments, respond to questions     |
+| `/plan cleanup`        | Resolve threads, apply changes, log decisions       |
 | `/plan ready`          | Finalize: validate and update status                |
 | `/plan implement`      | Execute tasks, optionally convert to XML            |
 
@@ -63,10 +64,19 @@ Uses config from dependencies:
 
 1. Find `> @droid` comments in active plan
 2. Address each, respond with `> @{user_mention}`
-3. Ask if resolved → graduate to Locked-In Decisions table
-4. Update the doc
+3. Update the doc
 
-See `references/workflows.md` for graduation pattern.
+## `/plan cleanup`
+
+**Trigger:** `/plan cleanup` or user says "clean up", "lock in decisions", "resolve these threads"
+
+1. Scan for resolved `@droid` / `@{user_mention}` threads
+2. Identify threads where decisions were made or questions answered
+3. Apply any agreed changes if not already done
+4. Graduate to Locked-In Decisions table
+5. Archive full thread to Discussion Log at bottom
+
+See `references/workflows.md` § Cleanup for the full graduation pattern.
 
 ## `/plan ready`
 
@@ -88,10 +98,12 @@ See `references/workflows.md` for graduation pattern.
 
 ## Comment Conventions
 
-| Comment          | Written by | Addressed to |
-| ---------------- | ---------- | ------------ |
-| `> @droid ...`   | User       | AI           |
-| `> @{user} ...`  | AI         | User         |
+| Comment                  | Written by | Addressed to |
+| ------------------------ | ---------- | ------------ |
+| `> @droid ...`           | User       | AI           |
+| `> @{user_mention} ...`  | AI         | 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.
 
 ## Natural Language Triggers
 

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

@@ -144,31 +144,66 @@ For each comment:
 
 1. **Read context** - surrounding lines, section it's in
 2. **Respond** - add response below with `> @{user_mention}`
-3. **Ask resolution** - "Is this resolved?"
 
-### Step 4: Graduation Pattern
+### Step 4: Update Doc
+
+Write changes back to plan file.
+
+---
+
+## `/plan cleanup`
+
+### Step 1: Load Active Plan
+
+If no active plan, prompt to search for one.
+
+### Step 2: Find All Comment Threads
+
+Search for `@droid` / `@{user_mention}` exchanges.
+
+### Step 3: Identify Resolved Threads
+
+Look for resolution signals:
+- Explicit: "sounds good", "let's do that", "agreed", "locked in"
+- Implicit: No follow-up questions after response
+
+For uncertain threads, ask: "Is this resolved?"
+
+### Step 4: Apply Pending Changes
+
+For each resolved thread:
+- Check if the agreed change was applied to the plan
+- If not, apply it now (with user confirmation)
+
+### Step 5: Graduation Pattern
 
 When a discussion is resolved:
 
-1. Mark as resolved in Discussion Log:
+1. **Extract decision** for Locked-In Decisions table:
    ```markdown
-   ### Resolved: {topic} ({date})
-   > @droid - {original question}
-   > @{user} - {response}
-   > **Resolved:** {one-line summary}
+   | {decision} | {choice} | {rationale from discussion} |
    ```
 
-2. Add to Locked-In Decisions table:
+2. **Archive to Discussion Log** at bottom:
    ```markdown
-   | {decision} | {choice} | {rationale from discussion} |
+   ### {topic} ({date})
+   > @droid {original question}
+   > @{user_mention} {response}
+   **Resolved:** {one-line summary}
    ```
 
-3. Move from "Open:" to "Resolved:" header
+3. **Remove thread** from its original location in the doc
 
-### Step 5: Update Doc
+### Step 6: Update Doc
 
 Write changes back to plan file.
 
+### Step 7: Summarize
+
+Report what was cleaned up:
+- "Cleaned up 3 threads, logged 2 decisions"
+- List the decisions briefly
+
 ---
 
 ## `/plan ready`
@@ -277,23 +312,25 @@ Add completion note:
 
 ## Discussion Graduation Flow
 
-The pattern for moving discussions to decisions:
+The pattern for moving discussions to decisions (via `/plan cleanup`):
 
 ```
 1. User leaves comment:
-   > @droid - Should we use Redis or Postgres?
+   > @droid Should we use Redis or Postgres?
 
-2. AI responds:
-   > @{user} - Redis for this use case because {reasons}
+2. AI responds (via /plan check):
+   > @{user_mention} Redis for this use case because {reasons}
 
-3. User confirms resolution (via /plan check):
-   > **Resolved:** Use Redis for rate limit state
+3. User runs /plan cleanup, confirms thread is resolved
 
-4. Entry added to Locked-In Decisions:
+4. Entry added to Locked-In Decisions table:
    | Storage | Redis | Better for distributed counters |
 
-5. Discussion header changes:
-   ### Resolved: Storage choice (2026-01-18)
+5. Thread archived to Discussion Log at bottom:
+   ### Storage choice (2026-01-28)
+   > @droid Should we use Redis or Postgres?
+   > @{user_mention} Redis for this use case because {reasons}
+   **Resolved:** Use Redis for rate limit state
 ```
 
 This creates an audit trail while keeping decisions accessible in the table.

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-tech-design",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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.4
+version: 0.2.5
 status: beta
 
 includes:

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

@@ -70,10 +70,12 @@ Tech-design has no configuration of its own. It delegates to:
 
 **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 |
+| 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, ALWAYS use `@{user_mention}`. NEVER use `@droid` — that's for user-to-AI only.
 
 3. **Roll-up** = Reviewer artifact
    - Synthesized from thought doc

package/package.json

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

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

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

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

@@ -31,10 +31,12 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 
 The directionality can be confusing. 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.
 
 Think of it like addressing someone in conversation:
 

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

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

package/src/tools/plan/commands/plan.md

@@ -1,7 +1,7 @@
 ---
 name: plan
 description: "Task-scoped planning with portable, structured plans"
-argument-hint: "new|search|check|ready|implement [topic]"
+argument-hint: "new|search|check|cleanup|ready|implement [topic]"
 ---
 
 # /plan
@@ -17,6 +17,7 @@ argument-hint: "new|search|check|ready|implement [topic]"
 | `/plan new {topic}` | Create new plan, offer context loading |
 | `/plan search {topic}` | Find and load existing plan |
 | `/plan check` | Address @droid comments |
+| `/plan cleanup` | Resolve threads, log decisions |
 | `/plan ready` | Finalize and validate |
 | `/plan implement` | Execute the plan |
 
@@ -26,6 +27,7 @@ argument-hint: "new|search|check|ready|implement [topic]"
 /plan new auth-refactor      # Start planning auth refactor
 /plan search rate-limit      # Find existing rate limit plan
 /plan check                  # Address open comments
+/plan cleanup                # Resolve threads, log decisions
 /plan ready                  # Mark plan as ready
 /plan implement              # Execute the plan
 ```

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

@@ -1,7 +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]"
+argument-hint: "[new {topic} | search {topic} | check | cleanup | ready | implement]"
 allowed-tools: [Read, Edit, Write, Glob, Grep, Bash, Task, AskUserQuestion]
 ---
 
@@ -34,7 +34,8 @@ Uses config from dependencies:
 | ---------------------- | --------------------------------------------------- |
 | `/plan new {topic}`    | Create plan doc, offer context loading              |
 | `/plan search {topic}` | Find and load existing plan                         |
-| `/plan check`          | Address `@droid` comments, graduate to decisions    |
+| `/plan check`          | Address `@droid` comments, respond to questions     |
+| `/plan cleanup`        | Resolve threads, apply changes, log decisions       |
 | `/plan ready`          | Finalize: validate and update status                |
 | `/plan implement`      | Execute tasks, optionally convert to XML            |
 
@@ -63,10 +64,19 @@ Uses config from dependencies:
 
 1. Find `> @droid` comments in active plan
 2. Address each, respond with `> @{user_mention}`
-3. Ask if resolved → graduate to Locked-In Decisions table
-4. Update the doc
+3. Update the doc
 
-See `references/workflows.md` for graduation pattern.
+## `/plan cleanup`
+
+**Trigger:** `/plan cleanup` or user says "clean up", "lock in decisions", "resolve these threads"
+
+1. Scan for resolved `@droid` / `@{user_mention}` threads
+2. Identify threads where decisions were made or questions answered
+3. Apply any agreed changes if not already done
+4. Graduate to Locked-In Decisions table
+5. Archive full thread to Discussion Log at bottom
+
+See `references/workflows.md` § Cleanup for the full graduation pattern.
 
 ## `/plan ready`
 
@@ -88,10 +98,12 @@ See `references/workflows.md` for graduation pattern.
 
 ## Comment Conventions
 
-| Comment          | Written by | Addressed to |
-| ---------------- | ---------- | ------------ |
-| `> @droid ...`   | User       | AI           |
-| `> @{user} ...`  | AI         | User         |
+| Comment                  | Written by | Addressed to |
+| ------------------------ | ---------- | ------------ |
+| `> @droid ...`           | User       | AI           |
+| `> @{user_mention} ...`  | AI         | 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.
 
 ## Natural Language Triggers
 

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

@@ -144,31 +144,66 @@ For each comment:
 
 1. **Read context** - surrounding lines, section it's in
 2. **Respond** - add response below with `> @{user_mention}`
-3. **Ask resolution** - "Is this resolved?"
 
-### Step 4: Graduation Pattern
+### Step 4: Update Doc
+
+Write changes back to plan file.
+
+---
+
+## `/plan cleanup`
+
+### Step 1: Load Active Plan
+
+If no active plan, prompt to search for one.
+
+### Step 2: Find All Comment Threads
+
+Search for `@droid` / `@{user_mention}` exchanges.
+
+### Step 3: Identify Resolved Threads
+
+Look for resolution signals:
+- Explicit: "sounds good", "let's do that", "agreed", "locked in"
+- Implicit: No follow-up questions after response
+
+For uncertain threads, ask: "Is this resolved?"
+
+### Step 4: Apply Pending Changes
+
+For each resolved thread:
+- Check if the agreed change was applied to the plan
+- If not, apply it now (with user confirmation)
+
+### Step 5: Graduation Pattern
 
 When a discussion is resolved:
 
-1. Mark as resolved in Discussion Log:
+1. **Extract decision** for Locked-In Decisions table:
    ```markdown
-   ### Resolved: {topic} ({date})
-   > @droid - {original question}
-   > @{user} - {response}
-   > **Resolved:** {one-line summary}
+   | {decision} | {choice} | {rationale from discussion} |
    ```
 
-2. Add to Locked-In Decisions table:
+2. **Archive to Discussion Log** at bottom:
    ```markdown
-   | {decision} | {choice} | {rationale from discussion} |
+   ### {topic} ({date})
+   > @droid {original question}
+   > @{user_mention} {response}
+   **Resolved:** {one-line summary}
    ```
 
-3. Move from "Open:" to "Resolved:" header
+3. **Remove thread** from its original location in the doc
 
-### Step 5: Update Doc
+### Step 6: Update Doc
 
 Write changes back to plan file.
 
+### Step 7: Summarize
+
+Report what was cleaned up:
+- "Cleaned up 3 threads, logged 2 decisions"
+- List the decisions briefly
+
 ---
 
 ## `/plan ready`
@@ -277,23 +312,25 @@ Add completion note:
 
 ## Discussion Graduation Flow
 
-The pattern for moving discussions to decisions:
+The pattern for moving discussions to decisions (via `/plan cleanup`):
 
 ```
 1. User leaves comment:
-   > @droid - Should we use Redis or Postgres?
+   > @droid Should we use Redis or Postgres?
 
-2. AI responds:
-   > @{user} - Redis for this use case because {reasons}
+2. AI responds (via /plan check):
+   > @{user_mention} Redis for this use case because {reasons}
 
-3. User confirms resolution (via /plan check):
-   > **Resolved:** Use Redis for rate limit state
+3. User runs /plan cleanup, confirms thread is resolved
 
-4. Entry added to Locked-In Decisions:
+4. Entry added to Locked-In Decisions table:
    | Storage | Redis | Better for distributed counters |
 
-5. Discussion header changes:
-   ### Resolved: Storage choice (2026-01-18)
+5. Thread archived to Discussion Log at bottom:
+   ### Storage choice (2026-01-28)
+   > @droid Should we use Redis or Postgres?
+   > @{user_mention} Redis for this use case because {reasons}
+   **Resolved:** Use Redis for rate limit state
 ```
 
 This creates an audit trail while keeping decisions accessible in the table.

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

@@ -1,6 +1,6 @@
 {
   "name": "droid-tech-design",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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.4
+version: 0.2.5
 status: beta
 
 includes:

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

@@ -70,10 +70,12 @@ Tech-design has no configuration of its own. It delegates to:
 
 **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 |
+| 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, ALWAYS use `@{user_mention}`. NEVER use `@droid` — that's for user-to-AI only.
 
 3. **Roll-up** = Reviewer artifact
    - Synthesized from thought doc