@orderful/droid 0.35.4 → 0.37.0

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/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/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.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/src/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}]"
 ---