@orderful/droid 0.10.1 → 0.10.3

package/src/skills/brain/references/naming.md

@@ -10,10 +10,10 @@ Conventions for naming brain docs.
 
 ## Components
 
-| Component | Description | Examples |
-|-----------|-------------|----------|
-| `{type}` | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note` |
-| `{topic-slug}` | Lowercase, hyphen-separated topic | `auth-refactor`, `caching-strategies` |
+| Component      | Description                          | Examples                              |
+| -------------- | ------------------------------------ | ------------------------------------- |
+| `{type}`       | Doc type: `plan`, `research`, `note` | `plan`, `research`, `note`            |
+| `{topic-slug}` | Lowercase, hyphen-separated topic    | `auth-refactor`, `caching-strategies` |
 
 ## Slug Rules
 
@@ -25,16 +25,17 @@ Conventions for naming brain docs.
 
 ## Examples
 
-| Input | Filename |
-|-------|----------|
-| `/brain plan Auth Refactor` | `plan-auth-refactor.md` |
-| `/brain research Caching Strategies` | `research-caching-strategies.md` |
-| `/brain plan Transaction Template Rendering` | `plan-transaction-template-rendering.md` |
-| `/brain note Remember to check rate limits` | `note-20250115-remember-to-check-rate.md` |
+| Input                                        | Filename                                  |
+| -------------------------------------------- | ----------------------------------------- |
+| `/brain plan Auth Refactor`                  | `plan-auth-refactor.md`                   |
+| `/brain research Caching Strategies`         | `research-caching-strategies.md`          |
+| `/brain plan Transaction Template Rendering` | `plan-transaction-template-rendering.md`  |
+| `/brain note Remember to check rate limits`  | `note-20250115-remember-to-check-rate.md` |
 
 ## Notes
 
 For notes, include the date in the filename:
+
 ```
 note-{YYYYMMDD}-{slug}.md
 ```
@@ -44,5 +45,6 @@ This prevents collisions and allows chronological sorting.
 ## Uniqueness
 
 If a file with the generated name already exists:
+
 1. Check if user wants to open existing doc
 2. Or append a numeric suffix: `plan-auth-refactor-2.md`

package/src/skills/brain/references/templates.md

@@ -94,9 +94,9 @@ Overall assessment.
 
 ## Template Variables
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `{Topic}` | Doc title from user input | "Auth Refactor" |
-| `{date}` | Current date (YYYY-MM-DD) | "2025-01-15" |
+| Variable              | Description               | Example                                 |
+| --------------------- | ------------------------- | --------------------------------------- |
+| `{Topic}`             | Doc title from user input | "Auth Refactor"                         |
+| `{date}`              | Current date (YYYY-MM-DD) | "2025-01-15"                            |
 | `{brief description}` | Context from conversation | "refactoring the authentication system" |
-| `{content}` | User-provided text | (for notes) |
+| `{content}`           | User-provided text        | (for notes)                             |

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

@@ -8,14 +8,18 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Search for matches**
+
    ```
    Glob: {brain_dir}/**/*{topic}*.md
    ```
+
    Fuzzy match the topic against doc filenames
 
 3. **Handle results:**
@@ -37,10 +41,12 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
-   - Use `inbox_folder` if configured
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - Also check for `inbox_folder` setting
+   - **Do NOT skip this step or assume defaults**
 
 2. **Generate filename** using naming conventions (see `naming.md`):
    - Format: `{type}-{topic-slug}.md`
@@ -59,11 +65,16 @@ Detailed procedures for each brain operation.
    - Any constraints or requirements mentioned?
    - Related work or prior decisions?
 
-7. **Write the doc** with template structure and initial context
+7. **Add placeholder comments** for sections needing user input:
+   - Read user's mention from `~/.droid/config.yaml` → `user_mention`
+   - Use `> @{user_mention}` for placeholders (e.g., `> @fry - Please provide requirements`)
+   - **CRITICAL:** NEVER use `@droid` - that's for user-to-AI comments, not AI-to-user
 
-8. **Set as active doc**
+8. **Write the doc** with template structure and initial context
 
-9. **Confirm creation** and summarize what was captured
+9. **Set as active doc**
+
+10. **Confirm creation** and summarize what was captured
 
 ## Notes
 
@@ -71,10 +82,12 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
-   - Use `inbox_folder` if configured
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - Also check for `inbox_folder` setting
+   - **Do NOT skip this step or assume defaults**
 
 2. **Generate filename:**
    - Format: `note-{date}-{slug}.md` where date is `YYYYMMDD`
@@ -105,8 +118,8 @@ Detailed procedures for each brain operation.
 2. **Read current content** of active doc
 
 3. **Append new section:**
-   ```markdown
 
+   ```markdown
    ---
 
    ## Update ({date})
@@ -133,18 +146,25 @@ Detailed procedures for each brain operation.
 
 2. **Read active doc**
 
-3. **Find all `> @droid` comments**
+3. **Check preserve_comments setting:**
+   - Read `~/.droid/skills/comments/overrides.yaml` if it exists
+   - Look for `preserve_comments` (default: `true`)
+
+4. **Find all `> @droid` comments**
    - Pattern: Lines starting with `> @droid` (blockquote with mention)
 
-4. **For each comment:**
+5. **For each comment:**
    - Show the comment and surrounding context
    - Address the question/request
-   - Add response as `> @{user_mention}` reply
-   - Or resolve inline if it was a simple note
+   - Add response as blockquote with user's mention: `> @{user_mention} Your response here`
+   - Example: `> @fry Yes, the index covers that query pattern.`
+   - **CRITICAL:** NEVER use `@droid` in your responses. Use `@{user_mention}` from config (e.g., `@fry`)
+   - **CRITICAL:** Always include the `>` prefix 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.
 
-5. **Update the doc** with responses
+6. **Update the doc** with responses
 
-6. **Summarize** what was addressed
+7. **Summarize** what was addressed
 
 ## Finalizing
 
@@ -177,14 +197,18 @@ Detailed procedures for each brain operation.
 
 **Steps:**
 
-1. **Read config first**
-   - Read `~/.droid/skills/brain/overrides.yaml`
-   - Use `brain_dir` if configured, otherwise use default for current AI tool
+1. **Read config first (MANDATORY)**
+   - Use the Read tool on `~/.droid/skills/brain/overrides.yaml`
+   - If file exists and contains `brain_dir:`, use that path
+   - Only use defaults if the file doesn't exist or `brain_dir` is not set
+   - **Do NOT skip this step or assume defaults**
 
 2. **Find recent docs:**
+
    ```
    Glob: {brain_dir}/**/*.md
    ```
+
    Sort by modification time, limit to 10-15
 
 3. **Present list** with:

package/src/skills/comments/SKILL.md

@@ -31,21 +31,23 @@ The AI will respond with `> @{user_mention}` (configured in droid setup, e.g., `
 **CRITICAL: The `@mention` is who you're talking TO, not who is speaking.**
 
 Think of it like addressing someone in conversation:
+
 - "Hey @droid, what do you think?" → User talking TO the AI
 - "Good point @fry, here's my take..." → AI talking TO the user
 
 | When you see... | Who wrote it | Who it's addressed to |
-|-----------------|--------------|----------------------|
-| `> @droid ...`  | User         | AI (droid)           |
-| `> @fry ...`    | AI           | User (fry)           |
+| --------------- | ------------ | --------------------- |
+| `> @droid ...`  | User         | AI (droid)            |
+| `> @fry ...`    | AI           | User (fry)            |
 
 **Examples:**
+
 ```markdown
-> @droid Can you explain this function?     ← User asking AI
+> @droid Can you explain this function? ← User asking AI
 > @fry This function calculates the hash... ← AI responding to user
 
-> @droid Should we refactor this?           ← User asking AI
-> @fry Yes, I'd suggest extracting...       ← AI responding to user
+> @droid Should we refactor this? ← User asking AI
+> @fry Yes, I'd suggest extracting... ← AI responding to user
 ```
 
 **Never flip this.** When responding to a `@droid` comment, always use `@{user}` (e.g., `@fry`) because you're addressing the user, not yourself.
@@ -76,13 +78,19 @@ When you find a `@droid` marker:
 ## Behavior
 
 ### On `/comments check`:
-1. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
-2. If there's a `git diff`, check those files first for relevant context
-3. For each comment, determine intent:
-   - **Action request** ("do X", "add Y", "fix Z") → Execute the action, remove the comment
-   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`, keep original comment
+
+1. **Read config first:** Check `~/.droid/skills/comments/overrides.yaml` for `preserve_comments` setting (default: `true`)
+2. Search for `> @droid` (and any configured `ai_mentions`) in the specified scope
+3. If there's a `git diff`, check those files first for relevant context
+4. For each comment, determine intent:
+   - **Action request** ("do X", "add Y", "fix Z") → Execute the action
+   - **Question** ("what do you think", "should we") → Respond with `> @{user_mention}`
+5. **Handle original comment based on `preserve_comments`:**
+   - If `preserve_comments: true` → Keep the original `@droid` comment (add response below it)
+   - If `preserve_comments: false` → Remove the original comment after addressing
 
 ### On `/comments cleanup`:
+
 1. Find AI tag and `> @{user_mention}` pairs where conversation appears resolved
 2. Remove both markers
 3. Output a summary of what was discussed/decided
@@ -98,8 +106,8 @@ user_mention: "@fry"
 # Additional AI mentions to recognize (e.g., if you're used to @claude)
 ai_mentions: "@claude"
 
-# Keep comments after addressing them (default: false)
-preserve_comments: false
+# Keep comments after addressing them (default: true)
+preserve_comments: true
 ```
 
 ## File Type Support

package/src/skills/comments/SKILL.yaml

@@ -15,7 +15,7 @@ config_schema:
   preserve_comments:
     type: boolean
     description: Keep original comments after addressing (vs removing them)
-    default: false
+    default: true
 examples:
   - title: "Action request"
     code: |